Cancel a command or the results of a command.
CS_RETCODE ct_cancel(connection, cmd, type) CS_CONNECTION *connection; CS_COMMAND *cmd; CS_INT type;
A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.
For CS_CANCEL_CURRENT cancels, connection must be NULL.
For CS_CANCEL_ATTN and CS_CANCEL_ALL cancels, one of connection or cmd must be NULL. If connection is supplied and cmd is NULL, the cancel operation applies to all commands pending for this connection.
A pointer to the CS_COMMAND structure managing a client/server operation.
For CS_CANCEL_CURRENT cancels, cmd must be supplied. The cancel operation applies only to the results pending for this command structure.
For CS_CANCEL_ATTN and CS_CANCEL_ALL cancels, if cmd is supplied and connection is NULL, the cancel operation applies only to the command pending for this command structure. If cmd is NULL and connection is supplied, the cancel operation applies to all commands pending for this connection.
The type of cancel. The following table lists the symbolic values that are legal for type
Value of type |
Result |
Notes |
|---|---|---|
CS_CANCEL_ALL |
ct_cancel sends an attention to the server, instructing it to cancel the current command. Client-Library immediately discards all results generated by the command. |
Causes this connection’s cursors to enter an undefined state. To determine the state of a cursor, an application can call ct_cmd_props with property as CS_CUR_STATUS. |
CS_CANCEL_ATTN |
ct_cancel sends an attention to the server, instructing it to cancel the current command. The next time the application reads from the server, Client-Library discards all results generated by the canceled command. |
Causes this connection’s cursors to enter an undefined state. To determine the state of a cursor, an application can call ct_cmd_props with property as CS_CUR_STATUS. |
CS_CANCEL_CURRENT |
ct_cancel discards the current result set. |
Safe to use on connections with open cursors. |
ct_cancel returns the following values:
Return value |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully. |
CS_FAIL |
The routine failed. |
CS_PENDING |
Asynchronous network I/O is in effect. For more information, see “Asynchronous programming”. |
CS_CANCELED |
The cancel operation was canceled. Only a CS_CANCEL_CURRENT type of cancel can be canceled. |
CS_BUSY |
An asynchronous operation is already pending for this connection. For more information, see “Asynchronous programming”. |
CS_TRYING |
A cancel operation is already pending for this connection. |
if (query_code == CS_FAIL)
{
/*
** Terminate results processing and break out of
** the results loop.
*/
retcode = ct_cancel(NULL, cmd, CS_CANCEL_ALL);
if (retcode != CS_SUCCEED)
{
ex_error("ex_execute_cmd: ct_cancel() failed");
}
break;
}
This code excerpt is from the exutils.c example program.
Canceling a command is equivalent to sending an attention to the server, instructing it to halt execution of the current command. When a command is canceled, any results generated by it are no longer available to an application.
Canceling results is equivalent to fetching and then discarding a result set.Once results are canceled, they are no longer available to an application. If the result set has not been completely processed, subsequent results remain available.
To cancel the current command and all results generated by it, an application calls ct_cancel with type as CS_CANCEL_ATTN or CS_CANCEL_ALL. Both of these calls tell Client-Library to:
Send an attention to the server, instructing it to halt execution of the current command.
Discard any results already generated by the command.
Both types of cancels return CS_SUCCEED immediately, without sending an attention to the server, if no command is in progress.
If an application has not yet called ct_send to send an initiated command or command batch:
A CS_CANCEL_ALL cancel discards the initiated command or command batch without sending an attention to the server. A CS_CANCEL_ATTN cancel has no effect.
A connection can become unusable due to error. If this occurs, Client-Library marks the connection as “dead.” An application can use the CS_CON_STATUS property to determine if a connection has been marked “dead.”
If a connection has been marked “dead” because of a results-processing error, an application can try calling ct_cancel(CS_CANCEL_ALL or CS_CANCEL_ATTN) to revive the connection. If this fails, the application must close the connection and drop its CS_CONNECTION structure.
The difference between CS_CANCEL_ALL and CS_CANCEL_ATTN is:
CS_CANCEL_ALL causes Client-Library to discard the canceled command’s results immediately.
CS_CANCEL_ATTN causes Client-Library to wait until the application attempts to read from the server before discarding the results.
This difference is important because Client-Library must read from the result stream to discard results, and it is not always safe to read from the result stream.
It is not safe to read from the result stream from within callbacks or interrupt handlers, or when an asynchronous routine is pending. It is safe to read from the result stream anytime an application is running in its mainline code, except when an asynchronous operation is pending.
Use CS_CANCEL_ATTN from within callbacks or interrupt handlers or when an asynchronous operation is pending.
Use CS_CANCEL_ALL in mainline code, except when an asynchronous operation is pending.
CS_CANCEL_ALL leaves the command structure in a “clean” state, available for use in another operation. When a command is canceled with CS_CANCEL_ATTN, however, the command structure cannot be reused until a Client-Library routine returns CS_CANCELED.
The Client-Library routines that can return CS_CANCELED are:
ct_cancel(CS_CANCEL_CURRENT)
ct_fetch
ct_get_data
ct_options
ct_recvpassthru
ct_results
ct_send
ct_sendpassthru
CS_CANCEL_ATTN has two primary uses:
To cancel commands from within an application’s interrupt handlers or callback routines.
In asynchronous applications, to cancel pending calls to the result-processing routines ct_results and ct_fetch.
If a command has been sent and ct_results has not been called, a ct_cancel(CS_CANCEL_ATTN) call has no effect.
Canceling commands on a connection that has an open cursor may affect the state of the cursor in unexpected ways. For this reason, it is recommended that the CS_CANCEL_ALL and CS_CANCEL_ATTN types of cancels not be used on connections with open cursors. Instead of canceling a cursor command, an application can simply close the cursor.
To cancel current results, an application calls ct_cancel with type as CS_CANCEL_CURRENT. This tells Client-Library to discard the current results; it is equivalent to calling ct_fetch until it returns CS_END_DATA.
The next buffer’s worth of results, if any, remains available to the application, and the current command is not affected.
Canceling results clears the bindings between the result items and program variables.
A CS_CANCEL_CURRENT type of cancel is legal for all types of result sets, even those that contain no fetchable results. If a result set contains no fetchable results, a cancel has no effect.
