How You Can Create, Register, and Raise Events
The tasks of creating, registering, and raising events are performed with the SQL statements, create dbevent, register dbevent, and raise dbevent, respectively. This section provides a brief overview of each statement as it is used in the OpenROAD programming environment.
How You Can Create the Event
The SQL create dbevent statement creates a database event. When you create a database event, you are the owner of the event, and it is part of the database with which you were connected when you created the event, for example:
initialize()=
{
create dbevent myevent;
commit;
}
Generally, you can create database events outside of the applications that send or receive them. When you are designing your applications, you can decide what database events are needed and create them all at once. However, it is possible to create and send a database event in the same application.
How You Can Register the Event
Each frame must be registered to receive those database events that you want it to receive. To register a frame for a database event, you use the register dbevent statement. Generally, you place the register dbevent statement in the frame's initialize statement block. However, you can put it in an event block if you want, for example:
initialize()=
{
register dbevent myevent;
commit;
}
An event registration is associated with a specific session. The frame receives all events for which it is registered in any currently open session. However, to process the event, the frame must be working in the session where the event was registered when the event reaches the top of the frame's event queue.
For example, assume that Frame A switches back and forth between two Sessions, 1 and 2. If the frame issues a register dbevent in Session 1, then the frame processes the specified event only when it is working in Session 1. If the frame happens to be working in Session 2 when the event reaches the top of the frame's event queue, the event is discarded. (For more information about the interaction of database events and multiple sessions, see
How Database Events Work with Multiple Sessions.)
The application's effective user must have permission to register events. (The effective user is the user name under which the application is running.) In a multi-session application, each session can be running under a different user name. If you want to execute the register dbevent statement in a particular session, you must ensure that its effective user has the register permission.
Registrations are valid as long as the session in which they were executed is open or until you use the remove dbevent statement to unregister the event. Using the remove dbevent statement removes the registration only for the frame where you execute the remove dbevent statement. You must issue this statement in the same session in which you registered the event. Disconnecting a session automatically removes all of the event registrations associated with that session for all frames.
How You Can Raise an Event
To send a database event, you use the raise dbevent statement. This statement sends the specified database event to the DBMS for distribution to those applications registered to receive the event, for example:
on click =
{
buff = 'Sending DBEvent';
raise dbevent myevent :buff;
commit;
}
To issue the raise dbevent statement, the application's effective user must own the specified database event or must have the raise permission. In a multi-session application, this means that the effective user of the session that issues the statement must either own the specified event or have the raise permission.