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。

註解

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，這會導致使用描述元字段中的有效位數和小數位數值。

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

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 會執行下列步驟順序：

1. 如果已經傳回數據行的所有數據，則傳回SQL_NO_DATA。

2. 如果數據為 NULL，則會將 *StrLen_or_IndPtr 設定為SQL_NULL_DATA。 如果數據為 NULL， 且 StrLen_or_IndPtr為 Null 指標， SQLGetData 會傳回 SQLSTATE 22002（需要指標變數但未提供）。

   如果數據行的數據不是 NULL，SQLGetData 會繼續進行步驟 3。

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

   注意

   SQL_ATTR_MAX_LENGTH 語句屬性的目的是減少網路流量。 它通常是由數據源實作，它會在透過網路傳回數據之前截斷數據。 驅動程式和數據源不需要支援它。 因此，為了保證數據被截斷為特定大小，應用程式應該配置該大小的緩衝區，並在 BufferLength 自變數中指定大小。

4. 將數據轉換成 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 明確設定適當的描述元欄位。

5. 如果數據轉換成可變長度數據類型，例如字元或二進位 ，SQLGetData 會檢查數據的長度是否超過 BufferLength。 如果字元數據長度（包括 Null 終止字元）超過 BufferLength，SQLGetData 會將數據截斷為 BufferLength，減少 Null 終止字元的長度。 然後，它會以 Null 結束數據。 如果二進位數據的長度超過數據緩衝區的長度， SQLGetData 會將它截斷為 BufferLength 位元組。

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

   SQLGetData 永遠不會截斷轉換成固定長度數據類型的數據;它一律假設 *TargetValuePtr 的長度是數據類型的大小。

6. 將已轉換的（且可能截斷）數據放在 *TargetValuePtr 中。 請注意， SQLGetData 無法從行傳回數據。

7. 將數據的長度置於 *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 多次時，這是目前呼叫開始時可用的數據長度;也就是說，每次後續呼叫都會減少長度。

   • 對於所有其他數據類型，這是轉換后的數據長度;也就是說，它是數據轉換的目標類型大小。

8. 如果數據在轉換期間不會遺失重要性（例如，當轉換成整數 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;  
      }  
   }  
}  

相關函數

另請參閱

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