HP OpenVMS Systems Documentation

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.

Software Version: OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3

Compaq Computer Corporation Houston, Texas

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

ZK6100

The Compaq OpenVMS documentation set is available on CD-ROM.

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.

Related Documents

For related information about these utilities, refer to the following documents:

• OpenVMS DCL Dictionary
• OpenVMS Linker Utility Manual

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

http://www.openvms.compaq.com/

Reader's Comments

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:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

The following conventions are used in this manual:

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

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

• Define the command in a command definition file, specifying the name of an image for the command to invoke.
• Use SET COMMAND to add the new definition to the DCL command table and copy the new table back to SYS$LIBRARY:

  $ SET COMMAND/TABLE=SYS$LIBRARY:DCLTABLES.EXE - _$ /OUTPUT=SYS$COMMON:[SYSLIB]DCLTABLES.EXE NEWCOMMAND.CLD

• To make the new command available to other users, use the INSTALL utility:

  $ INSTALL REPLACE SYS$LIBRARY:DCLTABLES.EXE

• To make the new command available to existing interactive processes, you can log out and log in again, or execute the following command:

  $ SET COMMAND/TABLE=SYS$LIBRARY:DCLTABLES.EXE

$ DIR SYS$SPECIFIC:[SYSLIB]DCLTABLES.EXE

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

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.