Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Registered procedures

Registered procedures

A registered procedure is a procedure that is defined and installed in a running Open Server application, and extends the functionality of Adaptive Server.

For Client-Library applications, registered procedures provide a means for inter-application communication and synchronization. This is because Client-Library applications connected to an Open Server watches for a registered procedure to execute. When the registered procedure executes, applications watching for it receive a notification that includes the procedure's name and the arguments it was called with.

For example, suppose that:

• stockprice is a real-time Client-Library application monitoring stock prices.

• price_change is a registered procedure created in Open Server by stockprice, and that price_change takes as parameters a stock name and a price differential.

• sellstock, an application that puts stock up for sale, has requested that it be notified when price_change executes.

When stockprice, the monitoring application, becomes aware that the price of Extravagant Auto Parts stock has risen $1.10, it executes price_change with the parameters "Extravagant Auto Parts" and "+1.10".

When price_change executes, Open Server sends sellstock a notification containing the name of the procedure (price_change) and the arguments passed to it ("Extravagant Auto Parts" and "+1.10"). sellstock uses the information contained in the notification to decide whether or not to sell Extravagant Auto Parts stock.

price_change is the means through which the stockprice and sellstock applications communicate.

Registered procedures as a means of communication have the following advantages:

• A single call to execute a registered procedure results in many client applications being notified that the procedure has executed. The application executing the procedure does not need to know how many, or which, clients have requested information.

• The registered procedure communication mechanism is server-based. Open Server acts as a central repository for connection addresses. Because of this, client applications communicate without having to connect directly to each other. Instead, each client simply connects to the Open Server.

A Client-Library application makes remote procedure calls to Open Server system registered procedures to:

• Create a registered procedure in Open Server.

  A Client-Library application creates only registered procedures that contain no executable statements. These bodiless procedures are primarily useful for communication and synchronization purposes.

• Drop a registered procedure.

• List all registered procedures defined in Open Server.

• Request to be notified when a particular registered procedure is executed.

• List all registered procedure notifications that the client connection is waiting for.

• Execute a registered procedure.

For more information about Open Server system registered procedures, see the Open Server Server-Library/C Reference Manual.

An application calls Client-Library routines to:

• Install a user-supplied notification callback routine to be called when the application receives notification that a registered procedure has executed

• Poll the network (if necessary) to see if any registered procedure notifications are waiting

When Client-Library receives a notification

When Client-Library receives a registered procedure notification, it calls an application's notification callback routine. Depending on the host client platform, the application may have to poll the network (with ct_poll) for Client-Library to invoke the notification callback. See "Receiving notifications asynchronously".

The registered procedure's name is available as the second parameter to the notification callback routine.

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

See "Notification callbacks".

Receiving notifications asynchronously

The application's receipt of notification events depends on the CS_ASYNC_NOTIFS property and the network I/O methods supported by the client platform.

The CS_ASYNC_NOTIFS property determines whether a connection receives notifications asynchronously. See "Asynchronous notifications".

When the connection to the Open Server has little or no activity other than notifications, asynchronous notifications should be enabled by setting the CS_ASYNC_NOTIFS property to CS_TRUE. This property defaults to CS_FALSE, which means that the application must be interacting with the server over the connection (to cause Client-Library to read from the network) to receive a registered procedure notification.

If a connection is used only to receive registered procedure notifications, asynchronous notifications must be enabled for a connection even if the connection is polled. On an otherwise idle connection, ct_poll does not trigger the notification callback unless the CS_ASYNC_NOTIFS property is CS_TRUE. The default setting is CS_FALSE.

If asynchronous notifications are enabled on platforms that support signal- or thread-driven I/O, then Client-Library automatically invokes a connection's notification callback when a notification arrives on the connection.

On other platforms, the application must poll the connection with ct_poll if the connection is not otherwise active. CS_ASYNC_NOTIFS must be set to CS_TRUE for ct_poll to report notifications.