JetEnumerateColumns 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetEnumerateColumns 函式

JetEnumerateColumns函式有效率地從游標的目前記錄或該資料指標的複製緩衝區擷取一組資料行及其值。擷取的資料行和值可以受到資料行識別碼、 itagSequence 數位和其他特性的清單所限制。這個資料行擷取 API 是唯一的，它會傳回動態配置記憶體中的資訊，而該記憶體是使用使用者提供的重新配置相容回呼取得。這個新的彈性可讓具有特定特性的資料行資料 (有效率地擷取，例如呼叫端未知的大小和乘數) 。這樣就不需要使用 JetRetrieveColumn 的探索模式來判斷這些特性，才能設定 JetRetrieveColumn 的最終呼叫，以成功擷取所需的資料。

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

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

cEnumColumnId

資料行識別碼的陣列，每個識別碼都有要列舉 的 itagSequence 數位選擇性陣列。

如果 cEnumColumnId 為 0 (零) 則會忽略 rgEnumColumnId ，而且會列舉並傳回給呼叫端的所有資料行值。如果資料行識別碼陣列的專案參考資料行識別碼為 0 (零) 則會略過該資料行的列舉，而且輸出中的對應位置會產生資料行狀態為 JET_wrnColumnSkipped。

如果 ctagSequence 為 0 (零) 資料行識別碼陣列的指定元素，則會忽略 rgtagSequence ，並列舉該資料行識別碼的所有資料行值，並傳回給呼叫端。如果 itagSequence 數位陣列的元素參考 itagSequence 數位 0 (零) 則會略過 該 itagSequence 編號的列舉，且輸出中的對應位置會產生資料行值狀態為 JET_wrnColumnSkipped。

rgEnumColumnId

請參閱 cEnumColumnId。

pcEnumColumn

傳回透過提供的 itagSequence 相容回呼所配置的記憶體中資料行及其值的列舉陣列。

如果輸入要求資料行識別碼的陣列，則輸出陣列的順序和大小會反映輸入陣列的順序和大小。同樣地，如果輸入上的特定資料行識別碼要求 itagSequence 數位的陣列，該資料行之資料行值的輸出陣列順序和大小將會反映輸入陣列的順序和大小。

除了JET_errBadColumnId和JET_errColumnNotFound以外，輸出參數會設定為 0 (零) 和 Null 。傳回這些錯誤時，輸出資料對受影響的資料行識別碼而言都是有效的，而且已完成。每個受影響資料行識別碼的狀態碼都會設定為下列其中一個錯誤，讓呼叫端可能會判斷哪些資料行識別碼不正確，而且可能會採取更正動作。

prgEnumColumn

請參閱 pcEnumColumn。

pfnRealloc

識別與重新配置相容的回呼，以及用來為數據行及其值的輸出陣列配置記憶體的選擇性內容指標。

pvReallocCoNtext

請參閱 pfnRealloc。

cbDataMost

設定要從長文字或長二進位資料行傳回的資料量上限。

此參數可用來防止列舉極大型的資料行值。一般而言，這類列舉可能會讓 API 呼叫失敗，並JET_errOutOfMemory。如果以這種方式截斷大型資料行值，則資料行值的狀態將會JET_wrnColumnTruncated。

grbit

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

值	意義
JET_bitEnumerateCompressOutput	列舉資料行值時，我們擷取所有值且只有一個非 Null 資料行值的所有資料行都可以以壓縮格式傳回。這類資料行的狀態會設定為JET_wrnColumnSingleValue，且資料行值的大小，而包含資料行值的記憶體將會直接在 JET_ENUMCOLUMN 結構中傳回。不保證所有合格資料行都會以這種方式壓縮。如需詳細資訊，請參閱JET_ENUMCOLUMN 。
JET_bitEnumerateCopy	此選項表示應該列舉記錄的修改資料行值，而不是原始資料行值。如果尚未修改資料行值，則會列舉原始資料行值。如此一來，插入或更新記錄時，可能會列舉尚未插入或更新的資料行值。此選項與搭配 JetRetrieveColumn 或 JetRetrieveColumns使用時JET_bitRetrieveCopy相同。
JET_bitEnumerateIgnoreDefault	如果記錄中沒有指定的資料行，則不會傳回任何資料行值。一般而言，如果有任何值，則會在此案例中傳回資料行的預設值。保證如果資料行設定為與預設值不同的值，則會傳回不同的值 (也就是說，如果具有預設值的資料行明確設定為 Null ，則會傳回 Null 作為該資料行的值) 。請注意，即使已要求這個選項，仍可以看到發生等於預設值的資料行值。不努力移除符合其預設值的資料行值。請務必注意，此選項會影響搭配JET_bitEnumeratePresenceOnly或JET_bitEnumerateTaggedOnly使用的 JetEnumerateColumns 輸出。
JET_bitEnumerateIgnoreUserDefinedDefault	如果記錄中沒有指定的資料行，而且其具有使用者定義的預設值，則不會傳回任何資料行值。此選項可防止在列舉該資料行的值時呼叫資料行的使用者定義預設值的回呼。 Windows Server 2003 和更早版本：針對 Windows Server 2003 和更早版本，作業將會失敗，並JET_errCallbackFailed。 Windows Server 2003 SP1：這個可能的值僅適用于 Windows Server 2003 SP1 和更新版本的作業系統。如果指定這個可能的值，而且資料表包含具有使用者定義預設值的資料行，則作業將會失敗並JET_errCallbackFailed。
JET_bitEnumeratePresenceOnly	如果要求的資料行或資料行值存在非 Null 值，則不會傳回相關聯的資料。相反地，該資料行或資料行值的相關聯狀態會設定為JET_wrnColumnPresent。如果資料行或資料行值為 Null ，則會如往常一樣傳回JET_wrnColumnNull。
JET_bitEnumerateTaggedOnly	例如，列舉記錄中的所有資料行值 (，也就是 cEnumColumnId 為零) 時，只會傳回標記的資料行值。列舉資料行識別碼的特定陣列時，不允許使用此選項。
JET_bitEnumerateInRecordOnly	Windows 7： Windows 7 中引進了JET_bitEnumerateInRecordOnly。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errBadColumnId	指定的資料行識別碼超出資料行識別碼的法律限制。如果要求特定資料行識別碼，則 JetEnumerateColumns 會傳回此錯誤，其中一個資料行識別碼無效，第一個不正確資料行識別碼失敗，其資料行狀態碼發生此錯誤。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errColumnNotFound	指定的資料行識別碼所描述的資料行不存在於資料表中。如果要求特定資料行識別碼，則 JetEnumerateColumns 會傳回此錯誤，其中一個資料行識別碼無效，而第一個不正確資料行識別碼失敗，其資料行狀態碼就會發生此錯誤。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。 Windowsxp：此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidgrbit	要求的其中一個選項無效或未實作。 JetEnumerateColumns會在下列情況下傳回此錯誤：指定JET_bitEnumerateLocal。指定了不合法的 grbit 。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數的值結合時沒有意義的值。 JetEnumerateColumns會在下列情況下傳回此錯誤： pcEnumColumn 為 Null。 prgEnumColumn 為 Null。 pfnRealloc 為 Null。
JET_errNoCurrentRecord	游標不在記錄上。此情況具有許多不同的原因。例如，如果游標目前位於目前索引的最後一筆記錄之後，就會發生這種情況。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRecordDeleted	游標位於已刪除的記錄上。此情況具有許多不同的原因。最常見的原因是會話不在交易中、資料指標位於記錄、該記錄已刪除，然後資料指標嘗試參考該記錄。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於一個以上的執行緒。 Windowsxp：此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。

成功時，要求的資料將會在輸出緩衝區中傳回。呼叫端必須負責釋放此回呼所配置的任何記憶體，並在輸出緩衝區中傳回。該記憶體應該透過提供的重新配置相容回呼釋放。不會變更資料庫狀態。

失敗時，不會傳回任何要求的資料。在呼叫期間配置的任何記憶體都會使用提供的重新配置相容回呼自動釋放。不會變更資料庫狀態。

備註

如果您要列舉記錄中的所有資料行值，但未指定JET_bitEnumerateIgnoreDefaults，則無法假設您永遠不會看到狀態碼為 JET_wrnColumnNull的資料行或資料行值。如果資料行具有預設值且明確設定為 Null ，或資料行是非疏鬆資料行 (例如固定或變數資料行) ，則您可以看到此狀態碼。

cbDataMost參數不適用於所有資料行值。此參數只會截斷長文字和長二進位資料行值，這些值很大，因此它們已與記錄分開儲存。

如果 JetEnumerateColumns 在其輸出參數中傳回資料，則呼叫端會負責釋放陣列中的記憶體，以及該陣列中內嵌指標所參考的任何記憶體。

規格需求

需求	值
用戶端	需要 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
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns

共用方式為

JetEnumerateColumns 函式