Back to Contents

Message Files

Summary:

See also: OPTIONS, SHOWHELP(), fglmkmsg, Localized Strings.

Basics

Message Files define text messages with a unique integer identifier. You can create as many message files as needed. Message files are typically used to implement application help system, especially when using the Text User Interface mode.

In order to use a message file, you need to do the following: 

  1. Create the source message file with a text editor.
  2. Compiler the source message file to a binary format.
  3. Copy the binary file to a distribution directory.
  4. In programs, specify the message file with OPTIONS HELP FILE.

Message files are supported for backward compatibility. You should also have a look at the Localized Strings feature.

Syntax

filename.msg

Notes:

  1. filename is the name of the message source file.

Syntax of a message file:

{
  message-definition
| include-directive
}
[...]

where message-definition is:

.message-number
message-line | new-page
[...]

where include-directive is:

.include file-name

and where new-page is:

^L (Control-L, ASCII 12)

Notes:

  1. message-number is an integer in the range -2147483648 to 2147483647.
  2. You can split the message into pages by adding the ^L (Control-L / ASCII 12) in a line.
  3. Note that multi-line messages will include the new-line (ASCII 10) characters.

Compiling Message Files

In order to use message files in a program, the message source files (.msg) must be compiled with the fglmkmsg utility to produce compiled message files (.iem).

The following command line compiles the message source file mess01.msg:

fglmkmsg mess01.msg

This creates the compiled message file mess01.iem.

For backward compatibility, you can specify the output file as second argument:

fglmkmsg mess01.msg mess01.iem

The .iem compiled version of the message file must be distributed on the machine where the programs are executed.

Using Message Files

In order to use compiled message files (.iem) in programs, you must first specify the message file with the OPTIONS HELP FILE command:

01  OPTIONS HELP FILE "mymessages.iem"

The message file will first be searched with the string passed to the OPTIONS HELP FILE command (i.e. the current directory if the file is specified without a path), and if not found, the DBPATH/FGLRESOURCEPATH environment variable with be used.

After the message file is defined, you can start the help viewer by calling the SHOWHELP() function:

01  CALL showhelp(1242)

You can also use the HELP keyword in a dialog instruction like INPUT to define particular message number for that the dialog:

01  INPUT BY NAME ... HELP 455

The help viewer will automatically display the message text corresponding to the number when the user pressed the help key. By default, the help key is CONTROL-W in TUI mode and F1 in GUI mode.

Example

Message source file example:

01 .101
02 This is help about option 1
03 .102
04 This is help about help
05 .103
06 This is help about My Menu

Application using this help message:

01 MAIN
02     OPTIONS
03         HELP FILE "help.iem"
04     OPEN WINDOW w1 AT 5,5 WITH FORM "const"
05     MENU "My Menu"
06         COMMAND "Option 1" HELP 101
07 	       DISPLAY "Option 1 chosen"
08         COMMAND "Help"
09             CALL SHOWHELP(103)
10     END MENU
11     CLOSE WINDOW w1
12 END MAIN