ct_cancel

Cancels a request or the results of a request.

CS_RETCODE ct_cancel(connection, command, type);
CS_CONNECTION *connection;
CS_COMMAND    *command;
CS_INT        type;

connection: (I) Handle for this connection. This connection handle must already be allocated with ct_con_alloc. The connection handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.

Either connection or command must be null. If connection is supplied and command is null, the cancel operation applies to all commands pending for this connection.

command: (I) Handle for this client/server operation. This handle is defined in the associated ct_cmd_alloc call. The command handle also corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.

Either connection or command must be null. If command is supplied and connection is null, the cancel operation applies only to the command pending for this command structure.

type: (I) Type of cancel requested. The following table lists the symbolic values that are legal for type:

Value

Meaning

CS_CANCEL_ALL (6001) or CS_CANCEL_ATTN (6002)

ct_cancel sends an attention to the server, instructing it to cancel the current request, and immediately discards all results generated by the request.

Value	Meaning
CS_CANCEL_ALL (6001) or CS_CANCEL_ATTN (6002)	ct_cancel sends an attention to the server, instructing it to cancel the current request, and immediately discards all results generated by the request.

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

ct_cancel 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 ct_cancel with type 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 ct_cancel with type as CS_CANCEL_ALL or CS_CANCEL_ATTN must be immediately followed by a ct_results call.
In Client-Library, canceling with type as CS_CANCEL_ALL or CS_CANCEL_ATTN leaves the command structure in a “clean” state, available for use by another operation.
For both the CS_CANCEL_ATTN and CS_CANCEL_ALL types of cancels, if no request is in progress, ct_cancel returns CS_SUCCEED immediately.
If a request was initiated but not yet sent, a CS_CANCEL_ALL is rejected.