EUS Online Help

Overview

Online help is called automatically from the Input Subsystem when the <HELP> key is pressed. In addition, application programs can display help without user input by calling the appropriate help utility. Three methods of help are supported:

Indexed ASCII text files containing contextual help information. These are displayed with _help.utl.
TAOS forms containing help information.
Searchable ASCII text files. These files are displayed by calling _help.pub. This is a slower access method than number one.

The following paragraphs describe setting up indexed help files. Searchable help files are discussed in more detail in _help.pub.

Indexed Help Files

The indexed help filesystem requires two files. The first is an ASCII file that contains all help screen text. One or more help screens can be defined in the help file. Each screen consists of two parts: the screen name or key, and the body of the help text. The header is indicated with a }{ marker.

This example illustrates the structure of the ASCII help file:

[ Help File Title ]
}{the first key
This is the first entry in the help file.
It will display in the help box.
}{ddmc
Data Dictionary - Copy File
This option copies the complete file
definition from one alias to another.

Always leave at least one blank line between each entry and the next key. This is required by the help indexing utility, _helpidx.utl.

Key values must be unique in the help file. The maximum length for keys is 32 characters. Spaces are allowed. Keys are forced to lower case by the help indexing utility.

Add to or edit the existing help screens using any text editor. After additions or changes have been made to the ASCII help file, it must be reindexed with the _helpidx.utl before it is used.

_help.utl supports global strings in help text. Global strings are indicated by enclosing them in parentheses in the help text. For example:

This screen allows address information for (COMPANY) to be changed.

_help.utl checks for the global string (COMPANY) and, if it exists, places the contents of that string into the help text before displaying it. It is possible to structure a heading for each help entry that draws upon global strings to indicate the date, workstation, operator code, and so on.

The second file required by the help system is an MKEYED file that contains indexes into the ASCII text file. The help system uses this file to quickly locate the correct screen of text when the <HELP> key is pressed, avoiding a record-by-record read of the ASCII text file. The _helpidx.utl utility will create the index file if it does not already exist.

The (HELPFILE) global string in the config.EUS file should specify the root name of the default help file. If the (HELPFILE) global string is not set, the default root help file name is assumed to be thelp. The name of the ASCII help file is the root name with the current language code as the extension. The name of the index file is the root name with an "i" appended and the current language code as the extension. For example, if the default root name, thelp, and the American language code, am, are being used, then the help file names will be:

Help File	File name
ASCII text	thelp.am
Index file	thelpi.am

If the (LANGUAGE) global string is not "am" and the help file and form cannot be found, the help system will use ".am" and ".fam" respectively.

Ensure that the ASCII help file name does not create an invalid file name with the appended "I."

To display the help screen "ddmc" in the thelp file:

CALL STBL("BBEXT")+"_help.utl","thelp@ddmc"

(or)

TRASH$=STBL("HELPFILE","thelp")
CALL STBL("BBEXT")+"_help.utl","ddmc"

This displays the sample help item shown earlier. The example uses the default root name thelp as the name of the help file and am as the current language code.

Using the current language code as the extension in the file names enhances support for multiple languages and only requires that an additional help text file be built for each supported language.

TAOS Forms as Help Files

Assuming a current language code of "de" (German) invokes a TAOS form object named account.fde:

CALL STBL("BBEXT")+"_help.utl","account"

The search path for this file is determined by the setting of the (HELP) global string.

Searchable Help Files

The following are two examples of calling help using _help.utl to utilize searchable help files:

CALL STBL("BBEXT")+"_help.utl","gl.hlp","account"

(or)

CALL STBL("BBEXT")+"_help.utl","gl.hlp;account"

This is translated to the following CALL:

CALL STBL("BBSTD")+"_help.pub","account","gl.hlp"

Refer to _help.pub for additional information.

Help on Help

If the user presses <HELP> within a help screen, the _help.utl utility calls the utility (BBEXT)_stdhelp.utl. This is a simple keymap display and can be overridden by editing the (HELPONHELP) global string in the configuration file:

PROJECT=/basis/acct/
HELPONHELP=(PROJECT)global.help

This tells _help.utl that a <HELP> key pressed within a help screen will call the global.help utility, located in the (PROJECT) directory, which is /basis/acct/ in this example.