Cancels a request or the results of a request.
%INCLUDE CTPUBLIC;
DCL 01 CONNECTION FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 COMMAND FIXED BIN(31) INIT(0); 01 CANCELTYPE FIXED BIN(31); CALL CTBCANCE (CONNECTION, RETCODE, COMMAND, CANCELTYPE);
(I) Handle for this connection. This connection handle must already be allocated with CTBCONALLOC. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
Either CONNECTION or COMMAND must be null (zeroes). If CONNECTION is supplied and COMMAND is empty, the cancel operation applies to all commands pending for this connection.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(I) Handle for this client/server operation. This handle is defined in the associated CTBCMDALLOC call. The command handle also corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.
Either CONNECTION or COMMAND must be zeroes. If COMMAND is supplied and CONNECTION is zeroes, the cancel operation applies only to the command pending for this command structure.
(I) Type of cancel requested. The following table lists the symbolic values that are legal for CANCELTYPE:
Value |
Meaning |
|---|---|
CS_CANCEL_ALL (6001) or CS_CANCEL_ATTN (6002) |
CTBCANCEL sends an attention to the server, instructing it to cancel the current request, and immediately discards all results generated by the request. |
CTBCANCEL returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
The routine completed successfully. |
CS_FAIL (-2) |
The routine failed. |
TDS_CONNECTION_TERMINATED (-4997) |
The connection is not active. |
TDS_INVALID_TDPROC (-18) |
Specified command handle is invalid. |
TDS_WRONG_STATE (-6) |
Program is in the wrong communication state to issue this call. |
CTBCANCEL cancels the current result set.
Canceling the current result set is equivalent to discarding the current set of results. Once results are discarded, they are no longer available to an application.
In Open ClientConnect, CS_CANCEL_ALL and CS_CANCEL_ATTN function identically. Both immediately cancel the current request and discard all results generated by it.
To cancel the current request and all results generated by it, an application calls CTBCANCEL with CANCELTYPE as CS_CANCEL_ATTN or CS_CANCEL_ALL. These calls tell Client-Library to:
Discard all results already generated by the request.
Send an attention to the server instructing it to halt execution of the current request.
For example, suppose the current request is a Transact-SQL language request that contains the queries:
select * from titles select * from authors
If an application cancels the language request after the first query executes but before the second query executes:
All remaining results from the first query are discarded.
Execution of the second query is halted.
A call to CTBCANCEL with CANCELTYPE as CS_CANCEL_ALL
or CS_CANCEL_ATTN must be immediately followed
by a CTBRESULTS call.
In Open Client Client-Library, canceling with CANCELTYPE as CS_CANCEL_ALL or CS_CANCEL_ATTN leaves the command structure in a “clean” state, available to be used for another operation.
For both the CS_CANCEL_ATTN and CS_CANCEL_ALL types of cancels, if no request is in progress, CTBCANCEL returns CS_SUCCEED immediately.
If a request initiates but has not been sent, a CS_CANCEL_ALL is rejected.
Related functions:
