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 函式

另請參閱

ODBC API 參考
ODBC 標頭檔