MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 21: ODBC API Reference

SQLCancel

Conformance

Version Introduced: ODBC 1.0
Standards Compliance: ISO 92

Summary

SQLCancel cancels the processing on a statement.

Syntax

SQLRETURN SQLCancel(
     SQLHSTMT     StatementHandle);

Arguments

StatementHandle

[Input]
Statement handle.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

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.

Comments

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.

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.

Canceling Asynchronous Processing

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 source–dependent. 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."

Canceling Functions that Need Data

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.

Canceling Functions in Multithread Applications

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."

Related Functions