Inquire_forms FRS

The inquire_forms frs statement obtains information about the FRS according to the FRS constant in the statement syntax. The general syntax is:

inquire_forms frs (fieldname =
    inquire_forms_constant [(frsobject)]
    {, fieldname = inquire_forms_constant
      [(frsobject)]})

The following FRS constants can be used to produce different variants of the inquire_forms frs statement:

activate	errortext	outofdatamessage
columns	getmessages	rows
command	label	shell
cursorcolumn	last_frskey	terminal
cursorrow	map	timeout
editor	mapfile	validate
errorno	menumap

The following subsections cover each variation individually.

inquire_forms frs (fieldname =
activate [(activationtype)]{, fieldname =
activate [(activationtype)]})

The inquire_forms frs (activate) statement checks whether activation is set to occur under the circumstances indicated by the activationtype parameter.

The value for each activationtype listed below is the integer 0 or 1, depending on whether the specified activation is turned off (0) or on (1).

Field activation only takes place if a field activation operation is specified for the current field.

The activate constant must be followed by one of the FRS objects (the activationtype):

Checks whether activation occurs upon pressing a function or control key associated with a FRS key

Indicates that activation occurs when you move to the next field. The default is 1 (on).

Indicates that activation occurs when you move to the previous field. The default is 0 (off).

The inquire_forms frs (columns) statement indicates the size, in number of columns, of the terminal screen. The columns constant does not accept a FRS object.

The inquire_forms frs (command) statement can be used in forms program activation blocks to determine what key stroke caused an activation to occur. The command constant does not accept a FRS object.

This statement can return one of the following values indicating the last keystroke made:

Value	Description
0	Undefined. Returned if an inquire statement is executed after exiting from a submenu block and before reentering the display loop.
1	Menu key
2	Any FRS key. To determine the number of the FRS key, see inquire_forms frs (last_frskey).
3	Any menuitem
4	Nextfield or autoduplicate
5	Previousfield
6	Downline
7	Upline
8	Newrow
9	Clearrest
10	Scrollup
11	Scrolldown
12	Nextitem
13	Timeout

The inquire_forms frs (cursorcolumn) statement indicates the current column position of the cursor in the window. The cursorcolumn constant does not accept a FRS object.

You can use the returned value to specify the starting column for positioning a pop-up message or lookup table. For example, you can use the value as input to the argument ii_startcolumn of the look_up( ) function.

The inquire_forms frs (cursorrow) statement indicates the current row position of the cursor on the terminal screen. The cursorrow constant does not accept a FRS object.

You can use the returned value to specify the starting row for positioning a pop-up message or lookup table. For example, you can use the value as input to the argument ii_startrow of the look_up( ) function.

The inquire_forms frs (editor) statement allows you to determine whether the system editor was disabled or enabled through a set_forms statement. A return value of 0 indicates that the editor is disabled, while a value of 1 indicates that it is enabled.

The inquire_forms frs (errorno) statement indicates the state of the error flag, which is set by FRS if an error occurs during the current display of the form. The errorno constant does not accept a FRS object. A return value of 0 indicates no errors. The error flag is set to 0 each time a menu operation is completed.

The errorno constant detects errors due to a user forms statement, such as getform or putform.

The inquire_forms frs (errortext) statement returns a string containing the text of the error message associated with the error number returned by errorno. If there is no current error it returns an empty string. The errortext constant does not accept a FRS object.

The inquire_forms frs (getmessages) statement allows you to determine whether the application has been set to suppress validation error messages. These are messages that occurs when the application attempts to retrieve a value from a field.

inquire_forms frs (fieldname =
label [(menuN|frskeyN|frscommand)]{, fieldname =
label [(menuN|frskeyN|frscommand)]})

The inquire_forms frs (label) statement returns the alias for the control or function key (including arrow or shell keys) to which a menu item, FRS key or FRS command is mapped. The alias (a character string) is displayed in the Help facility and on the control/function key-mapped menu line. Default menu item labels are often set in the terminal mapping file.

The label constant accepts one of the following FRS objects:

Specifies any of the FRS commands, including shell, to which a control or function key can be mapped.

Specifies any of the FRS keys in use during the application. N must be in the range 1 to 40.

One of the frscommand options available for UNIX and VMS is shell.

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.

This statement can return the following FRS default values:

• If the specified FRS object is not mapped to any control, function, or arrow key, an empty string is returned.

• Where X is any one of the characters A through Z or the Esc or Del keys, control keys are returned as "ControlX."

• Where N is a number from 1 to 40, function keys are returned as "PFN." (See also inquire_forms frs (map).)

The inquire_forms frs (last_frskey) statement returns the number of the FRS key that caused an activation. When several FRS keys are combined into one activation block (to reduce duplicate code), use this syntax to determine, at run time, which specific key caused the activation block to be executed.

It is a good idea to execute the inquire_forms frs (last_frskey) statement as early as possible in an activation block. Information is lost if you place it after any forms statement that creates an on-screen display, such as message, prompt, run submenu, and display submenu. To preserve information, use a nested display submenu that saves FRS state information.

inquire_forms frs (fieldname =
map [(menuN|frskeyN|frscommand)]{, fieldname =
map [(menuN|frskeyN|frscommand)]})

The inquire_forms frs (map) statement returns the alias, a character string containing the name of the control or function key (including arrow and shell keys) to which a menu item, FRS key, or FRS command has been mapped.

The map constant accepts one of the following FRS objects:

Specifies any of the FRS keys in use during the application. N must be in the range 1 to 40.

One of the frscommand options available is shell. For characteristics of this command, see Inquire_forms FRS (Label).

If no control, function, or arrow key is associated with the above FRS objects, map returns a null string. See the appropriate section of this guide for a complete explanation of function key mapping. (See also Inquire_forms FRS (Label).)

The inquire_forms frs (mapfile) statement returns a character string containing the specification for the application's key mapping file. The mapfile constant does not accept a FRS object.

The inquire_forms frs (menumap) statement indicates whether the menu line is set to display the function key equivalents (or assigned labels) for menu operations (Run(PF3), Edit(PF4), and so on). A return value of 1 indicates that the labels are displayed; 0 indicates they are not displayed. The menumap constant does not accept a FRS object.

The inquire_forms frs (outofdatamessage) statement indicates the current behavior for the "out of data" message. By default, the "out of data" message is displayed when a user attempts to scroll beyond the boundaries of a table field data set. The value can be one of the following:

Indicates that the forms system rings the monitor bell once instead of displaying the "out of data" message

The inquire_forms frs (rows) statement indicates the size, in number of rows, of the terminal screen. The rows constant does not accept a FRS component.

The inquire_forms frs (shell) statement allows you to determine whether the shell command key is enabled or disabled. The value is 1 if the shell command is enabled, 0 if it is disabled.

The inquire_forms frs (terminal) statement returns a character string specifying the type of terminal being used. This information comes from TERM_INGRES. The terminal constant does not accept a FRS object.

The inquire_forms frs (timeout) statement returns an integer value indicating the number of seconds in the timeout period. A value of zero indicates there is no timeout period set. The timeout constant does not accept a FRS object.

inquire_forms frs (fieldname =
validate [(validationname)]{, fieldname =
validate [(validationname)]})

The inquire_forms frs (validate) statement indicates whether or not validation is set to occur for the specified FRS component. It returns an integer value equal to 1 if validation is triggered by the described action for that FRS component, or 0 if validation is not set to occur as a result of the specified action. While in effect, settings apply to all form fields in the application that have validation checks defined for them.

The following are possible values for validationname:

Indicates whether fields are validated when you press a key mapped to a FRS key. The default is 0 (off).

Indicates whether fields are validated when you press the Menu key. The default is 0 (off).

Indicates whether fields are validated when you choose a menu operation. The default is 0 (off).

Indicates whether fields are validated when you move to the next field. The default is 1 (on).

Indicates whether fields are validated when you move to the previous field. The default is 0 (off).

Check whether validation occurs on moving the cursor backward through the form's fields:

Place the mode type of the current form into the field called formmode:

Get the sequence number in the current form of the empnum field and place its value in the fieldno field. Put the length in bytes of the data area for the empname field into the fldlen field:

Find the number of the FRS key selected by a user:

Put the number of rows displayed on the current table field into the integer field called numrows:

Put the name and length of the data area of the current column on the current table field in the current form into the character field colname and the integer field collength, respectively:

Check whether a change was made to the rank column of the current row:

Get the terminal size in number of rows and columns:

Determine which FRS key caused an activation:

key frskey1, key frskey2 =
begin
  inquire_forms frs (fieldnum = last_frskey);
  if fieldnum = 1 then
    message 'Key 1 was pressed';
  else
    message 'Key 2 was pressed';
  endif;
end