SQLDescribeCol 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLDescribeCol 會針對結果集中的一個資料行傳回結果描述元 - 資料行名稱、類型、資料行大小、小數位數和可為 Null。 這項資訊也可以在 IRD 的欄位中取得。
語法
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
引數
StatementHandle
[輸入]語句控制碼。
ColumnNumber
[輸入]從 1 開始，依序排序結果資料的資料行數目，依序排序。 ColumnNumber 引數也可以設定為 0 來描述書簽資料行。
ColumnName
[輸出]要在其中傳回資料行名稱之 Null 終止緩衝區的指標。 此值是從 IRD 的 [SQL_DESC_NAME] 欄位讀取。 如果資料行未命名或無法判斷資料行名稱，驅動程式會傳回空字串。
如果 ColumnName 為 Null， NameLengthPtr 仍會傳回可供 ColumnName 所指向 之緩衝區中傳回的字元總數（不包括字元資料的 Null 終止字元）。
BufferLength
[輸入]* ColumnName 緩衝區的長度，以字元為單位。
NameLengthPtr
[輸出]緩衝區的指標，要在其中傳回可在 * ColumnName 中傳回的字元總數（不包括 Null 終止）。 如果可用傳回的字元數大於或等於 BufferLength ，則 * ColumnName 中的資料行名稱會截斷為 BufferLength 減去 Null 終止字元的長度。
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 資料類型的相關資訊，請參閱驅動程式的檔。
ColumnSizePtr
[輸出]要在其中傳回資料來源上資料行大小（以字元為單位）之緩衝區的指標。 如果無法判斷資料行大小，驅動程式會傳回 0。 如需資料行大小的詳細資訊，請參閱 附錄 D：資料類型中的資料行大小、十進位數、傳輸八位長度和顯示大小 。
DecimalDigitsPtr
[輸出]緩衝區的指標，用來傳回資料來源上資料行的十進位數。 如果無法判斷或不適用十進位數，驅動程式會傳回 0。 如需小數位數的詳細資訊，請參閱 附錄 D：資料類型中的資料行大小、十進位數、傳輸八位長度和顯示大小 。
NullablePtr
[輸出]要在其中傳回值之緩衝區的指標，指出資料行是否允許 Null 值。 此值是從 IRD 的 [SQL_DESC_NullABLE] 欄位讀取。 此值為下列其中一項：
SQL_NO_NullS：資料行不允許 Null 值。
SQL_NullABLE：資料行允許 Null 值。
SQL_NullABLE_UNKNOWN：驅動程式無法判斷資料行是否允許 Null 值。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLDescribeCol 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以呼叫 具有 SQL_HANDLE_STMT HandleType 和 StatementHandle Handle 的 HandleType 來取得相關聯的 SQLSTATE 值。 下表列出 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 或 catalog 函式之前 呼叫函式。 （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 在 SQLPrepare 之後 呼叫，以及在 SQLExecute 之前 呼叫的任何 SQLSTATE，視資料來源評估與語句控制碼相關聯的 SQL 語句而定。
基於效能考慮，應用程式在執行語句之前，不應該呼叫 SQLDescribeCol 。
註解
應用程式通常會在 呼叫 SQLPrepare 之後，以及在 SQLExecute 相關聯呼叫之前或之後呼叫 SQLDescribeCol 。 應用程式也可以在呼叫 SQLExecDirect 之後呼叫 SQLDescribeCol 。 如需詳細資訊，請參閱結果集中繼資料。
SQLDescribeCol 會擷取 SELECT 語句所產生的 資料行名稱、類型和長度。 如果資料行是運算式，* ColumnName 是空字串或驅動程式定義的名稱。
注意
即使開放式群組和 SQL 存取群組呼叫層級介面規格未指定 SQLDescribeCol 的選項 ，ODBC 仍支援SQL_NullABLE_UNKNOWN做為延伸模組。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol |
| 取消語句處理 | SQLCancel |
| 傳回結果集中資料行的相關資訊 | SQLColAttribute |
| 擷取多個資料列 | SQLFetch |
| 傳回結果集資料行的數目 | SQLNumResultCols |
| 準備語句以供執行 | SQLPrepare |