SQLNumResultCols 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLNumResultCols 會傳回結果集中的數據行數目。
語法
SQLRETURN SQLNumResultCols(
SQLHSTMT StatementHandle,
SQLSMALLINT * ColumnCountPtr);
引數
StatementHandle
[輸入]語句句柄。
ColumnCountPtr
[輸出]要在其中傳回結果集中數據行數目的緩衝區指標。 此計數不包含系結書籤數據行。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLNumResultCols 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄來取得相關聯的 SQLSTATE 值。 下表列出 SQLNumResultCols 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle;然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLNumResultsCols 函式時，這個異步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 （DM） 在呼叫 StatementHandle 的 SQLPrepare 或 SQLExecDirect 之前呼叫函式。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 如需何時可以釋放語句句柄的詳細資訊，請參閱 SQLPrepare 函 式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
SQLNumResultCols 可以傳回 SQLPrepare 或 SQLExecute 在 SQLPrepare 之後呼叫，以及在 SQLExecute 之前傳回的任何 SQLSTATE，視數據源評估與語句相關聯的 SQL 語句而定。
註解
只有在語句處於備妥、執行或定位狀態時，才能成功呼叫 SQLNumResultCols 。
如果與 StatementHandle 相關聯的語句未傳回數據行， SQLNumResultCols 會將 *ColumnCountPtr 設定為 0。
SQLNumResultCols 傳回的數據行數目與 IRD SQL_DESC_COUNT 字段的值相同。
如需詳細資訊，請參閱 結果集是否已建立？ 和 元數據的使用方式？。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回結果集中數據行的相關信息 | SQLColAttribute 函式 |
| 傳回結果集中數據行的相關信息 | SQLDescribeCol 函式 |
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 以正向方向擷取單一數據列或數據區塊 | SQLFetch 函式 |
| 擷取部分或所有數據行的數據 | SQLGetData 函式 |
| 準備 SQL 語句以執行 | SQLPrepare 函式 |
| 設定游標卷動選項 | SQLSetStmtAttr 函式 |