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 将光标移动到两个特殊位置：“第一个之前”和“最后一个之后”。 如果游标位于表的第一个索引项上，并且使用 JET_MovePrevious 调用 JetMove ，则调用将失败并JET_errNoCurrentRecord并且游标将在逻辑上定位在索引中的第一个条目之前。 即使在索引中的第一个项之前插入了另一个索引项，也会保留此逻辑位置。 相对于索引末尾的 After Last，会出现类似的情况。 使用 JetMove 设置要循环访问的索引条目范围时，使用迭代器模型最有用，该模型预期在使用该元素之前始终移动到下一个 (或上一个) 元素。

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

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

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

当使用非常大的偏移量调用 JetMove 时，例如当 cRow 参数设置为 1000 时， JetMove 将遍历所有 1000 个索引条目以到达最终位置。 目前，ESE 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。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange