[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP OpenVMS Command Definition, Librarian, and Message Utilities Manual

Order Number: AA--QSBDE--TE

January 2005

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




Hewlett-Packard Company Palo Alto, California

© 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

ZK6100

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

Related Documents

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

  • HP OpenVMS DCL Dictionary
  • HP OpenVMS Linker Utility Manual

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


http://www.hp.com/go/openvms

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@hp.com
Postal Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address: 


http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions are 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 A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[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, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
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 text 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. 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

Note
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: 


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

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

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.

Next Contents Index