SQLCancel 函数
一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
总结
SQLCancel 取消对语句的处理。
若要取消对连接或语句的处理，请使用 SQLCancelHandle 函数。
语法
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
参数
StatementHandle
[输入]语句句柄。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。
诊断
当 SQLCancel 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLCancel 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 参数 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLCancel 函数时，此异步函数仍在执行。 （DM） 由于与 StatementHandle 关联的连接句柄正在进行异步操作，因此取消操作失败。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY018 | 服务器拒绝的取消请求 | 服务器拒绝了取消请求。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 StatementHandle 关联的驱动程序不支持该函数。 |
注释
SQLCancel 可以取消语句的以下处理类型：
在语句上异步运行的函数。
需要数据的语句的函数。
在另一个线程上的语句上运行的函数。
在 ODBC 2 中。x，如果在语句上未执行任何处理时应用程序调用 SQLCancel，则 SQLCancel 与 SQLFreeStmt 具有与 SQL_CLOSE 选项相同的效果;仅针对完整性定义此行为，应用程序应调用 SQLFreeStmt 或 SQLCloseCursor 来关闭游标。
当调用 SQLCancel 以异步方式在语句或需要数据的语句上运行的函数时，将清除由取消函数发布的诊断记录，SQLCancel 会发布自己的诊断记录;当调用 SQLCancel 以取消在另一个线程上的语句上运行的函数时，它不会清除被取消函数的诊断记录，也不会发布自己的诊断记录。
取消异步处理
在应用程序异步调用函数后，它会重复调用该函数以确定函数是否已完成处理。 如果函数仍在处理，它将返回SQL_STILL_EXECUTING。 如果函数已完成处理，则返回其他代码。
对返回SQL_STILL_EXECUTING函数的任何调用后，应用程序可以调用 SQLCancel 来取消该函数。 如果取消请求成功，驱动程序将返回SQL_SUCCESS。 此消息不指示该函数实际上已取消；它指示已处理取消请求。 当或是否实际取消函数依赖于驱动程序和数据源依赖时。 应用程序必须继续调用原始函数，直到返回代码未SQL_STILL_EXECUTING。 如果函数已成功取消，则返回代码SQL_ERROR SQLSTATE HY008（操作已取消）。 如果函数完成正常处理，则返回代码SQL_SUCCESS或SQL_SUCCESS_WITH_INFO如果函数成功或SQL_ERROR，如果函数失败，则返回代码为 HY008 以外的 SQLSTATE（操作已取消）。
注意
在 ODBC 3.5 中，当未对语句执行任何处理时，对 SQLCancel 的调用不会被视为具有SQL_CLOSE选项的 SQLFreeStmt，但根本不起作用。 要关闭游标，应用程序应调用 SQLCloseCursor，而非 SQLCancel。
有关异步处理的详细信息，请参阅 异步执行。
取消需要数据的函数
在 SQLExecute 或 SQLExecDirect 返回SQL_NEED_DATA，并在为所有数据执行参数发送数据之前，应用程序可以调用 SQLCancel 来取消语句执行。 取消语句后，应用程序可以再次调用 SQLExecute 或 SQLExecDirect 。 有关详细信息，请参阅 SQLBindParameter。
在 SQLBulkOperations 或 SQLSetPos 返回SQL_NEED_DATA，并在为执行时的所有数据列发送数据之前，应用程序可以调用 SQLCancel 来取消该操作。 取消操作后，应用程序可以再次调用 SQLBulkOperations 或 SQLSetPos ;取消不会影响游标状态或当前游标位置。 有关详细信息，请参阅 SQLBulkOperations 或 SQLSetPos。
取消在另一个线程上执行的函数
在多线程应用程序中，应用程序可以取消在另一个线程上运行的函数。 若要取消该函数，应用程序使用与目标函数使用的语句句柄相同的语句句柄调用 SQLCancel ，但在不同的线程上。 取消函数的方式取决于驱动程序和操作系统。 与取消异步运行的函数一样，SQLCancel 的返回代码仅指示驱动程序是否已成功处理请求。 只能返回SQL_SUCCESS或SQL_ERROR;不返回诊断信息。 如果原始函数已取消，它将返回SQL_ERROR和 SQLSTATE HY008（操作已取消）。
如果在另一个线程上调用 SQLCancel 来取消语句执行时执行 SQL 语句，则执行可能会成功并返回SQL_SUCCESS同时取消。 在这种情况下，驱动程序管理器假定语句执行打开的游标由取消关闭，因此应用程序将无法使用游标。
有关线程处理的详细信息，请参阅 多线程处理。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到参数 | SQLBindParameter 函数 |
| 执行批量插入或更新操作 | SQLBulkOperations 函数 |
| 除了 SQLCancel 的功能外，取消在连接句柄上异步运行的函数。 | SQLCancelHandle 函数 |
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备的 SQL 语句 | SQLExecute 函数 |
| 释放语句句柄 | SQLFreeStmt |
| 获取诊断记录的字段或诊断标头的字段 | SQLGetDiagField 函数 |
| 获取诊断数据结构的多个字段 | SQLGetDiagRec 函数 |
| 返回要为其发送数据的下一个参数 | SQLParamData 函数 |
| 在执行时发送参数数据 | SQLPutData 函数 |
| 将光标定位在行集中、刷新行集中的数据或更新或删除结果集中的数据 | SQLSetPos 函数 |