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 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT 和 Handle 为 StatementHandle。 下表列出了 SQLNumResultCols 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
08S01 通信链接失败 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle; 然后，在 StatementHandle 上再次调用 函数。

函数已调用，在它完成执行之前， SQLCancel 或 SQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。
HY010 函数序列错误 (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLNumResultsCols 函数时，此异步函数仍在执行。

(DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。

(DM) 在调用 StatementHandle的 SQLPrepare 或 SQLExecDirect 之前调用了函数。

(DM) 为 StatementHandle 调用了异步执行的函数 (不是此函数) ，并且调用此函数时仍在执行。

(DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回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 之前调用时可由 SQLPrepare 或 SQLExecute 返回的任何 SQLSTATE，具体取决于数据源评估与语句关联的 SQL 语句的时间。

注释

仅当语句处于准备、已执行或定位状态时，才能成功调用 SQLNumResultCols。

如果与 StatementHandle 关联的语句不返回列， SQLNumResultCols 会将 *ColumnCountPtr 设置为 0。

SQLNumResultCols 返回的列数与 IRD SQL_DESC_COUNT 字段的值相同。

有关详细信息，请参阅 是否创建了结果集？ 和 如何使用元数据？。

有关以下方面的信息 请参阅
将缓冲区绑定到结果集中的列 SQLBindCol 函数
取消语句处理 SQLCancel 函数
返回有关结果集中列的信息 SQLColAttribute 函数
返回有关结果集中列的信息 SQLDescribeCol 函数
执行 SQL 语句 SQLExecDirect 函数
执行准备好的 SQL 语句 SQLExecute 函数
提取数据块或滚动浏览结果集 SQLFetchScroll Function（SQLFetchScroll 函数）
以仅向前方向提取单个行或数据块 SQLFetch 函数
提取部分或全部数据列 SQLGetData 函数
准备要执行的 SQL 语句 SQLPrepare 函数
设置光标滚动选项 SQLSetStmtAttr 函数

另请参阅

ODBC API 参考
ODBC 头文件