Document revision date: 19 July 1999

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.

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.

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. Parameter defaults are described in the following section. 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.

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.

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

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.

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

The following commands are equal:

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

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 between the PLUTO.TXT, SATURN.TXT, and EARTH.TXT file specifications.

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

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

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

3.6.4 Conflicting Qualifiers

If you use two or more contradictory qualifiers on a command line, the right-most qualifier overrides the others.

Some commands contain conflicting qualifiers that cannot be specified in the same command line. If you use incompatible qualifiers, the command interpreter displays an error message.

Following is an example of conflicting qualifiers. Note that the PRINT command accepts only the /COPIES=2 and the /NOBURST qualifiers because they are the right-most qualifiers in the command line:

$ PRINT MYFILE/COPIES=3/BURST/COPIES=2/NOBURST EARTH.TXT

3.6.5 Values Accepted by Qualifiers

Qualifiers can accept keywords, file specifications, character strings, and numeric values. When you enter a value for a qualifier, separate the qualifier and the value with either an equal sign (=) or a colon (:).

Some qualifier keywords require additional information. In these cases, separate the keyword from its value with a colon or an equal sign.

To specify multiple keywords that require values, enclose the list in parentheses and separate the keyword and value with either an equal sign (=) or a colon (:).

Examples

• Either command in this example is valid:

  $ PRINT/COPIES=3 MYFILE.DAT

  $ PRINT/COPIES:3 MYFILE.DAT

• This is an example of a qualifier that requires additional information; the keyword "PROTECTION" is separated from its value by a colon:

  $ SET SECURITY/PROTECTION:GROUP:RW MYFILE.DAT

  $ SET SECURITY/PROTECTION=GROUP=RW MYFILE.DAT

• This is an example of a qualifier that requires multiple keywords, each of which require multiple values:

  $ SET SECURITY/PROTECTION=(OWNER=RWD,GROUP=RW) myfile.dat

  $ SET SECURITY/PROTECTION=(OWNER:RWD,GROUP:RW) myfile.dat

Certain commands and qualifiers (such as the PRINT/AFTER command) accept date and time values. You can specify these values in one of the following formats:

• Absolute time
• Delta time
• Combination time (combines absolute and delta time formats)

Absolute time is a specific date or time of day. The format for absolute time is as follows:

[dd-mmm-yyyy][:hh:mm:ss.cc]

The fields are as follows:

dd	Day of the month: an integer in the range 1 to 31
mmm	Month: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, or DEC
yyyy	Year: an integer
hh	Hour: an integer in the range 0 to 23
mm	Minute: an integer in the range 0 to 59
ss	Second: an integer in the range 0 to 59
cc	Hundredths of a second: an integer in the range 0 to 99

The following rules apply when specifying absolute time:

• You can truncate the date or the time on the right.
• If you specify both a date and a time, include a colon between them.
• The date must contain at least one hyphen.
• You can omit any of the fields within the date and time as long as you include the punctuation marks that separate the fields.
• A truncated or omitted date field defaults to the corresponding fields for the current date.
• A truncated or omitted time field defaults to zero.
• If you specify a past time in a command that expects the current or a future time, the current time is used.

You can also specify an absolute time as one of the following keywords:

TODAY	The current day, month, and year at 00:00:00.0 o'clock
TOMORROW	00:00:00.00 o'clock tomorrow
YESTERDAY	00:00:00.00 o'clock yesterday

The following table shows examples of absolute time specifications:

Time Specification	Result
11-DEC-1996:13	1 P.M. on December 11, 1996
11-DEC	Midnight at the beginning of December 11 this year
15:30	3:30 P.M. today
19--	Midnight on the 19th day of the current year and month
19--:30	12:30 A.M. on the 19th of this month

	privacy and legal statement
6489PRO_005.HTML