Back to Contents

Programs

Summary:

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

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 this parameter is set to true, intermediate triggers are executed. As the user moves 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 field and the destination field. When the parameter is set to false, intermediate triggers are not executed.

For new applications, it is recommended that you set the parameter to false. GUI applications allow users to jump from one field to any other field of the form by using the mouse. Therefore, it makes no sense to execute the BEFORE FIELD / AFTER FIELD triggers of intermediate fields.

Important note: 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 to false.

Warning: The Dialog.fieldOrder configuration parameter is ignored when the dialog uses the FIELD ORDER FORM option.

Make current row visible after sort in tables

Dialog.currentRowVisibleAfterSort = {true|false}

When this parameter is set to true, the offset of table page is automatically adapted to show the current row after a sort. By default, the offset is not changed and current row may not be visible after sorting rows of a table. Changing this parameter has no impact on existing code, it is just an indicator to force the dialog to shift to the page of rows having the current row, as if the end-user had scrollbar. You can use this parameter to get the same behavior as well known e-mail readers. 

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 control to this program block.

Syntax:

MAIN
  [ define-statement | constant-statement ]
  { [defer-statement] | fgl-statement | sql-statement }
  [...]
END MAIN

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:

DEFER { INTERRUPT | QUIT }

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:

DEFER INTERRUPT indicates that the program must continue when it receives an interrupt signal. By default, the program stops when it receives an interrupt signal.

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

Interrupt signals are raised on terminal consoles when the user presses a key like CTRL-C, depending on the stty configuration. When a BDL program is displayed through a front end, no terminal console is used; 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 details, refer to Interruption Handling in the Dynamic User Interface.

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

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

STATUS

Purpose:

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

Syntax:

STATUS

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. Use SQLCA.SQLCODE for SQL error management, and STATUS for 4gl errors.

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:

INT_FLAG

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 that you test INT_FLAG after an interactive instruction to check whether the input has been cancelled.

Warnings:

  1. Once INT_FLAG is set to TRUE, it must be reset to FALSE to detect a new interruption event. It is the programmer's responsibility to reset the INT_FLAG to FALSE.

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:

QUIT_FLAG

Definition:

DEFINE QUIT_FLAG INTEGER

Notes:

  1. The data type of QUIT_FLAG is INTEGER.
  2. QUIT_FLAG is 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 that you test QUIT_FLAG after an interactive instruction to check whether the input has been cancelled.

Warnings:

  1. Once QUIT_FLAG is set to TRUE, it must be reset to FALSE to detect a new quit event. It is the programmer's responsibility to reset the QUIT_FLAG to FALSE.

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

Importing modules

Purpose:

The IMPORT instruction declares a C extension to be used by the current module.

Syntax:

IMPORT filename [,...]

Notes:

  1. filename is the identifier (without the file extension) of the module to be loaded.

Usage:

The IMPORT instruction must be used to declare a C extension implementing functions or variables used by the current module.

Modules declared with the IMPORT instruction do not have to be linked to create a program. The runtime system automatically loads dependent modules.

The FGLLDPATH environment variable specifies the directories to search for the modules.

By default, the runtime system tries to load a module with the name userextension, if it exists. This simplifies the migration of existing C extensions; you just need to create a shared library named userextension.so (or userextension.dll on Windows), and copy the file to one of the directories defined in FGLLDPATH.

Warnings:

  1. The IMPORT instruction must be the first instruction in the current module. If you specify this instruction after DEFINE, CONSTANT or GLOBALS, you will get a syntax error.
  2. The compiler converts the module name specified by IMPORT to lowercase letters (if you write IMPORT MyModule, the name is stored as "mymodule" in the pcode.) When the module is loaded at runtime, the filename must match the lowercase name. Therefore, you must always use lowercase filenames for modules. Using lowercase filenames also simplifies distribution on platforms like Windows, where filenames are not case-sensitive.

Example:

01 IMPORT mylib1, mylib2
02 DEFINE filename STRING
03 MAIN
04   CALL func1()  -- function defined in mylib1
05 END MAIN

See also: C Extensions.

Program Options

Purpose:

The OPTIONS instruction allows you to change default program options.

Syntax:

OPTIONS
{ INPUT [NO] WRAP
| HELP FILE help-filename
| INPUT ATTRIBUTE ( {FORM|WINDOW|input-attributes} )
| DISPLAY ATTRIBUTE ( {FORM|WINDOW|display-attributes} )
| SQL INTERRUPT {ON|OFF}
| FIELD ORDER {CONSTRAINED|UNCONSTRAINED|FORM}
| ON TERMINATE SIGNAL CALL user-function
| ON CLOSE APPLICATION {CALL user-function|STOP}
| RUN IN {FORM|LINE} MODE
| MESSAGE LINE line-value TUI Only!
| COMMENT LINE {OFF|line-value} TUI Only!
| PROMPT LINE line-value TUI Only!
| ERROR LINE line-value TUI Only!
| FORM LINE line-value TUI Only!
| INSERT KEY key-name TUI Only!
| DELETE KEY key-name TUI Only!
| NEXT KEY key-name TUI Only!
| PREVIOUS KEY key-name TUI Only!
| ACCEPT KEY key-name TUI Only!
| HELP KEY key-name TUI Only!
} [,...]

Notes:

  1. The effect of the OPTIONS instruction is global for 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 ):

Defining the default position of reserved lines TUI Only!

The following options define the positions of reserved lines in TUI mode. Is it not recommended that you use these options in GUI mode, as most have no effect on the display.

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

Expression Description
FIRST The first line of the screen or window.
FIRST + integer A relative line position from the first line.
integer An absolute line position in the screen or window.
LAST - integer A relative line position from the last line.
LAST The last line of the screen or window.

Defining the default display and the input attributes

Any attribute defined by the OPTIONS statement remains in effect until the runtime system encounters a statement that redefines the same attribute. This can be another OPTIONS statement, or an ATTRIBUTE clause in one of the following statements:

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

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 clauses 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 valid input-attributes and display-attributes:

Attribute Description
BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, WHITE, YELLOW The color of the displayed text.
BOLD, DIM, INVISIBLE, NORMAL The font attribute of the displayed text.
REVERSE, BLINK, UNDERLINE The video attribute of the displayed text.

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 the entered data fills the last field and 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.

Application Termination

The OPTIONS ON TERMINATE SIGNAL CALL function 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:

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 is executed before the program stops.

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

The default is OPTIONS ON CLOSE APPLICATION STOP. This instructs the runtime system to stop without any error message if the front end program is stopped.

Note that a front-end program crash or network failure is not detected and cannot be handled by this instruction.

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.

By default, message files are searched in the current directory, then DBPATH environment variable is scanned to find the file.

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 can only be supported in TUI mode, with a simple form layout. It is not recommended to use this option: it is supported for backward compatibility only.

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, independent of 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.lname, 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 TUI 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 GUI mode. Use the Action Defaults to define accelerator keys for actions.
In TUI mode, action defaults accelerators are ignored.

Description of the keys:

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

Key Name Description
ESC or ESCAPE The ESC key (not recommended, use ACCEPT instead).
INTERRUPT The interruption key (on UNIX, interruption signal).
TAB The TAB key (not recommended).
CONTROL-char A control key where char can be any character except A, D, H, I, J, K, L, M, R, or X
F1 through F255 A function key.
LEFT The left arrow key.
RETURN or ENTER The return key.
RIGHT The right arrow key.
DOWN The down arrow key.
UP The up arrow key.
PREVIOUS or PREVPAGE  The previous page key.
NEXT or NEXTPAGE  The next page key.

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

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 an argument.

Syntax:

RUN command 
  [ IN {FORM|LINE} MODE ]
  [ RETURNING variable | WITHOUT WAITING ]

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 dependent. 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.

Defining the command execution shell

In order to execute the command line, the RUN instruction uses the OS-specific shell defined in the environment of the current user. On UNIX, this is defined by the SHELL environment variable. On Windows, this is defined by COMSPEC. Note that on Windows, the program defined by the COMSPEC variable must support the /c option as CMD.EXE.

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. It is also used in GUI mode to start another Genero program. In TUI mode, you must not use this clause because two programs cannot run simultaneously on the same terminal.

Catching the execution status

The RETURNING clause saves the termination status code of the command that RUN executes in a program variable of type SMALLINT. 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.

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

On Unix systems, the lower byte (x mod 256) of the return status defines the termination status of the RUN command. The higher byte (x / 256) of the return status defines the execution status of the program. On Windows systems, the value of the return status defines the execution status of the program.

IN LINE MODE and IN FORM MODE

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

According to the type of command to be executed, you may need to use the IN {LINE|FORM} MODE clause with the RUN instruction. It defines how the terminal or the graphical front-end behaves when running the child process.

Besides RUN, the OPTIONS, START REPORT, and REPORT statements can explicitly specify a screen mode. 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. The default screen mode for PIPE specifications in REPORT  is IN FORM MODE.

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. This also applies to the PIPE option.

Typically, if you need to run another interactive program, you must use the IN LINE MODE clause:

However, if you want to execute a sub-process running silently (batch program without output), you must use the IN FORM MODE clause:

Tip: To summarize, the FORM MODE must be used to optimize programs, if the child program does not do any output. If the child program uses interactive instructions, displays messages to the terminal, or if you don't known what it does, just use the RUN instruction in LINE MODE (which is the default).

It is recommended that you use functions to encapsulate child program and system command execution:

01 MAIN
02   DEFINE result SMALLINT
03   CALL runApplication("app2 -p xxx")
04   CALL runBatch("ls -l", FALSE) RETURNING result
05   CALL runBatch("ls -l > /tmp/files", TRUE) RETURNING result
06 END MAIN
07
08 FUNCTION runApplication(pname)
09    DEFINE pname, cmd STRING
10    LET cmd = "fglrun " || pname
11    IF fgl_getenv("FGLGUI") == 1 THEN
12       RUN cmd WITHOUT WAITING
13    ELSE
14       RUN cmd
15    END IF
16 END FUNCTION
17
18 FUNCTION runBatch(cmd, silent)
19    DEFINE cmd STRING
20    DEFINE silent STRING
21    DEFINE result SMALLINT
22    IF silent THEN
23       RUN cmd IN FORM MODE RETURNING result
24    ELSE
25       RUN cmd IN LINE MODE RETURNING result
26    END IF
27    IF fgl_getenv("OS") MATCHES "Win*" THEN
28       RETURN result
29    ELSE
30       RETURN ( result / 256 )
31    END IF
32 END FUNCTION

EXIT PROGRAM

Purpose:

The EXIT PROGRAM instruction terminates the execution of the program.

Syntax:

EXIT PROGRAM [ exit-code ]

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:

SCHEMA dbname

Syntax 2:

[DESCRIBE] DATABASE dbname

Notes:

  1. The SCHEMA instruction defines the database schema files to be used for compilation.
  2. dbname identifies the name of the database schema file to be used.
  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 supported for backward compatibility, but it is strongly 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:

NULL

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 their data type.
  2. Empty character string literals ("") 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:

TRUE

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:

FALSE

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:

NOTFOUND

Notes:

  1. This constant is used to test the execution status of an SQL statement returning a result set, to check whether 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:

BREAKPOINT

Usage:

Normally, to set a breakpoint when you debug a program, you must use the break command of the debugger. But in some situations, you might need to set the breakpoint programmatically. Therefore, the BREAKPOINT instruction has been added to the language.

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

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

key.key-name.text = "label"

Syntax 2: At the program level

CALL FGL_SETKEYLABEL( "key-name", "label" )

Syntax 3: At the form level

KEYS
key-name = "label"
[...]
[END]

Syntax 4: At the dialog level

CALL FGL_DIALOG_SETKEYLABEL( "key-name", "label" )

Syntax 5: At the field level

KEY key-name = "label"

Notes:

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

Warning:

  1. This feature is provided for backward compatibility.

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:

Key Name Description
f1 to f255 Function keys.
control-a to control-z Control keys.
accept Validation key.
interrupt Cancellation key.
insert The insert key when in an INPUT ARRAY.
delete The delete key when in an INPUT ARRAY.
help The help key.

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 section 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.

Responding to CTRL_LOGOFF_EVENT

Purpose:

On Windows platforms, when the user disconnects, the system sends a CTRL_LOGOFF_EVENT event to all console applications. When the DVM receives this event, it stops immediately (a simple exit(0) system call is done).

On a Windows Terminal Server, if an Administrator user closes his session, a CTRL_LOGOFF_EVENT is sent to all console applications started by ANY user connected to the machine (even if these applications were not started by the Administrator).

To prevent the DVM from stopping on a logoff event, you can use the fglrun.ignoreLogoffEvent entry in the FGLPROFILE configuration file. If this entry is set to true, the CTRL_LOGOFF_EVENT event is ignored by the DVM.

fglrun.ignoreLogoffEvent = true

As a result, when the Administrator user disconnects on a Windows Terminal Server, programs started by remote users would not stop.