Version Introduced: ODBC 1.0
Standards Compliance: ISO 92
SQLCancel cancels the processing on a statement.
SQLRETURN SQLCancel( SQLHSTMT StatementHandle);
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
When 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. 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. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
|01000||General warning||Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)|
|HY000||General error||An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec in the argument *MessageText buffer describes the error and its cause.|
|HY001||Memory allocation error||The driver was unable to allocate memory required to support execution or completion of the function.|
|HY013||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.|
|HY018||Server declined cancel request||The server declined the cancel request.|
|HYT01||Connection timeout expired||The connection timeout period expired before the data source responded to the request. The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.|
|IM001||Driver does not support this function||(DM) The driver associated with the StatementHandle does not support the function.|
SQLCancel can cancel the following types of processing on a statement:
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.
When SQLCancel is called, diagnostic records are returned for a function running asynchronously in a statement or for a function on a statement that needs data; diagnostic records are not returned, however, for a function running on a statement on another thread.
After an application calls a function asynchronously, it calls the function repeatedly to determine whether it has finished processing. If the function is still processing, it returns SQL_STILL_EXECUTING. If the function has finished processing, it returns a different code.
After any call to the function that returns SQL_STILL_EXECUTING, an application can call SQLCancel to cancel the function. 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 sourcedependent. The application must continue to call the original function until the return code is not SQL_STILL_EXECUTING. If the function was successfully canceled, the return code is SQL_ERROR and SQLSTATE HY008 (Operation canceled). 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.
Note 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. To close a cursor, an application should call SQLCloseCursor, not SQLCancel.
For more information about asynchronous processing, see "Asynchronous Execution" in Chapter 9: Executing Statements.
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. After the statement has been canceled, the application can call SQLExecute or SQLExecDirect again. For more information, see SQLBindParameter.
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. 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. For more information, see SQLBulkOperations or SQLSetPos.
In a multithread application, the application can cancel a function that is running synchronously on a statement. 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. As in canceling a function running asynchronously, the return code of the SQLCancel indicates only whether the driver processed the request successfully. Only SQL_SUCCESS or SQL_ERROR can be returned; no SQLSTATEs are returned. If the original function is canceled, it returns SQL_ERROR and SQLSTATE HY008 (Operation canceled).
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" in Chapter 17: Programming Considerations.
|For information about||See|
|Binding a buffer to a parameter||SQLBindParameter|
|Performing bulk insert or update operations||SQLBulkOperations|
|Executing an SQL statement||SQLExecDirect|
|Executing a prepared SQL statement||SQLExecute|
|Freeing a statement handle||SQLFreeStmt|
|Obtaining a field of a diagnostic record or a field of the diagnostic header||SQLGetDiagField|
|Obtaining multiple fields of a diagnostic data structure||SQLGetDiagRec|
|Returning the next parameter to send data for||SQLParamData|
|Sending parameter data at execution time||SQLPutData|
|Positioning the cursor in a rowset, refreshing data in the rowset, or updating or deleting data in the result set||SQLSetPos|