SQLGetDescField 函式

  • 發行項

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

摘要
SQLGetDescField 會傳回描述元記錄之單一欄位的目前設定或值。

語法

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

引數

DescriptorHandle
[輸入]描述項控制碼。

RecNumber
[輸入]指出應用程式從中搜尋資訊的描述元記錄。 描述項記錄是從 0 編號，記錄號碼 0 是書簽記錄。 如果 FieldIdentifier 引數指出標頭欄位， 則會忽略 RecNumber 。 如果 RecNumber 小於或等於SQL_DESC_COUNT但資料列不包含資料行或參數的資料，則對 SQLGetDescField 的呼叫 會傳回欄位的預設值。 （如需詳細資訊，請參閱 中的。 SQLSetDescField .）

FieldIdentifier
[輸入]指出要傳回其值之描述元的欄位。 如需詳細資訊，請參閱 SQLSetDescField 中的 < FieldIdentifier 引數>一節。

ValuePtr
[輸出]要在其中傳回描述項資訊的緩衝區指標。 資料類型取決於 FieldIdentifier 的值 。

如果 ValuePtr 是整數類型，應用程式應該使用 SQLULEN 的緩衝區，並將值初始化為 0，然後再呼叫此函式，因為某些驅動程式可能只會寫入較低 32 位或 16 位的緩衝區，並將較高順序位保持不變。

如果 ValuePtr 為 Null， StringLengthPtr 仍會傳回可供 ValuePtr 指向 的緩衝區中傳回的位元組總數（不包括字元資料的 Null 終止字元）。

BufferLength
[輸入]如果 FieldIdentifier 是 ODBC 定義的欄位，而 ValuePtr 指向字元字串或二進位緩衝區，則此引數應該是 * ValuePtr 的長度。 如果 FieldIdentifier 是 ODBC 定義的欄位，而 * ValuePtr 是整數， 則會忽略 BufferLength 。 如果 *ValuePtr 中的 值是 Unicode 資料類型（呼叫 SQLGetDescFieldW 時）， BufferLength 引數必須是偶 數。

如果 FieldIdentifier 是驅動程式定義的欄位，應用程式會藉由設定 BufferLength 引數，將欄位的性質指示給驅動程式管理員。 BufferLength 可以具有下列值：

  • 如果 *ValuePtr 是字元字串的指標， 則 BufferLength 是字串的長度或SQL_NTS。

  • 如果 *ValuePtr 是二進位緩衝區的指標，則應用程式會將SQL_LEN_BINARY_ATTR（ length ） 宏的結果放在 BufferLength 中 。 這會在 BufferLength 中 放置負值。

  • 如果 *ValuePtr 是字元字串或二進位字串以外的值指標，則 BufferLength 的值SQL_IS_POINTER。

  • 如果 *ValuePtr 包含固定長度的資料類型，則 BufferLength 會視需要SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT。

StringLengthPtr
[輸出]緩衝區的指標，這個緩衝區會傳回可在 * ValuePtr 中傳回的位元組總數（不包括 Null 終止字元所需的位元組數目）。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。

如果 RecNumber 大於目前的描述元記錄數目，則會傳回SQL_NO_DATA。

如果 DescriptorHandle 是 IRD 控制碼，而且語句處於已備妥或執行的狀態，但沒有與它相關聯的開啟資料指標，則會傳回SQL_NO_DATA。

診斷

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

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01004 字串資料，右截斷 緩衝區 * ValuePtr 不夠大，無法傳回整個描述元欄位，因此欄位已截斷。 未解構描述元欄位的長度會在 * StringLengthPtr 中 傳回。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
07009 不正確描述元索引 （DM） RecNumber 引數等於 0、SQL_ATTR_USE_BOOKMARK語句屬性SQL_UB_OFF， 而 DescriptorHandle 引數是 IRD 控制碼。 （只有在描述項與語句控制碼相關聯時，才能針對明確配置的描述元傳回此錯誤。

FieldIdentifier 引數是記錄欄位、 RecNumber 引數是 0，而 DescriptorHandle 引數是 IPD 控制碼。

RecNumber 引數小於 0。
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY007 未備妥相關聯的語句 描述項Handle 與 StatementHandle 相關聯為 IRD，且尚未準備或執行相關聯的語句控制碼。
HY010 函式順序錯誤 （DM） 描述項Handle 與 StatementHandle 相關聯，其會呼叫非同步執行函式（而非此函式），而且在呼叫此函式時仍在執行中。

（DM） 描述項Handle 與 SQLExecute、SQLExecute 、 SQLBulkOperations 或 SQLSetPos 呼叫並傳回SQL_NEED_DATA的 StatementHandle 相關聯。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。

（DM） 針對與 DescriptorHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLGetDescField 函式時 ，這個非同步函式仍在執行中。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY021 不一致的描述元資訊 SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE欄位不會形成有效的 ODBC SQL 類型、有效的驅動程式特定 SQL 類型（適用于 IPD），或有效的 ODBC C 類型（適用于 APD 或 ARD）。
HY090 不正確字串或緩衝區長度 （DM） *ValuePtr 是字元字串， BufferLength 小於零。
HY091 不正確描述元欄位識別碼 FieldIdentifier 不是 ODBC 定義的欄位，也不是實作定義的值。

FieldIdentifier 未針對 DescriptorHandle 定義。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 DescriptorHandle 相關聯的 驅動程式不支援 函式。

註解

應用程式可以呼叫 SQLGetDescField 來傳回描述元記錄之單一欄位的值。 呼叫 SQLGetDescField 可以傳回任何描述元類型中任何欄位的設定，包括標頭欄位、記錄欄位和書簽欄位。 應用程式可以藉由對 SQLGetDescField 進行重複呼叫，以任意順序取得相同或不同描述項中多個欄位的設定 。 您也可以呼叫 SQLGetDescField 來傳回驅動程式定義的描述元欄位。

基於效能考慮，應用程式在執行語句之前，不應該呼叫 IRD 的 SQLGetDescField 。

描述資料行或參數資料之名稱、資料類型和儲存之多個欄位的設定，也可以在對 SQLGetDescRec 的單一呼叫 中擷取。 您可以呼叫 SQLGetStmtAttr ，以傳回描述元標頭中也是語句屬性的單一欄位設定。 SQLColAttribute 、 SQLDescribeCol 和 SQLDescribeParam 會傳回記錄或書簽欄位。

當應用程式呼叫 SQLGetDescField 來擷取針對特定描述元類型未定義的域值時，函式會傳回SQL_SUCCESS但未定義欄位傳回的值。 例如，針對 APD 或 ARD 的 SQL_DESC_NAME 或 SQL_DESC_NullABLE 欄位呼叫 SQLGetDescField 會傳回SQL_SUCCESS，但欄位未定義的值。

當應用程式呼叫 SQLGetDescField 來擷取針對特定描述元類型所定義的域值，但尚未設定預設值，函式會傳回SQL_SUCCESS但未定義欄位傳回的值。 如需描述項欄位初始化和欄位描述的詳細資訊，請參閱 SQLSetDescField 中的 。 如需描述項的詳細資訊，請參閱 描述項 。

如需下列資訊 請參閱
取得多個描述元欄位 SQLGetDescRec 函式
設定單一描述元欄位 SQLSetDescField 函式
設定多個描述元欄位 SQLSetDescRec 函式

另請參閱

ODBC API 參考
ODBC 標頭檔