OpenVMS Command Definition, Librarian, and Message Utilities Manual

Updated: 11 December 1998

Order Number: AA--QSBDB--TE

November 1996

This manual describes how to use the Command Definition Utility to modify the DIGITAL Command Language (DCL), how to use the Librarian utility to create and maintain OpenVMS libraries, and how to use the Message utility to supplement OpenVMS system messages with messages of your own.

Revision/Update Information: This manual supersedes the OpenVMS Command Definition, Librarian, and Message Utilities Manual, Version 7.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: Bookreader, DECdirect, DECwindows, Digital, OpenVMS, OpenVMS Cluster, VAX, VAX DOCUMENT, VAXcluster, VMS, and the DIGITAL logo.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6100

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

Intended Audience

This manual is intended for programmers and general users of the OpenVMS operating system.

Document Structure

This manual is divided into three parts.

Chapter 1 describes the Command Definition Utility (CDU) and consists of the following sections:

Description---Provides a full description of CDU.
Usage Summary---Outlines the following information:
- Invoking the utility
- Exiting from the utility
- Directing output
- Restrictions or privileges required
File Statements---Describes the statements used in building command definition files, including statement formats, parameters, and examples.
Qualifiers---Describes qualifiers, including format, parameters, and examples.
Examples---Provides additional CDU examples.

Chapter 2 describes the Librarian utility (LIBRARIAN) and consists of the following sections:

Description---Provides a full description of LIBRARIAN.
Usage Summary---Outlines the following information:
- Invoking the utility
- Exiting from the utility
- Directing output
Qualifiers---Describes qualifiers, including format, parameters, and examples.

Chapter 3 describes the Message utility (MESSAGE) and consists of the following sections:

Description---Provides a full description of MESSAGE.
Usage Summary---Outlines the following information:
- Invoking the utility
- Exiting from the utility
Qualifiers---Describes qualifiers, including format, parameters, and examples.
Commands---Describes source file statements, including format, parameters, and examples.
Examples---Provides additional examples for using message files and pointer files.

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x or
GOLD x A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

... Horizontal ellipsis points in examples indicate one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace type Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Command Definition Utility

CDU Description

The Command Definition Utility (CDU) creates, deletes, or changes command definitions in a command table. Command tables are data structures created by CDU and used by the command language interpreter (CLI) to parse and evaluate DIGITAL Command Language (DCL) commands.

There are two types of command tables: system command tables used to parse system commands and process command tables used to parse process-specific commands. CDU creates command tables from command definition files, from existing command tables, or from a combination of these sources. The new table can be either executable code or an object module.

The following sections describe:

How DCL processes commands
How to write command definitions
How to modify command tables
How to process command definitions
How to use command language routines in programs

1.1 Command Processing

To write command definitions and modify command tables, you must understand how the DCL command interpreter processes commands. The process begins when DCL prompts you for a command and you enter an appropriate command string. Then DCL processes the command string from left to right using definitions in your process command table. Your process command table contains a list of valid commands and their attributes.

To parse a command string, DCL calls the CLI$DCL_PARSE routine to check each entity in the command string. If each entity is valid, DCL sets up an internal representation of the command string. Then DCL uses the CLI$DISPATCH routine to invoke the image or routine that executes the command. If the command string is not valid, DCL issues an error message.

The image or routine that executes a command must call the CLI$PRESENT and CLI$GET_VALUE routines to get information about the entities that were present in the command string. The image or routine uses this information to determine how to execute the command.

1.1.1 Command String Components

A command string can contain a verb that specifies the command to be executed, a parameter that specifies the verb object, and a qualifier that describes or modifies the action taken by the verb.

The DCL command definitions describe the allowable parameter values for each command. The command definitions also indicate whether or not qualifiers can take values and the value types that can be specified. Examples of qualifier values include file specifications, integer values, keywords, and character strings. Some commands (SET and SHOW) accept keywords as parameters. A keyword is a predefined string that can be used as a value for a parameter, qualifier, or another keyword.

The following example illustrates the components of a DCL command string:

$ DIFFERENCES/MODE=ASCII MYFILE.DAT YOURFILE.DAT

DIFFERENCES is the verb and /MODE is a qualifier that has as its value the keyword ASCII. MYFILE.DAT and YOURFILE.DAT are file specifications that function as the command parameters.

The next example shows a command that uses a keyword as a parameter value:

$ SHOW DEFAULT

Here, SHOW is the verb and DEFAULT is a keyword used as a parameter.

1.1.2 System and Process Command Tables

When you log in, the system command table in SYS$LIBRARY:DCLTABLES.EXE is copied to your process and DCL uses this process command table to parse command strings. Changing your process command table does not affect SYS$LIBRARY:DCLTABLES.EXE. To change the DCL tables, you need the CMKRNL privilege.

The system command table is created from source files called command definition files. A command definition file contains statements that name and describe verbs. Digital maintains the command definition files for DCL; they are not shipped with your system.

1.2 Using CDU

To use CDU:

Determine which table you want to create or modify. In general, you modify your process command table or the DCL table in SYS$LIBRARY, or you create an object module for a new table.
Choose a name and syntax for the command you define. Use a text editor to create a command definition file that defines the command.
Use the DCL command SET COMMAND to add your command definition to the appropriate command table. You can modify your process command table or a specified command table file. You can also create an object module from your command definition file.
Write the code for the image or routine that is invoked by the command you are adding to the command table.

Note that the foreign command facility is an alternate way to define command verbs. The foreign command allows you to pass information about a command string to an image. However, if you use the foreign command facility, your program must parse the command string; DCL does not parse the command string for you. For information about how to define a foreign command, see the OpenVMS User's Manual.

1.3 Choosing a Table

The type of table you are modifying or creating affects the way that you write a command definition, process this definition, and write the code that executes your command.

The most common tables that you modify or create include your process command table, the DCL table in SYS$LIBRARY, and new tables that allow your programs to process commands.

1.3.1 Modifying Your Process Command Table

To add a command to your process command table, define the new command in a command definition file, specifying the name of an image for the command to invoke. Then use SET COMMAND to add the new command to your process command table and to copy the new table back to your process. For example, the following command adds a command in NEWCOMMAND.CLD to your process command table:

$ SET COMMAND NEWCOMMAND

Now you can enter the new command after the DCL prompt. DCL will parse the command and then invoke the image that executes the command. Note that, when you write the source code for the new command, you must use the command language routines CLI$PRESENT and CLI$GET_VALUE to obtain information about the command string.

The first example in the CDU Examples section shows how to add a new command to your process command table and how to write the program that executes the new command.

To make the command in NEWCOMMAND.CLD available to you each time you log in, include the SET COMMAND command in your LOGIN.COM file.

1.3.2 Adding a System Command

To add a command to the DCL command table in SYS$LIBRARY, define the command in a command definition file, specifying the name of an image for the command to invoke. Then use SET COMMAND to add the new definition to the DCL command table and copy the new table back to SYS$LIBRARY. (You must have the CMKRNL privilege to change the DCL command table.) For example:

$ SET COMMAND/TABLE=SYS$LIBRARY:DCLTABLES - _$ /OUTPUT=SYS$LIBRARY:DCLTABLES NEWCOMMAND

To make the new command available to other users, use the Install utility.

1.3.3 Creating an Object Module

To create an object module for a new command table, define the commands in a command definition file, specifying the name of a routine in a program that executes the command. Then use SET COMMAND with the /OBJECT qualifier to create an object module from the command definition file. For example:

$ SET COMMAND/OBJECT NEWCOMMAND

Now link this object module with the program that uses the table. Note that, when you link a command table with your program, the program must perform the functions of a command interpreter. That is, the program must obtain the command string and call the parsing routine CLI$DCL_PARSE to verify and create an internal representation of it. The program must also call CLI$DISPATCH to invoke the appropriate routine. Each command routine must use the DCL interface routines CLI$PRESENT and CLI$GET_VALUE to get information about the command string that invoked the routine.

The second example in the CDU Examples section shows how to write and process command definitions for an object module and how to write a program that parses commands and invokes routines.

1.4 Writing a Command Definition File

A command definition file contains information that defines a command and its parameters, qualifiers, and keywords. In addition, the command definition file provides information about the image or routine that is invoked after the command string is successfully parsed.

Use a text editor to create a command definition file that contains the statements you need to describe your new command; you can use clauses to specify additional information for statements. The default file type for a command definition file is .CLD.

Use exclamation points to delimit comments. An exclamation point causes all characters that follow it on a line to be treated as comments.

Any statement and its clauses can be coded using several lines. No continuation character is necessary. (However, you cannot split names across two lines.) If you place a statement on one line, you can separate clauses in the statement with either commas or spaces.

You cannot abbreviate statement or clause names in the command definition language. All names (for example, DEFINE SYNTAX, PARAMETER, and so forth) must be spelled out completely.

Most statements and clauses accept user-supplied information such as verb names, qualifier names, image names, and so on. You can specify this information as a symbol or as a string.

If the statement requires that a term be specified as a string, enclose the term in quotation marks. A string can contain any alphanumeric or special characters. To include quotation marks within a string, use two quotation marks (""). For example, PARAMETER P1, LABEL=PORT, PROMPT="Enter ""one"" value" produces the following:

Enter "one" value

Note

To maintain compatibility with earlier releases, CDU accepts character strings that are not enclosed in quotation marks. However, Digital recommends that you surround character strings in quotation marks. If you do not enclose a string in quotation marks, all alphabetic characters are converted to uppercase characters (capital letters).

If a statement requires that a term be specified as a symbol, do not enclose the term in quotation marks. A symbol name must start with a letter or a dollar sign. It can contain from 1 to 31 letters, numbers, dollar signs, and underscore characters.

The Command Definition Language includes the following statements:

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

The following sections provide an overview of each CDU statement. See the CDU File Statements section for more detailed descriptions of each type of statement.

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.

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)

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

Contents

Index

Legal

 
6100PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
...	Horizontal ellipsis points in examples indicate one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ }	In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace type	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.