Registering Interest in Events
Go Up to Working with Events
An application must register a request to be notified about a particular event with the InterBase event manager before waiting for the event to occur. To register interest in an event, use the EVENT INIT statement. EVENT INIT requires two arguments:
- An application-specific request handle to pass to the event manager.
- A list of events to be notified about, enclosed in parentheses.
The application-specific request handle is used by the application in a subsequent EVENT WAIT statement to indicate a readiness to receive event notification. The request handle is used by the event manager to determine where to send notification about particular events to wake up a sleeping application so that it can respond to them.
The list of event names in parentheses must match event names posted by triggers or stored procedures, or notification cannot occur.
To register interest in a single event, use the following EVENT INIT syntax:
EXEC SQL EVENT INIT request_name (event_name);
<event_name> can be unlimited in character size, and can be passed as a constant string in quotes, or as a host-language variable.
For example, the following application code creates a request named RESPOND_NEW that registers interest in the “new_order” event:
EXEC SQL
EVENT INIT RESPOND_NEW ('new_order');
The next example illustrates how RESPOND_NEW might be initialized using a host-language variable, myevent, to specify the name of an event:
EXEC SQL EVENT INIT RESPOND_NEW (:myevent);
After an application registers interest in an event, it is not notified about an event until it first pauses execution with EVENT WAIT. For more information about waiting for events, see Waiting for Events with EVENT WAIT.
As an alternative to registering interest in an event and waiting for the event to occur, applications can use an InterBase API call to register interest in an event, and identify an asynchronous trap (
AST) function to receive event notification. This method enables an application to continue other processing instead of waiting for an event to occur. For more information about programming events with the InterBase API, see the API Guide.