The CS_ASYNC_NOTIFS connection property controls how a Client-Library application receives registered procedure notifications from an Open Server application. CS_ASYNC_NOTIFS determines whether a connection will receive registered procedure notifications asynchronously.
The Open Server application sends a notification to the client as one or more TDS packets. The client application does not learn of the notification until Client-Library reads the notification packets from the connection and invokes the application’s notification callback.
Registered procedure notifications allow clients to watch for execution of one or more registered procedures on an Open Server. When a watched procedure is executed by any client, Open Server sends a notification to each client that is watching that particular registered procedure.
The server sends the notification as one or more Tabular Data Stream packets. For the application to learn about notifications, Client-Library must read these packets and trigger the application’s notification callback. The CS_ASYNC_NOTIFS property determines how the application learns about notifications:
An otherwise synchronous connection receives asynchronous notifications by setting CS_ASYNC_NOTIFS to CS_TRUE.
An asynchronous connection does not receive notifications asynchronously unless it sets CS_ASYNC_NOTIFS to CS_TRUE.
On a connection that is used only to receive notifications, ct_poll does not look for notifications unless CS_ASYNC_NOTIFS is CS_TRUE.
When CS_ASYNC_NOTIFS is set to CS_TRUE, Client-Library interrupts the application to report an arriving registered procedure notification.
On platforms that support interrupt- or thread-driven I/O, Client-Library automatically reads the notification information and invokes the connection’s notification callback when a notification arrives on the connection.
On other platforms, if the connection is not otherwise active, it must be polled with ct_poll to trigger the notification callback. CS_ASYNC_NOTIFS must be CS_TRUE for ct_poll to trigger the notification callback on an otherwise idle connection.
When CS_ASYNC_NOTIFS is CS_FALSE (the default), the application must be reading from the network for Client-Library to report a registered procedure notification. When the server sends a notification, Client-Library reads the notification data and triggers the application’s notification callback the next time it interacts with the server.
Likewise, if CS_ASYNC_NOTIFS is CS_FALSE, ct_poll does not read notification data from the network and trigger the application’s notification callback. This means that an application must be reading results for ct_poll to report a registered procedure notification. When ct_poll reports the notification, the application’s notification callback is automatically called.
If a connection is used only for receiving registered
procedure notifications, CS_ASYNC_NOTIFS must
be set to CS_TRUE to
receive the notification. Asynchronous notifications must be enabled
even if the connection is polled with ct_poll.
The following fragment enables asynchronous notifications.
/* Turn on read-ahead notifications. */
boolval = CS_TRUE;
if (ct_con_props(conn, CS_SET, CS_ASYNC_NOTIFS, &boolval,
CS_UNUSED, (CS_INT *)NULL)! CS_SUCCEED)
{
fprintf(stderr,
"Error: ct_con_props(SET, CS_ASYNC_NOTIFS) failed\n");
(CS_VOID)ct_close(conn, CS_UNUSED);
(CS_VOID)ct_con_drop(conn);
}
Setting CS_ASYNC_NOTIFS to CS_FALSE does not immediately turn off asynchronous notifications. To turn off asynchronous notifications, an application must send a command to the server after setting CS_ASYNC_NOTIFS to CS_FALSE.
CS_ASYNC_NOTIFS is the only property that determines whether notifications are received asynchronously:
An otherwise synchronous connection receives asynchronous notifications.
An asynchronous connection does not receive notifications asynchronously unless it sets CS_ASYNC_NOTIFS to CS_TRUE.
For information about registered procedure notifications, see “Registered procedures”.
