Get a Database Event
To get the next database event, if any, from the queue of database events that have been raised and for which the application session has registered, use the GET DBEVENT statement:
EXEC SQL GET DBEVENT [WITH NOWAIT | WAIT [= wait_value]];
The following illustration shows how the GET DBEVENT statement works:
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 period, the GET DBEVENT statement times out, and no database event is returned. If GET DBEVENT WITH NOWAIT is specified, the DBMS Server 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 Server 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; returned in lowercase letters.
• 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.
