SQLGetData 函式

發行項
11/06/2024

一致性
引進版本：ODBC 1.0 標準合規性：ISO 92

摘要
SQLGetData 會擷取結果集中單一數據行的數據，或在 SQLParamData 傳回SQL_PARAM_DATA_AVAILABLE之後擷取單一參數的數據。您可以多次呼叫它，以擷取元件中的可變長度數據。

語法

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

引數

StatementHandle
[輸入]語句句柄。

Col_or_Param_Num
[輸入]若要擷取數據行數據，這是要傳回數據的數據行數目。結果集數據行會以從 1 開始增加數據行順序來編號。書籤數據行是欄號 0;只有在啟用書籤時，才能指定這個值。

若要擷取參數數據，它是從1開始的參數序數。

TargetType
[輸入]*TargetValuePtr 緩衝區之 C 數據類型的類型識別符。如需有效 C 數據類型和類型識別碼的清單，請參閱附錄 D：資料類型中的 C 數據類型一節。

如果 TargetType 是SQL_ARD_TYPE，驅動程式會使用 ARD SQL_DESC_CONCISE_TYPE 欄位中指定的類型識別碼。如果 TargetType 是SQL_APD_TYPE，SQLGetData 將會使用 SQLBindParameter 中指定的相同 C 數據類型。否則，SQLGetData 中指定的 C 數據類型會覆寫 SQLBindParameter 中指定的 C 數據類型。如果SQL_C_DEFAULT，驅動程式會根據來源的 SQL 數據類型選取預設 C 資料類型。

您也可以指定擴充的 C 資料類型。如需詳細資訊，請參閱 ODBC 的 C 資料類型。

TargetValuePtr
[輸出]要在其中傳回數據的緩衝區指標。

TargetValuePtr 不可以是 NULL。

BufferLength
[輸入]以位元組為單位的 *TargetValuePtr 緩衝區長度。

驅動程式會使用 BufferLength 來避免在傳回可變長度數據，例如字元或二進位數據時，寫入超過 *TargetValuePtr 緩衝區的結尾。請注意，當將字元數據傳回 *TargetValuePtr 時，驅動程式會計算 Null 終止字元。 *因此，TargetValuePtr 必須包含 Null 終止字元的空間，否則驅動程式會截斷數據。

當驅動程式傳回固定長度的數據，例如整數或日期結構時，驅動程式會忽略 BufferLength ，並假設緩衝區夠大，足以保存數據。因此，應用程式必須為固定長度的數據配置足夠大的緩衝區，否則驅動程式會寫入緩衝區結尾。

當 BufferLength 小於 0，但當 BufferLength 為 0 時，SQLGetData 會傳回 SQLSTATE HY090 （無效的字串或緩衝區長度）。

StrLen_or_IndPtr
[輸出]要在其中傳回長度或指標值的緩衝區指標。如果這是 Null 指標，則不會傳回長度或指標值。當擷取的數據為 NULL 時，這會傳回錯誤。

SQLGetData 可以在長度/指標緩衝區中傳回下列值：

可供傳回之數據的長度
SQL_NO_TOTAL
SQL_NULL_DATA

如需詳細資訊，請參閱本主題中的使用長度/指標值和「批注」。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLGetData 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 搭配SQL_HANDLE_STMT的 HandleType 和 StatementHandle 句柄，即可取得相關聯的 SQLSTATE 值。下表列出 SQLGetData 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	描述
01000	一般警告	驅動程式特定的資訊訊息。（函式會傳回SQL_SUCCESS_WITH_INFO。）
01004	字串數據，右截斷	並非所有指定數據行的數據，Col_or_Param_Num，都可以在對函式的單一呼叫中擷取。在目前呼叫 SQLGetData 之前，SQL_NO_TOTAL或指定數據行中剩餘的數據長度會在 *StrLen_or_IndPtr 中傳回。（函式會傳回SQL_SUCCESS_WITH_INFO。）如需針對單一數據行使用多個 SQLGetData 呼叫的詳細資訊，請參閱。
01S07	小數截斷	針對一或多個數據行傳回的數據已截斷。針對數值數據類型，數位的小數部分已截斷。針對包含時間元件的 time、timestamp 和 interval 數據類型，時間的小數部分已截斷。（函式會傳回SQL_SUCCESS_WITH_INFO。）
07006	受限制的數據類型屬性違規	結果集中數據行的數據值無法轉換成自變數 TargetType 所指定的 C 數據類型。
07009	無效的描述元索引	為 Col_or_Param_Num自變數指定的值為 0，且 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_OFF。為自變數指定的值Col_or_Param_Num 大於結果集中的數據行數目。 Col_or_Param_Num值不等於可用的參數序數。（DM）指定的數據行已繫結。此描述不適用於在 SQLGetInfo 中傳回 SQL_GETDATA_EXTENSIONS 選項SQL_GD_BOUND位掩碼的驅動程式。（DM）所指定資料行的數目小於或等於最高系結數據行的數目。此描述不適用於傳回 SQLGetInfo 中SQL_GETDATA_EXTENSIONS選項SQL_GD_ANY_COLUMN位掩碼的驅動程式。（DM）應用程式已針對目前數據列呼叫 SQLGetData;目前呼叫中指定的數據行數目小於上述呼叫中指定的數據行數目;而且驅動程式不會傳回 SQLGetInfo 中SQL_GETDATA_EXTENSIONS選項的SQL_GD_ANY_ORDER位掩碼。（DM） TargetType 自變數已SQL_ARD_TYPE，且 ARD 中的Col_or_Param_Num 描述元記錄失敗了一致性檢查。（DM） TargetType 自變數已SQL_ARD_TYPE，而 ARD SQL_DESC_COUNT 欄位中的值小於 Col_or_Param_Num 自變數。
08S01	通訊連結失敗	驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。
22002	需要指標變數，但未提供	StrLen_or_IndPtr是 Null 指標，而且已擷取 NULL 數據。
22003	超出範圍的數值	傳回數據行的數值（做為數值或字串），會導致截斷數位的整數部分（而不是小數部分）。如需詳細資訊，請參閱附錄 D：數據類型。
22007	無效的日期時間格式	結果集中的字元數據行已系結至 C 日期、時間或時間戳結構，而且數據行中的值是無效的日期、時間或時間戳。如需詳細資訊，請參閱附錄 D：數據類型。
22012	除以零	從算術表達式傳回以零除法的值。
22015	間隔欄位溢位	從確切的數值或間隔 SQL 類型指派給間隔 C 類型會導致前置欄位中的有效位數遺失。將數據傳回至間隔 C 類型時，間隔 C 類型中沒有 SQL 類型的值表示法。
22018	轉換規格的字元值無效	結果集中的字元數據行已傳回至字元 C 緩衝區，而且數據行包含的字元集沒有緩衝區字元集中的表示法。 C 類型是精確或近似數值、日期時間或間隔數據類型;數據行的 SQL 類型是字元數據類型;和數據行中的值不是系結 C 型別的有效常值。
24000	無效的數據指標狀態	（DM）未先呼叫 SQLFetch 或 SQLFetchScroll 來呼叫函式，以將游標放在所需的數據列上。（DM） StatementHandle 處於執行狀態，但沒有結果集與 StatementHandle 相關聯。已呼叫 StatementHandle 和 SQLFetch 或 SQLFetchScroll 上的數據指標，但數據指標位於結果集開頭之前或結果集結尾之後。
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息會描述錯誤及其原因。
HY001	記憶體配置錯誤	驅動程式無法配置支援執行或完成函式所需的記憶體。
HY003	程序類型超出範圍	（DM）自變數 TargetType 不是有效的數據類型，SQL_C_DEFAULT，SQL_ARD_TYPE（在擷取數據行數據時），或SQL_APD_TYPE（如果是擷取參數數據）。（DM）自變數Col_or_Param_Num為 0，而 TargetType 自變數不是固定長度書籤的SQL_C_BOOKMARK或可變長度書籤的SQL_C_VARBOOKMARK。
HY008	作業已取消	已針對 StatementHandle 啟用異步處理。已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle，然後在 StatementHandle 上再次呼叫函式。已呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫 SQLCancel 或 SQLCancelHandle，然後在 StatementHandle 上再次呼叫函式。
HY009	無效的 Null 指標使用	（DM）自變數 TargetValuePtr 是 Null 指標。
HY010	函式順序錯誤	（DM）指定的 StatementHandle 未處於執行狀態。未先呼叫 SQLExecDirect、SQLExecute 或目錄函式，就會呼叫函式。（DM）已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。呼叫 SQLGetData 函式時，這個異步函式仍在執行中。（DM）呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。（DM）已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。（DM） StatementHandle 處於執行狀態，但沒有結果集與 StatementHandle 相關聯。對 SQLExeceute、SQLExecDirect 或 SQLMoreResults 的呼叫傳回SQL_PARAM_DATA_AVAILABLE，但呼叫 SQLGetData，而不是呼叫 SQLParamData。
HY013	記憶體管理錯誤	無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY090	無效的字串或緩衝區長度	（DM）為自變數 BufferLength 指定的值小於 0。針對 Argument BufferLength 指定的值小於 4、Col_or_Param_Num自變數設定為 0，而驅動程式是 ODBC 2.x 驅動程式。
HY109	無效的數據指標位置	數據指標位於已刪除或無法擷取的數據列上（由 SQLSetPos、SQLFetch、SQLFetchScroll 或 SQLBulkOperations 放置。數據指標是正向數據指標，而且數據列集大小大於一個。
HY117	聯機因為未知的交易狀態而暫停。只允許中斷連線和唯讀函式。	（DM）如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。
HYC00	未實作選擇性功能	驅動程式或數據源不支援在 SQLFetchScroll 中使用 SQLGetData 與多個數據列。此描述不適用於在 SQLGetInfo 中傳回 SQL_GETDATA_EXTENSIONS 選項SQL_GD_BLOCK位掩碼的驅動程式。驅動程式或數據源不支援 TargetType 自變數與對應資料行之 SQL 資料類型的組合所指定的轉換。只有當數據行的 SQL 資料類型對應至驅動程式特定的 SQL 資料類型時，才會發生此錯誤。驅動程式僅支援 ODBC 2.x，而 TargetType 自變數是下列其中一項： SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT 和附錄 D：數據類型中 C 數據類型中列出的任何間隔 C 數據類型。驅動程式僅支援 3.50 之前的 ODBC 版本，而且 targetType 自變數SQL_C_GUID。
HYT01	已超過連線逾時	在數據源回應要求之前，連線逾時期限已過期。線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001	驅動程式不支援此函式	（DM）對應至 StatementHandle 的驅動程式不支援函式。
IM017	在異步通知模式中停用輪詢	每當使用通知模型時，輪詢就會停用。
IM018	尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。	如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式，則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。

註解

SQLGetData 會傳回指定數據行中的數據。 只有在 SQLFetch、SQLFetchScroll 或 SQLExtendedFetch 從結果集擷取一或多個數據列之後，才能呼叫 SQLGetData。如果可變長度的數據太大而無法以單一呼叫 SQLGetData 傳回（由於應用程式中的限制），SQLGetData 可以在元件中擷取。您可以系結數據列中的某些數據行，並針對其他數據行呼叫 SQLGetData ，不過這受限於某些限制。如需詳細資訊，請參閱取得長數據。

如需搭配串流輸出參數使用 SQLGetData 的詳細資訊，請參閱使用 SQLGetData 擷取輸出參數。

使用 SQLGetData

如果驅動程式不支援 SQLGetData 的擴充功能，則此函式只能針對大於最後一個系結數據行數目的未系結數據行傳回數據。此外，在數據列中，每個 SQLGetData 呼叫中Col_or_Param_Num自變數的值必須大於或等於上一個呼叫中Col_or_Param_Num的值;也就是說，數據必須以遞增的數據行號順序擷取。最後，如果不支援任何延伸模組，如果數據列集大小大於 1， 則無法呼叫 SQLGetData 。

驅動程式可以放寬這些限制。若要判斷驅動程式放寬哪些限制，應用程式會使用下列任一SQL_GETDATA_EXTENSIONS選項來呼叫 SQLGetInfo ：

SQL_GD_OUTPUT_PARAMS = SQLGetData 可以呼叫以傳回輸出參數值。如需詳細資訊，請參閱使用 SQLGetData 擷取輸出參數。
SQL_GD_ANY_COLUMN。如果傳回此選項， 可以針對任何未系結的數據行呼叫 SQLGetData ，包括最後一個系結數據行之前的數據行。
SQL_GD_ANY_ORDER。如果傳回這個選項， 可以依任何順序針對未系結的數據行呼叫 SQLGetData 。
SQL_GD_BLOCK。如果 sqlGetInfo 針對 SQL_GETDATA_EXTENSIONS InfoType 傳回這個選項，則驅動程式支援在數據列集大小大於 1 時呼叫 SQLGetData，而且應用程式可以使用 SQL_POSITION 選項呼叫 SQLSetPos，以在呼叫 SQLGetData 之前，將游標放在正確的數據列上。
SQL_GD_BOUND。如果傳回此選項， 可以針對系結數據行以及未系結的數據行呼叫 SQLGetData 。

這些限制有兩個例外，以及驅動程式放寬這些限制的能力。首先， 當數據列集大小大於 1 時，不應該針對正向數據指標呼叫 SQLGetData 。其次，如果驅動程式支援書籤，它必須一律支援呼叫 數據行 0 的 SQLGetData 的能力，即使它不允許應用程式在最後一個系結數據行之前呼叫 其他數據行的 SQLGetData 。（當應用程式使用 ODBC 2*.x* 驅動程式時， 在呼叫 SQLFetch 之後，SQLGetData 會在呼叫 Col_or_Param_Num 等於 0 時成功傳回書籤，因為 SQLFetch 是由 ODBC 3*.x* 驅動程式管理員對應至具有 fetchOrientation SQL_FETCH_NEXT 的 SQLExtendedFetch，而具有 Col_or_Param_Num 0 的 SQLGetData 則由 ODBC 3*.x* 驅動程式管理員對應至具有 fOption SQL_GET_BOOKMARK 的 SQLGetStmtOption。

SQLGetData 無法用來擷取剛插入的數據列書籤，方法是使用 SQL_ADD 選項呼叫 SQLBulkOperations ，因為數據指標不在數據列上。應用程式可以藉由系結數據行 0 來擷取這類數據列的書籤，然後再使用 SQL_ADD 呼叫 SQLBulkOperations ，在此情況下 ，SQLBulkOperations 會傳回系結緩衝區中的書籤。 然後可以使用 SQL_FETCH_BOOKMARK 呼叫 SQLFetchScroll ，以重新置放該資料列上的游標。

如果 TargetType 自變數是間隔數據類型，則會分別針對數據使用SQL_DESC_DATETIME_INTERVAL_PRECISION和SQL_DESC_PRECISION欄位所設定的預設間隔前置精確度（2）和預設間隔秒有效位數（6）。 如果 TargetType 自變數是SQL_C_NUMERIC數據類型，則會針對數據使用SQL_DESC_PRECISION和SQL_DESC_SCALE欄位所設定的預設有效位數（驅動程式定義）和預設小數位數（0）。如果有任何預設有效位數或小數位數不合適，應用程式應該藉由呼叫 SQLSetDescField 或 SQLSetDescRec 明確設定適當的描述元欄位。它可以將 [SQL_DESC_CONCISE_TYPE] 字段設定為 SQL_C_NUMERIC，並使用 targetType 自變數SQL_ARD_TYPE呼叫 SQLGetData，這會導致使用描述元字段中的有效位數和小數位數值。

注意

在 ODBC 2*.x*中，應用程式將 TargetType 設定為 SQL_C_DATE、SQL_C_TIME 或 SQL_C_TIMESTAMP，表示 *TargetValuePtr 是日期、時間或時間戳結構。在 ODBC 3*.x*中，應用程式將 TargetType 設定為 SQL_C_TYPE_DATE、SQL_C_TYPE_TIME 或 SQL_C_TYPE_TIMESTAMP。驅動程式管理員會視需要根據應用程式和驅動程式版本進行適當的對應。

擷取元件中的可變長度數據

SQLGetData 可用來從元件中包含可變長度數據的數據行擷取數據，也就是說，當數據行的 SQL 數據類型標識碼為SQL_CHAR、SQL_VARCHAR、SQL_LONGVARCHAR、SQL_WCHAR、SQL_WVARCHAR、SQL_WLONGVARCHAR、SQL_BINARY、SQL_VARBINARY、SQL_LONGVARBINARY或變數長度類型的驅動程式特定標識符時。

若要從部分數據行擷取數據，應用程式 會連續呼叫SQLGetData ，以連續呼叫相同數據行。每次呼叫時， SQLGetData 都會傳回數據的下一個部分。應用程式必須重新組合元件，並小心從字元數據的中繼部分移除 Null 終止字元。如果已為終止字元配置更多數據或沒有足夠的緩衝區， SQLGetData 會傳回SQL_SUCCESS_WITH_INFO和 SQLSTATE 01004 （數據截斷）。當它傳回數據的最後一個部分時， SQLGetData 會傳回SQL_SUCCESS。在最後一次有效的呼叫中，無法傳回SQL_NO_TOTAL或零，以便從數據行擷取數據，因為應用程式接著無法知道應用程式緩衝區中的數據有多少有效。如果 在此之後呼叫 SQLGetData ，則會傳回SQL_NO_DATA。如需詳細資訊，請參閱下一節<使用 SQLGetData 擷取數據>。

SQLGetData 可以在元件中傳回可變長度書籤。如同其他數據，呼叫 SQLGetData 以傳回元件中的可變長度書籤，將會傳回 SQLSTATE 01004 （字串數據，右截斷），並在傳回更多數據時傳回SQL_SUCCESS_WITH_INFO。這與呼叫 SQLFetch 或 SQLFetchScroll 截斷可變長度書籤的情況不同，這會傳回 SQL_ERROR 和 SQLSTATE 22001 （字串數據，右截斷）。

SQLGetData 無法用來傳回部分的固定長度數據。如果 包含固定長度數據的數據行在數據列中呼叫多個 SQLGetData ，則會針對第一次之後的所有呼叫傳回SQL_NO_DATA。

擷取串流輸出參數

如果驅動程序支援串流輸出參數，應用程式可以使用小型緩衝區多次呼叫 SQLGetData ，以擷取大型參數值。如需串流輸出參數的詳細資訊，請參閱使用 SQLGetData 擷取輸出參數。

使用 SQLGetData 擷取數據

若要傳回指定資料行的數據， SQLGetData 會執行下列步驟順序：

如果已經傳回數據行的所有數據，則傳回SQL_NO_DATA。
如果數據為 NULL，則會將 *StrLen_or_IndPtr 設定為SQL_NULL_DATA。如果數據為 NULL，且 StrLen_or_IndPtr為 Null 指標， SQLGetData 會傳回 SQLSTATE 22002（需要指標變數但未提供）。

如果數據行的數據不是 NULL，SQLGetData 會繼續進行步驟 3。
如果SQL_ATTR_MAX_LENGTH語句屬性設定為非零值，如果數據行包含字元或二進位數據，而且先前 尚未針對數據行呼叫 SQLGetData ，則數據會截斷為SQL_ATTR_MAX_LENGTH個字節。

注意

SQL_ATTR_MAX_LENGTH 語句屬性的目的是減少網路流量。它通常是由數據源實作，它會在透過網路傳回數據之前截斷數據。驅動程式和數據源不需要支援它。因此，為了保證數據被截斷為特定大小，應用程式應該配置該大小的緩衝區，並在 BufferLength 自變數中指定大小。
將數據轉換成 TargetType 中指定的類型。數據會提供該數據類型的預設有效位數和小數字數。如果 TargetType 是SQL_ARD_TYPE，則會使用 ARD SQL_DESC_CONCISE_TYPE 欄位中的數據類型。如果 TargetType 是SQL_ARD_TYPE，則數據會根據SQL_DESC_CONCISE_TYPE欄位中的數據類型，在 ARD 的SQL_DESC_DATETIME_INTERVAL_PRECISION、SQL_DESC_PRECISION和SQL_DESC_SCALE欄位中提供有效位數和小數位數。如果有任何預設有效位數或小數位數不合適，應用程式應該藉由呼叫 SQLSetDescField 或 SQLSetDescRec 明確設定適當的描述元欄位。
如果數據轉換成可變長度數據類型，例如字元或二進位 ，SQLGetData 會檢查數據的長度是否超過 BufferLength。如果字元數據長度（包括 Null 終止字元）超過 BufferLength，SQLGetData 會將數據截斷為 BufferLength，減少 Null 終止字元的長度。然後，它會以 Null 結束數據。如果二進位數據的長度超過數據緩衝區的長度， SQLGetData 會將它截斷為 BufferLength 位元組。

如果提供的數據緩衝區太小而無法保存 null 終止字元， SQLGetData 會傳回SQL_SUCCESS_WITH_INFO和 SQLSTATE 01004。

SQLGetData 永遠不會截斷轉換成固定長度數據類型的數據;它一律假設 *TargetValuePtr 的長度是數據類型的大小。
將已轉換的（且可能截斷）數據放在 *TargetValuePtr 中。請注意， SQLGetData 無法從行傳回數據。
將數據的長度置於 *StrLen_or_IndPtr。如果 StrLen_or_IndPtr 為 Null 指標， SQLGetData 不會傳回長度。
- 針對字元或二進位數據，這是轉換之後和因 BufferLength 而截斷之前的數據長度。如果驅動程式在轉換后無法判斷數據的長度，就如同使用長數據的情況一樣，它會傳回SQL_SUCCESS_WITH_INFO，並將長度設定為SQL_NO_TOTAL。（最後一次呼叫 SQLGetData 必須一律傳回數據的長度，而不是零或SQL_NO_TOTAL。如果因為 SQL_ATTR_MAX_LENGTH 語句屬性而截斷數據，則此屬性的值會放在 *StrLen_or_IndPtr 中。這是因為此屬性的設計目的是在轉換之前截斷伺服器上的數據，因此驅動程式無法找出實際長度。當 相同數據行連續呼叫 SQLGetData 多次時，這是目前呼叫開始時可用的數據長度;也就是說，每次後續呼叫都會減少長度。
- 對於所有其他數據類型，這是轉換后的數據長度;也就是說，它是數據轉換的目標類型大小。
如果數據在轉換期間不會遺失重要性（例如，當轉換成整數 1 時截斷實際數位 1.234），或因為 BufferLength 太小（例如，字元串 “abcdef” 放在 4 位元節緩衝區中）， SQLGetData 會傳回 SQLSTATE 01004 （數據截斷）和SQL_SUCCESS_WITH_INFO。如果因為SQL_ATTR_MAX_LENGTH語句屬性而未遺失重要性的數據， SQLGetData 會傳回SQL_SUCCESS，而且不會傳回 SQLSTATE 01004 （數據截斷）。

系結數據緩衝區的內容（如果系結數據行上呼叫 SQLGetData），而且如果 SQLGetData 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，則長度/指標緩衝區未定義。

對 SQLGetData 的後續呼叫會從要求的最後一個數據行擷取數據;先前的位移會變成無效。例如，執行下列順序時：

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

第二次呼叫 SQLGetData（icol=n）會從 n 數據行的開頭擷取數據。數據中的任何位移，因為先前呼叫 數據行的 SQLGetData 已不再有效。

描述項和 SQLGetData

SQLGetData 不會直接與任何描述元欄位互動。

如果 TargetType 是SQL_ARD_TYPE，則會使用 ARD SQL_DESC_CONCISE_TYPE 欄位中的數據類型。如果 TargetType 是SQL_ARD_TYPE或SQL_C_DEFAULT，則數據會根據SQL_DESC_CONCISE_TYPE欄位中的數據類型，在 ARD 的SQL_DESC_DATETIME_INTERVAL_PRECISION、SQL_DESC_PRECISION和SQL_DESC_SCALE欄位中提供有效位數和小數位數。

程式碼範例

在下列範例中，應用程式會 執行 SELECT 語句，以傳回依名稱、標識碼和電話號碼排序的客戶標識碼、名稱和電話號碼結果集。針對每個數據列，它會呼叫 SQLFetch ，將游標定位到下一個數據列。它會呼叫 SQLGetData 來擷取擷取的數據;數據的緩衝區和傳回的位元組數目是在呼叫 SQLGetData 時指定。最後，它會列印每個員工的名稱、標識碼和電話號碼。

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

如需下列資訊	請參閱
為結果集中的數據行指派記憶體	SQLBindCol
執行與區塊數據指標位置無關的大量作業	SQLBulkOperations
取消語句處理	SQLCancel
執行 SQL 語句	SQLExecDirect
執行備妥的 SQL 語句	SQLExecute
擷取數據區塊或捲動結果集	SQLFetchScroll
以正向方向擷取單一數據列或數據區塊	SQLFetch
在運行時間傳送參數數據	SQLPutData
放置數據指標、重新整理數據列集中的數據，或更新或刪除數據列集中的數據	SQLSetPos

另請參閱

ODBC API 參考
 ODBC 標頭檔
 使用 SQLGetData 擷取輸出參數

共用方式為

SQLGetData 函式

語法

引數

傳回

診斷

註解

使用 SQLGetData

擷取元件中的可變長度數據

擷取串流輸出參數

使用 SQLGetData 擷取數據

描述項和 SQLGetData

程式碼範例

另請參閱

意見反應

其他資源

共用方式為

SQLGetData 函式

語法

引數

傳回

診斷

註解

使用 SQLGetData

擷取元件中的可變長度數據

擷取串流輸出參數

使用 SQLGetData 擷取數據

描述項和 SQLGetData

程式碼範例

相關函數

另請參閱

意見反應

其他資源