Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Server message callbacks

An application handles server errors and informational messages inline or through a server message callback routine.

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

After allocating a connection, an application:

Installs a different server 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 server message callback is not installed and inline message handling is not enabled, Client-Library discards the server message information.

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

If a connection is handling server messages through a server message callback, then the callback is called whenever a server message arrives.

Defining a server message callback

A server message callback is defined as follows:

CS_RETCODE CS_PUBLIC 
 servermsg_cb(context, connection, message)
 
 CS_CONTEXT           *context;
 CS_CONNECTION    *connection;
 CS_SERVERMSG      *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.
message is a pointer to a CS_SERVERMSG structure containing server message information. For information on this structure, see the "CS_SERVERMSG structure".
Note that message can have a new value each time the server message callback is called.
A server message callback must return CS_SUCCEED.

Routines that a server message callback can call
Callable routines	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 only. The CS_USERDATA property can be set on command structures allocated with ct_cmd_alloc. The CS_USERDATA property cannot be set on the command structure obtained by the callback's ct_con_props(CS_EED_CMD) call.
ct_cancel(CS_CANCEL_ATTN)	Any circumstances.
ct_bind, ct_describe, ct_fetch, ct_get_data, ct_res_info	The routines must be called with the command structure returned by the callback's ct_con_props(CS_EED_CMD) call. A server message callback calls these routines only while extended error data is available; that is, until ct_fetch returns CS_END_DATA. See "Extended error data".

Warning!

Do not call ct_poll from within any Client-Library callback function or from within any other function that can execute at the system-interrupt level.

Calling ct_poll at the system-interrupt level can corrupt Open Client/Server internal resources and cause recursion in the application.

Server message callback example

This is an example of a server message callback:

/*

           ** ex_servermsg_cb()

**

           ** Type of function:

           **      Example program server message handler

**

           ** Purpose:

           **      Installed as a callback into Open Client.

**

           ** Returns:

           **      CS_SUCCEED

**

           ** Side Effects:

           **      None

*/

           CS_RETCODE CS_PUBLIC

           ex_servermsg_cb(context, connection, srvmsg)

           CS_CONTEXT        *connection;

           CS_CONNECTION     *cmd;

           CS_SERVERMSG      *srvmsg;

                fprintf(EX_ERROR_OUT, "\nServer message:\n");

                fprintf(EX_ERROR_OUT, "Message number: %ld, \

                     Severity %ld, ", srvmsg->msgnumber,

                     srvmsg->severity);

                fprintf(EX_ERROR_OUT, "State %ld, Line %ld",

                     srvmsg->state, srvmsg->line);

               if (srvmsg->svrnlen > 0)

                     fprintf(EX_ERROR_OUT, "\nServer '%s'",

                          srvmsg->svrname);

               if (srvmsg->proclen > 0)

                     fprintf(EX_ERROR_OUT, " Procedure '%s'",

                          srvmsg->proc);

               fprintf(EX_ERROR_OUT, "\nMessage String: %s",

                     srvmsg->text);

               return CS_SUCCEED;

Handling specific messages

In some applications, the programmer may want to code special handling for certain message numbers.

For example, if a message is known to be informational and not an error message, you may not want the application to display the message to the end user. The example below shows a fragment from a server message callback that does not display messages 5701, 5703, or 5704. Adaptive Server always sends a 5701 message when a connection is opened and may also send the other two. Adaptive Server also sends a 5701 message after every successful use database command. Some end users may not want to see such messages. If the code shown below is placed at the top of the server message callback, these message numbers are ignored:

/*

   ** Ignore these Server messages:

   **  5701 (changed database),

   **  5703 (changed language),

   **  or 5704 (changed client character set)

*/

   if (srvmsg->msgnumber == 5701

       || srvmsg->msgnumber == 5703

       || srvmsg->msgnumber == 5704)

     return CS_SUCCEED;

This code is specific to Adaptive Server. These message numbers may mean something else entirely when connected to another type of server, such as an Open Server gateway or a custom Open Server application.


	Expand Search