JetGetSecondaryIndexBookmark 函数

适用于： Windows |Windows Server

JetGetSecondaryIndexBookmark 函数

JetGetSecondaryIndexBookmark 函数检索光标当前位置的辅助索引条目的特殊书签。 然后，可以使用此书签通过 JetGotoSecondaryIndexBookmark 有效地将光标重新定位回同一索引项。 在包含重复键或包含同一记录的多个索引条目的辅助索引上重新定位时，这非常有用。

Windows XP：JetGetSecondaryIndexBookmark 在 Windows XP 中引入。

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

参数

sesid

用于此调用的会话。

tableid

要用于此调用的游标。

pvSecondaryKey

接收辅助密钥的输出缓冲区。

cbSecondaryKeyMax

辅助密钥的输出缓冲区的最大大小（以字节为单位）。

印刷品SecondaryKeyActual

接收辅助密钥的实际大小（以字节为单位）。

如果此参数为 NULL，则不会返回辅助密钥的实际大小。

如果输出缓冲区太小，仍将返回辅助密钥的实际大小。 这意味着此数字将大于输出缓冲区的大小。

pvPrimaryBookmark

接收主键书签的输出缓冲区。

cbPrimaryBookmarkMax

主键书签的输出缓冲区的最大大小（以字节为单位）。

印刷品PrimaryKeyActual

接收主键书签的实际大小（以字节为单位）。

如果此参数为 NULL，则不会返回主键书签的实际大小。

如果输出缓冲区太小，仍将返回主键书签的实际大小。 这意味着此数字将大于输出缓冲区的大小。

grbit

保留供将来使用。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBufferTooSmall	操作已成功完成，但其中一个输出缓冲区太小，无法接收请求的数据。 输出缓冲区中已填充了尽可能多的书签。 如果请求，还返回了书签的实际大小。
JET_errClientRequestToStopJetService	无法完成操作，因为与会话关联的实例上的所有活动都因调用 JetStopService 而停止。
JET_errInstanceUnavailable	无法完成操作，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 此错误仅由 Windows XP 及更高版本返回。
JET_errNoCurrentIndex	游标当前不在辅助索引上。 当游标当前未使用辅助索引时，检索辅助索引书签没有意义。 当光标不在辅助索引上时，应使用 JetGetBookmark。
JET_errNoCurrentRecord	光标未定位在记录上。 导致这种情况发生的原因有很多。 例如，如果光标当前位于当前索引上最后一条记录之后，则会发生此情况。
JET_errNotInitialized	无法完成操作，因为与会话关联的实例尚未初始化。
JET_errRestoreInProgress	无法完成该操作，因为正在对与会话关联的实例执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 此错误仅由 Windows XP 及更高版本返回。
JET_errTermInProgress	无法完成操作，因为正在关闭与会话关联的实例。

成功后，将在输出缓冲区中返回游标当前位置的索引项的辅助索引书签。 不会更改数据库状态。

如果失败，除非返回JET_errBufferTooSmall，否则输出缓冲区的状态和辅助索引书签的实际大小将不确定。 如果返回JET_errBufferTooSmall，则输出缓冲区将包含所提供空间中容纳的辅助索引书签，并且辅助索引书签的实际大小将准确。 在任何情况下，数据库状态都不会发生更改。

备注

书签通常应被视为不透明的数据块。 不应尝试利用此数据的内部结构。 但是，对于所有 ESENT 书签，以下属性是已知的：

• 书签唯一标识给定表中的记录。

• 记录的书签在该记录的生存期内不会更改。

• 记录的书签与包含该记录的表上主索引上该记录的键相同。 如果没有针对该表定义主索引，数据库引擎将为记录创建自己的书签。

• 书签可以使用 memcmp 在源记录表的主索引中建立其相对顺序，从而相互比较书签。 如果未对该表定义主索引，则表中书签的相对顺序没有意义。

• 将不同表中的记录书签相互比较是毫无意义的。

• 在 Windows Vista 之前，书签的长度始终小于或等于 JET_cbBookmarkMost (256) 字节。 在 Windows Vista 和更高版本中，书签可以更大。 书签的最大大小等于当前值 JET_paramKeyMost + 1。

键通常应被视为不透明的数据块。 不应尝试利用此数据的内部结构。 但是，对于所有 ESENT 键，可以知道以下属性：

• 可以使用 memcmp 在源索引条目表的起始索引中建立其相对顺序，从而相互比较键。

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

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

要求

要求	值
客户端	需要 Windows Vista 或 Windows XP。
服务器	需要 Windows Server 2008 或 Windows Server 2003。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp