SQLEndTran 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLEndTran 针对与连接关联的所有语句的所有活动操作请求提交或回滚操作。 SQLEndTran 还可以请求对与环境关联的所有连接执行提交或回滚操作。
注意
有关驱动程序管理器在 ODBC 3 时将此函数映射到的内容的详细信息。x 应用程序正在使用 ODBC 2。x 驱动程序，请参阅 映射替换函数以实现应用程序的向后兼容性。
语法
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
参数
HandleType
[输入]句柄类型标识符。 如果 句柄 是环境句柄) ，则包含SQL_HANDLE_ENV (;如果 句柄 是连接句柄) ，则包含SQL_HANDLE_DBC (。
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，句 柄 未处于连接状态。 |
| 08007 | 事务期间连接失败 | HandleType 已SQL_HANDLE_DBC，并且与句柄关联的连接在执行函数期间失败，并且无法确定请求的 COMMIT 或 ROLLBACK 是在失败之前发生的。 |
| 25S01 | 事务状态未知 | Handle 中的一个或多个连接未能完成指定结果的事务，结果未知。 |
| 25S02 | 事务仍处于活动状态 | 驱动程序无法保证全局事务中的所有工作都可以以原子方式完成，并且该事务仍处于活动状态。 |
| 25S03 | 事务已回滚 | 驱动程序无法保证全局事务中的所有工作都可以以原子方式完成，并且 已回滚 Handle 中活动事务中的所有工作。 |
| 40001 | 序列化失败 | 由于与另一个事务发生资源死锁，事务已回滚。 |
| 40002 | 完整性约束冲突 | CompletionType 已SQL_COMMIT，更改承诺导致完整性约束冲突。 因此，事务被回滚。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *szMessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 已为 ConnectionHandle 启用异步处理。 调用了函数，在它完成执行 SQLCancelHandle 之前，在 ConnectionHandle 上调用了函数。 然后，在 ConnectionHandle 上再次调用函数。 函数已调用，在执行完 SQLCancelHandle 之前，已从多线程应用程序中的不同线程在 ConnectionHandle 上调用。 |
| 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句 柄 是有效的环境句柄，并且该环境中有多个处于连接状态的连接，则驱动程序管理器将为该环境中处于连接状态的每个连接调用驱动程序中的 SQLTransact 一次。 每次调用中的 Handle 参数将是连接的句柄。 在任一情况下，驱动程序都会尝试提交或回滚在该环境中处于连接状态的所有连接，具体取决于 CompletionType 的值。 非活动连接不会影响事务。
注意
SQLEndTran 不能用于在共享环境中提交或回滚事务。 SQLSTATE HY092 (如果调用 SQLEndTran 并将 句柄 设置为共享环境的句柄或共享环境中的连接句柄，则将返回无效的属性/选项标识符) 。
仅当驱动程序管理器收到每个连接的SQL_SUCCESS时，才会返回SQL_SUCCESS。 如果驱动程序管理器在一个或多个连接上收到SQL_ERROR，它将SQL_ERROR返回到应用程序，并且诊断信息将放置在环境的诊断数据结构中。 若要确定在提交或回滚操作期间失败的连接或连接，应用程序可以为每个连接调用 SQLGetDiagRec 。
注意
驱动程序管理器不会在所有连接中模拟全局事务，因此不使用两阶段提交协议。
如果 CompletionType 是SQL_COMMIT， SQLEndTran 将对与受影响的连接关联的任何语句上的所有活动操作发出提交请求。 如果 CompletionType 为SQL_ROLLBACK， SQLEndTran 会针对与受影响的连接关联的任何语句发出所有活动操作的回滚请求。 如果没有活动的事务， SQLEndTran 将返回SQL_SUCCESS，不会对任何数据源产生影响。 有关详细信息，请参阅 提交和回滚事务。
如果驱动程序通过调用 SQLSetConnectAttr （SQL_ATTR_AUTOCOMMIT 属性设置为 SQL_AUTOCOMMIT_OFF) ） (手动提交模式，则当对当前数据源执行事务中包含的 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 使存在的任何语句都处于准备状态;应用程序可以为与连接关联的语句调用 SQLExecute ，而无需首先调用 SQLPrepare。
如果SQL_CURSOR_ROLLBACK_BEHAVIOR或SQL_CURSOR_COMMIT_BEHAVIOR值等于SQL_CB_PRESERVE， 则 SQLEndTran 不会影响与连接关联的打开游标。 游标保留在调用 SQLEndTran 之前指向的行。
对于支持事务的驱动程序和数据源，在没有事务处于活动状态时，使用 SQL_COMMIT 或 SQL_ROLLBACK 调用 SQLEndTran 将返回SQL_SUCCESS (指示没有要提交或回滚) 的工作，并且对数据源没有影响。
当驱动程序处于自动提交模式时，驱动程序管理器不会在驱动程序中调用 SQLEndTran 。 SQLEndTran 始终返回SQL_SUCCESS，无论调用的 CompletionType 为 SQL_COMMIT 还是SQL_ROLLBACK。
不支持 sqlGetInfo选项 SQL_TXN_CAPABLE (事务的驱动程序或数据源SQL_TC_NONE) 实际上始终处于自动提交模式，因此始终返回 SQLEndTran 的SQL_SUCCESS，无论它们是否使用SQL_COMMIT或SQL_ROLLBACK 的 CompletionType 调用。 此类驱动程序和数据源在请求这样做时实际上不会回滚事务。
挂起状态
在 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 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈