JetMove 函数

适用于: Windows |Windows Server

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

将光标移动到索引中的第一个索引项, (如果存在) 。 这会重置 使用 JetSetIndexRange 设置的任何索引范围。

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

JET_MoveLast

将光标移动到索引中的最后一个索引项, (如果存在) 。 这会重置 使用 JetSetIndexRange 设置的任何索引范围。

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

JET_MoveNext

将光标移动到索引中的下一个索引项, (如果存在) 。 此值完全等于 +1 的普通偏移量。 它遵循 使用 JetSetIndexRange 设置的索引范围。

JET_MovePrevious

将光标移动到索引中的上一个索引项, (如果存在) 。 它遵循 使用 JetSetIndexRange 设置的索引范围。

此值完全等于 -1 或 0 (零) 的普通偏移量。

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

grbit

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

含义

JET_bitMoveKeyNE

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

返回值

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

返回代码

描述

JET_errSuccess

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

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

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

Windowsxp: 此返回值在 Windows XP 中引入。

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRecordDeleted

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

Windowsxp: 此返回值在 Windows XP 中引入。

JET_errTermInProgress

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

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

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

备注

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

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

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

Header

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange