JetGetSecondaryIndexBookmark 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetGetSecondaryIndexBookmark 函式

JetGetSecondaryIndexBookmark函式會擷取游標目前位置之次要索引項目目的特殊書簽。接著，您可以使用此書簽，使用 JetGotoSecondaryIndexBookmark有效率地將游標重新置放回相同的索引項目目。在包含重複索引鍵或包含相同記錄多個索引項目的次要索引上重新置放時，這非常有用。

Windows XP：JetGetSecondaryIndexBookmark 是在 Windows XP 中引進。

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

pvSecondaryKey

接收次要金鑰的輸出緩衝區。

cbSecondaryKeyMax

次要索引鍵的輸出緩衝區大小上限，以位元組為單位。

@secondaryKeyActual

接收次要金鑰位元組的實際大小。

如果此參數為 Null，將不會傳回次要金鑰的實際大小。

如果輸出緩衝區太小，仍會傳回次要金鑰的實際大小。這表示這個數位會大於輸出緩衝區的大小。

pvPrimaryBookmark

接收主鍵書簽的輸出緩衝區。

cbPrimaryBookmarkMax

主鍵書簽的輸出緩衝區大小上限，以位元組為單位。

apiPrimaryKeyActual

接收主鍵書簽的實際大小，以位元組為單位。

如果此參數為 Null，則不會傳回主鍵書簽的實際大小。

如果輸出緩衝區太小，仍會傳回主鍵書簽的實際大小。這表示這個數位會大於輸出緩衝區的大小。

grbit

保留供未來使用。

傳回值

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

傳回碼	描述
JET_errSuccess	作業已成功完成。
JET_errBufferTooSmall	作業已順利完成，但其中一個輸出緩衝區太小，無法接收要求的資料。輸出緩衝區已填入符合的書簽數量。如果已要求，也會傳回書簽的實際大小。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errNoCurrentIndex	游標目前不在次要索引上。當游標目前未使用次要索引時，擷取次要索引書簽並不有意義。當游標不在次要索引上時，應該使用JetGetBookmark。
JET_errNoCurrentRecord	游標不在記錄上。此情況具有許多不同的原因。例如，如果游標目前位於目前索引上最後一筆記錄之後，就會發生這種情況。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errSessionSharingViolation	同一個會話不能同時用於多個執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。

成功時，資料指標目前位置之索引項目目的次要索引書簽將會在輸出緩衝區中傳回。不會變更資料庫狀態。

失敗時，除非傳回JET_errBufferTooSmall，否則輸出緩衝區的狀態和次要索引書簽的實際大小將會未定義。如果傳回JET_errBufferTooSmall，輸出緩衝區會包含與提供的空間一樣多的次要索引書簽，而次要索引書簽的實際大小將會正確。在任何情況下，都不會變更資料庫狀態。

備註

書簽通常應該視為不透明的資料區塊。不應嘗試利用此資料的內部結構。不過，下列屬性可以知道所有 ESENT 書簽：

書簽可唯一識別指定資料表中的記錄。
記錄的書簽不會在該記錄的存留期內變更。
記錄的書簽與包含該記錄之資料表上主要索引上的該記錄索引鍵相同。如果未在該資料表上定義任何主索引，資料庫引擎將會為記錄建立自己的書簽。
您可以使用 memcmp 彼此比較書簽，以在源記錄的資料表上，在主要索引中建立其相對順序。如果未在該資料表上定義任何主要索引，則來自該資料表的書簽相對順序沒有意義。
從不同的資料表與彼此比較記錄書簽是無意義的。
在 Windows Vista 之前，書簽一律小於或等於 JET_cbBookmarkMost (256) 個位元組。在 Windows Vista 和更新版本上，書簽可以較大。書簽的大小上限等於目前JET_paramKeyMost + 1 的值。

索引鍵通常應該視為不透明的資料區塊。不應嘗試利用此資料的內部結構。不過，下列屬性可以知道所有 ESENT 索引鍵：

您可以使用 memcmp 彼此比較索引鍵，以在源索引項目目的資料表上建立其相對順序。
從不同的索引與不同索引之間比較索引項目目的索引鍵是無意義的。
在 Windows Vista 之前，索引鍵一律小於或等於 JET_cbKeyMost (255) 個位元組。在 Windows Vista 和更新版本上，金鑰可以更大。索引鍵的大小上限等於JET_paramKeyMost的目前值。

規格需求

需求	值
用戶端	需要 Windows Vista 或 Windows XP。
Server	需要 Windows Server 2008 或 Windows Server 2003。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp

共用方式為

JetGetSecondaryIndexBookmark 函式