A client message callback is defined as follows:
CS_RETCODE CS_PUBLIC clientmsg_cb(context, connection, message) CS_CONTEXT *context; CS_CONNECTION *connection; CS_CLIENTMSG *msg;
where:
context is a pointer to the CS_CONTEXT structure for which the message occurred.
connection is a pointer to the CS_CONNECTION structure for which the message occurred. connection can be NULL.
message is a pointer to a CS_CLIENTMSG structure containing Client-Library message information. For information about this structure, see the section, “Client-Library and SQL Structures”.
Note that message can have a new value each time the client message callback is called.
A client message callback must return either CS_SUCCEED or CS_FAIL:
CS_SUCCEED instructs Client-Library to continue any processing that is occurring on this connection.
If the callback was invoked due to a timeout error, returning CS_SUCCEED causes Client-Library to wait for the duration of a full timeout period before calling the client message callback again. It continues this behavior until either the command succeeds without timing out or until the server cancels the current command in response to a ct_cancel(CS_CANCEL_ATTN) call from the client message callback.
In some cases a server may be unable to respond to a
client’s ct_cancel command.
Such a situation can occur, for example, if the server is processing
a very complex query and is not in an interruptible state.
CS_FAIL instructs Client-Library to terminate any processing that is currently occurring on this connection. A return of CS_FAIL results in the connection being marked as “dead”, or unusable. To continue using the connection, the application must close the connection and reopen it.
Table 2-3 lists the Client-Library routines that a client message callback can call:
Callable routine |
Permitted use |
|---|---|
ct_config |
To retrieve information only |
ct_con_props |
To retrieve information or to set the CS_USERDATA property only |
ct_cmd_props |
To retrieve information or to set the CS_USERDATA property only |
ct_cancel (CS_CANCEL_ATTN) |
Any circumstances |
Most applications use a client message callback that simply displays the error details or logs them to a file. However, some applications may require a callback that recognizes certain errors and takes specific action. See “Handling specific Client-Library messages” for more information on how this is done.
