SQLCancel 函数SQLCancel Function

符合性Conformance
版本引入了:ODBC 1.0 标准符合性:ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

摘要Summary
SQLCancel取消上一个语句的处理。SQLCancel cancels the processing on a statement.

若要取消连接或语句的处理,请使用SQLCancelHandle 函数To cancel processing on a connection or statement, use SQLCancelHandle Function.

语法Syntax

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);  

参数Arguments

StatementHandleStatementHandle
[输入]语句句柄。[Input] Statement handle.

返回Returns

SQL_SUCCESS、 SQL_SUCCESS_WITH_INFO、 SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLCancel返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO,关联的 SQLSTATE 值可以通过调用来获取SQLGetDiagRecHandleType的 SQL_HANDLE_STMT 和一个处理StatementHandleWhen SQLCancel returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常返回的 SQLSTATE 值SQLCancel ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。The following table lists the SQLSTATE values commonly returned by SQLCancel and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 常规警告General warning 特定于驱动程序的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
HY000HY000 常规错误General error 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. 返回的错误消息SQLGetDiagRec参数中 *MessageText缓冲区描述错误以及其原因。The error message returned by SQLGetDiagRec in the argument *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 该驱动程序无法分配支持执行或完成该函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY010HY010 函数序列错误Function sequence error (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 此异步函数仍在执行时SQLCancel调用函数。This asynchronous function was still executing when the SQLCancel function was called.

(DM) 取消操作失败,因为与之关联的连接句柄上正在执行异步操作StatementHandle(DM) Cancel operation failed because an asynchronous operation is in progress on a connection handle that is associated with StatementHandle.
HY013HY013 内存管理错误Memory management error 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY018HY018 服务器拒绝取消请求Server declined cancel request 服务器拒绝了取消请求。The server declined the cancel request.
HY117HY117 由于未知的事务状态而挂起连接。Connection is suspended due to unknown transaction state. 仅断开连接,并允许使用只读的函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYT01HYT01 连接超时时间已到Connection timeout expired 连接超时期限过期之前的数据源响应此请求。The connection timeout period expired before the data source responded to the request. 通过设置连接超时期SQLSetConnectAttr,SQL_ATTR_CONNECTION_TIMEOUT。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此函数Driver does not support this function (DM) 驱动程序与相关联StatementHandle不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.

注释Comments

SQLCancel可以取消以下类型的一个语句上的处理:SQLCancel can cancel the following types of processing on a statement:

  • 在帐单上以异步方式运行的函数。A function running asynchronously on the statement.

  • 需要数据的语句上一个函数。A function on a statement that needs data.

  • 在另一个线程中的语句上运行的函数。A function running on the statement on another thread.

在 ODBC 2。x,如果应用程序调用SQLCancel语句上不执行任何处理,是当SQLCancel具有相同的效果SQLFreeStmt SQL_CLOSE 选项;仅出于完整性的考虑定义此行为和应用程序应调用SQLFreeStmtSQLCloseCursor关闭游标。In ODBC 2.x, if an application calls SQLCancel when no processing is being done on the statement, SQLCancel has the same effect as SQLFreeStmt with the SQL_CLOSE option; this behavior is defined only for completeness and applications should call SQLFreeStmt or SQLCloseCursor to close cursors.

SQLCancel调用来取消异步运行一个语句或函数中,会清除的数据需求,由函数正在取消发布的诊断记录,对语句的函数和SQLCancel将发布其自身的诊断记录; 当SQLCancel称为若要取消的语句,另一个线程上运行的函数,但是,它不会清除诊断的记录不取消函数而不会发布其自身的诊断记录。When SQLCancel is called to cancel a function running asynchronously in a statement or a function on a statement that needs data, diagnostic records posted by the function being canceled are cleared, and SQLCancel posts its own diagnostic records; when SQLCancel is called to cancel a function running on a statement on another thread, however, it does not clear the diagnostic records of the being canceled function and does not post its own diagnostic records.

取消异步处理Canceling Asynchronous Processing

应用程序以异步方式调用一个函数后,它会调用重复用于确定它是否已完成处理的函数。After an application calls a function asynchronously, it calls the function repeatedly to determine whether it has finished processing. 如果该函数仍在处理,它将返回 SQL_STILL_EXECUTING。If the function is still processing, it returns SQL_STILL_EXECUTING. 如果该函数已完成处理,则会返回不同的代码。If the function has finished processing, it returns a different code.

任何返回 SQL_STILL_EXECUTING 函数调用后,应用程序可以调用SQLCancel取消函数。After any call to the function that returns SQL_STILL_EXECUTING, an application can call SQLCancel to cancel the function. 如果取消请求成功,驱动程序返回 SQL_SUCCESS。If the cancel request is successful, the driver returns SQL_SUCCESS. 此消息并不表示,该函数已实际取消;它指示已处理取消请求。This message does not indicate that the function was actually canceled; it indicates that the cancel request was processed. 时,或如果实际取消该函数是依赖于驱动程序的代码和数据源决定。When or if the function is actually canceled is driver-dependent and data source-dependent. 应用程序必须继续调用原始函数,直到返回代码不是 SQL_STILL_EXECUTING。The application must continue to call the original function until the return code is not SQL_STILL_EXECUTING. 如果已成功取消该函数,返回代码是 SQL_ERROR 并且 SQLSTATE HY008 (已取消的操作)。If the function was successfully canceled, the return code is SQL_ERROR and SQLSTATE HY008 (Operation canceled). 如果该函数完成其正常处理,返回代码是 SQL_SUCCESS 或如果该函数成功,则 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR 并且以外 HY008 SQLSTATE (已取消的操作) 如果失败的函数。If the function completed its normal processing, the return code is SQL_SUCCESS or SQL_SUCCESS_WITH_INFO if the function succeeded or SQL_ERROR and a SQLSTATE other than HY008 (Operation canceled) if the function failed.

备注

在 ODBC 3.5 中,调用SQLCancel不会进行处理的语句上完成的时不会视为SQLFreeStmt使用 SQL_CLOSE 选项,但具有根本不起作用。In ODBC 3.5, a call to SQLCancel when no processing is being done on the statement is not treated as SQLFreeStmt with the SQL_CLOSE option, but has is no effect at all. 若要关闭游标,应用程序应调用SQLCloseCursor,而非SQLCancelTo close a cursor, an application should call SQLCloseCursor, not SQLCancel.

有关异步处理的详细信息,请参阅异步执行For more information about asynchronous processing, see Asynchronous Execution.

正在取消需要数据的函数Canceling Functions that Need Data

之后SQLExecuteSQLExecDirect返回 SQL_NEED_DATA 和数据已发送的所有执行时数据参数之前,应用程序可以调用SQLCancel取消语句执行。After SQLExecute or SQLExecDirect returns SQL_NEED_DATA and before data has been sent for all data-at-execution parameters, an application can call SQLCancel to cancel the statement execution. 取消该语句后,应用程序可以调用SQLExecuteSQLExecDirect试。After the statement has been canceled, the application can call SQLExecute or SQLExecDirect again. 有关详细信息,请参阅SQLBindParameterFor more information, see SQLBindParameter.

之后SQLBulkOperationsSQLSetPos返回 SQL_NEED_DATA 和数据已发送的所有执行时数据列之前,应用程序可以调用SQLCancel若要取消该操作。After SQLBulkOperations or SQLSetPos returns SQL_NEED_DATA and before data has been sent for all data-at-execution columns, an application can call SQLCancel to cancel the operation. 已取消该操作后,应用程序可以调用SQLBulkOperationsSQLSetPos再次取消不会影响游标状态或当前光标位置。After the operation has been canceled, the application can call SQLBulkOperations or SQLSetPos again; canceling does not affect the cursor state or the current cursor position. 有关详细信息,请参阅SQLBulkOperationsSQLSetPosFor more information, see SQLBulkOperations or SQLSetPos.

正在取消其他线程上执行的函数Canceling Functions Executing on Another Thread

在多线程应用程序中,应用程序可以取消在另一个线程运行的函数。In a multithread application, the application can cancel a function that is running on another thread. 若要取消应用程序调用函数SQLCancel与由目标函数中,而另一个线程上使用的相同的语句句柄。To cancel the function, the application calls SQLCancel with the same statement handle as that used by the target function, but on a different thread. 如何取消该函数依赖于驱动程序和操作系统。How the function is canceled depends on the driver and the operating system. 如取消以异步方式运行的返回代码的函数中所示SQLCancel仅指示驱动程序是否已成功处理该请求。As in canceling a function running asynchronously, the return code of the SQLCancel indicates only whether the driver processed the request successfully. 可以返回仅 SQL_SUCCESS 或 SQL_ERROR;未不返回任何诊断信息。Only SQL_SUCCESS or SQL_ERROR can be returned; no diagnostic information is returned. 如果原始函数已取消,它将返回 SQL_ERROR 和 SQLSTATE HY008 (已取消的操作)。If the original function is canceled, it returns SQL_ERROR and SQLSTATE HY008 (Operation canceled).

如果 SQL 语句时执行SQLCancel上另一个线程取消语句执行调用,则可能会成功执行和取消时返回 SQL_SUCCESS 也是成功。If an SQL statement is being executed when SQLCancel is called on another thread to cancel the statement execution, it is possible for the execution to succeed and return SQL_SUCCESS while the cancel is also successful. 在这种情况下,驱动程序管理器假定使应用程序将无法再使用游标通过取消,关闭打开的语句执行游标。In this case, the Driver Manager assumes that the cursor opened by the statement execution is closed by the cancel, so the application will not be able to use the cursor.

关于线程处理的详细信息,请参阅多线程处理For more information about threading, see Multithreading.

有关信息For information about 请参阅See
绑定到参数的缓冲区Binding a buffer to a parameter SQLBindParameter 函数SQLBindParameter Function
执行大容量插入或更新操作Performing bulk insert or update operations SQLBulkOperations 函数SQLBulkOperations Function
取消异步上运行连接句柄,此外对功能的一个函数SQLCancelCancels a function running asynchronously on a connection handle, in addition to the functionality of SQLCancel. SQLCancelHandle 函数SQLCancelHandle Function
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
释放语句句柄Freeing a statement handle SQLFreeStmtSQLFreeStmt
获取诊断记录的字段或诊断标头的字段Obtaining a field of a diagnostic record or a field of the diagnostic header SQLGetDiagField 函数SQLGetDiagField Function
获取多个字段的诊断数据结构Obtaining multiple fields of a diagnostic data structure SQLGetDiagRec 函数SQLGetDiagRec Function
返回下一个参数将数据发送用于Returning the next parameter to send data for SQLParamData 函数SQLParamData Function
在执行时发送参数数据Sending parameter data at execution time SQLPutData 函数SQLPutData Function
将光标放置在行集中,刷新的行集中的数据或更新或删除结果集中的数据Positioning the cursor in a rowset, refreshing data in the rowset, or updating or deleting data in the result set SQLSetPos 函数SQLSetPos Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files