Database Events
A database event is a notification to an application that a specific condition has occurred.
An application processes database events with the following SQL statements:
register dbevent
Registers to receive event notifications. After register dbevent is executed, the application retrieves events with IIapi_catchEvent().
remove dbevent
Removes an event for which an application has previously registered.
Order in which OpenAPI Creates, Retrieves, and Deletes Database Events
How Database Events Are Processed
The application calls IIapi_getQueryInfo() and IIapi_close() after each call to IIapi_query(), shown in the illustration. Additional SQL statements are used to create, drop, and raise database events.
Note: For a description and usage of these statements, see the SQL Reference Guide.
IIapi_catchEvent() registers a callback function to be called when a database event notification is received. IIapi_catchEvent() operates similarly to the embedded SQL statement SET_SQL(DBEVENTHANDLER = dbevent_handler). IIapi_catchEvent() cannot be used in synchronous mode; it is inherently asynchronous.
For each call to IIapi_catchEvent(), only one database event notification will be returned. To receive multiple database events, IIapi_catchEvent() must be called every time OpenAPI returns a database event notification to the application. Rather than closing and repeatedly re-allocating event handles, an event handle passed to the application callback function can be re-activated by providing it as input to IIapi_catchEvent().
The server can send database event notifications with other query results. When OpenAPI receives a database event notification, OpenAPI processes the event and calls the the application callback function for any event handles matching the database event.
Database event notifications can also be sent by the server between client queries. OpenAPI provides a function, IIapi_getEvent(), which can be used to check for database events between queries or if the application desires only to wait for database event notification without performing other database operations.
IIapi_getEvent() waits for a database event notification to be sent by the server on a particular connection. No other request may be made on the connection until IIapi_getEvent() completes. A timeout value can be specified when calling IIapi_getEvent() so that the application can poll for database event notifications. IIapi_getEvent() operates similarly to the embedded SQL statement GET DBEVENT.
IIapi_getEvent() does not return database event notifications directly. To receive database events, the application must still issue an IIapi_catchEvent() request prior to calling IIapi_getEvent(). When received by IIapi_getEvent(), OpenAPI processes a database event notification and calls the application callback function for any event handles matching the database event.
Matching criteria specified when calling IIapi_catchEvent() permits an application to filter database events by name and owner. Database event notifications are compared to all active event handles and may result in callbacks for none, some, or all handles depending on the filtering information.
Since it is possible for a database event notification to be received but not matched to any active event handle, an additional callback function can be registered on the environment handle using IIapi_setEnvParm(). This callback function is called for each database event notification that fails to match an active event handle. An event handle is not passed to the callback function, but the output information available from IIapi_catchEvent() is passed to the callback function as a structure parameter.
Last modified date: 08/14/2024