符合性
引進版本：ODBC 1.0 標準合規性：ISO 92
總結
SQLDescribeCol 會回傳結果描述符——欄位名稱、類型、欄位大小、十進位數字及空值——針對結果集中的一欄。 這些資訊也可在IRD領域取得。
Syntax
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
論點
StatementHandle
[輸入]語句句柄。
欄位編號
[輸入]結果資料的欄位數，依欄位遞增順序排列，從1開始。
ColumnNumber 參數也可以設為 0，以描述書籤欄位。
ColumnName
[輸出]指標指向一個空終端緩衝區，回傳欄位名稱。 此數值是從IRD的SQL_DESC_NAME欄位讀取的。 若欄位未命名或無法確定欄位名稱，驅動程式會回傳空字串。
若 ColumnName 為 NULL，NameLengthPtr 仍會回傳 ColumnName 指向緩衝區中可返回的字元總數（不含字元資料的空終止字元）。
BufferLength
[輸入]*ColumnName 緩衝區的長度，以字元為單位。
NameLengthPtr
[輸出]指標指向一個緩衝區，回傳*ColumnName中可返回的字元總數（不含空終止符）。 若可回傳的字元數大於或等於 BufferLength，則 *ColumnName 中的欄位名稱會截斷為 BufferLength 減去一個空終止字元的長度。
DataTypePtr
[輸出]指標指向緩衝區，回傳欄位的 SQL 資料型別。 此數值是從IRD的SQL_DESC_CONCISE_TYPE欄位讀取的。 這會是 SQL 資料型別中的一個值，或是驅動程式專屬的 SQL 資料型別。 若無法確定資料型態，驅動程式會回傳 SQL_UNKNOWN_TYPE。
在ODBC 3。x、SQL_TYPE_DATE、SQL_TYPE_TIME 或 SQL_TYPE_TIMESTAMP 分別在 *DataTypePtr 中回傳日期、時間或時間戳資料;在ODBC 2中。x、SQL_DATE、SQL_TIME或SQL_TIMESTAMP會被回傳。 驅動程式管理員會在 ODBC 2 時執行必要的對應。x 應用程式正在使用 ODBC 3。x 驅動程式或 ODBC 3 時。x 應用程式正在使用 ODBC 2。x 驅動程式。
當 ColumnNumber 等於 0 （針對書籤數據行），SQL_BINARY在 *DataTypePtr 中傳回可變長度書籤。 如果 ODBC 3 使用書籤，則會傳回SQL_INTEGER。x 應用程式使用 ODBC 2。x 驅動程式或 ODBC 2。x 應用程式使用 ODBC 3。x driver.）
欲了解更多資料型態資訊，請參閱附錄D中的 SQL資料型別 ：資料型別。 如需驅動程式特定SQL數據類型的相關信息，請參閱驅動程序的檔。
欄位大小
[輸出]指標指向緩衝區，回傳資料來源欄位的大小（以字元為單位）。 若無法確定欄位大小，驅動程式回傳 0。 如需數據行大小的詳細資訊，請參閱 附錄 D：數據類型中的數據行大小、十進位數、傳輸八位長度和顯示大小 。
DecimalDigitsPtr
[輸出]指標指向一個緩衝區，回傳資料來源欄位的小數位數。 若無法確定小數點數或不適用，驅動程式回傳 0。 欲了解更多關於十進位數字的資訊，請參閱附錄D：資料型態中的 欄位大小、十進位數字、傳輸八重奏長度及顯示大小 。
NullablePtr
[輸出]指標指向緩衝區，回傳一個值，指示欄位是否允許 NULL 值。 此數值是從IRD的SQL_DESC_NULLABLE欄位讀取的。 其值為下列其中之一：
SQL_NO_NULLS：欄位不允許 NULL 值。
SQL_NULLABLE：欄位允許 NULL 值。
SQL_NULLABLE_UNKNOWN：驅動程式無法判斷欄位是否允許 NULL 值。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
當 SQLDescribeCol 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可透過呼叫 SQLGetDiagRec 取得對應的 SQLSTATE 值，並將 HandleType 設為 SQL_HANDLE_STMT，Handle 為 StatementHandle 。 下表列出 SQLDescribeCol 常回傳的 SQLSTATE 值，並在此函式情境下說明每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 說明 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串數據，右截斷 | 緩衝區 *ColumnName 不夠大，無法回傳整個欄位名稱，因此欄位名稱被截斷。 未截斷欄位名稱的長度會以 *NameLengthPtr 格式回傳。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 07005 | 預備陳述，而非 游標規格 | 與 StatementHandle 相關的敘述並未回傳結果集。 沒有欄位可供描述。 |
| 07009 | 無效描述子索引 | （DM） 參數 ColumnNumber 指定的值為 0，SQL_ATTR_USE_BOOKMARKS 陳述選項為 SQL_UB_OFF。 參數 ColumnNumber 所指定的值大於結果集的欄位數。 |
| 08S01 | 通訊連結故障 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| HY000 | 一般誤差 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置失效 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 行動取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 當呼叫 SQLDescribeCol 時，這個非同步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 該函式是在呼叫 SQLPrepare、 SQLExecute 或對該語句柄的目錄函式之前被呼叫的。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 無效的字串或緩衝區長度 | （DM） 為自變數 BufferLength 指定的值小於 0。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYT01 | 連線已逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
SQLDescribeCol 可回傳任何 SQLPrepare 或 SQLExecute 可回傳的 SQLSTATE，前提是 SQLPrepare 在 SQLPrepare 之後或 SQLExecute 之前，視資料來源何時評估與該陳述句柄相關的 SQL 陳述式而定。
出於效能考量，應用程式不應在執行語句前呼叫 SQLDescribeCol 。
評論
應用程式通常在呼叫 SQLPrepare 後，且在呼叫 SQLExecute 前後呼叫 SQLDescribeCol。 應用程式也可以在呼叫 SQLExecDirect 後呼叫 SQLDescribeCol。 如需詳細資訊，請參閱結果集中繼資料。
SQLDescribeCol 會取得由 SELECT 語句產生的欄位名稱、型別與長度。 若欄位為表達式，*ColumnName 則為空字串或驅動程式定義名稱。
Note
ODBC 支援 SQL_NULLABLE_UNKNOWN 作為擴充功能，儘管 Open Group 與 SQL 存取群組呼叫層介面規範並未指定 SQLDescribeCol 的選項。
相關函數
| 如需相關信息 | 看！ |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol |
| 取消語句處理 | SQLCancel |
| 傳回結果集中數據行的相關信息 | SQLColAttribute |
| 擷取多個數據列 | SQLFetch |
| 回傳結果集欄位數 | SQLNumResultCols |
| 準備語句以供執行 | SQLPrepare |