JetMove 函数

适用于:Windows |Windows服务器

JetMove 函数

JetMove 函数将光标定位在索引的开头或末尾,并遍历该索引中的条目,无论是向前还是向后。 还可以按指定的索引项数向前或向后移动光标。 另一种方法是通过使用 JetSetIndexRange 在游标上设置索引范围来人为地限制可以使用 JetMove 枚举的索引条目。

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

参数

sesid

要用于此调用的会话。

tableid

用于此调用的游标。

乌鸦

一个任意偏移量,指示游标在当前索引上的所需移动。

除了标准偏移量外,还可以使用以下选项之一设置此参数。

含义

JET_MoveFirst

将光标移动到索引中的第一个索引项, (如果存在) 。

注意 -2147483648的文本值用于表示此选项。 请勿将此值用作普通偏移量或意外行为可能会导致。

JET_MoveLast

将光标移动到索引中的最后一个索引项, (如果存在) 。

注意 2147483647的文本值用于表示此选项。 请勿将此值用作普通偏移量或意外行为可能会导致。

JET_MoveNext

将光标移动到索引中的下一个索引项, (如果存在) 。 此值完全等于 +1 的普通偏移量。

JET_MovePrevious

将光标移动到索引中的上一个索引项, (如果存在) 。

此值与普通偏移量 -1 或 0 (Zero) 完全相等。

游标保留在当前逻辑位置,并且将测试对应于该逻辑位置的索引项的存在。

grbit

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

含义

JET_bitMoveKeyNE

通过跳过索引中遇到的索引键值数,向前或向后移动游标。 这会影响将索引项与重复键值折叠成单个索引项。 通常,无论其键值如何,偏移量都会按指定的索引项数移动游标。

返回值

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

返回代码

说明

JET_errSuccess

操作已成功完成。 对于 JetMove,这意味着在请求的位置或当前索引的偏移量处找到了索引项。

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

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

Windows XP:Windows XP 中引入了此返回值。

JET_errNoCurrentRecord

游标当前未定位在索引项上。 对于 JetMove,这意味着在请求的位置或当前索引上的偏移量上找不到索引项。

JET_errNotInitialized

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

JET_errRecordDeleted

游标当前在与已删除的记录对应的索引项上进行逻辑定位。

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

Windows XP:Windows XP 中引入了此返回值。

JET_errTermInProgress

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

如果此函数成功,游标将定位在与请求的位置或偏移量匹配的索引项。 如果已准备好更新记录,则会取消该更新。 如果索引范围生效,并且指定了JET_MoveFirst或JET_MoveLast,则会取消该索引范围。 不会更改数据库状态。

如果此函数失败,则除非返回JET_errNoCurrentRecord,否则游标的位置将保持不变。 在这种情况下,游标将定位到与所请求的位置或偏移量匹配的索引项的位置。 游标可以相对于该位置移动,但仍不在有效的索引项上。 如果已准备好更新记录,则会取消该更新。 如果索引范围生效,并且指定了JET_MoveFirst或JET_MoveLast,则会取消该索引范围。 不会更改数据库状态。

注解

光标可以使用 JetMove、First 和 After Last 移动到两个特殊位置。 如果游标位于表中的第一个索引项上,并且 JetMove 使用JET_MovePrevious调用,则调用将失败,JET_errNoCurrentRecord,并且游标将在索引的第一个条目之前进行逻辑定位。 即使在索引的第一个条目之前插入了另一个索引项,也会保留此逻辑位置。 相对于索引末尾的 After Last,会出现类似的情况。 在使用 JetMove 设置要迭代的索引项范围时,在先于“先行”和“最后一个”之后,使用迭代器模型(希望始终移动到该元素之前的下一个 (或以前的) 元素)时最有用。

JetMove 可以访问的索引项集可以通过在游标上设置索引范围来限制。 这对于枚举一组与为该索引生成的搜索键配对表示的简单条件匹配的索引条目的应用程序非常有用。 有关详细信息,请参阅 JetSetIndexRange

在 Windows Server 2003 SP1 之前的版本中,JetMove 在某些特定情况下出现问题,这会影响 JetSetIndexRange 函数设置的索引范围的正确强制实施。 如果游标当前位于第一个索引项之前,并且索引范围设置的上限小于第一个索引项,则对 JetMove 的下一次调用将错误地转到该索引项,而不是按预期JET_errNoCurrentRecord失败。 从索引末尾开始的类似情况将发生相同的错误。 在设置索引范围的应用程序中,可能会发生这种情况,并使用迭代器来导航它,该迭代器希望在作为枚举的条目集的成员的第一个索引项之前启动,而不是从该集的第一个索引项开始。 这种情况也发生在从索引末尾开始的类似情况上。 解决方法是,应用程序通过比较使用 JetRetrieveKey) 检索到的当前索引项的键来手动验证获取的索引 (项是否在索引范围内,并比较使用 JET_bitRetrieveCopy) 使用 JetRetrieveKey 检索的当前索引范围的末尾的键 (。

将计算偏移量传递给 JetMove 时,请务必小心。 如果计算偏移量小于或等于JET_MoveFirst,则必须将偏移量分解为多个部分,每个偏移量分别传递到 JetMove ,但在单个事务中才能获得所需的效果。 对于大于或等于JET_MoveNext的偏移量,也是如此。 在现实世界中,应用程序不太可能经历这种情况,但鉴于JET_MoveFirst和JET_MoveLast的语义与普通偏移量非常不同,因此最好对此情况进行防御。

当使用非常大的偏移量(例如 cRow 参数设置为 1000 时)调用 JetMove 时, JetMove 将遍历所有 1000 个索引条目以到达最终位置。 目前,ESE API 不提供通过偏移量直接移动到给定索引项的有效方法,而无需遍历每个索引项。

要求

要求

客户端

需要 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
JetRetrieveKey
JetSetIndexRange