JetRetrieveKey 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetRetrieveKey 函式

JetRetrieveKey函式會擷取位於游標目前位置之索引項目的索引鍵。這類金鑰是由 JetMakeKey的呼叫所建構。然後，您可以使用擷取的索引鍵，透過呼叫 JetSeek，有效率地將該資料指標傳回至相同的索引項目目。

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

pvData

將接收金鑰的輸出緩衝區。

cbMax

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

sqlActual

接收金鑰的實際大小，以位元組為單位。

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

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

grbit

一組位，其中包含要用於此呼叫的選項，其中包含下列零個或多個選項。

值	意義
JET_bitRetrieveCopy	指定時，引擎會傳回資料指標的搜尋索引鍵。搜尋索引鍵是使用 JetMakeKey 的一或多個先前呼叫來建置，以便使用 JetSeek 搜尋該索引鍵，或使用 JetSetIndexRange設定索引範圍。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errKeyNotMade	資料指標目前沒有搜尋索引鍵。如果已指定JET_bitRetrieveCopy，而且尚未使用JetMakeKey的呼叫來建構此資料指標的搜尋索引鍵，JetRetrieveKey就會發生這種情況。在對 JetMove以外的資料指標上任何導覽 API 的呼叫之前，將會刪除搜尋索引鍵。
JET_errNoCurrentRecord	游標不在記錄上。此情況具有許多不同的原因。例如，如果游標目前位於目前索引的最後一筆記錄之後，就會發生這種情況。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於一個以上的執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。
JET_wrnBufferTruncated	作業已順利完成，但輸出緩衝區太小而無法接收整個金鑰。輸出緩衝區已填入大小一樣多的索引鍵。如果要求，也會傳回金鑰的實際大小。注意如果指定JET_bitRetrieveCopy，將不會傳回此錯誤。如需詳細資訊，請參閱一節。

成功時，資料指標目前位置的索引項目索引鍵將會在輸出緩衝區中傳回。如果傳回JET_wrnBufferTruncated，則輸出緩衝區會包含符合所提供空間的金鑰數量，且金鑰的實際大小會正確。不會變更資料庫狀態。

失敗時，輸出緩衝區的狀態和金鑰的實際大小將會未定義。不會變更資料庫狀態。

備註

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

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

除了一般 ESENT 索引鍵的上述屬性之外，請務必注意，搜尋索引鍵與索引項目的索引鍵不同。具體而言，搜尋索引鍵可能比一般索引鍵長。建構搜尋索引鍵時使用萬用字元選項時，就會發生這個額外長度。如需詳細資訊，請參閱 JetMakeKey 。

此 API 中有一個重要的 Bug 存在於所有版本中。如果使用 JET_bitRetrieveCopy 要求搜尋索引鍵，而且輸出緩衝區太小而無法接收整個金鑰，則不會傳回JET_wrnBufferTruncated。 JET_errSuccess會改為傳回。請務必確認使用 azureActual 傳回的金鑰實際大小小於或等於輸出緩衝區的大小。如果實際大小大於輸出緩衝區的大小， 則 JetRetrieveKey 的呼叫端應該會回應，就像傳回JET_wrnBufferTruncated一樣。

規格需求

需求	值
用戶端	需要 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
JetMakeKey
JetSeek
JetSetIndexRange

共用方式為

JetRetrieveKey 函式