Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Client message callbacks

Defining a client message callback

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       *message;

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:

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.


	Expand Search