OpenVMS Command Definition, Librarian, and Message Utilities Manual

Document revision date: 19 July 1999

OpenVMS Command Definition, Librarian, and Message Utilities Manual

Contents

Index

The MODULE statement assigns the name TABLE to the command table that CDU creates when you use the command SET COMMAND/OBJECT to develop an object module for the new command.
The IDENT statement provides additional identifying information. In this example, it shows the date when the command definition file was updated.
The DEFINE VERB statements define command verbs that can be used by the main program to invoke appropriate routines.

1.5 Processing Command Definition Files

A command definition file must be translated into an executable command table before the commands in the table can be parsed and executed. To perform this translation, use the DCL command SET COMMAND to invoke the Command Definition Utility.

The command SET COMMAND has the following modes:

SET COMMAND/DELETE Deletes command definitions from a command table

SET COMMAND/OBJECT Creates an object file from a command definition file

SET COMMAND/REPLACE Adds or replaces definitions in a command table using definitions from a command definition file

The /DELETE, /OBJECT, and /REPLACE qualifiers are mutually exclusive; you can use only one SET COMMAND mode in a command string. In addition to the qualifiers that specify modes, SET COMMAND provides the following qualifiers:

/[NO]LISTING Controls whether an output listing is created

/[NO]OUTPUT Controls where the modified command table should be written

/TABLE Specifies the command table that is to be modified

See the CDU Qualifiers section for additional information.

1.5.1 Adding Command Definitions to a Command Table

Use the /REPLACE qualifier to add or replace verbs in the command table. By default, SET COMMAND uses the /REPLACE mode to add commands to your process command table and to return the modified command table to your process.

The following example shows how to add the new command SKIP to your process command table:

$ SET COMMAND SKIP

In this example, SET COMMAND adds the definitions from the command definition file SKIP.CLD to your process command table. The modified table replaces your original process command table. The /REPLACE qualifier is present by default, so you do not need to explicitly specify it in the command string.

To modify a command table other than your process table, use the /TABLE qualifier and the /OUTPUT qualifier.

1.5.2 Deleting Command Definitions

Use the /DELETE qualifier to delete a command name from a command table. By default, commands are deleted from your process command table. The following example shows how to delete the command SKIP from your process command table:

$ SET COMMAND/DELETE=SKIP

1.5.3 Creating Object Modules

Use the /OBJECT qualifier to create an object module from a command definition file. When you enter the following sample command, CDU creates an object module, NEWCOMS.OBJ, containing a command table with the verb definitions from NEWCOMS.CLD:

$ SET COMMAND/OBJECT NEWCOMS

You can then link NEWCOMS.OBJ with a program that parses commands using the new command table.

1.5.4 Creating New Command Tables

You cannot use the /OBJECT qualifier to create an object module from a command definition file that contains the IMAGE clause. However, you can create an empty command table to which you can add verbs that invoke images. The following is a step-by-step example of how to do this:

Create an empty command table by developing a command definition file that contains only a MODULE statement to define the module name and an IDENT statement. In the following example, CDU creates the empty command table, TEST_TABLE, from a command definition file named TEST_TABLE.CLD:
MODULE TEST_TABLE IDENT "New command table"
Create an object module (TEST_TABLE.OBJ) from TEST_TABLE.CLD:
$ SET COMMAND/OBJECT TEST_TABLE.CLD
Link TEST_TABLE.OBJ to create a shareable image, TEST_TABLE.EXE:
$ LINK/SHARE/NOTRACEBACK TEST_TABLE
Create a command definition file that defines verbs that invoke images. In the following example, the command definition file VERBS.CLD includes two statements that call existing images:
DEFINE VERB PASS IMAGE "DISK4:[ROSEN]PASS" DEFINE VERB THROW IMAGE "DISK4:[ROSEN]THROW" . . .
Add the new commands in VERBS.CLD to the empty command table in TEST_TABLE.EXE and write the modified table back to the file TEST_TABLE.EXE. The /TABLE and /OUTPUT qualifiers specify the input and output table files. For example:
$ SET COMMAND/TABLE=TEST_TABLE.EXE/OUTPUT=TEST_TABLE.EXE VERBS
Note that the version number of the output file is one greater than the version number of the input file. If you do not explicitly specify an output file using the /OUTPUT qualifier, CDU replaces your process command table with the modified command table.

1.6 Using Command Language Routines

A program invoked by a command that you have added to your process (or system) command table needs information about the command string that invoked it. The program can obtain this information by calling the appropriate command language routine:

CLI$PRESENT	Determines if an entity is present in the command string
CLI$GET_VALUE	Gets the value of the next entity in the command string
CLI$DCL_PARSE	Parses a command string
CLI$DISPATCH	Invokes the routine that corresponds to the verb most recently parsed

When you use CDU to add a new command, use the CLI$PRESENT and CLI$GET_VALUE routines from the program invoked by the command to get information about the command string that called the program.

When you use CDU to create and link an object module that includes a command table, use the CLI$DCL_PARSE and CLI$DISPATCH routines to parse the command string and to execute the command. Then use the CLI$PRESENT and CLI$GET_VALUE routines within the routines that execute the command.

The CDU Examples section shows two programs that call these routines. For more information about the command language routines, see the OpenVMS Utility Routines Manual.

CDU Usage Summary

The Command Definition Utility (CDU) creates, deletes, or changes command definitions in a command table. CDU uses either an existing command table, a file that contains command definitions, or a combination of these, to create a new command table. The output table can be part of an executable image or an object module.
You invoke CDU with the DCL command SET COMMAND together with the appropriate qualifiers.

Format

SET COMMAND [filespec[,...]]

Command Parameter

filespec[,...]
Specifies the name of one or more command definition files (default file type .CLD). If you specify two or more files, separate them with commas.
Wildcard characters are allowed in the file specification.

Usage Summary Use the DCL command SET COMMAND to invoke CDU. SET COMMAND has the following modes:

SET COMMAND/DELETE	Deletes command definitions from a command table
SET COMMAND/OBJECT	Creates an object module from a command definition file
SET COMMAND/REPLACE	Adds or replaces definitions in a command table using definitions from a command definition file

The /DELETE, /OBJECT, and /REPLACE qualifiers establish the various SET COMMAND modes and are mutually exclusive; that is, you can use only one of these qualifiers in a command string.

The DCL prompt reappears on your screen when CDU finishes processing the command definition file or table.

By default, SET COMMAND/DELETE and SET COMMAND/REPLACE modify your process command table and return the modified table to your process. You can modify a different input command table by using the /TABLE command qualifier.

Note

You need CMKRNL privilege to modify the system command table in SYS$LIBRARY:DCLTABLES.EXE.

You can write the command table to an output file by using the /OUTPUT command qualifier along with the /TABLE qualifier.

SET COMMAND/OBJECT creates an object module with the same name as the command definition file unless you specify an alternate file name.

CDU File Statements

This section provides complete information about the statements that can be used in a command definition file. The statements are as follows:

DEFINE SYNTAX syntax-name [verb-clause[,...]]
DEFINE TYPE type-name [type-clause[,...]]
DEFINE VERB verb-name [verb-clause[,...]]
IDENT ident-string
MODULE module-name

DEFINE SYNTAX

Defines a syntax change that replaces a command's syntax (as defined in a DEFINE VERB, DEFINE TYPE, or another DEFINE SYNTAX statement). A syntax change allows a verb to use different syntax depending on the parameters, qualifiers, and keywords present in the command string.
DEFINE statements that refer to changed syntax are called primary DEFINE statements; DEFINE SYNTAX statements that define new syntax are called secondary DEFINE statements.
When a command string is parsed, its components are scanned from left to right. The string is parsed according to the current definition until CDU encounters an entity that specifies a syntax change. The remainder of the string is parsed using the new definition. DCL does not rescan the entities that appear before the entity that specified the syntax change.
Table 1-2 shows how the DEFINE SYNTAX statement modifies the current command definition if an entity specifies a syntax change. After parsing the command string, DCL saves the command definition to determine if any entities in the command string are not allowed. Then, DCL invokes the image or routine specified by the command definition and uses the definition to process CLI$PRESENT and CLI$GET_VALUE calls.

Table 1-2 How the DEFINE SYNTAX Statement Modifies the Primary DEFINE Statement
DEFINE SYNTAX Specifies Result

An image An image overrides the image in the primary DEFINE statement. DCL invokes the new image after it parses the command string.

A routine A routine overrides the routine in the primary DEFINE statement. DCL invokes the new routine when CLI$DISPATCH is called.

One or more disallows One or more disallows are used during command parsing and they override disallows in the primary DEFINE statement. This applies to all entities in the command that have not been invalidated by the new syntax definition.

No disallows Disallows from the primary DEFINE statement are used during command parsing.

The NODISALLOWS clause No disallows are permitted, regardless of definitions in the primary DEFINE statement.

One or more parameters Parameters that were already parsed are not reparsed according to the new definitions. However, parameters to the right of the entity that specified the new syntax are parsed according to the new definitions. DCL uses the new parameter definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.
Note that, in the DEFINE SYNTAX statement, P1 refers to the first parameter in the command string. To define additional parameters, use the PARAMETER clause in a secondary DEFINE statement to first enter the definitions for the original parameters exactly as they appear in the primary DEFINE statement. Then, enter the definitions for the additional parameters.

No parameters Parameter definitions from the primary DEFINE statement are used when DCL parses the remainder of the command string. DCL also uses these parameter definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.

The NOPARAMETERS clause Parameters previously parsed are not reparsed to the new definitions. However, no parameters are allowed when DCL parses entities to the right of the entity that specifies the new syntax. DCL uses the NOPARAMETERS definition when processing CLI$PRESENT and CLI$GET_VALUE calls.

One or more qualifiers The qualifiers previously parsed and the qualifiers that specify the syntax change are not affected. Qualifiers that appear in the command string after the entity that specifies the new syntax are parsed according to the new definition. DCL uses the new qualifier definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.
When DCL parses a command string that contains qualifiers that are ignored because of a syntax change, DCL issues a warning message.

No qualifiers Qualifier definitions from the primary DEFINE statement are used when DCL parses the remainder of the command string. DCL also uses these qualifier definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.

The NOQUALIFIERS clause Qualifiers previously parsed are ignored. No qualifiers are allowed when DCL parses entities to the right of the entity that specifies the new syntax. DCL uses the NOQUALIFIERS definition when processing CLI$PRESENT and CLI$GET_VALUE calls.

**Table 1-2 How the DEFINE SYNTAX Statement Modifies the Primary DEFINE Statement**
DEFINE SYNTAX Specifies	Result
An image	An image overrides the image in the primary DEFINE statement. DCL invokes the new image after it parses the command string.
A routine	A routine overrides the routine in the primary DEFINE statement. DCL invokes the new routine when CLI$DISPATCH is called.
One or more disallows	One or more disallows are used during command parsing and they override disallows in the primary DEFINE statement. This applies to all entities in the command that have not been invalidated by the new syntax definition.
No disallows	Disallows from the primary DEFINE statement are used during command parsing.
The NODISALLOWS clause	No disallows are permitted, regardless of definitions in the primary DEFINE statement.
One or more parameters	Parameters that were already parsed are not reparsed according to the new definitions. However, parameters to the right of the entity that specified the new syntax are parsed according to the new definitions. DCL uses the new parameter definitions when processing CLI$PRESENT and CLI$GET_VALUE calls. Note that, in the DEFINE SYNTAX statement, P1 refers to the first parameter in the command string. To define additional parameters, use the PARAMETER clause in a secondary DEFINE statement to first enter the definitions for the original parameters exactly as they appear in the primary DEFINE statement. Then, enter the definitions for the additional parameters.
No parameters	Parameter definitions from the primary DEFINE statement are used when DCL parses the remainder of the command string. DCL also uses these parameter definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.
The NOPARAMETERS clause	Parameters previously parsed are not reparsed to the new definitions. However, no parameters are allowed when DCL parses entities to the right of the entity that specifies the new syntax. DCL uses the NOPARAMETERS definition when processing CLI$PRESENT and CLI$GET_VALUE calls.
One or more qualifiers	The qualifiers previously parsed and the qualifiers that specify the syntax change are not affected. Qualifiers that appear in the command string after the entity that specifies the new syntax are parsed according to the new definition. DCL uses the new qualifier definitions when processing CLI$PRESENT and CLI$GET_VALUE calls. When DCL parses a command string that contains qualifiers that are ignored because of a syntax change, DCL issues a warning message.
No qualifiers	Qualifier definitions from the primary DEFINE statement are used when DCL parses the remainder of the command string. DCL also uses these qualifier definitions when processing CLI$PRESENT and CLI$GET_VALUE calls.
The NOQUALIFIERS clause	Qualifiers previously parsed are ignored. No qualifiers are allowed when DCL parses entities to the right of the entity that specifies the new syntax. DCL uses the NOQUALIFIERS definition when processing CLI$PRESENT and CLI$GET_VALUE calls.

Format

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

syntax-name
The name of the syntax change. The name is required and must immediately follow the DEFINE SYNTAX statement.
verb-clause[,...]
Optional verb clauses that define attributes of the command string.
DEFINE SYNTAX accepts the following verb clauses:

DISALLOW, NODISALLOWS
IMAGE
PARAMETER, NOPARAMETERS
QUALIFIER, NOQUALIFIERS
ROUTINE

The following text describes these clauses. Note that, if the syntax list contains only an IMAGE or ROUTINE clause, it affects only the specified clause in the primary DEFINE statement. If the list contains any qualifiers or the NOQUALIFIERS keyword, all qualifiers in the primary DEFINE statement are replaced by the qualifiers in the syntax list. If the syntax list contains neither qualifiers nor the NOQUALIFIERS keyword, the qualifiers in the primary DEFINE statement apply. Similarly, if the syntax list contains any parameter or the NOPARAMETERS keyword, all parameters in the primary DEFINE statement are replaced.

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, respectively.
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=prompt-string
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 on 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 a 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 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 defines a list of keywords that can be specified for the parameter. Specify the value type name 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 SYNTAX statement. The NOQUALIFIERS clause indicates that no qualifiers are allowed.
The qual-name is the name of the qualifier. Specify the qualifier name as a symbol. The first four characters of the qualifier name must be unique.
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 as the label name.
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 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 a DEFINE SYNTAX statement. 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 that 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 the name of a DEFINE TYPE statement that defines a list of keywords that can be specified for the parameter. Specify the value type name as a symbol.
See Section 1.4.2.1 for more information about built-in value types.

ROUTINE routine-name
Names a routine in syntax. Use the ROUTINE clause to create an object module from the command definition file.
The routine-name provides the name of the routine to be executed when CLI$DISPATCH is called. Specify the routine name as a symbol.
If you do not specify a routine, the routine from the primary DEFINE statement is invoked, if applicable.

Examples

#1
DEFINE VERB WRITER IMAGE "WORK:[JONES]WRITER" QUALIFIER LINE, SYNTAX=LINE QUALIFIER SCREEN, SYNTAX=SCREEN DEFINE SYNTAX LINE IMAGE "WORK:[JONES]LINE" QUALIFIER NUM DEFINE SYNTAX SCREEN IMAGE "WORK:[JONES]SCREEN" QUALIFIER AUDIT

DEFINE VERB WRITER 
        IMAGE "WORK:[JONES]WRITER" 
        QUALIFIER LINE, SYNTAX=LINE 
        QUALIFIER SCREEN, SYNTAX=SCREEN 
 
DEFINE SYNTAX LINE 
        IMAGE "WORK:[JONES]LINE" 
        QUALIFIER NUM 
 
DEFINE SYNTAX SCREEN 
        IMAGE "WORK:[JONES]SCREEN" 
        QUALIFIER AUDIT

Previous Next Contents Index

privacy and legal statement

6100PRO_002.HTML

/[NO]LISTING	Controls whether an output listing is created
/[NO]OUTPUT	Controls where the modified command table should be written
/TABLE	Specifies the command table that is to be modified

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 a 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 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 defines a list of keywords that can be specified for the parameter. Specify the value type name 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 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.