SQLCancelHandle 函数
一致性
引入的版本：ODBC 3.8 标准符合性：无
预计大多数 ODBC 3.8 (及更高版本的) 驱动程序将实现此函数。 如果驱动程序没有，则对 SQLCancelHandle 的调用（在 Handle 参数中使用连接句柄）将返回SQL_ERROR，SQLSTATE 为 IM001，并且消息“Driver 不支持此函数”。使用语句句柄作为 Handle 参数对 SQLCancel 的调用将由驱动程序管理器映射到对 SQLCancel 的调用，如果驱动程序实现 SQLCancel，则可以进行处理。 应用程序可以使用 SQLGetFunctions 来确定驱动程序是否支持 SQLCancelHandle。
摘要
SQLCancelHandle 取消对连接或语句的处理。 SQL_HANDLE_STMT HandleType 时，驱动程序管理器会将对 SQLCancelHandle 的调用映射到对 SQLCancel 的调用。
语法
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
参数
HandleType
[输入]要对其进行处理的句柄的类型。 有效值为SQL_HANDLE_DBC或SQL_HANDLE_STMT。
Handle
[输入]要取消处理的句柄。
如果 Handle 不是 HandleType 指定的类型的有效句柄， 则 SQLCancelHandle 返回SQL_INVALID_HANDLE。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。
诊断
当 SQLCancelHandle 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT 语句句 柄 或 handleType 为 SQL_HANDLE_DBC 和连接句 柄。
下表列出了 SQLCancelHandle 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在参数 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | 为与 Handle 关联的语句句柄之一调用了异步执行的语句相关 函数，并将HandleType 设置为 SQL_HANDLE_DBC。 调用 SQLCancelHandle 时，异步函数仍在执行。 (DM) 已SQL_HANDLE_STMT HandleType 参数;对关联的连接句柄调用了异步执行的函数;调用此函数时，函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 为与 Handle 和 HandleType 关联的语句句柄之一被设置为 SQL_HANDLE_DBC，并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 SQLBrowseConnect 已为 ConnectionHandle 调用，并返回SQL_NEED_DATA。 此函数是在浏览过程完成之前调用的。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。 |
| HY092 | 无效的属性/选项标识符 | HandleType 设置为 SQL_HANDLE_ENV 或 SQL_HANDLE_DESC。 |
| HY117 | 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 句柄 关联的驱动程序不支持 函数。 |
如果在将 HandleType 设置为 SQL_HANDLE_STMT 的情况下调用 SQLCancelHandle，则它可以返回可由函数 SQLCancel 返回的任何 SQLSTATE。
注释
此函数类似于 SQLCancel ，但可能采用连接句柄或语句句柄作为参数，而不仅仅是语句句柄。 SQL_HANDLE_STMT HandleType 时，驱动程序管理器会将对 SQLCancelHandle 的调用映射到对 SQLCancel 的调用。 这允许应用程序使用 SQLCancelHandle 取消语句操作，即使驱动程序未实现 SQLCancelHandle。
有关取消语句操作的详细信息，请参阅 SQLCancel 函数。
如果在 Handle 上没有正在进行的操作，则对 SQLCancelHandle 的 调用不起作用。
连接句柄上的 SQLCancelHandle 可以取消以下类型的处理：
在连接上异步运行的函数。
在另一个线程的连接句柄上运行的函数。
调用 SQLCancelHandle 以取消在连接中异步运行的函数时， SQLCancelHandle 发布的诊断记录将追加到正在取消的操作返回的诊断记录;但是，当取消在另一个线程上的连接上运行的函数时， SQLCancelHandle 不会返回诊断记录。
使用 SQLCancelHandle 取消 SQLEndTran 可能会使连接处于挂起状态。 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
注意
有关如何在将部署在早于 Windows 7 的 Windows 操作系统上的应用程序中使用 SQLCancelHandle 的信息，请参阅 兼容性矩阵。
取消Connection-Related异步处理
如果函数返回SQL_STILL_EXECUTING，应用程序可以调用 SQLCancelHandle 来取消操作。 如果取消请求成功， SQLCancelHandle 将返回SQL_SUCCESS。 这并不意味着原始函数已取消;它指示已处理取消请求。 驱动程序和数据源确定何时或是否取消操作。 应用程序必须继续调用原始函数，直到返回代码未SQL_STILL_EXECUTING。 如果取消了原始函数，则返回代码SQL_ERROR，SQLSTATE HY008 (操作) 取消。 如果原始函数完成其正常处理 (未) 取消，则返回代码SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，或者SQL_ERROR，如果原始函数失败，则) 取消了除 HY008 (操作以外的 SQLSTATE。
取消在另一个线程上执行的函数
在多线程应用程序中，应用程序可以取消在另一个线程上运行的操作。 若要取消该操作，应用程序使用函数使用的句柄调用 SQLCancelHandle ，但在不同的线程上。 驱动程序和操作系统确定取消操作的方式。 SQLCancelHandle 返回代码指示驱动程序是处理请求，返回SQL_SUCCESS还是SQL_ERROR () 返回诊断信息。 如果取消对原始函数的处理，则原始函数返回SQL_ERROR，SQLSTATE HY008 (操作取消) 。
如果在另一个线程上调用 SQLCancelHandle 以取消函数时正在执行某个函数，则函数可能会成功并返回SQL_SUCCESS，然后取消才能生效。 如果操作在 SQLCancelHandle 能够取消操作之前完成，则对 SQLCancelHandle 的调用不起作用。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 取消在语句句柄上异步运行的函数、取消需要数据的语句上的函数，或取消在另一个线程上的语句上运行的函数。 | SQLCancel 函数 |