SQLEndTran 函数SQLEndTran Function

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

摘要Summary
对于与连接相关联的所有语句, SQLEndTran请求执行提交或回滚操作。SQLEndTran requests a commit or rollback operation for all active operations on all statements associated with a connection. SQLEndTran还可以请求为与环境关联的所有连接执行提交或回滚操作。SQLEndTran can also request that a commit or rollback operation be performed for all connections associated with an environment.

备注

有关在 ODBC 3 时驱动程序管理器将此函数映射到的内容的详细信息。x应用程序正在使用 ODBC 2。x驱动程序, 请参阅为应用程序的向后兼容性映射替换函数For more information about what the Driver Manager maps this function to when an ODBC 3.x application is working with an ODBC 2.x driver, see Mapping Replacement Functions for Backward Compatibility of Applications.

语法Syntax

  
SQLRETURN SQLEndTran(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle,  
     SQLSMALLINT   CompletionType);  

参数Arguments

HandleTypeHandleType
送句柄类型标识符。[Input] Handle type identifier. 包含 SQL_HANDLE_ENV (如果handle为环境句柄) 或 SQL_HANDLE_DBC (如果柄是连接句柄)。Contains either SQL_HANDLE_ENV (if Handle is an environment handle) or SQL_HANDLE_DBC (if Handle is a connection handle).

HandleHandle
HandleType指示的类型的句柄, 指示事务的作用域。[Input] The handle, of the type indicated by HandleType, indicating the scope of the transaction. 有关详细信息, 请参阅 "注释"。See "Comments" for more information.

CompletionTypeCompletionType
送以下两个值之一:[Input] One of the following two values:

SQL_COMMIT SQL_ROLLBACKSQL_COMMIT SQL_ROLLBACK

返回Returns

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

诊断Diagnostics

SQLEndTran返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时, 可以通过使用相应的SQLGetDiagRec句柄调用HandleType来获取关联的 SQLSTATE 值。When SQLEndTran returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLGetDiagRec with the appropriate HandleType and Handle. 下表列出了通常由SQLEndTran返回的 SQLSTATE 值, 并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLEndTran 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.)
0800308003 连接未打开Connection not open (DM) HandleType是 SQL_HANDLE_DBC,句柄未处于已连接状态。(DM) The HandleType was SQL_HANDLE_DBC, and the Handle was not in a connected state.
0800708007 事务期间连接失败Connection failure during transaction HandleType为 SQL_HANDLE_DBC, 并且与句柄关联的连接在执行函数时失败, 并且无法确定请求的提交回滚是否发生在否则.The HandleType was SQL_HANDLE_DBC, and the connection associated with the Handle failed during the execution of the function, and it cannot be determined whether the requested COMMIT or ROLLBACK occurred before the failure.
25S0125S01 事务状态未知Transaction state unknown 句柄中的一个或多个连接无法完成具有指定结果的事务, 结果未知。One or more of the connections in Handle failed to complete the transaction with the outcome specified, and the outcome is unknown.
25S0225S02 事务仍处于活动状态Transaction is still active 驱动程序无法保证可以自动完成全局事务中的所有工作, 并且该事务仍处于活动状态。The driver was not able to guarantee that all work in the global transaction could be completed atomically, and the transaction is still active.
25S0325S03 事务已回滚Transaction is rolled back 驱动程序无法保证可以自动完成全局事务中的所有工作, 并且回滚了事务中处于活动状态的所有工作。 The driver was not able to guarantee that all work in the global transaction could be completed atomically, and all work in the transaction active in Handle was rolled back.
4000140001 序列化失败Serialization failure 由于另一个事务发生了资源死锁, 事务已回滚。The transaction was rolled back due to a resource deadlock with another transaction.
4000240002 完整性约束冲突Integrity constraint violation CompletionType是 SQL_COMMIT 的, 更改的承诺导致了完整性约束冲突。The CompletionType was SQL_COMMIT, and the commitment of changes caused integrity constraint violation. 因此, 事务已回滚。As a result, the transaction was rolled back.
HY000HY000 一般错误General error 发生了一个错误, 该错误没有特定的 SQLSTATE, 没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. SzMessageText 缓冲区中的 SQLGetDiagRec返回的错误消息描述了错误及其原因。 *The error message returned by SQLGetDiagRec in the *szMessageText 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 已为ConnectionHandle启用异步处理。Asynchronous processing was enabled for the ConnectionHandle. 在对ConnectionHandle调用SQLCancelHandle 函数之前, 调用了函数。The function was called, and before it finished executing SQLCancelHandle Function was called on the ConnectionHandle. 然后, 在ConnectionHandle上再次调用该函数。Then the function was called again on the ConnectionHandle.

调用了函数, 并且在完成执行SQLCancelHandle之前, 从多线程应用程序中的另一个线程调用了ConnectionHandleThe function was called, and before it finished executing SQLCancelHandle was called on the ConnectionHandle from a different thread in a multithread application.
HY010HY010 函数序列错误Function sequence error (DM) 为与ConnectionHandle关联的语句句柄调用了异步执行的函数, 并且在调用SQLEndTran时仍在执行该函数。(DM) An asynchronously executing function was called for a statement handle associated with the ConnectionHandle and was still executing when SQLEndTran was called.

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

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos调用了与CONNECTIONHANDLE关联的语句句柄, 并返回 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for a statement handle associated with the ConnectionHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前, 将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.

(DM) 为HandleType设置为 SQL_HANDLE_DBC 并且在调用此函数时仍在执行的句柄调用了异步执行的函数 (而不是此函数)。(DM) An asynchronously executing function (not this one) was called for the Handle with HandleType set to SQL_HANDLE_DBC and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirect或 SQLMoreResults 是为与句柄关联的某个语句句柄或 SQL_PARAM_DATA_AVAILABLE 返回的 调用的。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for one of the statement handles associated with Handle and returned SQL_PARAM_DATA_AVAILABLE. 在检索所有流式处理参数的数据之前调用此函数。This function was called before data was retrieved for all streamed parameters.
HY012HY012 事务操作代码无效Invalid transaction operation code (DM) 为参数CompletionType指定的值既不是 SQL_COMMIT 也不是 SQL_ROLLBACK。(DM) The value specified for the argument CompletionType was neither SQL_COMMIT nor SQL_ROLLBACK.
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.
HY092HY092 无效的属性/选项标识符Invalid attribute/option identifier (DM) 为参数HandleType指定的值既不是 SQL_HANDLE_ENV 也不是 SQL_HANDLE_DBC。(DM) The value specified for the argument HandleType was neither SQL_HANDLE_ENV nor SQL_HANDLE_DBC.
HY115HY115 对于包含启用了异步函数执行的连接的环境, 不允许使用 SQLEndTranSQLEndTran is not allowed for an environment that contains a connection with asynchronous function execution enabled (DM) 如果对环境中的连接启用了连接函数的异步执行, 则不能将HandleType设置为 SQL_HANDLE_ENV。(DM) HandleType cannot be set to SQL_HANDLE_ENV if asynchronous execution of connection functions is enabled for a connection in the environment.
HY117HY117 由于未知的事务状态, 连接被挂起。Connection is suspended due to unknown transaction state. 仅允许断开连接和只读函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息, 请参阅本主题的备注部分。(DM) For more information about suspended state, refer to the Comments section of this topic.
HYC00HYC00 未实现的可选功能Optional feature not implemented 驱动程序或数据源不支持回滚操作。The driver or data source does not support the ROLLBACK operation.
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) 与ConnectionHandle关联的驱动程序不支持该函数。(DM) The driver associated with the ConnectionHandle 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

对于 ODBC 3。x驱动程序, 如果HandleType为 SQL_HANDLE_ENV, handle为有效的环境句柄, 则驱动程序管理器将在与环境关联的每个驱动程序中调用SQLEndTranFor an ODBC 3.x driver, if HandleType is SQL_HANDLE_ENV and Handle is a valid environment handle, then the Driver Manager will call SQLEndTran in each driver associated with the environment. 对驱动程序的调用的Handle参数将是驱动程序的环境句柄。The Handle argument for the call to a driver will be the driver's environment handle. 对于 ODBC 2, 则为。x驱动程序, 如果HandleType为 SQL_HANDLE_ENV, handle为有效的环境句柄, 并且该环境中有多个连接处于连接状态, 则驱动程序管理器将在驱动程序中调用SQLTransact对于该环境中处于连接状态的每个连接。For an ODBC 2.x driver, if HandleType is SQL_HANDLE_ENV and Handle is a valid environment handle, and there are multiple connections in a connected state in that environment, then the Driver Manager will call SQLTransact in the driver once for each connection in a connected state in that environment. 每个调用中的handle参数将是连接的句柄。The Handle argument in each call will be the connection's handle. 无论是哪种情况, 驱动程序都将尝试根据CompletionType的值提交或回滚事务, 该环境中的所有连接都处于连接状态。In either case, the driver will attempt to commit or roll back transactions, depending on the value of CompletionType, on all connections that are in a connected state on that environment. 不活动的连接不会影响事务。Connections that are not active do not affect the transaction.

备注

SQLEndTran不能用于在共享环境中提交或回滚事务。SQLEndTran cannot be used to commit or roll back transactions on a shared environment. 如果调用SQLEndTran时将句柄设置为共享环境的句柄或共享环境上连接的句柄, 则将返回 SQLSTATE HY092 (无效的属性/选项标识符)。SQLSTATE HY092 (Invalid attribute/option identifier) will be returned if SQLEndTran is called with Handle set to either the handle of a shared environment or the handle of a connection on a shared environment.

仅当驱动程序管理器收到每个连接的 SQL_SUCCESS 时, 才会返回 SQL_SUCCESS。The Driver Manager will return SQL_SUCCESS only if it receives SQL_SUCCESS for each connection. 如果驱动程序管理器在一个或多个连接上收到 SQL_ERROR, 则会将 SQL_ERROR 返回到应用程序, 并将诊断信息置于环境的诊断数据结构中。If the Driver Manager receives SQL_ERROR on one or more connections, it returns SQL_ERROR to the application, and the diagnostic information is placed in the diagnostic data structure of the environment. 若要在提交或回滚操作期间确定哪些连接或连接失败, 应用程序可以为每个连接调用SQLGetDiagRecTo determine which connection or connections failed during the commit or rollback operation, the application can call SQLGetDiagRec for each connection.

备注

驱动程序管理器不会在所有连接上模拟全局事务, 因此不会使用两阶段提交协议。The Driver Manager does not simulate a global transaction across all connections and therefore does not use two-phase commit protocols.

如果CompletionType为 SQL_COMMIT, 则SQLEndTran将为与受影响的连接关联的任何语句的所有活动操作发出 COMMIT 请求。If CompletionType is SQL_COMMIT, SQLEndTran issues a commit request for all active operations on any statement associated with an affected connection. 如果CompletionType为 SQL_ROLLBACK, 则SQLEndTran将为与受影响的连接关联的任何语句的所有活动操作发出回滚请求。If CompletionType is SQL_ROLLBACK, SQLEndTran issues a rollback request for all active operations on any statement associated with an affected connection. 如果没有活动事务, 则SQLEndTran将返回 SQL_SUCCESS, 而不会对任何数据源产生任何影响。If no transactions are active, SQLEndTran returns SQL_SUCCESS with no effect on any data sources. 有关详细信息, 请参阅提交和回滚事务For more information, see Committing and Rolling Back Transactions.

如果驱动程序处于手动提交模式 (通过调用SQLSetConnectAttr , 并将 SQL_ATTR_AUTOCOMMIT 属性设置为 SQL_AUTOCOMMIT_OFF), 则在事务中可包含的 SQL 语句时, 将隐式启动新事务。针对当前数据源执行。If the driver is in manual-commit mode (by calling SQLSetConnectAttr with the SQL_ATTR_AUTOCOMMIT attribute set to SQL_AUTOCOMMIT_OFF), a new transaction is implicitly started when an SQL statement that can be contained within a transaction is executed against the current data source. 有关详细信息, 请参阅提交模式For more information, see Commit Mode.

若要确定事务操作如何影响游标, 应用程序需要使用 SQL_CURSOR_ROLLBACK_BEHAVIOR 和 SQL_CURSOR_COMMIT_BEHAVIOR 选项调用SQLGetInfoTo determine how transaction operations affect cursors, an application calls SQLGetInfo with the SQL_CURSOR_ROLLBACK_BEHAVIOR and SQL_CURSOR_COMMIT_BEHAVIOR options. 有关详细信息, 请参阅以下段落, 并查看事务对游标和预定义语句的影响For more information, see the following paragraphs and also see Effect of Transactions on Cursors and Prepared Statements.

如果 SQL_CURSOR_ROLLBACK_BEHAVIOR 或 SQL_CURSOR_COMMIT_BEHAVIOR 值等于 SQL_CB_DELETE, 则SQLEndTran将关闭并删除与该连接关联的所有语句上的所有打开的游标, 并放弃所有挂起的结果。If the SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR value equals SQL_CB_DELETE, SQLEndTran closes and deletes all open cursors on all statements associated with the connection and discards all pending results. SQLEndTran保留已分配 (未准备好的) 状态中的任何语句;应用程序可以重复使用这些方法来执行后续的 SQL 请求, 或者可以使用 SQL_HANDLE_STMT 的HandleType调用SQLFreeStmtSQLFreeHandle来解除分配。SQLEndTran leaves any statement present in an allocated (unprepared) state; the application can reuse them for subsequent SQL requests or can call SQLFreeStmt or SQLFreeHandle with a HandleType of SQL_HANDLE_STMT to deallocate them.

如果 SQL_CURSOR_ROLLBACK_BEHAVIOR 或 SQL_CURSOR_COMMIT_BEHAVIOR 值等于 SQL_CB_CLOSE, 则SQLEndTran将关闭与该连接关联的所有语句上的所有打开的游标。If the SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR value equals SQL_CB_CLOSE, SQLEndTran closes all open cursors on all statements associated with the connection. SQLEndTran使任何语句都处于准备好的状态;应用程序可以在不首先调用SQLPrepare的情况下, 为与连接关联的语句调用SQLExecuteSQLEndTran leaves any statement present in a prepared state; the application can call SQLExecute for a statement associated with the connection without first calling SQLPrepare.

如果 SQL_CURSOR_ROLLBACK_BEHAVIOR 或 SQL_CURSOR_COMMIT_BEHAVIOR 值等于 SQL_CB_PRESERVE, 则SQLEndTran不会影响与该连接关联的打开的游标。If the SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR value equals SQL_CB_PRESERVE, SQLEndTran does not affect open cursors associated with the connection. 在调用SQLEndTran之前, 游标保留在它们指向的行上。Cursors remain at the row they pointed to prior to the call to SQLEndTran.

对于支持事务的驱动程序和数据源, 如果没有活动事务, 则使用 SQL_COMMIT 或 SQL_ROLLBACK 调用SQLEndTran将返回 SQL_SUCCESS (表示没有要提交或回滚的工作), 并且对数据源。For drivers and data sources that support transactions, calling SQLEndTran with either SQL_COMMIT or SQL_ROLLBACK when no transaction is active returns SQL_SUCCESS (indicating that there is no work to be committed or rolled back) and has no effect on the data source.

当驱动程序处于自动提交模式时, 驱动程序管理器不会在该驱动程序中调用SQLEndTranWhen a driver is in autocommit mode, the Driver Manager does not call SQLEndTran in the driver. SQLEndTran始终返回 SQL_SUCCESS, 而不考虑是否使用CompletionType的 SQL_COMMIT 或 SQL_ROLLBACK 调用它。SQLEndTran always returns SQL_SUCCESS regardless of whether it is called with a CompletionType of SQL_COMMIT or SQL_ROLLBACK.

不支持事务的驱动程序或数据源 (SQLGetInfo 选项SQL_TXN_CAPABLE 为 SQL_TC_NONE) 实际上始终处于自动提交模式,因此无论是否使用 SQL_COMMIT 或 SQL_ROLLBACK 的CompletionType调用。Drivers or data sources that do not support transactions (SQLGetInfo option SQL_TXN_CAPABLE is SQL_TC_NONE) are effectively always in autocommit mode and therefore always return SQL_SUCCESS for SQLEndTran whether or not they are called with a CompletionType of SQL_COMMIT or SQL_ROLLBACK. 此类驱动程序和数据源不会在请求时实际回滚事务。Such drivers and data sources do not actually roll back transactions when requested to do so.

挂起状态Suspended State

在 Windows 7 之前发布的驱动程序管理器中, 如果SQLEndTran从驱动程序返回了 SQL_ERROR, 则事务处于活动状态。In Driver Managers that were released before Windows 7, a transaction was active if SQLEndTran returned SQL_ERROR from the driver. 但是, 事务已在服务器上成功提交, 但客户端上的驱动程序没有收到通知 (例如, 由于出现网络错误)。However, it was possible that the transaction had been successfully committed on the server, but the driver on the client had not been notified (for example, because a network error occurred). 这会使连接处于错误的状态。This would leave the connection in a bad state. 从 Windows 7 开始, 当SQLEndTran返回 SQL_ERROR 时, 该连接可能处于挂起状态。Starting with Windows 7, when SQLEndTran returns SQL_ERROR, the connection might be in a suspended state. 处于挂起状态时, 可以调用只读函数。In a suspended state, it is possible to call read-only functions. 最终, 应用程序应调用挂起的连接上的SQLDisconnect , 以释放资源。Eventually, the application should call SQLDisconnect on a suspended connection to release resources.

如果满足以下所有条件, 则连接将被置于挂起状态:If all of the following conditions are true, the connection will be put into a suspended state:

  • 驱动程序从SQLEndTran返回 SQL_ERROR。The driver returns SQL_ERROR from SQLEndTran.

  • 驱动程序为 ODBC 版本3.8 或更高版本。The driver is ODBC version 3.8, or later.

  • 应用程序版本为3.8 或更高版本;或者, 重新编译的 ODBC 2.x 或3.x 应用程序成功通过SQLCancelHandle取消了SQLEndTran函数。The application version is 3.8 or later; or the recompiled ODBC 2.x or 3.x application successfully cancels the SQLEndTran function through SQLCancelHandle.

  • 驱动程序未返回下列消息之一, 这将确认该事务未完成:The driver did not return one of the following messages, which confirm that the transaction did not complete:

    • 25S03:事务已回滚25S03: Transaction is rolled back

    • 40001:序列化失败40001: Serialization failure

    • 40002:完整性约束40002: Integrity constraint

    • HYC00:未实现的可选功能HYC00: Optional feature not implemented

如果在环境句柄上调用SQLEndTran , 并且其某个连接满足上述条件, 则连接到同一驱动程序的所有连接都将进入挂起状态。If SQLEndTran was called on an environment handle and one of its connections met the above conditions, all connections connecting to the same driver will be put into the suspended state.

在应用程序调用挂起的连接上的SQLDisconnect后, 可以使用该连接重新连接到另一个数据源或同一数据源。After an application calls SQLDisconnect on a suspended connection, the connection can be used to reconnect to another data source or the same data source.

有关信息For information about 请参阅See
取消在连接句柄上异步运行的函数。Canceling a function running asynchronously on a connection handle. SQLCancelHandle 函数SQLCancelHandle Function
返回有关驱动程序或数据源的信息Returning information about a driver or data source SQLGetInfo 函数SQLGetInfo Function
释放句柄Freeing a handle SQLFreeHandle 函数SQLFreeHandle Function
释放语句句柄Freeing a statement handle SQLFreeStmt 函数SQLFreeStmt Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件 ODBC Header Files
异步执行(轮询方法)Asynchronous Execution (Polling Method)