JetGotoBookmark 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetGotoBookmark 函式

JetGotoBookmark 函式會將游標定位至與指定書簽相關聯的記錄索引項目目。書簽可以搭配資料表上定義的任何索引使用。您可以使用 JetGetBookmark擷取記錄的書簽。

    JET_ERR JET_API JetGotoBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          void* pvBookmark,
      __in          unsigned long cbBookmark
    );

參數

sesid

要用於這個呼叫的會話。

tableid

要用於這個呼叫的資料指標。

pvBookmark

緩衝區，包含用來放置游標的書簽。

cbBookmark

緩衝區中書簽的大小。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errClientRequestToStopJetService	作業無法完成，因為與會話相關聯的實例上的所有活動都因為對 JetStopService的呼叫而停止。
JET_errInstanceUnavailable	作業無法完成，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。 Windowsxp：此傳回值是在 Windows XP 中引進的。
JET_errInvalidBookmark	提供的書簽無效。這可能是因為書簽的大小為零，或是書簽緩衝區指標為 Null而發生。
JET_errNoCurrentRecord	資料指標位於次要索引上，而且找不到與書簽相關聯的記錄索引項目目。
JET_errNotInitialized	無法完成作業，因為尚未初始化與會話相關聯的實例。
JET_errRecordDeleted	找不到與書簽相關聯的記錄。
JET_errRestoreInProgress	作業無法完成，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於多個執行緒。 Windowsxp：此傳回值是在 Windows XP 中引進的。
JET_errTermInProgress	作業無法完成，因為與會話相關聯的實例正在關閉。

如果此函式成功，資料指標將會放在與指定書簽相關聯的記錄索引項目目。如果記錄已準備好進行更新，將會取消該更新。如果索引範圍生效，則會取消該索引範圍。如果已針對游標建構搜尋索引鍵，則會刪除該搜尋索引鍵。不會變更資料庫狀態。

如果此函式失敗，資料指標的位置將會保持不變。如果記錄已準備好進行更新，將會取消該更新。如果索引範圍生效，則會取消該索引範圍。如果已針對游標建構搜尋索引鍵，則會刪除該搜尋索引鍵。不會變更資料庫狀態。

備註

有兩種方式可以使用書簽將游標放在索引上。第一個是使用書簽直接放置在記錄上。當資料指標的目前索引是主要索引時，就會發生這種情況。這項技術的運作方式是 ESENT 書簽與相關聯記錄的主鍵相同。

使用書簽的第二種方式是將它放在與該書簽相關聯之記錄的次要索引中。在此程式期間，引擎會使用主要索引上的書簽來查閱實際記錄。然後，它會使用記錄資料和次要索引定義，將索引鍵計算到指向記錄的次要索引中。然後，它會將該索引鍵的索引項目目放在游標上。如果資料指標目前位於一或多個多重值索引鍵資料行上的次要索引，資料指標將會放在對應至每個索引鍵資料行的第一個多重值索引項目上。

規格需求

需求	值
用戶端	需要 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_SESID
JET_TABLEID
JetGetBookmark

共用方式為

JetGotoBookmark 函式