syntax/ICHLPUS | Information Center Help |
In this information center, the syntax for commands is presented in the form of a diagram. The diagram tells you what you can do with the particular command, and indicates relationships between different options and, sometimes, different values of an option.
To change the format of syntax diagrams throughout the information center, expand Preferences in the home navigation panel, select Syntax diagrams, and choose your preferred format.
Syntax diagrams can be displayed in one of the following formats:
Railroad diagrams are a visual format suitable for sighted users of the information center. BNF and dotted decimal format are text-based formats that are more helpful for blind or partially sighted users. For the benefit of screen reader users, BNF and dotted decimal format are described first in this Help topic, before railroad diagrams.
Of the text-based formats, BNF is more difficult for beginners to understand, but because it was used in IBM information before the introduction of the railroad syntax diagram, you may already be familiar with it. Dotted decimal format is easier for beginners to understand.
Tip for Screen Reader Users: Ensure that your screen reader is set to read all punctuation before reading syntax diagrams or this Help topic.
In BNF, the syntax is written in a single line. Square brackets, ([ ]), braces, ({ }), and the vertical bar symbol (|), are used to describe the syntax. Collectively, these symbols are known as controls.
Blanks are used to separate the syntax elements from the square brackets, braces and vertical bars. Use your screen reader's speak next word (usually Control + RightArrow key) and speak prior word (usually Control + LeftArrow key) to move between successive BNF controls and syntax elements.
The characters that you need to include when you are constructing your command, for example brackets or braces, and separator, such as a comma, are located at the point at which you need to key them in. For example, a left bracket may be read out before a list of options. In some programming languages such as C, C++, and Java(TM), square brackets, braces, and the vertical bar symbol are used within the language. For ease of identification where the square bracket, brace, or vertical bar symbol is displayed in the syntax diagram as a part of the programming language, it is preceded by the backslash (\). If you hear \{, enter the { symbol at that point when you are constructing your command because the { symbol is not a part of the structure of the syntax diagram.
The BNF rendering works as follows:
In dotted decimal format, each syntax element is written on a separate line. If two or more syntax elements are always present together (or always absent together), they can appear on the same line, because they can be considered as a single compound syntax element.
Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To hear these numbers correctly, make sure that your screen reader is set to read out punctuation. All the syntax elements that have the same dotted decimal number (for example, all the syntax elements that have the number 3.1) are mutually exclusive alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, you know that your syntax can include either USERID or SYSTEMID, but not both.
The dotted decimal numbering level denotes the level of nesting. For example, if a syntax element with dotted decimal number 3 is followed by a series of syntax elements with dotted decimal number 3.1, all the syntax elements numbered 3.1 are subordinate to the syntax element numbered 3.
Characters such as commas, which are used to separate a string of syntax elements, are shown in the syntax just before the items they separate. They might appear on the same line as each item, or on a separate line with the same dotted decimal number as the relevant items. The line may also show another symbol giving information about the syntax elements. For example, the lines 5.1*, 5.1 LASTRUN, and 5.1 DELETE mean that if you use more than one of the LASTRUN and DELETE syntax elements, they must be separated by a comma. If no separator is given, assume that you use a blank to separate each syntax element.
If a syntax element is preceded by the % symbol, this indicates a reference that is defined elsewhere. The string following the % symbol is the name of a syntax fragment rather than a literal. For example, the line 2.1 %OP1 means that you should refer to separate syntax fragment OP1.
Certain words and symbols are used next to the dotted decimal numbers to add information about the syntax elements. Occasionally, these words and symbols might occur at the beginning of the element itself. For ease of identification, if the word or symbol is a part of the syntax element, it is preceded by the backslash (\) character. The * symbol can be used next to a dotted decimal number to indicate that the syntax element repeats. For example, syntax element *FILE with dotted decimal number 3 is given the format 3 \* FILE. Format 3* FILE indicates that syntax element FILE repeats. Format 3* \* FILE indicates that syntax element * FILE repeats.
The following words and symbols are used next to the dotted decimal numbers:
Notes:
Railroad diagrams are a visual format suitable for sighted users of the information center. You read the diagram by following the arrows from left to right, using the conventions described below. A list of the exception conditions that can occur on the command is displayed at the bottom of the diagram.
This railroad diagram shows a set of alternatives - one of which you must code.
>>-+-A-+------------------------------------------------------->< +-B-+ '-C-'
This railroad diagram shows a set of alternatives - one of which you must code. You may code more than one of them, in any sequence.
.-------. V | >>---+-A-+-+--------------------------------------------------->< +-B-+ '-C-'
This railroad diagram shows a set of alternatives - one of which you may code.
>>-+---+------------------------------------------------------->< +-A-+ +-B-+ '-C-'
This railroad diagram shows a set of alternatives, any number (including none) of which you may code once, in any sequence.
.-------. V | >>---+---+-+--------------------------------------------------->< +-A-+ +-B-+ '-C-'
This railroad diagram shows a set of alternatives where A is the default.
.-A-. >>-+---+------------------------------------------------------->< '-B-'
With this railroad diagram, use the named section in place of its name.
>>-| Name |---------------------------------------------------->< Name |--A-+---+------------------------------------------------------| '-B-'
The following example shows a complete syntax diagram. This syntax diagram indicates that INQUIRE STORAGE requires you to specify either the ADDRESS option or the NUMELEMENTS option (but not both). If, and only if, you choose ADDRESS, you can specify ELEMENT, FLENGTH, both, or neither. If you choose NUMELEMENTS, you can specify ELEMENTLIST, LENGTHLIST, or TASK in any combination (including none). The possible exception conditions are NOTAUTH and TASKIDERR.
INQUIRE STORAGE >>-INQUIRE STORAGE----------------------------------------------> >--+-ADDRESS(ptr-value)--+------------------+--+--------------------+-+->< | '-ELEMENT(ptr-ref)-' '-FLENGTH(data-area)-' | '-| nlist |--| elist |--| llist |--| task |------------------------' nlist |--NUMELEMENTS(data-area)---------------------------------------| elist |--+----------------------+-------------------------------------| '-ELEMENTLIST(ptr-ref)-' llist |--+---------------------+--------------------------------------| '-LENGTHLIST(ptr-ref)-' task |--+------------------+-----------------------------------------| '-TASK(data-value)-' Conditions: NOTAUTH, TASKIDERR