JetMakeKey 函数

项目
06/13/2023

适用于： Windows |Windows Server

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
    );

parameters

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	游标没有当前索引。如果游标位于表的聚集索引上，尚未定义主索引，并且未指定JET_bitNormalizedKey，则 JetMakeKey 将发生这种情况。如果游标位于没有任何键列的索引上，除非提供了以前构造的搜索键，则无法构造搜索键。
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 专业版。
服务器	需要 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

JetMakeKey 函数