Entering Commands | Getting Started with OpenVMS: A Guide for New Users (HP Technologies)

You may enter DCL commands in either upper-case or lower-case letters or in any mixture of the two. DCL will convert any items not enclosed within quotation marks ("") to upper case before processing the command. In keeping with the history of the OpenVMS documentation set, examples in this book are shown in upper case. When entering commands at the DCL prompt, you do not enter the leading dollar sign ($) shown in these examples. Dollar signs are required only within command procedures (see Chapter 9, "Command Procedures").

To enter a DCL command, type the verb first. Next, place any positional qualifiers you wish to apply to all parameters. Next come parameters (or keywords), the first of which must be preceded by a space. After each parameter, you may place any positional qualifier you wish to affect only that parameter. This positional qualifier is allowed to override the same qualifier appearing after the verb, as shown in examples that follow. A global qualifier may appear anywhere on the command line.

Some verbs, such as COPY and RENAME, accept multiple parameters. Others, such as PRINT and DELETE, accept lists of parameter values separated by commas (,) or plus signs (+) (see the following table).

You will encounter all of the following formats (and more) depending on the requirements of each command verb:

     General format                            Example     $ VERB                                    $ DIRECTORY                                               $ LOGOUT     $ VERB/QUALIFIER                          $ DIRECTORY/FULL                                               $ LOGOUT/BRIEF     $ VERB PARAMETER (or KEYWORD)             $ DELETE file                                               $ SHOW TIME     $ VERB PARAM1 PARAM2                      $ COPY existing-file new-file                                               $ RENAME old-name new-name     $ VERB PARAM1+PARAM2                      $ PRINT file1+file2                                               $ DELETE file1,file2     $ VERB/QUALIFIER PARAM,PARAM/QUALIFIER    $ PRINT/COPIES=2 file1,file2/COPIES=3

When the command is complete, press ENTER.

Before pressing ENTER, you may edit the command to correct any mistakes by using the backspace or delete key; in addition, you may use the arrow keys to move the cursor. Use CTRL/A to toggle between insert and overstrike modes. It is not necessary for the cursor to be at the end of the line when you press ENTER.

You may sometimes omit required elements and have DCL prompt you for them (see the section on "Entering Incomplete Commands" below).

Keywords

Some DCL commands may include an additional element known as a keyword. Keywords can appear in two different places. Sometimes, a keyword supplies a value to a qualifier. Other times, it appears after a verb, just as a parameter would.

Keywords are predefined words, not arbitrary text. When one appears on a command line, it must appear in the right place and be one of the values allowed by the command verb or qualifier with which it appears. For example:

    $ DIRECTORY LOGIN.COM /DATE=MODIFIED    Directory DKA100:[MIKE]     LOGIN.COM;45        30-AUG-2001 16:18:45.96     Total of 1 file.

This command instructs the DIRECTORY program to show the modification date of the file LOGIN.COM. In this example, MODIFIED is a keyword for the /DATE qualifier. Other possible keywords for DIRECTORY/DATE include BACKUP (the date the file was last backed up), CREATED (the date the file was created), and EXPIRATION (the date the file will expire or has expired).

Note

File expiration dates are used fairly infrequently, but may be used to help identify certain files that may no longer be needed. The system itself takes no action when a file expires.

Some qualifiers allow their keywords to appear in a list. Place them within parentheses, separated by commas. Colons (:) and equals signs (=) can be used interchangeably to supply a value to a keyword. The following two commands are equivalent:

     $ SET FILE DATA.TXT /PROTECTION=(SYSTEM=RWED,OWNER=RWED,GROUP=RW,WORLD=R)     $ SET FILE DATA.TXT /PROTECTION=(SYSTEM:RWED,OWNER:RWED,GROUP:RW,WORLD:R)

When using only one keyword, the parentheses may be omitted. The following two commands are equivalent:

     $ SET FILE DATA.TXT /PROTECTION=(SYSTEM=RWED)     $ SET FILE DATA.TXT /PROTECTION=SYSTEM=RWED

When appearing after a verb, keywords can behave like parameters. Let's consider a previous example:

     $ PRINT SCHEDULE.LIS

As we have seen, the verb (what to do) is PRINT. The parameter (what to PRINT) is SCHEDULE.LIS. Now let's introduce a command verb that uses keywords:

     $ SHOW TIME       6-NOV-2002 17:33:34

In this example, the verb (what to do) is SHOW, and the keyword (what to show) is TIME. When used this way, a keyword and a parameter are similar, but there are some important differences.

Parameters may appear as lists of items to be processed together, such as with a PRINT command specifying multiple files. The following commands

     $ PRINT SCHEDULE.LIS     $ PRINT PAYROLL.DAT

may be combined as follows:

     $ PRINT SCHEDULE.LIS,PAYROLL.DAT

Keywords, however, are usually not permitted in that kind of combination:

     $ SHOW DEFAULT      DKA0:[MIKE]     $ SHOW TIME        6-NOV-2002 17:22:47

Each of these commands is fine alone, but they cannot be combined. An attempt to do so results in an error message (more on those later):

     $ SHOW DEFAULT,TIME     %DCL-W-NOLIST, list of parameter values not allowed - check use of comma (,)      \DEFAULT,TIME\

DCL Keywords

Why is there a distinction between parameters and keywords used where parameters usually appear? The answer lies in the OpenVMS command definition utility (CDU). CDU is the tool that allows programmers to define the command line elements that their programs will use. Keywords allow the same command verb to execute one of several programs, depending on the keyword. For example, the program that performs the SET PASSWORD command can be separate from the program that performs the SET TIME command. This allows for smaller, more modular programs when a single verb, like SHOW or SET, makes sense for a variety of different functions.

Abbreviation of Command Line Elements

You need not always enter the full text of DCL verbs, qualifiers, or keywords. You may abbreviate them to the shortest length that is unambiguous with other valid entries. For example, you may abbreviate the DIRECTORY command verb to DIRECT or DIR. Yet you may not abbreviate it to DI, because that abbreviation also matches the DIAGNOSE, DIFFERENCES, DISABLE, DISCONNECT, and DISMOUNT verbs.

Should you abbreviate a command element to the point at which it becomes ambiguous, DCL will produce a message to that effect:

     $ DI     %DCL-W-ABVERB, ambiguous command verb - supply more characters      \DI\

Entering Commands Longer Than One Line

DCL can accept commands longer than one line. When your command nears the edge of the screen, you may simply continue typing and allow the line to wrap to the next line automatically. This method works for command lines shorter than 255 characters, or a little more than three lines on most terminals. If you exceed this limit, DCL will terminate your command entry and display an error message.

To manually continue a long command on the next line, end the current line with a hyphen (-) and press ENTER. DCL will not process the line you just entered, but will wait for you to continue your command on the next line. DCL indicates it is waiting for continuation by preceding the prompt by an underscore (_). A single command can be continued over several lines, as shown here:

     $ PRINT CONTENTS.TXT,CHAPTER1.TXT,CHAPTER2.TXT -     _$ /QUEUE=PRINTER3/FORM=SINGLE_LETTER/AFTER="11:00" -     _$ /JOB_COUNT=4/NOTIFY [enter]

When you continue a line with a hyphen, DCL will check for a valid command verb as soon as you move on to the first continuation line.

Once you have moved on to a continuation line, you may no longer correct any mistakes you may have made on a previous line. If you have made a mistake, you may press CTRL/Y to cancel the entire command.

Entering Incomplete Commands (DCL Prompts)

If you enter a DCL command, but do not include all required parameters, DCL will prompt you for the input it needs to process your command. If you wish to RENAME a file, but do not tell DCL what file to rename or what the new name should be, DCL will prompt you for these items:

     $ RENAME [enter]     _From: DRAFT4.TXT[enter]     _To: FINAL.TXT [enter]

If you simply press ENTER in response to a prompt, the prompt will be repeated until you enter a value or cancel the command. To cancel the command, press CTRL/Z.

     $ RENAME [enter]     _From: [enter]     _From: [enter]     _From: [ctrl/z] *Exit*

Note that DCL will prompt only for required elements; it is up to you to enter any optional elements, such as qualifiers. If a valid verb and all required parameters are present when you press ENTER or CTRL/Z, the command will be issued.

Comments

The DCL comment delimiter is an exclamation mark (!). When you place an exclamation mark on a DCL command line (except within quotation marks), everything to the right of it will be ignored by DCL.

This feature is used mainly in DCL command procedures (files containing commands to be executed sequentially) to provide internal documentation. A comment delimiter may also be used in an interactive command, as follows:

     $ SHOW TIME ! This is a comment and will be ignored.       21-NOV-2002 17:27:09

An exclamation mark appearing within quotation marks will not be treated as a comment character, but will be processed as part of the string in which it appears. For example, you may define a symbol whose value contains an exclamation mark as follows (symbols are introduced later in this chapter):

     $ PHRASE :== "Hey! That's my car!"     $ SHOW SYMBOL PHRASE       PHRASE == "Hey! That's my car!"

Informational, Warning, and Error Messages

In many cases, DCL simply executes your command without displaying a message. In general, if you see no message, you may assume that the command completed successfully.

If the command was unsuccessful or DCL has other information it must provide you, DCL will display an appropriate message. DCL messages, like DCL commands, follow a specific format. This section will show you how to interpret a DCL message.

Let's say you wish to obtain the current time:

     $ SHOW TIME       22-NOV-2002 18:28:49

But, you make a typographical error:

     $ SHOW TOME     %DCL-W-IVKEYW, unrecognized keyword - check validity and spelling      \TOME\

In the above example, TIME is misspelled as TOME, causing DCL to respond with a message indicating that it could not process the command.

Let's take a closer look at the message, breaking it down into its various parts to illustrate the uniform way that DCL reports errors. Consider the message

     %DCL-W-IVKEYW, unrecognized keyword - check validity and spelling      \TOME\

Messages begin with a percent sign (%) unless several related messages are displayed together (discussed below).

Next come three fields that identify the program issuing the message (here, DCL), the severity of the error (in this case W, meaning warning), and the error mnemonic (IVKEYW).

After this, the error is explained in plain English: "unrecognized keyword."

Finally, the message may include advice on how you may correct the error: "check validity and spelling."

Note

Any or all of these fields may be disabled via the SET MESSAGE command. See the OpenVMS online help facility for information.

Severity Levels

Every OpenVMS error message has an associated severity level, as follows. The numeric equivalents are shown in parentheses. Note that the numeric values follow the OpenVMS convention that odd values indicate success (or TRUE) conditions, while zero and even values indicate failure (or FALSE) conditions.

     -S-   (1) Success     -I-   (3) Informational     -W-   (0) Warning     -E-   (2) Error     -F-   (4) Severe (fatal) error

Multiple Messages from the Same Command

Sometimes a command may generate more than one error message in response to a single command. There are two principal reasons for this. One is that the command must perform several operations, more than one of which generates a separate message. The other main reason is to clarify the preceding message further. Both types are shown in the following example:

     $ PRINT/QUEUE=PRINTER4 NOFILE1.TXT,LOGIN.COM     %PRINT-E-OPENIN, error opening DKA0:[MIKE]NOFILE1.TXT; as input (1)     -RMS-E-FNF, file not found (2)     %PRINT-F-CREJOB, error creating job (3)     -JBC-E-NOSUCHQUE, no such queue (4)

This command attempts to print two files, LOGIN.COM, which exists, and NOFILE1.TXT, which does not. It attempts to print them on print queue PRINTER4, which also does not exist. The messages are interpreted below:

This message indicates that the PRINT facility cannot open the file NOFILE1.TXT. This is an error message, indicated by the severity field "-E-."
This message begins with a hyphen (-), indicating that it clarifies the previous message. It states the reason the file could not be opened: The file could not be found. This message is from the OpenVMS Record Management Services (RMS).

At this point, DCL continues to process the command, as it may still be possible to complete it partially. Had there been a Failure or Fatal error, processing would stop, but since the worst previous problem was an Error, processing continues.

The PRINT facility reports that it cannot create the print job (now consisting of just LOGIN.COM). This is a Fatal or Failure condition, as indicated by the severity code "-F-." Command processing stops upon encountering a Failure condition.
This message clarifies message (3), indicating the print job cannot be created because the specified printer queue, PRINTER4, does not exist. This message is from the Job Controller (JBC).