Document revision date: 30 March 2001

## OpenVMS User's Manual

Previous | Contents | Index

## Chapter 3
The DIGITAL Command Language: Interacting with the System

This chapter describes how to use the DIGITAL Command Language. This chapter includes information about:

- Using DCL commands
- Constructing DCL commands
- Entering DCL commands
- Rules for entering DCL commands
- Entering parameters
- Entering qualifiers
- Entering dates and times as values
- Recalling commands
- Editing the DCL command line
- Defining terminal keys
- Summary of key sequences

For additional information, refer to:

- The OpenVMS DCL Dictionary and online help, for all the commands, qualifiers, and parameters discussed in this chapter
- The OpenVMS Guide to Extended File Specifications, for commands for use with Extended File Specifications

## 3.1 Using DCL Commands

The DIGITAL Command Language (DCL) is a set of English-like instructions that tell the operating system to perform specific operations.

DCL commands let you do the following:

- Get information about the system
- Work with files
- Work with disks, magnetic tapes, and other devices
- Modify your work environment
- Develop and execute programs
- Provide security and ensure that resources are used efficiently

### 3.1.1 Entering Commands

To enter a DCL command, type the command at the DCL prompt ($) and press Return. DCL is not case sensitive; you can enter commands in either uppercase or lowercase letters.

In the following example, the DCL command SHOW TIME is entered as follows:

    $ SHOW TIME [Return]

The system responds by displaying the current date and time and returns the DCL prompt to indicate it is ready to accept another command:

    11-DEC-1999  15:41:43
    $

### 3.1.2 Commonly Used DCL Commands

The following table lists the DCL commands you use to perform a few common computing tasks:

Command | Task
--- | ---
COPY | Makes a copy of a specified file
COPY/FTP | Transfers files between hosts over a TCP/IP network
CREATE | Creates files or directories
DELETE | Erases a specified file and removes it from a directory
DIRECTORY | Displays the contents of a directory (list of files)
EDIT | Views and changes the contents of a text file
LOGOUT | Ends your session
PRINT | Sends a specified file to a printer for printing
RENAME | Changes the name or the location of a specified file
SET | Controls how you see the system on the screen
SHOW | Displays the status of the system
TYPE | Displays the contents of a specified file on the screen

### 3.1.3 Key Sequences

In addition to these DCL commands, you can perform tasks by using specific key sequences. A key sequence is a shortcut or a way to get the system's attention while it is processing another command.

To enter a key sequence, hold down the Ctrl key while you press and release a second key.

The following table describes a few commonly used key sequences. (Additional key sequences are listed in Section 3.11.)

Key Sequence | Function
--- | ---
Ctrl/C | During command entry, cancels command processing. Ctrl/C displays on your screen as Cancel.
Ctrl/Y | Interrupts command processing. Ctrl/Y displays on your screen as Interrupt.
Ctrl/T | Displays information about the current process, unless the system is temporarily unresponsive or is set to NOBROADCAST. For more information on using Ctrl/T, see Section 2.9.

## 3.2 Constructing DCL Commands

Like a spoken language, DCL is made up of words (vocabulary) and word order (syntax or format). The following sections describe these two elements and explain how to construct a valid DCL command.

The following example shows the general format and parts of a DCL command line:

    $  PRINT/COPIES = 5  GROCERY.LIS  [Return]
    (1)
       (2)
       (3)
          (4)
         (5)
         (6)

The following list describes each element of the DCL command line:

1. DCL prompt
   The dollar sign ($) is the default DCL prompt. When you work interactively with DCL, DCL displays the prompt when it is ready to accept a command.
2. DCL command
   A DCL command specifies the name of the command. The command can be a built-in command, a command that invokes a program, or a foreign command. In this example, the DCL command is PRINT.
3. Qualifier
   A qualifier modifies the action taken by the command. Some qualifiers modify the entire command, while others can modify specific command parameters. Some qualifiers can accept values. Qualifiers are always preceded by a slash (/). In this example, the qualifier is /COPIES.
4. Value
   A value modifies a qualifier and is often preceded by an equal sign (=). A value can be a file specification, a character string, a number, or a DCL keyword. A keyword is a word reserved for use in certain specified formats.
   In this example, the value is 5 (for 5 copies).
5. Parameter
   A parameter specifies what the command acts upon. You must position parameters in a specified order within the command. Examples of parameter values include file specifications, queue names, and logical names.
6. Return key
   The Return key ends the DCL command line and signals to the system that the command is ready for processing.

### 3.2.1 Other Components of Command Lines

The following items may also be used in a DCL command line:

- Labels
  Labels identify lines in command procedures. Use labels only within command procedures, which are described in Chapter 15 and Chapter 16.
- Keywords
  Keywords are words that are defined for use in certain specified formats. You must use keywords exactly as listed in the description of the particular DCL command you want to specify. For example, system, owner, group, and world are DCL keywords for the /PROTECTION qualifier of the SET SECURITY command. (A DCL keyword can also have a value.)
- Wildcard characters
  Wildcard characters are the asterisk (*), percent sign (%), ellipsis (...) and hyphen (-). They can be used within, or in place of, a file name, file type directory name, or version number in a file specification to indicate all for the given field. For information about using wildcard characters with files and directories, see Chapter 4 and Chapter 5.

  Note If you are working in an environment with Extended File Specifications, refer to the OpenVMS Guide to Extended File Specifications for information about using wildcard syntax in DCL commands.

### 3.2.2 Syntax

Just as a spoken language depends on the order of words to create meaning, DCL requires that you put the correct elements of the command line in a specific word order or format.

Following are two examples of the syntax, or format, used for typical DCL commands:

`command/qualifier=value=keyword`

`command parameter/qualifier`

## 3.3 Entering DCL Commands

When you enter a DCL command, some parameters are required; they must be entered on the command line. If you do not enter them, the system prompts you to supply the missing information. A line beginning with an underscore (_) means that the system is waiting for your response.

When you are prompted for an optional parameter, press Return to omit it. At any prompt, after you enter the required parameter, you can enter one or more of the remaining parameters and any additional qualifiers.

Note that you must enclose in quotation marks ("") any parameter containing a slash (/) or at sign (@).

In the following example, the TYPE command requires a file specification. Because a file specification is a required parameter of the TYPE command, if you do not enter one, the system requests it.

    $ TYPE
    _File:   WATER.TXT

### 3.3.1 Canceling Commands

If you press Ctrl/Z after a command prompt, DCL ignores the command and redisplays the DCL prompt.

### 3.3.2 Using Defaults

Some items, called defaults, need not be specified on the command line. When DCL performs an operation by default, it assigns a command certain values or performs certain functions associated with that command even though you may not have explicitly specified those values or functions when you entered the command. In general, the values and functions are those considered typical or expected by users.

DCL supplies default values in several areas, including command parameters and qualifiers. For parameter defaults, see the sections in this manual that describe the specific DCL command. Qualifier defaults are described in Section 3.6.

If the number of copies is not specified as a qualifier for the PRINT command, DCL uses the default value 1. In the following example, the default is overridden and multiple copies of the file are printed by including the /COPIES qualifier on the PRINT command line:

    $ PRINT/COPIES=4 MYFILE.TXT

### 3.3.3 Entering Multiple Line Commands

If you enter a command longer than one line, you can continue the command onto the next line by following this procedure:

Step | Task
--- | ---
1 | End the command line with a hyphen (-) and press Return. The system displays an underscore (_) followed by the DCL prompt ($).
2 | Enter the rest of the command line after this prompt. A line beginning with an underscore means that the system is waiting for your response.

Note the following:

- You must include the appropriate spaces between command names, parameters, and so on.
- Pressing Return after the hyphen does not add a space.
- There is no restriction to the number of continued lines you can use to enter a command, as long as you do not exceed the 1024-character limit.
- You can also enter a long command line without specifying a hyphen; the system automatically wraps text to the next line. However, separating portions of the command lines with hyphens makes the command line easier to read.

The following example shows how to enter a multiple line command:

    $ COPY/LOG FORMAT.TXT,FIGURE.TXT,ARTWORK.TXT -
    _$ SAVE.TXT

You can use the DCL command PIPE to create complex command processing statements from a single DCL command. For example, you can execute one or more of the following operations from the same DCL command line:

- Pipelining (a sequence of commands)
- Input/output redirection
- Multiple and conditional command execution
- Background processing

For more detailed information, see Section 16.20 and the description of the PIPE command in the OpenVMS DCL Dictionary: N--Z.

Refer to the OpenVMS Guide to Extended File Specifications for more information about multiple line commands in an environment employing Extended File Specifications.

## 3.4 Rules for Entering DCL Commands

The following sections describe specific rules and requirements you must observe when entering a DCL command.

Note If you are working in an environment with Extended File Specifications, refer to the OpenVMS Guide to Extended File Specifications for rules about using extended file names in DCL commands.

### 3.4.1 Case Sensitivity

Use any combination of uppercase and lowercase letters. The DCL interpreter translates lowercase letters to uppercase. Uppercase and lowercase characters in parameter and qualifier values are equivalent unless enclosed in quotation marks (" ").

### 3.4.2 Required Spaces

- Separate the command name from the first parameter with at least one blank space or a tab.
- Separate each additional parameter from the previous parameter or qualifier with at least one blank space or a tab.

### 3.4.3 Required Punctuation

- Begin each qualifier with a slash (/). The slash serves as a separator and need not be preceded by blank spaces or tabs.
- If a parameter or qualifier value includes a blank space or a tab, enclose the parameter or qualifier value in quotation marks.

### 3.4.4 Null Characters

You cannot specify null characters (<NUL>) on a DCL command line, even if you enclose the null character in quotation marks.

### 3.4.5 Maximum Elements

Include no more than 127 elements (parameters, qualifiers, and qualifier values) in each command line.

Each element in a command must not exceed 255 characters. The entire command must not exceed 1024 characters after all symbols and lexical functions are converted to their values. You use symbols, described in Chapter 14, to pass information to the system in an abbreviated manner. A lexical function, described in Chapter 17, obtains information from the system, including information about system processes, batch and print queues, and user processes, and then substitutes the result of the operation for itself.

### 3.4.6 Abbreviating Commands

You can abbreviate a command as long as the abbreviated name remains unique among the defined commands on a system. DCL looks only at the first four characters for uniqueness.

The following commands are equal:

    $ PRIN/COPI=2 FORMAL_ART.TXT
    $ PRINT/COPIES=2 FORMAL_ART.TXT

For greater clarity and to ensure that your command procedures are upwardly compatible, do not abbreviate commands in command procedures.

### 3.4.7 Additional Rules for Commands in Command Procedures

Additional rules govern the format of commands when they are used in command procedures. See Chapter 15 and Chapter 16 for more information about using commands in command procedures.

## 3.5 Entering Parameters

File specifications are the most common type of parameter. DCL commands can accept input file specifications (files that are acted upon by a command) and output file specifications (files that are created by a command).

The following rules apply when specifying parameters in a command line:

- Square brackets ([]) in command descriptions indicate optional items. For example, you do not have to enter a file specification in the following command:

  `DIRECTORY [file-spec]`

- In a command description, anything not enclosed in square brackets is required. For example, you must enter a device name in the following command:

  `SHOW PRINTER device-name`

- In general, precede an output file parameter with an input file parameter.
- A parameter can be one item or a series of items. If you enter a series of items, separate the items with commas (,) or plus signs (+). Any number of spaces or tab characters can precede or follow a comma or a plus sign. Note that some commands regard the plus sign as a concatenator, not as a separator.

Examples

1. The following example shows how to copy the input file LISTS.TXT to the output file FORMAT.TXT:

       $ COPY LISTS.TXT FORMAT.TXT

2. The following example line shows how you can enter a list of file specifications as the parameter:

   `DELETE file-spec[,...]`

3. The following example shows how to specify a list of parameters. Here, three files are copied to a fourth file. The three file specifications, PLUTO.TXT, SATURN.TXT, and EARTH.TXT, constitute the first parameter. PLANETS.TXT is the second parameter. Note that there are no spaces (although they could have been inserted) between the PLUTO.TXT, SATURN.TXT, and EARTH.TXT file specifications.

       $ COPY PLUTO.TXT,SATURN.TXT,EARTH.TXT PLANETS.TXT

## 3.6 Entering Qualifiers

There are three types of qualifiers:

- Command
- Positional
- Parameter

You can abbreviate any qualifier name as long as the abbreviated name remains unique among all qualifier names for the same command. However, to ensure that your command procedures are upwardly compatible, do not abbreviate commands and qualifiers in command procedures.

Commands have default qualifiers; you do not have to specify a qualifier unless it is different from the command default. The following sections describe types of qualifiers and qualifier defaults. The OpenVMS DCL Dictionary contains default information for specific commands.

### 3.6.1 Command Qualifiers

A command qualifier modifies a command and can appear anywhere in the command line. However, it is a good practice to place the qualifier after the command name. If you are specifying multiple qualifiers, you should place a command qualifier with other command qualifiers that follow the command name.

In the following example, /QUEUE is a command qualifier. The files SATURN.TXT and EARTH.TXT are queued to the print queue LN03_PRINT:

    $ PRINT/QUEUE=LN03_PRINT SATURN.TXT,EARTH.TXT

### 3.6.2 Positional Qualifiers

A positional qualifier can modify commands or parameters and has different meanings depending on where you place it in the command string. If you place a positional qualifier after the command but before the first parameter, it affects the entire command string. If you place a positional qualifier after a parameter, it affects only that parameter.

In the following example, the first PRINT command requests two copies of the files SPRING.SUM and FALL.SUM. The second PRINT command requests two copies of the file SPRING.SUM but only one copy of FALL.SUM.

    $ PRINT/COPIES=2 SPRING.SUM,FALL.SUM
    $ PRINT SPRING.SUM/COPIES=2,FALL.SUM

### 3.6.3 Parameter Qualifiers

A parameter qualifier can be used only with certain types of parameters, such as input files and output files. For example, the BACKUP command accepts several parameter qualifiers that apply only to input and output file specifications.

In the following example, the /CREATED and /BEFORE qualifiers, which can be specified only with input files, select specific input files for the backup operation. The asterisk (*) is a wildcard character that replaces the file name. BACKUP selects all files with the .TXT file type that were created before December 11, 1999.

    $ BACKUP *.TXT/CREATED/BEFORE=11-DEC-1999 NEWFILE.TXT

Previous | Next | Contents | Index

| privacy and legal statement |
6489PRO_005.HTML