JetSetCurrentIndex4 函数

  • 项目

适用于： Windows |Windows Server

JetSetCurrentIndex4 函数

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

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

参数

sesid

用于此调用的会话。

tableid

用于此调用的游标。

szIndexName

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

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

pindexid

要为游标选择的索引的 ID。

索引 ID 是可变的不透明句柄，可用于快速选择索引。 可以使用 JetGetIndexInfo 或使用 JET_IdxInfoIndexId 选项的 JetGetTableIndexInfo 检索此 ID。

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

如果此参数不存在，则其值假定为 NULL。

grbit

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

值

含义

JET_bitMoveFirst

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

JET_bitNoMove

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

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

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

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

itagSequence

用于在新索引上定位光标的多值列值的序列号。

此参数仅与 JET_bitNoMove 一起使用。 有关更多详细信息，请参阅此选项的说明。

如果此参数不存在或设置为零，则假定其值为 1。

返回值

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

返回代码

说明

JET_errSuccess

操作已成功完成。

JET_errBadItagSequence

使用 JET_bitNoMove 选项选择辅助索引，并且与指定序列号相对应的新索引的定义中的第一个多值键列没有值。

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。

此错误仅由 Windows XP 和更高版本返回。

JET_errInvalidIndexId

索引 ID 的内容无效或已过期，需要刷新。 在以下情况下 ，JetSetCurrentIndex4 可能会发生这种情况：

  • 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 和早期版本 () 的预期大小时，JetSetCurrentIndex4 可能会发生这种情况。

JET_errNoCurrentRecord

使用 JET_bitNoMove 选项选择辅助索引，并且新索引中没有与旧索引上游标当前位置的索引项关联的记录相对应的索引项。

JET_errNotInitialized

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

JET_errOutOfCursors

引擎已耗尽用于打开游标的资源池。 可以使用 JET_paramMaxCursors 控制在任何时间可以打开的最大游标数。 有关详细信息 ，请参阅 JetSetSystemParameter 。 当已选择辅助索引并且引擎无法打开内部游标以使用该索引时， JetSetCurrentIndex4 可能会发生这种情况。

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

同一会话不能同时用于多个线程。

此错误仅由 Windows XP 和更高版本返回。

JET_errTermInProgress

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

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

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

备注

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

要求

要求 值

客户端

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

服务器

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

标头

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

Unicode

实现为 JetSetCurrentIndex4W (Unicode) 和 JetSetCurrentIndex4A (ANSI) 。

另请参阅

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