JetSetCurrentIndex2 函数

项目
06/13/2023

适用于： Windows |Windows Server

JetSetCurrentIndex2 函数

JetSetCurrentIndex2 函数设置游标的当前索引，该索引定义表中哪些记录对游标可见，以及这些记录的显示顺序，方法是选择用于公开这些记录的索引项集。

    JET_ERR JET_API JetSetCurrentIndex2(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in          JET_GRBIT grbit
    );

parameters

sesid

用于此调用的会话。

tableid

要用于此调用的游标。

szIndexName

要为游标选择的索引的名称。

如果此参数为 NULL 或空字符串，则将选择聚集索引。如果为表定义了主索引，则将选择该索引，因为它与聚集索引相同。如果未为表定义主索引，则将选择顺序索引。顺序索引没有索引定义。有关详细信息，请参阅 JetCreateIndex 。

如果 pindexid 不为 NULL，则将忽略索引名称，并按索引 ID 选择索引。

grbit

一组位，其中包含要用于此调用的选项，其中包括以下零个或多个内容。

值	含义
JET_bitMoveFirst	此选项指示光标应位于指定索引的第一个条目上。如果选择聚集索引 (主索引或顺序索引) ，并且当前索引是辅助索引，则假定JET_bitMoveFirst。如果选择当前索引，则忽略此选项，并且不会更改光标位置。
JET_bitNoMove	此选项指示游标应位于新索引的索引项上，该索引项对应于与索引项关联的记录，该记录位于游标在旧索引上的当前位置。如果新索引的定义至少包含一个多值键列，则目标索引项不明确。在本例中，指定的 itagSequence 用于选择用于定位游标的最有效多值键列的哪个多值。即使对于多个多值键列，也只需要传递单个 itagSequence ，因为引擎只会扩展最重要的多值键列的所有值。有关更多详细信息，请参阅 JetCreateIndex 。如果指定了JET_bitMoveFirst，则忽略此选项。如果选择当前索引，则忽略此选项，并且不会更改光标位置。如果此参数不存在，则假定其值JET_bitMoveFirst。

值

含义

JET_bitMoveFirst

此选项指示光标应位于指定索引的第一个条目上。如果选择聚集索引 (主索引或顺序索引) ，并且当前索引是辅助索引，则假定JET_bitMoveFirst。如果选择当前索引，则忽略此选项，并且不会更改光标位置。

JET_bitNoMove

此选项指示游标应位于新索引的索引项上，该索引项对应于与索引项关联的记录，该记录位于游标在旧索引上的当前位置。

如果新索引的定义至少包含一个多值键列，则目标索引项不明确。在本例中，指定的 itagSequence 用于选择用于定位游标的最有效多值键列的哪个多值。即使对于多个多值键列，也只需要传递单个 itagSequence ，因为引擎只会扩展最重要的多值键列的所有值。有关更多详细信息，请参阅 JetCreateIndex 。

如果指定了JET_bitMoveFirst，则忽略此选项。

如果选择当前索引，则忽略此选项，并且不会更改光标位置。如果此参数不存在，则假定其值JET_bitMoveFirst。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBadItagSequence	正在使用 JET_bitNoMove 选项选择辅助索引，并且新定义中对应于指定序列号的索引的第一个多值键列没有值。
JET_errClientRequestToStopJetService	无法完成操作，因为与会话关联的实例上的所有活动都因调用 JetStopService 而停止。
JET_errInstanceUnavailable	无法完成操作，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。此错误仅由 Windows XP 及更高版本返回。
JET_errInvalidIndexId	索引 ID 的内容无效或已过期，需要刷新。在以下情况下， JetSetCurrentIndex2 可能会发生这种情况： pindexid-cbStruct> 与 Windows Server 2003 及更高版本) (大小不符。自提取索引 ID 以来，引擎已关闭。引用包含对应于索引 ID 的索引的表的所有游标都已关闭，并且引擎已从架构缓存中逐出索引的定义。索引 ID 与在错误表上打开的游标一起使用。索引已删除或对会话尚不可见。
JET_errInvalidName	指定的对象名称之一无效。所有对象名称必须符合同一组规则。这些规则如下：对象名称必须由 ASCII 字符组成。对象名称的长度必须至少为一个字符。对象名称的长度不得超过 JET_cbNameMost (64) 个字符。对象名称不能以空格开头。对象名称不能包含通过0x1F) (0x00 ASCII 控制字符。对象名称不能包含感叹号 (！) 、句点 (.) 、左方括号 ([) 或右方括号 (]) 字符。验证后，只有字符串中直到第一个空格的部分 (（如果有任何) ）将用于对象名称。这实际上意味着对象名称也可能不包含空格。
JET_errInvalidParameter	提供的其中一个参数包含意外值，或者包含与另一个参数的值组合时没有意义的值。当 pindexid 不为 NULL 且 pindexid-cbStruct> (Windows XP 和早期版本) 时，JetSetCurrentIndex2 可能会发生这种情况。
JET_errNoCurrentRecord	正在使用 JET_bitNoMove 选项选择辅助索引，并且新索引中没有与旧索引上游标当前位置处的索引项关联的记录相对应的索引项。
JET_errNotInitialized	无法完成操作，因为与会话关联的实例尚未初始化。
JET_errOutOfCursors	引擎已耗尽其用于打开游标的资源池。可以使用 JET_paramMaxCursors控制在任何时间可以打开的最大游标数。有关详细信息，请参阅 JetSetSystemParameter 。如果已选择辅助索引，并且引擎无法打开内部游标来使用该索引，则 JetSetCurrentIndex2 可能会发生这种情况。
JET_errRestoreInProgress	无法完成该操作，因为正在对与会话关联的实例执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。此错误仅由 Windows XP 及更高版本返回。
JET_errTermInProgress	无法完成操作，因为正在关闭与会话关联的实例。

成功后，游标的当前索引将设置为请求的索引。现在可以根据所请求索引的索引定义使用 JetSeek 来搜索索引条目。还可以按照该索引定义指定的顺序使用 JetMove 枚举索引条目。游标的当前位置设置为索引 (JET_bitMoveFirst) 上的第一个索引项，或设置为与游标在旧索引 (JET_bitNoMove) 上的当前位置相关的特定索引项。不会更改数据库状态。

失败时，游标的当前索引和当前位置处于未定义状态。不会更改数据库状态。

备注

如果索引 ID 提示过时，则 API 会失败。在这种情况下，不会像人们所期望的那样回退索引的文本名称。此回退必须由 API 的调用方手动完成。

要求

要求	值
客户端	需要 Windows Vista、Windows XP 或 Windows 2000 专业版。
服务器	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。
Unicode	实现为 JetSetCurrentIndex2W (Unicode) 和 JetSetCurrentIndex2A (ANSI) 。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSetSystemParameter
JetSeek
JetStopService

通过

JetSetCurrentIndex2 函数