SQLGetData 函式
一致性
引進版本：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 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應