HP OpenVMS Systems Documentation
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual
Order Number: AA--QSBDE--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 HP OpenVMS Command Definition, Librarian, and Message Utilities Manual, Version 7.3
Software Version:OpenVMS I64 Version 8.2 OpenVMS
Alpha Version 8.2
© Copyright 2005 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP 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.
The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Printed in the US
The HP 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 HP OpenVMS products and services, access the HP website at the following location:
HP welcomes your comments on this manual. Please send comments to either of the following addresses:
How To Order Additional Documentation
For information about how to order additional documentation, visit the following World Wide Web address:
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
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.