JetMakeKey 函数

  • 项目

适用于：Windows |Windows服务器

JetMakeKey 函数

JetMakeKey 函数构造搜索键，这些键随后可用于通过键列值的一些简单搜索条件在索引中查找一组条目。 搜索键也是游标的内部属性之一， JetSeek 和 JetSetIndexRange 操作用于查找与该游标当前索引匹配的索引项。 完整的搜索键构建在一系列 JetMakeKey 调用中，其中每个调用用于加载游标当前索引的下一个键列的列值。 还可以加载以前构造的搜索键，该键已使用 JetRetrieveKey 从游标中检索。

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

参数

sesid

要用于此调用的会话。

tableid

用于此调用的游标。

pvData

包含要为其构造搜索键的游标的当前索引的当前键列的列数据的输入缓冲区。

输入缓冲区中列数据的数据类型必须与当前键列的列定义的数据类型和其他属性完全匹配。 不会对列数据执行任何类型强制。

如果在 grbit 参数中指定了JET_bitNormalizedKey，则输入缓冲区必须包含以前构造的搜索键。 此类密钥是使用对 JetRetrieveKey 的调用获取的。

cbData

输入缓冲区中提供的列数据的大小（以字节为单位）。

如果在 grbit 参数中指定了JET_bitNormalizedKey，则这是输入缓冲区中提供的搜索键的大小。

如果列数据的大小为零，则忽略输入缓冲区的内容。 如果在 grbit 参数中指定了JET_bitKeyDataZeroLength，并且游标的当前索引的当前键列是可变长度列，则输入列数据假定为零长度值。 否则，输入列数据假定为 NULL 值。

grbit

一组指定以下选项的零个或多个位。

值

含义

JET_bitFullColumnEndLimit

应以某种方式构造搜索键，使当前键列之后的任何键列被视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为此键列和所有以前的键列提供的确切列值。

  • 后续键列所需的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引末尾最近的索引项。 索引的末尾是移动到该索引中的最后一条记录时找到的索引项。 索引的末尾与索引的高端不同，该索引可能会根据索引中键列的排序顺序而更改。

此选项仅适用于 Windows XP 及更高版本。

JETbitFullColumnStartLimit

应构造搜索键，以便将当前键列之后的任何键列视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为此键列和所有以前的键列提供的确切列值。

  • 后续键列所需的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引开始最近的索引项。 索引的开头是移动到该索引中的第一条记录时找到的索引项。 索引的起始点与索引的低端不同，该索引可能会根据索引中键列的排序顺序而更改。

此选项仅适用于 Windows XP 及更高版本。

JET_bitKeyDataZeroLength

如果输入缓冲区的大小为零，并且当前键列是可变长度列，则此选项指示输入缓冲区包含零长度值。 否则，输入缓冲区大小为零将指示 NULL 值。

JET_bitNewKey

应构造新的搜索键。 任何以前存在的搜索键都将被丢弃。

JET_bitNormalizedKey

指定此选项后，将忽略所有其他选项、丢弃以前存在的任何搜索键，并将输入缓冲区的内容作为新的搜索键加载。

JET_bitPartialColumnEndLimit

应构造搜索键，以便将当前键列视为前缀通配符，并且当前键列之后的任何键列都应被视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为此键列和所有以前的键列提供的确切列值。

  • 后续键列所需的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引末尾最近的索引项。 索引的末尾是移动到该索引中的最后一条记录时找到的索引项。 索引的末尾与索引的高端不同，该索引可能会根据索引中键列的排序顺序而更改。

当当前键列不是文本列或变量二进制列时，不能使用此选项。 如果尝试此操作，则此操作将失败，JET_errInvalidgrbit。

此选项仅适用于 Windows XP 及更高版本。

JET_bitPartialColumnStartLimit

此选项指示应构造搜索键，以便将当前键列视为前缀通配符，并且当前键列之后的任何键列都应被视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为此键列和所有以前的键列提供的确切列值。

  • 后续键列所需的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引开始最近的索引项。 索引的开头是移动到该索引中的第一条记录时找到的索引项。 索引的起始点与索引的低端不同，该索引可能会根据索引中键列的排序顺序而更改。

当当前键列不是文本列或变量二进制列时，不能使用此选项。 如果尝试此操作，则此操作将失败，JET_errInvalidgrbit。

此选项仅适用于 Windows XP 及更高版本。

JET_bitStrLimit

此选项指示应构造搜索键，以便将当前键列之后的任何键列视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为此键列和所有以前的键列提供的确切列值。

  • 后续键列所需的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引末尾最近的索引项。 索引的末尾是移动到该索引中的最后一条记录时找到的索引项。 索引的末尾与索引的高端不同，该索引可能会根据索引中键列的排序顺序而更改。

当此选项与JET_bitSubStrLimit和当前键列是文本列结合使用时，将忽略此选项。 此行为旨在允许生成搜索键时推断当前键列的类型。

如果要为索引的开头生成类似的搜索键，则应针对不是通配符但未指定通配符选项的最后一个键列对 JetMakeKey 的类似调用。 然后，搜索键处于适当的状态，用于此类搜索。 这类似于使用JET_bitFullColumnStartLimit，但搜索键未干净完成，因为它在使用通配符选项后。

此选项已弃用Windows XP 及更高版本，以便解决此尴尬的语义。 应尽可能使用JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit。

JET_bitSubStrLimit

此选项指示应构造搜索键，以便将当前键列视为前缀通配符，并且当前键列之后的任何键列都应被视为通配符。 这意味着，构造的搜索键可用于匹配具有以下项的索引项：

  • 为所有以前的键列提供的确切列值。

  • 指定的列数据作为当前键列的列值的前缀。

  • 后续键列的任何列值。

生成通配符搜索键时，应使用此选项来查找离索引末尾最近的索引项。 索引的末尾是移动到该索引中的最后一条记录时找到的索引项。 索引的末尾与索引的高端不同，该索引可能会根据索引中键列的排序顺序而更改。

如果此选项与JET_bitStrLimit和当前键列是文本列一起指定，则此选项优先。 当当前键列不是文本列时，将忽略此选项。 此行为旨在允许在生成搜索键时推断当前键列的类型。

如果要为索引开头生成类似的搜索键，则应对作为前缀通配符的键列发出类似的对 JetMakeKey 的调用，但未指定任何通配符选项。 然后，搜索键处于适当的状态，用于此类搜索。 这类似于使用JET_bitPartialColumnStartLimit，只是搜索键在使用通配符选项后未完全完成。

对于 Windows XP 和更高版本，为了解决此尴尬的语义，此选项已弃用。 应尽可能使用JET_bitPartialColumnStartLimit和JET_bitPartialColumnEndLimit。

返回值

此函数使用以下返回代码之一返回 JET_ERR 数据类型。 有关可能的 ESE 错误的详细信息，请参阅可扩展存储引擎错误和错误处理参数。

返回代码

说明

JET_errSuccess

操作已成功完成。

JET_errClientRequestToStopJetService

无法完成该操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动已停止。

JET_errIndexTuplesKeyTooSmall

提供的列数据太小，无法为当前索引生成有效的键，因为该索引是元组索引，最小元组大小大于提供的列数据。 有关元组索引的详细信息，请参阅 JetCreateIndex 。 此错误仅由 Windows XP 和更高版本返回。

JET_errInstanceUnavailable

无法完成该操作，因为与会话关联的实例遇到了一个致命错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 此错误仅由 Windows XP 和更高版本返回。

JET_errInvalidBufferSize

提供的列数据与列定义所需的大小不匹配。 如果列的数据类型本质上是特定大小，则可能会出现这种情况。 如果列的数据类型本身不是特定大小，但列的定义将声明为固定长度，则也可能发生这种情况。 这一点的一个例外是，如果为固定长度文本列提供的数据太少，则不会发生此错误，因为任何缺失的数据将自动填充空格。 第二个例外是，如果为固定长度二进制列提供的数据太少，则不会发生此错误，因为任何缺失的数据将自动填充为零。

JET_errInvalidgrbit

请求的选项之一无效，以非法方式使用或未实现。 当以下情况时 ，JetMakeKey 可能会发生这种情况：

  • 指定JET_bitPartialColumnStartLimit或JET_bitPartialColumnEndLimit，相应的键列不是文本列，也不是可变长度二进制列。 这种情况仅在 Windows XP 及更高版本上发生。

  • 尝试将以下多个选项一起使用：JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit。 这种情况仅在 Windows XP 及更高版本上发生。

  • 当使用以下选项之一时，尝试使用JET_bitStrLimit或JET_bitSubStrLimit：JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit。 这种情况仅在 Windows XP 及更高版本上发生。

JET_errInvalidParameter

提供的参数之一包含意外值或包含与另一个参数的值组合时没有意义的值。

当指定了JET_bitNormalizedKey并且输入缓冲区中提供的值太大，无法成为有效的搜索键时， JetMakeKey 可能会发生这种情况。

JET_errKeyIsMade

已拒绝提供给 JetMakeKey 的列数据，因为已为当前索引中的所有键列提供列数据。 这可以通过三种方式发生。 第一种方法是为当前索引中的每个键列提供列数据。 第二种方法是，如果为至少一个键列提供了列数据，并且为最后一次调用选择了通配符选项。 第三种方法是，如果使用JET_bitNormalizedKey（涵盖所有键列）提供以前构造的搜索键。

JET_errKeyNotMade

游标没有当前搜索键。 如果未指定JET_bitNewKey，并且尚未为此游标构造搜索键，则会使用之前调用 JetMakeKey 来为 JetMakeKey 构造此键。 搜索键将通过对 除 JetMove 以外的游标上的任何导航 API 的调用删除。

JET_errNoCurrentIndex

游标没有当前索引。 如果游标位于表的聚集索引上，则 JetMakeKey 会发生这种情况，但尚未定义主索引，并且未指定JET_bitNormalizedKey。 如果游标位于索引上，除非提供以前构造的搜索键，否则无法构造搜索键。

JET_errNotInitialized

无法完成该操作，因为尚未初始化与会话关联的实例。

JET_errRestoreInProgress

无法完成操作，因为与会话关联的实例上正在进行还原操作。

JET_errSessionSharingViolation

同一会话不能同时用于多个线程。 此错误仅由 Windows XP 和更高版本返回。

JET_errTermInProgress

无法完成该操作，因为与会话关联的实例正在关闭。

成功后，如果未指定JET_bitNormalizedKey和JET_bitNewKey，则搜索键将由当前索引中多个键列的搜索条件构建。 如果未指定JET_bitNormalizedKey并且指定了JET_bitNewKey，则会丢弃任何以前存在的搜索键，并且新搜索键将由当前索引中第一个键列的搜索条件构建。 如果指定了JET_bitNormalizedKey，则会丢弃任何以前存在的搜索键，并从输入缓冲区加载新的搜索键。 在任何情况下，都不会更改数据库状态。

失败时，如果指定了JET_bitNormalizedKey或JET_bitNewKey，则未定义搜索键的状态。 如果未指定JET_bitNormalizedKey或JET_bitNewKey，则不会更改搜索键的状态。 在任何情况下，都不会更改数据库状态。

备注

密钥应被视为不透明的数据区块。 不应尝试利用此数据的内部结构。 但是，以下是所有 ESENT 密钥的已知信息：

  • 可以使用 memcmp 相互比较键，以便在源索引项的表中在原始索引中建立相对顺序。

  • 将索引项的键与不同的索引项相互比较是毫无意义的。

  • 在 Windows Vista 之前，密钥的长度始终小于或等于 JET_cbKeyMost (255) 字节。 在 Windows Vista 及更高版本上，密钥可能更大。 键的最大大小等于JET_paramKeyMost的当前值。

如果使用通配符选项，搜索键可能更长一个字节。 在这种情况下，对于 Windows Vista 之前的版本，搜索键最多JET_cbLimitKeyMost (256 个) 字节，对于 Windows Vista 及更高版本，JET_paramKeyMost + 1 个字节。

此最大密钥大小有一个非常重要的影响。 每当有一个索引项具有足够大的列值，以便为该索引生成键（否则大于此最大大小）时，该键会以该最大大小以无提示方式截断。 这会导致两种影响：

  • 对于唯一索引中的条目，它将导致将唯一声明为重复项的条目。

  • 对于所有索引中的条目，键截断将导致索引项与给定搜索键的搜索条件不匹配，以便声明为匹配项。

应用程序必须预测此截断，并避免它或补偿其效果。 在 Windows Vista 中，添加了新的索引标志JET_bitIndexDisallowTruncation，使应用程序更容易防止密钥截断。 有关此索引选项的详细信息，请参阅 JET_INDEXCREATE 结构。

要求

要求 值

客户端

需要 Windows Vista、Windows XP 或 Windows 2000 Professional。

Server

需要Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。

标头

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange