Database Event Activations

Use a database event activation block to specify the actions to be taken when another activation signals that a database event has been raised. The code in the activation block is executed when the presence of the new event is detected.

To retrieve information about the event that caused the activation, you must place an inquire_sql statement within the activation block. Include any of the inquire_sql event-related parameters that are needed. (See the section Inquire_sql for more information on the inquire_sql statement.)

The syntax of an event activation block is:

on dbevent =
begin | {
[  inquire_sql ([var = dbeventname, ]
                [var = dbeventowner, ]
                [var = dbeventdatabase,]
                [var = dbeventtime,]
                [var = dbeventtext]);]
   statement; {statement;}
end | }

You must accompany a database event activation with a field, key, menu, or timeout activation in the same frame or display submenu, because the search for a database event in the event queue is made only when some other activation is about to be initiated or completed. If a database event is found, the statements associated with the database event activation are executed before any statements for the other activation (if it was about to be initiated).

You can use database event activations within a frame (outside any submenus) or within a display submenu statement, but not with a run submenu statement. You cannot use any variants of the resume statement other than resume without any operands.

See How Database Events Are Handled for a detailed description of event handling.

This chapter concludes with a complete 4GL specification for a sample start or top frame. The following figure shows the opening frame of the Project Management application. This is the same user frame, with an expanded menu, that was introduced briefly in Overview of 4GL.

The menu for this frame was created using the following 4GL specification. The form was created using the ABF FormEdit operation. The 4GL specification pairs each menu operation with statements to be executed whenever the user chooses the operation. It also defines the key activations for this frame.

/*
**
** top.osq; main frame for the projmgt
** application
**
**/

initialize =
begin
  message 'Starting the ABF Demonstration' +
  ' Application. . .';
  today = date('today');
  callproc startup;
  callproc timer_on(secs=2);
end

on timeout =
begin
  current_time=date('now');
end

Database =
begin
  callframe database;
end

Employee_Tasks =
begin
  set_forms field ''   (invisible(current_time)=1);
  redisplay;
  callframe emptasks;
  set_forms field ''   (invisible(current_time)=0);
end

Dependents =
begin
  callproc timer_off;
  callframe empdep;
  callproc timer_on(secs=2);
end

Experience =
begin
  callproc timer_off;
  callframe experience;
  callproc timer_on(secs=2);
end

Mail =
begin
  call system 'mail';
end

'4GL', key frskey16 =
begin
  callproc timer_off;
  helpfile 'Top Frame 4GL'
    '$dra0:[usr.admin.files.abfdemo]top.osq';
  callproc timer_on(secs=2);
end

'Help', key frskey1 =
begin
  callproc timer_off;
  help_forms (subject =
    'Top Frame Help Information',
    file = '$dra0:[usr.admin.files.abfdemo]top.hlp');
  callproc timer_on(secs=2);
end

'Quit', key frskey2, key frskey3 =
begin
  exit;
end

In the example, activations specify the main functions of the frame, as follows:

• The initialization section calls a separate procedure (using the callproc statement) to complete the initialize sequence.

• Menu activations set up the menu selections (Database, Employee_Tasks, Dependents, Experience, Mail, 4GL, Help, and Quit).

The callframe statements suspend the operation of the current frame to call another form and operations menu or start up a specific operation such as looking up data or running a report.

The call system statement is executed when you choose the Mail operation. It starts the operating system's mail utility and then returns to this frame when you exit from Mail.

The helpfile statement is executed when you choose the 4GL operation or presses the key associated with FRS key 16. It displays the 4GL source code file for this frame.

The help_forms statement is executed when you choose the Help operation or presses the key associated with FRS key 1. It displays the Help file for this frame.

The exit statement is executed when you choose the Quit operation or press the key associated with FRS key 2 or 3. It ends the application and returns the user to the operating system.

An on timeout block is used to display the current time at the end of the 2-second timeout period.

This frame is part of the Project Management Sample Application, presented in the ABF part of this guide.