Open Client Client-Library/C Reference Manual

Home

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Notification callbacks

A registered procedure is a procedure that is defined and installed in a running Open Server. A Client-Library application uses a remote procedure call command to execute a registered procedure, and also "watches" for a registered procedure to be executed by another application or by the application itself.

To watch for the execution of a registered procedure, a Client-Library application must be connected to the host Open Server. The client application remotely calls the Open Server sp_regwatch system registered procedure.

When a registered procedure executes, applications watching for it receive a notification that includes the procedure's name and the arguments it was called with. Client-Library receives the notification (via the connection to the Open Server) and calls the application's notification callback routine.

The CS_ASYNC_NOTIFS property determines how the notification callback is triggered. See the description of this property under "Asynchronous notifications".

The arguments with which the registered procedure was called are available inside the notification callback as a parameter result set. To retrieve these arguments, an application:

Calls ct_con_props(CS_NOTIF_CMD) to retrieve a pointer to the command structure containing the parameter result set
Calls ct_res_info(CS_NUMDATA), ct_describe, ct_bind, ct_fetch, and ct_get_data to describe, bind, and fetch the parameters

For more information on registered procedures and notifications, see the "Registered procedures".

Defining a notification callback

A notification callback is defined as follows:

CS_RETCODE CS_PUBLIC 
 notification_cb(conn, proc_name, namelen)
 
 CS_CONNECTION    *conn;
 CS_CHAR                  *proc_name;
 CS_INT                       namelen;

where:

connection is a pointer to the CS_CONNECTION structure receiving the notification. This CS_CONNECTION is the parent connection of the CS_COMMAND that sent the request to be notified.
proc_name is a pointer to the name of the registered procedure that has been executed.
namelen is the length, in bytes, of *proc_name.

A notification callback must return CS_SUCCEED.

Table 2-5 lists the Client-Library routines that a notification callback calls:

Routines that a notification 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 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_NOTIF_CMD) call.
ct_cancel(CS_CANCEL_ATTN)	Any circumstances.
ct_bind, ct_describe, ct_fetch, ct_get_data, ct_res_info(CS_NUMDATA)	To retrieve the notification parameter values. The routines must be called with the command structure returned by the callback's ct_con_props(CS_NOTIF_CMD) call.

Retrieving notification parameters

The parameter values with which a registered procedure was invoked are available in the notification callback. To get the values, the application retrieves the command structure stored as the CS_NOTIF_CMD connection property. Using this command structure, the application retrieves the parameter values with the usual calls to ct_res_info(CS_NUMDATA), ct_describe, and ct_fetch.

See "Registered procedures".


	Expand Search