SQLEndTran 函数

一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92

总结
SQLEndTran 针对与连接关联的所有语句请求提交或回滚操作。 SQLEndTran 还可以请求对与环境关联的所有连接执行提交或回滚操作。

注意

有关 Driver Manager 将此函数映射到 ODBC 3 时的内容的详细信息。x 应用程序正在使用 ODBC 2。x 驱动程序，请参阅 映射替换函数以实现应用程序的向后兼容性。

语法

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

参数

HandleType
[输入]句柄类型标识符。 包含SQL_HANDLE_ENV（如果 Handle 是环境句柄 ）或SQL_HANDLE_DBC（如果 Handle 是连接句柄）。

Handle
[输入]HandleType 指示的类型句柄，指示事务的范围。 有关详细信息，请参阅“批注”。

CompletionType
[输入]以下两个值之一：

SQL_COMMIT SQL_ROLLBACK

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE 或SQL_STILL_EXECUTING。

诊断

当 SQLEndTran 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用适当的 HandleType 和 Handle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLEndTran 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE	错误	说明
01000	常规警告	特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。）
08003	连接未打开	（DM） HandleType 已SQL_HANDLE_DBC，而 Handle 未处于连接状态。
08007	事务期间连接失败	HandleType 已SQL_HANDLE_DBC，并且与句柄关联的连接在执行函数期间失败，并且无法确定请求的 COMMIT 还是 ROLLBACK 在失败之前发生。
25S01	事务状态未知	Handle 中的一个或多个连接未能完成指定结果的事务，结果未知。
25S02	事务仍处于活动状态	驱动程序无法保证全局事务中的所有工作都可以以原子方式完成，并且该事务仍然处于活动状态。
25S03	事务回滚	驱动程序无法保证全局事务中的所有工作都可以以原子方式完成，并且已回滚 Handle 中处于活动状态的事务中的所有工作。
40001	序列化失败	由于资源死锁与另一个事务，事务已回滚。
40002	完整性约束冲突	CompletionType 已SQL_COMMIT，更改承诺导致完整性约束冲突。 因此，事务已回滚。
HY000	常规错误	发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *szMessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY008	操作已取消	为 ConnectionHandle 启用了异步处理。 调用了该函数，在完成对 ConnectionHandle 执行 SQLCancelHandle 函数之前。 然后，在 ConnectionHandle 上再次调用该函数。 调用了该函数，在完成对 ConnectionHandle 执行 SQLCancelHandle 之前，该函数从多线程应用程序中的不同线程调用。
HY010	函数序列错误	（DM） 为与 ConnectionHandle 关联的语句句柄调用异步执行函数，并在调用 SQLEndTran 时仍在执行。 （DM） 为 ConnectionHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为与 ConnectionHandle 关联的语句句柄调用 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 （DM） 异步执行函数（而不是此函数）为 HandleType 设置为SQL_HANDLE_DBC调用句柄，并在调用此函数时仍在执行。 （DM） SQLExecute、 SQLExecDirect 或 SQLMoreResults 被调用为与 Handle 关联的语句句柄之一并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。
HY012	事务操作代码无效	（DM） 为参数 CompletionType 指定的值既不是SQL_COMMIT也不是SQL_ROLLBACK。
HY013	内存管理错误	无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。
HY092	属性/选项标识符无效	（DM） 为参数 HandleType 指定的值既不是SQL_HANDLE_ENV也不是SQL_HANDLE_DBC。
HY115	对于包含启用了异步函数执行的连接的环境，不允许使用 SQLEndTran	（DM） 如果为环境中的连接启用了连接函数的异步执行，则 HandleType 不能设置为SQL_HANDLE_ENV。
HY117	连接因未知事务状态而挂起。 仅允许断开连接和只读函数。	（DM） 有关挂起状态的详细信息，请参阅本主题的“注释”部分。
HYC00	未实现可选功能	驱动程序或数据源不支持 ROLLBACK 操作。
HYT01	超过连接超时时间	在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。
IM001	驱动程序不支持此函数	（DM） 与 ConnectionHandle 关联的驱动程序不支持该函数。
IM017	在异步通知模式下禁用轮询	每当使用通知模型时，轮询将被禁用。
IM018	尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。	如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式， 则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。

评论

对于 ODBC 3。x 驱动程序，如果 HandleType SQL_HANDLE_ENV并且 Handle 是有效的环境句柄 ，则驱动程序管理器将在与环境关联的每个驱动程序中调用 SQLEndTran 。 调用驱动程序的 Handle 参数将是驱动程序的环境句柄。 对于 ODBC 2。x 驱动程序，如果 HandleType 为SQL_HANDLE_ENV且 Handle 是有效的环境句柄，并且在该环境中处于连接状态有多个连接，则驱动程序管理器将为该环境中处于连接状态的每个连接调用 一次 SQLTransact 。 每个调用中的 Handle 参数将是连接的句柄。 在任一情况下，驱动程序都将尝试提交或回滚事务，具体取决于 CompletionType 的值，具体取决于处于该环境中连接状态的所有连接。 未处于活动状态的连接不会影响事务。

注意

SQLEndTran 不能用于在共享环境中提交或回滚事务。 如果将 SQLEndTran 设置为 共享环境的句柄 或共享环境中的连接句柄，将返回 SQLSTATE HY092 （属性/选项标识符无效）。

仅当驱动程序管理器收到每个连接的SQL_SUCCESS时，驱动程序管理器才会返回SQL_SUCCESS。 如果驱动程序管理器在一个或多个连接上收到SQL_ERROR，则会将SQL_ERROR返回到应用程序，并将诊断信息放置在环境的诊断数据结构中。 若要确定在提交或回滚操作期间哪个连接或连接失败，应用程序可以为每个连接调用 SQLGetDiagRec 。

注意

驱动程序管理器不会模拟所有连接的全局事务，因此不使用两阶段提交协议。

如果 CompletionType SQL_COMMIT，SQLEndTran 将对与受影响的连接关联的任何语句上的所有活动操作发出提交请求。 如果 CompletionType SQL_ROLLBACK， 则 SQLEndTran 针对与受影响的连接关联的任何语句发出所有活动操作的回滚请求。 如果没有事务处于活动状态， SQLEndTran 将返回SQL_SUCCESS，而不会影响任何数据源。 有关详细信息，请参阅 提交和回滚事务。

如果驱动程序处于手动提交模式（通过调用 SQL_ATTR_AUTOCOMMIT属性设置为 SQL_AUTOCOMMIT_OFF 的 SQLSetConnectAttr ），则当可包含在事务中的 SQL 语句针对当前数据源执行时，将隐式启动新事务。 有关详细信息，请参阅 提交模式。

若要确定事务操作如何影响游标，应用程序使用SQL_CURSOR_ROLLBACK_BEHAVIOR和SQL_CURSOR_COMMIT_BEHAVIOR选项调用 SQLGetInfo 。 有关详细信息，请参阅以下段落，另请参阅 事务对游标和准备语句的影响。

如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等于SQL_CB_DELETE，SQLEndTran 将关闭并删除与连接关联的所有语句上所有打开的游标，并丢弃所有挂起的结果。 SQLEndTran 将保留处于已分配状态（未准备）状态的任何语句;应用程序可以重复使用这些语句以供后续 SQL 请求使用，或者可以使用 handleType 为 SQL_HANDLE_STMT 调用 SQLFreeStmt 或 SQLFreeHandle 以解除分配它们。

如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等于SQL_CB_CLOSE，SQLEndTran 将关闭与连接关联的所有语句上所有打开的游标。 SQLEndTran 保留处于已准备状态的任何语句;应用程序无需先调用 SQLPrepare 即可为与连接关联的语句调用 SQLExecute。

如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等于SQL_CB_PRESERVE，SQLEndTran 不会影响与连接关联的打开游标。 游标在对 SQLEndTran 的调用之前所指向的行中保留。

对于支持事务的驱动程序和数据源，在没有活动事务返回SQL_SUCCESS时，使用 SQL_COMMIT 或 SQL_ROLLBACK 调用 SQLEndTran （指示没有要提交或回滚的工作），并且对数据源没有影响。

当驱动程序处于自动提交模式时，驱动程序管理器不会在驱动程序中调用 SQLEndTran 。 SQLEndTran 始终返回SQL_SUCCESS，无论它是使用 SQL_COMMIT还是SQL_ROLLBACK的 CompletionType 调用。

不支持事务的驱动程序或数据源（SQLGetInfo 选项SQL_TXN_CAPABLE是SQL_TC_NONE）实际上始终处于自动提交模式，因此无论它们是否使用 SQL_COMMIT 或 SQL_ROLLBACK 的 CompletionType 调用，都会始终返回 SQLEndTran 的SQL_SUCCESS。 请求这样做时，此类驱动程序和数据源实际上不会回滚事务。

挂起状态

在 Windows 7 之前发布的驱动程序管理器中，如果 SQLEndTran 从驱动程序返回SQL_ERROR，则事务处于活动状态。 但是，事务可能在服务器上成功提交，但客户端上的驱动程序未收到通知（例如，因为发生了网络错误）。 这会使连接处于错误状态。 从 Windows 7 开始，当 SQLEndTran 返回SQL_ERROR时，连接可能处于挂起状态。 处于挂起状态时，可以调用只读函数。 最终，应用程序应在挂起的连接上调用 SQLDisconnect 以释放资源。

如果以下所有条件均为 true，连接将进入挂起状态：

• 驱动程序从 SQLEndTran 返回SQL_ERROR。

• 驱动程序是 ODBC 版本 3.8 或更高版本。

• 应用程序版本为 3.8 或更高版本;或重新编译的 ODBC 2.x 或 3.x 应用程序通过 SQLCancelHandle 成功取消 SQLEndTran 函数。

• 驱动程序未返回以下消息之一，该消息确认事务未完成：

  • 25S03：回滚事务

  • 40001：序列化失败

  • 40002：完整性约束

  • HYC00：未实现可选功能

如果在 环境句柄上调用了 SQLEndTran ，并且其中一个连接满足上述条件，则连接到同一驱动程序的所有连接都将处于挂起状态。

应用程序在挂起的连接上调用 SQLDisconnect 后，该连接可用于重新连接到另一个数据源或同一数据源。

相关函数

有关以下内容的信息	请参阅
取消在连接句柄上异步运行的函数。	SQLCancelHandle 函数
返回有关驱动程序或数据源的信息	SQLGetInfo 函数
释放句柄	SQLFreeHandle 函数
释放语句句柄	SQLFreeStmt 函数

另请参阅

ODBC API 参考
ODBC 头文件
异步执行（轮询方法）