Chapter 2: Functions

CTBCANCEL

Description

Cancels a request or the results of a request.

Syntax

01 CONNECTION PIC S9(9) COMP SYNC.
01 RETCODE PIC S9(9) COMP SYNC.
01 COMMAND PIC S9(9) COMP SYNC.
01 CANCELTYPE PIC S9(9) COMP SYNC.

CALL 'CTBCANCE' USING CONNECTION RETCODE 
COMMAND CANCELTYPE.

Parameters

CONNECTION

(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 (LOW-VALUES). If CONNECTION is supplied and COMMAND is LOW-VALUES, the cancel operation applies to all commands pending for this connection.

RETCODE: (O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Return values,” in this section.

COMMAND

(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 LOW-VALUES. If COMMAND is supplied and CONNECTION is LOW-VALUES, the cancel operation applies only to the command pending for this command structure.

CANCELTYPE

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

Returns

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.

Usage

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.

Canceling a request

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.