Activation Operations
Although you can create a simple forms application with only the initialize and finalize statements that allows the user to perform simple data entry and editing, most applications require more sophisticated control over the form display. For instance, it is possible to provide the user with help in filling out a form before the form is complete, let the user retrieve and update data from the database during the form's display, and catch values that the user has entered in two fields of the form to determine the value of a third field.
For such needs, you can use activate blocks to create operations. When the user selects an operation during the form's display, the statements in the operation's activate block are executed. The form remains on the screen after the section has been executed, allowing the user to continue entering and editing data or to select another operation.
In its simplest form, the activate section has the following syntax:
initialize [(fieldname = data {, fieldname = data})];
begin;
initialization code;
end;
When the specified condition occurs, the statements in the section are executed. You can specify more than one condition in a single activate section. However, if you specify more than one activation for the same condition, only the last one in your source file is executed.
Seven types of conditions, corresponding to the seven types of user-specified operations, are available. Two of these are used exclusively with table fields and are discussed in
Table Field Activation Operations. The others are:
menuitem
Causes the accompanying block of code to be executed when the user selects a menu item. The activate statement for this condition has the following syntax:
activate menuitem menuname;
The menunames appear on the menu line at the bottom of the screen, ordered according to the sequence of activate menuitem statements in the display block.
before field
Specifies that the statements associated with this condition are executed whenever the user moves the screen cursor into a specified field or, if you specify all, any field on the form. (This is often called an entry activation.) An activate statement for this condition has the syntax:
activate before field fieldname|all;
[after] field
Specifies that the statements associated with this condition are executed whenever the user moves the screen cursor out of a specified field or, if you specify all, any field on the form. (This is often called an exit activation.) An activate statement for this condition has the syntax:
activate [after] field fieldname|all;
frskey
Specifies that activation for this condition occurs when the user presses the control or function key mapped to the designated FRS key. (The Character-based Querying and Reporting Tools User Guide explains FRS (FRS) key mapping in detail.) You can specify the FRS key using a literal or an integer variable. The FRS key number must be in the range of 1 to 40. The syntax for this condition is:
activate frskeyN |frskey :integer_variable |frskey : integer_constant;
timeout
Specifies that the program code associated with this block is executed whenever a display loop times out. A display loop times out when a user does not perform any keyboard activity within a specified time limit. An activity can include such actions as moving the cursor, entering data, or making a menu choice. The syntax for this condition is:
activate timeout;
The following example illustrates the various types of activate statements described above:
...
exec sql begin declare section;
namevar character_string(20);
salvar float;
exec sql end declare section;
exec sql connect personnel;
exec frs forms;
exec frs forminit empform;
exec frs display empform;
exec frs initialize (ename = :namevar, sal = :salvar);
exec frs activate before field 'ename';
exec frs begin;
program code;
exec frs end;
exec frs activate frskey5;
exec frs begin;
program code;
exec frs end;
exec frs activate menuitem 'Help';
exec frs begin;
program code;
exec frs end;
exec frs activate menuitem 'Add';
exec frs begin;
program code;
exec frs end;
exec frs activate menuitem 'End', frskey3;
exec frs begin;
exec frs enddisplay;
exec frs end;
exec frs activate field 'salary';
exec frs begin;
program code;
exec frs end;
exec frs activate timeout;
exec frs begin;
program code;
exec frs end;
exec frs finalize;
exec frs endforms;
exec sql disconnect;
...
The first activate section in the example is executed when the user moves the cursor into the field ename. The user can execute the operation in the second section by pressing the function or control key that is mapped to FRS key 5. The next three activate sections are associated with menu items. They cause the following menu line to appear at the bottom of the form:
Help Add End
The user can execute the last menu item activate section in the example by either selecting the menu item End or pressing the function key mapped to FRS key 3, illustrating the fact that a single activate section can specify more than one condition. After the menu item activate section is a field activation that is executed when the user moves out of the salary field. If the user fails to perform any keyboard action within some previously specified time limit, the timeout activate section is executed.