符合性
推出版本：ODBC 3.0 標準合規：ISO 92
總結
SQLGetDescField 回傳描述符記錄中單一欄位的當前設定或值。
Syntax
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
論點
DescriptorHandle
[輸入]描述符的handle。
RecNumber
[輸入]表示應用程式尋找資訊的描述符記錄。 描述符記錄從 0 開始編號，記錄編號 0 為書籤記錄。 如果 FieldIdentifier 參數指示標頭欄位，則忽略 RecNumber 。 若 RecNumber 小於或等於 SQL_DESC_COUNT，但該列未包含欄位或參數的資料，呼叫 SQLGetDescField 將回傳欄位的預設值。 （更多資訊請參見 SQLSetDescField 中的「描述符欄位初始化」。）
FieldIdentifier
[輸入]表示要回傳的描述符欄位。 欲了解更多資訊，請參閱 SQLSetDescField 中的「FieldIdentifier Argument」章節。
ValuePtr
[輸出]指向緩衝區，回傳描述符資訊。 資料型別取決於 FieldIdentifier 的值。
若 ValuePtr 為整數型態，應用程式應使用 SQLULEN 緩衝區，並將值初始化為 0 後再呼叫此函式，因為部分驅動程式可能只寫入緩衝區的低 32 位或 16 位元，而高階位元則保持不變。
若 ValuePtr 為 NULL，StringLengthPtr 仍會回傳 ValuePtr 指向緩衝區中可返回的總位元組數（不含字元資料的空終止字元）。
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 中可用位元組數（不含空終止字元所需的位元組數）。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。
如果 RecNumber 超過目前描述符記錄數量，則會回傳 SQL_NO_DATA。
如果 DescriptorHandle 是 IRD 的 handle 且該語句處於準備或執行狀態，但沒有開啟游標，則會回傳 SQL_NO_DATA。
Diagnostics
當 SQLGetDescField 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可以透過呼叫 SQLGetDiagRec 並設定 HandleType 為 SQL_HANDLE_STMT 和 HandleHandle 來取得相關的 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 | 未備妥相關聯的語句 | DescriptorHandle 被關聯為 IRD ，且該敘述句柄尚未準備或執行。 |
| HY010 | 函式順序錯誤 | （DM） DescriptorHandle 與一個 StatementHandle 相關聯，該 StatementHandle 呼叫了一個非同步執行的函式（非此函式），且在呼叫該函式時仍在執行中。 （DM） DescriptorHandle 與一個 StatementHandle 相關聯，該 StatementHandle 呼叫 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 並回傳SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 （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 定義的欄位，也不是實作定義的值。 DescriptorHandle 的欄位識別碼未定義。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 欲了解更多關於暫停狀態的資訊，請參見 SQLEndTran 函式。 |
| HYT01 | 連線已逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 描述符Handle 相關聯的驅動程式不支援該函式。 |
評論
應用程式可以呼叫 SQLGetDescField 來回傳描述符記錄中單一欄位的值。 呼叫 SQLGetDescField 可回傳任何描述符類型中任意欄位的設定，包括標頭欄位、記錄欄位及書籤欄位。 應用程式可以透過反覆呼叫 SQLGetDescField 來，以任意順序取得相同或不同描述符中多個欄位的設定。 也可以呼叫 SQLGetDescField 來回傳驅動程式定義的描述欄位。
出於效能考量，應用程式不應在執行語句前呼叫 SQLGetDescField 取得 IRD。
描述欄位或參數資料名稱、資料型別及儲存的多個欄位設定，也可在單一呼叫 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 函數 |