21. 4GL Statement Glossary : Set_forms : Set_forms FRS
 
Share this page                  
Set_forms FRS
The following sections discuss the variants of the set_forms statement where the objecttype, as discussed in the table Parameters for Set_forms, is always frs. The set_forms_constant can be any of those shown in the table below.
The following sections discuss these variants of the set_forms frs statement:
activate
Turns field activation mechanisms on or off
editor
Disables or enables system editor
getmessages
Enables or suppresses error messages on field value retrieval
label
Assigns an optional alias or identification label to a mapped key for display purposes
map
Sets mappings between control/function keys and FRS keys, FRS command, and menu items
mapfile
Specifies the application's mapping file
menumap
Turns on or off the display of key settings next to menu items
outofdatamessage
Sets the behavior for the "out of data" message
shell
Enables or disables the FRS shell command
timeout
Assigns a timeout period
validate
Turns validation mechanisms on or off
Each statement variant is discussed in its own subsection below, in alphabetical order by set_forms_constant.
Set_forms FRS (Activate)
The set_forms frs activate statement has the following syntax:
set_forms frs  (activate (activationtype) = value
  {, activate (activationtype) = value})
The 4GL set_forms frs (activate) statement sets default field activation types for the application as a whole. Field activation occurs when you perform an action (such as moving forward out of a field) that is specified by an activation type variable set to a value of on. You must use the before and after keywords when writing field activation code, even if the set_forms frs (activate) statement is used.
The value can be a keyword, integer constant, or integer variable as follows:
on | 1
Turns field activation on. This is the default.
off | 0
Turns field activation off.
intvar
Specifies a 4GL expression evaluating to 0 or 1
Activations take place only for fields for which 4GL code specifies the activation. The following table lists possible activation types. The default of before enables field activation before entry into a field; the other types perform activations after the cursor has entered a field.
Note:  Be careful when writing entry applications, because an endless chain of entry activations can occur. For example, if fields "a" and "b" have entry activation code containing resume statements to each other, then an infinite loop results when you enter each field.
The possible activation types are:
before
Performs activation before the cursor enters the field or table field column from another field or table field column. Default activation type.
Enables or disables field entry activation, (activation when a specified field or table field cell is about to become the current item). Default is on.
keys
Performs activation when you press any function key mapped to an FRS key. The default is off.
menu
Performs activation when you press the Menu key. The default is off.
menuitem
Performs activation when you choose a menu operation or a key mapped to a menu operation. The default is off.
nextfield
Performs activation when the application user moves to the next field. The default is on.
previousfield
Performs activation when you move to the previous field. The default is off.
Set_forms FRS (Editor)
set_forms frs (editor = value )
The set_forms frs (editor) statement lets you disable the system editor to prevent access to the operating system from the system editor. The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Disables the editor
on | 1
Enables the editor. This is the default, to allow for compatibility with earlier releases of 4GL.
intvar
Specifies a 4GL expression evaluating to 0 or 1
Set_forms FRS (Getmessages)
set_forms frs (getmessages = value )
The set_forms frs (getmessages) statement allows an application to suppress validation error messages that occur when an application attempts to retrieve a value from a field. The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Disables getmessages
on | 1
Enables getmessages. This is the default.
intvar
Specifies a 4GL expression evaluating to 0 or 1
Set_forms FRS (Label)
set_forms frs
 (label(menuN|frskeyN|frscommand) = value
 { , label(menuN|frskeyN|frscommand) = value })
The set_forms frs (label) statement allows you to assign a designated character string label to an FRS key, menu item position, or FRS command (including arrow keys) for display purposes. When menumap is on, the label appears next to a menu operation in place of the default label for the key. This statement does not affect the key mapping itself.
The resulting value is a user-defined label that is a string constant or a program string variable, enclosed in quotes.
To map keys to menu operations, see the subsection below on set_forms frs (map).
If labels are assigned to both a menu operation and its associated FRS key, the FRS key label takes precedence. Any aliases created by the set_forms (label) statement remain in effect for the remainder of the application unless another label statement overrides it. For more information on function and control key mapping, see the appropriate sections of this guide.
Possible FRS objects for set_forms frs (label) are:
menuN
Specifies the Nth menu item on the menu line. N must be in the range 1 to 25.
frskeyN
Specifies an FRS key used in the application. N must be in the range 1 to 40.
frscommand
Specifies any of the FRS commands to which a control or function key can be mapped.
One of the frscommand options available is shell.
Windows: The frscommand spawns a command prompt from within the forms program in a manner similar to starting an editor on a field's contents. For security it is not active unless the application explicitly enables it.
UNIX:The frscommand spawns a Bourne shell (sh) (default) or c shell (csh) from within the forms program in a manner similar to starting an editor on a field's contents. For security it is not active unless the application explicitly enables it.
VMS: The frscommand spawns a DCL sub-process from within the forms program in a manner similar to starting an editor on a field's contents. For security it is not active unless the application explicitly enables it.
Set_forms FRS (Map)
set_forms frs
  (map(menuN|frskey
N|frscommand) = 
    pfN |control[up | down | right | left ]
    arrow )
      |[(label)] 
  {, map(menuN|frskeyN|frscommand) =
     pfN|controlx[up | down | right | left ] arrow )
      |[(label)]} 
set_forms frs
  (map(menu
N|frskeyN|frscommand) = 
    pfN |controlx|[(label)]
(In the previous syntax, x represents any single uppercase or lowercase letter.)
The set_forms frs (map) statement allows mapping of menu operations, FRS keys and FRS commands to control and function keys (including arrow keys) at the application level. Key mapping at the application level takes precedence over installation and user mapping files. Each menu operation, FRS key, and FRS command can be mapped to only one control or function key.
You can also map keys in two other ways:
Map a function/control key to a menu operation. Mapping a key to a menu operation causes a default label (PF3, PF4, etc.) to appear next to that menu operation when the menumap function is set to on. For information on changing this default label, see Set_forms FRS (Label).
Map a function/control key to an FRS key associated with the same operation through program code.
Note:   Because arrow keys on certain UNIX and VMS terminals send a control character (rather than an escape sequence), the implementation of your system must take this into account.
Mappings remain in effect for the remainder of the application unless overridden by another map statement. For more information on function and control key mapping, see the appropriate sections of this guide.
The following are the possible FRS objects and their values for set_forms frs (map):
menuN
Specifies the Nth menu item on the menu line. N must be in the range 1 to 25.
frskeyN
Specifies an FRS key used in the application. N must be in the range 1 to 40.
frscommand
Specifies any of the FRS commands to which a control or function key can be mapped
pfN
Specifies a function key. N must be in the range 1 to 40.
controlX
Specifies a control key. X can be any single letter of the alphabet, or del (Delete key), or esc (Escape key).
Control cannot be abbreviated. On most terminals, Control-M is equivalent to the Return key, and Control-I is equivalent to the Tab key.
Control can be abbreviated ctrl. On most PCs Ctrl-M is equivalent to the Enter key, and Ctrl-I is equivalent to the Tab key.
label
Designates any alphanumeric string. It appears in place of the default label for a menu item. It also appears in the Keys operation of the Help facility.
One of the FRS commands available is shell. For characteristics, see Set_forms FRS (Label).
Set_forms FRS (Mapfile)
set_forms frs (mapfile = pathname | file_specification)
The 4GL set_forms frs (mapfile) statement allows an application's FRS key mapping file to be determined dynamically.
The value to assign to mapfile is the complete pathname or file specification for the mapping file, as appropriate for your operating system. It must be a character string constant enclosed in quotes or the name of a field containing a character string constant.
Further information on mapping files can be found in the appendixes of this guide.
Set_forms FRS (Menumap)
set_forms frs (menumap = value)
The 4GL set_forms frs (menumap) statement sets the display of the default menu mapping to keys. The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Specifies that, when the display is off, or if no labels are defined, the key names do not appear.
on | 1
Specifies that, when the display is on, you see the key names in parentheses following the menu operations. This is the default.
intvar
Specifies a 4GL expression evaluating to 0 or 1
Default labels are set by the mapping files in the terminal definition. For details on mapping files, see the appendixes of this guide. Any labels assigned in set_forms frs (label) statements override the defaults.
Set_forms FRS (Outofdatamessage)
set_forms frs (outofdatamessage = value)
The set_forms frs (outofdatamessage) statement sets the behavior for the "out of data" message when a user attempts to scroll beyond the boundaries of a table field data set. The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Indicates the message is not displayed
on | 1
Indicates the "out of data" message is displayed. This is the default.
bell | 2
Indicates that the forms system rings the monitor bell once, instead of displaying the "out of data" message
intvar
Specifies a 4GL expression evaluating to 0, 1 or 2
Set_forms FRS (Shell)
set_forms frs (shell = value)
The 4GL set_forms frs (shell) statement enables or disables the shell command key. The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Disables the shell command key. This is the default.
on | 1
Enables the shell command key.
intvar
Specifies a 4GL expression evaluating to 0 or 1
For security, it is not active unless the application explicitly enables it.
Windows: The frscommand spawns a command prompt from within the forms program in a manner similar to starting an editor on a field's contents without any explicit coding.
UNIX:The shell option spawns a Bourne shell (sh) (default) or c shell (csh) from within the forms program in a manner similar to starting an editor on a field's contents without any explicit coding.
VMS: The shell option spawns a DCL sub-process from within the forms program in a manner similar to starting an editor on a field's contents without any explicit coding.
Set_forms FRS (Timeout)
set_forms frs (timeout = value )
The 4GL set_forms frs (timeout) statement specifies the number of seconds in the timeout period. The timeout value is normally set within the initialize block. For a timeout period, the value can range from 1 to 32767, that is, from 1 second to approximately 9 hours. A value of zero means no timeout is specified. Values greater than this range are truncated; negative values are set to zero and cause an error message.
If a timeout occurs, the timeout block is executed, defined by the keywords:
on timeout
  begin | {
    statements
  end | }
For further information and examples of timeout blocks, see the section Timeout Activations.
Set_forms FRS (Validate)
set_forms frs 
  (validate (validationname) = value
  {, validate (validationname) = value})
The 4GL set_forms frs (validate) statement sets validations for the application as a whole, not for individual fields. Validation occurs when you perform an action (such as moving to the next field or column) that is specified by a validationname variable whose value is set to on. See Inquire_forms for further discussion of this feature.
The following table lists the possible validation names for set_forms frs (validate). The value can be a keyword, integer constant, or integer variable as follows:
off | 0
Turns validation off
on | 1
Turns validation on for the named validation mechanism
intvar
Specifies a 4GL expression evaluating to 0 or 1
validationname can have any of the following values:
keys
Performs validation when you press any function key mapped to an FRS key. Default: off.
menu
Performs validation when you press the Menu key. Default: off.
menuitem
Performs validation when you choose a menu operation or a key mapped to a menu operation. Default: off.
nextfield
Performs validation when the application user moves to next field. Default: on.
previousfield
Performs validation when you move to the previous field. Default: off.
Examples
Clear the change variable for a field:
set_forms field empform 
  (change(empname) = 0);
Set the change variable for two columns in row 2 of a table field:
set_forms row partsform partstable 2
  (change(partnumber) = 1, 
  change(partdescription) = 1);
Cause the current field in the current form to appear in reverse video and blink:
set_forms field '' (reverse = 1, 
  blink = 1);
Turn off blinking in the partname column in the partstbl table field of the current form:
set_forms column '' partstbl 
  (blink (partname) = 0);
Change the mode of the current form to the mode designated in the modefield field of the form:
set_forms form (mode = modefield);
Cause a field activation to occur whenever you backtab or choose the Menu key or an FRS key:
set_forms frs (activate(previousfield) = 1,
  activate(menu) = 1, activate(keys) = 1);
Map the Control-H key to menu item 3, and equate the label "CTRL-H" with the same operation. When menumap is on, the label "CTRL-H" appears next to menu item 3, and the associated operation is invoked when you press the Control key and the "h" key:
set_forms frs (map(menu3) = 'controlh', 
  label(menu3) = 'CTRL-H');
Map the uparrow key to menu item 4, and equate the label "SCROLLUP" with the same operation. When menumap is on, the label "SCROLLUP" appears next to menu item 4, and the associated operation is invoked when you press the Scrollup key:
set_forms frs (map(menu4) = 'uparrow', 
  label(menu4) = 'SCROLLUP');
Equate Function key 3 with FRS key 5, so that any key activation operation utilizing FRS key 5 is activated when you press Function key 3:
set_forms frs (map(frskey5) = 'pf3');
Turn on the menu map display and set validation on the Menu key:
set_forms frs (menumap = 1, 
  validate (menu) = 1);
Perform a validation for the current field whenever you press any function key mapped to an FRS key.
set_forms frs (validate (keys) = 1);
Turn on all possible field and column validations for every frame in the application:
set_forms frs (validate(nextfield) = 1,
  validate(previousfield) = 1,
  validate(menu) = 1,
  validate(keys) = 1,
  validate(menuitem) = 1);