Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Client message callbacks

An application handles Client-Library error and informational messages inline or through a client message callback routine.

When a connection is allocated, it picks up a default client message callback from its parent context. If the parent context has no client message callback installed, then the connection is created without a default client message callback.

After allocating a connection, an application:

Installs a different client message callback for the connection.
Calls ct_diag to initialize inline message handling for the connection. Note that ct_diag automatically deinstalls all message callbacks for the connection.

If a client message callback is not installed for a connection or its parent context and inline message handling is not enabled, Client-Library discards message information.

If callbacks are not implemented for a particular programming language or platform version of Client-Library, an application must handle Client-Library messages inline, using ct_diag.

If a connection is handling Client-Library messages through a client message callback, then the callback is called whenever Client-Library generates an error or informational message.

The exception to this rule is that Client-Library does not call the client message callback when a message is generated from within most types of callback routines. Client-Library does call the client message callback when a message is generated within a completion callback. That is, if a Client-Library routine fails within a callback routine other than the completion callback, the routine returns CS_FAIL but does not trigger the client message callback.

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.

Client message callback example

This is an example of a client message callback:

/*

         ** ex_clientmsg_cb()

**

         ** Type of function:

         **      Example program client message handler

**

         ** Purpose:

         **      Installed as a callback into Open Client.

**

         ** Returns:

         **      CS_SUCCEED

**

         ** Side Effects:

         **      None

*/

        CS_RETCODE CS_PUBLIC

         ex_clientmsg_cb(context, connection, errmsg)

         CS_CONTEXT        *context

         CS_CONNECTION     *connection;

         CS_CLIENTMSG      *errmsg;

             fprintf(EX_ERROR_OUT, "\nOpen Client Message:\n");

             fprintf(EX_ERROR_OUT, "Message number:

                 LAYER = (%ld) ORIGIN = (%ld) ",

                 CS_LAYER(errmsg->msgnumber),

                 CS_ORIGIN(errmsg->msgnumber));

             fprintf(EX_ERROR_OUT, "SEVERITY = (%ld)

                 NUMBER = (%ld)\n",

                 CS_SEVERITY(errmsg->msgnumber),

                 CS_NUMBER(errmsg->msgnumber));

             fprintf(EX_ERROR_OUT, "Message String: %s\n",

                 errmsg->msgstring);

             if (errmsg->osstringlen > 0)

                 fprintf(EX_ERROR_OUT, "Operating System \

                     Error: %s\n", errmsg->osstring);

            return CS_SUCCEED;


	Expand Search