Using Activation Statements
Use activation statements to set up the way the application user manipulates the frame. These statements specify a set of 4GL statements that executes each time the user chooses a menu operation, presses a function key, or attempts to move into or out of a specific field, or when a time-out occurs. At the end of each activation, you can use the resume statement to return the cursor to any specified position on the frame.
Types of 4GL Activations
An activation in 4GL is an initialize statement or a field, key, menu, time-out, or database event activation. An operation in 4GL is defined by one or more of the following activations:
• An initialization occurs when a frame starts up, before the form is displayed. Use initializations to set or alter the contents of the form before the user interacts with it.
• A menu activation occurs when the user chooses a menu operation.
• A key activation occurs when the user presses an FRS key.
• A field activation occurs when the user enters or leaves a field.
• A timeout activation occurs when a preset time-out period has elapsed without keyboard activity.
• A database event activation occurs when one of the other activations causes the presence of a database event to be detected.
The initialization section is optional, but if it does appear, it must be first. Other operations can appear in any order. The following sections describe the overall structure of a 4GL source file.
Using an Initialization Section
The initialization section of a specification includes the initialize and declare statements. Use the initialization section to:
• Include a set of 4GL statements to execute when the frame starts up, before the form is displayed. These can include setting the mode of the form, defining key operations, and assigning initial values to fields and variables.
• Carry out an initial processing sequence before the application user does anything.
• Declare local variables and hidden columns which you can use throughout the specification file for the frame.
The syntax below shows these statements.
initialize [( {localvariable = typedeclaration,} )] =
[ declare { localvariable = typedeclaration ,} ]
begin
/* statements */
end
[ declare { localvariable = typedeclaration ,} ]
begin
/* statements */
end
Variables declared in the initialize portion can have values passed into them by a calling frame while those declared in the declare section cannot.
The following example sets the displayed field selection to a value of 1, sets the displayed field lname to the string "Last," and creates the local variable total and sets it to 0:
initialize =
declare total = smallint not null
begin
lname := 'Last';
selection := 1;
total := 0;
end
declare total = smallint not null
begin
lname := 'Last';
selection := 1;
total := 0;
end
The begin and end keywords in the statement enclose a group of statements that are to be executed every time the frame is called. For syntax and further considerations, see the section Initialize.
Menu Activations
Use a menu activation to:
• Define the name of the menu operation for display on the user's screen
• Specify the series of 4GL statements that executes each time the operation is selected
• Associate menu and key activations
The syntax for defining a menu operation is as follows:
'menuitemname'
[ ( [validate = value ] [, activate = value]
[, explanation = string] ) ]
[, key frskeyN
[ ( [validate = value ] [, activate = value] ) ] ] =
begin | {
statement; {statement;}
end | }
[ ( [validate = value ] [, activate = value]
[, explanation = string] ) ]
[, key frskeyN
[ ( [validate = value ] [, activate = value] ) ] ] =
begin | {
statement; {statement;}
end | }
The menuitemname is the name that appears on the menu line. Quotes surrounding the menuitemname are optional except where the name is a 4GL keyword. It is a good idea to use them routinely to avoid any possible name conflicts. Enclose all reserved words and single characters in quotes. You can specify menuitemname through a global constant, preceded by a colon.
The frskeyN is the FRS key designation (N is a number from 1 to 40) for a key that can activate the menu operation. Depending on the key mapping in use, each menu name is displayed in the window, and can be followed by a label indicating the activating key.
Menu operations are assigned default key mappings based on their sequence in the frame source code. You can use key frskeyN to override these default key mappings by mapping to an FRS key you select. In this case, the label for the control or function key mapped to that FRS key is displayed. For more information on key mapping, see Character-based Querying and Reporting Tools User Guide.
It is helpful to provide several ways to execute the same set of 4GL statements. In the following example, both the Help menu operation and the key associated with FRS key 1 display the help file for the start frame of the sample application:
Windows:
'help', key frskey1 =
begin
help_forms (subject =
'Start Frame Help Information',
file = '\usr\admin\files\personnel.hlp' c:)
end
begin
help_forms (subject =
'Start Frame Help Information',
file = '\usr\admin\files\personnel.hlp' c:)
end
UNIX:
'help' (activate = 1), key frskey1 (activate = 1) =
begin
help_forms (subject =
'Start Frame Help Information',
file = '/usr/admin/files/personnel.hlp')
end
begin
help_forms (subject =
'Start Frame Help Information',
file = '/usr/admin/files/personnel.hlp')
end
VMS:
'help' (activate = 1), key frskey1 (activate = 1) =
begin
help_forms (subject =
'Start Frame Help Information',
file = 'dra0:[usr.admin.files]personnel.hlp')
end
begin
help_forms (subject =
'Start Frame Help Information',
file = 'dra0:[usr.admin.files]personnel.hlp')
end
The value for validate or activate is 0 or Off to turn the option off, or 1 or On to turn the option on.
• Validate. If you turn validation on, the current field (where the cursor is when the operation is selected) is validated according to criteria established in the form definition window before the key or menu activation block runs. If the field fails the check, a message appears, and the cursor is positioned back on the field without executing the operation. No validation is performed if the form is in query or read mode.
• Activate. If activation is on, the activate block for the current field is executed before the key or menu activation block runs. No exit activation is performed if the form is in read mode.
If you specify both a menu item and an FRS key for your activation block, you must indicate the validate or activate keyword separately for each.
If validate or activate is not specified, the default action is controlled by whether it has been turned on globally for menu operations through a set_forms frs statement.
If an after field activation block exists, it must include a resume next statement or the menu activation block does not run.
Use the explanation clause to enter a string that describes a frame menu item. (You can specify this string through a global constant, preceded by a colon). The description appears in a table field accessed by the help/keys operation. When explanation is not used, the Explanation column of this table field is blank for the menu item. For more on this clause, see the section Helpfile Help_Forms.
Any sequence of 4GL statements can appear within a menu definition. You must place them between the keywords begin and end or within braces. The statements are executed whenever the user chooses the menu operation. For example:
'Increment' (validate = 1) =
begin
age := age + 1;
message 'Age has now been changed';
sleep 3;
end
begin
age := age + 1;
message 'Age has now been changed';
sleep 3;
end
In this specification, the menu operation Increment appears in the user's window. Whenever the user chooses Increment, Ingres validates the current field according to the criteria established when the form was created with the ABF FormEdit operation. Validation takes place because of the optional validate = 1 clause.
• If the value in the field is valid, the value in the age field is incremented, and the message "Age has now been changed" appears in the window.
• If the field fails the validation check, a message is displayed to the user and returns the cursor to the current field without performing the Increment operation.
For further details on field validations, see Character-based Querying and Reporting Tools User Guide.
Field Activations on Entry and Exit
Use a field activation operation to specify a series of 4GL statements to be executed when the cursor moves into or out of a specific field on a form. The syntax is:
[ before | after ] field
simplefieldname|all|tablefieldname.columnname
|tablefieldname.all
{, [ before | after ] field
simplefieldname|all|tablefieldname.columnname|
tablefieldname.all} =
begin | {
statement; {statement;}
end |}
simplefieldname|all|tablefieldname.columnname
|tablefieldname.all
{, [ before | after ] field
simplefieldname|all|tablefieldname.columnname|
tablefieldname.all} =
begin | {
statement; {statement;}
end |}
Note that an activation can be shared by more than one field. Also, you cannot perform activations on an entire table field; you must indicate specific columns (or use the keyword all).
The keywords before and after determine whether the activation takes place when the cursor enters the field or as the cursor exits. These keywords are optional. If omitted, the activation occurs upon exit from the field (after).
The keyword all sets an activation on all the simple fields in the form or columns in the table field. If a frame has activations on all and on an individual field or column, the last activation is the one that is executed. This applies to both before and after field activations.
Any sequence of 4GL statements can appear within the definition of a field activation. The 4GL statements that accompany the field definition are executed whenever the user leaves or enters the field, depending on the type of activation:
• Field exit activation (the default) is useful for data validation or control flow modification.
• Field entry activation is useful for activities such as highlighting the current field or providing field help information.
If specified, exit (keyword after) activations are performed in fill, update, and query mode; they do not occur in read mode. Entry activations occur in all modes including read mode (for a form or table field).
You can enable or disable activations globally for the application using the set_forms frs statement. By default, entry and exit activations are enabled.
Note: Be careful when writing entry activations, as an endless chain of entry activations can result. For example, if fields A and B have entry activation code containing a resume to each other, an infinite loop results once the user enters either field.
When the following statement block is used with an exit activation (keyword after), Ingres checks to see if the value in the field is zero or Null when the user leaves the empnum field. If so, it issues the error message and returns the cursor to the empnum field. If not, it retrieves the employee's name from the database and positions the cursor at the lname field.
field empnum =
begin
if empnum = 0 or empnum is null then
message 'Please enter an employee number';
sleep 3;
else
empform := select fname, lname
from employee
where num = empnum;
resume field 'lname';
endif;
end
begin
if empnum = 0 or empnum is null then
message 'Please enter an employee number';
sleep 3;
else
empform := select fname, lname
from employee
where num = empnum;
resume field 'lname';
endif;
end
In an exit activation, the last statement to be executed must be a resume statement. Without the resume statement, the cursor remains on the same field after all statements are executed, and does not exit to another field.
In general, entry activations follow the same rules as other activations and can be combined with them.
You cannot use field activations in operations lists for the run submenu statement, because no fields are accessible while the run submenu statement is executing.
Note: If the cursor is in a column for which an activation is defined, the activation causes the loss of multi-row scrollup and scrolldown capabilities.
Key Activations
Use a key activation operation to define the results of pressing a specific key on the keyboard. The operation is specified not for a particular function or control key, but for an FRS key, which is then mapped to the function or control key.
The syntax is:
key frskeyN [( [ validate = value ]
[, activate = value] )] =
begin | {
statement; {statement;}
end | }
[, activate = value] )] =
begin | {
statement; {statement;}
end | }
The frskey is the FRS key designation (N is a number from 1 to 40) for a key you want to activate.
The value for validate or activate is 0 or off to turn the option off, or 1 or on to turn the option on.
Validate
If you turn validation on, the field where the cursor resides is validated according to criteria established in the ABF FormEdit operation before the key activation block runs.
If the field fails the check, a message appears, and the cursor is positioned back on the field without executing the operation. No validation is performed if the form is in query or read mode.
Activate
If activation is on, the activate block for the current field is executed before the key activation block runs. No exit activation is performed if the form is in read mode.
• If validate or activate is not specified, the default action is controlled by whether it has been turned on globally for key operations through a set_forms frs statement.
• The field activation block must issue a resume next statement or the key activation block does not run. If no field activation block exists, the system runs the key activation block.
Any sequence of 4GL statements can appear after the key definition. You must place them between the keywords begin and end or within a pair of braces.
The 4GL statements that accompany the key activation definition are executed whenever the user presses the control or function key mapped to the specified FRS key. For example, the following statements start the Help facility with the personnel.hlp file when the user presses the key mapped to the FRS key 1.
Windows:
key frskey1 =
begin
help_forms (subject =
'Start Frame Help Information',
file = '\usr\admin\files\personnel.hlp' c:)
end
begin
help_forms (subject =
'Start Frame Help Information',
file = '\usr\admin\files\personnel.hlp' c:)
end
UNIX:
key frskey1 =
begin
help_forms (subject =
'Start Frame Help Information',
file = '/usr/admin/files/personnel.hlp')
end
begin
help_forms (subject =
'Start Frame Help Information',
file = '/usr/admin/files/personnel.hlp')
end
VMS:
key frskey1 =
begin
help_forms (subject =
'Start Frame Help Information',
file = 'dra0:[usr.admin.files]personnel.hlp')
end
begin
help_forms (subject =
'Start Frame Help Information',
file = 'dra0:[usr.admin.files]personnel.hlp')
end
Timeout Activations
Use a timeout activation operation to specify the actions to be taken if timeout occurs. A timeout block begins with the keywords on timeout. The syntax is:
on timeout =
begin | {
statement; {statement;}
end | }
begin | {
statement; {statement;}
end | }
The timeout feature enables you to control how long the application waits for requested input from a user. If the user fails to make a menu choice or respond to a prompt or message within the specified time, the timeout occurs, returning control to the application. The timeout sequence defined by the on timeout block is then activated.
You must repeat the on timeout block in all frames and submenus where activation is to occur on a timeout. If a timeout occurs without a timeout activation, the default is to complete the statement that is waiting for input. If no statement is waiting for input, such as a cursor positioned in a field, a Return is performed.
To enable timeout, include a set_forms statement (for example, in the initialization block) that specifies the length of the timeout period in seconds. For example:
set_forms frs (timeout = 60);
Once set, the timeout period applies to all display loops, prompts, messages, and all error messages requiring a Return for confirmation.
The timeout period remains in effect until another set_forms statement changes the period's length or sets it to zero, which effectively turns timeout off. You can place the statement inside or outside of a display loop, or inside a nested display loop. Once executed, it affects the application globally.
Timeouts set within an application do not affect any programs called by the application. To impose timeout limits on called programs, do so within the code of the called program itself.
The following timeout block clears the screen (of possibly confidential information) whenever user input has ceased for 10 seconds. The user must input the password "master" to reactivate the screen:
on timeout =
begin
clear screen;
set_forms frs (timeout = 0);
pass_var := '';
while pass_var <> 'master' do
pass_var := prompt noecho 'Password: ';
endwhile;
set_forms frs (timeout = 10);
redisplay;
end
begin
clear screen;
set_forms frs (timeout = 0);
pass_var := '';
while pass_var <> 'master' do
pass_var := prompt noecho 'Password: ';
endwhile;
set_forms frs (timeout = 10);
redisplay;
end
Timeout periods set to a small number (less than 10 seconds) cannot be handled reliably, depending on the system and its current load. The following example allows a much longer timeout. It blanks the screen after 9 minutes of inactivity, then redisplays the screen whenever Return is pressed:
on timeout =
begin
clear screen;
set_forms frs (timeout = 0);
pass_var := prompt '';
set_forms frs (timeout = 540);
redisplay;
end
begin
clear screen;
set_forms frs (timeout = 0);
pass_var := prompt '';
set_forms frs (timeout = 540);
redisplay;
end
Last modified date: 08/28/2024