Back to Contents

Programs

Summary:

• Runtime Configuration
• The MAIN block
• Signal Handling (DEFER)
• The STATUS variable
• The INT_FLAG variable
• The QUIT_FLAG variable
• Program Options (OPTIONS)
• Running Programs (RUN)
• Stop Program Execution (EXIT PROGRAM)
• Database Schema Specification (SCHEMA)
• The NULL Constant
• The TRUE Constant
• The FALSE Constant
• The NOTFOUND Constant
• The BREAKPOINT instruction
• Displaying Text in Line Mode (DISPLAY)
• Displaying Error Messages (ERROR)
• Displaying Application Messages (MESSAGE)
• Setting Key Labels

See also: Compiling Programs, Flow Control, The Application class, Database Schema Files, Preprocessor.

Runtime Configuration

You can control the behavior of the runtime system with some FGLPROFILE configuration parameters.

Intermediate field trigger execution

Dialog.fieldOrder = {true|false}

When TRUE, intermediate triggers are executed. As the user goes to a new field with a mouse click, the runtime system executes the BEFORE FIELD / AFTER FIELD triggers of the input fields between the source and the destination field. When FALSE, intermediate triggers are not executed..

The default setting for the runtime system is FALSE; while the default setting in FGLPROFILE for Dialog.fieldOrder is TRUE. As a result, the overall setting after installation is TRUE. To modify the behavior of intermediate field trigger execution, change the setting of Dialog.fieldOrder in FGLPROFILE.

The MAIN block

Purpose:

The MAIN block is the starting point of the application. When the runtime system executes a program, after some initialization, it gives the control to this program block.

Syntax:

Notes:

1. define-statement defines function arguments and local variables.
2. constant-statement can be used to declare local constants.
3. defer-statement defines how to handle signals in the program.
4. fgl-statement is any instruction supported by the language.
5. sql-statement is any static SQL instruction supported by the language.

Signal Handling

Purpose:

The DEFER instruction allows you to control the behavior of the program when an interruption or quit signal has been received.

Syntax:

Warnings:

1. DEFER INTERRUPT and DEFER QUIT instructions can only appear in the MAIN block.
2. Once deferred, you cannot reset to the default behavior.

Usage:

When an interrupt signal is caught by the runtime system and DEFER INTERRUPT is used, the int_flag global variable is automatically set to TRUE by the runtime system.

Interrupt signals are raised on terminal consoles when the user hits a key like CTRL-C (depends on the stty configuration). When using a front end, no terminal console is used for the BDL program; therefore users cannot send interrupt signals with the CTRL-C key. To send an interruption request from the front end, you must define an 'interrupt' action view. For more detail, refer to Interruption Handling in the Dynamic User Interface .

DEFER QUIT indicates that the program must continue when receiving a quit signal. By default, the program stops.

When a quit signal is caught by the runtime system and DEFER QUIT is used, the quit_flag global variable is automatically set to TRUE by the runtime system.

STATUS

Purpose:

STATUS is a predefined variable that holds the execution status of the last instruction.

Syntax:

Definition:

DEFINE STATUS INTEGER

Notes:

1. The data type of STATUS is INTEGER.
2. STATUS is typically used with WHENEVER ERROR CONTINUE (or CALL).
3. STATUS is set by expression evaluation errors only when WHENEVER ANY ERROR is used.
4. After an SQL statement execution, STATUS contains the value of SQLCA.SQLCODE.

Warnings:

1. STATUS is updated after any instruction execution. A typical mistake is to test STATUS after a DISPLAY STATUS instruction, written after an SQL statement.
2. While STATUS can be modified by hand, it is not recommended, as STATUS may become read-only in a later release.

Example:

01 MAIN
02   DEFINE n INTEGER
03   WHENEVER ANY ERROR CONTINUE
04   LET n = 10/0
05   DISPLAY STATUS
06 END MAIN

INT_FLAG

Purpose:

INT_FLAG is a predefined variable that is automatically set to TRUE when the user presses the interruption key.

Syntax:

Definition:

DEFINE INT_FLAG INTEGER

Notes:

1. The data type of INT_FLAG is INTEGER.
2. INT_FLAG is typically used with DEFER INTERRUPT.
3. INT_FLAG is set to TRUE when an interruption event is detected by the runtime system. The interruption event is raised when the user presses the interruption key.
4. If DEFER INTERRUPT is enabled and the interruption event arrives during a procedural instruction (FOR loop), the runtime system sets INT_FLAG to TRUE; it is up to the programmer to manage the interruption event (stop or continue with the procedure).
5. If DEFER INTERRUPT is enabled and the interruption event arrives during an interactive instruction (INPUT, CONSTRUCT), the runtime system sets INT_FLAG to TRUE and exits from the instruction. It is recommended to test INT_FLAG after an interactive instruction to check if the input has been cancelled.

Warnings:

1. Once INT_FLAG is set to TRUE, it must be reset to FALSE by hand to detect a new interruption event.

Example:

01 MAIN
02   DEFINE n INTEGER
03   DEFER INTERRUPT
04   LET INT_FLAG = FALSE
05   FOR n = 1 TO 1000
06      IF INT_FLAG THEN EXIT FOR END IF
07      ...
08   END FOR
09 END MAIN

QUIT_FLAG

Purpose:

QUIT_FLAG is a predefined variable that is automatically set to TRUE when a 'quit event' arrives.

Syntax:

Definition:

DEFINE QUIT_FLAG INTEGER

Notes:

1. The data type of QUIT_FLAG is INTEGER.
2. Typically used with DEFER QUIT.
3. QUIT_FLAG is set to TRUE when a quit event is detected by the runtime system. The quit event is raised when the user presses the QUIT signal key (Control+Backslash).
4. If DEFER QUIT is enabled and the quit event arrives during a procedural instruction (FOR loop), the runtime system sets QUIT_FLAG to  TRUE. It is the programmer's responsibility to manage the quit event (whether to stop or continue with the procedure).
5. If DEFER QUIT is enabled and the quit event arrives during an interactive instruction (INPUT, CONSTRUCT), the runtime system sets QUIT_FLAG to TRUE and exits from the instruction. It is recommended to test QUIT_FLAG after an interactive instruction to check if the input has been cancelled.

Warnings:

1. Once QUIT_FLAG is set to TRUE, it must be reset to FALSE by hand to detect a new quit event.

Example:

01 MAIN
02   DEFER QUIT
03   LET QUIT_FLAG = FALSE
04   INPUT BY NAME ...
05   IF QUIT_FLAG THEN
06      ...
07   END IF
08 END MAIN

Program Options

Purpose:

The OPTIONS instruction allows you to change default program options.

Syntax:

Notes:

1. The effect of the OPTIONS instruction is global to the entire program.
2. Most program options can be changed during the program execution.

Usage:

A program can include several OPTIONS statements. If these statements conflict in their specifications, the OPTIONS statement most recently encountered at runtime prevails. OPTIONS can specify the following features of other statements (such as CONSTRUCT, DISPLAY, DISPLAY ARRAY, DISPLAY FORM, ERROR, INPUT, INPUT ARRAY, MESSAGE, OPEN FORM, OPEN WINDOW, PROMPT and RUN ):

• Positions of the reserved lines
• Input and display attributes
• Logical key assignments
• The name of the Help file
• SQL statement interruption
• Field traversal constraints
• Default screen display mode

Defining the default position of reserved lines Console Only!

The following options define positions of  reserved lines in the console (character terminals). When using the standard graphical mode, is not recommended that you use these options, as most will have no effect on the display.

• COMMENT LINE specifies the position of the Comment line. The comment line displays messages defined with the COMMENT attribute in the form specification file. The default is (LAST-1) for the SCREEN, and LAST for all other windows. You can hide the comment line with COMMENT LINE OFF.
• ERROR LINE specifies the position on the screen of the Error line that displays the text of the ERROR statement. The default is the LAST line of the SCREEN.
• FORM LINE specifies the position of the first line of a form. The default is (FIRST+2), or line 3 of the current window.
• MENU LINE specifies the position of the Menu line. This displays the menu name and options, as defined by the MENU statement. The default is the FIRST line in the window.
• MESSAGE LINE specifies the position of the Message line. This reserved line displays the text of the MESSAGE statement. The default is (FIRST+1), or line 2 of the current window.
• PROMPT LINE specifies the position of the Prompt line where the text of PROMPT statements is displayed. The default value is the FIRST line in the window.

You can specify any of the following positions for each reserved line:

Defining the default display and the input attributes Console Only!

An ATTRIBUTE clause of an OPEN WINDOW, CONSTRUCT, INPUT, DISPLAY, INPUT ARRAY or DISPLAY ARRAY statement only temporarily redefines the attributes. After the window closes (in the case of an OPEN WINDOW statement) or after the statement terminates (in the case of an INPUT, DISPLAY, INPUT ARRAY or DISPLAY ARRAY statement), the runtime system restores the attributes from the most recent OPTIONS statement.

Any attribute defined by the OPTIONS statement remains in effect until the runtime system encounters an ATTRIBUTES clause that redefines the same attribute in one of the following statements:

• CONSTRUCT, INPUT, DISPLAY, INPUT ARRAY or DISPLAY ARRAY
• Another OPTIONS statement
• OPEN WINDOW  

The FORM keyword in INPUT ATTRIBUTE, or DISPLAY ATTRIBUTE clauses instructs the runtime system to use the input or display attributes of the current form. Similarly, you can use the WINDOW keyword of the same options to instruct the program to use the input or display attributes of the current window. You cannot combine the FORM or WINDOW attributes with any other attributes.

The following table shows the allowed input-attributes and display-attributes

Defining the form input loop

The tab order in which the screen cursor visits fields of a form is that of the field list of currently executing CONSTRUCT, INPUT, and INPUT ARRAY statements, unless the tab order has been modified by a NEXT FIELD clause. By default, the interactive statement terminates if the user presses RETURN in the last field (or if entered data fills the last field, if that field has the AUTONEXT attribute).

The INPUT WRAP keywords change this behavior, causing the cursor to move from the last field to the first, repeating the sequence of fields until the user presses the Accept key. The INPUT NO WRAP option restores the default input loop behavior.

Defining the default screen mode to run sub-processes

The RUN IN {FORM|LINE} MODE option can be used to set the default screen mode of the RUN instruction.

Controlling Application Termination

The OPTIONS ON TERMINATE SIGNAL CALL funcname defines the function that must be called when the application receives the SIGTERM signal. With this option you can control program termination - for example, by using ROLLBACK WORK to cancel all pending SQL operations. If this statement is not called, the program is stopped with an exit value of SIGTERM (15).

On Microsoft Windows platforms, the function will be called in the following cases:

• The console window that the program was started from is closed.
• The current user session is terminated (i.e. the user logs off).
• The system is shut down.

Controlling Front-End Termination

The OPTIONS ON CLOSE APPLICATION CALL function can be used to execute specific code when the front-end stops. For example, when the client program is stopped, when the user session is ended, or when the workstation is shut down.

Before stopping, the front-end sends a internal event that is trapped by the runtime system. When a callback function is specified with the above program option command, the application code that was executing is canceled, and the callback function as executed before the program stops.

You typically do a ROLLBACK WORK, close all files, and release all resources in that function.

You can configure this option in two ways:

• OPTIONS ON CLOSE APPLICATION STOP: The program stops as with EXIT PROGRAM 1.
• OPTIONS ON CLOSE APPLICATION CALL function: The user function is called, then the program stops.

Defining the message file

The HELP FILE clause specifies an expression that returns the filename of a help file. This filename can also include a pathname. Messages in this file can be referenced by number in form-related statements, and are displayed at runtime when the user presses the Help key.

See also Message Files.

Defining field tabbing order

In an INPUT, INPUT ARRAY, or CONSTRUCT, by default, the tabbing order is defined by the list of fields used by the program instruction. This corresponds to FIELD ORDER CONSTRAINED.

When using FIELD ORDER UNCONSTRAINED, the UP ARROW and DOWN ARROW keys will move the cursor to the field above or below, respectively. Use the FIELD ORDER CONSTRAINED option to restore the default behavior of the UP ARROW and DOWN ARROW keys (moving the cursor to the previous or next field, respectively).

Warning: The UNCONSTRAINED option is deprecated.

When you specify FIELD ORDER FORM,  the tabbing order is defined by the TABINDEX attributes of the current form fields. This allows you to define a tabbing order specific to the layout of the form, that is independent from the program instruction:

Form file:

01 LAYOUT
02 GRID
03 {
04   First name:  [f001            ]
05   Last name:   [f002            ]
06 }
07 END
08 END
09 ATTRIBUTES
10 EDIT f001 = FORMONLY.fname, TABINDEX = 1;
11 EDIT f002 = FORMONLY.fname, TABINDEX = 2;
12 END

Program file:

01 MAIN
02   DEFINE fname, lname CHAR(20)
03   OPTIONS FIELD ORDER UNCONSTRAINED
04   OPEN FORM f1 FROM "f1"
05   DISPLAY FORM f1
06   INPUT BY NAME fname, lname
07 END MAIN

Defining control keys Console Only!

The OPTIONS instruction can specify physical keys to support logical key functions in the interactive instructions.

Warning: The physical key definition options are only provided for backward compatibility with the character mode. These as not supported in graphical mode. Use the Action Defaults to define accelerator keys for actions.
Remark: In console mode, action defaults accelerators are ignored.

Here is the description of keys:

• The ACCEPT KEY specifies the key that validates a CONSTRUCT, INPUT, INPUT ARRAY, or DISPLAY ARRAY statement.
  The default ACCEPT KEY is ESCAPE.
• The DELETE KEY specifies the key in INPUT ARRAY statements that deletes a screen record.
  The default DELETE KEY is F2.
• The INSERT KEY specifies the key that opens a screen record for data entry in INPUT ARRAY.
  The default INSERT KEY is F1.
• The NEXT KEY specifies the key that scrolls to the next page of a program array of records in an INPUT ARRAY or DISPLAY ARRAY statement.
  The default NEXT KEY is F3.
• The PREVIOUS KEY specifies the key that scrolls to the previous page of program records in an INPUT ARRAY or DISPLAY ARRAY statement.
  The default PREVIOUS KEY is F4.
• The HELP KEY specifies the key to display help messages.
  The default HELP KEY is CONTROL-W.

You can specify the following keywords for the physical key names:

You might not be able to use other keys that have special meaning to your version of the operating system. For example, CONTROL-C, CONTROL-Q, and CONTROL-S specify the Interrupt, XON, and XOFF signals on many UNIX systems.

Setting default screen modes Console Only!

When using character terminals, BDL recognizes two screen display modes: line mode (IN LINE MODE) and formatted mode (IN FORM MODE). The OPTIONS and RUN statements can explicitly specify a screen mode. The OPTIONS statement can set separate defaults for these statements.

After IN LINE MODE is specified, the terminal is in the same state (in terms of stty options) as when the program began. This usually means that the terminal input is in cooked mode, with interruption enabled, and input not available until after a newline character has been typed.

The IN FORM MODE keywords specify raw mode, in which each character of input becomes available to the program as it is typed or read.

By default, a program operates in line mode, but so many statements take it into formatted mode (including OPTIONS statements that set keys, DISPLAY, OPEN WINDOW, DISPLAY FORM, and other screen interaction statements), that typical programs are actually in formatted mode most of the time.

When the OPTIONS statement specifies RUN IN FORM MODE, the program remains in formatted mode if it currently is in formatted mode, but it does not enter formatted mode if it is currently in line mode.

When the OPTIONS statement specifies RUN IN LINE MODE, the program remains in line mode if it is currently in line mode, and it switches to line mode if it is currently in formatted mode.

The RUN instruction

Purpose:

The RUN instruction creates a new process and executes the command passed as argument.

Syntax:

Notes:

1. command is a string expression containing the command to be executed.
2. variable is an integer variable receiving the execution status of the command.

Warnings:

1. The execution status in the RETURNING clause is system dependant. See below for more details.

Usage:

The RUN instruction executes an operating system command line;  you can even run a second application as a secondary process. When the command terminates, the runtime system resumes execution.

Waiting for the sub-process

By default, the runtime system waits for the end of the execution of the command.

Unless you specify WITHOUT WAITING, the RUN instruction also does the following:

1. Causes execution of the current program to pause.
2. Displays any output from the specified command in a new window.
3. After that command completes execution, closes the new window and restores the previous display in the screen.

If you specify WITHOUT WAITING, the specified command line is executed as a background process, and generally does not affect the visual display. This clause is useful if you know that the command will take some time to execute, and your program does not need the result to continue. 

Catching the execution status

The RETURNING clause saves the termination status code of the command that RUN executes in a program variable of type INTEGER. You can then examine this variable in your program to determine the next action to take. A status code of zero usually indicates that the command has terminated normally. Non-zero exit status codes usually indicate that an error or a signal caused execution to terminate.

The execution status provided by the RETURNING clause is platform dependant. On Unix systems, the value is composed by two bytes having different meanings. On Windows platforms, the execution status is usually zero for success, not zero if an error occurred.

The LINE and FORM mode

According to the type of command to be executed, you may need to use the line or form mode, which defines how the terminal or the graphical front-end behaves when running the child process.

By default, programs operate in line mode, but so many statements take it into form mode (including OPTIONS statements that set keys, DISPLAY, OPEN WINDOW, DISPLAY FORM, and other screen interaction statements) that typical programs are actually in form mode most of the time.

If no screen mode is specified in the RUN command, the current value from the OPTIONS statement is used. This is by default, IN LINE MODE. This mode is the opposite of the default screen mode for PIPE specifications.

When the RUN statement specifies IN FORM MODE, the program remains in form mode if it is currently in form mode, but it does not enter form mode if it is currently in line mode. When the prevailing RUN option specifies IN LINE MODE, the program remains in line mode if it is currently in line mode, and it switches to line mode if it is currently in form mode. The same comments apply to the PIPE option.

Remark: Besides RUN, the OPTIONS, START REPORT, and REPORT statements can explicitly specify a screen mode.

EXIT PROGRAM

Purpose:

The EXIT PROGRAM instruction terminates the execution of the program.

Syntax:

Notes:

1. exit-code is a valid integer expression that can be read by the process which invoked the program.
2. Usually, exit-code will be zero by default for normal, errorless termination.

Warnings:

1. exit-code is converted into a positive integer between 0 and 255 (8-bits).

Example:

01 MAIN
02   DISPLAY "Emergency exit."
03   EXIT PROGRAM (-1)
04   DISPLAY "This will never be displayed !"
05 END MAIN

Database Schema Specification

Purpose:

Database Schema Specification identifies the database schema files to be used for compilation.

Syntax 1:

Syntax 2:

Notes:

1. dbname identifies the name of the database schema file to be used.
2. The SCHEMA instruction defines the database schema files to be used for compilation.
3. The database name must be expressed explicitly, and not as a variable.
4. Use this instruction outside any program block, before a variable declaration with DEFINE LIKE instructions. It must precede any program block in each module that includes a DEFINE…LIKE declaration or INITIALIZE…LIKE and VALIDATE…LIKE statements. It must precede any GLOBALS…END GLOBALS block. It must also precede any DEFINE…LIKE declaration of module variables.
5. The [DESCRIBE] DATABASE instruction defines both the database schema files for compilation and the default database to connect to at runtime when the MAIN block is executed.

Warnings:

1. [DESCRIBE] DATABASE is still supported for backward compatibility, but it is recommended that you use SCHEMA instead.  The SCHEMA instruction defines only the database schema for compilation, and not the default database to connect to at runtime, which can have a different name than the development database.

Example:

01 SCHEMA dbdevelopment -- Compilation database schema
02 DEFINE rec RECORD LIKE customer.*
03 MAIN
04    DATABASE dbproduction -- Runtime database specification
05    SELECT * INTO rec.* FROM customer WHERE custno=1
06 END MAIN

NULL Constant

Purpose:

The NULL constant is provided as "nil" value.

Syntax:

Notes:

1. When comparing variables to NULL, use the IS NULL operator, not the equal operator.
2. If an element of an expression is NULL, the expression is evaluated to NULL.

Warnings:

1. Variables are initialized to NULL or to zero according to the data type.
2. Empty character strings ("") are equivalent to NULL.
3. NULL cannot be used with the = equal comparison operation, you must use IS NULL.

Example:

01 MAIN
02   DEFINE s CHAR(5)
03   LET s = NULL
04   DISPLAY "s IS NULL evaluates to:"
05   IF s IS NULL THEN 
06     DISPLAY "TRUE" 
07   ELSE 
08     DISPLAY "FALSE" 
09   END IF
10 END MAIN

TRUE Constant

Purpose:

The TRUE constant is a predefined boolean value that evaluates to 1.

Syntax:

Example:

01 MAIN
02   IF FALSE = TRUE THEN
03      DISPLAY "Something wrong here"
04   END IF
05 END MAIN

FALSE Constant

Purpose:

The FALSE constant is a predefined boolean value that evaluates to 0.

Syntax:

Example:

01 FUNCTION isodd( value )
02   DEFINE value INTEGER
03   IF value MOD 2 = 1 THEN
04      RETURN TRUE
05   ELSE
06      RETURN FALSE
07   END IF
08 END FUNCTION

NOTFOUND Constant

Purpose:

The NOTFOUND constant is a predefined integer value that evaluates to 100.

Syntax:

Notes:

1. This constant is used to test the execution status of an SQL statement returning a result set, to check if rows have been found.

Example:

01 MAIN
02   DATABASE stores
03   SELECT tabid FROM systables WHERE tabid = 1
04   IF SQLCA.SQLCODE = NOTFOUND THEN
05      DISPLAY "No row was found"
06   END IF
07 END MAIN

BREAKPOINT

Purpose:

The BREAKPOINT instruction sets a program breakpoint when running in debug mode.

Syntax:

Usage:

When you start fglrun in debug mode, if the program flow encounters a BREAKPOINT instruction, the program execution stops and the debug prompt is displayed, to let you enter a debugger command.

The BREAKPOINT instruction is ignored when not running in debug mode.

Example:

01 MAIN
02   DEFINE i INTEGER
03   LET i=123
04   BREAKPOINT
05   DISPLAY i
06 END MAIN

DISPLAY

Purpose:

The DISPLAY instruction displays text in line mode to the standard output channel.

Syntax:

Notes:

1. expression is any expression supported by the language.
2. The comma acts as a character string operator to concatenate strings. 
3. The values contained in variables are formatted according to the data type.

Usage:

You can use this instruction to display information to the standard output channel. 

Example:

01 MAIN
02   DISPLAY "Today's date is: ", TODAY
03 END MAIN

ERROR

Purpose:

The ERROR instruction displays an error message to the user.

Syntax:

Notes:

1. text is a string literal or variable.
2. The comma can be used as an operator to concatenate strings.
3. display-attributes is a list of attributes to display the error text. See below.
4. When using the console the error text is displayed in the Error Line of the current window. With the standard graphical style, the text is displayed in a specific area, depending on the front end configuration.

Usage:

The following table shows the display-attributes supported by the ERROR statement:

Example:

01 MAIN
02    WHENEVER ERROR CONTINUE
03    DATABASE stock
04    WHENEVER ERROR STOP
05    IF sqlca.sqlcode THEN
06       ERROR "Connection failed (" || sqlca.sqlcode || ")"
07    END IF
08 END MAIN

MESSAGE

Purpose:

The MESSAGE instruction displays a message to the user.

Syntax:

Notes:

1. text is a string literal or variable.
2. The comma can be used as an operator to concatenate strings.
3. display-attributes is a list of attributes to display the error text. See below.
4. When using the console the text is displayed in the Comment Line of the current window. With the standard graphical style, the text is displayed in a specific area, depending on the front end configuration.

Usage:

The following table shows the display-attributes supported by the MESSAGE statement:

Example:

01 MAIN
02    WHENEVER ERROR CONTINUE
03    DATABASE stock
04    WHENEVER ERROR STOP
05    IF sqlca.sqlcode THEN
06       ERROR "Connection failed (" || sqlca.sqlcode || ")"
07    ELSE
08       MESSAGE "Connected to database."
09    END IF
10 END MAIN

Setting Key Labels

Purpose:

This feature allows you to define the labels of keys, to show a specific text in the default action button created for the key.

Syntax 1: In FGLPROFILE

Syntax 2: At the program level

Syntax 3: At the form level

Syntax 4: At the dialog level

Syntax 5: At the field level

Notes:

1. key-name is the name of the key as defined below.

Usage:

Traditional 4GL applications use a lot of function keys and/or control keys to manage user actions. For example, in the following interactive dialog, the function key F10 is used to show a detail window:

01 INPUT BY NAME myrecord.*
02    ON KEY (F10)
03       CALL ShowDetail()
04 END INPUT

For backward compatibility, the language allows you to specify a label to be displayed in a default action button created specifically for the key.

By default, if you do not specify a label, no action button is displayed for a function key or control key.

The following table shows the key names recognized by the runtime system:

You can define key labels at different levels, from the default settings to a specific field, to show a specific label for the key when the focus is in that field. The order of precedence for key label definition is the following:

1. The label defined with the KEY attribute of the form field.
2. The label defined for the current dialog, using the FGL_DIALOG_SETKEYLABEL function.
3. The label defined in the KEYS sections of the form specification file.
4. The label defined as default for a program, using the FGL_SETKEYLABEL function.
5. The label defined in the FGLPROFILE configuration file (key.key-name.text entries).

You can query the label defined at the program level with the FGL_GETKEYLABEL function and, for the current interactive instruction, with the FGL_DIALOG_GETKEYLABEL function.