JetRetrieveColumns 函式

發行項
01/28/2024

適用于：Windows |Windows伺服器

JetRetrieveColumns 函式

JetRetrieveColumns函式會從單一作業中的目前記錄擷取多個資料行值。 JET_RETRIEVECOLUMN結構的陣列可用來描述要擷取的資料行值集，以及描述要擷取之每個資料行值的輸出緩衝區。

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

參數

sesid

要用於這個呼叫的會話。

tableid

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

pretrievecolumn

一或多個 JET_RETRIEVECOLUMN 結構的陣列指標。每個結構都包含要擷取的資料行值，以及儲存傳回資料的位置的描述。

cretrievecolumn

由 pretrievecolumn所指定陣列中的JET_RETRIEVECOLUMN結構數目。

傳回值

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

傳回碼	描述
JET_errSuccess	作業已成功完成。
JET_errBadItagSequence	在 pretinfo-itagSequence > 中傳遞了不正確多值資料行序號值。多重值資料行值序號的有效值為 1 或更大。值 0 (零) 對此函式有效，但 JetRetrieveColumn無效。
JET_errBadColumnId	提供的資料行識別碼超出資料行識別碼的法律限制。
JET_errClientRequestToStopJetService	無法完成作業，因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。
JET_errColumnNotFound	指定的 columnid 所描述的資料行不存在於資料表中。
JET_errIndexTuplesCannotRetrieveFromIndex	無法從索引擷取以子字串編制索引的資料行，因為每個索引項目目中通常只有一小部分的資料行存在。
JET_errInvalidBufferSize	在某些情況下，為擷取資料行指定的緩衝區必須有足夠的大小，才能傳回任何數量的資料行值。例如，委付可更新的資料行會針對呼叫會話的交易內容調整為一致，而這項調整需要呼叫端提供的緩衝區。如果提供緩衝區空間不足，則會傳回JET_errInvalidBufferSize，而且不會傳回任何資料行資料。
JET_errInvalidgrbit	提供的選項未知或不合法的已知位設定組合。
JET_errInvalidParameter	指定的一或多個參數不正確。如果 retinfo.cbStruct 的大小小於 JET_RETINFO，就可能會發生這種情況。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，需要撤銷所有資料的存取權，以保護該資料的完整性。 Windows XP：此錯誤只會由 Windows XP 和更新版本傳回。
JET_errNoCurrentRecord	游標不在記錄上。此情況具有許多不同的原因。例如，如果游標目前位於目前索引的最後一筆記錄之後，就會發生這種情況。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errRestoreInProgress	無法完成作業，因為與會話相關聯的實例上正在進行還原作業。
JET_errSessionSharingViolation	同一個會話不能同時用於一個以上的執行緒。 Windows XP：此錯誤只會由 Windows XP 和更新版本傳回。
JET_errTermInProgress	無法完成作業，因為與會話相關聯的實例正在關閉。
JET_wrnBufferTruncated	無法擷取整個資料行值，因為指定的緩衝區小於資料行的大小。

成功時，資料行資料和資料行大小會在 JET_RETRIEVECOLUMN結構的陣列中所述的提供緩衝區中傳回。如果 itagSequence 設定為 0 (零) 表示需要多重值欄位的實例數目，而不是資料行資料，則會在 itagSequence 欄位中傳回多重值資料行的實例數目。每個 JET_RETRIEVECOLUMN 結構都有一個錯誤欄位，其中包含所擷取資料行的警告。如果資料行值為 Null ，則錯誤碼會設定為 JET_wrnColumnNull。

失敗時，資料指標位置會保持不變，而且不會將資料複製到提供的緩衝區。

備註

JetRetrieveColumns 支援 JetRetrieveColumn 不支援的一項功能。這是擷取多重值資料行實例數目的能力。這項功能的目的是允許應用程式擷取資料行的所有值。您可以先判斷資料行所擁有的值數目，藉此完成此動作。接下來，您可以再次呼叫 JetRetrieveColumns ，並為每個值配置一個 JET_RETRIEVECOLUMN 結構來判斷其長度，以判斷資料行資料的長度。做法是傳遞nullpvData指標，其 cbMax為 0 (零) ，並以cbActual擷取資料行長度。第三個和最後一個呼叫可以針對資料行值資料使用配置的記憶體。

如果因為長度緩衝區不足而截斷任何擷取的資料行，則 API 會傳回JET_wrnBufferTruncated。不過，其他錯誤JET_wrnColumnNull只會在 JET_RETRIEVECOLUMN的錯誤欄位中傳回。這是因為應用程式通常會想要確保已擷取所有資料，並從 JetRetrieveColumns 傳回此錯誤有助於瞭解。

規格需求

需求	值
用戶端	需要 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
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns

共用方式為

JetRetrieveColumns 函式