OpenVMS DCL Dictionary

Document revision date: 19 July 1999

January 1999

This manual provides detailed reference information and examples for OpenVMS DCL commands and lexical functions.

Revision/Update Information: This manual supersedes the OpenVMS DCL Dictionary, Version 7.1.

Software Version: OpenVMS Alpha Version 7.2 OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, CDA, CI, DDIF, DEC, DECdirect, DECdtm, DECnet, DECprint, DECspell, DECterm, DECUS, DECwrite, DECwriter Correspondent, DEQNA, DIGITAL, DTIF, EDT, GIGI, HSC, LA, LiveLink, LN03, MicroVAX, MSCP, OpenVMS, PATHWORKS, PrintServer, Q-bus, RC25, ReGIS, RQDX3, RRD42, RRD50, RX01, RX02, RX33, RX50, RZ, TE16, TMSCP, TS11, ULTRIX, UNIBUS, VAX, VAX 8530, VAX 8550, VAX 11/780, VAX COBOL, VAX DOCUMENT, VAX FORTRAN, VAXft, VAXserver, VAXstation, VMS, VT, VT100, VT300, WPS, XUI, and the Compaq logo.

The following are third-party trademarks:

Adobe, Display POSTSCRIPT, and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.

Motif, OSF, OSF1, and OSF/Motif are registered trademarks, and Open Software Foundation is a trademark of the Open Software Foundation, Inc.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

ZK9996

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

Intended Audience

This manual is intended for all users of the OpenVMS operating system. It includes descriptions of all DIGITAL Command Language (DCL) commands and lexical functions. If a command has any restrictions or requires special privileges, they are noted in reference information for that command.

Readers of this manual should be familiar with the material covered in the OpenVMS User's Manual.

Document Structure

This manual contains detailed descriptions of each command and lexical function. The commands are listed in alphabetical order, with the command name appearing at the top of every page. The lexical functions are grouped under the heading Lexical Functions (after the JOB command description) and are listed alphabetically within that grouping; the lexical function name appears at the top of each page.

The hard copy of the OpenVMS DCL Dictionary is a two-part manual. The first contains commands beginning with the letters A to M (including the lexical functions); The second part contains commands beginning with the letters N to Z. The Table of Contents and Index are comprehensive: they include both parts. The Bookreader copy of the OpenVMS DCL Dictionary is one manual.

Appendix A lists the obsolete DCL commands and the current services that replace them.

The commands that invoke language compilers and other OpenVMS optional software products are not included in this manual; they are included in the documentation provided with those products.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZK03-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

In this manual, any reference to OpenVMS is synonymous with DIGITAL OpenVMS.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis 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.

.
.
. A vertical ellipsis 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 you must enclose the options in parentheses if you choose more than one.

[ ] 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 required elements; 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 dd represents the predefined code for the device type).

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

= (Assignment Statement)

Defines a symbolic name for a character string or integer value.

Format

symbol-name =[=] expression

symbol-name[bit-position,size] =[=] replacement-expression

Note

Compaq advises against assigning a symbolic name that is already a DCL command name. Compaq especially discourages the assignment of symbols such as IF, THEN, ELSE, and GOTO, which can affect the interpretation of command procedures.

Parameters

symbol-name
Specifies a string of 1 to 255 characters for the symbol name. The name can contain any alphanumeric characters from the DEC Multinational character set, the underscore (_), and the dollar sign ($). However, the name must begin only with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. Using one equal sign (=) places the symbol name in the local symbol table for the current command level. Using two equal signs (:=,=) places the symbol name in the global symbol table.
expression
Names the value on the right-hand side of an assignment statement. This parameter can consist of a character string, an integer, a symbol name, a lexical function, or a combination of these entities. The components of the expression are evaluated, and the result is assigned to the symbol. All literal character strings must be enclosed in quotation marks (" "). If the expression contains a symbol, the expression is evaluated using the symbol's value.
The result of expression evaluation is either a character string or a signed integer value. If the expression is evaluated as a string, the symbol is assigned a string value. If the expression is evaluated as an integer, the symbol is assigned an integer value. If the integer value exceeds the capacity of the 4-byte buffer that holds it, no error message is issued.
For a summary of operators used in expressions, details on how to specify expressions, and details on how expressions are evaluated, refer to the OpenVMS User's Manual.
DCL uses a buffer that is 1024 bytes long to hold an assignment statement and to evaluate the expression. The length of the symbol name, the expression, and the expression's calculations cannot exceed 1024 bytes.
[bit-position,size]
States that a binary overlay is to be inserted in the current 32-bit value of a symbol name. The current value of the symbol name is evaluated. Then, the specified number of bits is replaced by the result of the replacement expression. The bit position is the location relative to bit 0 at which the overlay is to occur. If the symbol you are overlaying is an integer, then the bit position must be less than 32. The sum of the bit position and the size must be less than or equal to 32.
If the symbol you are overlaying is a string, then the bit position must be less than 6152. Because each character is represented using 8 bits, you can begin an overlay at any character through the 768th character. (The 768th character starts in bit position 6144.) The sum of the bit position and the size must be less than or equal to 6152.
The size is the number of bits to be overlaid. If you specify a size that is greater than 32, DCL reduces the size to 32.
The brackets are required notation; no spaces are allowed between the symbol name and the left bracket. Specify values for the bit position and size as integers.
replacement-expression
Specifies the value that is used to overlay the symbol you are modifying. Specify the replacement expression as an integer.
If the symbol you are modifying is an integer, the replacement expression defines a bit pattern that is overlaid on the value assigned to the symbol. If the symbol you are modifying is a character string, the result of the replacement expression defines a bit pattern that is overlaid on the specified bits of the character string. If the symbol you are modifying is undefined, the result of the replacement expression is overlaid on a null string.

Description

Symbols defined using assignment statements allow you to extend the command language. At the interactive command level, you can use symbols to define synonyms for commands or command lines. In command procedure files, you can use symbols to provide for conditional execution and substitution of variables.
The maximum number of symbols that can be defined at any time depends on the following:

The amount of space available to the command interpreter to contain symbol tables and labels for the current process. The amount of space is determined for each process by the system parameter CLISYMTBL.
The size of the symbol names and their values. The command interpreter allocates space for a symbol name and its value. In addition, a few bytes of overhead are allocated for each symbol.

Examples

#1
$ LIST == "DIRECTORY"

The assignment statement in this example assigns the user-defined synonym LIST as a global symbol definition for the DCL command DIRECTORY.

#2
$ COUNT = 0 $ LOOP: $ COUNT = COUNT + 1 $ IF P'COUNT' .EQS. "" THEN EXIT $ APPEND/NEW &P'COUNT' SAVE.ALL $ DELETE &P'COUNT';* $ IF COUNT .LT. 8 THEN GOTO LOOP $ EXIT

This command procedure, COPYDEL.COM, appends files (specified as parameters) to a file called SAVE.ALL. After a file has been appended, the command procedure deletes the file. Up to eight file names can be passed to the command procedure. The file names are assigned to the symbols P1, P2, and so on.
The command procedure uses a counter to refer to parameters that are passed to it. Each time through the loop, the procedure uses an IF command to check whether the value of the current parameter is a null string. When the IF command is scanned, the current value of the symbol COUNT is concatenated with the letter P. The first time through the loop, the IF command tests P1; the second time through the loop it tests P2, and so on. After the expression P`COUNT' is evaluated, the substitution of the file names that correspond to P1, P2, and so on is automatic within the context of the IF command.
The APPEND and DELETE commands do not perform any substitution automatically, because they expect and require file specifications as input parameters. The ampersand (&) precedes the P`COUNT' expression for these commands to force the appropriate symbol substitution. When these commands are initially scanned each time through the loop, COUNT is substituted with its current value. Then, when the commands execute, the ampersand causes another substitution: the first file specification is substituted for P1, the second file specification is substituted for P2, and so on.
To invoke this procedure, use the following command:
$ @COPYDEL ALAMO.TXT BEST.DOC
The files ALAMO.TXT and BEST.DOC are each appended to the file SAVE.ALL and are then deleted.

#3
$ A = 25 $ CODE = 4 + F$INTEGER("6") - A $ SHOW SYMBOL CODE CODE = -15 HEX = FFFFFFF1 Octal = 1777761

This example contains two assignment statements. The first assignment statement assigns the value 25 to the symbol A. The second assignment statement evaluates an expression containing an integer (4), a lexical function (F$INTEGER("6")), and the symbol A. The result of the expression, --15, is assigned to the symbol CODE.

#4
$ FILENAME = "JOBSEARCH" - "JOB" $ FILETYPE = ".OBJ" $ FILESPEC = FILENAME + FILETYPE $ TYPE 'FILESPEC'

The first command in this example assigns the symbol FILENAME the value "SEARCH". Notice that the string "SEARCH" is the result of the string reduction operation performed by the expression. The second command assigns the symbol FILETYPE the character string ".OBJ".
The symbols FILENAME and FILETYPE are then added together in an expression assigned to the symbol FILESPEC. Because the values of the symbols FILENAME and FILETYPE are concatenated, the resultant value assigned to FILESPEC is the character string "SEARCH.OBJ". The symbol FILESPEC is then used as a parameter for the TYPE command. The single quotation marks (` ') request the command interpreter to replace the symbol FILESPEC with its value SEARCH.OBJ. Thus, the TYPE command types the file named SEARCH.OBJ.

#5
$ BELL[0,32] = %X07 $ SHOW SYMBOL BELL BELL = ""

In this example, the symbol BELL is created with an arithmetic overlay assignment statement. Because the symbol BELL is previously undefined, the hexadecimal value 7 is inserted over a null character string and is interpreted as the ASCII code for the bell character on a terminal. When you issue the command SHOW SYMBOL BELL, the terminal beeps.
If the symbol BELL had been previously defined with an integer value, the result of displaying BELL would have been to show its new integer value.

#6
$ $=34 %DCL-W-NOCOMD, no command on line - reenter with alphabetic first character $ $$=34 $ SHOW SYMBOL $$ %DCL-W-UNDSYM, undefined symbol - check validity and spelling $ SHOW SYMBOL $ $ = 34 Hex = 00000022 Octal = 00000000042

$ $=34 
%DCL-W-NOCOMD, no command on line - reenter with alphabetic first
character 
$ $$=34 
$ SHOW SYMBOL $$ 
%DCL-W-UNDSYM, undefined symbol - check validity and spelling 
$ SHOW SYMBOL $ 
$ = 34   Hex = 00000022  Octal = 00000000042

If you begin a symbol name with the dollar sign ($), use two dollar signs ($$) because DCL discards the first instance of the dollar sign.

:= (String Assignment)

Defines a symbolic name for a character string value.

Format

symbol-name :=[=] string

symbol-name[offset,size] :=[=] replacement-string

Note

Parameters

symbol-name
Specifies a string of 1 to 255 characters for the symbol name. The name can contain any alphanumeric characters from the DEC Multinational character set, the underscore (_), and the dollar sign ($). However, the name must begin only with an alphabetic character, an underscore, or a dollar sign. Using one equal sign (:=) places the symbol name in the local symbol table for the current command level. Using two equal signs (::=,=) places the symbol name in the global symbol table.
string
Names the character string value to be equated to the symbol. The string can contain any alphanumeric or special characters. DCL uses a buffer that is 1024 bytes long to hold a string assignment statement. Therefore, the length of the symbol name, the string, and any symbol substitution within the string cannot exceed 1024 characters.
With the string assignment statement (:=), you do not need to enclose a string literal in quotation marks (" "). String values are converted to uppercase automatically. Also, any leading and trailing spaces and tabs are removed, and multiple spaces and tabs between characters are compressed to a single space.
It is easier to use the assignment statement (=) to create symbols with string values because the assignment statement does not automatically convert letters to uppercase and remove extra spaces. Also, the assignment statement allows you to perform string operations in expressions.
To prohibit uppercase conversion and to retain required space and tab characters in a string, place quotation marks around the string. To use quotation marks in a string, enclose the entire string within quotation marks and use a double set of quotation marks within the string. For example:
$ TEST := "this is a ""test"" string" $ SHOW SYMBOL TEST TEST = "this is a "test" string"
In this example, the spaces, lowercase letters, and quotation marks are preserved in the symbol definition.
To continue a symbol assignment on more than one line, use the hyphen (-) as a continuation character. For example:
$ LONG_STRING := THIS_SYMBOL_ASSIGNMENT_IS_A_VERY_LONG- _$ _SYMBOL_STRING
To assign a null string to a symbol by using the string assignment statement, do not specify a string. For example:
$ NULL :=
Specify the string as a string literal, or as a symbol or lexical function that evaluates to a string literal. If you use symbols or lexical functions, place single quotation marks (` ') around them to request symbol substitution. See the OpenVMS User's Manual for more information on symbol substitution.
You can also use the string assignment statement to define a foreign command. Refer to the OpenVMS User's Manual for more information about foreign commands.
[offset,size]
Specifies that a portion of a symbol value is to be overlaid with a replacement string. This form of the string assignment statement evaluates the value assigned to a symbol and then replaces the portion of the value (defined by the offset and size) with the replacement string. The brackets are required notation, and no spaces are allowed between the symbol name and the left bracket.
The offset specifies the character position relative to the beginning of the symbol name's string value at which replacement is to begin. Offset values start at 0.
If the offset is greater than the offset of the last character in the string you are modifying, spaces are inserted between the end of the string and the offset where the replacement string is added. The maximum offset value you can specify is 768.
The size specifies the number of characters to replace. Size values start at 1.
Specify the offset and size as integer expressions. Refer to the OpenVMS User's Manual for more information on integer expressions. The value of the size plus the offset must not exceed 769.
replacement-string
Specifies the string that is used to overwrite the string you are modifying. If the replacement string is shorter than the size argument, the replacement string is filled with blanks on the right until it equals the specified size. Then the replacement string overwrites the string assigned to the symbol name. If the replacement string is longer than the size argument, then the replacement string is truncated on the right to the specified size.
You can specify the replacement string as a string literal, or as a symbol or lexical function that evaluates to a string literal. If you use symbols or lexical functions, place single quotation marks (` ') around them to request symbol substitution. For more information on symbol substitution, refer to the OpenVMS User's Manual.

Examples

#1
$ TIME := SHOW TIME $ TIME 24-DEC-1998 11:55:44

Next Contents Index

privacy and legal statement

9996PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZK03-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis 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.
. . .	A vertical ellipsis 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 you must enclose the options in parentheses if you choose more than one.
[ ]	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 required elements; 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 dd represents the predefined code for the device type).
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 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.