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 (Zero) 。 資料指標會保留在目前的邏輯位置，而且會測試對應至該邏輯位置的索引項目目是否存在。

grbit

指定下列選項之零或多個位群組。

值	意義
JET_bitMoveKeyNE	向前或向後移動資料指標，以略過索引中遇到的索引鍵值數目所需的索引項目數目。 這會影響將索引項目與重複索引鍵值折迭成單一索引項目。 一般而言，不論索引項目的值為何，位移都會依指定的索引項目目數目移動資料指標。

傳回值

此函式會傳回具有下列其中一個傳回碼 的 JET_ERR 資料類型。 如需可能 ESE 錯誤的詳細資訊，請參閱 可延伸儲存引擎錯誤 和 錯誤處理參數。

傳回碼	Description
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、Before First 和 After Last 移至兩個特殊位置。 如果游標位於資料表中的第一個索引項目目上，且使用 JET_MovePrevious 呼叫 JetMove ，則呼叫將會失敗並JET_errNoCurrentRecord，而且資料指標會以邏輯方式放置在索引的第一個專案之前。 即使在索引的第一個專案之前插入另一個索引項目目，仍會保留此邏輯位置。 相對於索引結尾的 After Last，會發生類似的情況。 在使用 JetMove設定要逐一查看的索引專案範圍時，使用預期一律移至下一個 (或先前) 元素的反覆運算器模型，在使用該元素之前，在 [前一頁] 和 [後一頁] 最有用。

JetMove可以流覽的索引項目目集合可以透過設定資料指標上的索引範圍來限制。 這適用于列舉一組符合簡單準則的索引項目目的應用程式，這些準則可透過針對該索引建置的一對搜尋索引鍵來表示。 如需詳細資訊，請參閱 JetSetIndexRange。

在 Windows Server 2003 SP1 之前的版本中， JetMove 在某些情況下發生問題，這會影響 JetSetIndexRange 函式所設定的索引範圍正確強制執行。 如果游標目前在第一個索引項目目之前，且索引範圍設定的上限小於第一個索引項目目，則下一次對 JetMove 的呼叫會錯誤地移至該索引項目目，而不會如預期般失敗，而不會發生JET_errNoCurrentRecord。 從索引結尾開始的類似情況會發生相同的錯誤。 這種情況可能發生在設定索引範圍的應用程式中，並使用預期在要列舉之專案集合成員的第一個索引項目目之前啟動的反覆運算器進行巡覽，而不是從該集合的第一個索引項目目開始。 這種情況也會發生在從索引結尾開始的類似案例上。 因應措施是讓應用程式手動驗證取得的索引項目是否在索引範圍內，方法是比較使用 JetRetrieveKey 擷取的索引鍵 () 與使用 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。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange