HP OpenVMS systems documentation

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.

This is the format for the DEFINE SYNTAX statement:

DEFINE SYNTAX syntax-name [verb-clause,[,...]]

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.

The following example shows how a syntax change is used to specify an alternate command syntax when the /LINE qualifier is specified:

DEFINE VERB ERASE IMAGE "DISK1:[MYDIR]ERASE" QUALIFIER SCREEN QUALIFIER LINE, SYNTAX=LINE (1) DEFINE SYNTAX LINE (2) IMAGE "DISK1:[MYDIR]LINE" QUALIFIER NUMBER, VALUE(REQUIRED)

1. The DEFINE VERB statement defines the verb ERASE. This verb accepts two qualifiers, /SCREEN and /LINE. The qualifier /LINE uses an alternate syntax, specified with the SYNTAX=LINE clause. If you enter the command ERASE/LINE, the definitions in the DEFINE SYNTAX LINE statement override the definitions in the DEFINE VERB ERASE statement. However, if you enter the command ERASE/SCREEN or if you do not specify any qualifiers, the definitions in the DEFINE VERB ERASE statement apply.
2. The DEFINE SYNTAX statement defines an alternate syntax called LINE. If you enter the command ERASE with the /LINE qualifier, the image DISK1:[MYDIR]LINE.EXE is invoked. The new syntax allows the qualifier /NUMBER, which requires a value.

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 1.4.2.1 lists the built-in value types; Section 1.4.2.2 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.

1.4.2.1 Built-In Value Types

The Command Definition Language provides the following built-in value types:

$ACL	The value must be an access control list.
$DATETIME	The value must be an absolute time or a combination time. DCL converts truncated time values, combination time values, and keywords for time values (such as TODAY) to absolute time format. DCL fills blank date fields from the current system date and fills omitted time fields with zeros.
$DELTATIME	The value must be a delta time. DCL fills missing fields with zeros.
$EXPRESSION	The value must be a DCL-style expression. DCL evaluates the expression and provides the results.
$FILE	The value must be a valid file specification.
$NUMBER	The value must be an integer represented by either decimal, octal, or hexadecimal numbers.
$PARENTHESIZED_VALUE	The value must be enclosed in parentheses. Note that DCL does not remove the parentheses.
$QUOTED_STRING	The value must be a string enclosed in quotation marks. Note that DCL does not remove the quotation marks.
$REST_OF_LINE	DCL treats the rest of the line literally as the specified value, ignoring spaces or punctuation marks. DCL does not remove quotation marks when processing the string.

The following example shows a parameter that must be specified as a file specification:

DEFINE VERB PLAY IMAGE "DISK1:[MYDIR]PLAY" PARAMETER P1, VALUE(TYPE=$FILE)

1.4.2.2 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.

To indicate that a command entity requires a keyword, use a VALUE clause of the following form in a definition statement:

DEFINE SYNTAX VALUE(TYPE=type-name)

The type-name points to the DEFINE TYPE statement that specifies the allowable keywords for the entity.

This is the format for the DEFINE TYPE statement:

DEFINE TYPE type-name [type-clause[,...]]

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:

KEYWORD FAST, DEFAULT KEYWORD SLOW

The following example illustrates the use of a DEFINE TYPE statement in conjunction with a DEFINE VERB statement:

DEFINE VERB SKIM (1) IMAGE "USER:[TOOLS]SKIM" QUALIFIER SPEED, VALUE(TYPE=SPEED_KEYWORDS) (2) DEFINE TYPE SPEED_KEYWORDS (3) KEYWORD FAST, DEFAULT KEYWORD SLOW

1. The DEFINE VERB statement defines a verb, SKIM, which invokes the image [TOOLS]SKIM.EXE and accepts the qualifier /SPEED.
2. The VALUE clause indicates that the /SPEED qualifier accepts a list of keywords as defined by the DEFINE TYPE SPEED_KEYWORDS statement.
3. The DEFINE TYPE statement lists the keywords that can be used with the /SPEED qualifier; you can specify SKIM/SPEED=FAST or SKIM/SPEED=SLOW. If you specify the /SPEED qualifier without a value, the default is FAST.

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 format for the DEFINE VERB statement is as follows:

DEFINE VERB verb-name [verb-clause[,...]]

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:

DISALLOW	Controls the use of an entity or a combination of entities.
NODISALLOWS	Permits all entities and entity combinations.
IMAGE	Specifies an image to be invoked by the verb.
PARAMETER	Defines a command parameter.
NOPARAMETERS	Disallows parameters.
QUALIFIER	Defines a command qualifier.
NOQUALIFIERS	Disallows qualifiers.
ROUTINE	Specifies a routine to be invoked by the verb.
SYNONYM	Specifies a verb synonym.

The following example illustrates a DEFINE VERB statement:

DEFINE VERB SEARCH (1) IMAGE "SEARCH" (2) PARAMETER P1, LABEL=SOURCE, PROMPT="File", VALUE(REQUIRED) (3)

1. The DEFINE VERB statement names the verb SEARCH.
2. The IMAGE verb clause identifies the image to be invoked at run time.
3. The PARAMETER verb clause defines the first parameter to appear after the verb in the command string. LABEL, PROMPT, and VALUE are parameter clauses that further define the parameter. LABEL defines a name that the image uses to refer to the parameter. PROMPT indicates the prompt string to be issued if you do not specify the parameter in the command string. VALUE uses the REQUIRED clause to indicate that the parameter must be present in the command string.

When you define a verb, you can use the DISALLOW verb clause to selectively disallow the use of one or more entities with the verb.

The DISALLOW verb clause has the following format:

DISALLOW expression

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:

DEFINE VERB SPORTS IMAGE "DISK3:[WILSON]SPORTS" QUALIFIER TENNIS QUALIFIER BOWLING QUALIFIER BASEBALL DISALLOW ANY2(TENNIS, BOWLING, BASEBALL)

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:

DEFINE VERB TEST IMAGE "DISK3:[WORK]TEST" PARAMETER P1 PARAMETER P2 QUALIFIER QUAL1 QUALIFIER QUAL2,PLACEMENT=LOCAL QUALIFIER QUAL3,PLACEMENT=LOCAL DISALLOW P1 AND QUAL1 DISALLOW QUAL2 AND QUAL3

Thus, the following two commands would be disallowed:

TEST P1 P2/QUAL1 TEST P1/QUAL2 P2/QUAL3

The global search context applied to local qualifiers is used only with DISALLOW processing, not with normal command parsing.

1.4.4.1 Specifying Expression Entities

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:

• A parameter, qualifier, or keyword name or label
• A keyword path
• A definition path

Names and Labels

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:

DEFINE VERB COLOR IMAGE "WORK:[JUDY]COLOR" QUALIFIER RED QUALIFIER BLUE QUALIFIER GREEN, VALUE(TYPE=GREEN_AMOUNT) DISALLOW RED AND ALL DISALLOW BLUE AND ALL DEFINE TYPE GREEN_AMOUNT KEYWORD ALL KEYWORD HALF

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:

$ COLOR/RED/GREEN=ALL$ COLOR/BLUE/GREEN=ALL

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.

Keyword Paths

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.)

$ NEWCOMMAND/QUAL1=(START=5,END=10)/QUAL2=(START=2,END=5)

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:

DISALLOW QUAL1.START AND QUAL3

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:

DEFINE VERB COLOR IMAGE "WORK:[JUDY]COLOR" QUALIFIER RED, VALUE(TYPE=RED_AMOUNT) QUALIFIER GREEN, VALUE(TYPE=GREEN_AMOUNT) DISALLOW RED AND GREEN.ALL DISALLOW GREEN AND RED.ALL DEFINE TYPE RED_AMOUNT KEYWORD ALL KEYWORD MIXED DEFINE TYPE GREEN_AMOUNT KEYWORD ALL KEYWORD HALF

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.

Definition Paths

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:

<definition-name>entity-spec

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.

For example:

DISALLOW <SKIP>FIRST

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:

DISALLOW <FILE>BILLS.ELECT AND GAS

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.

DEFINE VERB FILE QUALIFIER BILLS, SYNTAX=BILL_TYPES QUALIFIER RECEIPTS DEFINE VERB READ QUALIFIER NOTES DEFINE SYNTAX BILL_TYPES DISALLOW <READ>NOTES

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 SYNTAX statements.

1.4.4.2 Operators

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:

DISALLOW SINCE AND BEFORE

The logical operator AND stipulates that the command is invalid only when both qualifiers are present. When an expression contains logical operators, the operators are evaluated after the related command entities are determined to be present (logical true) or absent (logical false). If the result of the expression is true (that is, if both qualifiers are present), the command is disallowed. Conversely, if the result is false (one or none of the qualifiers is present), the command is accepted.

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.

Table 1-1 Summary of CDU Operators

Operator	Precedence	Meaning
ANY2	1	True if any two or more of the entities listed are present
NEG	1	True if the negated form of the entity is present
NOT	1	True if the entity is not present or if an entity is present by default
AND	2	True if both entities are present
OR	3	True if either entity is present

The following example shows how to use the AND operator:

DISALLOW TERMINAL AND PRINTER

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:

DISALLOW FAST AND (SLOW OR STILL)

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.