HP OpenVMS Systems Documentation
OpenVMS Command Definition, Librarian, and Message Utilities Manual
Order Number: AA--QSBDD--TE
This manual describes how to use the Command Definition Utility to modify OpenVMS 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.1.
OpenVMS Alpha Version 7.3
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.
OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group, L.P in the United States and other countries.
Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States and other countries.
Intel, Intel Inside, and Pentium are trademarks of Intel Corporation in the United States and other countries.
Motif, OSF/1, and UNIX are trademarks of The Open Group in the United States and other countries.
All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.
The Compaq OpenVMS documentation set is available on CD-ROM.
This manual is intended for programmers and general users of the OpenVMS operating system.
This manual is divided into three parts.
Chapter 1 describes the Command Definition Utility (CDU) and consists of the following sections:
Chapter 2 describes the Librarian utility (LIBRARIAN) and consists of the following sections:
Chapter 3 describes the Message utility (MESSAGE) and consists of the following sections:
For related information about these utilities, refer to the following documents:
For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:
How To Order Additional Documentation
Visit the following World Wide Web address for information about how to order additional documentation:
If you need help deciding which documentation best meets your needs, call 800-282-6672.
The following conventions are used in this manual:
$ 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. Compaq maintains the command definition files
for DCL; they are not shipped with your system.
1.2 Using CDU
To use CDU:
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.CLD
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. Refer to the OpenVMS Utility Routines Manual for additional information.
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
Following are the instructions to add a command to the DCL command table in SYS$LIBRARY:
$ SET COMMAND/TABLE=SYS$LIBRARY:DCLTABLES.EXE - _$ /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE NEWCOMMAND.CLD
$ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE
$ SET COMMAND/TABLE=SYS$LIBRARY:DCLTABLES.EXE
To ensure that the modified tables are written to the cluster common root, the output file specification is: SYS$COMMON:[SYSLIB]. This ensures that the new command is available to all systems sharing the same system disk. This also avoids potential problems with future changes to the command tables due to copies of DCLTABLES being present in the SYS$SPECIFIC:[SYSLIB] and SYS$COMMON:[SYSLIB] areas referenced by SYS$LIBRARY:.
To locate potentially errant copies of the command tables, use the following command:
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.
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
To maintain compatibility with earlier releases, CDU accepts character strings that are not enclosed in quotation marks. However, Compaq 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.