How a Database Event is Received
To receive a database event and its associated information, an application must perform two steps:
1. Remove the next database event from the session's database event queue (using GET DBEVENT or, implicitly, using WHENEVER DBEVENT or SET_SQL DBEVENTHANDLER).
2. Inquire for database event information (using INQUIRE_SQL). The GET DBEVENT statement gets the next database event, if any, from the queue of database events that have been raised and for which the application session has registered, as shown in the following illustration:
GET DBEVENT returns database events for the current session only; if an application runs multiple sessions, each session must register to receive the desired database events, and the application must switch sessions to receive database events queued for each session.
The optional WITH clause specifies whether your application waits for a database event to arrive in the queue. If GET DBEVENT WITH WAIT is specified, the application waits indefinitely for a database event to arrive. If GET DBEVENT WITH WAIT=wait_value is specified, the application waits the specified number of seconds for a database event to arrive. If no database event arrives in the specified time, the GET DBEVENT statement times out, and no database event is returned. If GET DBEVENT WITH NOWAIT is specified, the DBMS checks for a database event and returns immediately. The default is NOWAIT.
The WITH WAIT clause cannot be specified if the GET DBEVENT statement is issued in a select loop or user-defined error handler.
To obtain database event information, your application must issue the INQUIRE_SQL statement, and specify one or more of the following parameters:
dbeventname
The name of the database event (in lowercase letters). If there are no database events in the database event queue, the DBMS returns an empty string (or a string containing blanks, if your host language uses blank padded strings).
dbeventowner
The username of the user that created the database event.
dbeventdatabase
The database in which the database event was raised; returned in lowercase letters.
dbeventtime
The date and time the database event was raised, in date format. The receiving host variable must be a string (minimum length of 25 characters).
dbeventtext
The text, if any, specified in the optional event_text parameter by the application that raised the database event. The receiving variable must be a 256-character string. If the receiving variable is too small, the text is truncated.
