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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT， 句柄 为 StatementHandle。 下表列出了 SQLCancel 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在参数 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLCancel 函数时，此异步函数仍在执行。

(DM) Cancel 操作失败，因为异步操作正在进行与 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 函数

另请参阅

ODBC API 参考
ODBC 头文件