OpenVMS Command Definition, Librarian, and Message Utilities Manual

Document revision date: 19 July 1999

OpenVMS Command Definition, Librarian, and Message Utilities Manual

Contents

Index

This example illustrates a command definition file (WRITER.CLD) containing DEFINE SYNTAX statements that cause syntax changes depending upon the qualifiers specified in the command string. The verb WRITER invokes a text editor (WRITER.EXE). However, you can use the SCREEN and the LINE qualifiers to invoke alternate text editors.

You can add the command definition to your process command table by issuing the following command:

$ SET COMMAND WRITER

Then you can use the WRITER command to access different text editors. For example, assume you specify the following command:

$ WRITER/LINE

Here you invoke the LINE editor instead of the default editor (WRITER). Syntax redefinition is done from left to right because parsing of the string is done from left to right. This order means that when you specify two qualifiers that invoke different syntax lists, the leftmost qualifier takes precedence (because it is parsed first).

#2

DEFINE VERB DISPLAY PARAMETER P1, LABEL=ITEM, VALUE(REQUIRED, TYPE=$FILE) QUALIFIER SAVE, SYNTAX=SAVE DEFINE SYNTAX SAVE IMAGE "WORK:[NEWMAN]:SAVE_DISPLAY" PARAMETER P1, LABEL=ITEM, VALUE(REQUIRED, TYPE=$FILE) PARAMETER P2, LABEL=NAME

#2
DEFINE VERB DISPLAY PARAMETER P1, LABEL=ITEM, VALUE(REQUIRED, TYPE=$FILE) QUALIFIER SAVE, SYNTAX=SAVE DEFINE SYNTAX SAVE IMAGE "WORK:[NEWMAN]:SAVE_DISPLAY" PARAMETER P1, LABEL=ITEM, VALUE(REQUIRED, TYPE=$FILE) PARAMETER P2, LABEL=NAME

This example shows a syntax change that defines an additional parameter. The command definition file defines the verb DISPLAY. If the DISPLAY command is used without the /SAVE qualifier, then one parameter is required. This parameter indicates the name of the file to be displayed. If the DISPLAY command is used with the /SAVE qualifier, then two parameters are required: the name of the file to be displayed and the name of the file where the display should be saved. Note that you must repeat the definition of P1 in the DEFINE SYNTAX statement.

DEFINE TYPE

Describes the keywords referenced by the VALUE(TYPE=type-name) clause. You can use the VALUE clause in a DEFINE VERB, DEFINE SYNTAX, or DEFINE TYPE statement to indicate predefined values (keywords) for command parameters, qualifiers, or keywords.

Format

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

name
The name of the DEFINE TYPE statement. This name must match the name used in the VALUE(TYPE=type-name) clause that references the DEFINE TYPE statement.
type-clause[,...]
Defines a keyword that can be used as the value of the entity that referenced the DEFINE TYPE statement. The DEFINE TYPE statement accepts the following type clause:
KEYWORD keyword-name [,keyword-clause[,...]]
This clause specifies a keyword that can be used as the value type of the entity that references the DEFINE TYPE statement. Repeat the KEYWORD value type clause for each keyword that can be used. You can specify up to 255 keywords in a DEFINE TYPE statement.
The keyword-name is the name of the keyword. The optional keyword-clause specifies additional keyword characteristics.
You can use the following keyword clauses:

DEFAULT
LABEL=label-name
NEGATABLE, NONNEGATABLE
SYNTAX=syntax-name
VALUE[(key-value-clause[,...])]

DEFAULT indicates that the keyword is present by default. For this keyword to be recognized as present by default, the parameter, qualifier, or keyword definition that references this DEFINE TYPE statement must also specify the DEFAULT clause.
LABEL=label-name defines a label for referencing the keyword at run time. By default, the keyword name is used as the label name.
NEGATABLE and NONNEGATABLE indicate whether the keyword can be negated by adding NO to the keyword name (the default is NONNEGATABLE). If you do not specify either NEGATABLE or NONNEGATABLE, NO cannot be used to negate the keyword name. Note that this differs from qualifiers, which, by default, are negatable.
SYNTAX=syntax-name specifies an alternate verb definition to be invoked when the keyword is present. The syntax name must match the name used in the corresponding DEFINE SYNTAX statement.
VALUE[(key-value-clause[,...])] specifies additional characteristics for the keyword.
VALUE accepts the following keyword value clauses:

DEFAULT=default-string Specifies a default value to be used if a value for the keyword is not explicitly given. The DEFAULT clause and the REQUIRED clause are mutually exclusive. Specify the default string as a character string that does not exceed 94 characters.
Do not use this clause to specify a default if the value is a keyword. Specify keyword defaults in the DEFINE TYPE statement and by using the DEFAULT clause with the entity that uses the keyword.

LIST Indicates that a list of values for the keyword can be given. This list must be enclosed in parentheses, and the items must be separated by commas. Note that plus signs cannot be used to separate items in a list of keyword values.

REQUIRED Indicates that the keyword must have an explicitly specified value. No prompting is performed for a required keyword value. If the keyword is specified without a value, an error is automatically issued by DCL. The REQUIRED clause and the DEFAULT clause are mutually exclusive.

TYPE=type-name Symbolically equates either a built-in value type or the name of a DEFINE TYPE statement that defines keywords that can be specified as the keyword value. The TYPE clause cannot be specified if the DEFAULT clause is specified.
See Section 1.4.2.1 for more information about built-in value types.

Examples

#1
DEFINE VERB DISPLAY PARAMETER P1, LABEL=OPTION, PROMPT="What" VALUE(REQUIRED, TYPE=DISPLAY_OPTIONS) DEFINE TYPE DISPLAY_OPTIONS KEYWORD ANIMALS, SYNTAX=DISPLAY_ANIMALS KEYWORD FLOWERS, SYNTAX=DISPLAY_FLOWERS DEFINE SYNTAX DISPLAY_ANIMALS IMAGE "USER:[JOHNSON]ANIMALS" PARAMETER P1, LABEL=OPTION, VALUE(REQUIRED) QUALIFIER SMALL QUALIFIER LARGE QUALIFIER ALL, DEFAULT DEFINE SYNTAX DISPLAY_FLOWERS IMAGE "USER:[JOHNSON]FLOWERS" PARAMETER P1, LABEL=OPTION, VALUE(REQUIRED) NOQUALIFIERS

DEFINE VERB DISPLAY 
        PARAMETER P1, LABEL=OPTION, PROMPT="What" 
                      VALUE(REQUIRED, TYPE=DISPLAY_OPTIONS) 
 
DEFINE TYPE DISPLAY_OPTIONS 
        KEYWORD ANIMALS, SYNTAX=DISPLAY_ANIMALS 
        KEYWORD FLOWERS, SYNTAX=DISPLAY_FLOWERS 
 
DEFINE SYNTAX DISPLAY_ANIMALS 
        IMAGE "USER:[JOHNSON]ANIMALS" 
        PARAMETER P1, LABEL=OPTION, VALUE(REQUIRED) 
        QUALIFIER SMALL 
        QUALIFIER LARGE 
        QUALIFIER ALL, DEFAULT 
 
DEFINE SYNTAX DISPLAY_FLOWERS 
        IMAGE "USER:[JOHNSON]FLOWERS" 
        PARAMETER P1, LABEL=OPTION, VALUE(REQUIRED) 
        NOQUALIFIERS

This example shows how to define keywords that can be specified as parameters for the verb DISPLAY. Each keyword uses its own syntax definition to invoke an image to execute the command.
After you add the command definition to your process command table, you can enter the following DISPLAY commands:
$ DISPLAY ANIMALS $ DISPLAY FLOWERS
In addition, the syntax definition DISPLAY_ANIMALS specifies three qualifiers that can be used only with the command DISPLAY ANIMALS. No qualifiers are allowed with the command DISPLAY FLOWERS.

#2
DEFINE VERB DRAW QUALIFIER COLOR, VALUE(TYPE=COLOR_NAMES) DEFINE TYPE COLOR_NAMES KEYWORD RED KEYWORD BLUE

This example shows a verb definition that uses a DEFINE TYPE statement to define keywords that can be used with a qualifier. After you add the command definition for DRAW to your process command table, you can enter the following DRAW commands:
$ DRAW/COLOR=RED $ DRAW/COLOR=BLUE

#3
DEFINE VERB RANDOM PARAMETER P1, VALUE(TYPE=THINGS), DEFAULT DEFINE TYPE THINGS KEYWORD NUMBER, DEFAULT KEYWORD LETTER

This example defines a verb, RANDOM. RANDOM accepts a parameter, which must be one of the user-defined keywords NUMBER or LETTER. If a parameter is not specified with the verb RANDOM, then the default is NUMBER.
Note that, for the keyword NUMBER to be present by default, you must use the DEFAULT clause in two places. You must specify DEFAULT when you define the parameter in the DEFINE VERB statement, and you must also specify DEFAULT when defining the NUMBER keyword in the DEFINE TYPE statement.

DEFINE VERB

Defines a new command, its parameters, its qualifiers, and the image or routine it invokes.

Format

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

verb-name
The name of the command verb. This parameter is required and must immediately follow the DEFINE VERB statement. The first four characters of the verb name must be unique.
verb-clause[,...]
Optional verb clauses that define attributes of the command string.

DEFINE VERB accepts the following verb clauses:

DISALLOW, NODISALLOWS
IMAGE
PARAMETER, NOPARAMETERS
QUALIFIER, NOQUALIFIERS
ROUTINE
SYNONYM

The following text describes these verb clauses.

DISALLOW expression

NODISALLOWS
Disallows a command string if the result of the expression is true. The NODISALLOWS clause indicates that all entities and entity combinations are allowed.
The expression specifies an entity or a combination of entities connected by operators. Each entity in the expression is tested to see if it is present (true) or absent (false) in a command string. If an entity is present by default but not explicitly provided in the command string, the entity is false.
After each entity is evaluated, the operations indicated by the operators are performed. If the result is true, the command string is disallowed. If the result is false, the command string is valid.
You can specify entities in an expression using an entity name or label, a keyword path, or a definition path. See Section 1.4.4.1 for more information about entities. You can also specify the operators AND, ANY2, NEG, NOT or OR. See Section 1.4.4.2 for more information about these operators.
IMAGE image-string
Names an image to be invoked by the command. The image-string is the file specification (a maximum of 63 characters) of the image DCL invokes when you enter the command. The default device and directory is SYS$SYSTEM: and the default file type is .EXE.
If you do not specify the IMAGE verb clause and you use SET COMMAND/REPLACE to process the command definition file, the verb name is used as the image name. At run time, DCL searches for an image whose file name is the same as the verb name and whose device and directory names and file type are SYS$SYSTEM: and .EXE.
PARAMETER param-name [,param-clause[,...]]

NOPARAMETERS
Can be used to specify up to eight parameters in the command string. The NOPARAMETERS clause indicates that no parameters are allowed.
The param-name defines the position of the parameter in the command string. The name must be in the form Pn, where n is the position of the parameter. The parameter names must be numbered consecutively from P1 to P8. The name must immediately follow the PARAMETER clause.
The param-clause specifies additional characteristics for the parameter. You can use the following parameter clauses:

DEFAULT
LABEL=label-name
PROMPT
VALUE[(param-value-clause[,...])]

DEFAULT indicates that a user-defined parameter keyword is present by default. You should use this clause only if you also use the VALUE clause to indicate that a user-defined keyword must be specified as the parameter value. See the description of the DEFINE TYPE statement for more information about defining a keyword that is present by default.
To designate a default parameter that is not a keyword, use the VALUE(DEFAULT=default-string) clause.
LABEL=label-name defines a label for referring to a parameter at run time. Specify the label name as a symbol. If you do not specify a label name, the parameter name (P1 through P8) is used as the label name.
PROMPT=prompt-string supplies a prompt string (a maximum of 31 characters) when a parameter is omitted from the command string. If you do not specify a prompt string and a required parameter is missing, DCL uses the parameter name as the prompt string.
When you define more than one parameter but only the first parameter is required, DCL prompts for the first parameter until the user either enters a value or aborts the command with Ctrl/Z. When the user enters a value for the first parameter, DCL prompts for the optional parameters. If the user presses the Return key without entering a value for an optional parameter, DCL executes the command.
VALUE[(param-value-clause[,...])] specifies additional characteristics for the parameter. When you specify parameter value clauses, enclose them in parentheses and separate items with commas.
VALUE accepts the following parameter value clauses:

CONCATENATE Indicates that a parameter can be concatenated to another parameter with a plus sign.

DEFAULT=default-string Specifies a default value to be used if the value for the parameter is not explicitly given. The DEFAULT clause and the REQUIRED clause are mutually exclusive. Specify the default string as a character string that does not exceed 94 characters.
Do not use this clause to specify a default if the value is a keyword. Specify keyword defaults in the DEFINE TYPE statement and by using the DEFAULT parameter clause.

LIST Permits you to enter a list of parameters separated by commas or plus signs.

NOCONCATENATE Indicates that the parameters cannot be concatenated.

REQUIRED Indicates that the parameter is required. All required parameters must precede optional ones. If you use the REQUIRED clause, you should also specify a prompt string. The REQUIRED clause and the DEFAULT clause are mutually exclusive.

TYPE=type-name Gives either a built-in value type or the name of a DEFINE TYPE statement that lists keywords for the parameter. Specify the value as a symbol.
See Section 1.4.2.1 for more information about built-in value types.

QUALIFIER qual-name [,qual-clause[,...]]

NOQUALIFIERS
Specifies a qualifier that can be included in the command string. You can use the QUALIFIER clause up to 255 times in a DEFINE VERB statement. The NOQUALIFIERS clause indicates that no qualifiers are allowed.
The qual-name is the name of the qualifier. The first four characters of the qualifier name must be unique. Specify the qualifier name as a symbol.
The qual-clause specifies additional qualifier characteristics. You can use the following qualifier clauses:

BATCH
DEFAULT
LABEL=label-name
NEGATABLE, NONNEGATABLE
PLACEMENT=placement-clause
SYNTAX=syntax-name
VALUE[(qual-value-clause[,...])]

BATCH indicates that the qualifier is present by default if the command is used in a batch job.
DEFAULT indicates that the qualifier is present by default in both batch and interactive jobs.
LABEL=label-name defines a label for requesting information about the qualifier at run time. Specify the label name as a symbol. If you do not specify a label name, the qualifier name is used by default.
NEGATABLE and NONNEGATABLE indicate whether the qualifier can be negated by adding NO to the qualifier name. The default is NEGATABLE; if you do not specify either NEGATABLE or NONNEGATABLE, NO can be added to the qualifier name to indicate that the qualifier is not present.
PLACEMENT=placement-clause indicates where the qualifier can appear in the command string. PLACEMENT accepts the following placement clauses:

GLOBAL Indicates that the qualifier applies to the entire command string and can be placed after the verb or after a parameter. This is the default if you do not specify the PLACEMENT clause.

LOCAL Indicates that the qualifier can appear only after a parameter value and that it applies only to that parameter.

POSITIONAL Indicates that the qualifier can appear anywhere in the command string, but the function of the qualifier depends on its position: if the qualifier is used after a parameter value, it applies only to that parameter; if it is used after the verb, it applies to all parameters.

SYNTAX=syntax-name specifies an alternate syntax definition to be invoked when the qualifier is present. The syntax name must correspond to the name used in the related DEFINE SYNTAX statement. This alternate syntax is useful for commands that invoke different images depending upon the particular qualifiers that are present. Specify the syntax name as a symbol.
VALUE[(qual-value-clause[,...])] specifies additional characteristics for the qualifier. When you specify qualifier value clauses, enclose the list in parentheses and separate items with commas. If you do not specify any qualifier value clauses, DCL converts letters in qualifier values to uppercase.
VALUE accepts the following qualifier value clauses:

DEFAULT=default-string Specifies a default value to be used if a value for the qualifier is not explicitly given. The DEFAULT clause and the REQUIRED clause are mutually exclusive. Specify the default string as a character string that does not exceed 94 characters.
Do not use this clause to specify a default if the value is a keyword. Specify keyword defaults in the DEFINE TYPE statement and by using the DEFAULT qualifier clause.

LIST Indicates a list of values separated by commas can be specified for the qualifier. This list must be enclosed in parentheses, and the items must be separated by commas. Note that plus signs cannot be used to separate items in a list of qualifier values.

REQUIRED Indicates that the qualifier must have an explicitly specified value. No prompting is performed for a required qualifier value. The REQUIRED clause and the DEFAULT clause are mutually exclusive.

TYPE=type-name Gives either a built-in value type or a DEFINE TYPE statement that defines a list of keywords that can be specified for the parameter. Specify the value type as a symbol.
See Section 1.4.2.1 for more information about built-in value types.

ROUTINE routine-name
Symbol that specifies a routine the command calls to create an object module from the command definition file.
The routine-name provides the name of a routine that is executed when CLI$DISPATCH is called.
If you do not specify a routine, no default is provided.
SYNONYM synonym-name
Defines a synonym for the verb name. Specify the synonym name as a symbol.

Examples

#1
DEFINE VERB ERASE PARAMETER,P1 VALUE(DEFAULT=DISK3:[JONES]STATS.DAT)

This definition tells the command language interpreter that ERASE is a valid verb and that it takes a parameter. If you do not enter a parameter value, the default is DISK3:[JONES]STATS.DAT.
Because no image name is specified, the verb ERASE invokes the image SYS$SYSTEM:ERASE.EXE.

#2
DEFINE VERB SCATTER IMAGE "WRKD$:[MORRISON]SCATTER" PARAMETER P1, LABEL=INFILE, PROMPT="Input_file?", VALUE(REQUIRED) PARAMETER P2, LABEL=OUTFILE, PROMPT="Output_file?", VALUE(REQUIRED) QUALIFIER SLOW, DEFAULT QUALIFIER FAST DISALLOW SLOW AND FAST

DEFINE VERB SCATTER 
         IMAGE "WRKD$:[MORRISON]SCATTER" 
         PARAMETER P1, LABEL=INFILE, PROMPT="Input_file?", VALUE(REQUIRED) 
         PARAMETER P2, LABEL=OUTFILE, PROMPT="Output_file?", VALUE(REQUIRED) 
         QUALIFIER SLOW, DEFAULT 
         QUALIFIER FAST 
         DISALLOW SLOW AND FAST

This example shows a command definition file that defines a new command called SCATTER that invokes the image WRKD$:[MORRISON] SCATTER.EXE. It has two required parameters, an input file and an output file. It has two mutually exclusive qualifiers, /SLOW and /FAST (the default is /SLOW).

IDENT

Provides identifying information for an object module created from a command definition file.

Format

IDENT ident-string

ident-string
A string containing identifying information. The string has a maximum length of 31 characters.

Example


MODULE COMMAND_TABLE IDENT "V04-001" DEFINE VERB SPIN . . .

This command definition file uses the IDENT statement to identify the object module file.

MODULE

Provides a name for an object module and for a global symbol that refers to the address of a command table within an image into which the object module is linked.

Format

MODULE module-name

module-name
The module-name is used to create a global symbol that refers to the address of the command table within the image into which the object module is to be linked.
By default, CDU uses the object file name specified with the /OBJECT command qualifier. If no object file is explicitly specified, then CDU uses the name of the first command definition file as the module name.

Example


$ CREATE TEST.CLD MODULE TEST_TABLE DEFINE VERB SEND ROUTINE SEND_ROUT PARAMETER P1 . . . DEFINE VERB SEARCH ROUTINE SEARCH_ROUT PARAMETER P1 ^Z $ SET COMMAND/OBJECT=TEST.OBJ TEST $ LINK PROG,TEST $ RUN PROG

$ CREATE TEST.CLD
MODULE TEST_TABLE
DEFINE VERB SEND
        ROUTINE SEND_ROUT
        PARAMETER P1
   .
   .
   .
DEFINE VERB SEARCH
        ROUTINE SEARCH_ROUT
        PARAMETER P1
^Z
$ SET COMMAND/OBJECT=TEST.OBJ TEST
$ LINK PROG,TEST
$ RUN PROG

TEST.CLD defines two commands (SEND and SEARCH) that call routines in PROG.EXE, a program that uses DCL to parse command strings and execute routines.
The SET COMMAND command creates a command table object module that is linked with the program object module (PROG.OBJ) to produce an image (PROG.EXE) that includes the code for the program and for the command table. TEST_TABLE refers to the address of the command table in the image.
When you run PROG.EXE, it calls DCL parsing routines to parse the command string using the command table in module TEST_TABLE. 5

Contents

Index

privacy and legal statement

6100PRO_003.HTML

DEFAULT=default-string	Specifies a default value to be used if a value for the keyword is not explicitly given. The DEFAULT clause and the REQUIRED clause are mutually exclusive. Specify the default string as a character string that does not exceed 94 characters. Do not use this clause to specify a default if the value is a keyword. Specify keyword defaults in the DEFINE TYPE statement and by using the DEFAULT clause with the entity that uses the keyword.
LIST	Indicates that a list of values for the keyword can be given. This list must be enclosed in parentheses, and the items must be separated by commas. Note that plus signs cannot be used to separate items in a list of keyword values.
REQUIRED	Indicates that the keyword must have an explicitly specified value. No prompting is performed for a required keyword value. If the keyword is specified without a value, an error is automatically issued by DCL. The REQUIRED clause and the DEFAULT clause are mutually exclusive.
TYPE=type-name	Symbolically equates either a built-in value type or the name of a DEFINE TYPE statement that defines keywords that can be specified as the keyword value. The TYPE clause cannot be specified if the DEFAULT clause is specified. See Section 1.4.2.1 for more information about built-in value types.

CONCATENATE	Indicates that a parameter can be concatenated to another parameter with a plus sign.
DEFAULT=default-string	Specifies a default value to be used if the value for the parameter is not explicitly given. The DEFAULT clause and the REQUIRED clause are mutually exclusive. Specify the default string as a character string that does not exceed 94 characters. Do not use this clause to specify a default if the value is a keyword. Specify keyword defaults in the DEFINE TYPE statement and by using the DEFAULT parameter clause.
LIST	Permits you to enter a list of parameters separated by commas or plus signs.
NOCONCATENATE	Indicates that the parameters cannot be concatenated.
REQUIRED	Indicates that the parameter is required. All required parameters must precede optional ones. If you use the REQUIRED clause, you should also specify a prompt string. The REQUIRED clause and the DEFAULT clause are mutually exclusive.
TYPE=type-name	Gives either a built-in value type or the name of a DEFINE TYPE statement that lists keywords for the parameter. Specify the value as a symbol. See Section 1.4.2.1 for more information about built-in value types.

GLOBAL	Indicates that the qualifier applies to the entire command string and can be placed after the verb or after a parameter. This is the default if you do not specify the PLACEMENT clause.
LOCAL	Indicates that the qualifier can appear only after a parameter value and that it applies only to that parameter.
POSITIONAL	Indicates that the qualifier can appear anywhere in the command string, but the function of the qualifier depends on its position: if the qualifier is used after a parameter value, it applies only to that parameter; if it is used after the verb, it applies to all parameters.