通过

SQLCancelHandle 函数

  • 项目

一致性
引入的版本：ODBC 3.8 标准符合性：无

预计大多数 ODBC 3.8（及更高版本）驱动程序将实现此函数。 如果驱动程序不，则为 调用 SQLCancelHandle 时，Handle 参数中的连接句柄将返回SQL_ERROR的 SQLSTATE 为 IM001，消息“Driver 不支持此函数”A 使用语句句柄调用 SQLCancelHandle，因为 Handle 参数将映射到驱动程序管理器 SQLCancel 调用，如果驱动程序可以处理驱动程序实现 SQLCancel。 应用程序可以使用 SQLGetFunctions 来确定驱动程序是否支持 SQLCancelHandle。

摘要
SQLCancelHandle 取消对连接或语句的处理。 驱动程序管理器将调用映射到 SQLCancelHandle 调用 SQLCancel 时，HandleType SQL_HANDLE_STMT。

语法

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

参数

HandleType
[输入]要取消处理的句柄的类型。 有效值SQL_HANDLE_DBC或SQL_HANDLE_STMT。

句柄
[输入]要取消处理的句柄。

如果 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 调用 HandleType SQL_HANDLE_STMT和语句句柄 Handle 或 HandleType SQL_HANDLE_DBC 以及 Handle的连接句柄来获取关联的 SQLSTATE 值。

下表列出了 sqlCancelHandle 通常由 返回的 SQLSTATE 值，并在此函数的上下文中解释每个值：表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE 错误 描述
01000 常规警告 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。）
HY000 常规错误 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec*MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 为与 Handle关联的语句句柄之一调用异步执行的语句相关函数，HandleType 设置为SQL_HANDLE_DBC。 调用 SQLCancelHandle 时 ，异步函数仍在执行。

（DM） HandleType 参数SQL_HANDLE_STMT;对关联的连接句柄调用异步执行函数;调用此函数时，该函数仍在执行。

（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 连接超时已过期 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 sqlSetConnectAttrSQL_ATTR_CONNECTION_TIMEOUT设置的。
IM001 驱动程序不支持此函数 （DM） 与 Handle 关联的驱动程序不支持该函数。

如果调用 SQLCancelHandle，HandleType 设置为SQL_HANDLE_STMT，则可以返回函数 SQLCancel返回的任何 SQLSTATE。

评论

此函数类似于 SQLCancel，但可以采用连接或语句句柄作为参数，而不仅仅是语句句柄。 驱动程序管理器将调用映射到 SQLCancelHandle 调用 SQLCancel 时，HandleType SQL_HANDLE_STMT。 这允许应用程序使用 SQLCancelHandle 来取消语句操作，即使驱动程序未实现 SQLCancelHandle。

有关取消语句操作的详细信息，请参阅 SQLCancel 函数。

如果在 Handle 调用 SQLCancelHandle 没有正在进行的操作，则不起作用。

连接句柄上的 SQLCancelHandle 可以取消以下类型的处理：

  • 在连接上异步运行的函数。

  • 在另一个线程上的连接句柄上运行的函数。

调用 SQLCancelHandle 以取消在连接中异步运行的函数时，SQLCancelHandle 发布的诊断记录将追加到正在取消的操作返回的诊断记录;SQLCancelHandle 在取消在另一个线程上的连接上运行的函数时，不会返回诊断记录。

使用 SQLCancelHandle 取消 SQLEndTran 可能会使连接处于挂起状态。 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。

注意

有关如何在 Windows 7 之前的 Windows 操作系统上部署的应用程序中使用 SQLCancelHandle 的信息，请参阅 兼容性矩阵。

如果函数返回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 函数

另请参阅

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