SQLMoreResults 函数

  • 项目

一致性
引入的版本：ODBC 1.0 标准符合性：ODBC

摘要
SQLMoreResults 确定包含 SELECT、 UPDATE、 INSERT 或 DELETE 语句的语句上是否有更多结果可用，如果是，则初始化这些结果的处理。

语法

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

参数

StatementHandle
[输入]语句句柄。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE或SQL_PARAM_DATA_AVAILABLE。

诊断

当 SQLMoreResults 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT， 句柄 为 StatementHandle。 下表列出了 SQLMoreResults 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 描述
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01S02 选项值已更改 语句属性的值随着批处理的处理而更改。 (函数返回 SQL_SUCCESS_WITH_INFO.)
08S01 通信链接失败 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。
40001 序列化失败 由于与另一个事务发生资源死锁，事务已回滚。
40003 语句完成未知 关联的连接在执行此函数期间失败，无法确定事务的状态。
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 已为 StatementHandle 启用异步处理。 调用了 SQLMoreResults 函数，在完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用 SQLMoreResults 函数。

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

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

(DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。
HY013 内存管理错误 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。
HY117 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01 超过连接超时时间 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。
IM001 驱动程序不支持此函数 (DM) 与 StatementHandle 关联的驱动程序不支持 函数。
IM017 在异步通知模式下禁用轮询 每当使用通知模型时，轮询都将被禁用。
IM018 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。

注释

SELECT 语句返回结果集。 UPDATE、 INSERT 和 DELETE 语句返回受影响的行计数。 如果这些语句中的任何一个是批处理的、与参数数组一起提交的， (按参数递增顺序进行编号，按照它们在批处理) 或过程中出现的顺序进行编号，则可以返回多个结果集或行计数。 有关语句批处理和参数数组的信息，请参阅 SQL 语句批处理 和 参数值数组。

执行批处理后，应用程序定位在第一个结果集上。 应用程序可以在第一个或任何后续结果集上调用 SQLBindCol、 SQLBulkOperations、 SQLFetch、 SQLGetData、 SQLFetchScroll、 SQLSetPos 和所有元数据函数，就像只有单个结果集时一样。 完成第一个结果集后，应用程序将调用 SQLMoreResults 以移动到下一个结果集。 如果其他结果集或计数可用， SQLMoreResults 将返回SQL_SUCCESS并初始化结果集或计数以供其他处理。 如果结果集生成语句之间出现任何行计数生成语句，可以通过调用 SQLMoreResults 来逐行执行这些语句。为 UPDATE、INSERT 或 DELETE 语句调用 SQLMoreResults 后，应用程序可以调用 SQLRowCount。

如果当前结果集包含未提取的行， SQLMoreResults 将放弃该结果集，并使下一个结果集或计数可用。 如果已处理所有结果， SQLMoreResults 将返回SQL_NO_DATA。 对于某些驱动程序，输出参数和返回值在处理完所有结果集和行计数之前不可用。 对于此类驱动程序，当 SQLMoreResults 返回SQL_NO_DATA时，输出参数和返回值将变为可用。

为上一个结果集建立的任何绑定仍然有效。 如果此结果集的列结构不同，则调用 SQLFetch 或 SQLFetchScroll 可能会导致错误或截断。 为防止出现这种情况，应用程序必须调用 SQLBindCol 以根据需要显式重新绑定 (或通过) 设置描述符字段来执行此操作。 或者，应用程序可以使用 Option SQL_UNBIND 调用 SQLFreeStmt 来取消绑定所有列缓冲区。

语句属性的值（如游标类型、游标并发性、键集大小或最大长度）可能会随着应用程序通过调用 SQLMoreResults 在批处理中导航而更改。 如果发生这种情况， SQLMoreResults 将返回SQL_SUCCESS_WITH_INFO，并且 SQLSTATE 01S02 (Option 值已更改) 。

调用 SQLCloseCursor 或 SQLFreeStmt 且 选项 为 SQL_CLOSE，会放弃执行批处理后可用的所有结果集和行计数。 语句句柄返回已分配或准备状态。 如果已执行批处理并且语句句柄处于已执行、游标定位或异步状态，则调用 SQLCancel 来取消异步执行函数，如果取消调用成功，则会丢弃该批处理生成的所有结果集和行计数。 然后，语句将返回到已准备或已分配的状态。

如果一批语句或过程将其他 SQL 语句与 SELECT、 UPDATE、 INSERT 和 DELETE 语句混合使用，则这些其他语句不会影响 SQLMoreResults。

有关详细信息，请参阅 多个结果。

如果一批语句中搜索的更新、插入或删除语句不会影响数据源中的任何行， SQLMoreResults 将返回SQL_SUCCESS。 这不同于通过 SQLExecDirect、 SQLExecute 或 SQLParamData 执行的搜索更新、插入或删除语句的情况，如果它不会影响数据源中的任何行，则返回SQL_NO_DATA。 如果应用程序在调用 SQLMoreResults 后调用 SQLRowCount 来检索行计数，则 SQLRowCount 将返回SQL_NO_DATA。

有关结果处理函数的有效排序的其他信息，请参阅 附录 B：ODBC 状态转换表。

有关SQL_PARAM_DATA_AVAILABLE和流式输出参数的详细信息，请参阅 使用 SQLGetData 检索输出参数。

行计数的可用性

当批处理包含多个连续的行计数生成语句时，这些行计数可能会汇总为一个行计数。 例如，如果批有五个插入语句，则某些数据源能够返回五个单独的行计数。 某些其他数据源仅返回一个表示五个单独行计数之和的行计数。

当批处理包含结果集生成语句和行计数生成语句的组合时，行计数可能可用，也可能根本不可用。 驱动程序与行计数可用性相关的行为在通过调用 SQLGetInfo 提供的SQL_BATCH_ROW_COUNT信息类型中枚举。 例如，假设批包含 一个 SELECT，后跟两个 INSERT和另一个 SELECT。 然后，可能出现以下情况：

  • 与两个 INSERT 语句对应的行计数根本不可用。 第一次调用 SQLMoreResults 会将你置于第二个 SELECT 语句的结果集上。

  • 对应于两个 INSERT 语句的行计数单独可用。 (对 SQLGetInfo 的调用不会返回SQL_BATCH_ROW_COUNT信息类型的SQL_BRC_ROLLED_UP位。) 对 SQLMoreResults 的第一次调用会将你置于第一个 INSERT 的行计数上，第二次调用会将你置于第二个 INSERT 的行计数上。 第三次调用 SQLMoreResults 会将你置于第二个 SELECT 语句的结果集上。

  • 对应于两个 INSERT 的行计数汇总为一个可用的单行计数。 (对 SQLGetInfo 的调用将返回SQL_BATCH_ROW_COUNT信息类型的SQL_BRC_ROLLED_UP位。) 对 SQLMoreResults 的第一次调用将定位在汇总行计数上，而对 SQLMoreResults 的第二次调用会将你定位在第二个 SELECT 的结果集上。

某些驱动程序使行计数仅适用于显式批处理，而不适用于存储过程。

有关以下方面的信息 请参阅
取消语句处理 SQLCancel 函数
提取数据块或滚动浏览结果集 SQLFetchScroll Function（SQLFetchScroll 函数）
以仅向前方向提取单行或数据块 SQLFetch 函数
提取部分或全部数据列 SQLGetData 函数

另请参阅

ODBC API 参考
ODBC 头文件
使用 SQLGetData 检索输出参数