HP OpenVMS Systems Documentation
OpenVMS Command Definition, Librarian, and Message Utilities Manual
1.4.1 Defining Syntax
The DEFINE SYNTAX statement allows a command verb to use alternative syntax depending on the parameters, qualifiers, and keywords that are present in the command string. It redefines the syntax for a command verb previously defined by a DEFINE VERB or DEFINE TYPE statement, or it can be used to redefine the syntax for a command verb redefined by a previous DEFINE SYNTAX statement.
To define a syntax change, you must provide two DEFINE statements: a primary DEFINE statement and a secondary DEFINE statement. The primary DEFINE statement defines the affected command verb and it must include a SYNTAX=syntax-name verb clause to point to the secondary DEFINE statement. The secondary DEFINE statement defines the alternate syntax.
For example, you can write a command definition that uses a different syntax for a command verb when a particular qualifier is explicitly present, that is, not by default. When you include the specified qualifier in the command string, the syntax defined in the secondary DEFINE statement applies to the command verb described by the primary DEFINE statement.
The syntax-name verb clause is the name of the alternate syntax definition. The verb clause specifies additional information about the syntax. You can use the same verb clauses in a DEFINE SYNTAX statement as are allowed in a DEFINE VERB statement, with one exception: you cannot use the SYNONYM verb clause with DEFINE SYNTAX.
1.4.2 Defining Values
To define values for parameters, qualifiers, or keywords, use the VALUE clause. When you use the VALUE clause, you can further define the value type with the TYPE clause.
With the TYPE clause, you can specify that a value type must be a built-in type (for example, a file specification), or you can specify that a value must be a user-defined keyword. Section 188.8.131.52 lists the built-in value types; Section 184.108.40.206 describes how to specify a user-defined keyword.
When you use the VALUE clause and do not define a value type, DCL
processes the value in the following way. If the value is not enclosed
in quotation marks, then DCL converts letters to uppercase and
compresses multiple spaces and tabs to a single space. If the value is
enclosed in quotation marks, then DCL removes the quotation marks,
preserves the case of letters, and does not compress tabs and spaces.
To include quotation marks within a quoted string, use two contiguous
quotation marks ("") in the place you want the quotation
marks to appear.
The Command Definition Language provides the following built-in value types:
The following example shows a parameter that must be specified as a file specification:
220.127.116.11 User-Defined Keywords
The DEFINE TYPE statement defines keywords that are acceptable for use as values for various command entities, including parameters, qualifiers, or other keywords.
The type-name points to the DEFINE TYPE statement that specifies the allowable keywords for the entity.
The type-name is the name of the keyword list, and the type-clause lists the acceptable keywords. Each type clause begins with the keyword KEYWORD, followed by one or more keywords that can be used with the parameter, qualifier, or keyword that references the keyword list. The next example includes two type-clauses in the DEFINE TYPE statement:
1.4.3 Defining Command Verbs
The DEFINE VERB statement defines a new command verb and specifies its characteristics. You can define any number of verbs in a single command definition file.
The verb name is the name of the command. A verb clause specifies additional information about the verb. Verb clauses can appear in any order in the command definition file. Verb clauses are optional.
You can specify the following verb clauses:
1.4.4 Disallowing Entity Combinations
The DISALLOW verb clause has the following format:
The expression in the clause specifies the disallowed entities and you can use any of the various logical operators (exclusive-OR, AND, OR, and so forth) to define them. When a command string is parsed, each entity in the expression is tested to determine if the entity is present (true) or absent (false). If an entity is present by default but is not explicitly present in the command string, the entity is evaluated as absent (false).
After each entity is evaluated, the logical operations are performed. If the result is true, the command string is disallowed. If the result is false, the command string is valid.
For example, a command definition might contain a DEFINE VERB statement that defines the verb SPORTS with three qualifiers: /TENNIS, /BOWLING, and /BASEBALL. However, you might want to make the qualifiers mutually exclusive. The following example shows how to use the DISALLOW verb clause to put this restriction into the command definition file:
The DISALLOW verb clause indicates that a command string is invalid if it contains more than one of the qualifiers /TENNIS, /BOWLING, or /BASEBALL.
Note that, when you specify any entity in a DISALLOW expression, the search context is the entire command string. Therefore, local qualifiers are treated as if they were global. The following example shows the global context of the search:
Thus, the following two commands would be disallowed:
The global search context applied to local qualifiers is used only with
DISALLOW processing, not with normal command parsing.
When you specify entities in an expression, you need to uniquely identify the entities that are disallowed. You can specify an entity using one of the following:
You can refer to a parameter or qualifier using its name or label if the entity is defined in the current definition. To refer to a keyword, you can use its name or label if the keyword is in a keyword path that starts from the current definition, and if the keyword name or label is unique. (See the next subsection for more information about keyword paths.)
If the LABEL=label-name keyword is used to assign a label to an entity, use the label name to refer to the entity. Otherwise, use the entity name.
The following example disallows combinations of entities:
In this example, you can use the qualifier names RED and BLUE in the DISALLOW verb clause because both names are used in the current definition. You can use the keyword ALL because it is in a keyword path that starts within the current definition (the TYPE=GREEN_AMOUNT qualifier clause starts the path) and the keyword name is unique.
The DISALLOW clauses indicate that the following command strings are not valid:
To refer to a parameter or qualifier in another definition or to refer to a keyword whose path begins in another DEFINE statement, you must use a definition path.
A keyword path provides a way to uniquely identify a keyword. You can refer to a keyword using a keyword path if the keyword is in a path that starts from the current definition and if the keyword name or label is not unique. You can also use a keyword path if the same keyword can be used with more than one parameter or qualifier.
A keyword path contains a list of entity names or labels that are separated by periods. The first name in a keyword path is the name (or label) of the first entity that references the keyword's value type definition. A keyword path can contain up to eight names (the first parameter or qualifier definition, plus seven DEFINE TYPE keyword definitions).
If a keyword is assigned a label name, use the label name in the keyword path. Otherwise, use the keyword name. You can omit names that are not needed to resolve a keyword reference from the beginning of a keyword path. However, you must include enough names to uniquely reference the keyword.
The following command string illustrates a situation that requires keyword paths to uniquely identify keywords. In this command string, you can use the same keywords with more than one qualifier. (In the command definition file, two qualifiers refer to the same DEFINE TYPE statement.)
The keyword path QUAL1.START identifies the keyword START when it is used with QUAL1; the keyword path QUAL2.START identifies the keyword START when it is used with QUAL2. The name START is an ambiguous reference if used alone.
To disallow use of the keyword QUAL1.START when a third qualifier (QUAL3) is present, use the following line in the command definition file:
Although you cannot use QUAL1.START when QUAL3 is present, you can still use QUAL2.START with QUAL3.
The following example contains a keyword (ALL) that appears in two DEFINE TYPE statements:
In this example, you must use the keyword path RED.ALL to refer to the ALL keyword when it is used in the value type definition RED_AMOUNT; you must use the keyword path GREEN.ALL to refer to the ALL keyword when it is used in the value type definition GREEN_AMOUNT.
A definition path links a syntax definition to an entity that is defined in another DEFINE statement. For example, a definition path is needed when a syntax definition provides new disallow clauses for parameters or qualifiers that are defined in a primary definition.
A definition path has the following format:
The definition name is the name of the DEFINE statement where the entity is defined or the keyword path begins. The entity specification can be an entity name, a label, or a keyword path. The angle brackets are required.
This clause disallows a command string if the entity FIRST (specified in the DEFINE VERB statement for the command verb SKIP) is present.
The next example uses a keyword path and a definition path:
This clause disallows a command string if the entity described by the keyword path BILLS.ELECT (which originates in the DEFINE VERB statement for the command verb FILE) is present.
CDU does not check a definition path to determine whether the path refers to an entity that is valid in a given context. If you use a definition path to specify an entity that is not valid in a particular context, results are unpredictable. For example, if you try to disallow the qualifier NOTES in the DEFINE SYNTAX statement, the entity NOTES would not be recognized as valid because the path to BILL_TYPES is not established in the DEFINE VERB statement for the command verb READ.
Although the DISALLOW clause correctly identifies an entity in the command definition file, this entity is not valid in the DEFINE SYNTAX statement. However, the clause DISALLOW <FILE>RECEIPTS is valid in the DEFINE SYNTAX statement. The DEFINE SYNTAX statement inherits the qualifier RECEIPTS from the primary DEFINE statement (FILE) because no qualifiers are specified.
See the description of the DEFINE SYNTAX statement in the CDU File Statements
section for more information about how entities are inherited by DEFINE
A command definition can include one or more expressions of the relationship between an action verb and one or more objects of the verb (entities) that can be qualifiers, parameters, or keywords in various combinations. For example, the following expression states that the command is disallowed if it contains both of the previously defined qualifiers SINCE and BEFORE:
Table 1-1 shows the operators you can use in command definition expressions and the order in which CDU evaluates these operators. The highest precedence value is 1. When an expression contains two or more operators of equal precedence, CDU evaluates the leftmost operator first.
The following example shows how to use the AND operator:
This statement disallows the command string if both entities (TERMINAL and PRINTER) are present.
You can use parentheses to override the order in which operations are evaluated; operations within parentheses are evaluated first. For example:
The parentheses force the OR operator to be evaluated before the AND operator. Therefore, if the result of SLOW OR STILL is true, and if FAST is present in the command string, then the string is disallowed.