Using Command Abbreviations

Start of change An abbreviations file contains command synonyms and abbreviations, which the HELP facility uses to search for HELP files. End of change

Benefits of abbreviations files

Abbreviations and synonyms that are defined in an abbreviations file provide more opportunities to locate a HELP file. The role of an abbreviations file is similar to a synonym file discussed in Using Synonyms.

Start of change An abbreviations file can be used to provide help for command names that contain special characters other than those special characters that are supported by the HELP facility. For more information about translation of special characters in command names, see Command HELP name conventions. End of change

Start of change Abbreviations files increase the responsiveness of the HELP facility. Even if an abbreviations file contains no abbreviation or synonym definition, it can decrease the time that the HELP facility requires to search for a HELP file. End of change If no abbreviations are appropriate for any files in the HELP component, you can create an abbreviations file that contains only a comment line, which is indicated by an asterisk (*) in column 1.

Abbreviations file name convention

An abbreviations file name must identify a HELP component. For more information, see item 4

An abbreviations file type must be HELPABBR.

Abbreviations file structure

Each line in an abbreviations file contains 2-3 words:

File name: The first word is the file name of the command file. The file type is not included. The file name is required.
Synonym: The second word is the file name of the command file or a synonym. The second word is required.
Minimum abbreviation: The third word is a number, 1-8, that specifies the minimum abbreviation length that is allowed when the second word is specified as a cmd_name operand on the HELP command. If the number is omitted, the default value is the length of the second word or 8, whichever is less. If the number is 9 or more, the definition is not valid.

The order of the entries in the HELPABBR file can affect which command file is matched by the filename operand of the HELP command. The first entry that matches the filename operand on a HELP command determines the help topic that is retrieved. Other matches after the first match are ignored. The following table shows an example of which command file is retrieved given a set of HELPABBR file entries and a HELP command with an abbreviated filename operand. Assume the abbreviations file is ASSOCIAT HELPABBR and two files with similar names are EXIT_A HELPASSO and EXIT_B HELPASSO.

Table 1. The order of entries in a HELPABBR file and the retrieved command file
ASSOCIAT HELPABBR entries	HELP commands	Filename of the retrieved help file
`EXIT_A exit_a 2 EXIT_B exit_b 1`	`help associat e`	EXIT_B
	`help associat ex help associat exi help associat exit help associat exit_`	EXIT_A
	`help associat exit_b`	EXIT_B
`EXIT_B exit_b 1 EXIT_A exit_a 2`	`help associat e help associat ex help associat exi help associat exit help associat exit_`	EXIT_B
`EXIT_B exit_b 1 EXIT_A exit_a 2`	`help associat exit_a`	EXIT_A

Requirements for a search that uses an abbreviations file

Start of change The HELP facility always searches for a command file whose file name is specified by the command name (cmd_name) operand of the HELP command but can also search for synonyms and abbreviations of the command name. The synonyms and abbreviations must be defined in an abbreviations file (file type HELPABBBR). There are matching requirements among the operands of the HELP command, the file name and contents of the HELPABBR file, and the file name and file type of the target HELP file. Conditions 2 and 4 indicate that one set of matching requirements is satisfied if the component_name operand of the HELP command and the file name of the abbreviations file are a HELP component name that accurately identifies the appropriate HELP component. End of change

The HELP facility retrieves and displays a HELP file by using an abbreviations file when all the following conditions are true:

The HELP facility does not find a HELP file whose file name matches the cmd_name and that belongs to the HELP component that is specified by the component_name operand.

The component_name operand of the HELP command matches an abbreviations file name. The match criterion depends on the length of the abbreviations file name:

When the abbreviations file name is 8 characters, the first 8 characters of component_name must match the abbreviations file name.
When the abbreviations file name is less than 8 characters, component_name must match the abbreviations file name exactly.

The following table provides examples where the HELP command component_name operand matches an abbreviations file name.

Table 2. HELP command `component_name` operands that match an abbreviations file name
HELP command `component_name` operand	Abbreviations file
cp	CP HELPABBR
display	DISPLAY HELPABBR
directory	DIRECTOR HELPABBR
rscs	RSCS HELPABBR
rscsauth	RSCSAUTH HELPABBR
rscsauthorization	RSCSAUTH HELPABBR

The cmd_name operand of the HELP command matches an abbreviation or synonym that is defined in the abbreviations file that is identified in item 2. The match criterion depends on the length of the command file name:

When the cmd_name operand of the HELP command contains 8 or more characters, the first 8 characters of the cmd_name operand must match the first 8 characters of the abbreviation or synonym.
When the the cmd_name operand is less than 8 characters, the cmd_name operand must match the abbreviation or synonym exactly.

The following table provides examples where the cmd_name operand of the HELP command matches an abbreviation or synonym. The abbreviation and synonym definition examples are from the DISPLAY HELPABBR abbreviations file. The abbreviations and synonyms are defined for the GUESTZ HELPDISP command file.

Table 3. HELP command `cmd_name` operands that match an abbreviation or synonym definition
HELP command `cmd_name` operand	Abbreviation or synonym definition
gueststg	`GUESTZ GUESTSTG 8`
z	`GUESTZ Zarchitecture 1`
zarch	`GUESTZ Zarchitecture 1`
zarchitecture	`GUESTZ Zarchitecture 1`
zarchite9012345	`GUESTZ Zarchitecture 1`

The HELP file whose name matches the synonym or abbreviation is in the identified HELP component. In this case, "HELP component" is defined strictly as the last 5-8 characters (suffix) of a HELP file type. The HELP component is identified by the file name of the HELPABBR file. The identification criterion depends on the length of the file name of the HELPABBR file:

When the length of the file name of the HELPABBR file is four or more characters, the first four characters of the file name of the HELPABBR file must match the last four characters of a HELP file type.
When the length of the file name of the HELPABBR file is three or fewer characters, the file name of the HELPABBR file must match a HELP file type exactly.

The following table provides examples of abbreviations file names that identify HELP components.

Table 4. Abbreviations file names that identify HELP components
File type	File type suffix	Abbreviations file
HELPCP	CP	CP HELPABBR
HELPDISP	DISP	DISPLAY HELPABBR
HELPDIRE	DIRE	DIRECTOR HELPABBR
HELPRSCS	RSCS	RSCS HELPABBR
HELPRSCS	RSCS	RSCSAUTH HELPABBR

In the following example, the conditions are satisfied for the HELP facility to retrieve and display a HELP file by using an abbreviations file. The target file is the GUESTZ HELPDISP file, which contains information about the CP DISPLAY GUESTZ command. The CP DISPLAY GUESTZ command displays the storage contents of a virtual machine in z/Architecture® mode. The DISPLAY HELPABBR abbreviations file contains the following synonyms and abbreviations definitions for the GUESTZ HELPDISP file name:

GUESTZ     Zarchitecture 1
GUESTZ     GUESTSTG      8

The HELP facility retrieves and displays the GUESTZ HELPDISP file when you enter any of the following HELP commands:

help display gueststg

help display z

help display zarch

help display zarchitecture

help display zarchite901234

The example that contains zarchite901234 shows that the matching criterion is met when the first eight characters of the cmd_name operand match the first eight characters of the synonym definition. The matching term is zarchite. End of change

Of course, the HELP facility also retrieves and displays the GUESTZ HELPDISP file when you use the file name of the command file as the cmd_name operand:

help display guestz

Abbreviations for HELPMENU and HELPTASK files

Abbreviations files typically define synonyms and abbreviations for command HELP files. However, the HELP facility can use abbreviations files to match the names of HELMENU and HELPTASK files. In this case, the menu file type suffixes ("MENU" and "TASK") play the role of HELP component names and the menu file name plays the role of the command file name.

For example, create a MENU HELPABBR file with the following synonym definition for the PIPE HELPMENU file:

pipe      cmspipe  4

After you create the MENU HELPABBR file, the following command displays the PIPE HELPMENU file:

help menu cmsp