SQLMoreResults 函数SQLMoreResults Function

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

摘要Summary
SQLMoreResults 确定是否在包含 SELECTUPDATEINSERTDELETE 语句的语句上提供更多结果,如果是,则对这些结果初始化处理。SQLMoreResults determines whether more results are available on a statement containing SELECT, UPDATE, INSERT, or DELETE statements and, if so, initializes processing for those results.

语法Syntax

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

参数Arguments

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

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE 或 SQL_PARAM_DATA_AVAILABLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, OR SQL_PARAM_DATA_AVAILABLE.

诊断Diagnostics

SQLMoreResults 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时,可以通过使用 HandleType 的 SQL_HANDLE_STMT 和 StatementHandle句柄 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。When SQLMoreResults 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. 下表列出了通常由 SQLMoreResults 返回的 SQLSTATE 值,并对该函数的上下文中的每个值进行了说明:表示法 " (DM) " 位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLMoreResults 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 错误Error 说明Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。 ) (Function returns SQL_SUCCESS_WITH_INFO.)
01S0201S02 选项值已更改Option value has changed 处理批处理时,语句属性的值已更改。The value of a statement attribute changed as the batch was being processed. (函数返回 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.
4000140001 序列化失败Serialization failure 由于另一个事务发生了资源死锁,事务已回滚。The transaction was rolled back due to a resource deadlock with another transaction.
4000340003 语句完成情况未知Statement completion unknown 在执行此函数期间关联的连接失败,无法确定事务的状态。The associated connection failed during the execution of this function and the state of the transaction cannot be determined.
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. SQLMoreResults 函数在完成执行前调用,在 StatementHandle 上调用 SQLCancelSQLCancelHandleThe SQLMoreResults function was called and, before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle. 然后,在 StatementHandle 上再次调用 SQLMoreResults 函数。Then the SQLMoreResults function was called again on the StatementHandle.

SQLMoreResults 函数在完成执行之前调用,从多线程应用程序中的另一个线程调用 StatementHandle 上的 SQLCancelSQLCancelHandleThe SQLMoreResults 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. 调用 SQLMoreResults 函数时,此异步函数仍在执行。This asynchronous function was still executing when the SQLMoreResults function was called.

(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) 为 StatementHandle 调用 SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos ,并返回 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.
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.

注释Comments

SELECT 语句返回结果集。SELECT statements return result sets. UPDATEINSERTDELETE 语句返回受影响行的计数。UPDATE, INSERT, and DELETE statements return a count of affected rows. 如果这些语句中的任何一个进行了批处理,则将参数数组按参数顺序递增 (按其在批处理) 中出现的顺序进行编号,或在过程中,它们可以返回多个结果集或行计数。If any of these statements are batched, submitted with arrays of parameters (numbered in increasing parameter order, in the order that they appear in the batch), or in procedures, they can return multiple result sets or row counts. 有关语句的批处理和参数数组的信息,请参阅 SQL 语句的批处理参数值的数组For information about batches of statements and arrays of parameters, see Batches of SQL Statements and Arrays of Parameter Values.

执行批处理后,应用程序定位在第一个结果集上。After executing the batch, the application is positioned on the first result set. 应用程序可以在第一个或任何后续的结果集上调用 SQLBindColSQLBulkOperationsSQLFetchSQLGetDataSQLFetchScrollSQLSetPos 和所有元数据函数,就像在只有一个结果集的情况下。The application can call SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos, and all the metadata functions, on the first or any subsequent result sets, just as it would if there were just a single result set. 完成第一个结果集后,应用程序将调用 SQLMoreResults 以移到下一个结果集。Once it is done with the first result set, the application calls SQLMoreResults to move to the next result set. 如果有另一个结果集或计数可用,则 SQLMoreResults 将返回 SQL_SUCCESS 并初始化结果集或计数以进行其他处理。If another result set or count is available, SQLMoreResults returns SQL_SUCCESS and initializes the result set or count for additional processing. 如果在结果集生成语句之间出现任意行计数生成语句,则可以通过调用 SQLMoreResults 来逐过程进行。为 UPDATEINSERTDELETE 语句调用 SQLMoreResults 后,应用程序可以调用 SQLRowCountIf any row count-generating statements appear in between result set-generating statements, they can be stepped over by calling SQLMoreResults.After calling SQLMoreResults for UPDATE, INSERT, or DELETE statements, an application can call SQLRowCount.

如果当前包含 unfetched 行的结果集,则 SQLMoreResults 将丢弃该结果集,并使下一个结果集或计数可用。If there was a current result set with unfetched rows, SQLMoreResults discards that result set and makes the next result set or count available. 如果已处理所有结果, SQLMoreResults 将返回 SQL_NO_DATA。If all results have been processed, SQLMoreResults returns SQL_NO_DATA. 对于某些驱动程序,直到处理完所有结果集和行计数后,输出参数和返回值才可用。For some drivers, output parameters and return values are not available until all result sets and row counts have been processed. 对于此类驱动程序,当 SQLMoreResults 返回 SQL_NO_DATA 时,输出参数和返回值将变为可用。For such drivers, output parameters and return values become available when SQLMoreResults returns SQL_NO_DATA.

为之前的结果集建立的所有绑定仍然有效。Any bindings that were established for the previous result set still remain valid. 如果此结果集的列结构不同,则调用 SQLFetchSQLFetchScroll 可能导致错误或截断。If the column structures are different for this result set, then calling SQLFetch or SQLFetchScroll may result in an error or truncation. 若要防止出现这种情况,应用程序必须调用 SQLBindCol ,以便在适当的情况下显式重新绑定 (或通过设置描述符字段) 来执行此操作。To prevent this, the application has to call SQLBindCol to explicitly rebind as appropriate (or do so by setting descriptor fields). 或者,应用程序可以使用 SQL_UNBIND 选项 调用 SQLFreeStmt ,以取消绑定所有列缓冲区。Alternatively, the application can call SQLFreeStmt with an Option of SQL_UNBIND to unbind all the column buffers.

当应用程序通过调用 SQLMoreResults 在批处理中导航时,语句属性(如游标类型、游标并发、键集大小或最大长度)的值可能会更改。The values of statement attributes, such as cursor type, cursor concurrency, keyset size, or maximum length, may change as the application navigates through the batch by calls to SQLMoreResults. 如果发生这种情况, SQLMoreResults 将返回 SQL_SUCCESS_WITH_INFO 和 SQLSTATE 01S02 (选项值已更改) 。If this happens, SQLMoreResults will return SQL_SUCCESS_WITH_INFO and SQLSTATE 01S02 (Option value has changed).

如果使用 SQL_CLOSE 选项 调用 SQLCloseCursorSQLFreeStmt ,则会丢弃作为执行批处理的结果而提供的所有结果集和行计数。Calling SQLCloseCursor, or SQLFreeStmt with an Option of SQL_CLOSE, discards all the result sets and row counts that were available as a result of the execution of the batch. 语句句柄返回已分配状态或准备状态。The statement handle returns to either the allocated or prepared state. 如果调用 SQLCancel ,则在批处理已执行并且语句句柄处于执行、游标定位或异步状态时取消异步执行的函数会导致在取消调用成功的情况下丢弃的批处理生成的所有结果集和行计数。Calling SQLCancel to cancel an asynchronously executing function when a batch has been executed and the statement handle is in the executed, cursor-positioned, or asynchronous state results in all the results sets and row counts generated by the batch being discarded if the cancel call was successful. 然后,语句将返回到准备状态或已分配状态。The statement then returns to the prepared or allocated state.

如果一批语句或过程使用 SELECTUPDATEINSERTDELETE 语句来混合使用其他 SQL 语句,则这些其他语句不会影响 SQLMoreResultsIf a batch of statements or a procedure mixes other SQL statements with SELECT, UPDATE, INSERT, and DELETE statements, these other statements do not affect SQLMoreResults.

有关详细信息,请参阅 多个结果For more information, see Multiple Results.

如果在一批语句中搜索的 update、insert 或 delete 语句不会影响数据源中的任何行,则 SQLMoreResults 将返回 SQL_SUCCESS。If a searched update, insert, or delete statement in a batch of statements does not affect any rows at the data source, SQLMoreResults returns SQL_SUCCESS. 这不同于通过 SQLExecDirectSQLExecuteSQLParamData 执行的搜索的 update、insert 或 delete 语句的情况,如果不影响数据源中的任何行,则返回 SQL_NO_DATA。This is different from the case of a searched update, insert, or delete statement that is executed through SQLExecDirect, SQLExecute, or SQLParamData, which returns SQL_NO_DATA if it does not affect any rows at the data source. 如果在调用 SQLMoreResults 后,应用程序调用 SQLRowCount 来检索行计数,则 SQLRowCount 将返回 SQL_NO_DATA。If an application calls SQLRowCount to retrieve the row count after a call to SQLMoreResults has not affected any rows, SQLRowCount will return SQL_NO_DATA.

有关结果处理函数的有效序列的其他信息,请参阅 附录 B: ODBC 状态转换表For additional information about the valid sequencing of result-processing functions, see Appendix B: ODBC State Transition Tables.

有关 SQL_PARAM_DATA_AVAILABLE 和流式输出参数的详细信息,请参阅 使用 SQLGetData 检索输出参数For more information about SQL_PARAM_DATA_AVAILABLE and streamed output parameters, see Retrieving Output Parameters Using SQLGetData.

行计数的可用性Availability of Row Counts

如果批处理包含多个连续行计数生成语句,则可能会将这些行计数汇总成一个行计数。When a batch contains multiple consecutive row count-generating statements, it is possible that these row counts are rolled up into just one row count. 例如,如果某个批处理包含五个 insert 语句,则某些数据源可以返回五个单独的行计数。For example, if a batch has five insert statements, then certain data sources are capable of returning five individual row counts. 某些其他数据源仅返回一个行计数,表示五个单独行计数之和。Certain other data sources return only one row count that represents the sum of the five individual row counts.

当某个批处理包含结果集生成和行计数生成语句的组合时,行计数可能会也可能根本不可用。When a batch contains a combination of result set-generating and row count-generating statements, row counts may or may not be available at all. 对于行计数的可用性,驱动程序的行为在通过调用 SQLGetInfo 提供的 SQL_BATCH_ROW_COUNT 信息类型中进行枚举。The behavior of the driver with respect to the availability of row counts is enumerated in the SQL_BATCH_ROW_COUNT information type available through a call to SQLGetInfo. 例如,假设批处理包含 SELECT,后跟两个 INSERT s,另一个 选择For example, suppose that the batch contains a SELECT, followed by two INSERT s and another SELECT. 下面是可能的情况:Then the following cases are possible:

  • 与这两个 INSERT 语句相对应的行计数根本不可用。The row counts corresponding to the two INSERT statements are not available at all. 第一次调用 SQLMoreResults 时,会将您定位到第二个 SELECT 语句的结果集。The first call to SQLMoreResults will position you on the result set of the second SELECT statement.

  • 对应于两个 INSERT 语句的行计数分别可用。The row counts corresponding to the two INSERT statements are available individually. (调用 SQLGetInfo 不会返回 SQL_BATCH_ROW_COUNT 信息类型的 SQL_BRC_ROLLED_UP 位。 ) 第一次调用 SQLMoreResults 时,会将您定位到第一次 插入 的行计数,第二次调用会将您定位于第二次 插入 的行计数。(A call to SQLGetInfo does not return the SQL_BRC_ROLLED_UP bit for the SQL_BATCH_ROW_COUNT information type.) The first call to SQLMoreResults will position you on the row count of the first INSERT, and the second call will position you on the row count of the second INSERT. 第三次调用 SQLMoreResults 时,会将您定位到第二个 SELECT 语句的结果集。The third call to SQLMoreResults will position you on the result set of the second SELECT statement.

  • 对应于两个 插入 的行计数汇总到一个可用的单行计数中。The row counts corresponding to the two INSERTs are rolled up into one single row count that is available. (调用 SQLGetInfo 会返回 SQL_BATCH_ROW_COUNT 信息类型的 SQL_BRC_ROLLED_UP 位。 ) 第一次调用 SQLMoreResults 时,会将您定位到汇总行计数,而对 SQLMoreResults 的第二次调用会将您定位到第二个 SELECT 的结果集。(A call to SQLGetInfo returns the SQL_BRC_ROLLED_UP bit for the SQL_BATCH_ROW_COUNT information type.) The first call to SQLMoreResults will position you on the rolled-up row count, and the second call to SQLMoreResults will position you on the result set of the second SELECT.

某些驱动程序使行计数仅适用于显式批处理,不适用于存储过程。Certain drivers make row counts available only for explicit batches and not for stored procedures.

有关以下方面的信息For information about 请参阅See
正在取消语句处理Canceling statement processing SQLCancel 函数SQLCancel Function
提取数据块或滚动结果集Fetching a block of data or scrolling through a result set SQLFetchScroll Function(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

另请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件 ODBC Header Files
使用 SQLGetData 检索输出参数Retrieving Output Parameters Using SQLGetData