Updated: 11 December 1998 |
OpenVMS Command Definition, Librarian, and Message
Utilities Manual
Previous | Contents | Index |
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) |
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 |
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 |
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) |
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:
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.
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.
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 |
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.
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.
1.4.5 Identifying Object Modules
Use the MODULE and IDENT statements to provide identifying information if your command definition file is to create an object module. (You can create an object module from a command definition file with the command SET COMMAND/OBJECT. The object module contains a command table that you can link with your program.)
The MODULE statement assigns a symbolic name to the object module containing the command table. This is the format for the MODULE statement:
MODULE module-name |
The module-name is the symbolic name for the object module.
The IDENT statement provides additional information in a quoted string format to identify the module. Typically, this might be the date the module was created or the name of the creator. This is the format for the IDENT statement:
IDENT ident-string |
The ident-string is a quoted string having up to 31 characters.
The following sample command definition file illustrates the use of the MODULE and IDENT statements:
MODULE TABLE (1) IDENT "Updated 4/15/92" (2) DEFINE VERB SAVE (3) ROUTINE SAVE_ROUT DEFINE VERB GET (3) ROUTINE GET_ROUT |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
6100PRO_001.HTML
|