JetMakeKey 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetMakeKey 函式

JetMakeKey函式會建構搜尋索引鍵，然後透過索引鍵資料行值的一些簡單搜尋準則，用來在索引中尋找一組專案。搜尋索引鍵也是資料指標的其中一個內建屬性， JetSeek 和 JetSetIndexRange 作業會用來找出符合該資料指標目前索引之搜尋準則的索引項目目。完整的搜尋索引鍵會建置在 一系列的 JetMakeKey 呼叫中，其中每個呼叫都會用來載入資料指標目前索引之下一個索引鍵資料行的資料行值。您也可以載入先前建構的搜尋索引鍵，該索引鍵已使用 JetRetrieveKey從資料指標擷取。

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

pvData

輸入緩衝區，其中包含正在建構搜尋索引鍵之資料指標目前索引鍵資料行的資料行資料。

輸入緩衝區中資料行資料的資料類型必須與目前索引鍵資料行之資料行定義的資料類型和其他屬性完全相符。在資料行資料上不執行類型強制型別。

如果在 grbit 參數中指定JET_bitNormalizedKey，輸入緩衝區必須包含先前建構的搜尋索引鍵。這類金鑰是使用 JetRetrieveKey的呼叫來取得。

cbData

輸入緩衝區中提供之資料行資料的大小，以位元組為單位。

如果在 grbit 參數中指定JET_bitNormalizedKey，這是輸入緩衝區中提供的搜尋索引鍵大小。

如果資料行資料的大小為零，則會忽略輸入緩衝區的內容。如果在 grbit 參數中指定JET_bitKeyDataZeroLength，而資料指標目前索引的目前索引鍵資料行是可變長度資料行，則輸入資料行資料會假設為零長度值。否則，輸入資料行資料會假設為 Null 值。

grbit

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

值	意義
JET_bitFullColumnEndLimit	搜尋索引鍵應該以這種方式建構，讓目前索引鍵資料行之後的任何索引鍵資料行視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：為此索引鍵資料行和先前所有索引鍵資料行提供的確切資料行值。後續索引鍵資料行所需的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引結尾的索引項目目。索引結尾是移至該索引中最後一筆記錄時所找到的索引項目目。索引的結尾與索引的高階不同，其可能會根據索引中索引鍵資料行的排序次序而變更。此選項僅適用于 Windows XP 和更新版本。
JETbitFullColumnStartLimit	應該建構搜尋索引鍵，以便將目前索引鍵資料行之後的任何索引鍵資料行視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：為此索引鍵資料行和先前所有索引鍵資料行提供的確切資料行值。後續索引鍵資料行所需的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引開頭的索引項目目。索引的開頭是移至該索引中第一筆記錄時所找到的索引項目目。索引的開頭與索引的低端不同，這會根據索引中索引鍵資料行的排序次序而變更。此選項僅適用于 Windows XP 和更新版本。
JET_bitKeyDataZeroLength	如果輸入緩衝區的大小為零，且目前索引鍵資料行是可變長度資料行，則此選項表示輸入緩衝區包含零長度值。否則，輸入緩衝區大小為零表示 Null 值。
JET_bitNewKey	應該建構新的搜尋索引鍵。任何先前現有的搜尋索引鍵會被捨棄。
JET_bitNormalizedKey	指定此選項時，會忽略所有其他選項、捨棄任何先前現有的搜尋索引鍵，並將輸入緩衝區的內容載入為新的搜尋索引鍵。
JET_bitPartialColumnEndLimit	應該建構搜尋索引鍵，讓目前索引鍵資料行被視為前置詞萬用字元，而且目前索引鍵資料行之後的任何索引鍵資料行都應該視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：為此索引鍵資料行和先前所有索引鍵資料行提供的確切資料行值。後續索引鍵資料行所需的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引結尾的索引項目目。索引結尾是移至該索引中最後一筆記錄時所找到的索引項目目。索引的結尾與索引的高階不同，其可能會根據索引中索引鍵資料行的排序次序而變更。當目前的索引鍵資料行不是文字資料行或變數二進位資料行時，就無法使用此選項。如果嘗試此作業，作業將會失敗，並JET_errInvalidgrbit。此選項僅適用于 Windows XP 和更新版本。
JET_bitPartialColumnStartLimit	此選項表示應該建構搜尋索引鍵，讓目前的索引鍵資料行被視為前置詞萬用字元，而且目前索引鍵資料行之後的任何索引鍵資料行都應該視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：為此索引鍵資料行和先前所有索引鍵資料行提供的確切資料行值。後續索引鍵資料行所需的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引開頭的索引項目目。索引的開頭是移至該索引中第一筆記錄時所找到的索引項目目。索引的開頭與索引的低端不同，這會根據索引中索引鍵資料行的排序次序而變更。當目前的索引鍵資料行不是文字資料行或變數二進位資料行時，就無法使用此選項。如果嘗試此作業，作業將會失敗，並JET_errInvalidgrbit。此選項僅適用于 Windows XP 和更新版本。
JET_bitStrLimit	此選項表示應該建構搜尋索引鍵，以便將目前索引鍵資料行之後的任何索引鍵資料行視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：為此索引鍵資料行和先前所有索引鍵資料行提供的確切資料行值。後續索引鍵資料行所需的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引結尾的索引項目目。索引結尾是移至該索引中最後一筆記錄時所找到的索引項目目。索引的結尾與索引的高階不同，其可能會根據索引中索引鍵資料行的排序次序而變更。當此選項與JET_bitSubStrLimit搭配指定，而目前的索引鍵資料行是文字資料行時，將會忽略此選項。此行為旨在允許在建置搜尋索引鍵時推斷目前索引鍵資料行的類型。如果您想要為索引開頭建立類似的搜尋索引鍵，應該針對不是萬用字元但未指定萬用字元選項的最後一個索引鍵資料行，建立對 JetMakeKey 的類似呼叫。然後，搜尋索引鍵會處於適當的狀態，以便用於這類搜尋。這類似于使用 JET_bitFullColumnStartLimit，不同之處在于搜尋索引鍵在使用萬用字元選項之後並未完全完成。這個選項已被 Windows XP 和更新版本取代，以解決這個不想要的語意。 JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit應盡可能改用。
JET_bitSubStrLimit	此選項表示應該建構搜尋索引鍵，讓目前的索引鍵資料行被視為前置詞萬用字元，而且目前索引鍵資料行之後的任何索引鍵資料行都應該視為萬用字元。這表示建構的搜尋索引鍵可用來比對具有下列專案的索引項目：提供給所有先前索引鍵資料行的確切資料行值。指定的資料行資料做為其目前索引鍵資料行之資料行值的前置詞。後續索引鍵資料行的任何資料行值。建置萬用字元搜尋索引鍵時，應該使用此選項來尋找最接近索引結尾的索引項目目。索引結尾是移至該索引中最後一筆記錄時所找到的索引項目目。索引的結尾與索引的高階不同，其可能會根據索引中索引鍵資料行的排序次序而變更。當此選項與JET_bitStrLimit搭配指定，而目前的索引鍵資料行是文字資料行時，此選項會優先使用。當目前的索引鍵資料行不是文字資料行時，就會忽略這個選項。此行為旨在允許在建置搜尋索引鍵時推斷目前索引鍵資料行的類型。如果您想要為索引開頭建立類似的搜尋索引鍵，應該針對要成為前置詞萬用字元的索引鍵資料行建立類似的 JetMakeKey 呼叫，但未指定任何萬用字元選項。然後，搜尋索引鍵會處於適當的狀態，以便用於這類搜尋。這類似于使用 JET_bitPartialColumnStartLimit，不同之處在于搜尋索引鍵在使用萬用字元選項之後並未完全完成。這個選項已被 Windows XP 和更新版本取代，以解決這個不想要的語意。請盡可能改用JET_bitPartialColumnStartLimit和JET_bitPartialColumnEndLimit。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errIndexTuplesKeyTooSmall	提供的資料行資料太小，無法為目前索引建立有效的索引鍵，因為該索引是 Tuple 索引，而最小 Tuple 大小大於所提供的資料行資料。如需 Tuple 索引的詳細資訊，請參閱 JetCreateIndex 。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidBufferSize	提供的資料行資料不符合資料行定義所需的大小。如果資料行的資料類型本質上是特定大小，就可能發生此情況。如果資料行的資料類型不是內建特定大小，但資料行的定義宣告為固定長度，也會發生這種情況。其中一個例外狀況是，當為固定長度文字資料行提供太少的資料時，將不會發生此錯誤，因為任何遺漏的資料都會自動填補空格。第二個例外狀況是，當為固定長度二進位資料行提供太少的資料時，將不會發生此錯誤，因為任何遺漏的資料都會自動填補零。
JET_errInvalidgrbit	要求的其中一個選項無效、以不合法的方式使用，或未實作。當下列情況時，JetMakeKey 可能會發生此問題：會指定JET_bitPartialColumnStartLimit或JET_bitPartialColumnEndLimit，而對應的索引鍵資料行不是文字資料行，也不是可變長度的二進位資料行。這種情況只會發生在 Windows XP 和更新版本上。嘗試同時使用下列其中一個選項：JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit。這種情況只會發生在 Windows XP 和更新版本上。使用下列其中一個選項時，會嘗試使用JET_bitStrLimit或JET_bitSubStrLimit：JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit和JET_bitFullColumnEndLimit。這種情況只會發生在 Windows XP 和更新版本上。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數的值結合時沒有意義的值。當指定JET_bitNormalizedKey且輸入緩衝區中提供的值太大而無法成為有效的搜尋索引鍵時， JetMakeKey 就會發生這種情況。
JET_errKeyIsMade	已拒絕提供給 JetMakeKey 的資料行資料，因為已針對目前索引中的所有索引鍵資料行提供資料行資料。這可以透過三種方式發生。第一種方式是，如果目前索引中的每個索引鍵資料行都提供資料行資料。第二種方式是，如果至少為一個索引鍵資料行提供資料行資料，而且最後一次呼叫選擇萬用字元選項。第三種方式是使用JET_bitNormalizedKey來提供先前建構的搜尋索引鍵，其中涵蓋所有索引鍵資料行。
JET_errKeyNotMade	資料指標目前沒有搜尋索引鍵。如果未指定JET_bitNewKey，而且尚未使用JetMakeKey呼叫之前針對此資料指標建構搜尋索引鍵，就會發生此情況。在對 JetMove以外的資料指標上任何導覽 API 的呼叫之前，將會刪除搜尋索引鍵。
JET_errNoCurrentIndex	資料指標目前沒有索引。如果游標位於資料表的叢集索引上、尚未定義主索引，而且未指定JET_bitNormalizedKey，則 JetMakeKey 會發生此情況。如果游標位於索引上，除非提供先前建構的搜尋索引鍵，否則無法建構搜尋索引鍵。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於一個以上的執行緒。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。

成功時，如果未指定JET_bitNormalizedKey和JET_bitNewKey，搜尋索引鍵將會由目前索引中一個索引鍵資料行的搜尋準則所建置。如果未指定JET_bitNormalizedKey且已指定JET_bitNewKey，則會捨棄任何先前存在的搜尋索引鍵，而且已由目前索引中第一個索引鍵資料行的搜尋準則所建置新的搜尋索引鍵。如果指定了JET_bitNormalizedKey，則會捨棄任何先前現有的搜尋索引鍵，並從輸入緩衝區載入新的搜尋索引鍵。在任何情況下，都不會變更資料庫狀態。

失敗時，如果指定了JET_bitNormalizedKey或JET_bitNewKey，則搜尋索引鍵的狀態為未定義。如果未指定JET_bitNormalizedKey或JET_bitNewKey，則不會變更搜尋索引鍵的狀態。在任何情況下，都不會變更資料庫狀態。

備註

索引鍵應該視為不透明的資料區塊。不應嘗試利用此資料的內部結構。不過，以下是所有 ESENT 金鑰的已知專案：

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

如果使用萬用字元選項，搜尋索引鍵可以較長一個位元組。在此情況下，在 Windows Vista 和更新版本中，搜尋索引鍵最多會JET_cbLimitKeyMost (256 個) 個位元組，並針對 Windows Vista 和更新版本JET_paramKeyMost + 1 個位元組。

這個金鑰大小上限有一個非常重要的影響。每當有資料行值夠大而足以產生索引鍵的索引項目時，該索引鍵會大於這個大小上限，該索引鍵會以無訊息方式在大小上限處截斷。這會導致兩個效果：

對於唯一索引中的專案，它會導致將唯一的專案宣告為重複專案。
對於所有索引中的專案，索引鍵截斷會導致索引項目不符合指定搜尋索引鍵的搜尋準則，以宣告為相符專案。

應用程式必須預期這種截斷，並避免它或補償其效果。在 Windows Vista 中，已新增新的索引旗標JET_bitIndexDisallowTruncation，讓應用程式更容易防止索引鍵截斷。如需此索引選項的詳細資訊，請參閱JET_INDEXCREATE 結構。

規格需求

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

JetMakeKey 函式