SQLNumResultCols 函数SQLNumResultCols Function

Conformance
引入的版本:ODBC 1.0 标准符合性:ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

摘要Summary
SQLNumResultCols返回结果集中的列数。SQLNumResultCols returns the number of columns in a result set.

语法Syntax

  
SQLRETURN SQLNumResultCols(  
     SQLHSTMT        StatementHandle,  
     SQLSMALLINT *   ColumnCountPtr);  

参数Arguments

StatementHandleStatementHandle
送语句句柄。[Input] Statement handle.

ColumnCountPtrColumnCountPtr
输出一个指针, 指向要在其中返回结果集中的列数的缓冲区。[Output] Pointer to a buffer in which to return the number of columns in the result set. 此计数不包括绑定书签列。This count does not include a bound bookmark column.

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLNumResultCols返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时, 可以通过使用SQLGetDiagRec 的 HandleTypeSQL_HANDLE_STMT句柄调用StatementHandle来获取关联的 SQLSTATE 值。When SQLNumResultCols returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常由SQLNumResultCols返回的 SQLSTATE 值, 并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLNumResultCols and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 除非另有说明, 否则与每个 SQLSTATE 值相关联的返回代码为 SQL_ERROR。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
08S0108S01 通信链接失败Communication link failure 在函数完成处理之前, 驱动程序与连接到的数据源之间的通信链接失败。The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
HY000HY000 一般错误General error 发生了一个错误, 该错误没有特定的 SQLSTATE, 没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. MessageText 缓冲区中的 SQLGetDiagRec返回的错误消息描述了错误及其原因。 *The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 驱动程序无法分配支持执行或完成此函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY008HY008 操作已取消Operation canceled 已为StatementHandle启用异步处理。Asynchronous processing was enabled for the StatementHandle. 函数被调用, 在完成执行之前, 在StatementHandle上调用了SQLCancelSQLCancelHandle ;然后, 在StatementHandle上再次调用该函数。The function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle; the function was then called again on the StatementHandle.

函数被调用, 在完成执行之前, 从多线程应用程序中的另一个线程调用StatementHandle上的SQLCancelSQLCancelHandleThe function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle from a different thread in a multithread application.
HY010HY010 函数序列错误Function sequence error (DM) 为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLNumResultsCols函数时, 此异步函数仍在执行。This asynchronous function was still executing when the SQLNumResultsCols function was called.

(DM) 为StatementHandle调用了SQLExecuteSQLExecDirectSQLMoreResults , 并返回了 SQL_PARAM_DATA_AVAILABLE。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 在检索所有流式处理参数的数据之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM) 在为StatementHandle调用SQLPrepareSQLExecDirect之前调用了函数。(DM) The function was called prior to calling SQLPrepare or SQLExecDirect for the StatementHandle.

(DM) 为StatementHandle调用了异步执行的函数 (而不是此函数), 并且在调用此函数时仍在执行。(DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSETPOS调用了StatementHandle并返回了 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前, 将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.

有关如何释放语句句柄的详细信息, 请参阅SQLPrepare 函数See SQLPrepare Function for details on when a statement handle can be freed.
HY013HY013 内存管理错误Memory management error 未能处理函数调用, 原因可能是由于内存不足而无法访问基础内存对象。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY117HY117 由于未知的事务状态, 连接被挂起。Connection is suspended due to unknown transaction state. 仅允许断开连接和只读函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息, 请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYT01HYT01 连接超时已过期Connection timeout expired 连接超时期限在数据源响应请求之前过期。The connection timeout period expired before the data source responded to the request. 连接超时期限通过SQLSetConnectAttr、SQL_ATTR_CONNECTION_TIMEOUT 设置。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此功能Driver does not support this function (DM) 与StatementHandle关联的驱动程序不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.
IM017IM017 在异步通知模式下禁用轮询Polling is disabled in asynchronous notification mode 无论何时使用通知模型, 都将禁用轮询。Whenever the notification model is used, polling is disabled.
IM018IM018 尚未调用SQLCompleteAsync来完成此句柄上先前的异步操作。SQLCompleteAsync has not been called to complete the previous asynchronous operation on this handle. 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING, 并且如果启用了通知模式, 则必须在句柄上调用SQLCompleteAsync , 才能执行后处理并完成操作。If the previous function call on the handle returns SQL_STILL_EXECUTING and if notification mode is enabled, SQLCompleteAsync must be called on the handle to do post-processing and complete the operation.

SQLNumResultCols可以返回SQLPrepareSQLExecuteSQLPrepare之后调用时可以返回的任何SQLSTATE, 具体取决于数据源对 SQL 语句进行计算的时间与语句关联的。SQLNumResultCols can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute, depending on when the data source evaluates the SQL statement associated with the statement.

注释Comments

仅当语句处于准备好的、执行或定位状态时, 才能成功调用SQLNumResultColsSQLNumResultCols can be called successfully only when the statement is in the prepared, executed, or positioned state.

如果与StatementHandle关联的语句未返回列, 则将SQLNumResultCols ColumnCountPtr设置为0。If the statement associated with StatementHandle does not return columns, SQLNumResultCols sets *ColumnCountPtr to 0.

SQLNumResultCols返回的列数与 IRD 的 SQL_DESC_COUNT 字段的值相同。The number of columns returned by SQLNumResultCols is the same value as the SQL_DESC_COUNT field of the IRD.

有关详细信息, 请参阅是否创建了结果集?以及如何使用元数据?For more information, see Was a Result Set Created? and How is Metadata Used?.

有关信息For information about 请参阅See
将缓冲区绑定到结果集中的列Binding a buffer to a column in a result set SQLBindCol 函数SQLBindCol Function
正在取消语句处理Canceling statement processing SQLCancel 函数SQLCancel Function
返回有关结果集中的列的信息Returning information about a column in a result set SQLColAttribute 函数SQLColAttribute Function
返回有关结果集中的列的信息Returning information about a column in a result set SQLDescribeCol 函数SQLDescribeCol Function
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
提取数据块或滚动结果集Fetching a block of data or scrolling through a result set SQLFetchScroll 函数SQLFetchScroll Function
按只进方向提取单个行或数据块Fetching a single row or a block of data in a forward-only direction SQLFetch 函数SQLFetch Function
提取部分或全部数据列Fetching part or all of a column of data SQLGetData 函数SQLGetData Function
准备要执行的 SQL 语句Preparing an SQL statement for execution SQLPrepare 函数SQLPrepare Function
设置游标滚动选项Setting cursor scrolling options SQLSetStmtAttr 函数SQLSetStmtAttr Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files