Digital PDFs

AI-Y517A-TE

April 1986

770 pages

Original

66MB

Document:	VMS 4.4 VAX VMS Users Manual
Order Number:	AI-Y517A-TE
Revision:
Pages:	770
Original Filename:	https://archive.org/download/stx_AI-Y517A-TE_VMS_4.4_VAX_VMS_Users_Manual_Apr86/AI-Y517A-TE_VMS_4.4_VAX_VMS_Users_Manual_Apr86.pdf

OCR Text

VAX/VMS
User’s Manual
Order Number: AI-Y517A-TE

April 1986
This manual is an overview of the general use of the VAX/VMS
operating system.

Operating System and Version:

VAX/VMS Version 4.4

Software Version:

VAX/VMS Version 4.4

digital equipment corporation
maynard, massachusetts

April 1986
The information in this document is subject to change without notice and should not
be construed as a commitment by Digital Equipment Corporation. Digital Equipment
Corporation assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or
copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.
Copyright ©1986 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document requests the
user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

3BEBBSD

ZK3144
HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO RICO*

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital’s local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire, Alaska, and Hawaii call 603-884-6660.
In Canada call 800-267-6215.
*Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment Corporation,
Westminster, Massachusetts 01473.
This document was prepared using an in-house documentation production system. All page composition and
make-up was performed by T^X, the typesetting system developed by Donald E. Knuth at Stanford University.
T^X is a registered trademark of the American Mathematical Society.

Contents
Preface
Chapter 1

XV
Interaction with the System
1.1
Logging in to the System .
1.1.1
Automatic Login.
1.1.2
Dialing in.
1.1.3
Logging in over the Network.
1.1.3.1
Access and Login.
1.1.3.2
Terminating a Remote Session.
1.1.4
Logging out of the System.

1-1
1-2
1-2
1-3
1-5
1-6
1-6

1.2
Using the Terminal.
1.2.1
Entering Text.
1.2.2
Controlling Output.
1.2.2.1
Suspending/Resuming Terminal Display.
1.2.2.2
Formatting Screen Output with Escape Sequences ...

1-7
1-7
1-8
1-8
1-8

1.3
Setting the Terminal's Physical Attributes.
1.3.1
VT200 Series
1.3.1.1
The Set-Up Directory.
1.3.1.2
Changing Attributes with Set-Up.
1.3.1.3
Critical Attributes.
1.3.2
VT100 Series .
1.3.2.1
SET-UP Mode A.
1.3.2.2
SET-UP Mode B.

1-10
1-10
1-11
1-12
1-14
1-14
1-15
1-16

1.4 Commands and Utilities.
1.4.1
DCL Command Format.
1.4.2
Parameters.
1.4.3
Qualifiers.
1.4.4
Prompts.
1.4.5
Interactive Commands .
1.4.6
Interrupting Commands.
1.4.7
Editing Command Lines .
1.4.8
Help.

1-18
1-19
1-20
1-21
1-22
1-23
1-23
1-24
1-26

Contents

1.5
Shortcuts for Entering Commands.
1.5.1
Symbols .
1.5.2
Command Procedures.
1.5.3
Key Definitions.
1.5.3.1
Definable Keys .
1.5.3.2
Key States .
1.5.3.3
Examining and Deleting Keys.
1.5.4
Recalling Command Lines.

1-27
1-27
1-28
1-29
1-30
1-30
1-31
1-32

1.6
User Environment.
1.6.1
Programs.
1.6.2
Processes.
1.6.3
System Implementation.
1.6.3.1
Memory.
1.6.3.2
Images and Working Sets.
1.6.3.3
Processes and the Balance Set.
1.6.3.4
Resident System.
1.6.3.5
System Parameters.

1-33
1-33
1-34
1-36
1-36
1-37
1-38
1-39
1-39

1.7
1.7.1
1.7.2
1.7.3

Subprocesses.
Exiting from a Subprocess.
Subprocess Context.
Subprocess Execution.

1-39
1-41
1-42
1-43

1.8
1.8.1
1.8.2
1.8.3
1.8.4

Batch Jobs.
Submitting a Batch Job.
Controlling a Batch Job.
Batch Job Output.
Restarting Batch Jobs .

1-43
1-44
1-45
1-46
1-46

1.9
1.9.1
1.9.2

Error Conditions.
Commands That Do Not Change $STATUS.
System Error Messages.

1-48
1-48
1-49

1.10 Using the Mail Utility.
1.10.1
Sending Mail .
1.10.1.1
Sending a Mail Message .
1.10.1.2
Sending a File.
1.10.1.3
Setting the Default Editor.
1.10.1.4
Sending a Message Between Systems.
1.10.1.5
Sending a Message to a Distribution List.
1.10.2
Reading Mail .
1.10.2.1
New Messages.
1.10.2.2
Old Messages.
1.10.3
Creating a File from a Mail Message.
1.10.4
Deleting Mail.

1-49
1-49
1-50
1-51
1-51
1-52
1-52
1-53
1-53
1-54
1-55
1-55

Contents

1.10.5
Organizing Mail .
1.10.5.1
Creating and Modifying Folders.
1.10.5.2
Deleting Folders.
1.10.5.3
Creating, Accessing, and Deleting Mail Files.
1.10.5.4
Selecting Folders.
1.10.6
Using a Mail Subdirectory.
1.10.7
Using the Mail Keypad.

1-56
1-57
1-57
1-58
1-58
1-59
1-59

Chapter 2 Storage and Output of Data
2.1
2.1.1
2.1.2
2.1.3

Devices.
Physical Device Names.
Logical Device Names.
Generic Device Names.

2-1
2-2
2-2
2-3

2.2
File Operations on Disks.
2.2.1
File Specifications.
2.2.1.1
Setting Device and Directory Defaults.
2.2.1.2
Using Default File Specifications.
2.2.1.3
Matching Wildcards (* and %).
2.2.1.4
Search Wildcards (... and -).
2.2.2
Directory Operations.
2.2.2.1
Displaying Directories.
2.2.2.2
Creating Directories.
2.2.2.3
Deleting Directories .
2.2.3
File Operations.
2.2.3.1
File Characteristics.
2.2.3.2
Creating and Modifying Files.
2.2.3.3
Examining Files.
2.2.3.4
Deleting Files .
2.2.3.5
Common Qualifiers.
2.2.4
System Directories and Files.

2-3
2-3
2-4
2-5
2-6
2-7
2-8
2-9
2-10
2-10
2-11
2-12
2-14
2-17
2-17
2-18
2-19

2.3
Logical Names.
2.3.1
Logical Name Definition.
2.3.1.1
Defining Logical Names.
2.3.1.2
Deassigning Logical Names .
2.3.1.3
Displaying Logical Names.
2.3.2
Logical Name Translation .
2.3.2.1
Iterative Translation.
2.3.2.2
Noniterative Translation .
2.3.2.3
Concealed Translation of Device Names.
2.3.2.4
Search List Translation .
2.3.3
Scope and Precedence of Logical Names.
2.3.3.1
Logical Name Table Directories.

2-20
2-20
2-21
2-22
2-22
2-23
2-23
2-24
2-24
2-24
2-25
2-26

Contents

2.3.3.2
2.3.3.3
2.3.3.4
2.3.4
2.3.4.1
2.3.4.2

Precedence.
Logical Name Table Creation.
Access Modes.
System-Created Logical Names.
Process-Permanent Logical Names.
System-Permanent Logical Names.

2-28
2-29
2-30
2-30
2-30
2-31

2.4
Printing Files.
2.4.1
Controlling a Print Job .
2.4.2
Controlling a Print Queue.
2.4.2.1
Stopping and Restarting a Queue.
2.4.2.2
Creating a Print Queue.
2.4.2.3
Specifying Print Features and Restrictions.
2.4.2.4
Using the FORM=type Keyword.
2.4.3
Using Multiple Print Queues.
2.4.3.1
One Printer with Multiple Queues.
2.4.3.2
One Queue with Multiple Printers.

2-32
2-33
2-34
2-34
2-34
2-35
2-35
2-36
2-36
2-37

2.5
Sorting and Merging Files.
2.5.1
Record Sorting .
2.5.1.1
Single Key.
2.5.1.2
Multiple Keys.
2.5.2
Other Types of Sorting.
2.5.3
Character Data Files.
2.5.4
Noncharacter Data Files.
2.5.5
Terminal Input.
2.5.6
Output File Organization.
2.5.7
Batch Job Submission.
2.5.8
Specification Files.
2.5.8.1
Creating or Modifying a Collating Sequence.
2.5.8.2
Reformatting Records in the Output File.
2.5.8.3
Conditionally Selecting Key and Data Fields.
2.5.9
Merging Files.

2-37
2-37
2-38
2-39
2-39
2-40
2-40
2-41
2-41
2-41
2-42
2-43
2-44
2-44
2-45

2.6
Using Libraries.
2.6.1
Creating Text Libraries.
2.6.2
Creating Help Libraries.
2.6.2.1
Creating Help Modules.
2.6.2.2
Naming Help Libraries .
2.6.3
Displaying Libraries.
2.6.4
Deleting Libraries.
2.6.5
Adding Library Modules.
2.6.6
Deleting Library Modules.
2.6.7
Modifying Library Modules.

2-45
2-46
2-46
2-47
2-49
2-49
2-50
2-50
2-51
2-51

2.7

2-52

Transferring Files Between Systems.

2.7.1
2.7.2
2.7.3

Chapter 3

Contents

vii

Reading Files from Another System.
Writing Files to Another System.
Access Restrictions.

2-53
2-53
2-54

Editing Files with the EDT Editor

3.1
Invoking and Terminating EDT.
3.1.1
Invoking EDT.
3.1.2
Terminating EDT.
3.1.2.1
Saving Your Edits.
3.1.2.2
Discarding Your Edits.

3-1
3-2
3-2
3-3
3-3

3.2
3.2.1
3.2.2
3.2.3

Entering EDT Commands.
Entering EDT Line Commands.
Entering Keypad Commands .
Canceling EDT Commands.

3-3
3-3
3-4
3-6

3.3
3.3.1
3.3.2
3.3.3

Getting Help in EDT.
Getting HELP on Keypad-Editing Commands.
Getting HELP on Line-Editing Commands.
Getting HELP on Nokeypad-Editing Commands.

3-6
3-7
3-7
3-7

3.4
3.4.1
3.4.2
3.4.3

Changing Editing Modes.
Changing from Keypad to Line Editing.
Changing from Line to Keypad Editing.
Entering Line-Editing Commands from Keypad
Mode.

3-7
3-8
3-8
3-8

3.5

Recovering from Interruptions.

3-9

3.6
EDT Keypad Editing . 3-10
3.6.1
Manipulating the Cursor. 3-10
3.6.1.1
Moving the Cursor by Small Units. 3-10
3.6.1.2
Moving the Cursor by Large Units. 3-13
3.6.1.3
Moving the Cursor to the Beginning or End of the
Buffer.3-13
3.6.1.4
Changing the Cursor's Direction. 3-14
3.6.2
Inserting Text. 3-16
3.6.3
Deleting and Restoring Text. 3-16
3.6.3.1
Deleting and Restoring Characters. 3-17
3.6.3.2
Deleting and Restoring Words. 3-17
3.6.3.3
Deleting and Restoring Lines . 3-18
3.6.3.4
Deleting and Restoring Large Sections. 3-19
3.6.4
Locating Text. 3-20
3.6.5
Substituting Text. 3-22
3.6.6
Moving Text.
3-24

viii

Contents

3.6.6.1
3.6.6.2
3.6.7
3.7
3.7.1
3.7.2
3.7.3
3.7.4
3.7.5

Chapter 4

Moving Text Within the File.
Moving Text Between Files.
Using Multiple Buffers .

3-24
3-29
3-29

Controlling EDT Sessions.
Startup Command Files.
Controlling Screen Format with SET Commands.
Controlling Editing Functions with SET Commands . . .
Defining Keys.
Defining EDT Macros.

3-32
3-32
3-33
3-34
3-35
3-36

Using DIGITAL Standard Runoff

4.1
Formatting Text .
4.1.1
Filling and Justifying Text.
4.1.2
Adjusting Margins and Centering Text.
4.1.3
Writing Paragraphs.
4.1.4
Writing Literal Text .
4.1.5
Writing Lists.
4.1.5.1
Numbered Lists.
4.1.5.2
Bulleted Lists.
4.1.5.3
Nested Lists.
4.1.5.4
Letters and Roman Numerals.
4.1.6
Leaving Space on a Page.
4.1.7
Writing Notes.
4.1.8
Writing Footnotes .
4.1.9
Bolding and Underlining Text.

4-3
4-4
4-6
4-7
4-8
4-9
4-10
4-11
4-11
4-12
4-12
4-13
4-13
4-14

4.2 Laying Out a Document.
4.2.1
Chapters and Appendixes .
4.2.2
Sections.
4.2.3
Running Heads.
4.2.4
Pagination.

4-15
4-16
4-16
4-18
4-19

4.3
4.3.1
4.3.2
4.3.3

4-19
4-20
4-21
4-23

Processing DSR Files.
Producing a Table of Contents.
Producing an Index.
Printing Output Files .

Contents

5.1
5.1.1
5.1.2
5.1.3

Data Storage .
Character Data.
Numeric Data.
Logical Data.

5-1
5-3
5-5
5-6

5.2
5.2.1
5.2.2
5.2.3
5.2.4

Expressions.
Character Expressions.
Numeric Expressions .
Logical Expressions .
Combined Operations and Precedence.

5-7
5-7
5-9
5-11
5-12

Chapter 5 Data Representation

5.3

Lexical Functions.

5-13

5.4
5.4.1
5.4.2
5.4.3

Date and Time.
Absolute Time.
Delta Time.
Absolute and Delta Time Combinations .

5-14
5-14
5-15
5-15

5.5
5.5.1
5.5.2
5.5.3
5.5.4
5.5.5

Symbols.
Creation and Deletion.
Symbol Access Control.
Symbol Substitution.
Substring Substitution.
Use of Symbols.

5-16
5-17
5-18
5-18
5-20
5-21

Chapter 6 Command Procedures
6.1

Format.

6-2

6.2
6.2.1
6.2.2

Execution .
Nesting Command Levels.
Exiting from Command Procedures.

6-2
6-3
6-3

6.3
6.3.1
6.3.2
6.3.3
6.3.4

Passing Data .
Using Parameters To Pass Data.
The INQUIRE Command.
The READ Command.
Obtaining Data from SYS$INPUT.

6-4
6-4
6-6
6-7
6-7

6.4

Returning Data.

6-8

6.5
6.5.1
6.5.2
6.5.3

Displaying Data .
Displaying Literals and Symbols.
Displaying Text.
Displaying Files.

6-9
6-9
6-10
6-10

Contents

6.6
Inputting and Outputting Data from Files (File I/O) ....
6.6.1
Writing to a File .
6.6.2
Reading from a File.
6.6.3
Modifying a File .
6.6.3.1
Minor Modifications.
6.6.3.2
Major Modifications.
6.6.4
Handling I/O Errors.

6-10
6-10
6-12
6-13
6-13
6-15
6-16

6.7
Using Logic to Control the Flow of Execution.
6.7.1
Designing Complicated Command Procedures.
6.7.2
Coding Complicated Command Procedures.
6.7.2.1
Conditional Code.
6.7.2.2
Case Statements.
6.7.2.3
Loops.
6.7.2.4
Subroutines .
6.7.3
Testing and Debugging.

6-16
6-16
6-18
6-19
6-20
6-21
6-23
6-25

6.8
6.8.1
6.8.2
6.8.3

Handling Errors and CTRL/Y Interrupts.
The ON Command.
The SET [NO]ON Command.
CTRL/Y Interrupts.

6-28
6-28
6-29
6-30

6.9

Cleanup Operations.

6-30

Chapter 7 Accounts and Security
7.1
7.1.1

User Accounts .
User Authorization File.

7-1
7-1

7.2
Protection.
7.2.1
UIC-Based Protection.
7.2.1.1
User Identification Code .
7.2.1.2
Ownership and Access Categories.
7.2.1.3
Protection Masks.
7.2.1.4
Securing User Data and Devices .
7.2.2
ACL-Based Protection.
7.2.2.1
Object Types.
7.2.2.2
Identifiers.
7.2.2.3
Access Control Entries (ACE) .
7.2.2.4
IDENTIFIER ACEs.
7.2.2.5
Rights List.
7.2.2.6
DEFAULT-PROTECTION ACEs.
7.2.2.7
ALARM-JOURNAL ACEs.
7.2.3
Protection of Files.
7.2.3.1
Default File Protection.
7.2.3.2
Explicit File Protection.

7-1
7-2
7-3
7-4
7-5
7-5
7-6
7-6
7-7
7-8
7-8
7-9
7-10
7-10
7-11
7-11
7-12

Contents

Protection of Directories.
Protection of Mail Files.
Protection of Disk Volumes.
Protection of Devices.
Displays of Ownership and Protection .

7-12
7-12
7-13
7-13
7-14

7.3 Creating and Deleting ACLs.
7.3.1
Using the SET ACL Command.
7.3.2
ACL Editor.
7.3.2.1
Using Prompts.
7.3.2.2
Moving the Cursor.
7.3.2.3
Entering and Deleting Data.
7.3.2.4
Processing an ACE.

7-14
7-15
7-16
7-18
7-18
7-19
7-20

7.2.3.3
7.2.3.4
7.2.4
7.2.5
7.2.6

Appendix ACL Access Control Lists
ACL.l

Format of Access Control Entries.

ACL-1

ACL.2

EDIT/ACL Command.

ACL-4

ACL.3
ACL.3.1
ACL.3.2
ACL.3.3

ACL Editor Commands.
Keypad Diagram .
Keypad Commands.
Control Keys.

ACL-6
ACL-6
ACL-7
ACL-15

ACL.4

DCL Commands That Affect ACLs.

ACL-15

Appendix CHAR Character Sets
CHAR.l

ASCII Character Set.

CHAR-1

CHAR.2

ASCII and DEC Multinational Character Set
Tables .

CHAR-2

CHAR.3

DEC Multinational Character Set.

CHAR-5

Appendix DCL DCL Commands
Appendix DSR Digital Standard Runoff
DSR.l

DCL Commands for Invoking DSR.

DSR-1

DSR.2

DSR Commands

DSR-10

DSR.3

DSR Flags

DSR-45

DSR.4

Index Formatting.

DSR-47

xii

Contents

Appendix EDT

EDT Editor

EDT.l

EDIT Command.

EDT-1

EDT.2
EDT.2.1
EDT.2.2
EDT.2.3
EDT.2.4

EDT Keypad Editing.
Keypad Commands.
Keyboard Keys.
VT200 Supplemental Editing Keypad.
Control Keys.

EDT-3
EDT-3
EDT-15
EDT-16
EDT-17

EDT.3
EDT.3.1
EDT.3.2

Line Editing.
Range Specifications.
Line-Editing Commands.

EDT-21
EDT-21
EDT-22

EDT.4
EDT.4.1
EDT.4.2

Nokeypad Editing .
Text Entities.
Nokeypad Commands.

EDT-53
EDT-53
EDT-55

Appendix ESC

Escape Sequences

ESC.l

Moving the Cursor.

ESC-2

ESC.2
ESC.2.1
ESC.2.2

Setting Character Sets and Characteristics.
Specifying Character Sets.
Specifying Display Characteristics.

ESC-2
ESC-3
ESC-6

ESC.3

Erasing the Screen.

ESC-6

ESC.4

Creating a Scrolling Region

ESC-7

ESC.5

Setting Terminal Characteristics.

ESC-7

ESC.6

Setting Keypad Characteristics.

ESC-8

Appendix EXP

Expressions

Appendix KEY Terminal Keys
KEY.l

VT200 Terminal Series

KEY-1

KEY. 2

VT100 Terminal Series

KEY-2

Contents

Appendix LEX

xiii

Lexical Functions

Appendix MAIL MAIL

Index

MAIL.l

DCL Command.

MAIL-1

MAIL.2

Interactive Mail Utility.

MAIL-3

MAIL.2.1

MAIL Commands.

MAIL-3

MAIL.3
MAIL Keypad.
MAIL.3.1
MAIL Keypad Diagram.

MAIL-35
MAIL-35

MAIL.3.2

MAIL-36

MAIL Keypad Commands

Preface
This manual is an overview of the general use of the VAX/VMS operating system. It
contains information on: logging into the system and using the terminal; using DCL,
a command language that gives you interactive and batch access to the system; using
MAIL, an electronic mail utility; using the file system and disk devices; using EDT,
the default screen editor; writing command procedures, special files that combine
DCL commands and provide programlike capabilities; and formatting text with
DIGITAL Standard Runoff. For the most part, the chapters provide guidelines for
performing various tasks, while the appendixes contain the component specifications.
Most of the information found in the appendixes can also be obtained from the
system with the HELP command and can be found in outline form in the VAX/VMS

Mini-Reference.

Conventions Used in This Document
Conventions

Meaning

RETURN key

The RETURN key is not shown in formats and examples.
Assume that you must press RETURN after typing a command
or other input to the system unless instructed otherwise.

CTRL key

The word CTRL followed by a slash followed by a letter
means that you must type the letter while holding down the
CTRL key. For example, CTRL/B means hold down the CTRL
key and type the letter B.

Lists

When a format item is followed by a comma and an ellipsis
(,...), you can enter a single item or a number of those items
separated by commas. When a format item is followed by
a plus sign and an ellipsis (+...), you can enter a single item
or a number of those items connected by plus signs. If you
enter a list (more than one item), you must enclose the
list in parentheses. A single item need not be enclosed in
parentheses.

Optional items

An item enclosed in square brackets ([ ]) is optional.

xvi

Preface

Conventions

Meaning

Key Symbols

In examples, keys and key sequences appear as symbols, such
as fPF2l and |ctrl/Z| .

Ellipses

A vertical ellipsis indicates that part of the format or example
is missing.

Delete Key

The key on the VT200 series terminal keyboard that performs
the DELETE function is labeled <2] . Assume that DELETE
in text and examples refers to both the VT100 and VT200
series delete keys.

Examples

Examples show both system output (prompts, messages, and
displays) and user input. User input is printed in red.

Chapter 1
Interaction with the System
VAX/VMS is an interactive system. While you are logged in, you and the system
conduct a dialogue: you enter a command, the system responds, you respond, and
so on.

1.1

Logging in to the System

To log in to your system:
1.

Turn on your terminal.

Press the RETURN key.

You will be prompted for your USERNAME. Enter your user name and press
RETURN. You will then be prompted for your PASSWORD as follows:
PASSWORD:

Type your password and press RETURN. The password is not shown on the screen.
If the password is correct, you are logged in (unless a second password has been set,
in which case another PASSWORD prompt appears). If the password is incorrect,
you receive the message "User authorization failure" and are not logged in.
You can establish, change, or delete a password using the SET PASSWORD
command, as shown in the following example. The passwords you type are not
shown on the screen.
$ SET PASSWORD
Old password:
New password:
Verification:

To establish a password, press RETURN when prompted for the old password, and
then enter the new password when prompted for it. To delete a password, enter the
old password at the prompt for the old password, and then press RETURN when
prompted for the new password and verification.

1-2

Interaction with the System

If none of these prompts ($, PASSWORD:, or USERNAME:) appears when you press
RETURN, a system password may be required to log in to your system. If you know
the system password, type it and press RETURN. If you do not know it, see the
person in charge of your system.
If you are using a turnkey, or captive, account, you are running a user program, not
the complete VAX/VMS operating system. Typically, you cannot reset the password
or use CTRL/Y from a turnkey account.
When the DCL prompt appears, you are logged in to the system at DCL command
level. Your current default device and directory are the login defaults established by
the system manager. By default, the DCL prompt is a dollar sign ($).
When you log in, the VAX/VMS system searches for your login command procedure.
(A command procedure is a file containing DCL commands that are executed when
the file is invoked; see Chapter 6.) Typically, your login command procedure
is in a file named LOGIN.COM in your default directory. If a login command
procedure exists, the system executes it before displaying the DCL prompt. Your
login command procedure should contain any DCL command that you want executed
each time you log in to the system.

1.1.1 Automatic Login
Automatic login occurs when a terminal is associated with an account. To log in
on a terminal that is associated with an account, turn on the terminal and press the
RETURN key. Either the DCL or password prompt appears. If the DCL prompt
appears, you are logged in. If the password prompt appears, type the password of
the account associated with the terminal and press the RETURN key (the password
is not shown on the screen). You are logged in to the system at DCL command
level. Your current default device and directory are the login defaults for the account
(typically, a top-level directory on DISKI:). With automatic login enabled, the use of
the terminal is restricted to the associated account.

1.1.2 Dialing in
Dialing in allows you to communicate with your system by telephone. To dial in to
your system, you need the following items:
•

Modem (or data set)—The modem is a piece of hardware that is independent of
the VAX/VMS system. The user's manual that comes with the modem should
describe how to connect the modem to a telephone line and a terminal.

•

Terminal—You cannot dial in unless the baud rate of the terminal agrees with
the baud rate of the modem and the modem terminal characteristic is set. To set
the baud rate for a VT200 series terminal, select the "Comm" category in the
Set-Up Directory. To set the baud rate for a VT100 series terminal, use SET-UP

Interaction with the System

1-3

B. To set the modem characteristic, use the DCL command SET TERMINAL
/MODEM. If your terminal has the MODEM characteristic set (the DCL
command SHOW TERMINAL lists the terminal characteristics set for your
terminal), typing the SET TERMINAL/NOMODEM command causes the
VAX/VMS operating system to log you out.
•

Manual login account—If your account is set up for automatic login, you cannot
dial in to it. Either change the account to a manual login account (one where
you must type your user name) or use a different account.

•

Telephone number for the system—To dial in, you must know the telephone
number for your system. Ask the system manager if you do not know the
telephone number.

Once the terminal is receiving the signal through the telephone line, follow the
conventions your site has instituted for remote login. When communication is
established, your system should respond with the prompt appropriate to your
account. Note that passwords should be required for all dial-up accounts to ensure
security; that is, you should not allow dial-up accounts with null passwords.

1.1.3 Logging in over the Network
Once you are logged in to your system, you can use the SHOW NETWORK
command to determine whether your system is set up as a nonrouting node or a
routing node.
•

Nonrouting (end) node—A nonrouting node can receive data addressed to itself
and send data to other nodes. End nodes do not send or receive information
about network configurations.

•

Routing node—A routing node can receive data addressed to itself and send data
to other nodes. In addition, routers can receive data addressed to other nodes
and forward that data to the appropriate node. A router receives information
about network configurations and maintains a database to keep track of all nodes
in the network.

To obtain a list of the remote systems to which you have access, use the SHOW
NETWORK command. If your system is a router, the SHOW NETWORK display
lists the nodes.

VAX/VMS Network status for local node 161 BEAR on 14-N0V-1986 10:05:51
Node
160
161
21
41
1

ALPHA
BEAR
CUP
DAN
EBONY

Links

Cost

Hops

Next Hop to Node

0
0
0
0
0

0
8
18
18
18

0
1
2
2
2

(Local)
UNA-0
UNA-0
UNA-0
UNA-0

->
->
->
->
->

160
161
21
41
1

ALPHA
BEAR
CUP
DAN
EBONY

Total of 6 nodes.

If your system is a nonrouter, the SHOW NETWORK display does not contain the
network information.
$ SHOW NETWORK
VAX/VMS Network status for local node 160 ALPHA on 14-N0V-1986 10:06
This is a nonrouting node, and does not have any network information.
The designated router for ALPHA is node 161 BEAR.

If you have an account on the router system, you can log in and use the SHOW
NETWORK command to examine the network. Otherwise, you must find out about
your network by asking the person in charge of your system.
Each system (node) in a network is linked to one or more remote nodes, as shown:

ZK-1741-84

Interaction with the System

1-5

1.1.3.1 Access and Login
To access a remote node, use the SET HOST command. If the network link cannot
be established, you receive an error message. Otherwise, you can log in using the
remote system's login procedure. The following example assumes that you are
accessing a VAX/VMS system.
$ SET HOST EBONY
USERNAME: RIGBY
PASSWORD:
$
If you attempt to gain access using invalid access information, the host system
responds with the message "User authorization failure." If you want to try accessing
the remote node again, press RETURN and you will again be prompted for a user
name and password. If you want to abort the procedure, enter CTRL/Y twice as
described in Section 1.1.3.2.
For more convenient access to frequently used remote nodes, you can create a
command procedure for logging in. Invoking the following command procedure
accesses the USER account on the system named EBONY.
$ ! EBONY.COM
$ !
$ ! Log into EBONY::USER
$ SET HOST EBONY
USER
If the USER account has an associated password, the password prompt appears. For
security reasons, you should not put passwords into command procedures or any
other files.
To further simplify access to the remote node, define a symbol to invoke the
command procedure. The following symbol definition, which can be placed in
your login command procedure, allows you to access the USER account on EBONY
by typing EBONY (EBONY.COM is located in DISK1:[USER]):
$ EBONY == "GDISK1:[USER]EBONY"
Once logged in on a remote system, you can use that system's resources to log in to
another remote node.
The HOPS entry of the SHOW NETWORK display gives the number of nodes
needed to carry your data to the remote node listed. For example, the SHOW
NETWORK display typed on node ALPHA (see Section 1.1.3) shows one hop for
node BEAR and two hops for each of the other nodes. Multiple hops does not mean
that you must log in to each intermediate node. DECnet-VAX will make all the
connections for you. However, the data you type and the responses of the remote
system must pass through each node used to establish the link. Therefore, a large
FIOPS entry (greater than 3) means a slow response from the remote system.

1-6

Interaction with the System

1.1.3.2 Terminating a Remote Session
You can terminate a remote session in two ways:
•

Normally—Use the remote system's logout procedure (for example, on a
VAX/VMS system, use the LOGOUT command).

•

Abnormally—Press CTRL/Y twice. The host system should respond with
the question, "Are you repeating *Y to abort the remote session?" Answering
Y (uppercase or lowercase) aborts the remote session. This method works
regardless of the system running on the remote node.

When you terminate a remote session, the message "%REM-S-END, control returned
to node _NODENAME::" is displayed and you are returned to the calling system.
If DECnet-VAX has made intermediate connections for you and one of the
intermediate systems goes down, DECnet-VAX either attempts to reroute the
connection or waits for a few seconds to determine whether the system will recover.
If DECnet-VAX is able to recover the connection, the interruption may be brief
enough to occur without your noticing it or it may last as long as 60 seconds. If
DECnet-VAX cannot recover the connection, the remote session is terminated and
the message "Path lost to partner" is displayed.

1.1.4 Logging out of the System
When you finish using the system, you should log out. To log out, enter the
LOGOUT command.
$ LOGOUT
USER logged out at 14-DEC-1986

12:42:48.12

To find out how much time you spent at the terminal (elapsed time), how much
computer time you used (charged CPU time), and other accounting information, you
can include the /FULL qualifier to the LOGOUT command.
$ LOGOUT/FULL
USER logged out at 14-DEC-1986

12:42:48.12

Accounting information:
Buffered I/O count:
8005
Direct I/O count:
504
Page faults:
1476
Charged CPU time:0 00:00:50.01

Peak working set size:
212
Peak virtual size:
770
Mounted volumes:
0
Elapsed time:0 02:27:43.06

Interaction with the System

1-7

1.2 Using the Terminal
On an interactive terminal, you send information to the system using the terminal
keyboard, and the system displays information for you using the terminal screen. If
you are using a turnkey account, a user program processes the data you enter rather
than allowing the VAX/VMS operating system to do the processing. The following
discussion assumes that you are using the VAX/VMS system.

1.2.1 Entering Text
Pressing a key, or combination of keys (plus RETURN) on the keyboard sends the
ASCII value of the key(s) to the system. The system responds to data keys (letters,
numbers, and punctuation) by echoing (displaying the characters that are typed) and
storing the characters. Echoing does not occur as a direct result of your pressing
the key (unless you are in local mode), but as a result of the system writing the
character to your terminal. You can turn echoing off by entering the command SET
TERMINAL/NOECHO and turn it back on by entering SET TERMINAL/ECHO.
Enter text through the data keys on the main keyboard and, if the SET TERMINAL
/NUMERIC-KEYPAD command is in effect (rather than SET TERMINAL
/APPLICATION—KEYPAD), through the numeric keypad to the right (excluding
the PFn keys). If the SET TERMINAL/ APPLICATION-KEYPAD command is in
effect, you can define the keys of the numeric keypad for other uses, but you cannot
use them to enter numbers and punctuation marks.
The data keys are supplemented by several keys, including SHIFT and RETURN.
Keys that allow you to edit what you are typing are described in Section 1.4.7.
Control keys (entered by pressing the key labeled CTRL and, at the same time, a
data key), are referred to as CTRL/x, where x is the data key. Control keys are
described in sections pertaining to their functions; see Appendix KEY for a complete
list of control keys. (To pass a control character to an image rather than allowing the
system to process the character, press CTRL/V and then enter the control character.)
Function keys on the VT200 terminal are referred to as Fx, in which x is the number
associated with a particular function key. The function keys are located above the
main keyboard and are labeled FI through F20. Function keys are described in
sections pertaining to their use; see Appendix KEY for a complete list of function
keys.
If the system is not ready for your input when you enter it at the terminal, it is
stored in a special area called the type-ahead buffer. When the system is ready, it
processes your input from the type-ahead buffer and echoes it. In this way, you can
enter input before the system is ready to receive it without losing it. You can disable
the type-ahead buffer with the SET TERMINAL/NOTYPE—AHEAD command. Your
input is processed immediately, and if the system is not ready for the input, it is lost.

1-8

Interaction with the System

You can reenable the type-ahead buffer with the SET TERMINAL/TYPE—AHEAD
command. Note that certain control characters (such as CTRL/Y and CTRL/O) are
not put in the type-ahead buffer; they are processed immediately.

1.2.2 Controlling Output
You can control the formatting and movement of output on your terminal.

1.2.2.1 Suspending/Resuming Terminal Display
You may need to stop a lengthy screen display so that you can read it before
it disappears off the top of the screen. Use the FI key on VT200 terminals (the
NO SCROLL key on VT100), or CTRL/S, to stop output to the screen. To resume
output, press the FI (NO SCROLL) key a second time, or press CTRL/Q. The display
continues from the point where you halted it. The FI (NO SCROLL) key works only
if AUTO XON/XOFF is enabled; see Section I.3.I.3.
If you want to skip over portions of the text being displayed, use CTRL/O.
Pressing CTRL/O does not suspend output but suspends the echoing of the output.
Therefore, when you press CTRL/O a second time, echoing resumes at the current
position in the text rather than from the point where you suspended the text.

1.2.2.2 Formatting Screen Output with Escape Sequences
An escape sequence is a code consisting of an escape character followed by one or
more data characters. Escape sequences allow you to send formatting and other
control commands to the terminal. However, if escape sequences are sent to a
device that does not support them (for instance, a hardcopy terminal), the results
are unpredictable. Escape sequences must be specified exactly as described; case
(uppercase or lowercase) and punctuation are significant. Appendix ESC describes
the VT200 and VT100 escape sequences.
You can send escape sequences to a terminal in three ways:
•

Command procedure—Use an editor to create a command procedure that equates
the low-order 8 bits of a symbol to 27, the ASCII value of the ESC character,
and then writes escape sequences and text to the terminal. Use the symbol
rather than the escape character itself so that you can examine the file if you
accidentally send it to a device that does not support escape characters. When
executed, the following command procedure writes the word BOX in bold
characters inside a box drawn with special graphic characters (Appendix ESC
describes the graphic character set). The three apostrophes enclosing the symbol
ESC force the VAX/VMS system to translate the symbol; see Section 5.5.3 for
more information about symbol substitution.

Interaction with the System

1-9

BOX.COM
$
$
$ ! define the escape character
$ ESC [0,8] = #/,XlB

$
$
$
$
$
$
$
$

WRITE
WRITE
WRITE
WRITE
WRITE
WRITE
WRITE

SYS$OUTPUT
SYS$OUTPUT
SYSSOUTPUT
SYS$OUTPUT
SYSSOUTPUT
SYSSOUTPUT
SYSSOUTPUT

»’’ESC*(0"
"*’ESC*[10;35Hlqqqqqk"
"* *ESC *[11;35Hx’’ESC’[ll;41Hx"
"* * ESC *[12;35Hmqqqqqj"
"’'ESC *(B"
"”ESC’ [11;37H''ESC'[7mB0X"
"’’ESC’[OmM

In this example, the escape sequences were written in different statements for
clarity. However, lists of escape sequences can be on one or multiple lines,
provided that no escape sequence is split between two lines.
•

Text file—Use an editor to create a file containing escape sequences and text.
(Insert an escape character into the text by pressing CTRL/[ on VT200 terminals
or the ESC key on VT100 terminals twice.) Use the TYPE command to send the
file from the system to the terminal. Since a file containing escape characters
could mistakenly be sent to a device that does not support escape sequences, this
technique is not generally recommended.

•

LOCAL mode—Use the set-up feature (see Section 1.3) to put your terminal in
LOCAL mode. In local mode, characters are sent directly to the screen, not to the
system. For example, if you put the terminal in LOCAL mode, enter the escape
character CTRL/[ and then type [2J, the screen is erased. The escape sequence
<ESC> [2J is not echoed.

Most commonly, escape sequences are used to enhance the appearance of the text
when it is displayed or to make use of the graphic character set.
The terminal attribute Escape determines how the VAX/VMS system interprets the
escape character; it does not affect the execution of escape sequences. If Escape is
enabled, the system recognizes the escape character as the beginning of an escape
sequence, waits for the control characters that should follow, and interprets the
entire sequence as a line terminator. If Escape is disabled, the system recognizes the
escape character as a line terminator and echoes a dollar sign to the terminal. Since
a program can override the Escape attribute, even when you have disabled Escape
it may appear to be enabled. (Enable and disable Escape with the /[NOJESCAPE
qualifier of the SET TERMINAL command.)

1-10

Interaction with the System

1.3 Setting the Terminal’s Physical Attributes
You can set the physical attributes for your terminal by using the set-up feature
for your particular terminal. The DCL command SET TERMINAL sets the logical
attributes for your terminal and affects some of its physical attributes. See
Appendix DCL for a description of the SET TERMINAL command.

1.3.1 VT200 Series
Set-up on the VT200 series terminal is based on several set-up screens that you can
select from the Set-Up Directory. To enter Set-Up, press the F3 keyboard key; the
Set-Up Directory will be displayed on the lower third of your terminal screen.
To set physical attributes on the VT200 series terminal, you move the cursor
(displayed in reverse video) from field to field using the arrow keys.

Set-Up Directory

VT240 VI.0

Default ] Exit

Printer: None

To exit from Set-Up, either press the F3 key or select the Exit field in the Set-Up
Directory (as explained in Section 1.3.1.2) and then press the ENTER keypad key.
Each set-up screen contains a screen title, a terminal identifier, a firmware version
number, a status line, and attribute fields. To modify an attribute:
1.

Position the cursor—Use the arrow keys to position the cursor over the field
containing the attribute you want to change.

Press the ENTER keypad key—The ENTER key changes the setting of each field.

Interaction with the System

1-11

There are three types of fields, each of which responds differently when the ENTER
key is pressed.
Action field

An action field has only one value and is activated by pressing the
ENTER key.

Parameter field

A parameter field has two or more values. The next value is
selected by pressing the ENTER key.

Text parameter field

In text parameter fields, direct entry of text is accomplished by
typing the text or number you want entered on the status line at
the bottom of your screen. Pressing the ENTER key completes the
operation.

1.3.1.1 The Set-Up Directory
The top row in the Set-Up Directory consists of eight action fields. If you move the
cursor to one of these action fields and press ENTER, another set-up screen (Display,
General, Comm, Printer, Keyboard, Tab, Graphics, or Telephone) will be displayed
on your terminal.

NOTE:

The Telephone field only appears in the Set-Up Directory screen when the
VT200 series Integral/Modem option is installed.
The second row contains one parameter field and five action fields.
•

On Line/Off Line (parameter) field—Determines whether your terminal is
connected to the VAX/VMS operating system or whether data entered is sent
directly to the terminal screen.

•

Clear Display (action) field—Clears the terminal screen.

•

Clear Comm (action) field—Clears the communication lines; aborts any escape
sequence, control sequence, or DCS processing; clears the keyboard buffers;
clears the receive buffer; sends XON to the host port; resets XOFF received flags
on both the printer and host ports; and takes the printer out of controller mode.

•

Reset Terminal (action) field—Resets many internal terminal features; however,
this action does not affect communication and user-defined keys.

•

Recall (action) field—Replaces all the existing set-up characteristics with the
saved values and clears the terminal screen. Note that Recall causes a disconnect
to occur.

•

Save (action) field—Saves the current set-up features from the Set-up screen.

The third row of the Set-Up Directory contains two parameter fields and two action
fields.
•

Set-Up=[language] (parameter) field—Allows you to choose the language
in which you want the Set-Up attributes displayed. This field takes effect
immediately.

1-12

Interaction with the System

•

[National] Keyboard (parameter) field—Allows you to select correct terminal
operation for the national keyboard you are using.

•

Default (action) field—Replaces all current set-up features with the factory
default settings. The terminal screen is cleared and the cursor is returned to the
upper left corner of the screen. Note that Default causes a disconnect to occur.

•

Exit (action) field—Exits from Set-Up and returns the terminal to On-Line or
Local, depending on which feature is set.

1.3.1.2 Changing Attributes with Set-Up
To change a terminal attribute that is in the Set-Up Directory, select the attribute
field with the arrow keys. To change an attribute that is located in another screen,
select the appropriate screen and press ENTER. When the selected screen appears,
select the appropriate field. The following table lists the attributes available in the
Set-Up Directory and the eight other set-up screens:

Set-Up Directory

Display Set-Up

General Set-Up

Display Set-Up

To Next Set-Up

General Set-Up

To Directory

Communications Set-Up

80/132 Columns

Terminal Mode

Printer Set-Up

Interpret/Display Controls

VT100 ASCII/UK

Keyboard Set-Up

Auto Wrap

UDK Lock

Tab Set-Up

Smooth/Jump Scroll

User Features Lock

Graphics Set-Up

Light/Dark Text/Screen

Keypad Mode

Telephone Set-Up

Display Select

Cursor Key Mode

On Line/Local

Text Cursor

New Line

Clear Display

Block/Underline Cursor

Clear Communications
Reset Terminal
Recall Saved Attributes
Save Attributes
Set-Up Language
Keyboard Language
Set Factory Defaults
Exit Set-Up

Interaction with the System

Communications Set-Up

Printer Set-Up

Keyboard Set-Up

To Next Set-Up

To Directory

Transmit Speed

Transmit/Receive Speed

Typewriter/D.P.

Receive Speed

Printer to Host Mode

Caps/Shift Lock

XOFF

Print Mode

Auto Repeat

Data-Bits Parity

XOFF

Keyclick

Stop Bits

Data-Bits Parity

Margin Bell

Local Echo

Stop Bits

Warning Bell

1-13

Host Port Selection

Text Print Extent

Break

Disconnect

Printed Data Type

Auto Answerback

Transmit Rate Limit

Print Terminator

Answerback Message
Conceal Answerback

Tab Set-Up

Graphics Set-Up

Telephone Set-Up

To Next Set-Up

To Directory

Clear All Tabs

4010 CR Effect

Auto Answer

Set 8 Column Tabs

4010 Line Feed Effect

Telephone Number A

Tab Fields and Ruler

4010 GIN Terminator

Conceal A

4010 DEL as Lo Y

Telephone Number B

Macrograph Lock

Conceal B

Graphics Cursor
Compressed/Expanded Print

For complete information about your VT200 series terminal and its set-up features,
refer to your terminal owner's manual.
For example, to change the background color of the screen, enter the Set-Up
Directory by pressing the F3 key. Use the arrow keys to select the Display field
(this field should be the current field when you enter the Set-Up Directory), and
press the ENTER key. Once in the Display Set-Up screen, select the Light Text, Dark
Screen/Dark Text, Light Screen field (third field in the second row), and press the
ENTER key. The screen responds immediately by setting the text and screen tones.
By default, all the changes you make are temporary—the attributes remain until you
reset the terminal or turn it off. To make the changes permanent, select the Save
field in the Set-Up Directory and then press the ENTER key. The word "Done" will
appear on the status line at the bottom of the Set-Up screen indicating that your
terminal attributes have been saved.

1-14

Interaction with the System

1.3.1.3 Critical Attributes
Make sure the following critical attributes are set correctly:
•

Baud Rate—In the Communications Set-Up screen are two fields shown as
Transmit^_and Receive=_These fields indicate the transmit
and receive baud rates for the terminal. Move the cursor to either of these fields
and press the ENTER key repeatedly to move through the available baud rates
in the following order: 75, 110, 150, 300, 600, 1200, 2400, 4800, 9600, 19,200.
Both the Transmit_and the Receive=_fields should be set
to 9600 if your terminal is directly connected to the VAX/VMS system. Dial-in
terminals are usually set at 1200 or 300 baud.

•

XOFF Point—Also located in the Communications Set-Up screen is an XOFF
field. This field determines the XOFF point or disables the automatic XON/XOFF
flow control. Move the cursor to the XOFF field (first field in the second row),
and press the ENTER key to move through the XOFF values in the following
order: XOFF at 64, XOFF at 256, XOFF at 512, XOFF at 1024, No XOFF. The
XOFF field should be set to XOFF at 64.

1.3.2 VT100 Series
To change the physical attributes of a terminal in the VT100 series, enter SET-UP
mode by pressing the SET-UP key. The terminal display indicates that you are in
SET-UP mode A. To enter SET-UP mode B, press the SET-UP A/B key (the key
labeled 5 at the top of the keyboard). To exit from SET-UP mode, press the SET-UP
key.
By default, the changes you make are temporary—the attributes remain set until you
reset the terminal or turn it off. To make the changes permanent, press SHIFT/S
before exiting from SET-UP mode. To set the terminal to your permanent attributes,
enter SET-UP mode (either A or B) and press the RESET key (number 0).

Interaction with the System

1-15

1.3.2.1 SET-UP Mode A
Pressing the SET-UP key invokes the SET-UP A display:

SET-UP A
TO EXIT PRESS "SET-UP"

12345B7890Cg^CTPl^-lsI»3l

t
2345fi7Rflngg^glif

734EB7R9ng¥qcg¥^=V^^I»]

Use SET-UP mode A to change the following attributes:
•

Columns—The numbers across the bottom of the screen in SET-UP mode A
mark the columns. The screen can be either 80 or 132 columns wide. To change
the number of columns on the screen, press the 80/132 COLUMNS key (number
9): if the screen held 80 columns, it now holds 132; if the screen held 132
columns, it now holds 80. Changing the number of columns on the screen does
not change the number of characters the system places on a line. Use the DCL
command SET TERMINAL/WIDTH to specify the number of characters that the
system writes on a single line.

•

Tabs—You can set a tab in any column on the terminal screen. A tab is indicated
by a "T" placed above the column number at the bottom of the screen in SET-UP
mode A. To set or clear a tab, use the left and right arrow keys to position the
cursor in the proper column and press the SET/CLEAR TAB key (number 2). If
the column already has a tab, pressing the SET/CLEAR TAB key clears it; if the

Interaction with the System

1-16

column does not have a tab, pressing the SET/CLEAR TAB key sets one. To
clear all the tabs, press the CLEAR ALL TABS key (number 3).
The tabs you set in SET-UP can be used to format information in files created
with the DCL command CREATE. However, if you use an interactive editor,
you must use the tab commands provided by the editor since interactive editors
ignore the tabs set in SET-UP.

1.3.2.2 SET-UP Mode B
To invoke SET-UP B, first press the SET-UP key and then the SET-UP A/B key (the
key labeled 5 at the top of the keyboard):

ESC

'»

SCROLL

SHIFT

CTS
OSR
INSERT
LI
o
o
o
o
TOGGLE TRANSMIT RECEIVE 80/132
I/O
SPEED
SPEED COLUMNS RESET

rrrr

2lJjlIHEHLDE

IQ W
A

&PKS

KBD
LOCKED
o
SET-UP
A/B

LINE OFF LINE
)
o
SET/
CLEANS1 ALL ON/OFF
CLEAR TAB
TAf3S
LINE

SET-UP

S
^

E
D

R
F

T | Y | U |
G

| O

*
□0EBB

P |

XCVBNM<:>

PF4
SHE

{

| DELETE |

SHE

l
1
SHIFT

1
^
LINE
FEED

l
l

HHH

•

Interaction with the System

1-17

Each of the Is and Os contained in the four boxes on the lower left corner of the
display is associated with an attribute, as shown in the following figure. To change
one of these attributes:
1.

Position the cursor—Use the left and right arrow keys to position the cursor over
the number associated with the attribute you want to change.

Press the TOGGLE 1/0 key (number 6)—The number below the cursor changes:
if the number is 0, it becomes 1; if the number is 1, it becomes 0.

For example, to change the background color of the screen, enter SET-UP mode B,
position the cursor over the third number in the first box, and press the TOGGLE
1 /0 key (number 6).
A number of the attributes you can change in SET-UP mode B affect the operation
of the terminal. In the following figure, the proper settings for these attributes are
marked with an asterisk.
■ SCROLL <“=

- | #3l'j (SHIFTED) j

■ AUTOREPEAT <

- WRAP AROUND {

■ SCREEN (° “

NEW LINE ^

- CURSOR 1 ° =

INTERLACE <

□

rxij]
AUTO XON XOFF •

■ POWER <

(OPTIONAL
DISPLAY
FOR CUSTOM
FUNCTIONS)
, r T T T -)

R SPEED |

= 60 I- 50 Hz

(o = V
- ANSI/VT52 r = /1

(0 =
- BITS PER CHAR < 1

(0-0
- KEVCLICK < , _ 0

- PARITY

- MARGIN BELL < °

- PARITY SENSE

m OFF *
ON

You should make sure that the baud rates for your terminal are set correctly. In the
lower right comer of the SET-UP mode B display are two numbers labeled T SPEED
and R SPEED. These numbers indicate the transmit and receive baud rates. Use
the TRANSMIT SPEED and RECEIVE SPEED keys (numbers 7 and 8, respectively)
to set these rates. Pressing either TRANSMIT SPEED or RECEIVE SPEED causes
the terminal to move through the baud rates in the following order: 50, 75, 110,
134.5, 150, 200, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 9600, 19200. If your
terminal is connected directly to the VAX/VMS system, both the transmit and receive
speeds should be set at 9600. (Some modems require a different baud rate; see
Section 1.1.2.)

1-18

Interaction with the System

1.4 Commands and Utilities
The DIGITAL command language (DCL) provides you with a direct connection to
the VAX/VMS system and the software running on VAX/VMS. In response to the
DCL prompt (which is initially a dollar sign), you enter a command name followed
by any desired parameters and qualifiers. DCL interprets the command, and either
executes it directly (a so-called "built-in" command) or calls an appropriate program
to execute it, passing to that program any parameter and qualifier information. (Most
of the commands not given in the list of built-in commands are in this category.)
Some DCL commands invoke utilities that themselves accept interactive subcom¬
mands. You then work interactively with the program by entering subcommands
and other information in response to the utility's command prompts. You continue
to work with the utility until you exit from it and return to DCL command level. The
MAIL command falls into this category.
A program that is associated with a command (a command image) can be DIGITALor user-supplied. The built-in commands and the commands that execute system
programs are supplied and supported by DIGITAL as part of the operating system.
Appendix DCL contains complete descriptions of each of these commands.
Built-in commands:
ALLOCATE

ASSIGN

ATTACH

CALL

CANCEL

CONNECT

CONTINUE

CREATE/LOGICAL _N AME —TABLE

DEALLOCATE

DEASSIGN

DEBUG

DECK

DEFINE

DEFINE/KEY

DELETE/KEY

DELETE/SYMBOL

DEPOSIT

DISCONNECT

ENDSUBROUTINE

EOD

EXAMINE

EXIT

GOSUB

GOTO

INQUIRE

OPEN

READ

RECALL

RETURN

SET CONTROL

SET DEFAULT

SET KEY

SET ON

SET OUTPUT-RATE

SET PROMPT

SET PROTECTION/DEFAULT

SET UIC

SET VERIFY

SHOW DEFAULT

SHOW KEY

SHOW PROTECTION

Interaction with the System

SHOW QUOTA

SHOW STATUS

SHOW TIME

SHOW TRANSLATION

SPAWN

SHOW TIME

SUBROUTINE

WAIT

1-19

SHOW SYMBOL

WRITE
A utility is a program that provides some user service; it refers both to interactive
commands and to some complex noninteractive commands.

1.4.1 DCL Command Format
A DCL command follows the general format:

command [/command-qualifier...] [parameter[/parameter-qualifier...]]...
where command is the name of the command, command-qualifier is the name of a
command qualifier, parameter is the name of a parameter, and parameter-qualifier is
the name of a parameter qualifier. Lowercase and uppercase characters in command
and qualifier names are equivalent. Lowercase and uppercase characters in parameter
and parameter qualifier values are equivalent unless enclosed in quotation marks.
The following command line consists of the command name, a command qualifier,
and two parameters.
$ COPY/LOG FORMAT.TXT WATER.TXT
The command instructs the system to copy the file FORMAT.TXT to another file
named WATER.TXT and display (log) the status of the operation. (To implement
the command, DCL interprets the command and calls the system program
SYS$SYSTEM:COPY.EXE, passing it the qualifier and parameter information.) You
must observe the following rules in entering DCL commands:
•

Delimiters—Delimit the command name and parameters with one or more
blanks or tabs or qualifiers. Begin each qualifier with a slash (/); the slash
serves as a delimiter and need not be preceded by blanks or tabs.

•

Continuation over many lines—You can continue a command line by terminating
it with a hyphen, pressing RETURN, and entering more of the command on the
next line (although a single command line can not exceed 256 characters), as
demonstrated:
$ COPY/LOG FORMAT.TXT,WATER.TXT,SOIL.TXT _$ SAVE.TXT
The system responds to the hyphen and RETURN with the prompt string
preceded by an underscore. Note that the space delimiting command names and
parameters must be supplied (the RETURN is not treated as a delimiter).

1-20

Interaction with the System

•

Size limit—An element in a command (for example, a qualifier and associated
values) must not exceed 255 characters. The number of elements in a command
must not exceed 128. The entire command must not exceed 1024 characters after
all symbols and lexical functions are converted to their values.

•

Abbreviation—You can abbreviate a command name by truncating it if the
abbreviated name is still unique among all the DCL command names. You can
abbreviate a qualifier name if it remains unique among all qualifier names
for the same command. (For clarity, the examples in this manual do not
abbreviate commands or qualifiers.) All command and qualifier names are
unique within four characters (not counting the slash before qualifiers). The
following commands, for example, are equivalent:
$ PR/C=2 WATER.TXT
$ PRINT/C0PIES=2 WATER.TXT

In interactive mode, you will work faster if you abbreviate. The abbreviations
may feel awkward at first but you will soon get used to them. You should not
abbreviate commands in command procedures because: (1) your command
procedure will be difficult to read, and (2) the abbreviations might not be valid
after new DCL commands are added at a later date.
Other rules governing the format of commands apply mainly to their use in
command procedures (see Chapter 6).

1.4.2 Parameters
A parameter consists of a value or a list of values. You must position parameters in a
specified order within the command, as demonstrated:
$ COPY WATER.TXT FORMAT.TXT

This command causes the file WATER.TXT to be copied to FORMAT.TXT.
The following command reverses the order of the parameters, copying the file
FORMAT.TXT to WATER.TXT.
$ COPY FORMAT.TXT WATER.TXT

Specify a parameter list by separating the values with commas (in some commands,
you can use plus signs to denote concatenation of files). The following example
copies a number of files to another file.
$ COPY FORMAT.TXT,WATER.TXT,SOIL.TXT SAVE.TXT

The entire list FORMAT.TXT,WATER.TXT,SOIL.TXT constitutes the first parameter.
SAVE.TXT is the second parameter.

Interaction with the System

1-21

1.4.3 Qualifiers
A qualifier consists of a keyword, or a keyword followed by a value or list of values.
The keyword starts with a slash. Three general classes of qualifiers exist:
•

Command qualifiers—A command qualifier applies to the entire command; the
best practice is to place it after the command name (or after other command
qualifiers following the command name), although in some cases a command
qualifier can appear anywhere in the command. The following example prints
two copies each of WATER.TXT and SOIL.TXT:
$ PRINT/C0PIES=2 WATER.TXT,SOIL.TXT

•

Positional qualifiers—A positional qualifier has different meanings depending
on where you place it in the command string. If you place a positional qualifier
after the command verb but before the first parameter, the qualifier affects the
entire command string. If you place a positional qualifier after a parameter, the
qualifier affects only that parameter. In the following example, the first PRINT
command requests two copies of each 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/C0PIES=2 SPRING.SUM,FALL.SUM
$ PRINT SPRING.SUM/C0PIES=2,FALL.SUM

•

Parameter qualifiers—A parameter qualifier applies only to the parameter value
it follows. The following example prints two copies of WATER.TXT and three
copies of SOIL.TXT:
$ PRINT WATER.TXT/C0PIES=2,SOIL.TXT/C0PIES=3

Within the confines of the above rules, the relative position of qualifiers in a
command does not matter. Qualifiers take one of the following formats:
•

Positive-negative qualifiers—Positive-negative qualifiers have a value of true or
false. You do not specify a value, but indicate a true value by simply naming
the qualifier, or negate the qualifier by inserting the prefix NO. The first example
that follows puts a flag page at the beginning of the print job, while the second
example does not.
$ PRINT/FLAG.PAGE WATER.TXT,SOIL.TXT
$ PRINT/NOFLAG.PAGE WATER.TXT,SOIL.TXT

•

Value qualifiers—If the qualifier accepts a value, you specify it by appending an
equal sign and the value, as demonstrated:
$ PRINT/C0PIES=2 WATER.TXT
The /COPIES qualifier has a value of 2.

1-22

•

Interaction with the System

Lists of values for qualifiers—If the qualifier accepts a list of values, you
must enclose the values in parentheses and separate them with commas, as
demonstrated:
$ DELETE/ENTRY=(230,231) SYS$BATCH
The command deletes jobs 230 and 231 from the queue SYS$BATCH.

•

Value and positive-negative combinations—Some qualifiers combine positive¬
negative and value characteristics so that the qualifier accepts a value. The
SET TERMINAL command, for example, permits the following choices for the
/PARITY qualifier.
$ SET TERMINAL/PARITY=EVEN
$ SET TERMINAL/PARITY=0DD
$ SET TERMINAL/NOPARITY

•

Defaults—Most of the qualifiers take defaults or do not affect existing values
when they are not specified. For example, the following commands are
equivalent because the qualifiers /KEEP=1 and /NOLOG are the defaults for
the PURGE command.
$ PURGE [.MEMOS]
$ PURGE [.MEMOS]/KEEP=1/N0L0G
The following command affects only the width of your terminal screen. All the
other terminal characteristics remain the same.
$ SET TERMINAL/WIDTH=132

1.4.4 Prompts
If you omit a required parameter from a command, the system prompts you for the
parameter as demonstrated:
$ PRINT
.File:

WATER.TXT

You are also prompted for any additional parameters, required or optional.
$ ALLOCATE
.Device:
DL
.Log.Name:
ACCOUNTS.DISK
You can omit optional parameters by just pressing RETURN. On any prompt, you
can enter one or more of the remaining parameters and any additional qualifiers.
$ ALLOCATE
.Device:
DL ACCOUNTS.DISK

Interaction with the System

1-23

1.4.5 Interactive Commands
You invoke an interactive command by typing its name and pressing RETURN.
(Some interactive commands accept parameters and qualifiers on the command line.)
The command responds with a prompt, as shown:
$ MAIL
MAIL>
You can now enter subcommands recognized by that interactive command. To enter
another DCL command, you must first exit from the interactive command, usually
by typing EXIT (and pressing RETURN) or pressing CTRL/Z in response to the
command prompt.
To obtain help for an interactive command, invoke the command and then type
HELP (and press RETURN) as you would at DCL command level (see Section 1.4.8).

1.4.6 Interrupting Commands
You can interrupt the execution of a command by pressing CTRL/Y, CTRL/C, or
CTRL/T (the current program may have redefined CTRL/C or CTRL/T, in which
case the usual system actions are overridden). CTRL/T interrupts execution of the
command, displays a line of information (node name, process name, system time,
elapsed CPU time, page faults, direct and buffered I/O operations, and pages in
physical memory), and resumes execution. The following example interrupts the
copy operation to display CTRL/T information and then resumes the copy operation.
$ COPY [.MEMOS]*.* *
| CTRL/T |

BEAR::USER 16:54:17 COPY CPU=00:00:01.16 PF=241 10=47 MEM=141

NOTE:

You must enable system recognition of CTRL/T by using the DCL
command SET CONTROL=T.
CTRL/Y interrupts a command and returns you to DCL command level without
completing execution of the command.
$ COPY [.MEMOS]*.* *
| CTRL/Y |

INTERRUPT

1-24

Interaction with the System

After interrupting a command with CTRL/Y, you can:
•

Exit normally—In a normal exit, the program executes any cleanup procedures
before terminating. To terminate the program normally, enter any command that
causes a program to execute or enter the EXIT command. (If the next command
is a built-in command, the exit is delayed until a command executing a program
is entered.)

•

Exit abnormally—In an abnormal exit, the program terminates immediately. To
terminate the program abnormally, enter the command STOP. (The advantage
to using STOP over simply continuing with the next command is that STOP
suppresses any cleanup activities—for example, the display of error messages.)

•

Continue—You can continue execution of the program by entering the command
CONTINUE. Any number of built-in commands (but only built-in commands)
can be entered after CTRL/Y and before CONTINUE. The following example
interrupts the execution of the CLEANUP command procedure, sets verification,
and then continues execution of the command procedure.
$ ©CLEANUP
[CTRL/Yl

INTERRUPT
$ SET VERIFY
$ CONTINUE
CTRL/C works like CTRL/Y unless the program you are executing responds to
CTRL/C (which is a common practice).

1.4.7 Editing Command Lines
The following keys allow you to edit the current DCL command line (and the
command lines of most utilities). For some of these keys to work, the SET
TERMINAL/LINE__EDITING command must be in effect. (Enter the SHOW
TERMINAL command to display your terminal's attributes.)
VT200 Key

VT100 Key

Function

F12,CTRL/H

BACKSPACE,CTRL/H

Moves the cursor to the
beginning of the line

F14,CTRL/A

CTRL/A

Changes between SET
TERMINAL/OVERSTRIKE
and SET TERMINAL/INSERT

CTRL/B

Recalls up to 20 previously
entered commands

Interaction with the System

1-25

VT200 Key

VT100 Key

Function

CTRL/E

Moves the cursor to the end of
the line

CTRL/R

Repeats the current command
line

CTRL/U

Deletes the characters to the left
of the cursor

<31

DELETE

Deletes the character to the left
of the cursor, moving the cursor
one space to the left

F13

LINEFEED

Deletes the word to the left of
the cursor

DOWN ARROW

Recalls the command entered
after the current command

RIGHT ARROW,CTRL/F

Moves the cursor one character
right

LEFT ARROW,CTRL/D

Moves the cursor one character
left

UP ARROW

Recalls the command entered
before the current command

Command-line editing is most useful for modifying long command lines. You can
edit command lines that contain typographical errors or command lines that you
have recalled and want to modify (see Section 1.5.4 for a description of how to recall
previous command lines). For example, the following command line contains one
mistake that can be corrected more easily than retyping the entire command line.
(Where line-editing keys on the VT200 series and VT100 series terminals differ,
VT200 keys are pictured first and VT100 keys are pictured in parentheses.)
$ DILETE W0RKMAR1986:[ACCOUNTS]SMITH.DAT;3
[F12l

1 BACKSPACE]

$ DILETE W0RKMAR1986:[ACCOUNTS]SMITH.DAT;3

$ DILETE W0RKMAR1986:[ACCOUNTS]SMITH.DAT;3
E
$ DELETE W0RKMAR1986:[ACCOUNTS]SMITH.DAT;3 RETURN
This example assumes that the SET TERMINAL/OVERSTRIKE attribute is in effect
(as it is by default). The OVERSTRIKE attribute allows you to replace the incorrect
character by typing the correct character over it (replacing I with E in the preceding
example). To insert characters in the command line without simultaneously deleting
them, change the OVERSTRIKE attribute to the INSERT attribute. While you

1-26

Interaction with the System

are editing a command line, you can set the OVERSTRIKE or INSERT attributes
temporarily by entering F14 (or CTRL/A). Use the SET TERMINAL command to set
the attribute permanently for your terminal.

1.4.8 Help
To obtain online documentation for a command, enter the command HELP with the
name of the command as a parameter.
$ HELP ALLOCATE
ALLOCATE
Provides exclusive access to a device and optionally establishes a
logical name for the device.
Once a device has been allocated,
other users cannot access the device until you
specifically
deallocate it or log out.
Format:
ALLOCATE device-name[:][,...]

[logical-name[:]]

Additional information available:
Parameters Command_Qualifiers
/LOG
/GENERIC
Examples
ALLOCATE Subtopic?
If you need help, but do not know what command or system topic to specify, enter
the command HELP with the word HINTS as a parameter. Each task name listed
in the HINTS text is associated with a list of related command names and system
information topics.
$ HELP HINTS
HINTS
Type the name of one of the categories listed below to obtain a list
of related commands and topics.
To obtain detailed information on a
topic, press the RETURN key until you reach the "Topic?" prompt and then
type the name of the topic.
Topics that appear in all upper case are DCL commands.
Additional information available:
Batch_and_print_jobs
Creating.processes
Files_and_directories
System_management
HINTS Subtopic?

Command_procedures
Developing_programs
Logical.names
Terminal_environment

Contacting_people
Executing.programs
Physical_devices
User.environment

Interaction with the System

1-27

When HELP prompts you for a topic or subtopic, you can enter one of the listed
subtopics to obtain additional information (command and topic names can be
abbreviated). Alternatively, you can press RETURN to move back a level, enter
a question mark to redisplay the current text, or press CTRL/Z to exit. (You can use
HELP interactively by entering just the command HELP.)
Using wildcard characters when specifying a topic allows you to obtain various
amounts of information.

Format

Information Provided

HELP command...

The command or topic and all related information

HELP command *

All related information

HELP com*

All commands or topics beginning with the specified character(s)

1.5 Shortcuts for Entering Commands
You can use symbols, command procedures, and key definitions to simplify the
typing of command lines. In addition, you can use CTRL/B and the RECALL
command to reissue any of your last 20 command lines.

1.5.1 Symbols
Use symbols to tailor commands to suit your site conventions or personal habits.
For example, you can shorten the SHOW DEFAULT command by equating it to a
symbol.
$ SD = "SHOW DEFAULT"
Now you can issue the SHOW DEFAULT command by typing SD. If you wish to use
a symbol each time you log in, make it a global symbol (by using two equal signs)
and place the symbol definition in your login command procedure.
$ ! LOGIN.COM
$ !
$ SD == "SHOW DEFAULT"
A useful device is to equate SET DEFAULT commands for your most frequently
used directories to easily remembered symbols. For example, you might equate each
command to the name of the directory with the letter D appended.
$
$
$
$

! LOGIN.COM
!
ACC0UNTD == "SET DEFAULT W0RKDISK:[USER.ACCOUNT]"
MEM0D == "SET DEFAULT W0RKDISK:[USER.MEMO]"

1-28

Interaction with the System

1.5.2 Command Procedures
Use command procedures to combine commands. For example, if you like to
examine the contents of a directory immediately after setting your default to it,
you might set up a command procedure that issues the appropriate commands. The
command procedure for the ACCOUNT subdirectory might contain the following
commands.
$
$
$
$

! WORKDISK:[USER]ACCOUNTD.COM
!
SET DEFAULT WORKDISK:[USER.ACCOUNT]
DIRECTORY

Now you type @WORKDISK:[USER]ACCOUNTD (or @ACCOUNTD if your current
default is WORKDISK:[USER]) to change directories and view the contents of the
new directory.
Rather than write a separate command procedure for each directory, you could
write a single command procedure that would accept the name of a directory as a
parameter, change your default to the specified directory, and view the contents of
the new directory. In the following command procedure, the symbol PI is equated
to a value that you specify as a parameter when you invoke the command procedure.
$ ! WORKDISK:[USER]DIRECTORY.COM
$ !
$ SET DEFAULT ’PI*
$ DIRECTORY
To simplify the invocation of DIRECTORY.COM, you could equate DIRECTORY.COM
invocations for each of your directories to easily remembered global symbols. For
example, you might equate each invocation to the name of the directory with the
letter D appended.
$ ! LOGIN.COM
$ !
$ ACCOUNTD == "OWORKDISK:[USER]DIRECTORY WORKDISK:[USER.ACCOUNT]"
Chapter 6 discusses command procedures in greater detail.

Interaction with the System

1-29

1.5.3 Key Definitions
Use key definitions to equate a key on your terminal to a command or partial
command. To define keypad keys, issue the DCL command SET TERMINAL
/APPLICATION-KEYPAD. Then, for example, you might equate the PF1 key to
the SET DEFAULT command.
$ DEFINE/KEY PF1 "SET DEFAULT "
#/,DCL-1-DEFKEY, DEFAULT key PF1 has been defined
Now you can issue the SET DEFAULT command by pressing the PF1 key. When
you press the PF1 key, the words SET DEFAULT are entered and echoed as if you
had typed them. To complete the command, type the name of a device and/or
directory and press RETURN. (If you wish to use a key definition each time you log
in, place the key definition in your login command procedure. If you wish to make
the key definition available to everyone using the system, place the key definition in
the system login command procedure.)
Rather than typing the device/directory names after SET DEFAULT, you may wish
to define various keys as different device/directory names.
$ DEFINE/KEY/TERMINATE KP1
%DCL-I-DEFKEY, DEFAULT key
$ DEFINE/KEY/TERMINATE KP2
%DCL-I-DEFKEY, DEFAULT key

"WORKDISK:[USER]"
KP1 has been defined
"WORKDISK:[USER.ACCOUNTS]"
KP2 has been defined

Now you can change your default to WORKDISK:[USER.ACCOUNTS] by pressing
the PF1 key followed by the keypad number 2 key. The /TERMINATE qualifier
of the DEFINE/KEY command places a carriage return after the text; when you
press the key, the system attempts to execute the command line. When defining a
command line with two or more keys, remember to include all the necessary spaces.
In the previous example, the PF1 key definition provides the required space between
the command and the parameter.
The informational message following the key definition indicates the key state for
which the key is defined (see Section 1.5.3.2). The default key state is DEFAULT.
You can suppress the informational message using the /NOLOG qualifier of the
DEFINE/KEY command.

1-30

Interaction with the System

1.5.3.1 Definable Keys
By default, you can define the top row of keys on the keypad (PF1, PF2, PF3, and
PF4). You can also define certain function keys on terminals in the VT200 series. If
you set the keypad to application mode (SET TERMINAL/APPLICATION or SET
TERMINAL/NONUMERIC), you can also define the keypad keys (KPO through
KP9, MINUS, COMMA, PERIOD, and ENTER). See the DEFINE/KEY command in
Appendix DCL for a list of terminal keys that you can define.
If you are defining the keypad keys, you may want to define the ENTER key to
duplicate the RETURN key.
$ DEFINE/KEY/TERMINATE ENTER ""
%DCL-I-DEFKEY, DEFAULT key ENTER has been defined

1.5.3.2 Key States
Key states allow a single key to have multiple definitions. Typically, you use a
separate key state to define keys with parallel functions. For example, you might
define the PF1 key in the DEFAULT state to issue the SET DEFAULT command
and change the key state to DIRECTORY. Then, you might define various keys in a
second state, DIRECTORY, to issue different directory names. Use the /SET_STATE
qualifier to change the key state temporarily (the key state remains in effect until you
press a definable key or terminate the command line). Use the /IF_STATE qualifier
of the DEFINE/KEY command to indicate that a key is defined for the specified state.
$ DEFINE/KEY/SET_STATE=DIRECTORY PF1 "SET DEFAULT "
•/.DCL-I-DEFKEY, DEFAULT key PF1 has been defined
$ DEFINE/KEY/TERMINATE/IF_STATE=DIRECTORY MINUS "DISKI:[USER]"
•/.DCL-I-DEFKEY, DIRECTORY key MINUS has been defined
$ DEFINE/KEY/TERMINATE/IF_STATE=DIRECTORY COMMA "DISKI:[ACCOUNTS]"
•/.DCL-I-DEFKEY, DIRECTORY key COMMA has been defined
To change a key state permanently (until you log out or change the state again), use
the /LOCK qualifier with the /SET_STATE qualifier of the DEFINE/KEY command,
or use the /STATE qualifier of the SET KEY command. After permanently changing
the key state, you can recall the DEFAULT key state. However, the system does not
provide a mechanism that allows you to determine whether the DEFAULT state was
the previous key state.
Since you cannot determine the previous key state after permanently changing the
key state, you may wish to use the following steps to extend the duration of a
temporary state.
1.

Use the /SET_STATE qualifier of the DEFINE/KEY command to change your
key state temporarily.

Each time you define a key for that temporary state, use the /SET_STATE
qualifier to reset the temporary state.

Interaction with the System

1-31

The following command procedure defines PF3 in the DEFAULT state as the
RECALL command and defines each keypad key in the NUMERIC state as the
number of the key. The PF3 key, in addition to issuing the RECALL command,
sets the key state to NUMERIC temporarily. Since the RECALL command may be
followed by any number between 1 and 20, the user must be able to press two
NUMERIC keys. To allow a user to press more than one NUMERIC key, each key
defined for the NUMERIC state resets the NUMERIC state.
$
$
$
$
$
$

! KEYPAD_DEF.COM
!
IF F$M0DE() .NES. "INTERACTIVE" THEN EXIT
SET TERM/APPLICATION.KEYPAD
DEFINE/KEY PF3 "RECALL " /SET_STATE=NUMERIC/N0L0G

$ ! Define NUMERIC keypad.
/IF=NUMERIC
KPO ”0"
$
/IF=NUMERIC
KP1 ii ^ ii
$
/IF=NUMERIC
KP2 "2"
$
/IF=NUMERIC
KP3 11311
$
/IF=NUMERIC
KP4 11411
$
/IF=NUMERIC
KP5 11511
$
/IF=NUMERIC
KP6 "6"
$
/IF=NUMERIC
KP7 11 y 11
$
/IF=NUMERIC
KP8 " 8 "
$
/IF=NUMERIC
KP9 11911
$

/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC
/SET=NUMERIC

/N0L0G
/N0L0G
/N0L0G
/N0L0G
/NOLOG
/NOLOG
/NOLOG
/NOLOG
/NOLOG
/NOLOG

1.5.3.3 Examining and Deleting Keys
To examine the key definitions that you have created, use the SHOW KEY command.
The /DIRECTORY qualifier lists the states that you have defined.
$ SHOW KEY/DIRECTORY
DEFAULT
GOLD
The /ALL qualifier lists all the keys in the state(s) specified by the /STATE qualifier.
$ SHOW KEY/ALL/STATE=DEFAULT
DEFAULT keypad definitions:
ENTER = ""
(noecho,terminate)
PFi = "SET DEFAULT " (state=DIRECTORY)
PF3 = "RECALL "
(state=NUMERIC)
To delete a key definition, use the DELETE/KEY command. The following command
deletes all the keys defined in the GOLD state.
$ DELETE/KEY/ALL/STATE=G0LD
To delete a particular key, omit the /ALL qualifier and specify the key name as a
parameter to the DELETE/KEY command.

1-32

Interaction with the System

1.5.4 Recalling Command Lines
As described in Section 1.4.7, CTRL/B allows you to recall the previously typed line.
At DCL command level, you can recall the previous 20 command lines. Pressing
CTRL/B once recalls the previous command line, pressing CTRL/B again recalls the
line before the previous line, and so on to the last saved command line.
To examine up to 20 previously typed command lines, type RECALL/ALL.
$ RECALL/ALL
1 SET DEFAULT W0RK1:[USER]
2 EDIT ACCOUNTS.COM
3 PURGE ACCOUNTS.COM
4 DIRECTORY/FULL ACC0UNTS.COM
5 COPY ACC0UNTS.COM [.ACCOUNTS]*
6 SET DEFAULT [.ACCOUNTS]
Having reviewed the available commands, you can recall a particular command line
by typing RECALL followed by either the number of the desired command or the
first character(s) of the desired command line.
•

Number—RECALL returns the command associated with the specified number.
$ RECALL 4
$ DIRECTORY/FULL ACC0UNTS.COM

•

String—RECALL scans the previous command lines (beginning with the most
recent one) and returns the first command line that begins with the specified
character string.
$ RECALL DIR
$ DIRECTORY/FULL ACC0UNTS.COM

You can also recall a command with the up and down arrow keys, which recall
the previous and successive command respectively. For instance, after recalling
command number 4 in the preceding example, you can recall command number 3 by
pressing the up arrow.
$ DIRECTORY/FULL ACC0UNTS.COM
T
$ PURGE ACC0UNTS.COM
Pressing the down arrow after this command recalls command number 4. You can
press the arrow keys repeatedly to move rapidly through commands.

Interaction with the System

1-33

1.6 User Environment
Each user on the system is associated with a process. For example, the system creates
a process for you when you log in and deletes that process when you log out. A
process contains all the information that the system needs to execute programs, and
executes your programs (also called images or executable images) one at a time.
A program executes within the context of the process that invokes it. Some of these
programs are system programs that control the flow of events within the process.
For example, when you log in, your process is under the control of the system
program SYS$SYSTEM:LOGINOUT.EXE. When you work at DCL command level,
your process is under the control of SYS$SYSTEM:DCL.EXE.

1-6-1 Programs
A program is a file of instructions and data in machine-readable format. Image files,
which may be supplied by DIGITAL or by users, usually have a file type of EXE.
You cannot examine an image file with the DCL commands TYPE, PRINT, or EDIT
because image files do not consist of ASCII characters.
A program can be either a command image or a noncommand image.
•

Command image—A command image is a program that is associated with and
invoked by a DCL command. For example, when you type the DCL command
COPY, the VAX/VMS system executes the program SYS$SYSTEM:COPY.EXE;
COPY.EXE is a command image. The SYS$SYSTEM directory contains a number
of command image files, most of which are supplied by DIGITAL as part of
the VAX/VMS system. (Use the DCL command DIRECTORY SYS$SYSTEM to
examine this directory.)

•

Noncommand image—A noncommand image is a program that is not associated
with a DCL command. To invoke a noncommand image, name the file
containing the program as the parameter to the RUN command. The following
example invokes the image ACCOUNTS:[INC]INCOME.EXE.
$ SET DEFAULT ACCOUNTS:[INC]
$ RUN INCOME

Further operations depend on the program. For example, the program might work
interactively with you, prompting you for input and displaying information. Or, it
might simply run to termination with no outward indication to your terminal. When
the program terminates, you are returned to DCL command level.
You can give a noncommand image the appearance of a command image by defining
it as a foreign command. Define a foreign command with the following variation of
the assignment statement.
$ global-symbol-name == "$file-spec"

1-34

Interaction with the System

The command name for the foreign command is the global symbol name you specify.
The file specification identifies the file containing the noncommand image. The file
specification must be prefaced with a dollar sign and include the device, directory,
and filename. The file type defaults to EXE. The following example defines INCOME
as a foreign command that invokes the program ACCOUNTS:[INC]INCOME.EXE.
$ INCOME == "{ACCOUNTS: [INC]INCOME"
You can permit the abbreviation of foreign commands by placing an asterisk in the
symbol name after the point of the shortest abbreviation. The following example
allows you to invoke ACCOUNTS:[INC]INCOME.EXE by typing INC, INCO,
INCOM, or INCOME.
$ INC*OME == "{ACCOUNTS:[INC]INCOME"
A foreign command, since it is a symbol, supersedes any other command with the
same name or abbreviation. You cannot invoke a regular command with a name or
abbreviation that you have given to a foreign command. You will invoke the foreign
command instead.

1.6.2 Processes
The environment in which you use the VAX/VMS system is called your process.
A process contains identification and status information that the system needs to
execute programs for you. Within a process, programs execute one at a time in the
order in which they are invoked.
The VAX/VMS system creates a process for you when you:
•

•

Submit a batch job—The system creates a process for each batch job. When the
batch job is completed, the system deletes the process. Section 1.8 discusses
batch jobs.

•

Spawn a subprocess—The system creates a process when you use the SPAWN
command. Section 1.7 describes subprocesses.

•

Run a program—The system creates a subprocess when you issue the RUN
command with any of the RUN command qualifiers except /DEBUG. The system
creates a detached process when you use either the /DETACHED or /UIC=uic
qualifiers. See Appendix DCL for more information about the RUN command
and its qualifiers.

The system also creates special system processes to perform various functions. The
DCL command SHOW SYSTEM displays both user and system processes.
A process can be a detached process (a process that is independent of other
processes) or a subprocess (a process that is dependent on another process for its
existence and resources).

Interaction with the System

1-35

The following list summarizes the process context (information stored in a process).
Use the DCL command SHOW PROCESS/ALL to examine your process context.
•

Current date and time—The date and time when the SHOW PROCESS/ALL
command is executed.

•

Device name—The name of the device that is allocated to your process. This is
usually a terminal.

•

User name—The name assigned to the account that is associated with the
process.

•

Process identification number (PID)—A unique number assigned to the
process by the system. The SHOW PROCESS command displays the PID as
a hexadecimal number.

•

Process name—The name assigned to the process. Since process names are
unique, the first process logged in under an account is assigned the user name,
and subsequent processes logged in under the same account are assigned the
terminal name. You can change your process name with the DCL command SET
PROCESS/NAME.

•

User identification code (UIC)—The group and member numbers (and/or
letters) assigned to the account that is associated with the process (for example,
[PERSONNEL,RODGERS] and [200, 201]).

•

Priority—The current priority of the process.

•

Default file specification—The current default device and directory. You can
change your current defaults with the DCL command SET DEFAULT.

•

Devices allocated—The names of the devices allocated to the process. When you
are logged in at a terminal, that terminal is allocated to your process.

•

Process quotas—The quotas (limits) associated with the process. You can
examine these quotas with the /QUOTAS or /ALL qualifiers of the SHOW
PROCESS command.

•

Accounting information—The continuously updated account of the process's
use of memory and CPU time. You can examine this information with the
/ACCOUNTING or /ALL qualifiers of the SHOW PROCESS command.

•

Process privileges—The privileges associated with the process. You can examine
these privileges with the /PRIVILEGES or /ALL qualifiers of the SHOW
PROCESS command.

•

Process rights identifiers—System-defined identifiers that are used in conjunction
with access control list protection (See Section 7.2.2).

1-36

Interaction with the System

•

Process dynamic memory area—The process's current use of dynamic memory.
You can examine this information with the /MEMORY or /ALL qualifiers of the
SHOW PROCESS command.

•

Process address space—The virtual memory available to an image executing in
your process. (See Section 1.6.3.1.)

•

Processes in this tree—A list of subprocesses belonging to the parent process. An
asterisk appears after the current process.

1.6.3 System Implementation
The following discussion is provided for background information and to explain some
of the entries displayed by the DCL commands SHOW MEMORY, SHOW PROCESS,
SHOW STATUS, and SHOW SYSTEM. In general, the VAX/VMS system's use of
memory is transparent to you.

1.6.3.1 Memory
A program can directly address one gigabyte (2**30-l bytes) of space for code and
data and use most of another gigabyte without too much extra work. This area,
together with the space reserved for use by the VAX/VMS operating system, is
known as virtual memory. Half of virtual memory, called the process address space,
is unique to each process. This is the section of virtual memory that is usually
addressed by programs. The other half, called the system address space, is used by
the system and shared by all the processes on the system.
Executable images are stored as disk files. When you invoke an image, the
VAX/VMS system "maps" the image into your process address space. Mapping
associates the virtual addresses named in the image with the physical locations of the
code or data at those addresses.
To execute the image, the VAX/VMS system must bring the code and data into
physical memory. Typically, the system does not have enough physical memory to
hold every process's image, plus the system code and data structures. Therefore,
the VAX/VMS system restricts each process to a certain number of pages in physical
memory (a page is 512 bytes). This set of pages is called the process's working set.
The collection of working sets currently in memory is called the system balance set.
The DCL command SHOW STATUS displays the size (in pages) of your process
working set. The DCL command SHOW MEMORY displays the number of processes
that are resident in the balance set. The following table lists the main components of
physical memory in a VAX/VMS system.

Interaction with the System

Resident System

Page Cache

Executive routines

Free-page list

Process working sets

Nonpaged dynamic memory

Modified-page list

System working sets

1-37

Balance Set

PFN database

Pageable exec

System Page Table

System message file
Paged dynamic memory
Record Management
Services

1.6.3.2 Images and Working Sets
Once an image has been mapped into process address space, it can be executed.
Code or data is accessed from the pages in the working set as it is needed by the
image. If the code or data is not on a page in the working set, a page fault occurs,
causing the VAX/VMS system to read pages into the working set from a disk file.
Since a working set is empty when image execution begins, the first statements in
an image generate a lot of page faults. Usually, as the working set fills up, page
faults are generated at a slower rate. The DCL command SHOW SYSTEM displays
the total number of page faults generated by each process on the system. If a page
fault occurs when your working set is full, the VAX/VMS system must remove some
pages in the working set to make room for new pages. When the system removes a
page from your working set, the page is placed in one of the page caches. If the page
was modified while it was in the working set, it is placed on the modified-page list;
if it was not modified, it is placed on the free-page list.
When the modified-page list fills up, the system copies the contents of pages in the
modified-page list to the paging file on disk. Then, the pages on the modified-page
list are moved to the free-page list. A page on the free-page list is available to any
process. For example, if a process needs a page of physical memory, a page on the
free-page list can be overwritten (the contents replaced by new code or data). Or, if
a process needs the contents of a page on the free-page list, the page can be faulted
back into the working set of the appropriate process.
Pages can be faulted into the working set from the disk or from the page cache if the
page had been faulted out and was not reused. Since the page cache is in physical
memory, restoring pages from the page cache is faster than reading pages from the
disk. The DCL command SHOW MEMORY displays the number of pages in the
page cache.

1-38

Interaction with the System

1.6.3.3 Processes and the Balance Set
If enough processes are on the system, the system may run out of physical memory
and/or balance set slots. If either of these events occurs, the VAX/VMS system does
one of the following:
•

Trims working sets—The system adjusts the size of one or more working sets.
Usually, pages are taken from a number of different working sets and placed in
the page file to make room in physical memory.

•

Swaps processes—One or more processes are swapped out (removed from the
balance set). When a process is swapped out, its working set is placed in the
swapping file. A process cannot execute while it is swapped out.

The VAX/VMS system examines a process's scheduling state and priority to decide
whether a process should be swapped into or out of the balance set. In general,
processes ready to execute are kept in the balance set while processes in one of the
wait states are more likely to be swapped out. The DCL command SHOW SYSTEM
displays the state and priority of each process on the system. The following table
lists the possible process-scheduling states.
State

Explanation

CEF

Common event flag wait. Process is waiting for a combination of common event
flags to be set.

COLPG

Collided page wait. Page fault occurred while the requested page was being read
into physical memory for another process; process is waiting for the page to be
read in.

COM

Computable. Process is ready to execute.

COMO

Computable, outswapped. Process is ready to execute but swapped out.

CUR

Current. Process is currently executing.

FPG

Free-page wait. Process is waiting for a free page of physical memory.

HIB

Hibernate wait. Process is hibernating.

HIBO

Hibernate wait, outswapped. Process is hibernating and swapped out.

LEF

Local event flag wait. Process is waiting for a combination of local event flags
(usually, I/O related) to be set.

LEFO

Local event flag wait, outswapped. Process is waiting for a combination of local
event flags (usually I/O related) to be set and swapped out.

MUTEX

Mutual exclusion semaphore wait. Waiting to ensure that only one process has
access to requested code.

PFW

Page fault wait. Page fault has occurred; process is waiting for the page to be
read into physical memory.

SUSP

Suspend wait. Process is suspended.

Interaction with the System

1-39

State

Explanation

SUSPO

Suspend wait, outswapped. Process is suspended and swapped out.

RWxxx

Resource wait. The characters following the RW indicate the source of the wait:
BRK (broadcast)
CLU (cluster translation)
IMG (image activation)
LCK (lock ID database)
MBX (mailbox)
MPB (modified-page writer)
MPE (modified-page list)
NPG (nonpaged pool)
PAG (paged pool)
PFF (page file)
QUO (pooled quota)
SWP (swap file)

1.6.3.4 Resident System
The resident system is always in physical memory. It consists of:
•

Executive routines—Routines that must be available to the VAX/VMS system at
all times

•

Nonpaged dynamic memory—System data structures and code that are shared
among all the processes on the system

1.6.3.5 System Parameters
When your VAX/VMS system is first installed, the system adjusts certain system
parameters, called SYSGEN parameters, for your system hardware. You can alter
these parameters by setting values with the System Generation Utility (SYSGEN).

1.7 Subprocesses
To create a subprocess, use the DCL command SPAWN. By default, the subprocess
is created and you are given control at DCL command level within the subprocess.
Your default directory is the current default directory of the parent process. (You can
suppress the informational messages from DCL by specifying the /NOLOG qualifier
of the SPAWN command.)
$ SPAWN
7.DCL-S-SPAWNED,
7.DCL-S-ATTACHED,
$

process USER_1 spawned
terminal now attached to process USER_1

1-40

Interaction with the System

Alternatively, you can use SPAWN'S command parameter and /INPUT qualifier to
define SYS$COMMAND (command stream) and SYS$INPUT (data stream) for the
subprocess. SYS$COMMAND and SYS$INPUT determine subprocess execution.
•

No parameter, no /INPUT—SYS$COMMAND and SYS$INPUT default to your
terminal, as shown in the previous example. (SYS$INPUT defaults to NL: if you
invoke SPAWN from a command procedure.)

•

Parameter, but no /INPUT—SYS$COMMAND is the command parameter
(either a command or a command procedure) and SYS$INPUT defaults to your
terminal. (SYS$INPUT defaults to NL: if you invoke SPAWN from a command
procedure.) If the command parameter is a command that requires data, data
is read from the terminal. If the command parameter is a command procedure
that requires data, how data is read depends on how the command procedure is
written (INQUIRE, READ, and so on).

•

/INPUT, but no parameter—SYS$COMMAND and SYS$INPUT are both
defined as the file or device you specify as the qualifier value. If the specified
command(s) require data, the data is read from the specified file or device. In
addition, when you use the /INPUT qualifier of the SPAWN command to specify
a nonterminal input stream, the subprocess is created as a noninteractive process.
A noninteractive process exits upon encountering a severe error or an end-of-file
indicator. At DCL command level, CTRL/Z is treated as an end-of-file indicator.

•

Parameter and /INPUT—SYSSCOMMAND is the command parameter (either
a command or command procedure) and SYS$INPUT is the file or device you
specify as the /INPUT qualifier value. If a command specified by the command
parameter requires data, data is read from SYS$INPUT.

The following command creates a subprocess to execute the command procedure
SORT.COM. If SORT requires any data, data is read from the terminal. When
the command procedure completes, the subprocess is deleted along with any
subprocesses that it may have created.
$ SPAWN OSORT.COM
•/.DCL-S-SPAWNED, process USER_1 spawned
%DCL-S-ATTACHED, terminal now attached to process USER_1
.

! output from SORT.COM

%DCL-S-RETURNED, control returned to process USER
The following command creates a subprocess to execute the command procedure
SORT.COM. If SORT requires any data, the data must be supplied by the command
procedure (as in a batch job). When the command procedure completes (or
encounters a severe error), the subprocess is deleted along with any subprocesses
that it may have created.
$ SPAWN/INPUT=SORT

Interaction with the System

i-4i

Because each process that you create is unique, commands executed in one process
do not usually affect any other process. However, since control of the terminal
passes between processes, commands that affect the terminal characteristics (SET
TERMINAL) affect any process controlling that terminal. For example, if one process
inhibits echoing and exits without restoring it, echoing remains inhibited for the next
process that gains control of the terminal.

1.7.1 Exiting from a Subprocess
To exit from a subprocess created by SPAWN, use one of the following commands:
•

LOGOUT—When you exit from a subprocess with the LOGOUT command, the
subprocess is deleted (along with any subprocesses that it created) and you are
returned to the parent process.

•

ATTACH—When you exit from a subprocess with the ATTACH command, the
subprocess hibernates and control of your terminal is transferred to the specified
process. (You must either specify a process name as a parameter to the ATTACH
command or a process identification number as a value of the /IDENTIFIER
qualifier of the ATTACH command.) The following example shows how to
exit from the subprocess USER_1 and attach to the process USER using the
/IDENTIFIER qualifier.
$ SHOW PROCESS
26-APR-1986 10:37:27.32
User: USER
Pid: 00000019
Proc. name: USER_1
UIC: [200,200]
Priority:
4
Default file spec: SYS$SYSDEVICE:[USER]
$ ATTACH/IDENTIFIER=00000018
°/0DCL-S-RETURNED, control returned to process USER
$ SHOW PROCESS
26-APR-1986 10:34:58.50
0PA0:
User: USER
Pid: 00000018
Proc. name: USER
UIC: [200,200]
Priority:
4
Default file spec: SYS$SYSDEVICE:[USER]
Devices allocated: 0PA0:

1-42

Interaction with the System

1.7.2 Subprocess Context
A subprocess's context is copied from the parent's context with the following
exceptions:
•

Process identification number—The system assigns each created subprocess a
unique process identification number.

•

Process name—By default, the subprocess name consists of the name of the
parent process followed by an underscore and an integer. Use the /PROCESS
qualifier of the SPAWN command to specify a process name other than the
default. A process name must be unique.

•

Created commands—Commands that are defined by a parent process using
the SET COMMAND command are not copied to a subprocess. To use a
created command in a subprocess, you must use SET COMMAND to create
that command for the subprocess.

The previous list implies that, by default, a created subprocess inherits the following
items from the parent process: defaults, privileges, symbols, logical names, control
characters, message format, verification state, and key definitions. You can use the
following SPAWN qualifiers to prevent the subprocess from inheriting a number of
these items.
Qualifier

Items Inhibited or Changed

/CARRIAGE-CONTROL, /PROMPT

DCL prompt

/NOCLI

CLI (DCL by default)

/NOKEYPAD

Keypad definitions

/NOLOGICAL -NAMES

Logical names

/NOSYMBOL

Symbols

NOTE:

The /SYMBOL and /LOGICAL—NAMES qualifiers do not affect systemdefined symbols (such as $SEVERITY and $STATUS) or system-defined logical names
(such as SYS$COMMAND and SYS$OUTPUT).
Since copying logical names and symbols to a subprocess can be time consuming
(a few seconds), you will probably want to use the /NOLOGICAL—NAMES and
/NOSYMBOL qualifiers unless you plan to use the logical names or symbols in the
subprocess. If you create subprocesses frequently, the best practice is to use the
ATTACH command to transfer control between the parent and the subprocess rather
than repeatedly waiting for the system to create a new subprocess for you.

Interaction with the System

1-43

1.7.3 Subprocess Execution
Typically, you use a subprocess in one of two ways:
•

Interrupts—To perform a second task, then return to an original task. Since
SPAWN is a built-in command (see Section 1.4), you can use CTRL/Y to
interrupt one task, spawn a subprocess to perform a second task, exit from
the subprocess, and enter the CONTINUE command to return to the original
task. Note that you can only issue the CONTINUE command after interrupting
a command procedure when there is no ON—CONTROL _Y condition in the
command procedure. (If you interrupt the EDT editor, enter the CONTINUE
command and then press CTRL/W to refresh the screen.)

•

Batch—To perform a second task while continuing to work on your original task.

By default, when you create a subprocess, the parent process hibernates. When you
return to the parent process, you either delete or hibernate the subprocess. Only one
of your processes is executing at any one time.
To execute a subprocess and its parent process at the same time, you must specify
the /NOWAIT qualifier of the SPAWN command. Since both processes are executing
concurrently, both will attempt to control the terminal. To prevent conflicts, when
you create a subprocess using the /NOWAIT qualifier, also specify the following:
•

/OUTPUT qualifier—Indicates that the subprocess should write output to a
specified file rather than to the terminal.

•

SPAWN command parameter or /INPUT qualifier—Indicates that the subprocess
should execute the specified commands rather than reading input from the
terminal.

When you specify the /INPUT qualifier of the SPAWN command, the subprocess is
created as a noninteractive process that exits upon encountering a severe error or an
end-of-file indicator (such as CTRL/Z pressed at DCL command level).

1.8 Batch Jobs
A batch job consists of one or more command procedures that execute in a detached
process without user interaction. A batch queue is a list of batch jobs waiting to
execute. Your job may have to wait for a previous job to complete before it can
begin executing. (The number of batch jobs that can execute simultaneously is
specified when the batch queue is created by the system manager.)
In general, you use batch jobs to execute a command or set of commands that either
take a long time to execute or that you want to schedule for execution after regular
hours (see Section 1.8.2).

1-44

Interaction with the System

1.8.1 Submitting a Batch Job
Use the SUBMIT command to enter a command procedure into a batch queue. If you
specify more than one command procedure, the procedures execute one after another
in the order of specification. The following command enters LIBRARY.COM and
SORT.COM into the default batch queue SYS$BATCH (file type defaults to COM).
$ SUBMIT LIBRARY,SORT
Job LIBRARY (queue SYS$BATCH, entry 201) started on SYS$BATCH
The system displays the name of the job, the queue containing the job, and the entry
number assigned to the job. Once a job is submitted, you reference it using the entry
number.
To specify parameters for a command procedure submitted as a batch job, use
the /PARAMETERS qualifier of the SUBMIT command. Note that you can
also pass data to a batch job by including the data in the command procedure
itself or by defining SYS$INPUT to be a file. (See Section 6.3 for further
information.) The specified parameters are used for each command procedure in
the batch job. You cannot specify different parameters for individual command
procedures within a single job. The following example passes LIBRARY.COM
and SORT.COM the parameters WORKDISK:[ACCOUNT.BILLS]DATA.DAT and
WORKDISK:[ACCOUNT]NAME.DAT.
$ SUBMIT LIBRARY, SORT/PARAMETERS= _$ (WORKDISK:[ACCOUNT.BILLS]DATA.DAT,WORKDISK:[ACCOUNT]NAME.DAT)
Job SORT (queue SYS$BATCH, entry 203) started
Your batch job executes as if you had logged in and executed each of the submitted
command procedures. For example, the previous SUBMIT command executes a batch
job that logs in under your account, executes your login command procedure, and
then executes the following commands:
$ ©LIBRARY WORKDISK:[ACCOUNT.BILLS]DATA.DAT WORKDISK:[ACCOUNT]NAME.DAT
$ ©SORT WORKDISK:[ACC0UNT.BILLS1DATA.DAT WORKDISK:[ACCOUNT]NAME.DAT
Since your login defaults are not usually the defaults needed to access files
mentioned in a command procedure, the command procedures should use one
of the following mechanisms to ensure that the correct files are accessed.
•

Use complete file specifications—When accessing a file in a command procedure
or passing a file to a command procedure, include the device and directory names
as part of the file specification, as shown in the previous example.

•

Use the SET DEFAULT command—Before accessing a file in a command
procedure, use the SET DEFAULT command to specify the proper device and
directory.

Interaction with the System

$
$
$
$
$

1-45

! SORT.COM
!
! Sort PI into P2
SET DEFAULT WORKDISK:[ACCOUNT.BILLS]
S0RT/KEY=(POSITION:1,SIZE:4) ’PI’ ’P2’

1.8.2 Controlling a Batch Job
To specify control information when submitting a batch job, add the appropriate
qualifiers to the SUBMIT command. To specify control information after submitting
a batch job but before the job begins executing, use the SET QUEUE/ENTRY=n
command (where n is the job number). Control information allows you to perform
a number of operations; the following list describes the most common operations.
(Unless otherwise noted, the specified qualifiers can be used with either SUBMIT or
SET QUEUE/ENTRY. For a complete list of qualifiers see the command descriptions
in Appendix DCL.)
•

Specify job name—Use the /NAME qualifier. The job name defaults to the file
name of the first command procedure.

•

Delay execution—To specify an exact time of execution, use the /AFTER
qualifier. To hold a job indefinitely, use the /HOLD qualifier. To execute a
job that is being held (either by /AFTER or /HOLD), use the /RELEASE or
/NOHOLD qualifier of the SET QUEUE/ENTRY command.

•

Delete job—Use the DELETE/ENTRY command if the job has not started. Use
the STOP/QUEUE/ENTRY command if the job is executing.

•

Restart job—Use the STOP/QUEUE/REQUEUE/ENTRY command. You can
restart the job on the same queue or on a different queue. A batch job cannot be
restarted unless it was submitted with the /RESTART qualifier. See Section 1.8.4
for more information on restarting batch jobs.

•

Delete command procedures—Use the /DELETE qualifier. As a command
qualifier, /DELETE indicates that all command procedures are to be deleted after
executing. As a file qualifier, /DELETE indicates the specified file is to be deleted
after executing.

•

Request notification of job completion—Use the /NOTIFY qualifier. When the
job completes, a message to that effect is broadcast to the terminal that you are
logged in on.

Note that if multiple procedures are submitted in a batch job, the batch job
terminates when any procedure exits with an error or fatal error status.

1-46

Interaction with the System

1.8.3 Batch Job Output
By default, accumulated output from a batch job is written to a log file once each
minute. (To specify a different time interval, include the SET OUTPUT-RATE
command in your command procedure.) If you attempt to read the file while the
system is writing to it, you receive a message indicating that the file is locked by
another user. Wait a few seconds and try again.
The output from a batch job includes the contents of your login command file,
everything written to SYS$OUTPUT (command procedure output, error messages,
and so on), and the full logout message. To prevent your login command procedure
from being written to the batch log file, begin your login command procedure with
the following command:
$ IF F$MODE()

.EQS.

"BATCH" THEN SET NOVERIFY

The name of the log file defaults to the job name, a file type of LOG, and the device
and directory specified by your login defaults. To specify a different log file name
when you submit the job, use the /LOG—NAME qualifier of the SUBMIT command.
When the batch job completes, the log file is queued to SYS$PRINT, printed, and
deleted. To save the log file after printing it, use the /KEEP qualifier of the SUBMIT
command. To save the log file without printing it, use the /NOPRINT qualifier of
the SUBMIT command.

1.8.4 Restarting Batch Jobs
By default, if the system fails while your batch job is executing, your job does not
complete. When the system recovers and the queue is restarted, your job is aborted
and the next job in the queue is executed. However, by specifying the /RESTART
qualifier when you submit a job (SUBMIT command), you indicate that the system
should reexecute the job if the system crashes before the job completes. In addition,
specifying the /RESTART qualifier allows you to abort execution of the job and
restart it on the same queue or a different queue using the /ENTRY qualifier of the
STOP/QUEUE/REQUEUE command.
By default, a batch job is reexecuted beginning with the first line. You can use the
following symbols to specify a different restarting point:
•

$RESTART—A global symbol whose value is true if the batch job has been
started at least once before this execution. Do not specify a value for $RESTART;
the system will assign the appropriate value.

•

BATCH$RESTART—A global symbol whose value you specify with the SET
RESTART-VALUE command.

Interaction with the System

1-47

The following steps describe how to use these symbols in a command procedure.
•

Begin each possible starting point of the procedure with a label.

•

As the first step in each section, equate the value of BATCH$RESTART to the
label with the SET RESTART—VALUE command.

•

At the beginning of the procedure, test $RESTART. If $RESTART is true, issue a
GOTO statement using BATCH$RESTART as the transfer label.

The following command procedure extracts a number of modules from a library,
concatenates those modules, and then sorts the resulting file. If aborted, the
command procedure reexecutes from the beginning of the file, the statement labeled
CONCATENATE—LIBRARIES or the statement labeled SORT—FILE, depending
on the value of BATCH$RESTART. (If you were extracting a number of separate
modules, you could make each extraction a separate section.)
$
$
$
$
$
$
$
$
$
$
$

! SORT_MODULES.COM
!
! set default to the directory containing
! the library whose modules are to be sorted
SET DEFAULT WORKDISK:[ACCOUNTS.DATA83]
! check for restarting
IF $RESTART THEN GOTO BATCH$RESTART
EXTRACT.LIBRARIES:
SET RESTART_VALUE=EXTRACT_LIBRARIES

$ CONCATENATE.LIBRARIES:
$ SET RESTART_VALUE=CONCATENATE_LIBRARIES

$ SORT.FILE:
$ SET RESTART_VALUE=SORT_FILE

$ EXIT

1-48

Interaction with the System

1.9 Error Conditions
System commands and utilities place a value in the global symbol $STATUS when
they exit. User programs may also set $STATUS. To set $STATUS when exiting from
your command procedure, include a parameter value on the EXIT command. The
system uses $STATUS to determine which message, if any, to display and whether
or not to continue execution. The value of the lower three bits in $STATUS is placed
in the global symbol $SEVERITY. This value indicates success or failure, as shown:
Value

Severity

Warning

Success

Error

Information

Fatal or severe error

In the following example, $STATUS and $SEVERITY indicate successful completion
of a command.
$ SHOW SYMBOL $STATUS
SSTATUS = "°/0X00000001"
$ SHOW SYMBOL $SEVERITY
$SEVERITY = ”1"
Success is indicated by an odd value; failure and warning are indicated by an even
value. Therefore, $SEVERITY (or $STATUS) can be used as a logical value. The
following statement (from a command procedure) passes control to an error routine
if $SEVERITY indicates failure.
$ IF .NOT. $SEVERITY THEN GOTO ERROR

1.9.1 Commands That Do Not Change $STATUS
The following commands do not change $STATUS or $SEVERITY when they execute
successfully:
CONTINUE

DECK

DEPOSIT

EOD

EXAMINE

GOTO

SHOW STATUS

SHOW SYMBOL

STOP

WAIT

Interaction with the System

1-49

1.9.2 System Error Messages
System error messages are displayed in the format:
#/oFACILITY-L-IDENT, text
FACILITY
L
IDENT
text

=
=
=
=

the mnemonic for the program issuing the message
the first letter of the severity code
an abbreviation of the text
an explanation of the error

Suppress any part of the error message with the SET MESSAGE command. A SET
MESSAGE command remains in effect until you enter the SET MESSAGE command
again or log out. The following command suppresses the explanatory text of the
message.
$ SET MESSAGE/NOTEXT
To examine the current setting of SET MESSAGE, use the MESSAGE keyword of the
F$ENVIRONMENT lexical function.
$ MESSAGE = F$ENVIRONMENT ("MESSAGE")
$ SHOW SYMBOL MESSAGE
MESSAGE = "/FACILITY/SEVERITY/IDENTIFICATION/NOTEXT"

1.10 Using the Mail Utility
The interactive Mail Utility (MAIL) allows you to send and receive messages, as well
as to file, forward, delete, and reply to messages that you have received. To invoke
the interactive Mail Utility, specify the DCL command MAIL without parameters.
$ MAIL
MAIL>
You can display information about MAIL commands by entering HELP in response
to the MAIL> prompt (or you can refer to Appendix MAIL for descriptions of MAIL
commands). To exit from MAIL, enter the MAIL command EXIT or press CTRL/Z.

1.10.1 Sending Mail
You can create and send mail messages interactively with the Mail Utility. You can
send files to other users from within the Mail Utility or from the DCL command
level.

1-50

Interaction with the System

1.10.1.1 Sending a Mail Message
After invoking the Mail Utility, specify the SEND command to create and send a
mail message. MAIL prompts you for the names of the users to whom you want to
send the message, the subject of the message (optional), and the text of the message
(optional). The following example sends a message to user name USER:
MAIL> SEND
To:
USER
Subj:
Meeting of June 9
Enter your message below.Press CTRL/Z when complete,or CTRL/C to quit:
Sorry I cannot make the meeting:
I’ll be on vacation
during that week.
Let me know how it goes.
Frank
Note that pressing CTRL/Z actually sends the message.
If you decide not to send the message, enter CTRL/C, which cancels the SEND
operation without exiting from MAIL.
To use the editor when sending a mail message interactively, specify the /EDIT
qualifier with the SEND command.
MAIL> SEND/EDIT
After you respond to the prompts for the names to whom you want to send the
message and for the subject of the message, MAIL invokes the editor, which you
can use to compose your message. By default, MAIL invokes the EDT editor.
Section 1.10.1.3 describes how to change the default editor. To send the message,
exit from the editor by pressing CTRL/Z and entering the EXIT command; to cancel
the send operation, exit from the editor by pressing CTRL/Z and entering the QUIT
command.
In addition to the SEND command, you can use the /EDIT qualifier with the REPLY
and FORWARD commands. By specifying /EDIT when you invoke the Mail Utility,
you can use the editor for SEND, REPLY, and/or FORWARD operations during the
ensuing mail session. See Appendix MAIL for descriptions of the /EDIT qualifier for
the Mail Utility commands.

Interaction with the System

1-51

1.10.1.2 Sending a File
To send a file to one or more users, specify either the DCL command MAIL or the
SEND command of the Mail Utility. The following DCL command sends the file
MEMO.TXT to user name USER. The argument to the /SUBJECT qualifier must be
enclosed in quotation marks if it contains any spaces or nonalphanumeric characters.
$ MAIL/SUBJECT="Another memo" MEMO.TXT USER
If you use the SEND command from within interactive MAIL, you can specify the
/EDIT qualifier to edit the file before sending it. The following example invokes the
editor to edit the file MEMO.TXT before sending the file to user name USER.
MAIL> SEND/EDIT MEMO.TXT
To:
USER
Subj:
The memo I promised you.
To send the message, press CTRL/Z and enter the EXIT command; to cancel the
SEND operation, press CTRL/Z and enter the QUIT command.

1.10.1.3 Setting the Default Editor
By default, MAIL invokes the EDT editor whenever you specify the /EDIT qualifier.
To specify an editor other than EDT as the default editor for MAIL, do the following:
1.

Copy the MAILEDIT.COM command procedure to your directory with the
following command:
$ COPY SYSSSYSTEM:MAILEDIT.COM *

Edit the command procedure MAILEDIT.COM, changing each occurrence of
the EDIT command to the command name you have defined to invoke your
alternative editor. For example, if you use the foreign command WINK to invoke
your editor, the edited version of MAILEDIT.COM should read as follows (see
Section 1.6.1 for information on defining foreign commands).
$ ! MAILEDIT.COM
$ !
$ ! Command procedure to invoke an editor for MAIL.

$ !
$ !

Inputs:

$ !
$ !
$ !

PI = Input filename.
P2 = Output filename.

$ !
$
$
$
$

! If MAIL$EDIT is undefined, MAIL will invoke
!
callable EDT.
! If MAIL$EDIT is defined to be a command procedure,
! MAIL will create a subprocess to edit the mail.

$ !

Interaction with the System

1-52

$
$
$
$
$

! Note that this procedure is run in the context
!
of a subprocess.
! LOGIN.COM is not executed.
However, all process
!
logical names and DCL global symbols are
!
copied.

$ !
$ ! The default directory is the same as that
$ !
of the parent process.

$ !
$ DEFINE /USER SYS$INPUT ’F$TRNLNM("SYS$OUTPUT")’
$ IF PI .EQS. "" THEN GOTO NOINPUT
$ WINK /0UTPUT= *P2* 'PI'
$ EXIT
SNOINPUT:
$ WINK ’P2’
$ EXIT
3.

Include the following line in your LOGIN.COM file.

$ DEFINE MAIL$EDIT disk:[directory]MAILEDIT.COM

1.10.1.4 Sending a Message Between Systems
To send a message to a user on another system, specify the node name of that
system, a double colon, and the user name.

nodename::username
For example, to send a message to a user named OSGOOD on a node named
BRUTUS, specify:
MAIL> SEND
To:
BRUTUS::OSGOOD

1.10.1.5 Sending a Message to a Distribution List
You can create a file containing a list of users to whom you frequently send mail and
specify the file name rather than the individual user names when you send mail to
those users. The default file type of a distribution list file is DIS.
When you create a distribution list, type one user name per line. You can also
include the names of other distribution lists by specifying an at sign (@) followed
by the name of the distribution list. Begin comments with exclamation points. For
example:

Interaction with the System

1-53

! ALLBUD.DIS
!
! Budget Committee Members
OBUDGET
! listed in BUDGET.DIS
! Staff
USER
! me
BRUTUS::WILSON
! Martha Wilson
PORTIA::RIPLEY
! Roy Ripley
To use the distribution list, type an at sign (@) and then the file name in response
to the To: prompt. For example:
MAIL> SEND
To:
OALLBUD
Subj:
Tomorrow’s Meeting
You can also specify more than one distribution list in response to the To: prompt.
MAIL> SEND
To:
USER,(3ALLBUD
Subj:
Tomorrow’s Meeting

1.10.2 Reading Mail
You must invoke the interactive Mail Utility to read a mail message. Messages that
you receive are stored in mail files, which have a default file type of MAI. Your
default mail file, MAIL.MAI, is created in your default directory the first time you
receive a mail message. See Section 1.10.5.3 for information on creating, accessing
and deleting mail files.

1.10.2.1 New Messages
When you are logged in and receive a mail message, notice of the new message
appears on your screen. For example, a message sent by user name USER would
appear as:
New mail from USER
You are also notified that you have new mail when you log in and when you invoke
MAIL. To read a new mail message, invoke MAIL interactively; MAIL prompts for a
command and, if you have received mail, displays the number of mail messages you
have received.
$ MAIL
You have 1 new message.
MAIL>

1-54

Interaction with the System

To read the new message, press RETURN; the message appears on your screen.
#1
From:
To:
Subj :

l-JUN-1986

14:12:27

NEWMAIL

USER
BOSS
Meeting of June 9

The meeting has been moved from the auditorium to the
cafeteria.
MAIL>
To continue reading your new mail messages, press RETURN in response to the
MAIL> prompt. Pressing RETURN in MAIL is equivalent to specifying the READ
command without parameters. When you have read all new messages, MAIL issues
the message //0/oMAIL-E-NOMOREMSG, no more messages," and continues to
prompt for commands until you exit by entering EXIT or pressing CTRL/Z.
If you receive a mail message while you are in interactive MAIL, specify the READ
/NEW command to read the new message.

1.10.2.2 Old Messages
To read old mail messages, invoke the Mail Utility and press RETURN. If you have
no new mail messages, the first message (numbered 1) in your default mail file
appears on your screen. Press RETURN to display the next message. If the message
is too long to display on the screen, pressing RETURN displays the next part of the
message. To skip part of a message and display the next message, specify the NEXT
command.
You can select and display a particular message within the current folder by
specifying the READ command and the number of the message. (Section 1.10.5
describes folders.) To list the numbers of messages in the current mail folder, specify
the DIRECTORY command.
MAIL> DIRECTORY
MAIL
# From
1 BRUTUS::OSGOOD
2 USER

Date
17-N0V-1986
17-N0V-1986

Subject
our meeting
status

MAIL> READ 2
If you have a large number of messages, you can locate a particular message by using
the SEARCH command to find a specified string. The SEARCH command selects and
displays the first message in the current folder that contains the specified string. To
search for a new string, specify the string as a parameter of the SEARCH command.
Each time you specify a new string, the SEARCH command starts the search at
message number 1. To continue searching the folder for messages that contain the
specified string, use the SEARCH command without specifying a parameter.

Interaction with the System

1-55

MAIL> SEARCH STAFF
Selects and displays the first message containing "staff."
MAIL> SEARCH
Selects and displays the next message containing "staff."
MAIL> SEARCH
'/.MAIL-E-NOTFOUND, no messages containing * STAFF * found

1.10.3 Creating a File from a Mail Message
To copy a mail message to a sequential file, use the EXTRACT command. The
following commands create a file named MEETING.TXT containing the text of
message number 3. (The /NOHEADER qualifier specifies that only the text of the
message is to be copied to the file.) In this case, BOSS is a logical name you have
previously defined (using the DEFINE command) to equate to your supervisor.
MAIL> READ 3
#3
From:
To:
Subj:

l-JUN-1986

14:12:27

NEWMAIL

USER
BOSS
Meeting of June 9

The meeting has been moved from the auditorium to the
cafeteria.
MAIL> EXTRACT/NOHEADER MEETING.TXT
Use the /APPEND qualifier of the EXTRACT command to copy a message to the end
of an existing file. Use the /ALL qualifier to copy all the files in the current folder to
an existing file (Section 1.10.5 discusses folders).

1.10.4 Deleting Mail
To delete a mail message, either specify the number of the mail message as the
parameter of the DELETE command, or read the message (to make it the current
message) and specify the DELETE command without parameters. For example, to
select and delete message number 3, specify:

1-56

Interaction with the System

MAIL> READ 3
#3

l-JUN-1986

From:
To:
Subj:

14:12:27

NEWMAIL

USER
BOSS
Meeting of June 9

The meeting has been moved from the auditorium to the
cafeteria.
MAIL> DELETE
The following command has the same effect as the preceding example.
MAIL> DELETE 1
When you delete a message, the message is moved to the wastebasket folder. During
your interactive MAIL session you can recover any deleted message by moving the
message out of the wastebasket folder (see Section 1.10.5.1). When you exit from the
current mail file (either by exiting from MAIL or by specifying a different mail file),
MAIL automatically deletes all messages in the wastebasket folder. (Section 1.10.5.3
discusses mail files.)
By default, the wastebasket folder is named WASTEBASKET. Use the SET
WASTEBASKET_NAME command to specify a different name for the wastebasket
folder. Use the SHOW WASTEBASKET_NAME command to display the current
name of the wastebasket folder.

1.10.5 Organizing Mail
By default, each account has one mail file (MAIL.MAI in your login default directory)
that contains two folders:
•

NEWMAIL—Contains all messages that have not been read. If you enter mail
and NEWMAIL contains one or more messages, your current folder will be
NEWMAIL. Once you leave NEWMAIL (either by exiting from MAIL or by
changing folders), MAIL moves any messages that have been read and not
deleted to your MAIL folder; the messages moved to MAIL are deleted from
NEWMAIL.

•

MAIL—Contains messages that have been read and not deleted. If you invoke
mail and NEWMAIL contains no messages, your current folder will be MAIL.

You can create any number of mail files. Each mail file can contain any number of
folders. Each folder can contain any number of messages. Typically, you organize
your messages by creating folders rather than by creating mail files. If your mail file
is very large (over 500 blocks), you may want to create separate mail files for the
larger folders to improve the Mail Utility's performance.

Interaction with the System

1-57

1.10.5.1 Creating and Modifying Folders
The following commands allow you to create and modify folders.
•

COPY—Places a copy of the current message into the specified folder. If the
folder does not exist, you are prompted for confirmation before it is created. The
following commands copy all the messages concerning the FEED account from
the current folder to a folder named FEED. After the commands are executed,
you have two copies of each message, one in the current folder and one in FEED.
MAIL> SEARCH FEED
Selects and displays first message containing "feed."
MAIL> COPY FEED
Folder FEED does not exist.
Do you want to create it (Y/N, default is N)?Y
‘/.MAIL-1-NEWFOLDER, folder FEED created
MAIL> SEARCH
Selects and displays next message containing "feed."
MAIL> COPY FEED
MAIL> SEARCH
#/,MAIL-E-NOTFOUND, no messages containing ’FEED* found

•

MOVE—Moves the current message into the specified folder. If the folder does
not exist, you are prompted for confirmation of its creation. After being moved,
the message is automatically deleted from the current folder. The following
command moves the current message to the folder named FEED, deleting it from
the current folder.
MAIL> MOVE FEED

•

FILE-Interchangeable with the MOVE command.

1.10.5.2 Deleting Folders
To delete a mail folder, delete all the messages in the folder. The following example
deletes the FEED folder.
MAIL> SELECT FEED
#/,MAIL-1-SELECTED, 2 messages selected
MAIL> DELETE/ALL

1-58

Interaction with the System

1.10.5.3 Creating, Accessing, and Deleting Mail Files
To create a mail file, move a message into the file. Use the COPY, MOVE, or FILE
command as you would to create a folder with the following addition: specify the
name of the mail file after the name of the folder. The following example creates the
mail file ACCOUNTS.MAI and moves the current message into a folder named FEED
in the file ACCOUNTS.MAI, deleting the message from its current folder and file.
MAIL> MOVE FEED ACCOUNTS
To work within a mail file other than the default mail file, use the SET FILE
command to specify the alternate file. (The SHOW FILE command displays the
name of the current mail file.) When you change mail files, the WASTEBASKET
folder of the current mail file is emptied and the mail file is closed.
To delete a mail file, delete all the messages in all the folders in the mail file (or
copy, file, or move them to another mail file). Then exit from MAIL, change the
protection of the file and delete it (using the DCL commands SET PROTECTION and
DELETE).

1.10.5.4 Selecting Folders
The name of the current folder is displayed in the top right corner of the screen
each time you enter a READ or DIRECTORY command. You can operate only on
messages that are in your current folder.
To display a list of the folders in your current mail file, use the DIRECTORY
/FOLDER command.
MAIL> DIRECTORY/FOLDER
Listing of folders in SYS$L0GIN:[USER]MAIL.MAI;1
Press CTRL/C to cancel listing
MAIL
MEETING_MINUTES
MEMOS
PROJECT.NOTES
STAFF
To select a new folder as your current folder, use one of the following commands:
•

SELECT—Selects the specified folder as the current folder.
MAIL> SELECT STAFF
'/.MAIL-1-SELECTED, 4 messages selected

•

DIRECTORY—Selects the specified folder as the current folder and lists the
messages in the folder.
MAIL> DIRECTORY STAFF
#
1
2
3
4

From
BRUTUS::OSGOOD
BRUTUS::OSGOOD
CAESAR:.USER
BRUTUS::OSGOOD

Date
12-N0V-1986
19- N0V-1986
20- N0V-1986
3-DEC-1986

STAFF
Subj ect
Staff meeting
Staff meeting
Goodbye Sarah
Staff meeting

Interaction with the System

•

1-59

READ—Selects the specified folder as the current folder and displays the
specified message (by default, the first message in the folder).
MAIL> READ STAFF
#1
12-N0V-1986
From:
To:
Subj:

14:12:28

STAFF

BRUTUS::OSGOOD
JULIUS::USER
Staff meeting

The weekly staff meeting was cancelled due to the
conference in Denver.
MAIL>

1.10.6 Using a Mail Subdirectory
When you receive mail messages longer than three blocks, they are written to files
named MAIL$xxxxxxxxxx.MAI located in your SYS$LOGIN directory. To avoid the
display of these MAI files in your SYS$LOGIN directory, use the
SET MAIL—DIRECTORY command, which creates a mail subdirectory and moves
all your MAI files to that subdirectory. (The SHOW MAIL—DIRECTORY command
displays the name of the subdirectory that contains all your MAI files.) To move the
MAI files from a subdirectory back to your SYS$LOGIN directory, use the
SET NOMAIL-DIRECTORY command.

1.10.7 Using the Mail Keypad
You can use the keypad to execute commands in the Mail Utility. Most of the
keypad keys execute two commands. To enter the top command shown in the
following diagram, you simply press the key. To enter the bottom command shown
in the following diagram, you press the PF1 key before you press the key (just as
you do when using the editing keypad).

PF1

PF2

PF3

PF4

HELP

EXTRACT/MAIL

ERASE

DIR/FOLDER

EXTRACT

SELECT/MAIL

GOLD

SEND

FORWARD

READ/NEW

SEND/EDIT

REP/EDIT/EXT

FORWARD/EDIT

SHOW/NEW

CURRENT

FIRST

LAST

dir/new

CURRENT/EDIT

FIRST/EDIT

LAST/EDIT

DIR MAIL

ENTER

BACK

DIR

BACK/EDIT

PRINT/PR/NOT

DIR/ST=99999
SELECT
•

0
NEXT

FILE

NEXT/EDIT

DELETE

7K-1744-84

To execute the MAIL command SEND, for example, press the keypad key 7. To
execute the MAIL command SEND/EDIT, press the PF1 key first and then press key
7. (For more information on mail keypad commands, see Appendix MAIL).
You can redefine the keypad keys to execute MAIL commands when you are in the
Mail Utility. Defining keypad keys in MAIL is similar to defining keypad keys to
execute DCL commands; see the DEFINE/KEY command in Appendix MAIL for
specifications.

Chapter 2
Storage and Output of Data
You can save data by storing it on disks and magnetic tapes, which are structured so
that the data resides in discrete files. You can examine data by displaying files on the
terminal screen and printing files on paper.

2.1

Devices

Devices are classified as either mass storage or record oriented.
Mass storage devices provide a way to save the contents of files on a magnetic
medium. Files thus saved can be accessed at any time and updated, modified, or
reused. Disks and magnetic tapes are mass storage devices. When disk packs or reels
of magnetic tape are mounted on drives, they are called volumes.
Record-oriented devices read and write only single physical units of data at a time,
and do not provide online storage of the data. Terminals, printers, mailboxes, and
card readers are record-oriented devices. (Printers and card readers are also called
unit record devices.)
You can use physical, logical, or generic names to refer to devices.
Note that certain commands such as ALLOCATE and MOUNT require that you
specify a device name. When a command requires a device name, specify only the
device portion of the file specification.

2-2

Storage and Output of Data

2.1.1 Physical Device Names
Each physical device known to the system is uniquely identified by a physical device
name specification in the following format:
ddcu
where dd is a code for the device type, c is a controller designation, and u is a unit
number.
The controller designation and unit number identify the location of the device within
the hardware configuration of the system. Controllers are designated with alphabetic
letters A through Z. Unit numbers are decimal numbers from 0 through 65535.
The maximum length of the device name field, including the controller and the
unit number, is 15 characters. When you specify a device name as part of a file
specification, terminate it with a colon (:).
When you refer to a file on a disk volume set, you can specify either the name of the
device on which the first volume in the set is mounted or the logical name assigned
to the volume set when it was mounted. If you do not specify a logical or physical
device name, your current default device name is supplied.

2.1.2 Logical Device Names
Your system manager can set up logical names to indicate the devices available to
you. You should use these logical names, rather than the physical device names,
when referring to files. In this way, you can achieve file and device independence.
If you specify a file using a logical device name, you can access the file, regardless
of which physical device holds the disk or tape containing your file. Your system
manager will ensure that the logical device names are always equated to the correct
physical devices. When you use a logical device name in a file specification, you
must terminate the name with a colon.
For example, the following file specification uses a logical device name to specify the
device containing the disk volume with the file [NOAH]ANIMALS.LIS:

USE1 :[NOAH]ANIMALS.LIS
As long as the system manager defines the logical name USE1 correctly, the system
can access your files, regardless of where the volume is mounted.
The VAX/VMS system also offers a special type of logical device name called a
concealed device name. If a device has a concealed device name, the logical name
(not the physical device name) will be displayed in system messages that refer to the
device.

Storage and Output of Data

2-3

2.1.3 Generic Device Names
With the commands ALLOCATE and MOUNT, the VAX/VMS system allows you
to specify generic device names in which the controller and/or the unit number is
not specified. When you use a generic device name, the system locates an available
controller or device unit whose physical name satisfies the portions of the generic
device name that are specified. For example, if you issue an ALLOCATE command
and specify only a device type, the ALLOCATE command locates an available unit of
that type.
For all commands except ALLOCATE and MOUNT, the system goes to controller A
if you omit the controller designation; it goes to unit number 0 if you omit the unit
number.

2.2 File Operations on Disks
VAX/VMS disks are structured to let you create and access files through a
hierarchical organization. The higher levels of the hierarchy (all but the end
levels) are specially structured files called directories; the end levels are the data
or program files. The access path (file specification) to a file is through the device
name (identified by the logical name of the disk or the drive on which the volume is
mounted), through a first-level directory, through any subdirectories, and then to the
file.
For example, a disk named CLERK might have a first-level directory named
LICENSES. This directory might have subdirectories named AUTO, DOG, and
MARRIAGE, and a file named SUM1986.DAT;18. The DOG subdirectory might
contain a file named 1986.DAT;32. The access paths to the two end files are as
follows:

CLERK=> LICENSES=> SUM1986.DAT;18
CLERK=> LICENSES=> DOG=> 1986.DAT;32

2.2.1 File Specifications
You identify a file by specifying its access path in the following format (the colon,
brackets, periods, and semicolon are required delimiters):

device:[directory.subdirectory.etc]filename.type;version
NOTE:

Directory specifications are valid only on disks; magnetic tapes do not have
directory structures.

2-4

Storage and Output of Data

Field
device

Meaning
The logical name assigned to the disk or magnetic tape device containing
the file (or the name, logical or physical, of the drive on which it is
mounted)

directory

The name of a first-level directory; 1-39 alphanumeric characters

subdirectory

The names of up to 7 subdirectories (not including the first level
directory, separated by periods; 1-39 alphanumeric characters)

filename

The name of a file; 1-39 characters; can be null

type

The file type; 1-39 characters; can be null

version

The version of the file; a positive integer in the range 1-32767; you can
refer to version numbers in a relative manner by specifying 0 as the
latest (highest numbered) version of the file, -1 as the next most recent
version, -2 as the version before that and so on

You can use any alphanumeric character, the underscore (__), the hyphen (-), and
the dollar sign ($) in file names and file types; however, file names and types must
begin with an alphanumeric character.
The following examples demonstrate the format of a file specification.

CLERK:[LICENSES]SUM1984.DAT;18
I
I
I
I
I
disk
directory
file
type
version
CLERK:[LICENSES.DOG]1984.DAT ;32
I
subdirectory

2.2.1.1 Setting Device and Directory Defaults
You can establish the device name, or the device plus directory name (the
first-level directory and any number of subdirectories), as the first part of future file
specifications by setting your default to that device and/or directory. The default
remains in effect until you enter another SET DEFAULT command.
The following example displays the file CLERK:[LICENSES.DOG]1982.DAT;32.
$ SET DEFAULT CLERK:[LICENSES.DOG]
$ TYPE 1982.DAT;32
Subdirectories are specified by concatenating the subdirectory name to the name
of the directory one level above it. The following example displays the same file
displayed in the preceding example.
$ SET DEFAULT CLERK: [LICENSES]
$ TYPE [.DOG]1982.DAT;32

Storage and Output of Data

2-5

A default device and directory remains in effect until you enter another SET
DEFAULT command. You can display the current default device and directory by
entering the command SHOW DEFAULT. If a new default specification is incomplete,
only that portion specified is replaced.
$ SHOW DEFAULT
CLERK:[LICENSES]
$ SET DEFAULT [MEMOS]
$ SHOW DEFAULT
CLERK:[MEMOS]
If you include only subdirectories as the default, they are appended to the current
default.
$ SHOW DEFAULT
CLERK:[LICENSES]
$ SET DEFAULT [.DOG]
$ SHOW DEFAULT
CLERK:[LICENSES.DOG]
If you specify only the device name, the new default includes the current directory.
$ SHOW DEFAULT
CLERK:[LICENSES]
$ SET DEFAULT WORKDISK:
$ SHOW DEFAULT
WORKDISK:[LICENSES]

2.2.1.2 Using Default File Specifications
In most DCL commands, the file version defaults to the latest (highest numbered)
version for an existing file and to either a version number of 1 or the existing version
number plus 1 for a new file. Exceptions are noted in the command descriptions in
Appendix DCL, as are the default file types taken by certain commands.
When a DCL parameter consists of a list of files, missing fields in a file specifi¬
cation default to the corresponding fields in the preceding file specification, as
demonstrated:
$ COPY CLERK:[LICENSES.DOG]1984.DAT,1982 1980S.DAT
This example copies the latest versions of CLERK:[LICENSES.DOGJ1984.DAT
and CLERK:[LICENSES.DOG]1982.DAT to the file 1980S.DAT in the default
directory. The second file specification (output) parameter receives as defaults
the corresponding fields of the first file specification.
When you want to specify the default file type (as in the example that follows), be
sure to omit the period (which would indicate a null file type).

2-6

Storage and Output of Data

You can revert to the default directory specification in a parameter list by preceding
the file name with a null directory name. The following example copies the
files CLERK:[LICENSES.DOG]1984.DAT and CLERK:[LICENSES]1982.DAT to
CLERK:[LICENSES]SUM1984.DAT. Note that the second (output) parameter
uses the default directory, not the directory in the first input file specification
(exceptions, such as the RENAME command, are noted in the command descriptions
in Appendix DCL).
$ SET DEFAULT CLERK:[LICENSES]
$ COPY [.DOG]1984.DAT.[] 1982 SUM1984

2.2.1.3 Matching Wildcards (* and %)
With some DCL commands, you can substitute an asterisk for all or part of a field in
a file specification. You can also use a percent sign for any single character in a file
specification. The command then applies to all files that satisfy the portion of the file
specification entered. Some examples follow.
$ TYPE CLERK:[LICENSES.DOG]*.*;*
Displays all files in the subdirectory CLERK:[LICENSES.DOG].
$ TYPE CLERK:[LICENSES.DOG]*.*
Displays the latest versions of all files in CLERK:[LICENSES.DOG].
$ TYPE CLERK:[LICENSES.DOG]*.DAT
Displays the latest versions of all DAT files in CLERK:[LICENSES.DOG].
$ TYPE CLERK:[LICENSES.DOG]19*.DAT
Displays the latest versions of all DAT files in CLERK:[LICENSES.DOG] whose file
names begin with the characters 19.
$ TYPE CLERK: [LICENSES.*]*.DAT
Displays the latest versions of all DAT files in all subdirectories one level under
[LICENSES].
$ TYPE CLERK: [*.DOG]*.DAT
Displays the latest versions of all DAT files in all second-level subdirectories named
[.DOG].
$ TYPE CLERK: [LICENSES] 198°/,.DAT
Displays the latest versions of all files with a file name beginning with the digits 198
and ending in any single digit and the file type DAT in the directory [LICENSES].
For files being created or modified from other files, the wildcard character indicates
the substitution of the corresponding field of the first file, as demonstrated in the
following examples:
$ COPY *.DAT *.SAV

Storage and Output of Data

2-7

Copies the latest versions of all DAT files in your default directory to new files in
your default directory with the same name but a file type of SAV.
$ COPY 19*.DAT [SAVE]*.*
Copies the latest versions of all DAT files in your default directory beginning with
the characters 19 to new files with the same names but in the directory [SAVE].
$ COPY [*.D0G]*.*;*

[SAVE.*]*.*;*

Copies all versions of all files in all second-level subdirectories named [.DOG]
(previously created with the CREATE/DIRECTORY command) to subdirectories
under [SAVE] named after the first-level directories of [.DOG].
$ COPY [*.D0G]*.*;*

[SAVE.*.*]*.*;*

Copies all files in the second-level directories named [.DOG] to two levels of
subdirectories under [SAVE] named [first-level-dir.DOG]. The COPY command
creates the necessary subdirectories under the named directory; however, the named
directory (in this case [SAVE]) must already exist.
When used with directory names in output file specifications, at least one wildcard
character (to represent the file name, file type, and version number) must follow a
directory specification.
You can use the asterisk wildcard character in several places in a field of an input file
specification. For example, *19*.DAT means a file name that begins and ends with
anything, but has 19 in the middle.
You cannot use the asterisk wildcard character to specify part of a version number.
The wildcard character applies to the entire field.
The percent sign substitutes for a single character. For example, 198%.DAT means
the latest version of all DAT files in your default directory whose names have four
characters starting with 198.
Note that you can use certain qualifiers to select files from a group of files denoted
by wildcard characters; see Section 2.2.3.5 for a list of such qualifiers.

2.2.1.4 Search Wildcards (... and -)
The ellipsis wildcard character permits you to search down through a hierarchy of
directories, as illustrated in the following examples:
$ TYPE [LICENSES. . J1984.DAT
Displays the latest versions of all files named 1984.DAT in [LICENSES] and all
subdirectories under [LICENSES].
$ TYPE [...DOG]1984.DAT
Displays the latest versions of the file named 1984.DAT in the [.DOG] subdirectory
under your default directory.
$ TYPE [...]1984.DAT

2-8

Storage and Output of Data

Displays the latest versions of all files named 1984.DAT in your default directory and
all subdirectories under your default directory.
$ TYPE [*...]1984.DAT
Displays the latest versions of all files named 1984.DAT in all directories on the
default disk.
$ TYPE [...DOG...]1984.DAT
Displays the latest versions of all files named 1984.DAT in the [.DOG] subdirectory
under your default directory, and all subdirectories under the [.DOG] subdirectory.
$ COPY [...]*.*;* [SAVE
Copies all files in the current directory and all files in the subdirectories under that
directory to the directory named SAVE and subdirectories under the SAVE directory.
The COPY command creates the necessary subdirectories under the named directory;
however, the named directory (in this case [SAVE]) must already exist.
The hyphen wildcard character permits you to search up through directories. Each
hyphen moves you up one directory. You can follow the hyphens with directory
and/or subdirectory names to move down the directory structure on another path.
For the following examples, assume a default directory of [LICENSES.MARRIAGE].
$ TYPE [-]1984.DAT
Displays the latest version of 1984.DAT in [LICENSES]
$ TYPE [-.DOG]1984.DAT
Displays the latest version of 1984.DAT in [LICENSES.DOG]
Specifying one level above a first-level directory (for example, [-], when your default
directory is [LICENSES]) puts you at the level of the master directory for the disk,

[000000].

2.2.2 Directory Operations
The master file directory (or MFD) on a disk volume exists as a file named
000000.DIR;1. Its directory name is [000000]. First-level directories exist as files
named directory.DIR; 1 in the master file directory. For example, the directory
[LICENSES] exists as a file named LICENSES.DIR;1 in [000000]. Subdirectories exist
as files named subdirectory.DIR; 1 in their respective directories or subdirectories. For
example, the subdirectory [LICENSES.DOG] exists as a file named DOG.DIR;l in
the directory [LICENSES]. Subdirectory levels are limited to a depth of 7; that is, the
maximum number of levels, including the first-level directory (but not the master
directory), is 8. The file type and version number of a directory file are always DIR
and 1 respectively. In the following figure, LICENSES and TAXES are first-level
directories.

[000000]

MASTER DIRECTORY:

DEPT.DAT ;31
NEWREGS.TXT;9

DEPT.DAT ;2
DEPT.DAT;1

n n wi
SALES.Dl R; 1

OC/CI. L-' 1 Tl

TOP LEVEL DIRECTORY:

SALES

FEDERAL.LIS:6
STATE.LIS;2

MARRIAI3E.DIR;1

PROPERTY

MARRIAGE

DISTRICTI.DATil
DISTRICT2.DAT ;4
DISTRICT3.DAT :2

CURRENT. DAT;6
FEES.DAT;11
PRIOR1980.DAT;2

FEES.DAT ;4
FEMALE. LIS:6
MALE.LIS:3

SECOND LEVEL DIRECTORY:

2.2.2.1 Displaying Directories

The DIRECTORY command displays the names of the files in a directory. The
following example lists the files in [LICENSES].
$ SET DEFAULT CLERK:[LICENSES]
$ DIRECT0RY/C0LUMNS=1
Directory CLERK:[LICENSES]
AUTO.DIR;1
DOG.DIR;1
MARRIAGE.DIR;1
SUM1984.DAT;38
SUM1985.DAT;3
Total of 5 files.

The display shows us that [LICENSES] contains three subdirectories—[LICENSE
[LICENSES.DOG], and [LICENSES.MARRIAGE]—and data files [LICENSES]SUM
and [LICENSES]SUM1985.DAT;3. The next example (assuming no change in th
default directory) lists the contents of the subdirectory [LICENSES.DOG].

2-10

Storage and Output of Data

$ DIRECTORY/C0LUMNS=1

[.DOG]

Directory CLERK:[LICENSES.DOG]
1984.DAT;38
1984.DAT;37
BITE.LIS;18
Total of 3 files.
To display the names of the first-level directories and files, specify [000000] as
the name in the DIRECTORY command or search up one level from a first-level
directory. Remember that nine of the files contained in [000000] are the structure
files, and must not be deleted (see Section 2.2.4).

2.2.2.2 Creating Directories
The CREATE/DIRECTORY command creates a directory. The following example
creates a first-level directory. (Note that you must have SYSPRV privilege to create a
first-level directory.)
$ SET DEFAULT CLERK:
$ CREATE/DIRECTORY [LICENSES]
The next example creates a subdirectory.
$ SET DEFAULT CLERK:[LICENSES]
$ CREATE/DIRECTORY [.DOG]
The CREATE/DIRECTORY command creates the named directory as a file with a file
type of DIR. For example, DOG.DIR is the file that corresponds to the subdirectory
[.DOG]. A directory name consists of a top-level directory name plus up to seven
concatenated subdirectory names enclosed in square brackets. Each name can
be from 1 through 39 characters and can contain any special characters that file
specifications can contain.

2.2.2.3 Deleting Directories
Before deleting a directory or subdirectory, make sure that it contains no files by
entering the DIRECTORY command.
$ SET DEFAULT [LICENSES.DOG]
$ DIRECTORY

No files found.
You cannot delete a directory containing files. If the directory contains any files,
copy or rename them to another directory (if you want to save them) and delete
them from the directory of interest. If the directory contains subdirectories, check
those subdirectories (copying and deleting their files) and delete the subdirectories.

Storage and Output of Data

2-11

To delete a directory, delete the file containing the directory (the file with the type
DIR in the directory one level above the one being deleted) with the DELETE
command. A directory file is created without delete access to prevent accidental
deletion of the directory. Therefore, you must change the file protection to allow
delete access before you can delete the directory file (see Section 7.2 for more
information about file protection). The following example deletes the subdirectory
[LICENSES.DOG].
$ SET DEFAULT [LICENSES]
$ SET PR0TECTI0N=0WNER:D DOG.DIR
$ DELETE DOG.DIR;1
Remember that the directory files (files with the type DIR) for first-level directories
are under the master directory and may require SYSPRV privilege to delete.
$ SET DEFAULT [000000]
$ SET PR0TECTI0N=0WNER:D LICENSES.DIR
$ DELETE LICENSES.DIR;1
To simplify the deletion of directories, you can create a command procedure that
changes the protection of the directory file and then deletes it.
!

[MAINTENANCE]DELDIR.COM

!
$
$
$

Deletes a directory.
! PI = directory name
SET PR0TECTI0N=0WNER:D ’PI’.DIR
DELETE ’P1’.DIR;1

Once you have created the command procedure, you can create a symbol to invoke
it.
$ D.DIRECTORY == "@W0RK1:[MAINTENANCE]DELDIR"
The following commands will now delete the subdirectory [LICENSES.DOG].
$ SET DEFAULT [LICENSES]
$ D_DIRECT0RY DOG
Refer to Chapter 6 for more information about command procedures.

2.2.3 File Operations
At DCL level, you normally deal with sequential, variable-length text files, although
some commands permit access to indexed files. Your application programs may
permit you to deal with files with other characteristics.

2-12

Storage and Output of Data

2.2.3.1 File Characteristics
A file consists of records, each of which consists of a number of bytes of data. The
primary file characteristics are as follows:
•

File organization—Sequential, indexed, or relative.
The records of a sequential file are arranged one after another in the order of
creation. Records must be read from the file in order. The file must be rewritten
(that is, another file or version of the file must be created) to update it.
The records of an indexed file are arranged randomly and accessed through
one or more indexes. An index contains a portion of each record called a key;
the keys are arranged in sequence from lowest to highest (by binary, numeric, or
ASCII value depending on data type); one key is called the primary key. You can
read a record directly (randomly) by specifying an index and the value of one of
its keys. You can read records sequentially by specifying an index—records are
read in ascending sequence according to the key values for that index, starting
with the current record. You update an indexed file in place by adding, deleting,
or changing records. Indexed files require more space since, in addition to the
data, the indexes must be stored.
The records of a relative file are arranged in fixed-length, numbered cells. The
cell numbers are used to determine the position of the record in the file. As with
indexed files, you can read records sequentially or randomly. Typically, relative
files are created and accessed by programs, rather than from DCL command
level.

•

Record format—Fixed length, variable length, or variable length with fixed
control area (VFC). All records in a fixed-length file are the same size. Records
in a variable-length file vary in size. Records in a VFC file have a fixed-length
header followed by a variable part. Note that VFC record format is not applicable
for indexed files.

•

Data type—Strictly speaking, a file does not have a data type, because programs
processing a file must know how each item in the file is to be interpreted.
However, a file whose records contain all character data (each item is one byte
interpreted according to ASCII conventions) is called a text, or character, file. A
file whose data is formatted as integers, floating-point numbers, object code, or
other non-ASCII data is called a binary file.

•

Carriage control—New line (also known as "implied," "carriage return," or
"CRLF"), FORTRAN carriage control, none, or print. New line places a carriage
return and line feed at the end of each record when it is displayed or printed.
FORTRAN carriage control uses the first character of each record to specify
carriage-control information. "None" does not place carriage-control characters
into a file; if you want to include control characters in the file, you must specify
them as part of the data in the file. Note that the PRINT and TYPE commands

Storage and Output of Data

2-13

interpret carriage-return, line-feed, and form-feed characters embedded in
records. Print carriage control interprets the two bytes of each VFC record as
prefix and postfix carriage-control information.
Files you create using the editor or the CREATE command use new-line carriage
control. Each time you press RETURN, you create a new record. When the file
is printed or typed, each record appears on a new line. Files you create using the
OPEN, WRITE, and CLOSE commands use print carriage control. Each WRITE
command adds a new record (in VFC format) to the file.
•

File size—The size of a sequential file with fixed-length records can be calculated
by multiplying the number of records and the size of each record. Variablelength records require two extra bytes per record, and indexed files require space
for the indexes. In addition to the files themselves, the VAX/VMS system uses
disk space to store directory entries, file headers, and other file-maintenance
information.

You can examine a file's characteristics with the /FULL qualifier of the DIRECTORY
command.
$ DIRECTORY/FULL 1984.DAT
Directory CLERK:[LICENSES.DOG]
1984.DAT;38
File ID
(103,75,0)
[200,200]
Size:
64/66
Owner:
Created:
02-JAN-1984 17:47 Revised 24-MAR-1984 11:28
<No backup done>
Expires:
<None specified> Backup:
File organization:
Sequential
Allocation=66, Extend=0
File attributes:
Global Buffer Count = 0
Variable length
Record format:
Carriage return
Record attributes:
System:RWED, Owner:RWED, Group:RWED, World:RE
File protection:
Access Control List None
Total of 1 file, 64/66 blocks.
The file size of the preceding example indicates that 64 blocks have been used out of
the 66 allocated (file size is the number of actual blocks used of the blocks that have
been allocated). If you are only interested in the size of the file (or several files), use
the /SIZE qualifier. The following example lists the number of blocks used by the
files in one directory.

2-14

Storage and Output of Data

$ DIRECTORY/SIZE
Directory CLERK:[LICENSES.DOG]
1984.DAT;38
1984.DAT;37
BITE.LIS;18
Total of 3 files,

64
62
4
130 blocks.

2.2.3.2 Creating and Modifying Files
The most versatile interactive tool for creating and modifying files is the interactive
editor. Other tools include the following DCL commands.
•

CREATE—Creates a text file from the lines you enter following invocation of the
command:
$ CREATE POUND.LIS
Tag #23, Elmer Doolittle, notified
Tag #37, Arlene Theriault, notified
No tag, light brown, 30 lbs., looks part beagle
[CTRL/Zl

Pressing CTRL/Z signals the end of the file and returns you to DCL command
level. You cannot modify a file with the CREATE command. Also, you cannot
modify a record in the file you are creating once you have pressed RETURN.
•

COPY—Creates a new file from the contents of an old file. The following
example copies FORMAT.TXT to WATER.TXT in the default directory.
$ COPY FORMAT.TXT WATER
The COPY command can duplicate many files at a time. The following example
copies all TXT files in the default directory to another directory.
$ COPY *.TXT;*

[SAVETEXT] *.*;*

Refer to Section 2.2.1.3 for more information about using wildcard characters in
file specifications.
The COPY command can concatenate files. The following example appends
WATER2.TXT to WATER1.TXT (forming a new version of WATER1.TXT) in your
default directory.
$ COPY WATER1.TXT.WATER2.TXT WATER1.TXT
See Appendix DCL for the full set of options and more examples.
•

RENAME—Gives the file a new name, optionally locating it in a different
directory. The following example gives the file FORMAT.TXT the new name
WATER.TXT and moves it from the default directory to another directory.
$ RENAME FORMAT.TXT;3 [SAVETEXT]WATER.TXT

Storage and Output of Data

2-15

Note that after being renamed, the file FORMAT.TXT;3 no longer exists in the
default directory.
You can also create files by writing to files the information normally displayed on the
terminal by TYPE, SHOW, and other commands. To do this, assign SYS$OUTPUT
to a file before entering the display command. (See Section 2.3.4 for information
about system-created logical names.) Specify the /USER_MODE qualifier with
the display command so that SYS$ OUTPUT is deassigned immediately after the
command executes.
$ DEFINE/USER.MODE SYS$OUTPUT DEVICES.LIS
$ SHOW DEVICES
In this example, the display produced by SHOW DEVICES goes to a new text file
named DEVICES.LIS in your default directory, rather than to your terminal. You can
manipulate this data as you can any text file. Most commands have an /OUTPUT
qualifier for this function.
$ DIRECTORY/FULL/OUTPUT=FULL.LIS
The display produced by DIRECTORY goes to a new text file named FULL.LIS in
your default directory.
You can also modify text files with the OPEN, CLOSE, READ, and WRITE
commands, which are normally used in command procedures. To create a file,
you open it for output, perform one or more write operations, and close it. Each
write operation produces one record.
$
$
$
$
$

OPEN/WRITE POUND POUND.LIS
WRITE POUND "Tag #23, Elmer Doolittle, notified"
WRITE POUND "Tag #37, Arlene Theriault, notified"
WRITE POUND "No tag, light brown, 30 lbs."
CLOSE POUND

In the OPEN command, you specify a logical name (in this case, POUND) for the file
and then use that logical name in the WRITE and CLOSE commands. The preceding
sequence of commands creates a new file named POUND.LIS in the default directory
(consisting of three records).
To read a text file, you open it for input, perform one read operation for each record
that you want to read, and close the file. The read operation equates the value of the
record to a symbol of your choice.
$
$
$
$

OPEN POUND POUND.LIS
READ POUND P0UND1
CLOSE POUND
SHOW SYMBOL POUND1
POUND1 = "Tag #23, Elmer Doolittle, notified"

Read each record from the old file and follow the instructions below for the action
you wish to take.
•

No change—write the symbol to the new file.

•

Change—ignore the symbol and write the new contents to the new file.

•

Deletion—ignore the symbol and write nothing.

•

Insertion—process the last current record before locating the new record, and
then write the new record to the new file before reading the next record.

The following example creates a new version of POUND.LIS, changing the third
record and adding a fourth record.
$ OPEN POUNDOLD POUND.LIS ! Open existing file
$ OPEN/WRITE POUNDNEW POUND.DAT ! create new file
$ READ POUNDOLD POUND ! no change
$ WRITE POUNDNEW POUND
$ READ POUNDOLD POUND ! no change
$ WRITE POUNDNEW POUND
$ READ POUNDOLD POUND ! new contents
$ WRITE POUNDNEW "No tag, Charles Crowley, notified"
$ READ POUNDOLD POUND ! additional record
#/,RMS-E-E0F, end of file detected
$ WRITE POUNDNEW "Tag #14, Sam White, notified"
$ CLOSE POUNDOLD
$ CLOSE POUNDNEW

When you open a file for output (/WRITE) and the specified file already exists, a new
version is created. If you specify an existing file by version number (for example,
OPEN/WRITE POUNDNEW POUND.LIS;38), an error condition will result unless
you specify the /APPEND qualifier with the OPEN command. An end-of-file
condition occurs when you try to read beyond the last record in the file. Normally,
you would perform operations such as the above in a loop in a command procedure
(see Chapter 6).

Storage and Output of Data

2-17

2.2.3.3 Examining Files
The following facilities allow you to examine files on line:
•

TYPE command—Displays a file on the terminal. The following example
displays DOGS.DAT.
$ TYPE DOGS.DAT
If more than one file is listed in the TYPE command, the files are displayed in
the order specified; if wildcard characters are used, the files are displayed in
alphabetical order.
To stop the scrolling of the text on the screen temporarily, press the NO SCROLL
key (FI on VT200-series terminals); to resume scrolling, press the NO SCROLL
(FI) key again. To stop the display and return to DCL command level, press
CTRL/Y or CTRL/O.

•

Interactive editor with /READ-ONLY qualifier—Permits you to use interactive
editing commands to move around in a file, and search for specific sequences of
characters. (The /READ-ONLY qualifier prevents you from modifying the file
as you display it.) Control characters are displayed rather than being interpreted
when you use /READ-ONLY, however. For example, the form-feed character
(hexadecimal OC) appears as <FF> rather than producing a form feed.

2.2.3.4 Deleting Files
The DELETE command deletes files and releases the disk blocks they occupy for use
by other files. The command requires you to specify a version number or the asterisk
wildcard character in each file specification, as shown in the following examples:
$ DELETE POUND.LIS;17
Deletes version 17 of POUND.LIS.
$ DELETE POUND.LIS;16,POUND.LIS;17
Deletes versions 16 and 17 of POUND.LIS.
$ DELETE POUND.LIS;*
Deletes all versions of POUND.LIS.
When you delete many files with wildcard characters, you should confirm each
deletion by specifying the /CONFIRM qualifier.
$ DELETE/CONFIRM *.*;*
CLERK:[LICENSES.DOG]1981.DAT;38, delete? [N]:
CLERK:[LICENSES.DOG]BITE.LIS;18, delete? [N]:
CLERK:[LICENSES.DOG]BITE.LIS;17, delete? [N]:
CLERK:[LICENSES.DOG] POUND.LIS;19, delete? [N]:

2-18

Storage and Output of Data

Similarly, you may want to display the names of files as they are deleted; specify the
/LOG qualifier with the DELETE command.
$ DELETE/LOG *.LIS;*
_#/,DELETE-I-FILDEL, CLERK: [LICENSES. DOG] BITE. LIS; 18 deleted (38 blocks)
_#/.DELETE-I-FILDEL, CLERK: [LICENSES.DOG]BITE.LIS; 17 deleted (35 blocks)
_%DELETE-I-FILDEL, CLERK:[LICENSES.DOG]POUND.LIS;19 deleted (5 blocks)
The PURGE command deletes old versions of a file or files, as demonstrated in the
following examples:
$ PURGE
Deletes all but the latest version of each file in the default directory.
$ PURGE/KEEP=2
Deletes all but the latest two versions of each file in your default directory.
$ PURGE WATER.TXT
Deletes all but the latest version of WATER.TXT in your default directory.
Purging sequential files after updating them enables you to retain more free space on
your disk volumes.

2.2.3.5 Common Qualifiers
Typically used with a command that includes a wildcard character in its file
specification, the following qualifiers select files from the group of files specified
by the wildcard characters. You can use these qualifiers with most commands
that manipulate files, including the APPEND, BACKUP, COPY, DELETE, PURGE,
RENAME, and TYPE commands:
•

/BEFORE[=time]—Selects files dated prior to a particular time. Specify one of the
following qualifiers with /BEFORE to indicate the date to be used as the basis for
selection:

Qualifier

Date

/BACKUP

The last backup

/CREATED

Creation

/EXPIRED

Expiration

/MODIFIED

The last modification

Storage and Output of Data

2-19

•

/BY_OWNER[=uic]—Selects files owned by the user with the specified user
identification code (UIC). You can specify either the numeric or alphanumeric
forms of the UIC. (Note that the BACKUP command accepts the /OWNER_UIC
qualifier instead of the /BY_OWNER qualifier.)

•

/CONFIRM—Requests confirmation for each file operation, processing only
those files which you confirm by typing Y. This qualifier is especially useful for
saving files marked for deletion by the DELETE and PURGE commands.

•

/EXCLUDE(=file-spec,...)—Prevents the specified files from being affected by the
command. Wildcard characters are allowed in the file specification.

•

/SINCE[=time]—Selects files dated after a particular time. Specify one of the
following qualifiers with /BEFORE to indicate the date to be used as the basis for
selection:
Qualifier

Date

/BACKUP

The last backup

/CREATED

Creation

/EXPIRED

Expiration

/MODIFIED

The last modification

You can specify time as absolute or as a combination of absolute and delta times,
or as one of the following keywords: TODAY, TOMORROW, and YESTERDAY.
Refer to Section 5.4 for information about specifying the date and time.
In the following example the /SINCE qualifier selects for copying only the files in
the directory [83ACCOUNTS] that have been modified since MAY 15, 1983.
$ C0PY/SINCE=15-MAY-1983/MODIFIED [83ACC0UNTS]*.*

2.2.4 System Directories and Files
The system maintains several special directories for system files. A number of firstlevel files on each volume are reserved for structure information: INDEXF.SYS;1
(index file), BITMAP.SYS;1 (storage bit map), BADBLK.SYS;1 (bad block file),
000000.DIR;1 (master directory), CORIMG.SYS;l (core image file), VOLSET.SYS;l
(volume set list file), CONTIN.SYS;l (continuation file), BACKUP.SYS;1 (backup log
file), BADLOG.SYS;l (pending bad block log file), and QUOTA.SYS;l (disk quota file,
which exists only if disk quotas are enabled). These files are created at initialization
time and updated as the volume is used.

2-20

Storage and Output of Data

In addition, the system disk contains a large number of files for the images,
command procedures, and data required to run the operating system. These files
are in the directories [SYSEXE], [SYSHLP], [SYSLIB], [SYSMGR], and [SYSMSG],
located under the system directory [SYSO] on the system disk. You can refer to
these directories by placing their names after the logical name SYS$SYSROOT, for
example, SYS$SYSROOT:[SYSEXE]. In addition, these directories have special logical
names as described in Section 2.3.

2.3 Logical Names
A logical name is a name that you can use in place of a file specification, part of a
file specification, or another logical name. Logical names serve two main functions:
•

Shorthand and readability—You can define commonly used files, directories,
and devices with short, meaningful logical names. Such names are easier
to remember and type than the full file specifications. Names that you use
frequently can be defined in your login command procedure. Names that most
users on your system use frequently can be defined in the site-specific system
startup command procedure.

•

File independence—You can define logical names to associate input/output
operations with the appropriate files for use in images and command procedures.
For example, if a command procedure references the logical name ACCOUNTS,
you can equate ACCOUNTS to any file on any disk before executing the
command procedure. (System images—commands and utilities—generally
use predefined logical names (see Section 2.3.4) so that you need not explicitly
define them. Logical names defined in MOUNT commands provide device
independence.

The system maintains logical names in logical name tables.

2.3.1 Logical Name Definition
Once you have equated a logical name to one or more equivalence strings, you can
use the logical name to reference those equivalence strings.

Storage and Output of Data

2-21

2.3.1.1 Defining Logical Names
The DEFINE command creates a logical name and associates it with one or more
equivalence names. The following example associates the logical name ACCOUNTS
with the equivalence name WORK1984:[ACCOUNTS].
$ DEFINE ACCOUNTS W0RK1984:[ACCOUNTS]
You can now use the logical name ACCOUNTS in commands to mean the
equivalence name WORK1984:[ACCOUNTS]. If the logical name is part of a file
specification, it must be the first (left) part and must be separated from the rest of the
file specification by a colon. The following example displays the file PAYROLL.DAT
in the directory [ACCOUNTS] on the disk WORK1984.
$ TYPE ACCOUNTS:PAYROLL.DAT
If the equivalence name represents the name of a device (whether it is a physical
device name or is itself a logical name), terminate the equivalence name with a
colon in the DEFINE command. The following command equates the logical name
ACCOUNTS—DISK with the device name WORKDISK.
$ DEFINE ACCOUNTS.DISK WORKDISK:
The following commands may also be used to define logical names.
•

ALLOCATE—Allocates a device for exclusive use and optionally assigns a logical
name for that device.

•

ASSIGN—Associates one or more equivalence names with a logical name.

•

MOUNT—Mounts a volume and assigns a logical name for the volume.

•

OPEN—Associates the specification of the file being opened with a logical name.
(The function of the logical name, in this case, is to identify the file in subsequent
READ, WRITE, and CLOSE commands.)

You can equate more than one logical name with an equivalence string. For example,
you can equate the logical names $TERMINAL and CONSOLE to the physical name
of a terminal so that both logical names translate to the same device. (If you equate
a logical name to more than one equivalence string in a single command, you create
a search list for the system to use to translate the names; see Section 2.3.2.4 for
information about search list translation.)
If you equate a logical name to one equivalence string and then equate the same
logical name to another equivalence string, the second definition supersedes the first.
You can, however, equate the same logical name to different equivalence strings
if the logical name definitions are in different tables (see Section 2.3.3.1). You can
equate the same logical name to different strings in the same table if they are defined
in different access modes (see Section 2.3.3.4).

2-22

Storage and Output of Data

Use care when defining a logical name with an equivalence string that is identical
to a component of a file specification. For example, suppose that a user-created
image exists as a file named CLERK:[USEREXE]DOG.EXE with the requirement that
a logical name DOG be defined before running the image. You enter the following
commands with the intent of defining DOG and running the image.
$ DEFINE DOG CLERK1:[LICENSES.DOG]1984.DAT
$ SET DEFAULT CLERK:[USEREXE]
$ RUN DOG
You do not execute CLERK:[USEREXE]DOG.EXE as intended because the system
translates DOG to be CLERKl:[LICENSES.DOG]1984.DAT.
If you cannot access a file, and the command you are specifying and the file
specification seem in order, check the left-hand component of the file specification
(with SHOW LOGICAL) to be sure that it is not defined as a logical name.

2.3.1.2 Deassigning Logical Names
Logical names in process-private tables and your job table are automatically deleted
when your process terminates. (Section 2.3.3 discusses logical name tables.)
User-mode logical names in your process table are automatically deleted following
the execution of a single image. The following commands explicitly deassign logical
names.
•

DEASSIGN—Deassigns the logical name defined interactively.

•

DISMOUNT—Deassigns the logical name defined when the volume was
mounted.

•

CLOSE—Deassigns the logical name defined when the file was opened.

Note that any logical name defined through the ALLOCATE command is not
automatically deassigned when the device is deallocated. You must deassign it
explicitly with the DEASSIGN command.

2.3.1.3 Displaying Logical Names
The SHOW LOGICAL command displays the iterative translations of a logical name.
$ SHOW LOGICAL ACCOUNTS.DISK
"ACCOUNTS.DISK" = "WORKDISK" (LNM$PROCESS_TABLE)
In this display, LNM$PROCESS_TABLE refers to the logical name table in which the
definition resides (see Section 2.3.3.1).

Storage and Output of Data

2-23

2.3.2 Logical Name Translation
You can substitute a logical name for a file specification or for the leftmost
components of a file specification. In the latter case, terminate the logical name
with a colon when you use it as a reference. The equivalence name for the specified
logical name takes the place of the omitted components. The following examples all
display the file WORKDISK:[ACCOUNTS]1984.DAT.
$ DEFINE ACCOUNTS WORKDISK:[ACCOUNTS]1984.DAT
$ TYPE ACCOUNTS
$ DEFINE ACCOUNTS.FILE WORKDISK:[ACCOUNTS]1984
$ TYPE ACCOUNTS.FILE:.DAT
$ DEFINE ACCOUNTS.DIR WORKDISK:[ACCOUNTS]
$ TYPE ACCOUNTS.DIR:1984.DAT
$ DEFINE ACCOUNTS.DISK WORKDISK:
$ TYPE ACCOUNTS.DISK:[ACCOUNTS]1984.DAT
Note that if you combine a logical name with an explicitly stated file type or version
number only, you must include the period or semicolon, respectively. For example,
if ACCOUNTS is equivalent to DUAl:[ACCOUNTS]1984.DAT, ACCOUNTS:2 is an
invalid file specification. (ACCOUNTS:;2 is valid.) Defaults for the current directory,
the file type (depending on the function being performed), and the version number
are applied as usual after translation.

2.3.2.1 Iterative Translation
You can associate a logical name with one or more equivalence names that are
themselves logical names or that contain logical names. Most system commands and
utilities translate file specifications iteratively (up to 10 times) until all logical names
are resolved. In the following example, ACCOUNTS is translated to WORKDISK:
with the SHOW LOGICAL command.
$ DEFINE ACCOUNTS.DISK WORKDISK:
$ DEFINE ACCOUNTS ACCOUNTS.DISK
$ SHOW LOGICAL ACCOUNTS
"ACCOUNTS" = "ACCOUNTS.DISK"

(LNM$PROCESS_TABLE)

1 "ACCOUNTS.DISK" = "WORKDISK:"

(LNM$PROCESS_TABLE)

Some functions (as noted in the appropriate descriptions) do not translate logical
names iteratively. The SHOW TRANSLATION command, for example, provides
only the immediate equivalence name.
$ DEFINE ACCOUNTS.DISK WORKDISK:
$ DEFINE ACCOUNTS ACCOUNTS.DISK
$ SHOW TRANSLATION ACCOUNTS
ACCOUNTS = "ACCOUNTS.DISK" (LNM$PROCESS_TABLE)

2-24

Storage and Output of Data

2.3.2.2 Noniterative Translation
To prevent an equivalence name from being translated iteratively, define it with the
/TRANSLATION_ATTRIBUTES=TERMINAL qualifier. The VAX/VMS system
does not attempt to translate the equivalence string of a logical name defined
with the TERMINAL attribute. The following example equates the logical name
WORKDISK to the physical name DUAO. If DUAO is later defined as a logical name,
the translation of WORKDISK will nevertheless stop at DUAO.
$ DEFINE/TRANSLATION_ATTRIBUTES=TERMINAL WORKDISK DUAO

2.3.2.3 Concealed Translation of Device Names
A concealed device name causes the logical name for the device to be shown
in system displays rather than the physical name to which the system actually
translates the logical name. To define a device name so that it is concealed in
system displays (except for the SHOW LOGICAL display), specify the
/TRANSLATION _ATTRIBUTES=CONCEALED qualifier with the DEFINE
command.
$ DEFINE/TRANSLATION_ATTRIBUTES=CONCEALED WORKDISK DUA1
Device names are concealed by default with the MOUNT command. You can display
the concealed device name by specifying the associated logical name in a SHOW
LOGICAL command, or by referring to the device name rather than the logical name
(for example, in a DIRECTORY command); otherwise, the system uses the logical
name in displays.

2.3.2.4 Search List Translation
You can specify more than one equivalence string for a logical name in a single
DEFINE command. The order in which you specify the equivalence strings
determines the order in which the system translates the names. The following
example defines the logical name ACCOUNTS to be both WORK1983:[ACCOUNTS]
and WORK1984:[ACCOUNTS]. The subsequent DIRECTORY command searches
the ACCOUNTS directory on the disk named WORK1983 first, and then the
ACCOUNTS directory on the disk named WORK1984.
$ DEFINE ACCOUNTS W0RK1983:[ACCOUNTS].W0RK1984:[ACCOUNTS]
$ DIRECTORY ACCOUNTS:ACME.DAT
Directory W0RK1983:[ACCOUNTS]
ACME.DAT;3
Total of 1 file.
Directory W0RK1984:[ACCOUNTS]
ACME.DAT;1
Total of 1 file.
Grand total of 2 directories, 2 files.

Storage and Output of Data

2-25

If you use a search list with a DCL command that does not accept wildcard characters
in a file specification, the VAX/VMS system uses the search list to translate only until
it finds a valid file specification; that is, the command affects only the first file found.
For example, the RUN command (which does not accept wildcard characters) would
execute only one program in the following example (and, if no file TAX.EXE exists,
would generate a single file-not-found error message).
$ DEFINE ACCOUNTS W0RK1983:[ACCOUNTS].W0RK1984:[ACCOUNTS]
$ RUN ACCOUNTS:TAX.EXE

2.3.3 Scope and Precedence of Logical Names
The VAX/VMS system maintains logical names and their equivalence strings in tables
that are either shareable (across multiple processes) or private to the process that
created them. Of the four default logical name tables (LNM$PROCESS, LNM$JOB,
LNM$GROUP, and LNM$SYSTEM), process is process-private, group and system
are shareable across multiple processes, and job is shareable among the process and
subprocesses in a single job tree.
Logical name tables and the logical name definitions they contain can be:
•

Process-private—Available only to your process and deassigned when you log
out. You should define logical names at this level unless you have a definite
need for other processes to use them. By default, the DEFINE command
creates process-private logical names. Process-private logical names are
defined in the process logical name table LNM$PROCESS (also called
LNM$PROCESS_TABLE). You can define process-private logical names in
your LOGIN.COM command procedure, so that they will be defined for you
each time you log in.

•

Shareable—Available to all processes (or to all processes with the same
group number) in the system. System logical names are usually set up in
SYSTARTUP.COM and are deleted when the system shuts down. Use the
/SYSTEM (or /GROUP) qualifier to define a logical name in the system logical
name table LNM$SYSTEM (or group logical name table, LNM$GROUP);
SYSNAM (or GRPNAM) privilege is required. (Logical names that are
shared among your login process and its subprocesses—but not among other
processes—are defined in the job logical name table LNM$JOB.)

2-26

Storage and Output of Data

2.3.3.1 Logical Name Table Directories
The system maintains the names of logical name tables in logical name table
directories. The names of logical name tables are logical names that either define
tables or translate iteratively to table names; they can be up to 31 alphanumeric
(including the dollar sign and underscore) characters in length. The names of logical
name tables are contained in one of the following directory tables:
•

•

Process directory table—By default, the process logical name table directory
(LNM$PROCESS_DIRECTORY) contains the following logical names when you
log in. Some of the logical names identify logical name tables; others translate
iteratively to logical name tables. All tables catalogued in the process logical
name table directory are private to the process that created them.

Logical Name

Translation

LNM$PROCESS_DIRECTORY

The process directory table

LNM$PROCESS_TABLE

The process logical name table; takes precedence;
the default

LNM$PROCESS

A logical name for the process logical name table
(equivalent to LNM$PROCESS_TABLE)

LNM$GROUP

A logical name for your group logical name table
(equivalent to LNM$GROUPxxx)

LNM$JOB

A logical name for your process tree logical name
table (equivalent to LNM$JOBxxx)

System directory table—By default, the system logical name table directory
(LNM$SYSTEM_DIRECTORY) contains the following logical names when you
log in. Some of the logical names identify logical name tables; others translate
to logical name tables. All tables catalogued in the system logical name table are
shareable.

Logical Name

Translation

LNMSSYSTEM —DIRECTORY

The system directory table

LNM$SYSTEM -TABLE

The system logical name table; requires SYSNAM or
SYSPRV privilege to create or delete logical names
contained in it

LNMSSYSTEM

A logical name for the system logical name table
(equivalent to LNM$SYSTEM_TABLE)

LNMSGROUP—xxx

The group logical name table, where xxx is the
group number; requires GRPNAM or SYSNAM
privilege to create or delete a logical name contained
in it

Storage and Output of Data

2-27

Logical Name

Translation

LNM$JOBxxx

The job logical name table, where xxx is a unique
number for each job tree

LNM$DCL —LOGICAL

A logical name for the search list specified by
LNM$FILE_DEV; the list is LNM$PROCESS,
LNM$JOB, LNM$GROUP, LNM$SYSTEM; the
DCL commands SHOW LOGICAL and SHOW
TRANSLATION use LNM$DCL —LOGICAL to
determine the tables to be searched

LNMSDIRECTORIES

A logical name for the following:
LNM$PROCESS_DIRECTORY and
LNM$SYSTEM_DIRECTORY

LNM$FILE_DEV

A logical name for the following search list:
LNM$PROCESS, LNM$GROUP, LNM$JOB,
LNM$SYSTEM; used by all DCL commands to
translate logical names used to locate files

LNM$PERMANENT_MAILBOX

A logical name that translates iteratively to the
logical name table in which logical names associated
with permanent mailboxes are entered

LNM$TEMPORARY_MAILBOX

A logical name that translates iteratively to the
logical name table in which logical names associated
with temporary mailboxes are entered

Generally, you do not need to change the default logical name table definitions
set up in the directory tables, LNM$PROCESS_DIRECTORY and
LNM$SYSTEM_DIRECTORY. Two reasons for changing the entries in the directory
tables are: (1) to create another logical name table and (2) to change the search order
for file specification logical names by redefining LNM$FILE_DEV.
To display the names defined in a particular logical name table, you can use the
/TABLE qualifier. For example, to display the contents of the system logical name
table, specify:
$ SHOW LOGICAL/TABLE=LNM$SYSTEM
Note that to display the process, job, group, or system tables, you can specify the
corresponding qualifier: /PROCESS, /JOB, /GROUP, and /SYSTEM. The following
command has the same effect as the preceding example.
$ SHOW LOGICAL/SYSTEM
To display an entry in one of the directory tables, you must specify the /TABLE
qualifier. The following example displays the equivalence strings for the logical
name LNM$DCL —LOGICAL.
$ SHOW LOGICAL/TABLE=LNM$SYSTEM_DIRECTORY LNM$DCL_LOGICAL

2-28

Storage and Output of Data

2.3.3.2 Precedence
Identical logical names can exist in more than one table. The logical name that
is used depends on the order in which the logical name tables are searched. For
example, when the system attempts to translate a logical name in order to identify
the location of a file, it uses the logical name LNM$FILE_DEV to provide the list of
tables in which to look for the name. The order in which the tables are listed is
also the order in which they are searched. The precedence order defined by
LNM$FILE_DEV is: (1) process table, (2) job table, (3) group table, (4) system table.
Therefore, if a logical name exists in both the process and the group logical name
tables, the logical name within the process table is used. The following examples
demonstrate the use of the same logical name in process and system tables.
$ DEFINE/SYSTEM ACCOUNTS WORKDISK:[ACCOUNTS]1984.DAT
Defines ACCOUNTS as a system logical name.
$ DEFINE ACCOUNTS WORKDISK:[ACCOUNTS]1982.DAT
Defines ACCOUNTS as a process logical name.
$ SHOW LOGICAL ACCOUNTS
"ACCOUNTS" = WORKDISK:[ACCOUNTS]1982.DAT

(LNM$PROCESS_TABLE)

Displays the logical name that takes precedence.
$ SHOW LOGICAL/SYSTEM ACCOUNTS
"ACCOUNTS" = "WORKDISK:[ACCOUNTS]1984.DAT"

(LNM$SYSTEM_TABLE)

Displays the system logical name.
$ DEASSIGN ACCOUNTS
Deletes the process logical name.
$ SHOW LOGICAL ACCOUNTS
"ACCOUNTS" = "WORKDISK:[ACCOUNTS]1984.DAT"

(LNM$SYSTEM_TABLE)

Displays the logical name that takes precedence.
Multiple tables with the same name may also exist. For example, there may exist
both a process-private and a shareable table called MY_TABLE. The process-private
version always takes precedence over the shareable table in all logical name table
processing. When a logical name, such as LNM$FILE_DEV, is used as a table
name, the logical name is iteratively translated until a list of table names is formed.
During this iterative translation, each name is first translated in the process directory
and, if this translation fails, it is then translated in the system directory. This order
of precedence cannot be changed. As a consequence of this ordering, a logical
name placed in the process directory table for use as a table name will always take
precedence over any identical name residing in the system directory.

Storage and Output of Data

2-29

2.3.3.3 Logical Name Table Creation
The CREATE/NAME—TABLE command creates a logical name table and catalogs it
in one of the directory logical name tables. (Logical names that identify logical name
tables or that translate iteratively to logical name tables must always be entered
into one of the directory logical name tables.) To create a logical name table that is
private to your process, create the table in LNM$PROCESS_DIRECTORY
(the default). If you want the table to be shareable, specify
/PARENT—TABLE=LNM$SYSTEM_DIRECTORY with the CREATE/NAME-TABLE
command. Creating shareable name tables requires SYSPRV privilege or ENABLE
access to the parent table.
The following example creates a process-private logical name table named TAX,
places the definition for the logical name CREDIT in the table, and verifies the
table's creation. (You must specify the /TABLE qualifier with the SHOW LOGICAL
command to display a logical name in any table other than LNM$SYSTEM or
LNM$PROCESS.)
$ CREATE/NAME_TABLE TAX
$ DEFINE/TABLE=TAX CREDIT [ACCOUNTS.1984]CREDIT.DAT
$ SHOW LOGICAL/TABLE=TAX CREDIT
"CREDIT" = "[ACCOUNTS.1984]CREDIT.DAT"

(TAX)

To make the system search a user-created logical name table automatically when
processing file specifications, you must create a process-private version of the default
search list (LNM$FILE_DEV) in LNM$PROCESS_DIRECTORY. To add the created
table's name to the default search list, you can define LNM$FILE_DEV as follows:
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV __$ TAX,LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM
Placing the table's name first specifies that the system search that table first, and so
on in the order of specification.
To delete a logical name table, specify the table that contains it (the system or process
directory logical name table) and the name of the table. Deleting a shareable logical
name table requires DELETE access to the table or SYSPRV privilege. For example,
to delete the logical name table TAX of the preceding example, specify the following
command line:
$ DEASSIGN/TABLE=LMN$PROCESS_DIRECTORY TAX
Note that all logical names in descendant tables (and the descendant tables
themselves) are deleted when a parent logical name table is deleted.

2-30

Storage and Output of Data

2.3.3.4 Access Modes
A logical name has an associated access mode of user, supervisor, executive, or
kernel. The default access mode for the DEFINE command is supervisor; you must
have SYSNAM privilege to create an executive mode logical name.
You can equate the same logical name to different equivalence strings in the same
logical name table by specifying different access modes for each definition. The
following example equates the directory named ACCOUNTS to two different strings
in the process logical name table—one in supervisormode (the default) and one in
usermode.
$ DEFINE ACCOUNTS WORKDISK:[ACCOUNTS]1984.DAT
$ DEFINE/USER.MODE ACCOUNTS WORKDISK:[ACCOUNTS]1984.DAT
Define a logical name in usermode when you want to define it only for the
execution of the next DCL or user image. In the following example, the logical
name ACCOUNTS is automatically deleted after the execution of PAYABLE.
$ DEFINE/USER.MODE ACCOUNTS WORKDISK:[ACCOUNTS]1984.DAT
$ RUN PAYABLE
In looking up logical names, all privileged images and utilities, such as LOGINOUT
and MAIL, bypass the user- and supervisor-mode portions of the system logical name
table (LNM$SYSTEM_TABLE). Therefore, DIGITAL recommends that logical names
for important system components (public disks and directories, for example) be
defined in executive mode, using the DCL command DEFINE/SYSTEM/EXECUTIVE.
This operation requires either the SYSPRV or SYSNAM privilege.

2.3.4 System-Created Logical Names
The system creates a number of logical names for you when you start the system and
when you log in.

2.3.4.1 Process-Permanent Logical Names
The following table lists the logical names automatically created for each process
when you log in. You cannot deassign these logical names. You can redefine them
(by specifying the same name in a DEFINE command), but if the redefined name is
later deassigned, the process-permanent name is reestablished. These logical names
are available to each user of the system at the process level.

Storage and Output of Data

Logical Name

Equivalence Name
Interactive mode

Batch mode

SYS$INPUT (default input stream)

Terminal1

Disk2

SYS$COMMAND (original input stream)

Terminal1

Disk2

SYS$OUTPUT (default output stream)

Terminal1

Disk3

SYS$ERROR (default error message output)

Terminal1

Disk3

2-31

terminal: your terminal
2 Disk: initial input device
3 Disk: initial output device

2.3.4.2 System-Permanent Logical Names
The following table lists the logical names automatically defined when the system
starts up. These names are available to all users of the system at the system level.
Logical Name

Equivalence Name

DBG$INPUT

SYS$INPUT at the process level

DBG$OUTPUT

SYS$OUTPUT at the process level

SYS$ERRORLOG

SYS$SYSROOT:[SYSERR]

SYS$HELP

SYS$SYSROOT :[SYSHLP]

SYS$LIBRARY

SYS$SYSROOT:[SYSLIB]

SYS$MAINTENANCE

SYS$SYSROOT:[SYSMAINT]

SYS$MANAGER

SYS$SYSROOT:[SYSMGR]

SYS$MESSAGE

SYS$SYSROOT:[SYSMSG]

SYS$NODE

Name of your node if you are on a network

SYS$SHARE

SYS$SYSROOT:[SYSLIB]

SYS$SYSDEVICE

System disk (usually SYS$DISK)

SYS$SYSROOT

SYS$SYSDEVICE:[SYSO.]

SYSSSYSTEM

SYS$SYSROOT:[SYSEXE]

SYS$TEST

SYS$SYSROOT:[SYSTEST]

SYS$UPDATE

SYS$SYSROOT:[SYSUPD]

In general, you do not need to redefine process-permanent and system-permanent
logical names. Occasionally, you may wish to redefine SYS$INPUT or SYS$OUTPUT
to redirect terminal input/output. The best practice is to define them with the
/USER_MODE qualifier so that they will automatically revert to their initial
definitions after the next image runs (see Section 2.3.3.4).

Storage and Output of Data

2-32

2.4

Printing Files

To print a file or files, use the PRINT command.
The PRINT command places your print job (all the files to be printed) in a list of
jobs to be printed called the print queue. The following example places a print job
containing three files in the default print queue, SYS$PRINT.
$ PRINT POUND,DOGS.DAT,CAT
Job POUND (queue SYS$PRINT, entry 202) started on SYS$PRINT
The system displays the job name (POUND), the queue name (SYS$PRINT), the job
number (202), and indicates whether the job has started or is pending. Once a job is
submitted, you reference it using the job number. The file types of the files named
in the PRINT command default to LIS or the last explicitly named file type; thus, the
preceding example queues POUND.LIS, DOGS.DAT, and CAT.DAT to SYS$PRINT.
Once the job is queued, it will be printed when no other jobs precede it in the queue
and when the printer is physically ready to print.
A print queue can execute only one job at a time. Print jobs are scheduled for
printing according to their priority, and the job with the highest priority is printed
first. If more than one job exists with the same priority, the smallest job is printed
first (unless the queue was initialized with the /SCHEDULE=NOSIZE qualifier). Jobs
of equal size having the same priority are selected for printing according to their
submission time, where the job submitted earliest is printed first.
The default print queue, SYS$PRINT, is usually initialized and started as part of
the site-specific system startup procedures. The SHOW QUEUE command displays
the queues that have been initialized and the status of your jobs; specify the /ALL
qualifier to see jobs queued for other users. In the following example job POUND is
the only job in the queue SYS$PRINT.
$ SHOW QUEUE/ALL SYS$PRINT
Printer queue SYS$PRINT
Jobname
Username
Entry
POUND

USER

202

Blocks
38

Status
Printing

By default, the job name is the name of the first (or only) file specified in the PRINT
command. Use the job entry number to delete the job from the queue.
$ DELETE/ENTRY=202 SYS$PRINT

Storage and Output of Data

2-33

2.4.1 Controlling a Print Job
Various commands and qualifiers allow you to control print jobs in the following
ways (see Appendix DCL for the complete specifications of each command and
additional qualifiers).
Print Operations
Number of copies
By job
By file
Specified file only
Number of pages
Print features
Flag pages
Type of forms (paper)
Special features
Double-spacing
Page heading

Print Job Commands and Qualifiers
PRINT/JOB_COUNT=n 1
PRINT/COPIES^1
file-spec/COPIES=n 1
PRINT/PAGES=1
PRINT/FLAG^1
PRINT/FORM= 1
PRINT/CHARACTERISTICS^
PRINT/SPACE 1
PRINT/HEADER1

Notification of job execution

PRINT/NOTIFY

Delaying execution of a job
For a specified time
Indefinitely

PRINT/AFTER
PRINT/HOLD

Releasing a delayed job

SET QUEUE/RELEASE/ENTRY

Stopping a print job
Delete job
Stop currently printing
job and begin printing
the next job in the
queue
Stop currently printing
job and requeue it for
printing

DELETE/ENTRY=
STOP/ABORT

STOP/REQUEUE

1 Parallel qualifiers for the SET QUEUE/ENTRY command allow you to specify these operations for
print jobs that are already queued but not yet printing.

Operations that affect print jobs are checked against the R (read) and D (delete)
protection specified for the queue and the owner UIC of the job.

2-34

Storage and Output of Data

2.4.2 Controlling a Print Queue
You must have OPER privilege or have EXECUTE access to a queue to act as an
operator of that queue. See Appendix DCL for access and privilege restrictions on
individual commands described in this section.

2.4.2.1 Stopping and Restarting a Queue
Print queues are usually initialized and started as part of the system startup
procedure. However, in some situations you may need to stop and start a queue
from a running system. After the system has been booted, the START/QUEUE
/MANAGER command must be issued before any other queue commands can be
entered. For example, you may need to stop a queue to change forms or to fix the
printer. The steps involved in stopping and restarting a print queue are as follows:
1.

Enter the STOP/QUEUE/NEXT command—To stop a queue temporarily
(without deleting it). The /NEXT qualifier allows the current job to finish
printing before the queue is stopped. If the /NEXT qualifier is omitted, the
current job is interrupted and the queue "pauses" instead of stopping.
$ STOP/QUEUE/NEXT SYS$PRINT

Wait for current jobs to complete—See the /NEXT qualifier in the previous step.

Do whatever is necessary to the printer—Change forms (paper) or change the
ribbon, for example.

Enter the START/QUEUE command—To restart a print queue that has been
previously initialized.
$ START/QUEUE SYS$PRINT

2.4.2.2 Creating a Print Queue
If you are creating a new print queue, you should spool the printer and initialize
the queue before starting it. (Spooling uses secondary storage to buffer files passing
between slow I/O devices, such as line printers, and the programs that generate
them. This allows the system to produce output as quickly as the disk device allows
instead of at printer speed. When the printer file is closed by the program, the
temporary file spooled to disk is queued for printing.) Spool the printer as shown:
$ SET DEVICE/SPOOLED=SYS$PRINT $TERMINAL1
Use the DCL command INITIALIZE/QUEUE/START to initialize and start
the queue. (The following example assumes that the systemwide logical name
SPRINTER has been assigned to the print device.)
$ INITIALIZE/QUEUE/START/ON=$PRINTER SYS$PRINT
If you initialize and start a printer with one command, you can queue and print jobs
immediately (unless an incompatible print characteristic or form was specified in the
PRINT command). After a queue has been started, you can stop and restart it (with

Storage and Output of Data

2-35

STOP/QUEUE and START/QUEUE respectively) without affecting the jobs in the
queue.

2.4.2.3 Specifying Print Features and Restrictions
The qualifiers you use when you initialize or start a queue allow you to specify
default print features for the queue and to control the jobs that can execute on the
queue.
•

•

Default print features—To assign default print features to a queue, specify the
/DEFAULT qualifier with the INITIALIZE/QUEUE, START/QUEUE, or SET
QUEUE commands and one or more of the following keywords:
BURST

Burst page printed preceding output

FEED

Form feed inserted at end of page

FLAG

Flag page printed preceding output

FORM=type

Default form for a printer, terminal, or server queue

TRAILER

Trailer page printed following output

Print queue restrictions—To restrict the types of jobs that can execute on the
queue, specify one of the following qualifiers with the INITIALIZE/QUEUE,
START/QUEUE, or SET QUEUE commands:
/BLOCK-LIMIT

Restricts by size

/CHARACTERISTIC

Restricts by characteristics

/FORM

Restricts by form (paper)

2.4.2.4 Using the FORM=type Keyword
You can change the default form type for a specific output queue by using the
/DEFAULT=FORM=type option to the DCL command INITIALIZE/QUEUE,
START/QUEUE, or SET QUEUE. The new default form must first be defined
using the DEFINE/FORM=type command. (See the VAX/VMS DCL Dictionary
for a description of the DEFINE/FORM command.)
The stock (type of paper stock) of the default form must be identical to the stock
of the mounted form, or any job submitted without an explicit form will enter a
pending state until they are made identical.
To find out the default form for a particular queue, issue the DCL command SHOW
QUEUE/FULL queue-name. The following example shows the default form for a
queue named LN03$PRINT.
$ SHOW QUEUE/FULL LN03$PRINT
Printer queue LN03$PRINT, on ALPHA::ALPHA$LCAO, mounted form STANDARD (stock=8xl0
/BASE_PRI0RITY=4 /DEFAULT=(FEED,FLAG,FORM=REPORT(stock=8xl0),TRAILER=ONE)
/NOENABLE_GENERIC Lowercase /OWNER=[1,4] /PR0TECTI0N=(S:E,0:D,G:R,W:W)

2-36

Storage and Output of Data

In this example, the default form is named REPORT and the stock is named 8x10.
The stock of the default form matches the stock of the mounted form. All jobs not
associated with an explicit form definition will be associated with the form named
REPORT by default. Since the stock of the form STANDARD matches the stock of
the default form REPORT, all jobs submitted to this queue without an explicit form
definition will be processed.

2.4.3 Using Multiple Print Queues
The number and type of queue that you need depends on the number of printers
your system has and your particular print needs (for instance, whether and how
often you need special print forms). Printer queues can be one of the following types
of queues:
•

Printer queue—A queue assigned to a specific print device.

•

Terminal queue—A printer queue assigned to a hardcopy terminal that is being
used solely as a printer (not interactively).

•

Generic queue—A queue that distributes the processing of jobs to printers with
similar characteristics. Jobs submitted to a generic queue are held in that queue
until one of the assigned printer queues becomes available.

2.4.3.1 One Printer with Multiple Queues
If you want to be able to queue certain jobs (low-priority jobs or jobs requiring
special print forms, for example) for printing during off-peak hours, you can initialize
a queue without starting it. Jobs sent to a queue that is initialized but not started
will not print until you stop the other queue and start this queue. For example, the
following commands initialize and start the first queue, SYS$PRINT, and initialize
but do not start the second queue, LOW-PRIORITY. The first PRINT command
prints the file REG_FILE.DAT on SYS$PRINT; the second PRINT command queues
but does not print the file BIG_FILE.DAT.
$ INITIALIZE/QUEUE/ON=$PRINTER SYS$PRINT/START
$ INITIALIZE/QUEUE/ON=$PRINTER LOW.PRIORITY
$ PRINT REG_FILE.DAT
Job REG.FILE (queue SYS$PRINT, entry 202) started on SYS$PRINT.
$ PRINT BIG.FILE.DAT/QUEUE=L0W_PRI0RITY
Job BIG.FILE (queue L0W_PRI0RITY, entry 3) pending.
To start the second queue so that the jobs queued to it can print, do the following:
$ STOP/QUEUE/NEXT SYS$PRINT
$ SHOW QUEUE SYS$PRINT
Printer queue SYS$PRINT, stopped
$ START/QUEUE L0W.PRI0RITY

Storage and Output of Data

2-37

The STOP/QUEUE/NEXT command stops the queue SYS$PRINT after the current
job finishes printing; use the SHOW QUEUE command to be sure that the job has
finished printing. The START/QUEUE command starts the queue LOW-PRIORITY
so that jobs previously queued to it can print.

2.4.3.2 One Queue with Multiple Printers
If your system has more than one printer of a similar type, you should initialize at
least one generic queue. Because the PRINT command queues jobs to SYS$PRINT
by default, you should initialize SYS$PRINT as the generic queue with the
INITIALIZE/QUEUE/GENERIC command in the system startup procedure,
specifying the generic queues with the /GENERIC qualifier. Queues assigned
to printers that are remote, that use special forms, or that possess unique
printer characteristics should be explicitly disabled as generic queues with the
/NOENABLE—GENERIC qualifier, to prevent them from being assigned to the
generic queue by default. A terminal queue assigned to a generic queue should be
initialized and started with the /TERMINAL qualifier.
In the following example, the print queues PRINTER—1 and PRINTER—2 are
initialized and then assigned to the generic queue SYS$PRINT.
$ INITIALIZE/QUEUE/ON=LPAO: PRINTER.1/START
$ INITIALIZE/QUEUE/ON=LPBO: PRINTER.2/START
$ INITIALIZE/QUEUE SYS$PRINT/START/GENERIC=(PRINTER.l,PRINTER.2)

2.5 Sorting and Merging Files
The SORT and MERGE commands let you combine and reorder files at the DCL
command level. The SORT command reorders records in a file (or files) so that
they are in alphabetic or numeric order, either low to high (ascending) or high to
low (descending), according to a portion of each record called the key. The MERGE
command combines up to 10 sorted files into one ordered output file.

2.5.1 Record Sorting
Record sorting, the default type of sort operation, keeps records intact and produces
an output file consisting of complete records. The following example demonstrates
an ascending (the default) record sort based on that portion of each record starting at
character position 8 and extending to the end of the record (the name).
$ S0RT/KEY=(P0SITI0N=8,SIZE=15) EMPLOYEE.LST BYNAME.LST

2-38

Storage and Output of Data

- EMPLOYEE.LST B
A
C
A
B

7828
7933
8102
8042
7951

- BYNAME.LST A
C
B
B
A

MCMAHON JANE
ROSENBERG HARRY
KNIGHT MARTHA
BENTLEY PETER
LONG FRANK

8042
8102
7951
7828
7933

BENTLEY PETER
KNIGHT MARTHA
LONG FRANK
MCMAHON JANE
ROSENBERG HARRY

ZK-1748-84

The next example sorts the same file in descending order using positions 3 through 6
(the number) as the key.
$ S0RT/KEY=(P0SITI0N=3,SIZE=4,DESCENDING) EMPLOYEE.LST BYNUMBER.LST
- EMPLOYEE.LST B
A
C
A
B

7828
7933
8102
8042
7951

- BYNUMBER.LST -

MCMAHON JANE
ROSENBERG HARRY
KNIGHT MARTHA
BENTLEY PETER
LONG FRANK

C
A
B
A
B

8102
8042
7951
7933
7828

KNIGHT MARTHA
BENTLEY PETER
LONG FRANK
ROSENBERG HARRY
MCMAHON JANE

ZK-1749-84

The first parameter of the SORT command names the file or files to be sorted.
Multiple files are treated as one large file for sorting purposes. The second parameter
provides a name for the ordered output file that the sort will create. The following
example sorts the records in two files, EMPLOYEE.LST and EMPLOYER.LST, and
creates the ordered output file BYNAME.LST.
$ SORT EMPLOYEE.LST,EMPLOYER.LST BYNAME.LST

2.5.1.1 Single Key
By default, the SORT command assumes a key field that begins in the first position
of a record, that includes the entire record, and that will be sorted in ascending
order. Use the /KEY qualifier to specify characteristics of the key field other than
those assumed by default. In the following example, the /KEY qualifier specifies that
the key starts in position 8 and is 15 characters in length.
$ SORT/KEY=(P0SITI0N=8,SIZE=15) EMPLOYEE.LST BYNAME.LST

(If an actual key would have to extend beyond the end of the record to meet the size
specification—for example, if the key is the last item in a variable-length format—the
missing characters are treated as nulls.)

Storage and Output of Data

2-39

2.5.1.2 Multiple Keys
You can specify more than one key (up to a limit of 255) and each key can be
ascending or descending. Specify multiple keys in their order of priority. For
example, the following command sorts records first on the value of position 1 in
descending order, then on the value of positions 8 through 27 (or the end of the
record) in ascending order.
$ S0RT/KEY= (POSITIONS, SIZE=1,DESCENDING) _$ /KEY=(P0SITI0N=8,SIZE=15) _$ EMPLOYEE.LST DEPTNAME.LST
The results of the sort specified in the preceding example are as follows.
- EMPLOYEE.LST B
A
C
A
B

7828
7933
8102
8042
7951

MCMAHON JANE
ROSENBERG HARRY
KNIGHT MARTHA
BENTLEY PETER
LONG FRANK

-DEPTNAME.LSTC
B
B
A
A

8102
7951
7828
8042
7933

KNIGHT MARTHA
LONG FRANK
MCMAHON JANE
BENTLEY PETER
ROSENBERG HARRY

ZK-1764-84

By default, records with identical keys are kept but not sorted predictably. To
retain identical keys and arrange them according to the input file order, specify
the /STABLE qualifier. To eliminate duplicate keys, specify the /NODUPLICATES
qualifier.

2.5.2 Other Types of Sorting
In addition to record sorting, you can perform the following types of sorts.
•

Tag sort—Sorts the keys only and then rereads the input file to produce an
output file of complete records. The net result is the same as for a complete
record sort. A tag sort is useful if disk space is at a premium, because it typically
uses less scratch file space. Time may be saved if the records are large but the
keys are relatively small. Specify the /PROCESS=TAG qualifier with the SORT
command to generate a tag sort.

•

Address sort—Sorts the keys only and produces an output file of record
addresses (RFAs) in binary format. An address sort is faster than a record
sort, but you must write a program to associate the record addresses with the
records of the input file. Specify the /PROCESS=ADDRESS qualifier to generate
an address sort.

2-40

•

Storage and Output of Data

Indexed sort—Sorts the keys only and produces an output file of keys and
record addresses (RFAs). The addresses are in binary format. An index sort is
faster than a record sort, but you must write a program to associate the record
addresses with the records of the input file. Specify the /PROCESS=INDEX
qualifier to generate an index sort.

2.5.3 Character Data Files
The SORT command assumes by default that the files to be sorted contain character
data. ASCII is the default collating sequence for character data. You can specify
EBCDIC to generate an output file that is ordered in EBCDIC sequence (although it
remains in ASCII representation). In general, ASCII orders numbers (0 through 9)
first, then uppercase letters (A through Z), and then lowercase letters (a through z).
The multinational collating sequence collates according to the international character
set defined by DIGITAL (see Appendix CHAR). The multinational collating sequence
compares for different characters first, then for different diacritical forms of the
same character (formed by using diacritical marks as part of "compose sequences"
on VT200 series terminals), and then for different cases (uppercase or lowercase)
of the same character. To use the multinational collating sequence, specify the
/COLLATING _SEQUENCE=MULTINATIONAL qualifier.

NOTE:

Use caution when using the multinational collating sequence to sort
or merge files for further processing. Sequence checking procedures in most
programming languages compare numeric characters. Because the multinational
sequence is based on actual graphic characters (and not the codes representing those
characters), normal sequence checking will not work.

2.5.4 Noncharacter Data Files
If you sort files containing items other than character data, you must specify the data
type of each key. Also, you must take care in calculating starting positions and sizes,
as the items being compared may occupy more than one byte. For example, if you
are sorting a file that contains 20 characters followed by 3 floating-point numbers in
F floating format, and the key is the last floating-point number, you must make the
following specification:
$ S0RT/KEY=(P0SITI0N=29,F_FL0ATING) STATS.RAW STATS.SOR
The character data occupies positions 1 through 20 (20 characters), the first F
floating-point number occupies position 21 through 24, the second F floating-point
number occupies positions 25 through 28, and the third F floating-point number
occupies positions 29 through 32. The size of the floating-point number is not
specified (since it is fixed at 4 bytes).

Storage and Output of Data

2-41

2.5.5 Terminal Input
To enter the input records for a SORT or MERGE operation from your terminal,
specify SYS$INPUT as the input file parameter, qualifying it with the size of the
longest record (in bytes) and the approximate size of the input file (in blocks).
After you enter the command, enter the input records. Terminate each record
by pressing RETURN and terminate the file by pressing CTRL/Z. The following
example demonstrates a sort operation in which the input comes from the terminal.
$ SORT/KEY=(P0SITI0N=8,SIZE=15) _$ SYS$INPUT/FORMAT=(REC0RD_SIZE=22,FILE_SIZE=10) BYNAME.LST
B 7828 MCMAHON JANE
A 7933 ROSENBERG HARRY
C 8102 KNIGHT MARTHA
A 8042 BENTLEY PETER
B 7951 LONG FRANK
1 CTRL/Z |

2.5.6 Output File Organization
You must specify the file organization of the output file of a SORT or MERGE
operation if that organization differs from that of the input file. Assume, for example,
that EMPLOYEE.LST is an indexed file and you wish the output file produced by the
sort to be a sequential file.
$ S0RT/KEY=(P0SITI0N=8,SIZE=15) _$ EMPLOYEE.LST BYNAME.LST/SEQUENTIAL
If the organization of the output file is indexed, the file must already exist and be
empty. You must also qualify the output file parameter with /OVERLAY.
To change the format and order of the records in the output file, use a specification
file; see Section 2.5.8 for information on specification files.

2.5.7 Batch Job Submission
If you are sorting large files, submission of the sort as a batch job is advisable since
the sort will require some time. If the input is a file, the command procedure you
submit must contain the SORT command and either set your default directory or
include the directory in the file specifications.
$ SUBMIT S0RTJ0B
! SORTJOB.COM
!
$ SET DEFAULT [USER.PER]
$ S0RT/KEY=(P0SITI0N=8,SIZE=15)EMPLOYEE.LST BYNAME.LST

2-42

Storage and Output of Data

You can include the input records in the batch job by placing them after the sort
command, one record per line.
$ SUBMIT SORTJOB
! SORTJOB.COM
i

$ SET DEFAULT [USER.PER]
$ S0RT/KEY=(P0SITI0N=8,SIZE=15)SYS$INPUT/F0RMAT=(REC0RD_SIZE=22,FILE_SIZE=10)BYNAME.LST
B 7828 MCMAHON JANE
A 7933 ROSENBERG HARRY
C 8102 KNIGHT MARTHA
A 8042 BENTLEY PETER
B 7951 LONG FRANK
As with terminal input, specify the input file parameter as SYS$INPUT and qualify it
with the record size (in bytes) and the approximate file size (in blocks).

2.5.8 Specification Files
Specification files allow you to:
•

Create or modify a collating sequence

•

Reformat records in the output file

•

Conditionally select key and data fields

Create a specification file with the CREATE command or the editor; the default file
type of a specification file is SRT. List in the file the qualifiers and keywords that
define the sort or merge operation you desire. (See the /SPECIFICATION qualifier
of the SORT or MERGE commands in Appendix DCL for a complete list of the
qualifiers allowed in a specification file.) The order of qualifiers matters only when
you are sorting and specifying more than one key field, when you are describing
output format, and when you are defining multiple record types. (In these cases, the
order in which you specify qualifiers is the order in which they are processed.) Begin
comments with an exclamation point.
To use a specification file, include the /SPECIFICATION qualifier in the SORT or
MERGE command line as follows:
$ S0RT/SPECIFICATI0N=NAME_SPEC BY_NUMB.DAT BY_NAME.DAT
Any DCL command qualifiers override corresponding qualifiers in the specification
file.

Storage and Output of Data

2-43

2.5.8.1 Creating or Modifying a Collating Sequence
You can create or modify a collating sequence by including the
/COLLATING-SEQUENCE qualifier in the specification file.
•

Modifying a collating sequence—To modify a collating sequence, specify the
MODIFICATION option with the /COLLATING-SEQUENCE qualifier. For
example, to modify the ASCII sequence so that the string "MC" is treated as the
equivalent of the letter "M," include the following qualifier in a specification file.
/COLLATING_SEQUENCE=(SEQUENCE=ASCII,
MODIFICAT10N=(M MC M = "M"),
IGN0RE=("’").FOLD)

The IGNORE option in the preceding example specifies that the apostrophe
be ignored during the sort or merge (that is, the next character is collated).
The FOLD option specifies that uppercase and lowercase letters be treated as
equivalents. (The multinational collating sequence folds lowercase letters into
uppercase letters by default.) Because the FOLD, MODIFICATION, and IGNORE
options are processed in the order in which they are specified, you should
generally specify the FOLD option last to ensure that the MODIFICATION and
IGNORE options affect uppercase and lowercase characters.
•

Creating a collating sequence—To define a collating sequence, specify the
sequence as a string of characters, single or double, or a range of single characters
in the order of priority. You must specify in the sequence all characters that
appear in the key field; characters not specified by the sequence are ignored
(unless you specify them with the FOLD or MODIFICATION options). Enclose
each character or string in quotation marks and separate them with commas. The
following example defines a collating sequence that sorts only records beginning
with the letters A, B, and C.
$ SORT/COLLATING_SEQUENCE=(SEQUENCE=("A"."B","C"))

2-44

Storage and Output of Data

2.5.8.2 Reformatting Records in the Output File
By default, the record format of an output file is the same as that of the input file.
To eliminate or reorder fields in your output file, first name the appropriate fields
and then specify each field by name in a /DATA qualifier in the specification file.
The order in which you specify the /DATA qualifiers is the order in which the fields
appear in the output file. You must specify each field that you want to appear. For
example, you could alter the following record format with the qualifiers below:
B 7828 MCMAHON JANE
A 7933 ROSENBERG HARRY
C 8102 KNIGHT MARTHA
A 8042 BENTLEY PETER
B 7951 LONG FRANK
/FIELD=(NAME=LETTER,POSITIONS,SIZE=1)
/FIELD=(NAME=FULLNAME,POSITIONS,SIZE=15)
/KEY=FULLNAME
/DATA=LETTER
/DATA=M "
/DATA=FULLNAME

Note that /DATA-' " in the preceding example inserts a space between the letter and
surname fields of each record.

2.5.8.3 Conditionally Selecting Key and Data Fields
You can select fields conditionally by first defining the condition in a /CONDITION
qualifier and then specifying the condition in an /INCLUDE, /OMIT, /KEY, or
/DATA qualifier. Use one of the following operators to define the condition test:
EQ, NE, GT, GE, LT, or LE (and optionally AND or OR). For example, to omit all
records containing the letter C in the first field (LETTER) of the preceding example,
you could define the condition to be the existence of the letter C in that field and
then specify the /OMIT qualifier for all occurrences of that condition, as follows:
/FIELD=(NAME=LETTER,POSITIONS,SIZE=1)
/FIELD=(NAME=SURNAME,P0SITI0N=8,SIZE=15)
/KEY=SURNAME
/DATA=LETTER
/DATA=SURNAME
/C0NDITI0N=(NAME=LETTER_C,TEST=(LETTER EQ "C"))
/0MIT=(C0NDITI0N=LETTER_C)

Storage and Output of Data

2-45

2.5.9 Merging Files
The MERGE command combines up to 10 sorted files (that is, the input files must be
in order) into one ordered output file. The input files must have the same format and
must have been sorted on the same key fields. The following example demonstrates
the merging of two files based on that portion of each record starting at position 8
and extending to the end of the record (the name).
$ MERGE/KEY=(P0SITI0N=8,SIZE=15) BYNAME1.LST,BYNAME2.LST BYNAME3.LST
BYNAME1.LST •
A
C
B
B
A

8042
8102
7951
7828
7933

BENTLEY PETER
KNIGHT MARTHA
LONG FRANK
MCMAHON JANE
ROSENBERG HARRY

BYNAME2.LST
C 7212 KRAMER KARL
C 8323 NORTON FLORENCE
A 8240 TROUT SAM

BYNAME3.LST
A
C
C
B
B
C
A
A

8042
8102
7212
7951
7828
8323
7933
8240

BENTLEY PETER
KNIGHT MARTHA
KRAMER KARL
LONG FRANK
MCMAHON JANE
NORTON FLORENCE
ROSENBERG HARRY
TROUT SAM

ZK-1771-84

By default, MERGE does sequence checking to ensure the input files are in order.
The sequence check stops the merge if a record is found to be out of order. To
prevent sequence checking during the merge, specify the /NOCHECK_SEQUENCE
qualifier.

2.6

Using Libraries

A library is a specially formatted file in which you store data in units called modules.
System-defined libraries include object, shareable image, macro, help, and text
libraries. Various system components process libraries. The HELP command, for
example, displays information according to the contents of help libraries. Unless you
are programming, you typically use only help and text libraries. (For the complete
specifications of the LIBRARY command, see Appendix DCL.)

2-46

Storage and Output of Data

2.6.1 Creating Text Libraries
A text library stores modules that contain lines of text. Each text file inserted into the
library corresponds to one library module. A text library has a default file type of
TLB; an input file to a text library has a default file type of TXT. Specify the /TEXT
qualifier with the LIBRARY command to identify a text library.
Use the /TEXT and /CREATE qualifiers to create a text library. The following
command creates a text library named MEMO.TLB.
$ LIBRARY/TEXT/CREATE MEMO
When you create a library, you can optionally specify a file or a list of files that
contain modules to be placed in the library. You can also exceed the default limit
of 31 characters per text module name by specifying the size of the longest module
name with the KEYSIZE option of the /CREATE qualifier. (See Section 2.6.2 for an
example of the KEYSIZE option.)

2.6.2 Creating Help Libraries
A help library stores modules of specially formatted lines of text. A help source file
can contain any number of modules; every level-1 line starts a new library module.
A help library has a default file type of HLB; a help source file has a default file type
of HLP. Specify the /HELP qualifier with the LIBRARY command to identify a help
library.
Use the /HELP and /CREATE qualifiers to create a help library. When you create
a library, you can optionally specify a file or a list of files that contain modules to
be placed in the library. For example, the following command creates a help library
named HELPLIB.HLB (first parameter) from a source help file named HELPLIB.HLP
(second parameter).
$ LIBRARY/HELP/CREATE HELPLIB HELPLIB
The /CREATE qualifier allows you to exceed the default limit of 15 characters per
module name by specifying the size of the longest module name with the KEYSIZE
option. If the number of modules exceeds 256, specify the number (or a larger
number to give yourself some leeway) with the MODULES option. The following
example makes use of both options.
$ LIBRARY/HELP/CREATE=(KEYSIZE:19,MODULES:400) _$ HELPLIB HELPLIB

Storage and Output of Data

2-47

2.6.2.1 Creating Help Modules
Source files for a help library are formatted so that each module is a topic for the
HELP command. Within each module, the text is arranged in levels: typing HELP
level-1-name obtains all the information under the level-1 topic plus the names of the
level-2 topics; typing HELP level-1-name level-2-name obtains all the information
under the level-2 topic plus the names of the level-3 topics; and so on. In addition,
information about qualifiers (topics whose names begin with a slash) can be obtained
discretely even though the qualifiers are not numbered as topics. The name of the
level-1 topic is the name of the module.
A source help file can contain any number of modules. The general format of each
module is as follows:
1 module-name
first-level-text ...
2 topic-name
second-level-text ...
(lower-level modules as desired)
2 topic-name
second-level-text

...

(more second-level and lower modules as desired)

Observe the following rules in formatting modules in source help files:
•

Module levels—Lower-level topics are logically under the higher-level topics that
they physically follow. Level numbers must be one digit in column 1; no other
number (for example, a number that is part of the text) must be in column 1.

•

Qualifiers—A line beginning with a slash is treated as a separate topic at the
same level as the level number it physically follows.

•

Module names—A module name (that is, a first-level topic name) is restricted to
the number of characters specified for the key size when the library is created or
compressed (the default is 15 characters). In addition, the module name can only
contain alphanumeric characters, the underscore, the dollar sign, and the hyphen.
Extra characters, and all characters following an invalid character, are truncated
from the module name. (For example, if you specify CREATE/DIRECTORY as
a first-level topic, the module name will be taken as CREATE—all characters
starting with the slash are truncated. If you specify CREATE—DIRECTORY as
the module name and the key size for the library is 15, the module name will be
taken as CREATE-DIRECTOR.)

•

Comments—Lines with an exclamation point in column 1 are interpreted as
comments.

You should give your source help file a file type of HLP. If the source file represents
the entire contents of the library, give it the same name as the library. If the source
file represents part of the contents of the library, give it a meaningful name for those
contents. The following example represents a source help file named CREATE.HLP,
which contains two modules.
CREATE.HLP
1 CREATE
Creates a sequential text file (or files). Specify the
content of the files on the lines following the
command, one record per line. In interactive mode,
terminate the file input with CTRL/Z.
Format
CREATE file-spec [,...]
2 Parameters
file-spec
Specifications of the files being created. No
wildcards are allowed.
2 Qualifiers
/LOG
/NOLOG (default)
Displays the file specification of each new file created.
1 CREATE.DIRECTORY
Creates one or more new directories or subdirectories.
F ormat
CREATE/DIRECTORY directory-spec [,...]
2 Parameters
directory-spec[,...]
Disk device (optional) and name of new directory or
subdirectory. No wildcards are allowed.
2 Qualifiers
/DIRECTORY
Indicates creation of a directory rather than a file.
This qualifier is required.
/LOG
/NOLOG (default)
Displays the directory specification of each directory
created.

Storage and Output of Data

2-49

2.6.2.2 Naming Help Libraries
If you intend the help library to be the main help library for your system, give it a
file name of HELPLIB. Otherwise, give it a meaningful name that corresponds to its
contents. The following example creates a help library named PAYABLE.HLB from a
source help file named PAYABLE.HLP.
$ LIBRARY/HELP/CREATE PAYABLE PAYABLE
The /LIBRARY qualifier of the DCL command HELP allows you to search another
library in place of the default libraries.

CAUTION: Place site-specific help in separate libraries that are defined as
logical names (HLP$LIBRARY_1, HLP$LIBRARY_2, etc.) in SYSTARTUP.COM.
Do NOT place site-specific help in the system library provided by VAX/VMS
(SYS$LIBRARY:HELPLIB.HLB) as it could interfere with VAX/VMS updates and
layered-product installations.

2.6.3 Displaying Libraries
The /LIST qualifier displays information concerning the library and lists the modules
in the library. The /LIST/FULL qualifiers list additional information on each module.
The following example displays information on and the contents of the library
MEMO.TLB.
$ LIBRARY/TEXT/LIST MEMO
Directory of TEXT library AC:[MEMOS]MEMO.TLB;1 on 15-APR-1986 16:21:41
Creation date: 10-APR-1986 21:34:40 Creator:
VAX-11 Librarian V-04-00
Revision date: 10-APR-1986 21:43:46 Library format:
4.0
Max. key length:
31
Number of modules:
67
Other entries:
0
Preallocated index blocks:
7
Recoverable deleted blocks:
0
Total index blocks used:
4
Max. number history records:
20
Library history records:
4
AIR1

WATER3
You can display a history of the updates performed on the library by specifying
/HISTORY with /LIST. Each history record identifies the user who performed the
update, the number of modules affected, and the date of the update. A specification
of /LIST/HISTORY/FULL names the modules that were inserted or deleted.
You can limit the modules displayed with the /ONLY qualifier. The following
example lists only those modules whose names begin with WATER in the library
MEMO.TLB.
$ LIBRARY/LIST/ONLY=WATER* MEMO

2-50

Storage and Output of Data

You can redirect the display to a file (the default for the output is SYS$OUTPUT)
by specifying the name of the file with the /LIST qualifier. The following example
stores the library display in a file named MEMO.LIS.
$ LIBRARY/TEXT/LIST=MEMO/FULL MEMO
To examine the contents of a module or modules, use the /EXTRACT qualifier. The
following example displays on SYS$OUTPUT the contents of the module WATER2
in the library MEMO.TLB.
$ LIBRARY/TEXT/EXTRACT=WATER2/0UTPUT=SYS$0UTPUT MEMO

2.6.4 Deleting Libraries
To delete a library, use the DELETE command, as shown:
$ DELETE MEMO.TLB;1
Be sure, however, that you no longer need the contents of the library or that
you have converted the library back to source files with the /EXTRACT qualifier.
Otherwise, you may accidentally delete a large amount of data.

2.6.5 Adding Library Modules
You can add modules to a library at creation time by specifying the source files as
the second parameter. (The first parameter is the name of the library.) The following
example creates the library MEMO.TLB and inserts the modules named WATER1,
WATER2, and AIR1 (contained in files named WATER1.TXT, WATER2.TXT, and
AIR1.TXT) in the library.
$ LIBRARY/TEXT/CREATE MEMO WATER1.WATER2,AIR1
To add new modules to an existing library, use the /INSERT or /REPLACE qualifier.
The /INSERT qualifier does not add a module if a module with the same name
already exists in the library (instead an error message results). The /REPLACE
qualifier, the default, inserts the module if the module does not already exist in
the library or replaces the module of the same name if it does exist. The following
example adds the module WATER3 (contained in the file WATER3.TXT) to the library
MEMO.TLB, replacing any modules of the same name in the library.
$ LIBRARY/TEXT/REPLACE MEMO WATER3

Storage and Output of Data

2-51

2.6.6 Deleting Library Modules
To delete a module from a library, specify the module name (not the file name) with
the /DELETE qualifier. The following example deletes the module WATER3 from
the library MEMO.TLB.
$ LIBRARY/TEXT/DELETE=WATER3 MEMO
You can use a wildcard character to delete a group of modules, as shown in the
following example, which deletes all modules beginning with the letters PAY from
the library HELPLIB.HLB.
$ LIBRARY/HELP/DELETE=PAY* HELPLIB
Deleting modules from a library does not reduce the size of the library file. The
space used by the deleted modules remains unused until new modules requiring it
are added. You can recover the free space generated by the deletions by creating
another library file with the /COMPRESS qualifier.
$ LIBRARY/HELP/DELETE=(CREATE,CREATE.DIRECTORY)_$ /COMPRESS HELPLIB
$ PURGE HELPLIB.HLB
The REDUCE option of the /DATA qualifier further compresses the text of the
library. Libraries in reduced format require less disk space but take slightly longer to
access.

2.6.7 Modifying Library Modules
To modify a module or modules in a text library, take the following steps:
1.

Extract the module from the library with the /EXTRACT qualifier of the
LIBRARY command.

Make the necessary edits to the module.

Return the modules to the library with the /REPLACE qualifier of the LIBRARY
command.

The following example modifies the module WATER3 in the library MEMO.TLB.
$ LIBRARY/TEXT/EXTRACT=WATER3/OUTPUT=WATER3 MEMO
$ EDIT WATER3.TXT
editing session
$ LIBRARY/TEXT/REPLACE MEMO WATER3
$ DELETE WATER3.TXT;*

2-52

Storage and Output of Data

Note that the module is named as part of the /EXTRACT qualifier and that it is the
name of the module, not the file containing the module. The /OUTPUT qualifier
names the file produced by the /EXTRACT operation; if you omit /OUTPUT, the
file is named after the library, for example, MEMO.TLB. Once you have replaced the
modules, you can delete the source file.
To make wholesale changes to a library (for example, to make a change that affects
all commands in a help library), re-create a library by taking the following steps:
1.

Extract all the modules. Create a source file that represents the entire contents of
the library by specifying /EXTRACT=*. Do not use the /OUTPUT qualifier. The
name of the source file will be the same as the library (but the file type will be
HLP or TXT). The following example extracts all the modules from HELPLIB.HLB
and creates a source help file named HELPLIB.HLP from them.
$ LIBRARY/HELP/EXTRACT=* HELPLIB

Edit the source help file. Add, delete, and change modules in the source help file
as you see fit.

Create a new library. Create a new library with the original name, using the
edited source file as input, and purge the old library file.
$ LIBRARY/HELP/CREATE HELPLIB HELPLIB
$ PURGE HELPLIB.HLB

2.7 Transferring Files Between Systems
You can move files between your system and another system by prefixing file
specifications with the node name of the other system and a double colon.
For example, the following command displays on your terminal screen the file
CLERK:[ACCOUNTS]FY83.SUM from the system whose node name is EBONY.
$ TYPE EBONY::CLERK:[ACCOUNTS]FY83.SUM
You can define a node name plus a device name, or a node name plus a device and
directory name, as a logical name. The following example equates the logical name
ACCOUNTS to a partial file specification and then uses the logical name in place of
that portion of the file specification.
$ DEFINE ACCOUNTS EBONY::CLERK:[ACCOUNTS]
$ TYPE ACCOUNTS:FY83.SUM
If the name of the file on the other system is not a valid VAX/VMS file specification,
enclose it (starting after the double colon) in quotation marks; the quotation marks
prevent the local VAX/VMS system from performing syntax checking or logical name
translation.
$ TYPE EBONY::"$FY1984.SUMMARY"

Storage and Output of Data

2-53

The SHOW NETWORK command lists the systems available to your node if it is a
routing node. (If your local node is a nonrouting or end node, you will receive a
message to that effect.)

2.7.1 Reading Files from Another System
Use the COPY command to move files from another system to your system, as
demonstrated in the following examples:
$ COPY EBONY::CLERK:[ACCOUNTS]FY83.DAT *
Moves the latest version of CLERK:[ACCOUNTS]FY83.DAT on the system EBONY
to a file named FY83.DAT in your default directory.
$ COPY EBONY::CLERK:[ACCOUNTS]*.* *
Moves the latest versions of all files in CLERK:[ACCOUNTS] on the system EBONY
to files with the same names in your default directory.
You can also use the DIRECTORY, PRINT, READ (with OPEN and CLOSE), and
TYPE commands to examine files on another system.

2.7.2 Writing Files to Another System
The COPY command also moves files from your system to another system, as
demonstrated in the following examples:
$ COPY FY83.DAT EBONY::CLERK:[ACCOUNTS]
Moves the latest version of FY83.DAT in your default directory to a file of the same
name in the directory CLERK:[ACCOUNTS] on the system EBONY.
$ COPY *.* EBONY::CLERK:[ACCOUNTS]
Moves the latest versions of all files in your default directory to files with the same
names in the directory CLERK:[ACCOUNTS] on the system EBONY.
You can also use the Mail Utility to move files to another system: the file is copied
to the mail file of the account rather than to a specified file. The following example
copies the file FY83.DAT to USER'S mail file on the system EBONY.
$ MAIL FY83.DAT EBONY::USER
You can print files on another system by copying files to spooled devices on the
other system, or by copying files to files on the other system and printing them with
the /REMOTE qualifier of the PRINT command.
$ COPY FY83.DAT EBONY::LPAO:
Prints FY83.DAT in your default directory on LPAO (typically the line printer
assigned to SYS$PRINT) on EBONY. Note that to specify a device (rather than a
file) in the COPY command, you must follow the device name with a colon.
$ PRINT/REMOTE EBONY::CLERK:[ACCOUNTS]FY83.DAT

2-54

Storage and Output of Data

Prints CLERK:[ACCOUNTS]FY83.DAT on the device assigned to the logical name
SYS$PRINT on the system EBONY. Note that the file must reside on the node on
which it is being printed.
You can also use the following commands to affect files on another system: CREATE,
DELETE, WRITE (with OPEN and CLOSE), PURGE, and SUBMIT/REMOTE.

2.7.3 Access Restrictions
If you receive a protection violation or DECnet-VAX error message in attempting to
move a file across systems, you have two choices: (1) if you are writing the file, you
can send it to a user account on the other system with MAIL (see Appendix MAIL)
or (2) you can follow the node name with an access control string.
An access control string consists of the user name and password of a user account
on the system that has access to the directory and/or file you want to access.
Enclose the access control string in quotation marks and place it between the node
name and the double colon. The following example displays a file located on the
system EBONY by including the access control string "PERRY R27L4R15" in the
file specification. In this example, PERRY is the user name and R27L4R15 is the
password.
$ TYPE EBONY"PERRY R27L4R15"::CLERK:[ACCOUNTS]FY83.SUM
If the account does not have a password, omit the password from the access control
string.
If you define a logical name that includes an access control string, you must use triple
quotation marks around the access control string in the definition. The following
example equates the logical name CURRENT to a file specification using an access
control string (where PERRY is the user name and R27L4R15 is the password).
$ DEFINE CURRENT EBONY"""PERRY R27L4R15"CLERK:[ACCOUNTS]FY85.SUM

Chapter 3
Editing Files with the EDT Editor
EDT is an interactive text editor. With EDT you can create a new file, insert text into
it, and modify that text. You can also edit text in existing files.
EDT provides both line and keypad editing. In line editing, you type the editing
command and the range of text you want the command to affect. In keypad editing,
you move the cursor directly to the text you want to change and press keypad keys
to enter the editing commands.
An efficient way to use EDT on a video terminal is to use keypad as the primary
editing mode in combination with various line-editing commands. You can also
redefine certain keypad and control keys to perform editing functions not available in
keypad editing. This chapter describes keypad editing as the main editing mode and
includes supplementary line-editing commands and key definitions. (If you are using
a hardcopy terminal, you can use only line-editing commands. See Appendix EDT.3
for a list of EDT's line-editing commands.)

3.1

Invoking and Terminating EDT

The DCL command EDIT invokes the EDT editor, which has its own set of
commands for editing files. Included in these EDT commands are two commands for
leaving the EDT editor: EXIT and QUIT.

3-2

Editing Files with the EDT Editor

3-1.1 Invoking EDT
To invoke EDT, type the DCL command EDIT and specify as a parameter the file
you want to edit. If the specified file already exists, EDT saves the existing versions
and places a copy of the latest version in your buffer. The existing versions of the file
remain unchanged. For example, to edit an existing file named MEMO.TXT, enter
the following command line:
$ EDIT MEMO.TXT
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
The first few lines of the latest version of the file appear on the screen. The cursor
is positioned at the top of the screen, and EDT is ready to receive a keypad-editing
command.
If you invoke EDT to create a file, the following message appears:
$ EDIT NEWFILE.TXT
[EOB]

Input file does not exist
Only the EDT message and the end-of-buffer symbol, [EOB], appear on the screen,
and EDT is ready to receive keypad-editing commands. (A buffer is the temporary
storage area in which you edit text. See Section 3.6.7 for more information about
buffers.)
NOTE: In the previous examples, you enter EDT in keypad (change) mode because
a startup command file (SYS$LOGIN:EDTINI.EDT) containing the SET MODE
CHANGE command has been executed. If this command is not executed in an EDT
startup command file, you will enter EDT in line mode. See Section 3.7.1 for more
information on EDT startup command files.

3.1.2 Terminating EDT
Both the EXIT and QUIT commands terminate an EDT editing session; however, only
EXIT saves your edits in a new version of the file. (Note that the existing versions of
a file remains unchanged regardless of how the editing session is terminated.)

Editing Files with the EDT Editor

3-3

3.1.2.1 Saving Your Edits
To save your edited text, use the line-editing command EXIT to terminate EDT.
When you enter the EXIT command, EDT creates an output file containing the edited
version of the input file. By default, the output file will have the same name and
type as the input file, with the version number incremented by 1. For example, if
you enter the EXIT command after editing a file named MEMO.TXT;3, the output file
will be named MEMO.TXT;4.
♦EXIT
$DISK1:[USER]MEMO.TXT;4
$

2 lines

To override the default output file name, enter the EXIT command with a new file
specification as the parameter. For example, if you end the same editing session with
EXIT OSGOODE.DAT, the output file will be named OSGOODE.DAT; 1 (providing
no other file named OSGOODE.DAT exists).
♦EXIT OSGOODE.DAT
$DISK1:[USER]OSGOODE.DAT;1
$

2 lines

3.1.2.2 Discarding Your Edits
To terminate EDT without saving your edits, use the line-editing command QUIT. All
edits you have made to the text will be ignored, and no output file will be created.
♦QUIT
$
The QUIT command is a useful way to terminate EDT when you have opened a file
by mistake.

3.2 Entering EDT Commands
You enter most keypad-editing commands by pressing a keypad key. You enter
line-editing commands by typing them after the line-editing prompt and pressing
RETURN.

3.2.1 Entering EDT Line Commands
EDT prompts for line-editing commands with an asterisk. Line-editing commands
usually operate on a range of one or more lines of text that you specify as a
parameter for the command. For example, to display an entire file on your screen,
enter the TYPE command and specify WHOLE as the parameter.
♦TYPE WHOLE
You can abbreviate EDT line-editing commands, however, for clarity, the examples
in this chapter show complete line-editing commands.

3-4

Editing Files with the EDT Editor

3.2.2 Entering Keypad Commands
In keypad editing, the screen displays editing changes as you make them. You type
text from the main keyboard and enter keypad-editing commands from the numeric
keypad. (To initiate keypad editing you must first enter the line-editing command
CHANGE. See Section 3.4.2 for information on the CHANGE command.)
The following figure shows the keypad keys and their functions.

PF1

PF2

GOLD

HELP

PF3
FNDNXT

PF4
DEL L

FIND

UND L

PAGE

SECT

9
APPEND

DEL W

COMMAND

FILL

REPLACE

UND W

4
ADVANCE

5
BACKUP

BOTTOM

TOP

*
CUT

DEL C

PASTE

UND C

ENTER

WORD

EOL

CHAR

CHNGCASE

DEL EOL

SPECINS

ENTER

•

0
LINE

SELECT

OPEN LINE

RESET

SUBS

ZK-1688-84

Each key in the keypad performs at least one editing command; most perform two.
Pressing a key invokes the regular, or upper, function. To invoke the alternate, or
lower, function of a key, press the GOLD key (labeled PF1) first, followed by the
desired key. (In the examples that follow, a small diagram of the keypad highlights
the key or keys that perform the command being described. The text associated with
the keypad illustrates the effect of that editing command.)

Editing Files with the EDT Editor

3-5

For example, key 1 performs both the WORD and the CHNGCASE functions. To
invoke the WORD command, press WORD: the cursor moves to the beginning of the
next word.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
WORD

□□□
□□□
□□□
run
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
To invoke the CHNGCASE command, press the GOLD key first and then
CHNGCASE: the character at the cursor changes from lowercase to uppercase or
from uppercase to lowercase.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
CHNGCASE

□□□
□□□
rnn
I Am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
The supplemental editing keys on the VT200 keypad perform the same functions as
some of the EDT keypad keys. (See Appendix EDT.2.3 for more information about
these supplemental editing keys.)

3-6

Editing Files with the EDT Editor

(Enter)
Do

Find

Select

(Paste)
Insert
Here

(Cut)
Remove

Prev
Screen

Next
Screen

ZK-1677-84

3.2.3 Canceling EDT Commands
Use CTRL/C to cancel the currently executing EDT command without affecting
previous edits. For example, to stop the display of a long file, press CTRL/C.
*TYPE WHOLE

| CTRL/C1

Aborted by CTRL/C
*

The display stops and the CTRL/C message appears.

3.3 Getting Help in EDT
EDT provides a help facility for each of the EDT editing modes.

Editing Files with the EDT Editor

3-7

3.3.1 Getting HELP on Keypad-Editing Commands
To display a diagram of the keypad keys and their various functions, enter change
mode and then press the HELP key (labeled PF2). (On VT200 series terminals,
you can also use the HELP key on the supplemental editing keypad.) To display
information about a particular keypad command, first press the HELP key and then
press the keypad key.

3.3.2 Getting HELP on Line-Editing Commands
To display a list of EDT topics on which information is available, type HELP
and press RETURN. To display information about a particular command or topic,
type HELP followed by the name of the topic and press RETURN. EDT responds
with a display of information about the topic and a list of related topics on which
information is available. To display information on the use of a particular command
qualifier, type HELP plus the command and that qualifier and press RETURN. For
example, to display information on the use of /QUERY with the COPY command,
enter the following command line:
*HELP COPY /QUERY

3.3.3 Getting HELP on Nokeypad-Editing Commands
Nokeypad commands are used to construct key definitions. To display a list of the
nokeypad-editing commands on which information is available, enter the following
HELP command in line mode:
*HELP CHANGE SUBCOMMANDS
To display information about nokeypad entities (units of text upon which nokeypad¬
editing commands operate), enter the following HELP command in line mode:
♦HELP CHANGE ENTITIES

3.4 Changing Editing Modes
You can easily switch back and forth between line and keypad editing; you can also
enter line-editing commands from keypad mode. Before using keypad commands, be
sure that your terminal type is set properly. (Use SHOW TERMINAL to display the
setting and SET TERMINAL/INQUIRE to set the terminal type.)

3-8

Editing Files with the EDT Editor

3.4.1 Changing from Keypad to Line Editing
To change from keypad editing to line editing, press CTRL/Z. The asterisk prompt
appears at the bottom of your screen, indicating EDT is ready to accept line-editing
commands.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
1CTRL/Z1

3.4.2 Changing from Line to Keypad Editing
To change from line editing to keypad editing, enter the CHANGE command:
♦CHANGE
The first 22 lines of the file are displayed on your screen. If the file has fewer than
22 lines, the [EOB] symbol will appear below the last line of the file.

3.4.3 Entering Line-Editing Commands from Keypad Mode
The keypad COMMAND function allows you to enter line-editing commands
without leaving keypad mode. First, enter COMMAND (by pressing GOLD and then
COMMAND) to invoke the Command: prompt, then type the line-editing command
and press ENTER. (If you press RETURN by mistake, ~M appears; simply delete
the "M by pressing the DELETE key on the main keyboard, and press ENTER.) The
following example enters the line-editing command SET QUIET, which suppresses
the sound made when EDT issues an error message.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
COMMAND

□□□
□□□
1 I 1

Editing Files with the EDT Editor

3-9

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
Command:

SET QUIET

ENTER

□□□□
□□□□
□□□□
□□□■
mol

3.5 Recovering from Interruptions
You can recover from interruptions to your editing session in the following ways:
•

Deleting extraneous characters—Pressing CTRL/W removes extraneous
characters (such as a broadcast message or a message indicating that you have
received electronic mail) from the screen and restores the previous display. You
should use CTRL/W to clear extraneous characters to ensure that the cursor is in
the correct position.

•

Resuming an interrupted editing session—The DCL command CONTINUE
resumes an editing session that was interrupted by pressing CTRL/Y, so long
as only built-in DCL commands were entered after pressing CTRL/Y. (See
Section 1.4 for a list of built-in commands.) For example, you could press
CTRL/Y, then enter the command SHOW TIME, and then return to your editing
session with the CONTINUE command. (Press CTRL/W to restore the screen to
its display prior to the SHOW TIME and CONTINUE commands.)

•

Recovering a lost session—By default, EDT keeps a journal file with the same file
name as the input file and a file type of JOU. If the editing session ends without
interruption, the journal file is deleted when you terminate the session. If the
editing session is aborted (for example, during a system failure or in response
to pressing CTRL/Y, or entering the QUIT/SAVE command), you can recover
your edits (with the possible exception of those commands entered just prior to
the interruption). Enter the same command line you used to begin the editing
session but add the /RECOVER qualifier. For example:
$ EDIT/RECOVER MEMO.TXT

3-10

Editing Files with the EDT Editor

EDT will reproduce the editing session, reading the commands from the journal
file and executing them on the screen.

3.6 EDT Keypad Editing
While line editing allows you to manipulate large portions of text easily, EDT keypad
editing provides easy manipulation of small units of text. Several EDT keypad
commands enable you to find, insert, delete, substitute, and move text in a file. The
cursor can be moved through a file in a variety of ways, and the position of the
cursor in a file determiners how text will be affected by EDT commands.

3.6.1 Manipulating the Cursor
You can manipulate the cursor with commands that move it unit by unit through the
text and commands that move it directly to a particular location. Several commands
that move the cursor are controlled by the ADVANCE and BACKUP commands,
which set the cursor's direction forward and backward respectively. Unless otherwise
stated, this chapter assumes the default direction of the cursor to be ADVANCE. If
your cursor does not move as described, it may be set to move backward rather than
forward. See Section 3.6.1.4 for information about changing the cursor's direction.
Where EDT editing keys on the VT200 and VT100 series terminals differ, the VT200
key is described first and the VT100 key is described in parentheses.

3.6.1.1 Moving the Cursor by Small Units
You can move the cursor by character, word, and line units.
Three keys move the cursor by character.
•

RIGHT ARROW—Moves the cursor one character to the right.

•

LEFT ARROW—Moves the cursor one character to the left.

•

CHAR—Moves the cursor one character in the current direction (depending on
whether ADVANCE or BACKUP is set).
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

Editing Files with the EDT Editor

3-11

CHAR

□□□
□□□
□□□
□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
The WORD command moves the cursor to the beginning of the next or previous
word (depending on whether ADVANCE or BACKUP is set).
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
WORD

□□□
□□□
□□□
□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
Several keys move the cursor by line:
•

UP ARROW—Moves the cursor up one line.

•

DOWN ARROW—Moves the cursor down one line.

•

EOL—Moves the cursor to the end of the current or previous line (depending on
whether ADVANCE or BACKUP is set).
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3-12

Editing Files with the EDT Editor

EOL

□□□
□□□
□□□
run
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
•

FI2 (the BACKSPACE key on VT100 series terminals)—Moves the cursor to the
beginning of the previous line.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
fFT2l

(I backspace!)

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
•

LINE—Moves the cursor to the beginning of the next line or previous line,
depending upon whether ADVANCE or BACKUP is set.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
LINE

□□□
□□□
□□□
□□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
The OPEN LINE command terminates a line without moving the cursor. (The
RETURN key also terminates a line, but moves the cursor to the next line.) The
OPEN LINE command is useful when you want to insert a blank line or a new line
of text. When the cursor is placed at the beginning of a line and the OPEN LINE
command is entered, the text on that line is moved down so that the cursor is at the
beginning of a blank line.

Editing Files with the EDT Editor

3-13

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
OPEN LINE

□□□
□□□
□□□
I am happy to inform you that Justice H.

Osgoode has

accepted our offer of the position of town programmer.
[EOB]

3.6.1.2 Moving the Cursor by Large Units
The SECT and PAGE commands allow you to scan several lines of text at a time.
The direction in which EDT moves depends upon whether ADVANCE or BACKUP
is set.
•

SECT—Moves the cursor across a 16-line section of text in EDT's current
direction. If there are fewer than 16 lines, SECT moves the cursor across the
existing lines.
(On the VT200 series terminals, the supplemental editing keypad key Next
Screen moves the cursor 16 lines forward, regardless of EDT's current direction.
The supplemental editing keypad key Prev Screen moves the cursor 16 lines
backward, regardless of EDT's current direction.)

•

PAGE—Moves the cursor to the next or previous page boundary (form feed) or
to the end or top of the buffer if there is no boundary. To insert form feeds in
your text, use CTRL/L.

3.6.1.3 Moving the Cursor to the Beginning or End of the Buffer
The TOP and BOTTOM commands allow you to move directly to the beginning or
end of a buffer. (A buffer is a temporary storage area in which you edit text. See
Section 3.6.7 for information about buffers.)
•

TOP—Moves the cursor to the beginning, or top, of the buffer.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3-14

Editing Files with the EDT Editor

TOP

□□□
□□□
][
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
•

BOTTOM—Moves the cursor to the end, or bottom, of the buffer.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
BOTTOM

□□□
□□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3.6.1.4 Changing the Cursor’s Direction
The ADVANCE and BACKUP commands control the cursor's direction for the
following EDT keypad-editing commands: CHAR, CHNGCASE, EOL, FIND,
FNDNXT, LINE, PAGE, SECT, SUBS, and WORD. Each of the directional commands
remains in effect until you set the cursor in the opposite direction with the other
command.
•

ADVANCE—Sets the cursor's direction forward so that subsequent commands
move the cursor in the forward direction. For example, if you enter the WORD
command after using ADVANCE, the cursor moves forward one word.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

Editing Files with the EDT Editor

3-15

ADVANCE

□□□
□□□
□□□
□□
WORD

□□□
□□□
□□□
□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
•

BACKUP—Sets the cursor's direction in the backward direction so that
subsequent commands move the cursor toward the top of the buffer. For
example, if you enter the WORD command after using BACKUP, the cursor
moves backward one word.
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
BACKUP

□□□
□□□
□□□
□□

3-16

Editing Files with the EDT Editor

WORD

□□□
□□□
□□□
□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
The cursor will then remain set in the backward direction until you press ADVANCE.
For example, if you enter a second WORD command in the example above, you will
receive a message indicating that the command requests EDT to back up past the top
of the buffer.
The ADVANCE and BACKUP commands are particularly important in string
searches; see Section 3.6.4 for more information on searches.

3.6.2 Inserting Text
To insert text in EDT keypad editing, position the cursor where you want the text
to be inserted and begin typing; the cursor remains one position to the right of
the last character inserted. Inserting text in the middle of a line moves both the
cursor and the remainder of the line one position to the right for each character
inserted. When the line exceeds 80 characters, the text you type will either wrap to
the following line or remain invisible, depending on the status of the SET SCREEN,
SET [NO]TRUNCATE, and SET [NO]WRAP commands. (See Section 3.7.2 for
information about screen formatting commands.)

3.6.3 Deleting and Restoring Text
The delete commands work like the cursor movement commands. In EDT keypad
editing, you can delete by character using the Delete key (<X1 ) (DELETE on
VT100 series terminals) and DEL C; by word using FI3 (LINEFEED on VT100 series
terminals) and DEL W; and by line using DEL L, DEL EOL, and CTRL/U. The
deleted text is stored in a buffer so that you can also restore the character (UND C),
word (UND W), or line (UND L) most recently deleted wherever and as many times
as you desire. Note that the undelete commands restore only the corresponding units
of text that were most recently deleted. For example, if you have deleted two lines of
text with the DEL L (delete line) command, the UND L (undelete line) command will
restore only one line, the line most recently deleted.

Editing Files with the EDT Editor

3-17

3.6.3.1 Deleting and Restoring Characters
Whereas the O key on the main keyboard (the DELETE key on VT100 series
terminals) deletes the character immediately to the left of the cursor, the EDT
keypad-editing command DEL C deletes the character directly at the cursor. The
UND C command restores the last character deleted with either the <x] (DELETE)
key or the DEL C command. For example:
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
DEL C

□□□□
□□□□
□□□■

□□U
am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
UND C

■□□□
□□□□
□□□■
□□U
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3.6.3.2 Deleting and Restoring Words
The FI3 key on the main keyboard (the LINEFEED key on VT100 series terminals)
deletes to the beginning of the current or preceding word, and the DEL W command
deletes to the end of the current word. Blank spaces are considered part of the word
they follow, while all other word delimiters are considered to be separate words in
themselves. The UND W command restores the last word deleted with either the
FI3 (LINEFEED) key or the DEL W command. For example:
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3-18

Editing Files with the EDT Editor

del w

□□□□
■
□□□[
□□□[
□□□1

I am happy to inform you that H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]
UND W

■□□□
■
□□□[
□□□[
□□□1

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3.6.3.3 Deleting and Restoring Lines
Three commands delete a line (or part of a line) of text.
•

DEL L—Deletes from the cursor to the end of the line, including the line
terminator. If the cursor is at the beginning of the line, the entire line is deleted,
and the cursor is positioned at the beginning of the next line.

•

DEL EOL—Deletes from the cursor to the end of the line (excluding the line
terminator), leaving the cursor at the end of the truncated line.

•

CTRL/U—Deletes from the cursor to the next previous beginning of line, leaving
the cursor at the beginning of the previous line. (If CTRL/U is used when the
cursor is at the beginning of the line, the previous line is deleted.)

The UND L command restores the last line (or part of a line ) that was deleted with
the DEL L, DEL EOL, OR CTRL/U command. For example:
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

Editing Files with the EDT Editor

3-19

DEL L

□□□■

□□□
□□□
□□□
run

I am happy accepted our offer of the position of town programmer.
[EOB]
UND L

□□□
□□□
□□□
mo
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
[EOB]

3.6.3.4 Deleting and Restoring Large Sections
The EDT line-editing command DELETE is useful for deleting large sections of text.
Generally you use line numbers to specify a range for a line-editing command. For
example, to delete lines 306 through 860, enter the following:
♦.DELETE 306 THRU 860
555 lines deleted
861
Furthermore,

I have been informed recently that

Note that the EDT line-editing command SET NUMBERS (the default) must be in
effect for line numbers to be displayed in EDT line editing.
You can also use certain keywords (such as WHOLE, REST, BEFORE) as range
specifiers. For example, if you are in the middle of a long buffer and want to delete
from the cursor to the end of the buffer, enter the following:
Command:

DELETE REST

(You can also specify range by using the EDT keypad-editing command SELECT. See
Section 3.6.6.1 for information on SELECT.)

3-20

Editing Files with the EDT Editor

3.6.4 Locating Text
You can move the cursor to a specified character string with the FIND and FNDNXT
EDT keypad-editing commands. The FIND command searches for the specified
character string between the current position of the cursor and the beginning or
end of the buffer (depending on whether the ADVANCE or the BACKUP command
is in control). EDT does not distinguish between uppercase and lowercase letters
unless you use the SET SEARCH EXACT line-editing command. When EDT finds
the string, it positions the cursor at the first character in the string (unless the SET
SEARCH END command is in effect, and then the cursor is positioned at the last
character in the string). In a long file the message "Working" may flash on the screen
while EDT searches for the string.
For example, to insert a comma after the word "Vermont" in the following text, you
can use the FIND command to move the cursor to the string "Vermont." First, enter
the EDT keypad command FIND by pressing the GOLD key and then the FIND
key (on the VT200 series terminal you may also use the FIND key located on the
supplemental editing keypad). Next, type the string you want to locate (the search
string) after the Search for: prompt.
FIND

□□□
□□□
□□□
1 ILJ
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgoode comes from Steeple
Creek, Vermont where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]
Search for:

Vermont

To search in the forward direction, use the ADVANCE command to enter the search
string.

ADVANCE

□□□
□□□
□□□
mn

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgoode comes from Steeple
Creek, Vermont where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]

Use the CHAR command to move the cursor to the end of the word "Vermont"
then insert the comma.
CHAR

□□□
□□□
□□□
I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgoode comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]

3-22

Editing Files with the EDT Editor

To find the next occurrence of the string located with the FIND command, use the
FNDNXT (find next) command. If there is no other occurrence of the string (as in the
example above), EDT issues the message "String was not found."

NOTE:

Note that the directional setting of the cursor determines the direction of
the search. After you press FIND, you can press either ADVANCE or BACKUP
(depending on the direction in which you wish to search) to enter the search string.
You can also use the ENTER command, which applies the current direction to the
search.

3.6.5 Substituting Text
To substitute one character string for another, you can use the SUBS keypad¬
editing command or the SUBSTITUTE line-editing command. The EDT line-editing
command can make global substitutions; that is, it can replace every occurrence of
one character string in the specified range with another string using only one EDT
line-editing command. In contrast, you must use the keypad SUBS command (press
the GOLD key followed by the SUBS key) for each substitution you make. (If you
do not specify a range, the line-editing command SUBSTITUTE replaces only the first
occurrence of the search string in the current line with the substitute string.)
For example, to substitute the string "Osgood" for "Osgoode" throughout a buffer,
enter the line-editing command SUBSTITUTE, the old string, and the new string,
separating all three with the same delimiter. You can use any nonalphanumeric
character (except the percent sign and underscore) as a delimiter for the SUBSTITUTE
command, so long as the delimiting character is not part of either string. To apply
the command to the entire buffer in a global substitution, specify WHOLE as the
parameter. When the operation has been completed, EDT displays each occurrence
of the substitution and the total number of substitutions. The following example
substitutes the string "Osgood" for each occurrence of the string "Osgoode" in the
text below.
COMMAND

□□□
□□□
1 III

Editing Files with the EDT Editor

3-23

I am happy to inform you that Justice H. Osgoode has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgoode comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]
Command:

SUBSTITUTE\Osgoode\Osgood\WHOLE

ENTER

□□□□
□□□□
□□□□
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]
1
I am happy to inform you that Justice H. Osgood has
7
unable to interview him, Mr. Osgood comes from Steeple
2 substitutions
Press return to continue
After you press RETURN, the cursor moves to the top of the buffer.
Note that a global substitution replaces all occurrences of the string, regardless of
case or surrounding characters. If you want EDT to search for exact comparisons
of case, use the SET SEARCH EXACT command. If the search string occurs in the
middle of a longer string, the substitution will still be made. For instance, a global
substitution of "IN" for "AT" would change all words containing the string "AT".

Editing Files with the EDT Editor

3-24

("LATER" would become "LINER", "THAT" would become "THIN", "SAT" would
become "SIN", and so on.)
To get EDT to prompt you before each substitution, use the /QUERY qualifier with
the SUBSTITUTE command.
Command:

SUBSTITUTE\AT\IN\WHOLE/QUERY

EDT prompts you with a ? to verify each substitution. You can respond with one of
the following:
Y

Yes, do the substitution

No, do not do the substitution

Quit, terminate the command

All, do the rest of the substitutions without query

3.6.6 Moving Text
Both EDT keypad and line commands can move text; however, only line-editing
commands transfer text between buffers and files.

3.6.6.1 Moving Text Within the File
The EDT keypad-editing command CUT deletes a selected range of text and the
PASTE command inserts it at the cursor's current position. (On the VT200 series
terminals, the supplemental editing keys Remove and Insert Here perform the same
functions as the EDT keypad commands CUT and PASTE.) For instance, to move the
first sentence in the second paragraph of the example to the end of that paragraph,
move the cursor to the beginning of the sentence and press SELECT. (On the VT200
series terminals, the supplemental editing key SELECT performs the same function
as the EDT keypad command SELECT.) This marks the beginning of the selected
range. (You can cancel the SELECT command with the RESET command.)
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]

□□□
□□□
□□□
□□□

To mark the end of the selected range, move the cursor to the end of the sent
The terminal highlights a selected range in reverse video. (The selected range
includes the text up to the character preceding the cursor.)
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well. For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]

Then press CUT to delete the selected text.
CUT

□□□
□□□
□□□
run
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]

3-26

Editing Files with the EDT Editor

EDT holds the text deleted with the CUT command in the PASTE buffer until
you enter the CUT command again. To restore the text, move the cursor to the
appropriate position and enter the PASTE command. (The text will be inserted
directly in front of the cursor.)
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
[EOB]
PASTE

□□□
□□□
rnn
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
[EOB]
Because the selected text is held in the PASTE buffer until you perform another CUT
operation (or give the line-editing command CLEAR PASTE), you can paste the text
contained in the PASTE buffer as many times as you want. You can also enter the
PASTE buffer to edit the text it contains. (See Section 3.6.7 for information on using
multiple buffers.)
After moving the text, you may want to use the FILL command to reorganize selected
text so that the maximum number of whole words are fitted within the current line
width. The default line width is 80 characters, but you can use the SET WRAP
command to use another line length for filling text. For example, you can set the line

Editing Files with the EDT Editor

3-27

length to 60 characters with the EDT line-editing command SET WRAP and then fill
a selected range of text.
COMMAND

□□□
□□□
□□
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
[EOB]
Command:

SET WRAP 60

ENTER

□□□□
□□□□
□□□□
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
[EOB]

3-28

Editing Files with the EDT Editor

EDT will now wrap lines of inserted text and fill lines of selected text at a line width
of 60 characters. Use the SELECT command to mark the text you want to affect and
then enter the EDT keypad command FILL.
SELECT

□□□
□□□
□□□
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were
unable to interview him, Mr. Osgood comes from Steeple
Creek, Vermont, where he served as chief statistician,
responsible for designing and implementing their current
budget system.
He leaves Steeple Creek in July to join
us September 1.
I am especially glad to have him since he brings not
only an excellent programming background, but experience
in town management as well.
[EOB]
FILL

□□□
□□□
mo
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were unable to interview him, Mr.
Osgood comes from Steeple Creek, Vermont, where he served as
chief statistician, responsible for designing and
implementing their current budget system.
He leaves Steeple
Creek in July to join us September 1. I am especially glad
to have him since he brings not only an excellent
programming background, but experience in town management as
well.
[EOB]

Editing Files with the EDT Editor

3-29

3.6.6.2 Moving Text Between Files
There are several EDT line-editing commands that move text. For example, the
MOVE and COPY commands each perform a function similar to those of the keypad
CUT and PASTE operations. MOVE deletes text from one location and inserts it in
another; COPY inserts a copy of the text where specified without deleting any text.
The EDT line-editing commands INCLUDE and WRITE perform tasks not possible
with EDT keypad-editing commands.
•

INCLUDE—Copies a file into the buffer you are currently editing or the buffer
you specify. Follow the VAX/VMS conventions for file specifications when
specifying the file to be copied to the buffer. For example, the following
command copies the file named MEM.DAT to the buffer named BUF1.
Command:

•

INCLUDE MEM.DAT =BUF1

WRITE—Copies a specified range of text from a buffer (the current buffer by
default) to a specified file. If you do not specify a range, the WRITE command
copies the entire contents of the current buffer. For example, the following
command copies the contents of the current buffer to the file OSGOODE.DAT.
Command:
WRITE OSGOODE.DAT
$DISK1:[USER]OSGOODE.DAT;1
11 lines
The message displays the new file's specification and length.

3.6.7 Using Multiple Buffers
When you begin editing a file with EDT, you are working on a copy of the file in a
buffer called MAIN. (EDT also uses a buffer called PASTE to store the text that you
delete with the CUT and APPEND commands; you can edit this buffer just as you
can edit other text buffers.) You can create other buffers to store pieces of text during
your EDT editing session. You can enter and edit these buffers; you can copy text to
and from them; and you can write their contents to specified files. To create a buffer,
press the COMMAND key. Type the line-editing command FIND followed by the
equal sign and whatever name you are giving the buffer, then press the ENTER key.
For example, the following command creates a buffer named BUF1.

3-30

Editing Files with the EDT Editor

COMMAND

□□□
□□□
rzn
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were unable to interview him, Mr.
Osgood comes from Steeple Creek, Vermont, where he served as
chief statistician, responsible for designing and
implementing their current budget system.
He leaves Steeple
Creek in July to join us September 1. I am especially glad
to have him since he brings not only an excellent
programming background, but experience in town management as
well.
[EOB]
Command:

FIND=BUF1

When you enter this command, the system responds by displaying nothing but the
[EOB] symbol, which indicates that the current buffer, BUF1, is empty. You can now
insert and edit text just as you would in the MAIN buffer. To return to the MAIN
buffer, follow the same procedure, typing FIND=MAIN rather than FIND=BUF1.
To return to your previous position in the MAIN buffer, include a period after the
buffer's name.
Command:

FIND=MAIN.

The buffer named BUF1 will remain intact until you exit from EDT, regardless of
whether you issue the EXIT or QUIT command. That is, you can enter, edit, and exit
from a buffer at will. However, when you exit from EDT, only the buffer MAIN is
saved.
The SHOW BUFFER command displays the number of lines contained in each
buffer and indicates (with an equal sign) the current buffer. The following example
indicates that there are three buffers (including MAIN and PASTE, which always
exist) and that MAIN is the current buffer.

Editing Files with the EDT Editor

3-31

COMMAND

□□□
□□□
□□
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were unable to interview him, Mr.
Osgood comes from Steeple Creek, Vermont, where he served as
chief statistician, responsible for designing and
implementing their current budget system.
He leaves Steeple
Creek in July to join us September 1. I am especially glad
to have him since he brings not only an excellent
programming background, but experience in town management as
well.
[EOB]
Command:

SHOW BUFFER

=MAIN
11
lines
PASTE 3
lines
BUF1
2
lines
Press return to continue
Pressing the RETURN key returns the cursor to its previous position in the buffer.
You can further manipulate the contents of a buffer by specifying the buffer's name
in an EDT line-editing command. For instance, if you are in the MAIN buffer and
want to save the contents of BUF1 in a file named BUDGET.DAT before exiting from
EDT, enter the following command:
COMMAND

□□□
□□□
□□

3-32

Editing Files with the EDT Editor

I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were unable to interview him, Mr.
Osgood comes from Steeple Creek, Vermont, where he served as
chief statistician, responsible for designing and
implementing their current budget system.
He leaves Steeple
Creek in July to join us September 1. I am especially glad
to have him since he brings not only an excellent
programming background, but experience in town management as
well.
[EOB]
Command:

WRITE BUDGET.DAT =BUF1

$DISK1:[USER]BUDGET.DAT;1

2 lines

EDT returns a message indicating that the file has been created, and the cursor is
returned to its previous location in the buffer.

3.7 Controlling EDT Sessions
You can control some of the characteristics of an EDT editing session with the SET
commands. You can redefine the functions of many keys by using the EDT line¬
editing command DEFINE KEY (or CTRL/K in keypad editing) plus one or more
EDT nokeypad-editing commands. (EDT nokeypad-editing commands perform
keypad operations; you can combine them in key definitions to extend your editing
capacity. See Appendix EDT.4.2 for a list of EDT nokeypad-editing commands.) You
can also define a macro (a sequence of line-editing commands) and define keys in
EDT. You can enter these control commands interactively, or you can include them
in an EDT startup command file.

3.7.1 Startup Command Files
An EDT startup command file contains EDT line-editing commands that are executed
when you invoke EDT (before you receive control of the editor). A startup command
file is useful for setup operations in EDT; it can include specifications for screen
format, definitions of text entities, and definitions of keys and macros. Generally,
EDT reads a system-wide startup command file at the beginning of your editing
session. If no system-wide startup command file exists on your system, EDT looks
for a file named EDTINI.EDT in your default directory and processes the commands
in that file.
To create an EDTINI.EDT file, invoke an editor and specify EDTINI.EDT as the file
specification. An example follows:
$ EDIT EDTINI.EDT

Editing Files with the EDT Editor

3-33

Now list the commands, one per line. Some typical commands you might want to
put in a startup command file follow:
SET QUIET
SET WRAP 60
SET SEARCH BOUNDED
SET TAB 5
DEFINE KEY GOLD P AS "PAR."
SET MODE CHANGE
When you exit from the editor, you will have an EDTINI.EDT file. Then, every time
you invoke the editor, the commands in your EDTINI.EDT file will be in effect.
To specify an EDT startup command file named something other than EDTINI.EDT,
you must include the file specification in the EDIT command line as follows:
$ EDIT/COMMAND=startup-file-spec

file-spec

For a list of EDT line and nokeypad editing commands, see Appendix EDT.4.2.

3.7.2 Controlling Screen Format with SET Commands
Several EDT commands control the format of a screen display. A few of these are
listed below. See Appendix EDT.3.2 for a comprehensive list of the SET commands.
•

SET LINES n—Controls the number of lines that EDT displays on the screen.
This number, which can be set from 1 to 22, defaults to 22. To set the screen to
15 lines, for example, type:
Command:

SET LINES 15

Note that if you are editing at slow baud rates, setting the number of lines low
will increase your editing speed.
•

SET SCREEN width—Controls the maximum length of the line EDT displays;
the default width is 80 characters. (When there are more characters than the SET
SCREEN command specifies, EDT displays a diamond at the end of the line.)
Command:

SET SCREEN 132

If you SET SCREEN wider than 80 on either a VT100 or VT200 series terminal,
EDT changes the terminal's screen width to 132.
•

SET [NOJTRUNCATE—Controls whether the characters that exceed the SET
SCREEN width are displayed on the next line. The default is SET TRUNCATE,
which ends the display of a line at the value of SET SCREEN.
Command:

SET [NO]TRUNCATE

3-34

•

Editing Files with the EDT Editor

SET [NO]WRAP n—Specifies n character positions as the point at which text will
be moved to the beginning of the next line. When you are inserting text in EDT
keypad mode and the cursor position exceeds the value of n, EDT wraps the next
full word to the next line. (However, when you insert text in the middle of a
line, that line does not always wrap.) The default is NOWRAP. To wrap the text
exceeding 75 characters, for example, type:
Command:

SET WRAP 75

The SET commands have corresponding SHOW commands; see Appendix EDT.3.2
for a list of SHOW commands.

3.7.3 Controlling Editing Functions with SET Commands
Several commands control EDT's responses during an editing session. Some of
these are listed below. (See Appendix EDT.3.2 for a comprehensive list of the SET
commands.)
•

SET ENTITY—Defines boundaries for the WORD, SENTENCE, PARAGRAPH,
and PAGE entities. (The SENTENCE and PARAGRAPH entities are not used
by any default key definitions; consequently, they are useful only in the key
definitions you create with the DEFINE KEY command.) For example, the
default boundaries for the WORD entity are a line feed, tab, form feed, line
terminator, and space. To make the period and comma the only delimiters of the
word entity, give the following SET ENTITY command.
Command:

•

SET ENTITY WORD \

’

SET MODE—Controls the EDT editing mode to be entered when the processing
of the EDTINI.EDT file is completed (either line or change mode). For example,
to enter change mode instead of line mode at the beginning of editing sessions,
insert the following command at the end of your EDT startup command file:
SET MODE CHANGE

•

SET QUIET—Suppresses the sound made when EDT issues an error message in
keypad mode. The default is NOQUIET.

Editing Files with the EDT Editor

3-35

3.7.4 Defining Keys
To redefine a key, assign one or more EDT nokeypad-editing commands (listed in
Appendix EDT.4.2) to the key with the DEFINE KEY command:
Command:

DEFINE KEY key AS "command(s)"

You can redefine all keypad keys and you can define any GOLD keyboard key
sequence except the keyboard digits, minus sign, and O key (the DELETE key
on VT100 series terminals). See Appendix EDT.3.2 for a diagram of the keypad key
numbers you use to define keypad keys. Although you can define many keys as
control keys, you should not redefine specialized control keys, such as CTRL/C,
CTRL/M, CTRL/O, CTRL/P, CTRL/Q, CTRL/R, CTRL/S, CTRL/T, CTRL/U,
CTRL/Y, and CTRL/Z.
The following example of a key definition redefines GOLD + S to perform a global
substitution, with prompts for the search string and the replacement string.
❖DEFINE KEY GOLD S AS "EXT S/?*’REPLACE:

’/?*’

WITH:

’/WHOLE."

The string between quotation marks consists of an EDT nokeypad-editing command
(EXT, which tells EDT that the rest of the line is an EDT line-editing command); an
EDT line-editing command (SUBSTITUTE, abbreviated "S"); its qualifier (WHOLE);
prompts (the question marks followed by the prompts REPLACE and WITH, and
the asterisk (*) directly following the question mark prompt, allowing you to use
either ENTER or RETURN to enter your response). Note that the period at the end
of the definition (before the final quotation mark) is necessary to make the command
execute immediately when the key is pressed. Subsequent use of GOLD + S performs
the substitution, prompting for old and new strings and displaying the substitutions.
I am happy to inform you that Justice H. Osgood has
accepted our offer of the position of town programmer.
For those of you who were unable to interview him, Mr.
Osgood comes from Steeple Creek, Vermont, where he served as
chief statistician, responsible for designing and
implementing their current budget system.
He leaves Steeple
Creek in July to join us September 1. I am especially glad
to have him since he brings not only an excellent
programming background, but experience in town management as
well.
[EOB]
I GOLD 1 +

[s]

REPLACE:

Osgood

I enter I

WITH:

Osgoode

1 enter 1

1 am happy to inform you that Justice H.
Osgoode has
unable to interview him, Mr. Osgoode comes from Steeple
2 substitutions

3-36

Editing Files with the EDT Editor

Placing key definitions (such as the GOLD + S definition) in an EDT startup
command file makes the redefined keys available during every editing session.

3.7.5 Defining EDT Macros
An EDT macro allows you to execute a sequence of EDT line-editing commands
whenever you invoke the macro. To define a macro, follow these steps:
1.

Use the EDT line-editing command DEFINE MACRO to define the name of a
buffer as the macro name. For example, to define a macro named "heading,"
type:
Command:

Create and enter a buffer with the same name as the macro. (See Section 3.6.7
for information about using multiple buffers.)
Command:

DEFINE MACRO heading

FIND=heading

Type the EDT line-editing commands in the desired sequence, one command per
line. The following macro inserts a four-line heading.
INSERT;NAME:
INSERT;DEPT:
INSERT;DATE:
INSERT;SUBJ:
[EOB]

Exit from the buffer.
Command:

FIND=MAIN.

To invoke the macro, enter its name as an EDT line-editing command. For example:
Command:

HEADING

The lines of the heading are inserted at the cursor position.
NAME:
DEPT:
DATE:
SUB J:
To make a macro available during other editing sessions, you can place the DEFINE
MACRO command and the macro command sequence in an EDT startup command
file. When you include a macro definition in a startup command file, be sure
the command sequence contains the commands for entering the macro buffer

that you must precede each command in the sequence with the INSERT comm
For example, to use the macro HEADING in an EDT startup command file pre
each insertion with the INSERT command:
DEFINE MACRO HEADING
FIND=HEADING
INSERT;INSERT:NAME:
INSERT;INSERT;DEPT:
INSERT;INSERT;DATE:
INSERT;INSERT;SUBJ:
FIND=MAIN

You can also redefine a key to accomplish the same results as the macro. The
following example defines GOLD + J to insert the heading of the previous ma
example:
*DEF KEY GOLD J AS "I~Z~MINAMEZ~MIDEPTZ~MIDATEZ~MISUBJZ~M."

For more information about key definitions and macro definitions, see Appendi

Chapter 4
Using DIGITAL Standard Runoff
DIGITAL Standard Runoff (DSR) processes source files into formatted text and
intermediate files and creates tables of contents and indexes. You process source and
intermediate files with the RUNOFF, RUNOFF/CONTENTS, and RUNOFF/INDEX
commands.
The source DSR file is your creation. It can contain text and DSR commands. The
DSR commands cause the text to be formatted into sections, paragraphs, lists, and
so on. DSR commands start with the control flag, which is usually represented by a
period (you can change the character). Five examples of DSR commands follow.
.BREAK
.BLANK
.BLANK 2
.RIGHT MARGIN 34
.CENTER;Twelve Days of Dieting
The .BREAK command ends the current line. The .BLANK command without a
parameter inserts a blank line in the text. The .BLANK command with the parameter
2 inserts two blank lines in the text. The .RIGHT MARGIN command sets the
right margin at position 34. The .CENTER command centers the text following the
semicolon.
You can abbreviate DSR command names. The abbreviations must be exactly as
listed in Appendix DSR.2. (You cannot always abbreviate simply by shortening the
command name to any length as in DCL.) The abbreviations for .BLANK, .CENTER,
and .RIGHT MARGIN are .B, .C, and .RM.
DSR commands can be typed in uppercase, lowercase, or a combination of uppercase
and lowercase.
On any line containing a DSR command, the first item on the line must be a DSR
command and the control flag must occupy position 1. Depending on the particular
commands, a line containing a command may contain additional commands and/or
text. Note the following examples:
.BLANK 2

command.
.CENTER;Twelve Days of Dieting

This command and text are placed on one line. The semicolon acts as the command
terminator.
.BLANK 2.CENTER;Twelve Days of Dieting

Two commands are placed on one line. The beginning of the second command
terminates the first command.
See Appendix DSR.2 for the complete rules for entering DSR commands and for a
description of each command. The following example demonstrates the use of the
DSR commands .BLANK and .CENTER to format text.
.RIGHT MARGIN 34
.CENTER;Twelve Days of Dieting
.CENTER;Watching Your Weight Increase
.BLANK 2
On the twelfth day of dieting, Millitsa gave to me,
.BREAK
Twelve hot fudge sundaes,
.BREAK
Eleven Hostess Twinkies,
.BREAK
Ten cherry cheese cakes,
.BLANK
Nine lady fingers,
.BREAK
Eight date nut muffins,
.BREAK
Seven oatmeal cookies,
.BREAK
Six bags of Fritos,
.BREAK
Five coffee rings,
.BLANK
Four sticky buns,
.BREAK
Three Clark bars,
.BREAK
Two marbled cakes,
.BREAK
And a pizza with pepperoni.

Using DIGITAL Standard Runoff

4-3

The preceding lines coded in DSR produce the following output:
Twelve Days of Dieting
Watching Your Weight Increase
On the twelfth day of dieting, Millitsa gave to me,
Twelve hot fudge sundaes.
Eleven Hostess Twinkies,
Ten cherry cheese cakes,
Nine lady fingers,
Eight date nut muffins.
Seven oatmeal cookies,
Six bags of Fritos,
Five coffee rings,
Four sticky buns,
Three Clark bars.
Two marbled cakes,
And a pizza with pepperoni.
You should avoid editing the output file from a DSR operation. You should instead
modify the DSR file and reprocess it. If you do make minor modifications to the
output file, note that the file does not have the carriage return record attribute (which
causes each record in the file to produce a new line automatically when the file
is displayed or printed); the carriage return and line feed control characters are
embedded in the file.

4.1

Formatting Text

You can format text into paragraphs, lists, and literal text. You can adjust the margins
and you can adjust the spacing between lines or blocks of lines. DSR also provides
commands for leaving blocks of space on a page and for writing notes and footnotes.

You can control such features as bolding and underlining with embedded flags.
By default, DSR treats certain characters as flags rather than text. For example,
by default, a character is underlined if it is preceded by an ampersand (&). (To
place an actual ampersand in the text, you must write an ampersand preceded
by an underscore (_&) or you must turn off the flag governing that character.)
One approach is to turn off all flags at the start of your DSR file. The following
commands turn off all flags that are on by default.

4-4

Using DIGITAL Standard Runoff

Flag Command

Flag Character

.NO FLAGS ACCEPT

Underscore (_) by default

.NO FLAGS COMMENT

Exclamation point (!) by default

.NO FLAGS LOWERCASE

Backslash (\) by default

.NO FLAGS SPACE

Number sign (#) by default

.NO FLAGS SUBINDEX

Right angle bracket (> ) by default

.NO FLAGS UNDERLINE

Ampersand (&) by default

.NO FLAGS UPPERCASE

Circumflex Q by default

When you need a particular flag, set the flag on (.FLAGS command), write the text
that uses the flag, and set the flag off (.NO FLAGS command). (See Section 4.1.9.)
You can change the special flag character when you specify the .FLAGS command.

4.1.1 Filling and Justifying Text
By default, DSR fills and justifies text. Filling causes words from the input file to be
placed on one output line until the addition of another word would exceed the right
margin. Justification causes DSR to add spaces between words to expand each line
exactly to the right margin. The following example demonstrates how text is filled
and justified.
.RIGHT MARGIN 45
For it so falls out.
That what we have
we prize not
to the worth
while we enjoy it;
but being lacked,
lacked and lost.
Why,
then we rack the value.
The preceding lines coded in DSR produce the following output:
For it so falls out.
That what we have
we prize not to the worth while we enjoy
it; but being lacked, lacked and lost,
Why, then we rack the value.
If you do not want filling or justification, you must explicitly specify the .NO FILL
command or the .NO JUSTIFY command before you write the text. You can turn
filling or justifying back on again by specifying the .FILL or .JUSTIFY command. The
following example turns off justification but retains filling, which produces a ragged
right margin.

.NO JUSTIFY
For it so falls out.
That what we have
we prize not
to the worth
while we enjoy it;
but being lacked,
lacked and lost,
Why,
then we rack the value.
.JUSTIFY

The preceding lines coded in DSR produce the following output:
For it so falls out, That what we have
we prize not to the worth while we enjoy
it; but being lacked, lacked and lost,
Why, then we rack the value.

The next example turns off both filling and justifying, which formats the outpu
in the same way as the input lines.
.NO FILL.NO JUSTIFY
For it so falls out,
That what we have
we prize not
to the worth
while we enjoy it;
but being lacked,
lacked and lost,
Why,
then we rack the value.
.FILL.JUSTIFY

The preceding lines coded in DSR produce the following output:
For it so falls out,
That what we have
we prize not
to the worth
while we enjoy it;
but being lacked,
lacked and lost,
Why,
then we rack the value.

The text of the examples in this section is from William Shakespeare's Much A
About Nothing.

4-6

Using DIGITAL Standard Runoff

4.1.2 Adjusting Margins and Centering Text
By default, margins are set at 0 and 70. You can change the margin settings with the
.LEFT MARGIN and .RIGHT MARGIN commands. The following example changes
the right margin to position 60.
.RIGHT MARGIN 60
<remainder of DSR file>
To indent one or more lines of text on the left, increase the left margin setting. After
you write the indented text, decrease the left margin setting by the same amount.
You can indent on the right by decreasing the right margin setting, writing the text,
and increasing the right margin setting. The following example indents text by 10
spaces on either margin.
<first part of DSR file>
.LEFT MARGIN +10.RIGHT MARGIN -10
<indented text>
.LEFT MARGIN -10.RIGHT MARGIN +10
<remainder of DSR file>
You can indent a single line of text from the left margin with the .INDENT
command. The following example indents a line of text eight spaces.
.INDENT 8
<line of text>
You can indent a single line of text from the right margin with the .RIGHT command.
You can also use the .RIGHT command to position a single line of text against the
right margin.
.RIGHT 0
<line of text>
To center text between two margins, use the .CENTER command. You can place the
text to be centered on the line following the command, as shown:
.CENTER
<text to be centered>
Or you can terminate the .CENTER command with a semicolon and place the text to
be centered on the same line.
.CENTER;<text to be centered>

Using DIGITAL Standard Runoff

4-7

4.1.3 Writing Paragraphs
To separate text into paragraphs, place the .PARAGRAPH command between
paragraphs. By default, the .PARAGRAPH command indents the first line of a
paragraph five spaces, inserts one blank line before starting a new paragraph, and
tests to ensure that room remains on the page for at least four lines of text. You can
change the parameter values when you issue your first .PARAGRAPH command
or by placing a .SET PARAGRAPH command at the top of the file. The following
example does not indent the first line of each paragraph and ensures that room
remains on the page for at least three lines of text.
.SET PARAGRAPH 0,1,1
<paragraph of text>
.PARAGRAPH
<paragraph of text>
.PARAGRAPH

You can also separate text by inserting .BLANK or .SKIP commands. The .BLANK
command inserts the exact number of lines specified by the parameter (which
defaults to 1). The .BLANK command does not provide for indentation or for testing
the room left on the page; you can perform these actions with the .INDENT and
.TEST PAGE commands as desired. The following example separates two blocks of
text with one blank line, after first testing to ensure that at least three lines remain
on the page.
<block of text>
.TEST PAGE 3
.BLANK
<block of text>
The .SKIP command takes into account the spacing you have in effect. When the
default is in effect (spacing is 1), .BLANK and .SKIP are equivalent. However,
if multiple spacing is in effect, the .SKIP command multiplies the skip value by
the spacing value. You can specify something other than single spacing with the
.SPACING command. (The .SPACING command also affects the test page value
in the .PARAGRAPH and .SET PARAGRAPH commands.) The following example
demonstrates double spacing with two extra lines between blocks of text.
.SPACING 2
<block of text>
.SKIP
<block of text>
.SKIP

You can place text in the output file exactly as it appears in the DSR file by enclosing
it between .LITERAL and .END LITERAL commands.
.RIGHT MARGIN 34
.BLANK 2
.LITERAL
Twelve Days of Dieting
Watching Your Weight Increase
On the twelfth day of dieting, Millitsa gave to me,
Twelve hot fudge sundaes,
Eleven Hostess Twinkies,
Ten cherry cheese cakes,
Nine lady fingers,
Eight date nut muffins,
Seven oatmeal cookies,
Six bags of Fritos,
Five coffee rings,
Four sticky buns,
Three Clark bars,
Two marbled cakes,
And a pizza with pepperoni.
.END LITERAL

Using DIGITAL Standard Runoff

4-9

Literal text is not filled and not justified—lines are the same as in the input file.
Except for the .END LITERAL command, commands and flags are not recognized
in literal text. In addition, commands and flags placed before the literal text do not
affect the literal text except that you can set the left margin, set tab stops, set spacing,
start bolding, and start underlining. You cannot reset any of these items until the
literal text ends (for example, you would have to bold the entire literal block). The
following example indents the literal text (the .MARGIN commands must be outside
the literal block).
<text filled and justified>
.LEFT MARGIN +5
.LITERAL
<literal text>
.END LITERAL
.LEFT MARGIN -5
If you want the positional effect of literal text but also want to use commands and
flags, you can turn off filling and justifying (.NO FILL and .NO JUSTIFY) and turn
it back on after the literal text. If the literal text contains blank lines, specify .KEEP
when you turn off the filling and justification.
<text filled and justified>
.NO FILL
.NO JUSTIFY
.KEEP
ciiteral text>
.FILL
.JUSTIFY
.NO KEEP
For a short number of lines, you might alternatively place .BREAK or .BLANK
commands (specify .BLANK 0 for single spacing) between the literal lines.

4.1.5 Writing Lists
You can format text as lists. You can choose among several types of lists; numbered,
bulleted, and lettered are possiblities.

4-10

Using DIGITAL Standard Runoff

4.1.5.1 Numbered Lists
The following three commands format a numbered list:
•

.LIST—Starts the list by leaving one blank line and indenting. The text of the
list is indented nine spaces if the left margin is currently 0. Otherwise, the text
of the list is indented four spaces.

•

.LIST ELEMENT—Starts an element within the list. You can have any number
of elements.

•

.END LIST—Ends the list and writes a blank line.

Each element is preceded by a number starting with number 1. Elements are
separated by blank lines.
Note the following example:
.LIST
.LIST ELEMENT;grosbeak
.LIST ELEMENT;goldfinch
.LIST ELEMENT;redpoll
.LJST ELEMENT;sparrow
.END LIST
The preceding lines coded in DSR produce the following output:
1.

grosbeak

goldfinch

redpoll

sparrow

The text for each list element can be placed after the semicolon terminating the
command (as shown in the example) or can be placed on a line or lines following the
command. A single list element continues until the next .LIST ELEMENT command
or an .END LIST command occurs. The list element can contain commands and
flags.
You can change the spacing between list elements by specifying the number of
spaces as parameter 1 to the .LIST command. For example, .LIST 0 places no spaces
between list elements.

4.1.5.2 Bulleted Lists

By default, DSR creates a numbered list. You can substitute another character
numbers by specifying the character as the second parameter of the .LIST com
The character must be enclosed in quotation marks or apostrophes; the charac
does not have to be preceded by a comma if the first parameter is not specified
example, the lowercase o gives the effect of a hollow bullet.
.LIST "o"
.LIST ELEMENT;ferret
.LIST ELEMENT;mink
.LIST ELEMENT;rabbit
.LIST ELEMENT;sable
.LIST ELEMENT;raccoon
.END LIST ELEMENT

The preceding lines coded in DSR produce the following output:
o

ferret

mink

rabbit

sable

raccoon

4.1.5.3 Nested Lists

You can nest one list within another as long as the nested list is entirely withi
element of the outer list. Note the following example:
.LIST 0
.LIST ELEMENT;German
.LIST ELEMENT;Russian
.LIST ELEMENT;Swedish
.LIST ELEMENT;Yugoslavian
.LIST 0, "o"
.LIST ELEMENT;Serbian
.LIST ELEMENT;Croatian
.LIST ELEMENT;Macedonian
.END LIST 0
.LIST ELEMENT;Turkish
.LIST ELEMENT;Scottish
.LIST ELEMENT;Irish
.END LIST

The preceding lines coded in DSR produce the following output:

Using DIGITAL Standard Runoff

4-12

1.
2.
3.
4.

5.
6.
7.

German
Russian
Swedish
Yugoslavian
o
Serbian
o
Croatian
o
Macedonian
Turkish
Scottish
Irish

4.1.5.4 Letters and Roman Numerals
By default, DSR numbers lists with decimal numbers. Instead, you can use letters or
roman numerals in uppercase or lowercase by specifying them with the .DISPLAY
ELEMENTS command. You must write the .DISPLAY ELEMENTS command after
the .LIST command for the list and before the first .LIST ELEMENT command. The
following example writes a numbered list using lowercase roman numerals.
.LIST 0
.DISPLAY ELEMENTS RL
.LIST ELEMENT;tan
.LIST ELEMENT;beige
.LIST ELEMENT;rust
.LIST ELEMENT;brown
.END LIST
The preceding lines coded in DSR produce the following output:
i. tan
ii. beige
iii. rust
iv. brown

4.1.6 Leaving Space on a Page
The text of a file usually starts on the fourth or fifth line from the top of a page
depending on the layout of the document. To leave extra space at the top of a page,
specify the amount desired in a .FIGURE command (the .BLANK command does
not work at the top of a page). To leave extra space in the middle of a page, you
can use either the .FIGURE or .BLANK command. If you absolutely must have a
certain amount of space all on one page, use the .FIGURE or .FIGURE DEFERRED
command. These commands insert the required space on the next page if it will
not fit on the current page. However, the .FIGURE command leaves the rest of the
current page blank whereas the .FIGURE DEFERRED command fills the rest of the
current page using the text and commands that follow the .FIGURE DEFERRED
command.

Using DIGITAL Standard Runoff

4-13

The following example writes 40 blank lines to the current page if they will fit;
otherwise, the 40 blank lines are placed at the top of the next page and the current
page is filled from the input lines following the .FIGURE DEFERRED line.
<text filled and justified>
.FIGURE DEFERRED 40
<text filled and justified>

You can also create space on a page by issuing the .LITERAL command, pressing
RETURN once for each empty line, and issuing the .END LITERAL command. This
technique allows you to see the amount of space you are creating. However, the
space will be split if you cross page boundaries.

4.1.7 Writing Notes
The .NOTE command narrows the left and right margins, inserts a blank line, writes
a centered title, inserts a blank line, and writes the text that follows the .NOTE
command. The .END NOTE command writes a blank line and restores the margin
settings. The title defaults to the word NOTE.
The following example writes a note with the title CAUTION.
.NOTE CAUTION
Do not operate the machine outdoors in wet weather.
Do not operate the machine in a wet area indoors or outdoors.
Such actions may lead to a severe electrical shock.
.END NOTE

The preceding lines coded in DSR produce the following output:
CAUTION
Do not operate the machine outdoors
in wet
weather.
Do not
operate the machine in a wet area indoors or
outdoors.
Such actions may
lead
to
a
severe
electrical shock.

4.1.8 Writing Footnotes
The .FOOTNOTE command places the text following the command at the bottom of
the page if enough room exists. If enough room does not exist for the entire footnote,
it is placed at the bottom of the next page. No automatic formatting occurs—you
must format the footnote with DSR commands as you see fit. In addition, no
automatic footnote symbols are provided. The .END FOOTNOTE command ends
the footnote and automatically restores any case, fill, justify, and margin settings you
might have changed within the footnote.

Press the START button firmly.
Release the START button as soon as the engine starts.(1)
.FOOTNOTE.BLANK.LEFT MARGIN +4.INDENT -4

(1)
If the engine does not crank, ensure that the battery cables
are firmly connected to the battery. Sometimes the cables are
disconnected for shipping.
.END FOOTNOTE
Push the choke in until you hear it click.
Pull the throttle about halfway down but do not let the
engine stall.
After about two minutes, push the choke all the way in
and pull the throttle all the way down.
.PARAGRAPH 0
Before engaging the drive train, ensure that you are in a
comfortable position to operate the machine.
Two seat controls are provided for your comfort.

The preceding lines coded in DSR produce the following output:
Press the START button firmly.
Release the START button as
soon as
the engine starts.(1) Push the choke in until you hear it click.
Pull
the throttle about halfway down but do not
let the
engine
stall.
After about two minutes, push the choke all the way in and pull the
throttle all the way down.
Before engaging the drive train, ensure that you are in a comfortable
position to
operate the machine.
Two seat controls are provided for
your comfort.
(1)

If the engine does not crank, ensure that the battery
firmly connected to the battery.
Sometimes the
disconnected for shipping.

cables
cables

are
are

4.1.9 Bolding and Underlining Text
To bold a single character, turn the bold flag on if it is not already on (the bold flag
is off by default); in the text, precede the character to be bolded by the bold flag (an
asterisk by default); turn the bold flag off to enable the use of the flag as a normal
character. The following example bolds the numbers 3 and 7.
.FLAGS BOLD
Follow route *3 to route *7.
.NOFLAGS BOLD

Using DIGITAL Standard Runoff

4-15

To underline a single character, turn the underline flag on if it is not already on (the
underline flag is on by default); in the text, precede the character to be underlined by
the underline flag (an ampersand by default); turn the underline flag off to enable the
use of the flag as a normal character. The following example underlines the letters A
and B.
.FLAGS UNDERLINE
&A is for Amy and &B is for Basil.
.NOFLAGS UNDERLINE
To bold or underline a block of text, turn on the uppercase and lowercase flags if they
are not already on (they are on by default) in addition to the bold or underline flag;
start the block of text with the uppercase flag (a circumflex by default) followed by
the bold or underline flag; end the block of text with the lowercase flag (a backslash
by default) followed by the bold or underline flag. The following example bolds a
line of text.
.FLAGS BOLD
.FLAGS UPPERCASE
.FLAGS LOWERCASE
~*KEEP OFF THE GRASS, PLEASE\*
.NOFLAGS BOLD
.NOFLAGS UPPERCASE
.NOFLAGS LOWERCASE

4.2 Laying Out a Document
By default (if you do not specify .LAYOUT, .CHAPTER, or .APPENDIX commands),
DSR produces a document of consecutively numbered pages. On each page, the text
area is the fourth line through the bottom line. Page numbers appear in the upper
right corner as "Page 2," "Page 3," and so on, starting with page 2. Running heads
(chapter names or other designated text) appear in the upper left corner.
You can adjust the position of page numbers and running heads with the .LAYOUT
command. Layout codes 1, 2, and 3 center the page number at the bottom of the
page. Layout code 1 centers running heads at the top of the page; layout code 2
moves the running heads to one upper corner or the other depending on whether the
page number is odd or even; layout code 3 puts the running heads in the upper left
comer and puts the date in the upper right corner. You should specify the .LAYOUT
command at the beginning of your file. The following command adjusts the layout
to code 2.
.LAYOUT 2,3

4-16

Using DIGITAL Standard Runoff

4.2.1 Chapters and Appendixes
To break a document into chapters, start each chapter with the .CHAPTER command.
The title of the chapter must follow the command name on the same line. The lines
following the .CHAPTER command are part of that chapter until another .CHAPTER
command or an .APPENDIX command is given.
By default, chapters are numbered consecutively within the document, beginning
with chapter 1. You can force the numbering of a chapter (for example, in order to
place each chapter in a separate file) by preceding the .CHAPTER command with a
.NUMBER CHAPTER command. The following example begins chapter 2.
.NUMBER CHAPTER 2
.CHAPTER starting procedures
The preceding lines coded in DSR produce the following output:
<12 blank lines>
CHAPTER 2
STARTING PROCEDURES
DSR starts a chapter on a new page with 12 blank lines at the top of the page. The
number of the chapter and the chapter title are centered on the page in uppercase.
You can adjust the appearance of the chapter number with the .DISPLAY CHAPTER
command.
The .APPENDIX, .NUMBER APPENDIX, and .DISPLAY APPENDIX commands work
similarly to the chapter commands, except that by default appendixes are lettered
sequentially starting with appendix A. The following example starts appendix C.
.NUMBER APPENDIX C
.APPENDIX connecting the battery

4.2.2 Sections
The .HEADER LEVEL command divides a document into sections and subsections
identified by a decimal numbering scheme to a maximum depth of 6. The topmost
section is header level 1. Each level is numbered sequentially starting with 1 unless
a .NUMBER LEVEL command precedes the .HEADER LEVEL command. The
following example shows a document with three sections.
<text>
.HEADER LEVEL 1 normal starting
<text>
.HEADER LEVEL 1 cold weather starting
<text>
.HEADER LEVEL 1 troubleshooting
<text>

<text>
1
NORMAL STARTING
<text>
2 COLD WEATHER STARTING
<text>
3 TROUBLESHOOTING
<text>

Subsections are numbered within their respective higher-level sections.
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>
.HEADER LEVEL
<text>

1 normal starting
2 cold engine
2 warm engine
1 cold weather starting
2 above zero
2 below zero
1 troubleshooting

The preceding lines coded in DSR produce the following output:
<text>
1
NORMAL STARTING
<text>
1.1
Cold Engine
<text>
1.2 Warm Engine
<text>
2 COLD WEATHER STARTING
<text>
2.1 Above Zero
<text>
2.2 Below Zero
<text>
3 TROUBLESHOOTING
<text>

4-18

Using DIGITAL Standard Runoff

If the sections are within chapters or appendixes, the section number is prefixed by
the chapter or appendix identifier and a decimal point.
.NUMBER CHAPTER 2
.CHAPTER starting procedures
<text>
.HEADER LEVEL 1 normal starting
<text>
.HEADER LEVEL 1 cold weather starting
<text>
.HEADER LEVEL 1 troubleshooting
<text>

The preceding lines coded in DSR produce the following output:
<chapter heading and text>
2.1 NORMAL STARTING
<text>
2.2 COLD WEATHER STARTING
<text>
2.3 TROUBLESHOOTING
<text>

You can force the numbering of a section with the .NUMBER LEVEL command. The
following example forces the start of section 1.2.
.NUMBER LEVEL 1,2
.HEADER LEVEL 2 Warm Engine

You can change the appearance of section headers with the .STYLE HEADERS
command. The default .STYLE HEADERS settings cause level 1 headers to be
written in all uppercase and level 2 headers to be written with the initial letter of
every word in uppercase. The following command changes the settings so that the
headers below level 1 are written exactly as you type them.
.STYLE HEADERS 3,1,0,7,7,2,1,9,2

4.2.3 Running Heads
By default, chapter and appendix titles appear as the first line of running heads. If
the document does not contain chapters or appendixes, no running heads appear.
Running heads are always placed at the top of the page; their exact position can be
changed with the .LAYOUT command.
To use level 1 header titles as the second line of running heads, issue the following
commands at the start of your DSR file.
.SUBTITLE
.AUTOSUBTITLE

Using DIGITAL Standard Runoff

4-19

To use titles other than chapter and section titles as running heads, use the .TITLE
and .SUBTITLE commands. The .TITLE command affects the first line of the running
head; the .SUBTITLE command affects the second line of the running head.
The title specified by a .TITLE command remains in effect until another .TITLE or
.CHAPTER command occurs. If you want to use a specified title in place of a chapter
name, issue the .TITLE command immediately after the .CHAPTER command. The
title specified by a .SUBTITLE command remains in effect until another .SUBTITLE
command occurs or until a .HEADER LEVEL command occurs if automatic subtitles
are in effect.

4.2.4 Pagination
If the document is not chapter oriented, pagination is sequential throughout the
document. If the document is chapter oriented, pagination is sequential throughout
the document only if .LAYOUT 3 is in effect. Otherwise, pagination is sequential
within each chapter and appendix; the page number starts with the chapter or
appendix identifier and a hyphen.
You can suspend the numbering of pages with the .NO NUMBER command (unless
.LAYOUT 3 is in effect). You can write a document that is not paged (no running
heads, no page numbers) by issuing the command .NO PAGING.

4.3 Processing DSR Files
Enter the RUNOFF command to process a DSR file. Specify the name of the DSR file
as the parameter; the file type defaults to RNO. The following example processes a
file named MESS.RNO in your default directory.
$ RUNOFF MESS
If you do not specify the /OUTPUT qualifier, the RUNOFF command produces
an output file with the same name as the input file and a file type of MEM. The
preceding example produces an output file named MESS.MEM. The following
example produces an output file named MESS.MEM from a DSR file named
TEMPLATE.RNO.
$ RUNOFF/OUTPUT=MESS TEMPLATE
See Appendix DSR.l for a complete description of the RUNOFF command and its
qualifiers.

4-20

Using DIGITAL Standard Runoff

4.3.1 Producing a Table of Contents
To produce a table of contents, take the following steps:
1.

Produce an intermediate (BRN) file—Specify the /INTERMEDIATE qualifier
when you process the DSR (RNO) file. The name of the intermediate file is the
same as the name of the DSR file but with a file type of BRN, unless you specify
a different name. You will also get the usual output (MEM) file; you can specify
/NOOUTPUT if you do not want the MEM file.

Produce an unformatted table of contents (RNT) file—Issue the command
RUNOFF/CONTENTS specifying the intermediate file as input. This command
produces a file with the same name as the input file but a file type of RNT.

Produce a formatted table of contents (MEC) file—Issue the RUNOFF command
specifying the RNT file as input. You must specify the file type. This command
produces a file with a file type of MEC containing the formatted table of contents.

The following example processes a file named OPER.RNO and produces an output
file named OPER.MEM and a table of contents named OPER.MEC.
$ RUNOFF/INTERMEDIATE OPER
$ RUNOFF/CONTENTS OPER
$ RUNOFF OPER.RNT
To produce a table of contents from more than one file, you must concatenate the
intermediate files when you issue the RUNOFF/CONTENTS command. (You cannot
use wildcard characters.) The following example produces output files and a single
table of contents from three DSR files.
$
$
$
$
$

RUNOFF/INTERMEDIATE 0PER1
RUNOFF/INTERMEDIATE 0PER2
RUNOFF/INTERMEDIATE 0PER3
RUNOFF/C0NTENTS/0UTPUT=0PER 0PER1+0PER2+0PER3
RUNOFF OPER.RNT

The table of contents is based on the .CHAPTER, .APPENDIX, and .HEADER LEVEL
commands in your DSR file. You can control the formatting to some extent with the
qualifiers to the RUNOFF/CONTENTS command. (See Appendix DSR.l.) You can
write additional information to the table of contents with the command .SEND TOC.

Using DIGITAL Standard Runoff

4-21

4.3.2 Producing an Index
An index is based on .INDEX and .ENTRY commands in your DSR file. (You can
also use the index flag to index a word of text.) The .INDEX command names an
item to be placed in the index. You should position the .INDEX command as close
as possible to the text being indexed. The item appears in the index followed by the
number of the page on which it was written to the formatted text (MEM) file. The
following example makes index entries for each section.
<text>
.HEADER LEVEL 1 Normal Starting
.INDEX Normal starting
<text>
.HEADER LEVEL 1 Cold Weather Starting
.INDEX Cold weather starting
<text>
.HEADER LEVEL 1 Troubleshooting
.INDEX Troubleshooting
<text>
The index entries would take the following appearance:
Cold weather starting,
Normal starting, 2-1
Troubleshooting, 2-3

2-2

Use the subindex flag (by default a right angle bracket) to indicate subentries in
the index. A subentry is listed under the higher-level item in the index and has its
own page number. The subindex flag must be turned on. The following example
produces one index entry for "Starting" under which are listed the two subentries
"normal" and "cold weather".
<text>
.HEADER LEVEL 1 Normal Starting
.FLAGS SUBINDEX
.INDEX Normal starting
.INDEX Starting>normal
.NOFLAGS SUBINDEX
<text>
.HEADER LEVEL 1 Cold Weather Starting
.FLAGS SUBINDEX
.INDEX Cold weather starting
.INDEX Starting>cold weather
.NOFLAGS SUBINDEX
<text>
.HEADER LEVEL 1 Troubleshooting
.INDEX Troubleshooting
<text>

4-22

Using DIGITAL Standard Runoff

The index entry for "Starting" would have the following appearance:
Starting
cold weather, 2-2
normal, 2-1
You can make an entry without a page number in the index with the .ENTRY
command. Usually these index entries are used for cross references. The following
example produces an index entry for "Weather" under which the subentry "see cold
weather" appears without a page number.
.FLAGS SUBINDEX
.ENTRY Weather>see cold weather
The index entry would have the following appearance:
Weather
see cold weather
To produce an index, take the following steps:
1.

Produce an unformatted index (RNX) file—Issue the command RUNOFF/INDEX
specifying the intermediate file as input. This command produces a file with the
same name as the input file but a file type of RNX.

Produce a formatted index (MEX) file—Issue the RUNOFF command specifying
the RNX file as input. You must specify the file type. This command produces a
file with a file type of MEX containing the formatted index.

The following example processes a file named OPER.RNO and produces an output
file named OPER.MEM, a table of contents named OPER.MEC, and an index named
OPER.MEX.
$ RUNOFF/INTERMEDIATE OPER
$ RUNOFF/CONTENTS OPER
$ RUNOFF/INDEX OPER
$ RUNOFF OPER.RNT
$ RUNOFF OPER.RNX
To produce an index from more than one file, you must concatenate the intermediate
files when you issue the RUNOFF/INDEX command. (You cannot use wildcard
characters.) The following example produces formatted text files, a single table of
contents, and a single index from three DSR files.

Using DIGITAL Standard Runoff

4-23

$ RUNOFF/INTERMEDIATE 0PER1
$ RUNOFF/INTERMEDIATE 0PER2
$ RUNOFF/INTERMEDIATE 0PER3
$ RUNOFF/CONTENTS/OUTPUT=OPER 0PER1+0PER2+0PER3
$ RUNOFF/INDEX/OUTPUT=OPER 0PER1+0PER2+0PER3
$ RUNOFF OPER.RNT
$ RUNOFF OPER.RNX

4.3.3 Printing Output Files
Keep in mind the following guidelines when printing nonlaser-output files produced
by DSR:
•

Copying files—You can copy a file (with the COPY command) to a printer, but
you may occasionally lose a form feed. More precisely, you lose a form feed
when the size of an output page equals 66 or the value that SYS$LP_LINES had
at the time the file was created if SYS$LP_LINES was defined as a logical name.
(Note that the current value of SYS$LP_LINES has no effect on the output file
after it is created.)

•

Generating automatic form feeds—In general, you should use the default for
the DCL command PRINT (PRINT/FEED) to generate form feeds automatically
when printing nonlaser files. However, you may occasionally generate a blank
page. More precisely, you generate a blank page when an output page equals 66
or the value that SYS$LP_LINES had at the time the file was created if
SYS$LP_LINES was defined as a logical name. (Note that the current value
of SYS$LP_LINES has no effect on the output file.) If you specify PRINT
/NOFEED, you eliminate the chance of a blank page, but you take the chance of
losing pages under the same circumstances as a COPY operation.

You should set up laser printers with the following commands, for example, in the
site-specific startup command procedure. Dsr$ln01 is the name you assign the laser
printer form. LpbO is the name of the printer.

4-24

Using DIGITAL Standard Runoff

$ ! Define form for dsr output on InOl laser printer
$
$ DEFINE/FORM dsr$ln01 /MARGIN=(B0TT0M=0) _$
/NOWRAP _$
/NOTRUNCATE _$
/STOCK=DEFAULT _$
/DESCRIPTION"dsr InOl form definition"
$
$ ! Set up InOl laser printer for dsr output
$
$ SET PRINTER lpbO
/NOTRUNCATE _$
/NOWRAP _$
/TAB _$
/PRINTALL _$
/FF _$
/NOCR
The print command should specify /NOFEED, the name of the form, and the name
of the queue. You should equate this command to a global symbol in your login file
or in the system login file. The following example makes LNPRINT a global symbol
that prints LN01 files.
$ ! Set up lnprint as print command for InOl laser printer
$
$ LNP+RINT == "PRINT/N0FEED/F0RM=dsr$ln01/QUEUE=ln01_queue"

Chapter 5
Data Representation
At DCL command level, the VAX/VMS operating system permits you to define and
run your own images; manipulate character and integer (whole-number) data; create
symbols for shorthand purposes or store variable data; and execute commands as
batch jobs rather than interactively.

5.1

Data Storage

Data is stored as follows:
•

Bit—The most basic unit of storage, a bit has a value of 0 or 1.

•

Byte—Equal to 8 bits, a byte has an unsigned value of 0 through 255 and a
signed value of -128 through 127.

•

Word—Equal to 2 bytes (16 bits), a word has an unsigned value of 0 through
65535 and a signed value of -32768 through 32767.

•

Longword—Equal to 4 bytes (32 bits), a longword has an unsigned value of 0
through 4294967295 and a signed value of -2147483648 through 2147483647.

A "low-order" unit means the first unit in the series. As a numeric value, the
low-order unit is the least significant unit in the number. The following conventions
are used in representing the values of storage units:
•

Character representation—A series of bytes representing characters is read left to
right. The leftmost character represents the low-order byte in the series.

•

Binary representation—A series of storage units representing numeric values is
read right to left. The rightmost unit represents the low-order unit in the series.

The units in a series of storage units are referenced by their offset from the
low-order unit, so that the low-order unit is unit 0, the next unit is unit 1, and so
on. Numeric values can be stated in hexadecimal, octal, or decimal radixes. The
following examples illustrate the conventions for representing data.

Example 1: Assume that the word MAINTASK has been stored as a series of
characters.
Character representation:
bytes = M A I N T A S K
offsets =01234567
Hexadecimal representation on a per-byte basis:
bytes = 4B 53 41 54 4E 49 41 4D
offsets = 76543210
Hexadecimal representation on a per-word basis:
words = 4B53 4154 4E49 414D
offsets =3210
Hexadecimal representation on a per-longword basis:
longwords = 4B534154 4E49414D
offsets =1
0
Octal representation on a per-byte basis:
bytes = 113 123 101 124 116 111 101 115
offsets = 765432
10
Decimal representation on a per-byte basis:
bytes = 75 83 65 84 78 73 65 77
offsets = 76543210

Example 2: Assume that the numbers 9001 and 9002 are stored in two consecutive
longwords.
Decimal representation on a per-longword basis:
longwords = 9002 9001
offsets =10
Octal representation on a per-longword basis:
longwords = 021462 021461
offsets =1
0
Hexadecimal representation on a per-longword basis:
longwords = 00002332 00002331
offsets =1
0
Hexadecimal representation on a per-word basis:
words = 0000 2332 0000 2331
offsets =3210
Hexadecimal representation on a per-byte basis:
bytes
00 00 23 32 00 00 23 31
offsets
76543210
Character representation:
bytes = 1 # . . 2 #
offsets =012345 6 7

(Periods mean the characters are not printable.)

Data Representation

5-3

Interpreting characters in octal and decimal on something other than a byte basis
makes no sense, as octal and decimal notation do not correspond evenly to the
storage capacity of a byte (as does hexadecimal, where one byte represents exactly
two digits). Likewise, interpreting numeric values in octal and decimal on something
other than the basis of the storage unit representing the number (a longword in the
example above) makes no sense.
Right-to-left and offset conventions are also used in referring to bit configurations.
For example, the bit configuration of hexadecimal FE (the low-order bit is 0 and the
remaining seven bits are 1) is written as 11111110.

5.1.1 Character Data
A character is one byte interpreted according to ASCII conventions. Appendix CHAR.2
includes tables of the ASCII character set and the DEC Multinational Character Set.
The first half of the numbered columns (0 through 7) in the ASCII table identifies the
character as you would enter it on a VT100 or VT200 series terminal or as you would
see it on a printer (except for the nonprintable characters). The remaining columns
identify the character by the binary value of the byte; the value is stated in three
radixes—octal, decimal, and hexadecimal. For example, the letter uppercase A has,
under ASCII conventions, a storage value of hexadecimal 41 (a bit configuration of
01000001), which is equivalent to 101 in octal notation and 65 in decimal notation.
Characters fall into three main categories:
•

Alphanumeric characters—The uppercase letters A through Z, the lowercase
letters a through z, the digits 1 through 9, the dollar sign ($), and the underscore
(-).

•

Special characters—All the other characters that can be displayed or printed: the
exclamation point (!), quotation marks ("), number sign (#), and so on.

•

Nonprintable characters—All characters that cannot be printed or displayed.
In general, nonprintable characters are ignored for display and print purposes.
However, several nonprintable characters serve control functions.
Character

Function

Starts printing or typing at the next horizontal tab

Starts printing or typing on the next line

Starts printing or typing at the top of the next page

Starts printing or typing at the first space on the same line

ESC

Introduces a terminal escape sequence

Inserts one space

5-4

Data Representation

EDT and the DUMP command represent the nonprintable characters with special
combinations of characters.

Character

Character
Name

NUL

Null

SOH-BS

Backspace

"A-'H

“A-'H

Horizontal tab

an actual tab

<LF>

Linefeed

Vertical tab

Form feed

Carriage Return

SO-SUB

Substitute

ESC

Escape

DUMP

EDT

<VT>
AL

<FF>

~N-Z

"N-AZ

■]

i
—

<CR>

<ESC>

RS
US

an actual space

SP
DEL

<DEL>

You can specify nonprintable characters with the F$FAO lexical function and
substring assignment statements (see Section 5.5.4). At DCL level, you can
generate certain control functions by holding down the CTRL key and typing the
letter corresponding to the control function.
CTRL/I

Generates a tab

CTRL/J

Generates a line feed

CTRL/L

Generates a form feed

CTRL/M

Generates a carriage return

A character string is a series of characters interpreted as a single entity. At DCL
command level and within command procedures, you specify character strings in
either of two formats:
•

Names—In name format, you enter the characters that constitute the character
string. The name can only include alphanumeric characters and some special
characters, depending on the use of the character string. Lowercase characters are
converted to uppercase. You use name format mainly for specifying command
names, qualifier names, some parameter and qualifier values, and symbol names.
$ MOUNT/SYSTEM DUA1 ACCOUNTS ACCOUNTS

Data Representation

5-5

MOUNT, SYSTEM, DUA1, ACCOUNTS, and ACCOUNTS are character strings
specified in name format.
•

Literals—In literal format, you enclose the characters that constitute the character
string in quotation marks. The literal can include all printable characters. (To
include a quotation mark in a character literal, type two consecutive quotation
marks.) Lowercase characters remain lowercase characters. You use literal format
mainly for assigning character strings to symbols and writing records with the
WRITE command.
$
$
$
$

D0G2 = "No tag, light brown, 30 lbs."
OPEN/WRITE POUND POUND.DAT
WRITE POUND "No tag, light brown, 30 lbs."
CLOSE POUND

Do not continue a literal from one line to the next. Assign the literal as several
literals to different symbols and concatenate the symbols.
$ D0G2A = "No tag, light brown, 30 lbs."
$ D0G2B = "- looks part beagle"
$ D0G2 = D0G2A + D0G2B

5.1.2 Numeric Data
A number is a series of decimal digits (the ASCII characters 0 through 9),
hexadecimal digits (the ASCII characters 0 through 9 and A through F), or octal
digits (the ASCII characters 0 through 7) interpreted as an integer. The number must
be in the range -2147483648 through 2147483647. (An error is not reported if a
number outside this range is specified or calculated, but an incorrect value results.)
At DCL command level and within command procedures, you specify a number as
follows:
•

Positive numbers—Specify a positive number by typing the appropriate digits.
The following example assigns the number 13 to the symbol DOG—COUNT.
$ D0G_C0UNT = 13
$ SHOW SYMBOL DOG.COUNT
DOG.COUNT = 13
Hex = 0000000D

•

Negative numbers—Precede a negative number with a minus sign.
$ BALANCE = -15237
$ SHOW SYMBOL BALANCE
BALANCE = -15237
Hex = FFFFC47B

•

Octal = 000015

Octal = 142173

Radix—Specify a number in a radix other than decimal by preceding the number
(but not the minus sign) with %X for hexadecimal numbers and %0 for octal
numbers.

5-6

Data Representation

$ DOG.COUNT = °/eXD
$ SHOW SYMBOL DOG.COUNT
DOG.COUNT = 13
Hex = OOOOOOOD
$ BALANCE = -#/,X3B85
$ SHOW SYMBOL BALANCE
BALANCE = -15237
Hex = FFFFC47B
•

Octal = 000015

Octal = 142173

Fractions—A number cannot include a decimal point. In calculations, fractions
are truncated; for example, 5 divided by 2 equals 2.

Numbers are stored internally as signed 4-byte integers: positive numbers have
values of 0 through 2147483647 and negative numbers have values of 4294967296
minus the absolute value of the number. The number -15237, for example, is
stored as 4294952059. Negative numbers are converted back to minus-sign
format for ASCII or decimal displays; however, they are not converted back for
hexadecimal and octal displays. For example, the number -15237 appears in displays
as hexadecimal FFFFC47B (decimal 4294952059) rather than hexadecimal -00003B85.
Numbers are stored in text files as a series of digits using ASCII conventions (the
digit 1 has a storage value of 49, and so on).

5.1.3 Logical Data
Some operations interpret numbers and character strings as logical data with values
as follows:
•

True—A number has a logical value of true if it is odd (that is, the low-order
bit is 1). A character string has a logical value of true if the first character is an
uppercase or lowercase T or Y.

•

False—A number has a logical value of false if it is even (that is, the low-order
bit is 0). A character string has a logical value of false if the first character is not
an uppercase or lowercase T or Y.

In both of the following examples, DOG—COUNT is assigned the value 13 (IF
STATUS means if the logical value of STATUS is true).

Example 1:
$ STATUS = 1
$ IF STATUS THEN D0G_C0UNT = 13

Example 2:
$ STATUS = "TRUE"
$ IF STATUS THEN D0G_C0UNT = 13

Data Representation

5-7

5.2 Expressions
Expressions are formed by combining data entities with operators. Operators are
denoted by:
•

Special characters—Asterisk (*), slash (/), plus sign ( + ), and minus sign (-).

•

Special names—.EQ., .GE., .GT., .LE., .LT, .NE., .NOT., .AND., and .OR.; the
names can be in uppercase or lowercase.

Data entities and operators can be adjacent or can be separated by any number of
spaces or tabs. The data entities can be symbols or literals. Expressions take two
forms:
•

Operations—An operation combines two data entities or alters a data entity. The
following example combines the values 10 and 3 by adding them.
$ D0G_C0UNT =10+3
$ SHOW SYMBOL D0G_C0UNT
D0G.C0UNT = 13
Hex = 0000000D

•

Octal = 000015

Comparisons—A comparison evaluates a relationship between two entities as
true or false. A true comparison evaluates to a numeric value of 1, and a false
comparison evaluates to a numeric value of 0. The following example compares
the value of DOG__COUNT with 13 and finds them to be equal.
$ D0G_CHECK = D0G_C0UNT .EQ. 13
$ SHOW SYMBOL DOG.CHECK
D0G.CHECK =1
Hex = 00000001

Octal = 000001

5.2.1 Character Expressions
In a character expression, the data entities must be literal character strings or symbols
equated to character strings. Attempting an operation or comparison between a
character string and a number causes the character string to be converted to a
number.
You can specify the following character operations:
•

Concatenation—The plus sign concatenates two character strings.
$
$
$
$

COLOR = "light brown"
WEIGHT = "30 lbs."
D0G2 = "No tag, " + COLOR + ", " + WEIGHT
SHOW SYMBOL D0G2
D0G2 = "No tag, light brown, 30 lbs."

5-8

•

Data Representation

Reduction—The minus sign removes the character string in the second specified
data entity from the character string in the first specified entity.
$ SHOW
D0G2
$ D0G2
$ SHOW
D0G2

SYMBOL D0G2
= "No tag, light brown, 30 lbs."
= D0G2 - ", 30 lbs."
SYMBOL D0G2
= "No tag, light brown"

If the character string in the second specified entity occurs more than once in the
first specified entity, only the first occurrence of the string is removed.
You can specify the types of character comparisons given in the following list. When
you make such comparisons, strings are compared character by character, and strings
of different lengths are not equal (for example, "dog" is greater than "dog" because
DCL pads the shorter string with NUL characters). The comparison criteria are the
ASCII values of the characters, so that the digits 0 through 9 are less than the letters
A through Z, and the uppercase letters A through Z are less than the lowercase
letters a through z. A character string comparison terminates either (1) when all the
characters have been compared, in which case the strings are equal, or (2) when the
first mismatch occurs. For the following examples, assume that LAST_NAME has
the value WHITFIELD.
•

Equal to—The operator .EQS. compares one character string to another for
equality. The following example indicates that the value of the symbol
LAST_NAME does not equal the literal NORMAN.
$ TEST_NAME = LAST.NAME .EQS. "NORMAN"
$ SHOW SYMBOL TEST.NAME
TEST.NAME =0
Hex = 00000000 Octal = 000000

•

Greater than or equal to—The operator .GES. compares one character string to
another for a greater or equal value in the first specified string. The following
example indicates that the value of the symbol LAST—NAME is greater than or
equal to the literal NORMAN.
$ TEST_NAME = LAST.NAME .GES. "NORMAN"
$ SHOW SYMBOL TEST_NAME
TEST.NAME =1
Hex = 00000001
Octal = 000001

•

Greater than—The operator .GTS. compares one character string to another for
a greater value in the first specified string. The following example indicates that
the value of the symbol LAST—NAME is greater than the literal NORMAN.
$ TEST_NAME = LAST.NAME .GTS. "NORMAN"
$ SHOW SYMBOL TEST.NAME
TEST.NAME =1
Hex = 00000001
Octal = 000001

Data Representation

•

5-9

Less than or equal to—The operator .LES. compares one character string to
another for a lesser or equal value in the first specified string. The following
example indicates that the value of the symbol LAST_NAME is not less than or
equal to the literal NORMAN.
$ TEST.NAME = LAST_NAME

.LES.

"NORMAN”

$ SHOW SYMBOL TEST.NAME
TEST.NAME = 0

•

Hex = 00000000

Octal = 000000

Less than—The operator .LTS. compares one character string to another for a
lesser value in the first specified string. The following example indicates that the
value of the symbol LAST_NAME is not less than the literal NORMAN.
$ TEST.NAME = LAST.NAME

.LTS.

"NORMAN"

$ SHOW SYMBOL TEST.NAME
TEST.NAME =0

•

Hex = 00000000

Octal = 000000

Not equal—The operator .NES. compares one character string to another for
inequality. The following example indicates that the value of the symbol
LAST_NAME does not equal the literal NORMAN.
$ TEST.NAME = LAST.NAME

.NES.

"NORMAN"

$ SHOW SYMBOL TEST.NAME
TEST.NAME = 1
Hex = 00000001

Octal = 000001

5.2.2 Numeric Expressions
In a numeric expression, the data entities must be literal numbers or symbols equated
to numbers. In addition, you can use a character string that represents a number (for
example, "23" or "-51"). Attempting an operation or comparison between a number
and a character string causes the character string to be converted to a number.
You can specify the following numeric operations:
•

Multiplication—The asterisk multiplies two numbers.
$ BALANCE = 142 *

$ SHOW SYMBOL BALANCE
BALANCE = 1988
Hex = 000007C4

•

Octal = 003704

Division—The slash divides the first specified number by the second specified
number.
$ BALANCE = BALANCE /

$ SHOW SYMBOL BALANCE
BALANCE = 142

Hex = 0000008E

Octal = 000216

If a number does not divide evenly, the remainder is lost. (No rounding takes
place.)

•

Addition—The plus sign adds two numbers.
$ BALANCE = BALANCE + 37
$ SHOW SYMBOL BALANCE
BALANCE = 179
Hex = 000000B3

•

Octal = 000263

Subtraction—The minus sign subtracts the second specified number from the first
specified number.
$ BALANCE = BALANCE - 15416
$ SHOW SYMBOL BALANCE
BALANCE = -15237
Hex = FFFFC47B

•

Octal = 142173

Unary plus and minus—The plus and minus signs change the sign of the number
they precede.
$ BALANCE = -(-142)
$ SHOW SYMBOL BALANCE

BALANCE = 142

Hex = 0000008E

Octal = 000216

You can specify the following numeric comparisons:
•

Equal to—The operator .EQ. compares one number to another for equality. The
following example indicates that BALANCE equals -15237.
$ TESTJBALANCE = BALANCE .EQ. -15237
$ SHOW SYMBOL TEST_BALANCE
TEST.BALANCE =1
Hex = 00000001
Octal = 000001

•

Greater than or equal to—The operator .GE. compares one number to another
for a greater or equal value in the first number. The following example indicates
that BALANCE is greater than or equal to -15237.
$ TEST.BALANCE = BALANCE .GE. -15237
$ SHOW SYMBOL TEST.BALANCE
TEST.BALANCE =1
Hex = 00000001
Octal = 000001

•

Greater than—The operator .GT. compares one number to another for a greater
value in the first number. The following example indicates that BALANCE is not
greater than -15237.
$ TEST.BALANCE = BALANCE .GT. -15237
$ SHOW SYMBOL TEST.BALANCE
TEST.BALANCE =0
Hex = 00000000 Octal = 000000

•

Less than or equal to—The operator .LE. compares one number to another for a
lesser or equal value in the first number. The following example indicates that
BALANCE is less than or equal to -15237.
$ TEST.BALANCE = BALANCE .LE. -15237
$ SHOW SYMBOL TEST.BALANCE
TEST.BALANCE =1
Hex = 00000001
Octal = 000001

Data Representation

•

5-11

Less than—The operator .LT. compares one number to another for a lesser value
in the first number. The following example indicates that BALANCE is not less
than -15237.
$ TEST_BALANCE = BALANCE .LT. -15237
$ SHOW SYMBOL TEST_BALANCE
TEST.BALANCE =0
Hex = 00000000 Octal = 000000

•

Not equal to—The operator .NE. compares one number to another for inequality.
The following example indicates that BALANCE equals -15237.
$ TEST.BALANCE = BALANCE .NE. -15237
$ SHOW SYMBOL TEST.BALANCE
TEST.BALANCE =0
Hex = 00000000 Octal = 000000

5.2.3 Logical Expressions
A logical operation affects all the bits in the number being acted upon. (If the
logical data item is a character string beginning with T, t, Y, or y, it is treated as the
number 1. If the logical data item is a character string beginning with any character
other than T, t, Y, or y, it is treated as the number 0.) Typically, however, you are
interested only in the value of the low-order bit, that is, whether the entity has a
logical value of true or false. You can specify the following logical operations:
•

Not—The operator .NOT. reverses the bit configuration of a logical value. A
true value becomes false and a false value becomes true. The following example
reverses a true value.
$ SHOW SYMBOL STATUS
STATUS =1
Hex = 00000001
Octal = 000001
$ STATUS = .NOT. STATUS
$ SHOW SYMBOL STATUS
STATUS = -2
Hex = FFFFFFFE Octal = 177776
The value -2 is even, that is, false.

•

And—The operator .AND. combines two logical values as follows:

Bit Level

Entity Level

1 .AND. 1 = 1

true .AND. true = true

1 .AND. 0 = 0

true .AND. false = false

0 .AND. 1 = 0

false .AND. true = false

0 .AND. 0 = 0

false .AND. false = false

5-12

Data Representation

The following example combines a true value and a false value to produce a false
value.
$
$
$
$

•

STAT1 = "TRUE1'
STAT2 = "FALSE"
STATUS = STAT1 .AND. STAT2
SHOW SYMBOL STATUS
STATUS =0
Hex = 00000000

Octal = 000000

Or—The operator .OR. combines two logical values as follows:
Bit Level

Entity Level

1 .OR. 1 = 1

true .OR. true = true

1 .OR. 0 = 1

true .OR. false = true

0 .OR. 1 = 1

false .OR. true = true

0 .OR. 0 = 0

false .OR. false = false

The following example combines a true value and a false value to produce a true
value.
$
$
$
$

STAT1 = "TRUE"
STAT2 = "FALSE"
STATUS = STAT1 .OR. STAT2
SHOW SYMBOL STATUS
STATUS =1
Hex = 00000001

Octal = 000001

5.2.4 Combined Operations and Precedence
An expression can contain any number of operations and comparisons. You can
indicate precedence by placing operations to be performed first in parentheses.
(Parentheses can be nested.) Otherwise, operations within an expression are
evaluated in the following order:
1.

Unary plus ( + ) and minus (-)

Multiplication and division

All other numeric and character operations

All numeric and character comparisons

Logical NOT operations

Logical AND operations

Logical OR operations

Data Representation

5-13

Operations and comparisons that have the same precedence are evaluated from left
to right. The following examples illustrate precedence of operations in expressions.

Example 1:
$ BALANCE = 150 + 20 * 4
BALANCE = 150 + 80
$ SHOW SYMBOL BALANCE
BALANCE = 230
Hex = 000000E6

Octal = 000346

Example 2:
$ BALANCE = (150 + 20) * 4
(BALANCE = 170 * 4)
$ SHOW SYMBOL BALANCE
BALANCE = 680 Hex = 000002A8

Octal = 001250

Example 3:
$ STATUS = 150 * 4 .GT. 80 * 2
STATUS = 600 .GT. 160
$ SHOW SYMBOL STATUS
STATUS =1
Hex = 00000001 Octal = 000001

5.3 Lexical Functions
A lexical function performs operations on system and user data items, and substitutes
the result of the operation for itself. Appendix LEX describes each lexical function
and lists them by function.
You invoke a lexical function by typing its name (which always begins with F$) and
a parameter list in place of a character string or number. Use the following format:

F$function (parameter,...)
The parameter list follows the function name with none or any number of
intervening spaces and tabs. The list must be enclosed in parentheses. Within
the list, specify parameters in exact order and separate them with commas; even
if you omit an optional parameter, do not omit the comma. If no parameters are
required, type an empty set of parentheses.
The F$LOCATE function, for example, requires two character strings as parameters
and returns (that is, substitutes for itself) a number that is the starting offset of the
first character string (the substring) within the second. In the following example,
F$LOCATE is equivalent to the number 4.

F$LOCATE (“string”,“fullstring”)

5-14

Data Representation

You can use a lexical function in any position that you can use a symbol. In positions
where symbol substitution must be forced by enclosing the symbol in apostrophes,
lexical function evaluation must be forced by placing the lexical function within
apostrophes. Lexical functions can also be used as parameter values in other lexical
functions. Consider the following examples:
$ L = FSLENGTH (LINE)
Equates the length of the character symbol LINE to a numeric symbol named L.
$ LINE = F$EXTRACT (0,F$LENGTH(LINE)-2,LINE)
Strips the last two characters from the character string that is the value of the symbol
LINE.

5.4 Date and Time
You specify time in absolute or delta format or in a combination of both formats.
Absolute format provides an exact time. Delta format provides an offset from the
current date and time. An absolute and delta time combination provides an exact
time plus or minus an offset from the current date and time.

5.4.1 Absolute Time
The general format for an absolute time is as follows:

dd-mmm-yyyy:hh:mm:ss.cc
where:
dd

day of the month; an integer in the range 1-31

mmm

month; JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, or DEC

yyyy

year; an integer

hour; an integer in the range 0-23

minute; an integer in the range 0-59

seconds; an integer in the range 0-59

hundredths of a second; an integer in the range 0-99

You can truncate the date or the time on the right. However, if you are specifying
both date and time, you must include the colon between the date and time, and
the date must contain at least one hyphen. You can omit fields if you supply the
punctuation. Truncated or omitted date fields default to the corresponding fields for
the current date. Truncated or omitted time fields default to 0.
You can also specify an absolute time as TODAY (00:00:00.00 today), TOMORROW
(00:00:00.00 tomorrow), or YESTERDAY (00:00:00.00 yesterday).

Data Representation

5-15

If you specify a past time in a command that expects the current or a future time, the
current time is used.

Specification

Time

15-MAY-1986:13

1 P.M. on May 15, 1986

15-MAY

0 A.M. on May 15 this year

15:30

3:30 P.M. today

15-

0 A.M. on the 15th of this month

15-::30

0:30 A.M. on the 15th of this month

5.4.2 Delta Time
The general format of a delta time is as follows:

dddd-hh:mm:ss.cc
where:
dddd

number of days; an integer in the range 0-9999

number of hours; an integer in the range 0-23

number of minutes; an integer in the range 0-59

number of seconds; an integer in the range 0-59

number of hundredths of seconds; an integer in the range 0—99

You can truncate a delta time on the right. You can omit fields as long as you include
the punctuation. Truncated or omitted fields default to 0.

Specification

Time

3 days from now

3 hours from now

:30

30 minutes from now

3-:30

3 days and 30 minutes from now

15:30

15 hours and 30 minutes from now

5.4.3 Absolute and Delta Time Combinations
To combine absolute and delta time, specify an absolute time plus ( + ) or minus (-)
a delta time. The variable fields and default fields for absolute and delta time values
are the same as those described in the preceding sections. The delta time value must
always be preceded by a plus or minus sign. Whenever a plus sign precedes the
delta time value, the entire time specification must be enclosed in quotation marks.

5-16

Data Representation

Specification

Time

"+5"

5 hours from now

"+:5"

5 minutes from now

-:5

current time minus 5 minutes

"TOMORROW+1"

tomorrow plus 1 hour

NOTE:

If a qualifier is described as a value that may be expressed as an absolute
time, a delta time, or a combination of the two, then you must specify a delta time
as if it were part of a combination time. For example, to specify a delta time value of
five minutes from the current time, use "+:5" (not "0-0:5").

5.5 Symbols
A symbol is a name that represents a numeric, character, or logical value. The
symbol name is 1 through 255 characters long and must begin with a letter,
an underscore (_), or a dollar sign ($). In a symbol name, both lowercase and
uppercase letters are treated as uppercase.
A symbol can be either of the following:
•

Local—A local symbol can be accessed from the command level that defines it or
from lower command levels.

•

Global—A global symbol can be accessed from any command level regardless of
the level at which it was defined.

Local symbols take precedence over global symbols of the same name. Symbols
take precedence over identical command names. If you define a symbol with the
same name as a DCL command, your definition overrides the command name. For
example, if you define HELP as the command TYPE HELP.LST you cannot use the
system's HELP command by typing HELP.
The SHOW SYMBOL command displays symbol values. Specify the name of the
symbol to display the value of a particular local symbol. Specify the name of the
symbol and /GLOBAL to display the value of a particular global symbol. Specify
/ALL to display all local symbols, and /ALL /GLOBAL to display all global symbols.

Data Representation

5-17

5.5.1 Creation and Deletion
Symbols are created when assigned a value in the following format:

symbol-name =[=] value
To create a local symbol, use a single equal sign in the assignment statement; to
create a global symbol, use two equal signs. The following commands define the
local symbol FILE as the character string ACCOUNTS:[BOLIVAR]PRICES.84 and the
global symbol MAX—VALUE as the number 24.
$ FILE = "ACCOUNTS:[BOLIVAR]PRICES.84"
$ MAX.VALUE == 24
You can omit the quotation marks around character strings in assignment statements
if you precede the equal sign(s) with a colon. Note that symbol assignments that
omit quotation marks automatically change the character string to uppercase letters
and compress multiple spaces and/or tabs to a single space. The following example
creates the same local symbol FILE that the preceding example creates.
$ FILE := ACCOUNTS:[BOLIVAR]PRICES.84
You can equate symbols to character strings (A="ar"), integers (VAR=26), symbols
(C=A), lexical functions (I = F$LOCATE(//substring", "fullstring") ), or a combination
of these entities.
The result of DCL's evaluation of a symbol is either a character string or an integer
value. The data type (character or integer) of a symbol is determined by the data
type of the value currently assigned. The type is not permanent: if the value changes
type, as in the following example, the symbol changes type. In this example, the
local symbol NUM is first assigned a character value and then converted to an
integer value when used in an expression with an integer.
$ NUM = "12"
$ RESULT = NUM + 12
The DELETE/SYMBOL command deletes a symbol. You must include the /GLOBAL
qualifier to delete a global symbol. In the following example, the global symbol
TEMP is deleted.
$ DELETE/SYMBOL/GLOBAL

TEMP

5-18

Data Representation

5.5.2 Symbol Access Control
The SET SYMBOL/SCOPE=(keyword,...) command controls access to local and
global symbols in command procedures. This allows you to treat symbols as being
undefined without deleting them. Symbol scoping works differently for local and
global symbols.
If you specify /SCOPE=NOLOCAL, all local symbols defined in an outer procedure
level are treated as being undefined by the current procedure and any inner levels.
Specifying LOCAL removes any symbol translation limit set by the current procedure
level.
For example, if SET SYMBOL/SCOPE=NOLOCAL was specified at procedure levels
2 and 4, procedure level 2 can access only procedure level 2 local symbols. Procedure
level 3 can access procedure levels 2 and 3 local symbols and procedure level 4 can
access procedure level 4 local symbols and any local symbols in inner procedure
levels.
Global symbols are not procedure level dependent. The global symbol scoping
state (GLOBAL or NOGLOBAL) that is in effect when a new procedure level is
invoked is propagated to the new procedure level. Specifying /SCOPE=NOGLOBAL
makes all global symbols inaccessible for all subsequent commands until you either
specify /SCOPE=GLOBAL or exit to a previous level at which global symbols were
accessible.
In the following example, the SET SYMBOL command denies access to all global
symbols.
$ SET SYMBOL/SCOPE=NOGLOBAL
Exiting a procedure level back to an outer procedure level causes the symbol scoping
state to be restored for both local and global symbols.

5.5.3 Symbol Substitution
When a command line is executed, symbols in the following positions are
automatically substituted.
•

On the right side of an = or == assignment statement

•

In a lexical function

•

In the brackets on the left side of an assignment statement when you are
performing substring substitution (see Section 5.5.4).

•

In a DEPOSIT, EXAMINE, IF, or WRITE command

•

At the beginning of the command line

Data Representation

5-19

To force substitution of a symbol that is not in one of the positions listed, enclose the
symbol with apostrophes. For example:
$ TYPE ’B’
To force substitution of a symbol within a quoted character string, enclose that
symbol in double apostrophes, as follows:
$ T = "TYPE ’’B’*"
When processing a command line, DCL replaces symbols with their values in the
following order:
•

Forced substitution—From left to right, DCL replaces all strings delimited by
apostrophes (or double apostrophes for strings within quotation marks). Symbols
preceded by single apostrophes are translated iteratively; symbols preceded by
double apostrophes are not.

•

Automatic substitution—From left to right, DCL evaluates each value in the
command line, executing it if it is a command and evaluating it if it is an
expression. Symbols in expressions are replaced by their assigned values; this
substitution is not iterative.

The following example demonstrates the effect of the order in which DCL substitutes
symbols. Assume the following symbol definitions:
$ SUBN = "SUBMIT/NOTIFY/NOPRINT"
$ FILE1 = "[BOLIVAR]ACCOUNTING.COM"
$ NUM = 1
Given these symbol definitions, the following commands submit the command
procedure named [BOLIVARjACCOUNTING.COM.
$ FILE = "’FILE’*NUM * *"
$ SUBN ’FILE’
In the first command, forced substitution causes NUM to become 1, making
FILE'NUM' become FILE1. Then automatic substitution causes FILE1 to become
[BOLIVAR]ACCOUNTING.COM. In the second command, forced substitution causes
'FILE' to become [BOLIVAR]ACCOUNTING.COM, and then automatic substitution
causes SUBN to become SUBMIT/NOTIFY/NOPRINT.

5-20

Data Representation

5.5.4 Substring Substitution
The following variations of the assignment statement allow you to manipulate
character symbols on a character-by-character basis and numeric symbols on a
bit-by-bit basis.
•

Character—Specify a character symbol on a character-by-character basis as
follows. The assignment statement must use := in place of = to force equation of
a character string to a substring.

symbol[offset,length] := value
Offset specifies the starting character within the symbol. An offset of 0 means the
first character in the symbol, an offset of 1 means the second character, and so
on. Length specifies the number of characters to change. The following example
changes the string "THIS IS A STRING" to "THERE'S A STRING".
$ STR1 = "THIS IS A STRING"
$ STR1[0,6] := "THERE*"
If the specified length is greater than the number of characters in the value, the
value is padded on the right with blanks. The following command defines the
symbol LINE as a character string of 80 blanks.
$ LINE[0,80]
•

:= " "

Number—Specify a number symbol on a bit-by-bit basis as follows:

symbol[offset,length] = value
Offset specifies the starting bit within the number, where 0 means the low-order
bit, 1 means the second bit, and so on. Length specifies the number of bits to
change. The maximum for both length and offset is 32 bits. (If you have not
predefined the symbol that you are planning to set bits in, DCL assumes that the
value of that symbol is 0.) The following example defines the symbol BELL as
the value 7 (7 is the ASCII value of CTRL/G, which rings the terminal's bell).
BELL[0,8] = 7

! the binary value of 7 is 111

The low-order byte of BELL has the binary value 00000111. By changing the 0 at
offset 5 of BELL (beginning with 0, count bits from right to left) to 1, you create
the binary value 00100111 (hexadecimal 27, the ASCII value for an apostrophe).
BELL[5,1] = 1

! the binary value of 1 is 1

Data Representation

5-21

5.5.5 Use of Symbols
Although you can use symbols as a mnemonic device (for example, equate a phone
number to a name: HELEN = 617-754-8076), usually you use symbols as shorthand.
You define a symbol as a literal and then type the symbol name rather than the
literal. For example, you may define a symbol as any of the following:
•

Foreign command—Defining a symbol as a foreign command allows you to
execute the named image by entering only the symbol name. In the following
example, the symbol FIX is defined to execute the image NUMFIX.EXE in the
[BILLS] directory on the disk ACCOUNTS.
$ FIX == "{ACCOUNTS:[BILLS]NUMFIX"

•

Command line—Defining a symbol as a command line allows you to execute
the command by entering only the symbol name. In the following example, the
symbol EBONY is defined to establish a network connection to the node EBONY.
$ EBONY == "SET HOST EBONY"
Setting a symbol equal to a command line that executes a command procedure
allows you to execute the procedure by typing only the symbol name. In the
following example, COUNT is defined to execute the command procedure
CENSUS.
$ COUNT == "©CENSUS"
When you enter COUNT to execute CENSUS, place any parameters for CENSUS
after the symbol as if you had entered @CENSUS.

•

Character string—Defining a symbol as a character string allows you to insert
that string in a command line by typing the symbol (with delimiting apostrophes
to force substitution). In the following example, the symbol FILE is first defined
as a complete file specification and then used in the TYPE command.
$ FILE == "CLERK:[LICENSES.DOG]D0GS81.DAT"
$ TYPE ’FILE’
The string could be a directory you often access. In the following example,
whenever the symbol DOG occurs in a command line, the literal value replaces
the symbol before the line is executed.
$ DOG == "[LICENSES.DOG]"
$ COPY ’DOG’D0GS83.DAT D0GS83.TMP

Symbols can also hold variables: values that you calculate, or that you assign as
something other than a literal. For example, you might assign the value of a lexical
function to a variable or read the value of a file record into a variable. As variables,
symbols are most often used in command procedures (see Chapter 6). Note that the
symbols you create are deleted when you log out.

Chapter 6
Command Procedures
Command procedures are files containing DCL commands that are executed when
the procedure is invoked. A command procedure can be:
•

Simple—The procedure executes a series of DCL commands exactly as they are
written. The following example sets your default directory and examines it.
$
$
$
$
$

•

! PROCEDURES.COM
!
! Enter [MAINT.PROCEDURES] and examine it
SET DEFAULT [MAINT.PROCEDURES]
DIRECTORY

Complex—The procedure performs programlike functions. The following
example asks for directory names and examines the directories.
$ ! DIRECTORY.COM
$ !
$ ! Examine directories
$START:
$ INQUIRE DIR.NAME "Directory name"
$ IF DIR.NAME . EQS. "" THEN GOTO END
$ DIRECTORY ’DIR_NAME’
$ GOTO START
$END:

6-2

Command Procedures

6.1

Format

Begin each command line with a dollar sign. Omit the dollar sign for data lines. The
following format conventions are recommended:
•

Use comments—Comments explain the procedure to anyone who must maintain
it; they are ignored during execution of the command procedure. Use comments
at the beginning of a procedure to describe the procedure and the parameters
passed to it; use them at the beginning of each block of commands to describe
that section of the procedure. Comments must begin with an exclamation point;
the comment is the text to the right of the exclamation point. (To include a
literal exclamation point in a command line, precede and follow it with quotation
marks.)

•

Do not abbreviate—Commands and qualifiers are usually self-explanatory if they
are spelled out. Also, when new commands are added with a release of the
VAX/VMS operating system, abbreviated commands may no longer be unique
and thus command procedures using them might require changes.

•

Put labels on separate lines—Using separate lines for labels makes loops and
conditional coding easier to understand. Placing labels immediately after the
dollar sign (in contrast to commands, which are placed after a blank space
following the dollar sign) makes them easier to find. A label can have up to 255
characters, cannot contain embedded blanks, and must be terminated by a colon.

•

Separate command sequences—Insert lines containing a dollar sign and an
exclamation mark before and after a logical sequence of commands. This makes
it easier to see the outline of the command procedure. (If you insert blank lines,
DCL reads them as data lines and produces a message warning you that the data
lines were ignored.)

6.2 Execution
To execute command procedures, type an at sign (@) followed by the file
specification of the procedure. The file type defaults to COM. Procedures can
be executed at the DCL level or from within another command procedure.
The following command executes the procedure SETD.COM in the directory
[MAINT.PROCEDURES] on the disk WORKDISK.
$ (3W0RKDISK: [MAI NT. PROCEDURES] SETD
To simplify the invocation of a procedure, create either a symbol or logical name.
Equating the command line to a symbol allows you to invoke the command
procedure from any directory by entering the symbol name.
$ SETD = "QWORKDISK:[MAINT.PROCEDURES]SETD"
$ SETD

Command Procedures

6-3

Equating the file specification to a logical name allows you to invoke the command
procedure from any directory by entering an at sign followed by the logical name.
$ DEFINE SETD WORKDISK:[MAINT.PROCEDURES]SETD.COM.
$ OSETD

6.2.1 Nesting Command Levels
Command procedures can contain other nested command procedures. When a
command procedure is invoked, the command level increases by 1. For instance,
if you invoke procedure SUB from DCL command level (level 0), SUB executes at
command level 1. If SUB then calls SUB1, which calls SUBSUB 1, SUB1 executes at
command level 2 and SUBSUB 1 at command level 3. Command levels are limited to
32.
By convention, DCL is called the highest command level and command level 32 the
lowest command level. Hence, if you move from command level 3 to command level
2, you are said to be moving to the next higher command level.

6.2.2 Exiting from Command Procedures
A command procedure exits when it reaches the end of the procedure, an EXIT
command, or a STOP command. If the exit is caused by the end of the procedure or
an EXIT command, control returns to the next higher command level. For instance, if
you invoke SUB at DCL command level, and SUB calls SUB1:
•

Exiting from SUB1 returns you to SUB at the command line following the call to
SUB1.

•

Exiting from SUB returns you to DCL command level.

If the exit is caused by the STOP command, control returns to DCL command
level. If the exit is caused by the EXIT command, you can return a status value
to the next higher command level by specifying the value as the parameter of the
EXIT command. This status value is placed in the global symbol $STATUS (see
Section 1.9).

6-4

Command Procedures

6.3 Passing Data
Command procedures frequently require data provided by a user. To specify the
same data each time the command procedure is executed, place the data on data
lines following the command that requires the data. (A data line is a line that does
not begin with a dollar sign. To include a data line that begins with a dollar sign,
use the DECK and EOD commands.) The following command procedure executes
the image CENSUS.EXE, which reads 1981, 1982, and 1983 each time the procedure
is executed.
$ RUN CENSUS
1981
1982
1983
The text on a data line is passed directly to the image; it is not processed by DCL.
Therefore, you should not include symbols or arithmetic expressions on data lines.
Since logical names are not translated by DCL, a logical name included on a data
line is properly processed.
To specify different data each time a command procedure is executed, use one of the
following mechanisms:
•

Pass the data as one or more parameter values.

•

Use the INQUIRE or READ command within the command procedure to read
the data.

•

Specify a device or file from which to read the data by redefining the logical
name SYS$INPUT.

6.3.1 Using Parameters To Pass Data
When you invoke a command procedure, you can pass it up to eight parameters
by placing the values of the parameters after the file specification of the command
procedure. Separate the parameters with one or more spaces and/or tabs. Specify a
parameter value as one of the following:
•

Number—To pass a number, specify the number. A number must be an integer
and is passed as a literal. In the following example, the values "24" and "25" are
passed to ADDER.COM.
$ 0ADDER 24 25

•

Literal—To pass a literal, specify the literal. In the following example, the values
"Paul" and "Cramer" are passed to DATA.COM.
$ ©DATA Paul Cramer

Command Procedures

6-5

To preserve spaces, tabs, or lowercase characters, you must place quotation
marks before and after the literal. In the following example, the single value
"Paul Cramer" is passed to DATA.COM.
$ ODATA "Paul Cramer"
•

Symbol—To pass the value of a symbol, place quotation marks before and after
the symbol. In the following example, the values "Paul" and "Cramer" are passed
to DATA.COM.
$ NAME = "Paul Cramer"
$ ©DATA ’NAME’
Note that in passing a symbol, DCL removes quotation marks that enclose a
literal. To preserve spaces, tabs, and lowercase characters in a symbol value, you
must enter the enclosing quotation marks as part of the symbol value. To include
a quotation mark as part of a literal value, enter three quotation marks. In the
following example, the single value "Paul Cramer" is passed to DATA.COM.
$ NEW_NAME = """Paul Cramer"""
$ ODATA ’NEW.NAME’

•

Null string—To pass a null parameter, use a set of quotation marks as a place
holder in the command string. In the following example, the first parameter
passed to DATA.COM is a null parameter.
$ ODATA """Paul Cramer"

Parameters are treated as literals and placed in the local symbols PI through P8; PI
is assigned the first parameter value; P2 the second; P3 the third, and so on. If you
pass more than eight values, you receive the error message "too many command
procedure parameters - limit to eight" and the procedure is not executed; if you pass
fewer than eight values, the extra symbols are assigned null values.
For example, when DATA.COM is invoked with the command:
$ ODATA

"Paul Cramer" 24 "(603) 423—8769"

PI through P8 are defined in DATA.COM as
PI = Paul Cramer
P2 = 24
P3 = (603) 423-8769
P4-P8 = Null
When you enter a nested procedure, the local symbols PI through P8 are assigned
the parameters passed by the invoking procedure. The local symbols PI through P8
in the nested procedure are not related to the local symbols PI through P8 in the
invoking procedure. In the following example, DATA.COM invokes NAME.COM
with the command.
$ ! DATA.COM
$ ONAME ’PI*

6-6

Command Procedures

In NAME.COM, PI through P8 are defined as follows:
PI= Paul
P2 = Cramer
P3-P8 = Null
Because DCL removes quotation marks when passing a symbol, to preserve spaces,
tabs, and lowercase characters in a symbol value, you must enclose the value in
three sets of quotation marks. In the following example, the literal value in PI
is enclosed in three sets of quotation marks and passed to NAME.COM. If PI
originally contained the value "Paul Cramer", the value "Paul Cramer" is passed to
NAME.COM.
$
$
$
$

! DATA.COM
QUOTE = ,,,,,,
PI = QUOTE + PI + QUOTE
ONAME ’PI’

An alternative is to enclose the text in quotation marks and, where a symbol appears,
precede it with two apostrophes, and follow it with one apostrophe.
$ ! DATA.COM
$ ONAME "”P1’U

6.3.2 The INQUIRE Command
The INQUIRE command prompts for a value, reads the value from the terminal,
and assigns it to a symbol. All characters typed at the terminal in response to the
prompt are taken as a character string value. By default the response is converted to
uppercase, multiple blanks and tabs are replaced by a single space, and leading and
trailing spaces are removed. To preserve lowercase characters, multiple spaces, and
tabs, enclose your response in quotation marks. The following command procedure
writes the prompt Filename: and puts the response into the local symbol FILE.
$ INQUIRE FILE "Filename"
To suppress the colon and space automatically added to the end of the prompt, use
the /NOPUNCTUATION qualifier. To make the symbol global instead of local, use
the /GLOBAL qualifier. The following command procedure writes the prompt Do
you want to use defaults? and puts the response into the global symbol DEFAULT.
$ INQUIRE/NOPUNCTUATION/GLOBAL DEFAULT"Do you want to use defaults?"
When a command procedure is submitted as a batch job, the value for a symbol
specified in an INQUIRE command is read from the data line following the INQUIRE
command. If you do not include a data line, the symbol is assigned a null value.

Command Procedures

6-7

6.3.3 The READ Command
The READ command prompts for a value, reads the value from the source specified
by the first parameter, and assigns it to the symbol named as the second parameter.
By default, the READ command uses the prompt DATA:. To specify a different
prompt, use the /PROMPT qualifier. All characters typed on the terminal in response
to the prompt are taken as an exact character string value (case, spaces, and tabs are
preserved). The following command procedure writes the prompt Filename:, reads
the response from the source specified by the logical name SYS$COMMAND (by
default, the terminal), and assigns the response to the symbol FILE.
$ READ/PROMPT="Filename:" SYS$COMMAND FILE

6.3.4 Obtaining Data from SYS$INPUT
Commands, utilities, and other system images normally take their input from the
source specified by the logical name SYS$INPUT. You can specify SYS$INPUT as
any one of the following:
•

Data line—In a command procedure, SYS$INPUT by default is equated to the
data lines of the procedure. In the following command procedure, the image
CENSUS.EXE uses the default value of SYS$INPUT to take input (1981, 1982,
and 1983) from the data lines.
$ ! CENSUS.COM
$ !
$ ! Execute CENSUS
$ RUN CENSUS
1981
1982
1983

•

Terminal—A command procedure can get input from a terminal by defining
SYS$INPUT as the terminal. This allows you to perform interactive tasks from a
command procedure. The following command procedure defines SYS$INPUT as
the terminal, then invokes EDIT. The editing session that follows the call to EDIT
is interactive. (The /USER_MODE qualifier redefines SYS$INPUT for a single
image; you should use this qualifier whenever you redefine a process-permanent
logical name.)
$
$
$
$
$
$

! EDIT.COM
!
! Edit the file STATS.DAT
WRITE SYS$0UTPUT "Edit STATS.DAT:"
DEFINE/USER.MODE SYS$INPUT SYS$C0MMAND:
EDIT STATS.DAT

6-8

•

Command Procedures

File—A command procedure can get input from a file by defining SYS$INPUT
as a file. The following command procedure defines SYS$INPUT as the file
YEARS.DAT, then invokes the program CENSUS. CENSUS reads its input from
the file YEARS.DAT. (The /USER_MODE qualifier redefines SYS$INPUT for
a single image; you should use this qualifier whenever you redefine a
process-permanent logical name.)
$
$
$
$
$

! CENSUS.COM
!
! Execute CENSUS
DEFINE/USER_MODE SYS$INPUT YEARS.DAT
RUN CENSUS

6.4 Returning Data
To return a value from a command procedure (either to a calling procedure or to
DCL command level), you must assign the value to a global symbol. The global
symbol can be read at any command level. Use comments to explain the use of any
global symbols.
To create a global symbol, specify the value to be passed on the right side of a
global assignment statement. In the following example, the command procedure
DATA.COM invokes the command procedure NAME.COM, passing NAME.COM a
full name. NAME.COM places the last name in the global symbol LAST_NAME.
When NAME.COM completes, DCL continues executing DATA.COM, which reads
the last name by referencing the global symbol LAST_NAME. (The command
procedure NAME.COM would be in a separate file; it is indented here for clarity.)
$ ODATA "Paul Cramer"
$
$
$
$
$
$
$

!
!
!
!
!

DATA.COM
PI is a full name
NAME.COM returns the last name in the
global symbol LAST.NAME

©NAME ’PI’
$ ! NAME.COM
$ ! PI is a first name
$ ! P2 is a last name
$ ! return P2 in the global symbol LAST_NAME
$ LAST.NAME :== ’P2*
$ EXIT
$ ! write LAST.NAME to the terminal
$ WRITE SYS$OUTPUT "LAST.NAME = * *LAST.NAME *"
LAST.NAME = "CRAMER"

Command Procedures

6-9

6.5 Displaying Data
Commands, utilities, and other system images normally write their output to the
source specified by the logical name SYS$OUTPUT. By default, SYS$OUTPUT
is equated to the terminal. However, you can redirect the output of a command
procedure to a file with the /OUTPUT qualifier. In the following example, output
from the command procedure SETD.COM is written to the file RESULTS.TXT instead
of to the terminal.
$ @SETD/OUTPUT=RESULTS.TXT
Other DCL commands that accept the /OUTPUT qualifier include: ACCOUNTING,
CALL, DIRECTORY, HELP, LIBRARY, RUN (process), SPAWN, and TYPE.

6.5.1 Displaying Literals and Symbols
The WRITE command displays literals and symbols on the terminal:
•

Literal—Enclose the text to be displayed in quotation marks. The following
example displays the text "Two files were written."
$ WRITE SYSSOUTPUT "Two files were written."

•

Symbol value—Enclose the symbol in apostrophes. The following example
displays the text "STAT1.DAT".
$ FILE = "STAT1.DAT"
$ WRITE SYSSOUTPUT ’FILE*

•

Combination of literals and symbol values—Enclose the text to be displayed
in quotation marks. Preface a symbol with two apostrophes and follow it with
one apostrophe. The following example displays the text "STAT1.DAT and
STAT2.DAT were written."
$ AFILE = "STAT1.DAT"
$ BFILE = "STAT2.DAT"
$ WRITE SYSSOUTPUT "”AFILE> and *’BFILE* were written."

6-10

Command Procedures

6.5.2 Displaying Text
To display text that is more than one line long, use the TYPE command. TYPE
writes data to SYS$OUTPUT (the terminal, by default). Using SYS$INPUT as the
parameter causes TYPE to read the data from the command procedure. When the
following command procedure is executed, the text on the data lines is displayed on
the terminal.
$
$
$
$

! CLEAN.COM
!
TYPE SYS$INPUT
INQUIRE COMMAND'•Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY)"

6.5.3 Displaying Files
To display a file, use the TYPE command. The following example displays the file
STAT1.DAT on the terminal.
$ TYPE STAT1.DAT

6.6

Inputting and Outputting Data from Files (File I/O)

To move data to and from files, use the OPEN, CLOSE, READ, and WRITE
commands. The logical name you specify in the OPEN command is used to refer to
the file in the WRITE, READ, and CLOSE commands.

6.6.1 Writing to a File
To write data to a file, take the following steps:
1.

Open the file—The OPEN command opens a file and associates the file name
with a logical name.
Use the /APPEND qualifier of the OPEN command to write data to the end of
an existing file. If you use the /APPEND qualifier to open a nonexistent file, an
error occurs.
Use the /WRITE qualifier of the OPEN command to create a new file. If you use
the /WRITE qualifier to open an existing file, a new version of that file is created.
Both the /APPEND and the /WRITE qualifiers cause DCL to open the file for
write access.

Command Procedures

6-11

Begin the write loop—File I/O is done in a loop unless you are writing or
reading a single record.

Read the data to be written—Use the INQUIRE command or the READ
command to read data into a symbol.

Test the data—Check the symbol containing the data. If the symbol is null
(the user pressed RETURN without any data on the line), you have reached the
end of the data to be written to the file and should go to the end of the loop.
Otherwise, continue.

Write the data to the file—Use the WRITE command to write the value of the
symbol (one record) to the file.

Return to the beginning of the loop—You remain in the loop until there is no
more data to be written to the file.

End the loop and close the file—The CLOSE command disassociates the file
name from the logical name and closes the file. (Files opened by the OPEN
command remain open until you log out unless you explicitly close them.)

The following command procedure writes data to the new file STAT.DAT. If a file of
that name exists, a new version is created.
$ ! Write a file
$ OPEN/WRITE IN.FILE STAT.DAT
$ ON CONTROL.Y GOTO END.WRITE
$
$WRITE:
$ INQUIRE STUFF "Input data"
$ IF STUFF .EQS. "" THEN GOTO END.WRITE
$ WRITE IN.FILE STUFF
$ GOTO WRITE
SEND.WRITE:
$
$ CLOSE IN.FILE

!0pen the file
!Close the file if you abort
! execution with a CTRL/Y
!Begin loop
!Get input
•Test for end of file
IWrite to the file
!Goto beginning
!End loop
IClose the file

NOTE:

The logical name in the OPEN command must be unique. If the OPEN
command does not work and your commands seem correct, change the logical name
in the OPEN command. The SHOW LOGICAL command displays logical name
definitions.
If you want to create a file with a unique name, use the F$SEARCH lexical function
(see Appendix LEX) to see whether the name is already in the directory. The
following command procedure prompts the user for a file name, then uses the
F$SEARCH lexical function to search the default directory for the name. If a file with
that name already exists, control is passed to ERROR—l, the procedure prints the
message "File already exists," and control returns to GET_NAME where the user is
again prompted for a file name.

6-12

Command Procedures

$ ! FILES.COM
$ !
$GET_NAME:
$ ! Get a file name
$ INQUIRE FILE "File"
$ ! Make sure the name is unique
$ CHECK = F$SEARCH (FILE)
$ IF CHECK .NES. "" THEN GOTO ERROR. 1
$ ! Open and write to the file
$ OPEN/WRITE IN.FILE ’FILE’

$ EXIT
$ERR0R_1:
$ WRITE SYS$OUTPUT "File already exists"
$ GOTO GET.NAME

6.6.2 Reading from a File
To read data from a file, take the following steps:
1.

Open the file—The OPEN/READ command opens the file for read access and
associates the file name with a logical name.

Begin the read loop—File I/O is done in a loop unless you are reading or writing
a single record.

Read the data from the file—Use the READ command with the /END_OF_FILE
qualifier to read the next record in the file to a symbol. The /END_OF_FILE
qualifier causes the VAX/VMS system to pass control to the label specified by
the /END_OF_FILE qualifier if you have reached the end of the file. Generally,
you specify the label that marks the end of the read loop.
If you are reading records from the terminal, the READ command automatically
uses DATA: to prompt the user for a record. To specify a different prompt,
use the /PROMPT qualifier of the READ command. The record value consists
of all characters typed on the terminal in response to the prompt. Lowercase
characters, multiple spaces, and tabs are preserved. Press CTRL/Z in response to
the READ prompt to indicate the end of a file.

Process the data—Since you must read a file sequentially, process the current
record before reading the next one.

Command Procedures

6-13

Return to the beginning of the loop—You remain in the loop until you reach the
end of the file.

End the loop and close the file—The CLOSE command disassociates the file
name from the logical name and closes the file.

The following command procedure reads and processes each record from STAT.DAT.
$ OPEN/READ 0UT_F STAT.DAT

!Open the file

$
$READ_DATA:
$ READ/END_OF_FILE=END_READ OUT_F STUFF

!Begin the loop
!Read a record and test for end of file
!

$ GOTO READ_DATA
$END_READ:

Process the data

!Go to the beginning of the loop
!End of loop

$
$ CLOSE 0UT_F

!Close the file

6.6.3 Modifying a File
You can modify a file in one of two ways:
•

Rewrite records—This method allows you to make minor adjustments to one or
more records in a file. You cannot change the size of a record or the number of
records in the file.

•

Rewrite the file—This method allows you to change, delete, and insert records.
You create a new file using the old file as the main source of input.

6.6.3.1 Minor Modifications
To make minor changes to the records in a file, take the following steps:
1.

Open the file for both read and write access.

Use the READ command to read through the file until you reach the record that
you want to modify.

Create a symbol containing the modified record. The modified record must be
exactly the same size as the original record. If the text of the modified record is
shorter, pad the record with spaces. If the text of the modified record is longer,
you cannot use this method to modify the file.

Write the record.

Repeat steps 2 through 4 until you have changed all the records to be changed.

Since this method does not allow you to modify the size of the record, use it only if
you have formatted the records in a file (for example, in a data file).

6-14

Command Procedures

The following command procedure reads each record in a data file. The record is
displayed on the terminal, and the user is asked whether the record is to be modified.
If the user chooses to modify the record, a new record is read from the terminal and
its length is compared to the length of the original record. If the original record is
longer, the new record is padded with spaces. If the original record is shorter, an
error message is displayed, and the user is again prompted for a new record. If the
user chooses not to modify the record, the next record is read from the file.
$ ! MODIFY.COM
$ !
$ ! Initialize string of spaces for padding
$ SPACES = "
$
$ ! Open the file
$ OPEN/READ/WRITE FILE STATS.DAT
$
$ ! Begin the loop
$BEGIN_L00P:
$
$ ! Read and display a record
$ READ/END_0F_FILE=END_L00P FILE RECORD
$PR0MPT:
$ WRITE SYS$0UTPUT RECORD
$
$ ! Does the user want to change the record?
$ INQUIRE/NOPUNCTUATION YN "Change? [Y] "
$ ! if not, get next record
$ IF YN .EQS. "N" THEN GOTO BEGIN.L00P
$
$ ! Otherwise, get the new record
$ INQUIRE NEW_REC0RD "New record"

$
$ ! Compare the old and new records
$ 0LD_LEN = F$LENGTH (RECORD)
$ IF OLD.LEN .GE. F$LENGTH(NEW_RECORD) THEN GOTO N0_ERR0R
$ ! New record longer than old record
$ WRITE SYSSOUTPUT "ERROR — New record is too long"
$ GOTO PROMPT
$N0_ERR0R:
$ IF OLD.LEN .EQ. F$LENGTH(NEW_REC0RD) THEN GOTO WRITE_REC0RD
$ ! New record shorter than old record
$ PAD = F$EXTRACT(0,OLD_LEN-F$LENGTH(NEW_RECORD),SPACES)
$ NEW.RECORD = NEW.RECORD + PAD
$

Write the new record

$WRITE_RECORD:
$ WRITE/UPDATE FILE NEW.RECORD
$ GOTO BEGIN.LOOP
$
$END_L00P:
$ CLOSE FILE

6.6.3.2 Major Modifications

To make extensive changes to a file, open that file for read access and open a
file for write access. Since the /WRITE qualifier opens a new file for write acc
the new file can have the same name as the original file—the version number
incremented automatically.
NOTE: You must open the existing file for read access before you open the
version for write access to ensure that the correct file is opened for reading.

As you read each record from the original file, decide how the record is to be t
In the following examples, the symbol RECORD contains the record read from
original file.
•

No change—Write the same symbol to the new file.
$

No change

$ WRITE NEWSFILE RECORD

•

Change—Use the INQUIRE command to read a different record into the s
then write the modified symbol to the new file.
$

Change

$ INQUIRE NEW.RECORD "New record"
$ WRITE NEW.FILE NEW_RECORD

•

Delete—Do not write the symbol to the new file.

•

Insert—Write the symbol to the new file. Then enter a loop that allows yo
read a different record into the symbol and write the symbol to the new fi
$

Insertion

$ WRITE NEW.FILE RECORD
$
$LOOP:
$ !Get new records to insert
$ INQUIRE NEW.RECORD "New record"
$ IF RECORD

.EQS.

"" THEN GOTO END.LOOP

$ WRITE NEW.FILE NEW.RECORD
$ GOTO LOOP
$END.LOOP:

6-16

Command Procedures

6.6.4 Handling I/O Errors
Use the /ERROR qualifier with the OPEN, READ, or WRITE command to suppress
any error message and to pass control to a specified label. This qualifier overrides all
other error-control mechanisms (except the /END_OF_FILE qualifier on the READ
command). In the following command procedure, if an error occurs during execution
of the OPEN command, the message "Error at OPEN" is printed and the procedure
exits.
$ OPEN/READ/ERROR=READ_ERR OUT_F STAT.DAT

$ EXIT
$READ_ERR:
$ WRITE SYS$OUTPUT "Error at OPEN"
$ EXIT

6.7 Using Logic to Control the Flow of Execution
To create a command procedure that performs a consecutive series of DCL
commands, type the commands in their order of execution. If you include a number
of commands, group the commands and include comments explaining each group.
To create a command procedure that requires decision making and/or variable input,
the following guidelines are suggested.

6.7.1 Designing Complicated Command Procedures
Before writing a complicated command procedure, perform the tasks interactively.
As you type the necessary commands, note the following:
•

Variables—Data that changes each time you perform the task.

•

Conditionals—Any command or set of commands that may vary each time you
perform the task. Note the commands and the conditions under which you
would execute it.

•

Iteration—Any command or set of commands that you repeat. Note the
commands and the factor that controls how often you repeat them.

Command Procedures

6-17

The following example shows the commands needed to clean up a directory.

REPEAT
UNTIL
DONE

COMMAND VARIABLE

CONDITION

DIRECTORY
or
TYPE filename
or
PURGE filename
or
DELETE filename
or
COPY filename newname

- TO DISPLAY NEW FILE NAMES
- TO DISPLAY A FILE
- TO PURGE A FILE
- TO DELETE A FILE
- TO MOVE A FILE

ZK-1750-84

The file names change each time you clean your directory; therefore, they are
variables. Any or all of the commands may be executed depending on the operation
you need to perform; therefore, each command is conditional. The entire process is
repeated until the directory is clean; therefore, it is iterative.
Decide how to load the variables, test the conditionals, and exit from the loop. The
following decisions would be made for the clean directory procedure:
•

Load variables—Get the file names from the terminal.

•

Test conditionals—Get a command name from the terminal and execute the
appropriate statements based on the command. The first two characters of each
command must be read to differentiate between DELETE and DIRECTORY.

•

Exit from loop—Get an EXIT command from the person using the procedure.

Fill in the design:

GET command

If command begins with Dl
DIRECTORY

If command begins with TY
GET filename
TYPE filename

If command begins with PU
GET filename
PURGE filename

If command begins with DE
GET filename
DELETE/CONFIRM filename

If command begins with CO
GET filename
GET newname
COPY filename newname

If command begins with EX
EXIT
ZK-1751-84

6.7.2 Coding Complicated Command Procedures
To make the command procedure easier to understand and to maintain, try to
write the statements so that the procedure executes straight through from the first
command to the last command. The following subsections describe how to execute

Command Procedures

6-19

conditional code and loops in a linear fashion. Section 5.2 discusses the logical
operators used in condition expressions.

6.7.2.1 Conditional Code
The recommended arrangement of conditional statements depends on whether a
specified condition causes the execution of one or more commands.
•

One command—To execute a single command, make the command part of the
IF statement as shown. The command is executed if the condition is met.

•

More than one command—How you execute a block of commands depends on
whether you leave the commands in the same command procedure or put them
in another command procedure.

IF condition THEN command

If you leave the commands in the command procedure, place them after the IF
statement. If the condition is not met, pass control to a label at the end of the
block of commands, as follows:

$ IF not condition THEN GOTO end-label
.

! block of commands

$end_label:
If you put the commands into a separate command procedure, make the call
to that command procedure part of the IF statement. The specified command
procedure is executed if the condition is met.

IF condition THEN (©command—procedure
In the following example, two commands (INQUIRE and PURGE) are executed if
COMMAND equals "PU".
$ ! Purge a file
$ IF COMMAND .NES. "PU" THEN GOTO END.PURGE
$ INQUIRE FILESPEC "File to purge"
$ PURGE *FILESPEC *
$END_PURGE:

6-20

Command Procedures

The following statement performs the same function. (The command procedure
PURGE_FILE.COM would be in a separate file; it is indented here for clarity.)
$ IF COMMAND .EQS. "PU" THEN @PURGE_FILE
$ ! PURGE_FILE.COM
$ ! Purge a file
$ INQUIRE FILESPEC "File to purge"
$ PURGE 1FILESPEC’

6.7.2.2 Case Statements
A case statement is a special form of conditional code that executes one out of a set
of command blocks, depending on the value of a variable or expression. Typically,
the valid values for the case statement are labels at the beginning of each command
block. The case statement passes control to the appropriate block of code by using
the specified value as the target label in a GOTO statement.
To write a case statement:
1.

List the labels—Equate a symbol to a string that contains a list of the labels
delimited by slashes (or any character you choose to act as a delimiter). This
symbol definition should precede the command blocks.
$ COMMAND.LIST = "/PURGE/DELETE/EXIT/"

Write the "case statement"—First get the value of the case variable. (Generally,
the user supplies a value.) Then, use F$LOCATE and F$LENGTH (described in
Appendix LEX) to determine whether the value of the case variable is valid. If
so, pass control to the appropriate block of code. Otherwise, display a message
and exit or request a different case value. (Since the label is equated to the
full command name, F$LOCATE includes the delimiters in its search for the
command name to ensure that the command is not abbreviated.) The case
statement should follow the list of labels and precede the blocks of code.
$GET_COMMAND:
$ INQUIRE COMMAND "Command (EXIT,PURGE,DELETE)"
$ IF F$L0CATE ("/"+C0MMAND+"/",COMMAND_LIST)
F$LEN (COMMAND_LIST) THEN GOTO ERROR.1
$ GOTO * COMMAND *

.EQ.

$ERR0R_1:
$ WRITE SYS$OUTPUT "No such command as * *COMMAND *"
$ GOTO GET.COMMAND

Command Procedures

6-21

3. Write the command blocks—Each block of commands may contain one or more
commands. Begin each command block with a unique label. End each command
block by passing control to a label outside the list of command blocks.
$GET_COMMAND:

SPURGE:
$ INQUIRE FILE
$ PURGE ’FILE*
$ GOTO GET_COMMAND
$
SDELETE:
$ INQUIRE FILE
$ DELETE 'FILE'
$ GOTO GET.COMMAND
$
SEXIT:

6.7.2.3 Loops
The following arrangement is recommended for statements that form a loop:
1.

Begin the loop.

Change the termination variable.

Test the termination variable. If the condition is met, go to the end of the loop.

Perform the commands in the body of the loop.

Return to the beginning of the loop.

End the loop.

You can also write loops that test the termination variable at the end of the loop
rather than at the beginning, as follows:
1.

Begin the loop.

Perform the commands in the body of the loop.

Change the termination variable.

Test the termination variable. If the condition is not met, go to the beginning of
the loop.

End the loop.

Note that when you test the termination variable at the end of the loop the
commands in the body of the loop are executed at least once regardless of the
value in the termination variable.

6-22

Command Procedures

Both the examples that follow execute a loop that terminates when COMMAND
equals "EX" (EXIT). (F$EXTRACT, which is described in Appendix LEX, shortens
COMMAND to its first two characters.) In the first example, COMMAND (the
termination variable) is tested at the beginning of the loop; in the second, it is tested
at the end.
$

EXAMPLE 1

$ !
$GET_COMMAND:
$ INQUIRE COMMAND'•Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) "
$ COMMAND = FSEXTRACT(0,2,COMMAND)
$ IF COMMAND .EQS. "EX" THEN GOTO END_L00P
!

body of the loop

$ GOTO GET_COMMAND
$END_L00P:
$

EXAMPLE 2

$ !
$GET_COMMAND:
$ INQUIRE COMMAND"Command (EXIT.DIRECTORY,TYPE,PURGE.DELETE,COPY)"
$ COMMAND = FSEXTRACT(0,2,COMMAND)
!

body of the loop

$ IF COMMAND .NES.
$ ! End of loop

"EX" THEN GOTO GET_COMMAND

To perform a loop a known number of times, use a counter as the termination
variable. In the following example, 10 file names are input by the user and placed
into the local symbols FIL1, FIL2, ..., FIL10:
$ NUM = 1
SLOOP:
$ INQUIRE FIL’NUM’ "File"
$ NUM = NUM + 1
$ IF NUM .LT. 11 THEN GOTO LOOP
$END_L00P:

Set counter
Begin loop
Get file name
Update counter
Test for termination
End loop

Command Procedures

6-23

To perform a loop for a known sequence of values, use F$ELEMENT. In the
following example, the files CHAP1, CHAP2, CHAP3, CHAPA, CHAPB, and
CHAPC are processed in that order.
$ FILE.LIST = "1,2,3,A,B,C"
$ INDEX = 0
$PROCESS:
$ FILE = CHAP’F$ELEMENT(INDEX,”,",FILE_LIST) ’
$ IF FILE .EQS.
GOTO END_L00P
! process file named by FILE
$ INDEX = INDEX + 1
$ GOTO PROCESS
$ENDL00P:

6.7.2.4 Subroutines
The GOSUB command transfers control to a labeled subroutine in a command
procedure without creating a new procedure level. Since the GOSUB command
does not cause the creation of a new procedure level, it is referred to as a "local"
subroutine call. The RETURN command terminates the GOSUB subroutine
procedure, returning control to the command following the calling GOSUB statement.
The following command procedure shows how to use the GOSUB command to
transfer control to labeled subroutines. After TEST2 is executed, the RETURN
command returns control back to the command line following each calling GOSUB
statement.

$!
$! GOSUB.COM
$!
$ SHOW TIME
$ GOSUB TEST1
$ WRITE SYS$0UTPUT "success completion"
$ EXIT

$!
$! TEST1 GOSUB definition
$!
$ TEST1:
$
WRITE SYS$0UTPUT "This is GOSUB level 1."
$
GOSUB TEST2
$
RETURN

$!
$! TEST2 GOSUB definition
$!
$ TEST2:
$
WRITE SYS$0UTPUT "This is GOSUB level 2."
$
RETURN

6-24

Command Procedures

The CALL command transfers control to a labeled subroutine in a command
procedure and creates a new procedure level. Execution of the CALL command
proceeds until an EXIT command is encountered. Control is then transferred to the
command following the CALL command.
Local symbols and labels defined within a nested subroutine structure invoked
with the CALL command are treated as if the routines had been invoked with
the @ command. Labels are only valid for the subroutine level in which they are
defined. Local symbols defined in an outer subroutine level are available to any
inner subroutine levels.
The SUBROUTINE and ENDSUBROUTINE commands define the beginning and
end of a subroutine invoked with the CALL command. The subroutine must
begin with the SUBROUTINE command as the first executable statement. The
ENDSUBROUTINE command functions as an EXIT command if an EXIT command is
not specified in the procedure.
The label defining the entry point to the subroutine must appear either before the
SUBROUTINE command or on the same command line. A subroutine can have only
one entry point.
The following procedure shows how to use CALL to transfer control to a labeled
subroutine. The example also shows that you can call another command file from
within a subroutine. (You can also call another subroutine from a subroutine.)
The CALL command invokes the subroutine SUB1, directing output to the file
NAMES.LOG and allowing other users write access to the file.
$
$! CALL.COM
$
$! Define subroutine SUB1
$!
$ SUB1: SUBROUTINE

$ QFILE

!Invoke another procedure command file

$ EXIT
$ ENDSUBROUTINE
!End of SUB1 definition
$!
$! Start of main routine. At this point, SUB1 has
$! been defined but none of the previous commands have
$! been executed.

Command Procedures

6-25

$ START:
$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS PI"

EXIT !Exit this command procedure file

6.7.3 Testing and Debugging
For lengthy or complicated command procedures, write the logic for the main
procedure, but use stubs for the nested procedures and subroutine-type pieces of
code. A stub writes a message stating the function it is replacing.

$ ! Purge a file
$ IF COMMAND .NES. "PU" THEN GOTO END.PURGE
$ WRITE SYS$OUTPUT "Purge routine"
! stub
$END_PURGE:

If you have a number of places that need stubs, you can use one nested command
procedure to insert the stub logic. (The command procedure STUB.COM would be
in a separate file; it is indented here for clarity.)

$ ! Purge a file
$ IF COMMAND .NES. "PU" THEN GOTO END_PURGE
$ OSTUB "Purge"
$ ! STUB.COM
$ ! Procedure STUB
$ WRITE SYSSOUTPUT "”P1* routine"
$END_PURGE:

Once you have written the code using stubs, you can test the overall logic of the
command procedure. Test all possible paths of execution. For example, to test the
following statements, print the purge and the delete messages and then exit using
the EXIT command.
$ ! CLEAN.COM
$ !
$GET_C0MMAND:
$ ! Read a command from the terminal
$ INQUIRE COMMAND"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY)"
$ COMMAND = FSEXTRACT(0,2,COMMAND)
$
$ IF COMMAND .EQS. "EX" THEN GOTO END.COMMAND
$
$ ! Purge a file
$ IF COMMAND .NES. "PU" THEN GOTO END.PURGE
$ WRITE SYS$OUTPUT "Purge routine."
$END_PURGE:
$
$ ! Delete a file
$ IF COMMAND .NES. "DE" THEN GOTO END.DELETE
$ WRITE SYS$OUTPUT "Delete routine."
$END_DELETE:

$ GOTO GET.COMMAND
$END_COMMAND:
Once the overall logic of the procedure works, you can begin filling in the stubs. Fill
in the first stub, test it, and debug it if necessary. When that stub works, move on to
the next one.
The following commands are useful for debugging command procedures:
•

SET VERIFY—SET VERIFY prints each line before it is executed. When an error
occurs with verification set, you see the error and the line that generated the
error. In the following example, seeing the command line that generated the
error explains the error message.

Command Procedures

6-27

$ SET VERIFY
$ OCDIR
$ ! Read a command from the terminal
$ INQUIRE COMMAND"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY)"
Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE. COPY): DELETE
$ COMMAND = F$EXTRACT(0,2,COMMAND)
$GET_COMMAND:
$ IF COMMAND .EQ. "EX" THEN GOTO END_COMMAND
*/,DCL-W-IVCHAR, non-numeric character in value string
\E\ EXIT
$ IF COMMAND .NES. "DI" THEN GOTO END.DIR

The logical operator .EQ. is used to compare numbers, not strings (see
Section 5.2). To correct the error, change .EQ. to .EQS.. Note that you can
use keywords with SET VERIFY to indicate that only command lines or data
lines are to be verified.
•

SHOW SYMBOL—Use the SHOW SYMBOL command to print the values of
the symbols involved in an error. In the following procedure, the IF statements
are not passing control to the expected procedures. Putting the SHOW SYMBOL
COMMAND command before the IF statements allows you to check the value of
COMMAND.
$ SET VERIFY
$ SCDIR
$GET_COMMAND:
$ ! Read a command from the terminal
$ INQUIRE COMMAND"Command (EXIT, DIRECTORY, TYPE, PURGE. DELETE, COPY)"
Command (EXIT, DIRECTORY, TYPE. PURGE, DELETE, COPY): DELETE
$ COMMAND = F$EXTRACT(1,2,COMMAND)
$ SHOW SYMBOL COMMAND
COMMAND = "EL"
$GET_COMMAND:
$ IF COMMAND .EQS. "EX" THEN GOTO END.COMMAND

The F$EXTRACT lexical function is extracting two characters beginning at character
1 (the second character) rather than at character 0 (the first character). To correct the
error, change F$EXTRACT(l,2,COMMAND) to F$EXTRACT(0,2,COMMAND). Note
that INQUIRE automatically converts input to uppercase; therefore, the quoted string

6-28

Command Procedures

in the IF statement must be written in uppercase for DCL to evaluate the strings as
equal.

6.8 Handling Errors and CTRL/Y Interrupts
The following table describes the default action taken when an error occurs or when
you press CTRL/Y. These default actions can be overridden with the ON, SET
[NO]ON, and SET [NO]CONTROL=Y commands.

Interrupt

Default Action

Error or
severe error

Procedure exits to the next command level.

CTRL/Y at
DCL command level
or command level 1

Interrupts procedure: procedure can continue if no other image
forces it to exit.

CTRL/Y at command
level lower than
level 1

Procedure exits to the next higher command level.

6.8.1 The ON Command
The ON command specifies an action to be performed if an error of a particular
severity or greater occurs. See Section 1.9 for a discussion of error conditions and
severity levels. If such an error occurs, the system takes the following actions:
1.

The error message is displayed.

The action specified by the ON command is performed.

The default error action (exit to the next higher command level) is reset.

If an error of less than the specified severity occurs, the error message is displayed
and the command procedure continues executing. Assume a command procedure
executes the following command:
$ ON ERROR THEN GOTO ERR1
The command procedure continues to execute unless an error or severe error occurs.
If such an error occurs, the error message is displayed; the default error action (exit
to the next higher command level) is reset; and the command procedure continues
execution at ERR1. If a second error occurs before another ON or SET NOON
command is executed, the procedure exits to the next higher level.

Command Procedures

6-29

The execution of an ON statement performs an implicit SET ON function, thus
nullifying any SET NOON condition that may be in effect.

NOTE:

Only one ON statement can be in effect at any one time. If more than one
ON statement has been issued, only the last one is in effect.

6.8.2 The SET [NO]ON Command
The SET ON and SET NOON commands enable and disable error checking for the
current command level. The SET NOON command overrides the ON command. If
an error (regardless of severity) occurs after a SET NOON command is executed, the
system takes the following actions:
1.

Displays the error message

Continues execution of the procedure

SET NOON remains in effect until either an ON or SET ON command is executed.
The SET ON command resets the action specified by the last ON command.
In the following command procedure, if an error or severe error occurs while copying
the file, the procedure continues to execute without going to GET_COMMAND as
specified by the ON command.
$ ON ERROR THEN GOTO GET.COMMAND
SGET.COMMAND:

$ ! Type a file
$ IF COMMAND .NES. "CO" THEN GOTO END.COPY
$ INQUIRE FILESPEC "File to move"
$ INQUIRE COPYSPEC "New file specification"
$ SET NOON
$ COPY ’FILESPEC’ ’COPYSPEC’
$ SET ON
$END_C0PY:

6-30

Command Procedures

6.8.3 CTRL/Y Interrupts
The ON CONTROL _Y command specifies an action to be performed when CTRL/Y
is pressed at the command level that defined the CTRL/Y action. In the following
command procedure, pressing CTRL/Y while a file is being typed passes control to
END_TYPE.

$ ! Type a file
$ IF COMMAND .NES. "TY" THEN GOTO END.TYPE
$ ON CONTROLS THEN GOTO END.TYPE
$ TYPE ’FILESPEC’
SEND.TYPE:
$
$ !Reset default
$ SET N0C0NTR0L=Y
$ SET C0NTR0L=Y

An ON CONTROL _Y command remains in effect until another ON CONTROL _Y
or a SET NOCONTROL=Y command is executed or the command procedure exits.
See Section 6.9 for another example of using the ON CONTROL__Y command.
To exit from a non terminating loop when CTRL/Y is disabled, you must delete your
process from another terminal using the DCL command STOP. If you disable the
CTRL/Y default action, reset it as soon as possible. To reset the CTRL/Y default,
execute the SET NOCONTROL=Y command followed by the SET CONTROL=Y
command, as shown in the previous example.

6.9 Cleanup Operations
In general, execution of a command procedure should not affect the user's process
state. Therefore, a command procedure should include a set of commands that
returns the process to its original state. Common cleanup operations include the
following (see Appendix LEX for lexical function specifications):
•

Closing files—If you have opened any files, make sure that they are closed
before the command procedure exits. You can use the lexical function F$GETJPI
to examine the remaining open file quota (FILCNT) for the process. If FILCNT
is the same at the beginning and end of the command procedure, you know that
no files have been left open. In the following example, a warning message is
displayed if a file is left open.

Command Procedures

6-31

$ FIL.COUNT = F$GETJPI("","FILCNT")

$ IF FIL.COUNT .NE. F$GETJPI("","FILCNT") THENWRITE SYS$OUTPUT "WARNING — file left open"
•

Deleting temporary or extraneous files—If you have created temporary files,
delete them. In general, if you have updated any files, you should purge them to
delete the previous copies. Take care in deleting files that you have not created.
For example, if you have updated a file that contains crucial data, you may wish
to make the purging operation optional.

•

Resetting default device and directory—If you change the default device and/or
directory, reset the original defaults before the command procedure exits.
To save the name of the original default directory, use the DEFAULT keyword of
the F$ENVIRONMENT lexical function. At the end of the command procedure,
include a SET DEFAULT command that restores the saved device and directory.
The following example saves and restores device and directory defaults.
$ SAV.DEFAULT = F$ENVIRONMENT("DEFAULT")

$ SET DEFAULT ’SAV_DEFAULT *
The following table lists other commonly changed process characteristics along with
the lexical functions and commands used to save and restore the original settings.

Characteristic

To save...

To restore...

DCL prompt

F$ENVIRONMENT

SET PROMPT

Default protection

FSENVIRONMENT

SET PROTECTION/DEFAULT

Privileges

F$PRIVILEGES

F$SETPRV or SET PROCESS
/PRIVILEGES

Control characters

F$ENVIRONMENT

SET CONTROL

Verification

FSENVIRONMENT

F$ VERIFY

Message format

FSENVIRONMENT

SET MESSAGE

Key state

FSENVIRONMENT

SET KEY

To ensure that cleanup operations are performed even if the command procedure is
aborted, begin the command procedure with the following statement:
$ ON CONTROL.Y THEN GOTO CLEAN.UP
Cleanup operations follow the CLEAN_UP label. Default CTRL/Y action is reset
when the command procedure exits.

Chapter 7
Accounts and Security
7.1

User Accounts

User accounts are maintained in a file named SYS$SYSTEM:SYSUAF.DAT, referred
to as the user authorization file, or UAF. A VAX/VMS system uses the UAF to
validate login requests and to set up processes for users who successfully log in. You
can examine and modify this file with the Authorize Utility (AUTHORIZE).

7.1.1 User Authorization File
The UAF contains a record for each account. Each record consists of fields providing
information for the following areas: identification, login characteristics, login
restrictions, priority, limits, and privileges. The username field is specified as a
parameter to Authorize Utility commands; the other fields are specified as qualifier
values of Authorize Utility commands. See the VAX/VMS Authorize Utility Reference
Manual for descriptions of the qualifiers and information on invoking the Authorize
Utility.

7.2 Protection
A VAX/VMS system provides two related mechanisms to control the access that
users have to system objects.
•

UlC-based protection—Each user process in the system is assigned a user
identification code (UIC) in the user authorization file (UAF) with the Authorize
Utility. Each object on the system is also associated with a UIC (typically the
UIC of its creator). A protection mask associated with an object determines the
type of access allowed to a user, based on the relationship between the user UIC
and the object UIC.

7-2

•

Accounts and Security

ACL-based protection—An access control list (ACL) that specifies the type
of access to be granted or denied to a particular user or group of users may
be associated with a system object. The system objects for which ACL-based
protection may be specified are: files, directories, devices, logical name tables,
and global sections. Users are specified by identifiers in the rights database that
are assigned with the Authorize Utility.

The system determines whether to grant a user access to an object in the following
steps:
1.

ACL—If the user matches an identifier in the object's ACL, the system grants or
denies access based on the ACL. However, even if an entry in the ACL denies
access, the system may still grant access based on the SYSTEM and OWNER
fields of the UlC-based protection.

UIC—If the user does not match an identifier in the object's ACL or the object
has no ACL, the system grants or denies access based on the relationship
between the user's UIC and the object's UIC as qualified by the object's
protection mask.

Privileges—If the system denies the user access, the user may be granted access
by using one of the following privileges: BYPASS, GRPPRV, READ ALL, or
SYSPRV.

UlC-based protection is useful for denying or granting access to a specified group
of users or to all users on the system. The optional ACL-based protection allows
further control over the protection of an object: you can grant or deny access to
individual users, and you can further identify users by certain aspects of their usage
(such as whether they are interactive, batch, local, remote, or dial-up users). The
combination of UIC and ACL protection provides a way to specify multiple subsets
and overlapping groups of users.

7.2.1 UlC-Based Protection
Typically, you use UlC-based protection if the object is to be accessed by (1) only the
owner, (2) all users on the system, or (3) a specific group of users.

Accounts and Security

7-3

7.2.1.1 User Identification Code
UICs are a subset of the identifiers that the VAX/VMS system uses to identify users
and groups of users (see Section 7.2.2.2 for other identifiers). A UIC consists of two
parts, group and member, specified in the following format:

[group,member]
A UIC can be either numeric or alphanumeric.
•

Numeric UIC—Consists of a group number in the range 0 through 37776 (octal)
and a member number in the range 0 through 177776 (octal).

•

Alphanumeric UIC—Consists of a member name (the username parameter
specified with the Authorize Utility command ADD) and, optionally, a
group name (the name specified with the Authorize Utility command ADD
/ACCOUNT); both member and group names must contain at least one
alphabetic character and up to a maximum of 31 alphanumeric characters
(including A-Z, 0-9, underscore, and dollar sign characters). An alphanumeric
UIC is equated to a numeric UIC in the rights database by default once the rights
database has been created. You can generally specify a numeric UIC and its
equivalent alphanumeric UIC interchangeably.

The member component of a UIC must be unique to the system. By default, the
member component of an alphanumeric UIC is equated to both the group and
member components of a numeric UIC in the rights database (so that specifying
just the member part of an alphanumeric UIC is sufficient). The following examples
illustrate several UICs in proper UIC notation.
UIC

Meaning

[200,10]

Group 200, member 10

[3777,3777]

Group 3777, member 3777

[USER,FRED]

Group USER, member FRED

[EXECJONES]

Group EXEC, member JONES

[JONES]

Group EXEC, member JONES

When you log in to a VAX/VMS system, your process UIC is specified in your
UAF account. Typically, your process UIC does not change, although it can be
changed with the SET UIC command (which requires CMKRNL privilege). By
default, detached processes (created by the DCL command SUBMIT or RUN) and
subprocesses (created by the DCL command SPAWN) take the same UICs as their
creators. If you have DETACH privilege, you can create a detached process with a
different UIC (by using the /UIC qualifier of the RUN command).

7-4

Accounts and Security

By default, an object (such as a file) receives the UIC of the process creating it. You
can specify the UIC of a file with the /OWNER _UIC qualifier of the BACKUP,
CREATE, SET DIRECTORY, and SET FILE commands. With SYSPRV privilege, you
can specify any UIC; with GRPPRV privilege, you can specify any member within
your current group; otherwise, you can specify only your own UIC. You can specify
the UIC of a disk volume with the /OWNER—UIC qualifier of the INITIALIZE and
MOUNT commands (except for the system disk, which retains the UIC specified
when it was initialized). You can also change the UIC of a disk (including the system
disk) with the SET VOLUME command. You must have the VOLPRO privilege to
specify a UIC other than your own. In addition, when you initialize a system disk
(/SYSTEM qualifier), it receives a UIC of [1,1] and a group disk (/GROUP qualifier)
receives a UIC of [n,0], where n is the group number of the owner. You can specify
a UIC for a device such as a terminal (by default, devices are not owned) with the
/OWNER_UIC qualifier of the SET PROTECTION/DEVICE command.

7.2.1.2 Ownership and Access Categories
The relationships between the UIC of a process and the UIC of an object fall into the
following four ownership categories:
•

System—The UIC of the process is in the range 1 through 10 (octal) or the
process has SYSPRV (or GRPPRV) privilege. (The range of system UICs is
determined by the SYSGEN parameter MAXSYSGROUP, which defaults to 10
octal.)

•

Owner—The UIC of the process and the UIC of the object are identical.

•

Group—The group number of the process and the group number of the object
are identical.

•

World—The UIC of the process and the UIC of the object can have anything or
nothing in common.

A process and object may have any number of the above relationships. For example,
a process that owns an object necessarily has group and world relationships with the
object.
A process can access an object in the following ways:
•

Read (allocate)—Read a file; read from a disk volume; allocate nonfile devices.

•

Write—Write a file; write to a disk volume.

•

Execute (create)—Execute an image file; look up entries in a directory if you
explicitly specify the file name (without using wildcard characters); create files on
a disk volume.

•

Delete—Delete files.

Accounts and Security

7-5

7.2.1.3 Protection Masks
A protection mask consists of four fields, each with four indicators. Each field applies
to one category of ownership. Each indicator within a field applies to one category
of access. The fields and indicators are as follows:

Ownership

Access

SYSTEM

READ

WRITE

EXECUTE

DELETE

OWNER

READ

WRITE

EXECUTE

DELETE

GROUP

READ

WRITE

EXECUTE

DELETE

WORLD

READ

WRITE

EXECUTE

DELETE

Protection for an object must be specified in the following format:

(ownership[:access],...)
Specify ownership as one of the following (each may be abbreviated to one
character): SYSTEM, OWNER, GROUP, or WORLD. Specify access as one or more
of the following indicators: R (read), W (write), E (execute), D (delete). Omission of
the colon and access indicators means no access for that category of ownership. The
following protection specification allows system users full access to an object, the
owner full access except delete, and group and world users no access:

(S:RWED,0:RWE,G,W)
Omission of an ownership category generally results in no access being granted that
category. However, the SET PROTECTION command retains the existing protection
of the object for omitted fields of the ownership category.

7.2.1.4 Securing User Data and Devices
The suggestions for UlC-based protection of data and devices belonging to individual
and application accounts are as follows:
•

Default protection—Make sure your default protection is adequate for the
average situation. In general, you do not want to grant write or delete access to
world users. You may or may not want to grant write access to group users. You
may or may not want to grant read access to world users.

•

Sensitive files—Protect sensitive files by specifying extra protection, for example,
with the SET PROTECTION command. You can also protect sensitive files by
maintaining them in a subdirectory on which extra protection is set. (However,
to protect sensitive files completely, the directory protection alone is not
adequate. You must also protect each individual file contained within the
directory. You can add a default protection ACE to the subdirectory file to
facilitate this process.

Accounts and Security

7-6

•

Individual access—Use access control lists (ACLs) to grant or deny individual
users access to a file (see Section 7.2.2).

•

Copied files—In general, do not copy a file into someone else's directory (for
example, if you have write access to a group member's directory), as it will have
your UIC instead of the UIC of the directory's owner. Use the MAIL command
to send the file, or have the owner of the directory copy the file.
Private volumes—If you mount a private volume, be sure to deallocate the device
when you are done.

7.2.2 ACL-Based Protection
Typically, you use access control lists (ACLs) on system objects to grant or deny
access to individual users, groups of users, and to subsets of user groups. ACLs
contain entries (ACEs) that specify the access to be granted or denied a user or group
of users. The user or group of users is designated by identifiers.

7.2.2.1 Object Types
You can establish ACLs for various system objects: files, directory files, global
sections, devices, and logical name tables. In general, you need not be concerned
about the object type when establishing or changing an ACL; however, you do
need to be aware of few object-specific considerations. This section describes these
considerations.
Devices
You must reestablish ACLs on devices every time the system is booted because they
are not saved. ACLs on devices are set up and modified with the ACL Editor or with
the command:
$ SET ACL/OBJECT_TYPE=DEVICE device-name
Global Sections
You must reestablish ACLs on global sections (except those backed by files) every
time the system is booted because they are not saved.
The ACL on a global section backed by a file is the ACL of the file. Changing the
file's ACL causes the corresponding change in the global section's ACL. The ACL on
the global section itself cannot be changed directly.
You can establish ACLs on both system and group global sections. Note, however,
that if a user attempts to access a group global section that is outside his UIC group,
the operating system denies him access and does not consider the ACL. ACLs on

Accounts and Security

7-7

page frame numbers (PFN) and page file global sections may be set up and modified
with the ACL Editor or with the commands:
$ SET ACL/OBJECT_TYPE=SYSTEM_GLOBAL_SECTION section_name
$ SET ACL/OBJECT_TYPE=GROUP_GLOBAL_SECTION section.name
Logical Name Tables
You must reestablish ACLs on logical name tables every time the system is booted
because they are not saved. ACLs on logical name tables are set up and modified
with the ACL Editor or with the command:
$ SET ACL/OBJECT_TYPE=LOGICAL_NAME_TABLE table-name

7.2.2.2 Identifiers
An identifier is a value that represents an individual user, a group of users, or an
aspect of the user's environment. There are three types of identifiers:
•

UIC

•

General identifiers

•

System-defined identifiers

UICs can be in both numeric and alphanumeric form and are (see Section 7.2.1.1)
useful in identifying individual users. UIC identifiers must be enclosed in brackets
and may have wildcard characters in either the group or member fields (for example,
[EXEC,*]).
Identifiers include other general identifiers that you explicitly associate with users
in the rights database. These general identifiers are useful in identifying multiple
groups of users outside the bounds of UIC groups. For example, you could create the
identifier SECRET and assign it in the rights database to a selected group of users,
some of whom could be in different UIC groups.
A third type of identifier includes the following system-defined identifiers, which you
can use to identify users by their mode of using the system.
System-defined Identifiers

Type of user

BATCH

Batch user

DIALUP

User logged in on a dial-up terminal

INTERACTIVE

Interactive user

LOCAL

User logged in on local terminal

NETWORK

Network process

REMOTE

User logged in over the network

7-8

Accounts and Security

Generally, you should treat the preceding system-defined identifiers as being
mutually exclusive. However, you can combine them with UIC identifiers or general
identifiers by connecting them with plus signs (for example, [FRED]+BATCH). Access
is granted only if both identifiers are true. (In the example [FRED]+BATCH, the user
identified as [FRED] must be running a batch job for the system to grant the specified
access.)
The following are examples of user-defined identifiers that are valid for ACL-based
protection:
•

PAYROLL—Specifies all users holding the identifier PAYROLL.

•

[USERJONES]—Specifies the user whose alphanumeric UIC is group USER and
member JONES.

•

[200,10]—Specifies the user whose numeric UIC is group 200, member 10.

•

[FREDJ+BATCH—Specifies the batch user whose alphanumeric UIC is FRED.

•

DIALUP—Specifies all users logged in on a dial-up terminal.

7.2.2.3 Access Control Entries (ACE)
An entry in an access control list specifies the access to a system object that is to be
granted or denied a user. This access is specified by the identifier. Different kinds of
access are: NONE, READ, WRITE, EXECUTE, DELETE and/or CONTROL.
There are three types of ACEs:
•

Identifier ACE

•

Default protection ACE

•

Security alarm ACE

7.2.2.4 IDENTIFIER ACEs
An identifier ACE controls the type of access allowed to a particular user or group of
users. Identifier ACEs have the following format:

(IDENTIFlER=identifier[,OPTIONS=options+...],ACCESS=access+...)
The following are examples of ACEs:
(IDENTIFIER=[200,201],ACCESS=READ+WRITE+EXECUTE)
Grants the user identified by UIC identifier [200,201] read, write, and execute access
to the system object.
(IDENTIFIER=[FRED]+BATCH,ACCESS=WRITE+EXECUTE)
Grants batch users with the alphanumeric UIC [FRED] write and execute access to
the system object.
(IDENTIFIER=PAYROLL,ACCESS=READ)

Accounts and Security

7-9

Grants users who hold the identifier PAYROLL read access to the system object.
(IDENTIFIER=DIALUP,ACCESS=NONE)
Denies holders of the system-defined identifier DIALUP any access to the system
object.
The preceding ACEs could be specified in a single ACL for a system object, as
follows:
(IDENTIFIER=[200,201],ACCESS=READ+WRITE+EXECUTE)
(IDENTIFIER=[FRED]+BATCH,ACCESS=WRITE+EXECUTE)
(IDENTIFIER=PAYROLL,ACCESS=READ)
(IDENTIFIER=DIALUP,ACCESS=N0NE)
To specify one or more default ACEs for inclusion in the ACLs of files subsequently
created in a directory, use the OPTIONS=DEFAULT option of an identifier ACE. The
following ACE , when placed in the ACL of the directory file, grants all users holding
the SECRET identifier read, write, and execute access to new files in the directory by
default.
(IDENTIFIER=SECRET,0PTI0NS=DEFAULT,ACCESS=READ+WRITE+EXECUTE)

NOTE:

Default protection is associated only with newly created files, not existing

ones.

7.2.2.5 Rights List
The system determines protection by checking the object's ACL against the list of
identifiers held by the accessor to find a matching entry. This list, called a rights list,
is maintained in the rights database.
The rights list is the portion of the rights database associated with a specific user.
The rights list is created for each user at login and contains all the identifiers and
attributes held by the user. On the other hand, the rights database is a file that
contains ALL the identifiers defined in the system.
You can add or remove entries in the rights list with the DCL command SET
RIGHTS—LIST. This differs from the rights database, which requires you to use
AUTHORIZE commands.
Beginning with the first entry in the rights list, all the accessor's identifiers are
compared to each entry in the list; the accessor must hold all identifiers specified in a
single entry for a match to exist. The search continues until a match is found.
Because the system determines access at the first matching entry, the order of
the entries is critical. For example, if the last entry in the previous example—
(IDENTIFIER=DIALUP,ACCESS=NONE)—were placed at the top of the list, all
dial-up users (including those specified in the remaining entries) would be denied
access to the associated file. Placing it last in the access control list allows users
holding identifiers [200,201], [FREDJ+BATCH, and [PAYROLL] the specified access,
even when they are dial-up users.

7-10

Accounts and Security

7.2.2.6 DEFAULT-PROTECTION ACEs
To specify default protection for new files in a particular directory, place a
default—protection ACE in the ACL of the directory file. (The directory file is the file
with the directory name as file name and DIR as file type in the parent directory).
The default—protection ACE affects files that are subsequently created in the directory
and in any subdirectories under that directory unless protection is specified for one
of those files individually. Default—protection ACEs apply UlC-based protection.
Specify a default—protection ACE in the following format, where
protection-mask is the same mask used in UIC protection (see Section 7.2.1.3):

(DEFAULT—PROTECTION^ options], protection-mask)
The following default—protection ACE specifies that by default the system and owner
have read, write, execute, and delete access to any files subsequently created for the
directory and that group and world users have no access.
(DEFAULT-PROTECTION,S:RWED,0:RWED,G,W)

7.2.2.7 ALARM-JOURNAL ACEs
The alarm—journal ACE allows you to specify that an alarm message be sent to
the security operator's terminal if a certain type of access takes place. Alarms are
supported only for files and global sections. The alarm—journal ACE functions only
when alarms to the security operator's terminal have been enabled through the
DCL command SET AUDIT, security messages to the operator's terminal have been
enabled with the DCL command REPLY/ENABLE=SECURITY, and the OPCOM
process is executing.
The format of an alarm—journal ACE is

(ALARM—JOURNAL=SECURITY[,options*...][,access*...])
The following alarm—journal ACE specifies that an alarm will be sent to the security
operator's terminal if an accessor attempts to read the object, and that this ACE will
be preserved even when an attempt is made to delete the entire ACL.
(ALARM.JOURNAL=SECURITY,0PTI0NS=PR0TECTED,ACCESS=READ+SUCCESS+FAILURE)
For an alarm to have any effect, you must include either SUCCESS or FAILURE or
both in the ACCESS field.

Accounts and Security

7-11

7.2.3 Protection of Files
For the most part, file protection is transparent. The tools exist, however, to adjust
the protection of a file as you see fit. You must own the file, have control access
to the file, or have GRPPRV, SYSPRV, BYPASS, or READ ALL privilege to set the
protection or modify the ACL of a file.

NOTE:

You cannot completely protect a file without applying at least the same
protection to the directory in which the file resides; see Section 7.2.3.3 for
information on directory protection.

7.2.3.1 Default File Protection
A new file receives default UlC-based protection and the default ACEs (if any) of
its parent directory. A renamed file's protection is unchanged. A new version of an
existing file receives the UlC-based protection and ACL of the previous file. (Use
the /PROTECTION qualifier of the BACKUP, COPY, and CREATE commands to
override the default UlC-based protection.)
•

Default UIC protection—The operating system provides each process with
a default UlC-based protection of (S:RWED,0:RWED,G:RE,W). To change
the default protection, invoke the SET PROTECTION command with the
/DEFAULT qualifier. For example, if you place the following command in your
login command procedure, you grant all processes read and execute access to any
files that you subsequently create. (Remember that you must execute the login
command procedure for this command to execute.)
$ SET PROTECTION = (S:RWED,0:RWED,G:RE,W:RE)/DEFAULT

•

Default ACL protection—You can override default UIC protection for specified
directories or subdirectories by placing a default—protection ACE in the ACL
of the appropriate directory file. The default protection specified in the ACE is
applied to any new file created in the specified directory or any subdirectory
of the directory. The following ACE, which must be in the ACL of a directory
file, specifies that the default protection for that directory and the directory's
subdirectories allow system and owner processes full access, group processes
read and execute access, and world users no access.
(DEFAULT.PROTECTION.S:RWED,0:RWED,G:RE,W:)
To specify a default identifier ACE to be copied to the ACL of any file
subsequently created in the directory, specify the DEFAULT option in the
directory file's identifier ACL.

7-12

Accounts and Security

7.2.3.2 Explicit File Protection
You can explicitly specify UlC-based protection for a new file with the /PROTECTION
qualifier (valid with the BACKUP, COPY, and CREATE command), as demonstrated:
$ CREATE MAST12.TXT/PROTECTI0N=(S:RWED,0:RWED,G,W)
You can change the UlC-based protection on an existing file with the SET
PROTECTION command, as demonstrated:
$ SET PROTECTIONS: RWED, 0: RWED, G,W) MAST 12 . TXT
After a file is created and you have created an ACL for the file, you can modify the
ACL and add as many ACEs to the ACL as you desire. The protection specified by
the ACL overrides the file's UIC protection.

7.2.3.3 Protection of Directories
You cannot completely protect a file without applying at least the same protection to
the directory in which the file resides. For example, if you deny a user all access to
a file but allow that user read access to the file's directory, the user cannot access the
contents of the file but can see that it exists. Conversely, a user allowed access to a
file and denied access to the file's directory (or one of the parent directories) cannot
see that the file exists.
NOTE: To protect sensitive files, the directory protection alone is not adequate.
You must also protect each individual file contained within the directory.
By default, top-level directories receive UlC-based protection (S:RWE,0:RWE,G:RE,W:E)
and no ACL. Subdirectories receive UlC-based protection minus any delete access or
default—protection ACEs from the parent directory.
To specify UlC-based protection explicitly when creating a directory, use the
/PROTECTION qualifier of the CREATE/DIRECTORY command. You cannot
specify an ACL for the directory until the directory is created. To change the
UlC-based protection of an existing directory, use the SET PROTECTION command
(apply this command to the directory file). To specify or change the ACL of an
existing directory, edit the directory file's ACL (see Section 7.2.3.1).
You can limit but not prohibit directory access by specifying execute access but not
read access. Execute access on a directory permits you to examine and read files that
you know are contained in the directory (that is, you know the file specifications) but
prevents you from displaying a list of the files in the directory.

7.2.3.4 Protection of Mail Files
Mail files receive the protection (S:RWD,0:RW,G,W). Files of type MAI cre¬
ated with the EXTRACT command of the Mail Utility receive the protection
(S:RWD,0:RWD,G,W).

Accounts and Security

7-13

7.2.4 Protection of Disk Volumes
By default, no protection is applied to newly initialized disk volumes. You can
specify protection with the /PROTECTION qualifier of the INITIALIZE command
and you can specify an ACL for a disk volume. The following example specifies
UlC-based protection for the disk volume ACCOUNT1.
$ INITIALIZE WORKDISK: ACC0UNT1 _$ /PROTECTION=(S:RWED,0:RWED,G:R,W:R)
You can respecify the protection each time you mount the volume with the
/PROTECTION qualifier of the MOUNT command. You must own the volume
or have VOLPRO privilege to change protection.
You can also limit access to a disk volume with the following qualifiers to the
INITIALIZE and MOUNT commands:
•

/SYSTEM—All processes have RWED access to the volume, but only system
processes (or processes with SYSNAM and SYSPRV privileges) can create
first-level directories. (The volume is owned by [1,1].)

•

/GROUP and /NOSHARE—System, owner, and group processes have RWED
access to the volume. World users have no access.

•

/NOSHARE—System and owner processes have RWED access to the volume.
Group and world users have no access.

At initialization time, the above qualifiers override any protection mask specified. At
mount time, however, the protection mask overrides the qualifiers. When mounting
a volume, you must have GRPNAM privilege to specify /GROUP and SYSNAM
privilege to specify /SYSTEM.

7.2.5 Protection of Devices
In general, device protection controls the ability to allocate the device and is specified
by granting read access in an ACL. To specify an ACL for a disk device, use the
SET ACL/OBJECT_TYPE=DEVICE command. For example, to grant a user with the
alphanumeric UIC [FRED] read access to the disk device WORKDISK, type:
$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENTIFIER=[FRED],ACCESS=READ) _$ WORKDISK
Note that when you specify an ACL for a disk device, the ACL is associated with
the device, not with the disk volume. For example, if you mount a disk device on
WORK1, specify the preceding SET ACL/OBJECT_TYPE=DEVICE command, and
then dismount the disk device, the ACL protection remains on WORK1 but not on
the disk device.

7-14

Accounts and Security

The only protection that applies to a nonfile device is the ability to allocate
it, specified by read access. By default, nonfile devices such as mailboxes are
unprotected. Interactive terminals are set up to provide complete access to system
users and no access to all other users. (Note that access here refers to access via an
application program. The device protection on a terminal does not control who can
log in on it.) You can change the protection of a nonfile device through the use of
ACLs or by changing the standard UIC protection. Modify the ACL with the DCL
command SET ACL/OBJECT_TYPE=DEVICE. Modify the UIC protection with the
DCL command SET PROTECTION/DEVICE (requires OPER privilege). For example,
the following command allows users holding the PAYROLL identifier read access to
TERMINAL3.
$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENTIFIER=PAYROLL,ACCESS=READ)
_$ TERMINAL3

7.2.6 Displays of Ownership and Protection
You can display ownership and protection information with the following commands
and qualifiers:
Command

Display

DIRECTORY/ACL file-spec

File's ACL

DIRECTORY/OWNER_UIC file-spec

File's UIC

DIRECTORY/PROTECTION file-spec

File's UlC-based protection

DIRECTORY/SECURITY

All of the above

DIRECTORY/FULL file-spec

All of the above

SHOW ACL

Device, file, logical name table, or global
section's ACL

SHOW PROCESS/ALL

Process UIC

SHOW PROTECTION

Default file protection

SHOW DEVICES/FULL device-name

Device UIC and protection

7.3 Creating and Deleting ACLs
Typically, you use the ACL editor to create an ACL or to make major changes to it,
and you use the DCL commands SET ACL, SET FILE/ACL, SET DIRECTORY/ACL,
and SET DEVICE/ACL to make minor changes to an ACL or to set an ACL on more
than one object.

Accounts and Security

7-15

7.3.1 Using the SET ACL Command
The DCL command SET ACL allows you to specify an ACL for a file, directory,
device, system logical name table, or global section. To specify an ACL for a device,
for example, specify the SET ACL command with the /OBJECT_TYPE=DEVICE
qualifier. For example, the following command specifies an ACL that grants users
who hold the identifier PAYROLL read access to the disk device WORKDISK:
$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENTIFIER=PAYROLL,ACCESS=READ) _$ WORKDISK
To set the same ACL on all files with the file type DAT in the default directory,
specify the following command:
$ SET ACL/OBJECT_TYPE=FILE/ACL=(IDENTIFIER=PAYROLL,ACCESS=READ) _$ *.DAT;*
To select a subset of the files specified by the wildcard character, use one or more of
the following qualifiers:
Qualifier

Meaning

/BY_OWNER

Selects files with a specified UIC

/EXCLUDE

Selects all but the specified files

/BEFORE

Selects files created or modified before a specified time

/SINCE

Selects files created or modified since a specified time

/CREATED

Specifies that /BEFORE or /SINCE check for the creation date

You can also use the /CONFIRM qualifier with those of the preceding list to elicit
a confirmation prompt for each file; the /CONFIRM qualifier allows you to specify
whether the file is to be affected.
By default, the DCL commands that create ACLs add the entries in the order specified
to the top of the ACL. (If the object does not have an ACL, an ACL is created.) Use
the /AFTER qualifier to specify a position for the entry (other than the top of the
ACL). For example, the following command places a new entry after an existing
entry—the ACE specified with the /AFTER qualifier—in the access control list of the
file DOGS83.DAT.
$ SET ACL/AFTER=(IDENTIFIER=[JONES],ACCESS=READ)_$ /ACL=(IDENTIFIER=SECRET,ACCESS=READ+EXECUTE) D0GS83.DAT
The /AFTER qualifier is especially useful because the ACEs are processed from first
to last. For example, if users holding the identifier PAYROLL are denied access in
an ACE that precedes one granting access to user FRED, and if FRED holds both
identifiers, FRED will be denied access.

7-16

Accounts and Security

The SET ACL command also permits the following ACL operations:
•

Delete an ACE—Use the /DELETE qualifier to delete ACEs (specified on the
/ACL qualifier) from an object's ACL. If no value is specified with the /ACL
qualifier, all the entries in the ACL of the specified objects are deleted (except
those entries protected by the PROTECTED option). The following example
deletes the ACE specified with the /ACL qualifier from the ACL of the latest
version of each file with type FOR in the default directory.
$ SET ACL/OBJECT_TYPE=FILE _$ /ACL=(IDENTIFIER=PAYROLL,ACCESS=READ+WRITE+EXECUTE)_$ /DELETE *.FOR

•

Replace an ACE—Use the /REPLACE qualifier to specify an ACE to replace the
ACE specified by the /ACL qualifier. If no value is specified with the /ACL
qualifier, the ACEs specified by the /REPLACE qualifier are added to the ACLs
of the specified object(s). The following example changes the ACE specified with
/ACL to the one specified by /REPLACE in the ACL of the device WORKDISK.
$ SET ACL/ACL=(IDENTIFIER=[200,200],ACCESS=READ)_$ /REPLACE=(IDENTIFIER=NONEXEC,ACCESS=N0NE)_$ /OBJECT_TYPE=DEVICE WORKDISK

•

Copy an ACL—Use the /LIKE qualifier to copy an ACL from one object to
another. Specify the name of the object whose ACL is to be copied as the value
of the /LIKE qualifier and specify the name of the object(s) to receive the ACL as
the parameter of the SET ACL command. The following example copies the ACL
from [USERJX.X to all versions of all files in the [USER] directory tree. The /LOG
qualifier displays each file specification as the file is modified. (You might also
wish to include the /CONFIRM qualifier, which issues a request for confirmation
before each modification.)
$ SET ACL/L0G/LIKE=[USER.TESTS]X.X

•

[USER...]*.*;*

Make an ACL the default—Use the /DEFAULT qualifier to set the ACL on an
existing file to be the same as a newly created file. Any ACL that already exists
on the file is deleted.

7.3.2 ACL Editor
To invoke the ACL editor, type EDIT/ACL followed by the name of the object whose
ACL you wish to edit and press RETURN.
$ EDIT/ACL PR0TA.TXT
If the object has an ACL, the ACL appears on the screen. Otherwise, you are creating
an ACL and will begin the editing session by entering an ACE. You enter ACL editor
commands by using the keypad keys pictured in the following diagram.

PF2
HELP

PF1

PF3
FNDNXT

GOLD
HELPFMT

7
SEL FIELD

FIND

ADV FIELD

4
ADVANCE

6
BACKUP
TOP

BOTTOM

1
WORD

EOL
DEL EOL

•

0
OVER ACE

ITEM
INSERT

ZK-1740-84

By default, the ACL editor assumes that the object whose ACL is being edite
file. To specify an object other than a file, use the /OBJECT_TYPE qualifier.
example, to edit the ACL of a device named TTA1:, you would enter the foll
command line:
$ EDIT/ACL/OBJECT_TYPE=DEVICE TTA1:

You can specify any one of the following objects with the /OBJECT_TYPE qu
FILE

Specifies that the object type is a file or a director

DEVICE

Specifies that the object type is a device

SYSTEM -GLOBAL -SECTION

Specifies that the object type is a system global se

GROUP-GLOBAL -SECTION

Specifies that the object type is a group global sec
Specifies that the object type is a logical name tab

LOGICAL-NAME-TABLE

To execute a command, press the key. To execute the lower command show
a key in the diagram, press the GOLD key first and then press the key. You

7-18

Accounts and Security

display information on each command by pressing the HELP key followed by the
command. To display information on the proper format of an ACE, press GOLD and
then HELP.
To exit from the editor, and create or modify the ACL, press CTRL/Z. To exit,
without creating or modifying the ACL, press GOLD and CTRL/Z. To refresh the
screen while in the editor (for example, after receiving a broadcast message), enter
CTRL/W.
The ACL editor edits a copy of the ACL. If your ACL editing session is terminated
by entering CTRL/Y or if the system fails, the existing ACL remains unchanged or,
if no ACL exists, no ACL is created. To recover an ACL editing session interrupted
by CTRL/Y or system failure, specify the /RECOVER qualifier of the EDIT/ACL
command.

7.3.2.1 Using Prompts
By default, the ACL editor prompts for each ACE and provides values in the various
fields within an ACE whenever possible. The /MODE qualifier controls the choice of
mode. To disable prompting, specify /MODE=NOPROMPT.
The FIELD, ITEM, and ENTER commands on the keypad enable you to take full
advantage of prompt mode in the ACL editor.
•

FIELD—Completes the current ACE field and moves the cursor to the next ACE
field or subfield, inserting text as needed. If the ACL editor is not in prompt
mode, the ACL editor advances to the next field in the current existing ACE.

•

ITEM—Selects the next item for the current ACE field. If the ACL editor is not
in prompt mode, this key is ignored.

•

ENTER—Indicates that the current ACE is complete and ready for parsing. This
key terminates the insertion. You can press it while the cursor is located at any
position within the ACE. (Pressing RETURN produces the same results.)

7.3.2.2 Moving the Cursor
To position the cursor within the current line, use the following commands:
Command

Action

EOL

Moves the cursor to the end of the line

WORD

Moves the cursor one word in the current direction

ADVANCE

Sets the cursor direction to forward

BACKUP

Sets the cursor direction to backward

LEFT ARROW

Moves the cursor left one character

RIGHT ARROW

Moves the cursor right one character

FIELD

Completes the current ACE field and moves the cursor to the nex
field or subfield

ITEM

Selects the next item for the current ACE field

The following commands move the cursor to a different line of the ACL.
Command

Action

BOTTOM

Moves the cursor to the end of the ACL

TOP

Moves the cursor to the beginning of the ACL

UP ARROW

Moves the cursor up a line

DOWN ARROW

Moves the cursor down a line

OVER ACE

Moves the cursor to the next ACE

To locate a specified text string or locate the next occurrence of a previously s
text string use FIND and FIND NEXT.

If the command moves the cursor out of an unprocessed ACE, the editor attem
process the current ACE. If the ACE is improperly formatted, an error occurs a
cursor remains in place.

7.3.2.3 Entering and Deleting Data

Unless you disable prompting, the following text appears on the screen when
invoke the ACL editor.
(IDENTIFIER=

If you want to create an identifier ACE, specify the identifier value by typing
the appropriate value. Or you can delete the text and type a default-protecti
alarm—journal ACE.
To delete text, use the following commands:
Command

Action

DEL C

Deletes the current character

DELETE key

Deletes the previous character

DEL W

Deletes the current word

LINE FEED

Deletes the previous word

DEL EOL

Deletes from cursor to end of line

DEL ACE

Deletes the current ACE

CTRL/U

Deletes the text from the cursor to the beginning of the line

7-20

Accounts and Security

If you delete text by mistake, you can restore it by using the following commands:
Command

Action

UND C

Restores the most recently deleted character

UND W

Restores the most recently deleted word

UND ACE

Restores the most recently deleted ACE

GOLD CTRL/U

Restores the most recently deleted portion of a line

7.3.2.4 Processing an ACE
To process an ACE, press ENTER or carriage return. You must process the current
ACE before you can begin editing a second ACE. If the ACE is in the proper format,
the editor puts the ACE into the ACL and moves the cursor to the next line. If
the cursor is positioned at the end of the ACL and if prompting is enabled, the
editor displays the text IDENTIFIER^ (Moving the cursor off a line containing an
unprocessed ACE implicitly processes the ACE.)

Appendix ACL
Access Control Lists
An access control list (ACL) specifies protection information for an object, such as a
file, directory, device, system logical name table, or global section.

ACL.1

Format of Access Control Entries

An access control entry has the following general format (parentheses and commas
are required).

(type, option, access)
The only portion that is always required is the type field. The option and access fields
may be optional, depending on the type of ACE being specified.
PARAMETERS

type
Indicates the kind of information to be supplied by the access control entry.
Specify type as one of the following (abbreviations are allowed).
ALARM _JOURNAL=name

The name of an alarm journal to which security
alarms are sent. The only name currently allowed
is SECURITY. See the SET AUDIT command
in Appendix DCL and Section 7.2.2.7 for more
information about security auditing.

DEFAULT-PROTECTION

Default file protection information for a directory.
Applicable only to an access control list of a directory
file.

IDENTIFIER=identifier

Access information for an object (file, directory, or
device). Identifier specifies the user(s) to whom the
access information applies.

acl-2

Access Control Lists
Format of Access Control Entries

options
Specifies whether the access control entry is propagated and whether it can be
displayed and/or deleted. Specify option in the following format:

O PTIO N S=key wo rd+...
Specify keyword as one of the following (may be abbreviated).
NONE (default)

No options.

DEFAULT

The access control entry is to be placed in the access control list
of each file subsequently created in the directory. (The DEFAULT
option is not copied with the rest of the access control entry.)
Applicable only to an access control list of a directory file.

HIDDEN

The access control entry can be changed only by the program
that created it. The HIDDEN option can only be specified from a
program. (You cannot specify it using DCL commands.)

PROTECTED

The access control entry is not deleted by explicit (/DELETE)
or implicit (/LIKE) attempts to delete the entire ACL. An access
control entry marked as protected must be explicitly identified to
be deleted (for example, /ACL=(ACE)/DELETE).

NOPROPAGATE

The ACE is not propagated when the ACL is copied from one
version of a file to a later version of the file.

access
Specifies the type of access to be granted. If the access control entry is of
IDENTIFIER type, specify access in the form

ACCESS=keyworck...
Specify keyword as one of the following (may be abbreviated).
NONE
READ
WRITE
EXECUTE
DELETE
CONTROL
You may also specify the keywords SUCCESS and FAILURE with the
ALARM-JOURNAL ACE type.

NONE

No access to the device

READ

The right to allocate and issue read requests to the device

WRITE

The right to issue write requests to the device

CONTROL

The right to change the access control list

SUCCESS

Causes an alarm if access is granted to the device

FAILURE

Causes an alarm if access is denied to the device

When applied to files, access types have the following meanings:
NONE

No access to the file

READ

The right to read the file

WRITE

The right to read and write to the file

EXECUTE

The right to execute the file

DELETE

The right to delete the file

CONTROL

The right to change the file header; this implies that users with CO
access can give themselves any other type of access

SUCCESS

Causes an alarm if access is granted to the file

FAILURE

Causes an alarm if access is denied to the file

When applied to global sections, access types have the following meaning
NONE

No access to the global section

READ

The right to map the section for read access

WRITE

The right to map the section for write access

EXECUTE

The right to map the section for execute access (available only to
privileged software)

CONTROL

The right to change the access control list (applies only to page fr
number (PFN) and page file global sections)

SUCCESS

Causes an alarm if access is granted to the global section

FAILURE

Causes an alarm if access is denied to the global section

acl-4

Access Control Lists
Format of Access Control Entries

When applied to system logical name tables, access types have the following
meanings:
NONE

No access to the logical name table

READ

The right to look up logical names in the table

WRITE

The right to create and delete logical names in the table

DELETE

The right to delete the logical name table

CONTROL

The right to change the access control list

SUCCESS

Causes an alarm if access is granted to the logical name table

FAILURE

Causes an alarm if access is denied to the logical name table

When applied to volumes, access types have the following meanings:
NONE

No access to the volume.

READ

The right to examine, print, or copy files on a volume (READ access on
volumes limits the access to read only)

WRITE

The right to modify or to write existing files on a volume

EXECUTE

The right to create files on the volume and to write into them

DELETE

The right to delete files on the volume

CONTROL

The right to change the protection and ownership of the volume

SUCCESS

Causes an alarm if access is granted to the volume

FAILURE

Causes an alarm if access is denied to the volume

For a DEFAULT-PROTECTION access control entry, specify access in the format

ownership:[access],...
Ownership is the ownership category: SYSTEM, OWNER, GROUP, or WORLD. Each
category may be abbreviated to the first character. Access is the access category: R
(read), W (write), E (execute), or D (delete). To deny access to an ownership category,
omit the access character after the ownership.

ACL.2

EDIT/ACL Command

Use the DCL command EDIT /ACL to invoke the ACL editor.

EDIT/ACL object-spec
Invokes the ACL editor. Enter CTRL/Z to exit from the ACL editor and save your
edits; enter GOLD + CTRL/Z to quit the editing session without saving the edits.

Access Control Lists

acl-5

EDIT/ACL Command

PARAMETERS

object-spec
Specification of the object whose access control list is being edited. Specify a
directory file as a file specification with the file type DIR. The file must be a disk
file on a Files-11 Structure Level 2 formatted volume. No wildcard characters
are allowed.
QUALIFIERS

/JOURNAL[=file-spec] (default)
/NOJOURNAL
Specifies whether or not the ACL editor keeps a journal file during an editing
session and the specification of that journal file. File-spec defaults to the name of
the file being edited and a file type of JOU.

/MODE=option
Specifies whether or not the ACL editor prompts for field values. Specify the
option as PROMPT (default) or NOPROMPT.

/OBJECT=type
Specifies the type of object whose ACL is being edited. Possible types are:
FILE (default)

Specifies that the object is a file.

DEVICE

Specifies that the object is a device.

SYSTEM_GLOBAL _
SECTION

Specifies that the object type is a system global section.

GROUP-GLOBAL -SECTION

Specifies that the object type is a group global section,

LOGICAL _NAME_TABLE

Specifies that the object type is a system logical name
table.

/RECOVER[=file-spec]
/NORECOVER (default)
Specifies whether or not a journal file is executed before the editing session
begins. File-spec defaults to the name of the file being edited and a file type of
JOU.
EXAMPLES
$ EDIT/ACL CHAP.TXT
Invokes the ACL editor to edit the access control list associated with the highest
version of the file CHAP.TXT. If CHAP.TXT does not exist, an error occurs. If
CITAP.TXT has no access control list, one is created when the user enters CTRL/Z.
$ EDIT/RECOVER/ACL CHAP.TXT
Invokes the ACL editor to recover edits made during a previously aborted editing
session.

Invoke the ACL editor (with the EDIT/ACL command) to use the following
commands.

ACL.3.1 Keypad Diagram
Use the keypad to enter keypad commands.

PF2
HELP

PF1

PF3
FNDNXT

PF4
DEL ACE

FIND

UND ACE

GOLD
HELPFMT

7
SEL FIELD

DEL W
UND W

ADV FIELD

4
ADVANCE

5
BACKUP

DEL C

TOP

UND C

BOTTOM

ENTER

EOL

WORD

DEL EOL
ENTER
•

0
OVER ACE

ITEM
INSERT

ZK-1740-84

Access Control Lists

acl-7

ACL Editor Commands

ACL.3.2 Keypad Commands
The diagram above the command description represents the keypad shown in
Section ACL.3.1.
ADVANCE

□□□
□□□
□□□
i in
Sets the cursor direction forward, from top to bottom of the access control list, for the
commands OVER ACE, FIND, FNDNXT, MOVE SCREEN, and WORD, and remains
in effect until you press BACKUP.
ADV FIELD

□□□
□□□
mo
Completes the current ACE field and moves the cursor to the next ACE field,
inserting text as needed.
BACKUP

□□□
□□□
□□□
run
Sets cursor direction backward, from bottom to top of the access control list, for the
commands OVER ACE, FIND, FNDNXT, MOVE SCREEN, and WORD, and remains
in effect until you press ADVANCE.

acl-8

Access Control Lists
ACL Editor Commands

BOTTOM

□□□
□□□
rnn
Moves the cursor to the end, or bottom, of the access control list. If prompting is
enabled, begins the prompting sequence for a new ACE.
DEL ACE

□□□■
□□□
□□□
□□□
mo

Deletes the current ACE (which may be more than 1 line).
DEL C

□□□□
□□□□
□□□■
□□u

Deletes the character the cursor is on.
DEL EOL

□□□
□□□
i in
Deletes the text from the cursor to the end of the line. The deleted text is stored in a
buffer.

Access Control Lists

acl-9

ACL Editor Commands

□□□□
□□□■
□□□□
DEL W

□□□n
nnu

Deletes text up to the first character of the next word.
ENTER

□□□□
□□□□
□□□□
Completes and checks the syntax of the current ACE. The object's ACL is not
modified at this time.
EOL

□□□
□□□
□□□
IHD
Moves the cursor to the end of the current line.
FIELD

□□□
□□□
□□□
rnn
Completes the current ACE field and moves the cursor to the next ACE field or
subfield, inserting text as needed.

ACL-10

Access Control Lists
ACL Editor Commands

FIND

□□□
□□□
□□□
run
Displays the "Search for:" prompt and finds the first occurrence of the character string
that you specify in response. You must terminate the string by pressing ENTER. If
the string is found, the cursor moves to the first character in the string; otherwise,
the cursor remains in place and the message "String was not found" appears.
FNDNXT

□□□
□□□
□□□
mo
Moves the cursor to the first character of the next occurrence of the search string
specified in the FIND command. If there is no further occurrence of the string, the
cursor remains in place and the message "String was not found" appears.
GOLD

□□□
□□□
□□□

non
When pressed before another keypad key, specifies the second key's alternate
function (the bottom function on the keypad diagram).

Access Control Lists

ACL-11

ACL Editor Commands

HELP

□□□
□□□
□□□
□□
Displays a diagram of keypad keys. When one of the keys is pressed after HELP,
information about that key is displayed. Pressing the TAB key after HELP is like
pressing HELP FMT.
HELP FMT

□□□
□□□
□□□
run
Displays the format of an ACE. By pressing the TAB key after HELP FMT, you can
obtain information about each field and its possible values.
INSERT

□□□
□□□
□□□
Inserts a blank line before the current ACE. If prompting is enabled, begins the
prompting sequence for a new ACE.
ITEM

□□□
□□□
□□□
□□□
Selects the next value of the current ACE field.

ACL-12

Access Control Lists
ACL Editor Commands

MOVE SCREEN

□□□
□□□
□□□
□□

Moves the cursor one screen in the current direction (see ADVANCE or BACKUP). A
screen is defined as two-thirds the number of lines in the display.
OVER ACE

□□□
□□□
□□□
□□□

Moves the cursor to the beginning of the next ACE or to the beginning of the
previous ACE.
TOP

□□□
□□□
mo
Moves the cursor to the beginning, or top, of the access control list.
UND ACE

□□□
□□□
□□□
rzo
Inserts, above the current access control entry, the access control entry most recently
deleted with DEL ACE.

Access Control Lists

ACL-13

ACL Editor Commands

UND C

■□□□
□□□□
□□□■

□□u

Inserts to the left of the cursor the character most recently deleted with DEL C or
DELETE.

■□□□
□□□■
□□□□
UND W

□□□n
□□U

Inserts to the left of the cursor the word most recently deleted with DELW or LINE
FEED.
WORD

□□□
□□□
□□□
rnn
Moves the cursor one word in the current direction (see ADVANCE or BACKUP)
within the current line.
Four arrow keys also move the cursor.
•

DOWN ARROW—Moves the cursor to the character in the line below. If the
access control entry in which the cursor is positioned is new, the ACL editor
processes the access control entry before moving the cursor. If the entry is
incomplete or improperly formatted, an error occurs and the cursor remains in
place.

•

LEFT ARROW—Moves the cursor one character to the left. If the cursor is at the
left margin, LEFT ARROW moves the cursor to the rightmost character in the
line above.

ACL-14

Access Control Lists
ACL Editor Commands

•

RIGHT ARROW—Moves the cursor one character to the right. If the cursor is at
the right margin, RIGHT ARROW moves it to the leftmost character in the line
below.

•

UP ARROW—Moves the cursor to the character in the line above it. If the access
control entry in which the cursor is positioned is new, the ACL editor processes
the access control entry before moving the cursor. If the entry is incomplete or
improperly formatted, an error occurs and the cursor remains in place.

You can use the following keyboard keys to supplement the keypad keys. Keys in
parentheses are for a VT100 series terminal.
•

FI2 (BACKSPACE)—Moves the cursor to the beginning of the current line.

•

<E3 (DELETE)—Deletes the character to the left of the cursor.

•

FI3 (LINE FEED)—Deletes the text from the cursor to the beginning of the word.
If cursor is positioned at the first character of the word, deletes to the beginning
of the previous word.

•

TAB (TAB)—Moves the text to the next tab stop.

On the VT200 series terminal, you can also use the following supplemental editing
keypad keys:
•

FIND (HD)—Elicits the Search for: prompt as the first step in the FIND operation.
Type the search string after the prompt and then press either the DO or ENTER
key to process the search. (Performs the same function as the FIND keypad key.)

•

INSERT HERE (HU)—Indicates the line where the selected text in the PASTE
buffer is to be inserted. By default, support for the PASTE buffer is disabled.

•

REMOVE (HU)—Removes the text within the select range to the PASTE buffer.
Each time REMOVE is used, the previous contents of the PASTE buffer are
deleted. By default, support for the PASTE buffer is disabled.

•

COPY (IgoldI [e3] )—Copies the text within the select range to the PASTE buffer.
Each time COPY is used, the previous contents of the PASTE buffer are deleted.
By default, support for the PASTE buffer is disabled.

•

SELECT (HD )—Marks the beginning of a range of text to be removed or copied
to the PASTE buffer. Press SELECT; move the cursor to include the desired
amount of text to be removed or copied; and press either REMOVE (HU) or
COPY (I gold | [e3] ) to complete the operation. By default, support for the PASTE
buffer is disabled.

•

PREV SCREEN (HU )—Moves the cursor one screen in the backward direction.
By default, a screen is defined as two-thirds the number of lines in the display.

Access Control Lists

acl-is

ACL Editor Commands

•

NEXT SCREEN (GOD )—Moves the cursor one screen in the forward direction. By
default, a screen is defined as two-thirds the number of lines in the display.

ACL.3.3 Control Keys
The following control keys also perform editing functions:
•

CTRL/A—Determines whether characters are entered in insert or overstrike
mode. Insert mode (the default) inserts a character to the left of the current
character. Overstrike mode replaces the current character.

•

CTRL/D—Allows you to execute one TPU command.

•

CTRL/H—Moves the cursor to the beginning of the current line.

•

CTRL/J—Deletes the text from the cursor to the beginning of the word. If the
cursor is positioned at the first character of the word, CTRL/J deletes to the
beginning of the previous word.

•

CTRL/U—Deletes the text from the cursor to the beginning of the line.

•

CTRL/W—Refreshes the screen by deleting extraneous characters and restoring
the previous display.

•

CTRL/Z—Terminates the editing session and updates the ACL.

•

GOLD + CTRL/Z—Ignores changes made to the ACL and terminates the editing
session.

ACL.4 DCL Commands That Affect ACLs
Use the following DCL commands to create, modify, or delete a single access control
entry or to manipulate an entire access control list.

SET ACL object
Creates or modifies one or more access control entries (ACEs) in the access control
list (ACL) of the specified object.
PARAMETERS

object
The specification of an object whose access control list is to be modified. Files
must be on Files-11 Structure Level 2 formatted disk volumes. Logical name
tables must be system logical name tables.

acl-16

Access Control Lists
DCL Commands That Affect ACLs

QUALIFIERS

/ACL[=(ace,...)]
Specifies the access control list or entries to be created or modified. Ace specifies
an access control to be inserted at the top of the ACL. If no ACE is specified, the
entire ACL is affected. (Note that security alarm ACEs are always placed at the
beginning of the ACL.)

/AFTER=ace
Places the access control entries specified with the /ACL qualifier after the access
control entry specified with /AFTER. By default, access control entries are added
to the beginning of the access control list. (Note that security alarm ACEs are
always placed at the beginning of the ACL.)

/BEFORE[=time]
Modifies the ACLs of only those files dated before the specified time. You can
specify time as an absolute time, a combination of absolute and delta times, or
one of the following keywords: TODAY (default), TOMORROW, YESTERDAY.
Compatible only with /OBJECT_TYPE=FILE.

/BY__OWNER[=uic]
Modifies only the ACLs of those files with the specified user identification code
(UIC). The default UIC is that of the current process. Compatible only with
/ OBJECT—T YPE=FILE.

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each modification. Compatible only with
/OBJECT_TYPE=FILE. The following responses are valid:
YES

Modify the ACE.

Do not modify the ACE.

TRUE

Modify the ACE.

FALSE

Do not modify the ACE.

Modify the ACE.

Do not modify the ACE.

RETURN

Do not modify the ACE.

ALL

Continue execution of the command with no further confirmation
prompts.

CTRL/Z

Stop execution of the command.

QUIT

Stop execution of the command.

Access Control Lists

acl-17

DCL Commands That Affect ACLs

/CREATED
Modifies the ACLs of files selected according to their creation date. Relevant only
with the /BEFORE and /SINCE qualifiers. Compatible only with
/OBJECT_TYPE=FILE.

/DEFAULT
Creates a new ACL using the default ACEs of the parent (not the default)
directory. For a directory file, the /DEFAULT qualifier propagates the entire
ACL (except for ACEs with the NOPROP AG ATE options) so that a particular
access protection can be propagated throughout a directory tree. For all other
files, the /DEFAULT qualifier propagates the DEFAULT option ACEs in the ACL
of the parent directory to the ACL of the specified files. Compatible only with
/OBJECT_TYPE=FILE.

/DELETE
Deletes the access control entries specified with the /ACL qualifier. If no access
control entry is specified with /ACL, the entire access control list is deleted
(excluding ACEs specified with the PROTECTED option).

/EXCLUDE=(file-spec,...)
Excludes the specified files from the operation. Wildcard characters are allowed.
However, you cannot use relative version numbers to exclude a specific version.
Compatible only with /OB]ECT_TYPE=FILE.

/LIKE=(OBJECT-TYPE=type,OBJECT_NAME=name)
Deletes the access control list of the specified object and replaces it with the
access control list of the object specified with /LIKE. (The source and destination
objects do not have to be the same type for this qualifier.) You can specify the
following keywords for /OBJECT_TYPE: DEVICE, FILE, SYSTEM-GLOBAL _
SECTION, GROUP-GLOBAL-SECTION, or LOGICAL-NAME-TABLE.

/LOG
/NOLOG (default)
Displays the specification of each object whose ACL is modified as the command
executes.

/NEW
Deletes the ACL (except ACEs with the PROTECTED option) of the specified
object and replaces it with the ACL specified with the /ACL or /LIKE qualifier.

/OBJECT—TYPE(=keyword)
Specifies the type of the object whose ACL is being modified. Possible keywords
are: FILE (default), DEVICE, SYSTEM-GLOBAL-SECTION,
GROUP-GLOBAL-SECTION, or LOGICAL-NAME-TABLE.

acl-18

Access Control Lists
DCL Commands That Affect ACLs

/REPLACE=(ace,...)
Deletes the access control entries specified with the /ACL qualifier and replaces
them with the access control entries specified with /REPLACE.

/SINCE[=time]
Modifies only the ACLs of those files dated after the specified time. You can
specify time as an absolute time, a combination of absolute and delta times,
or one of the following keywords: TODAY (default), TOMORROW, and
YESTERDAY. Compatible only with /OBJECT__TYPE=FILE.
EXAMPLES
$ SET ACL/ACL=(IDENTIFIER=[SMITH],ACCESS=CONTROL)

*.FOR

Adds the access control entry specified by /ACL to the beginning of the access
control list of each file with a file type of FOR in the current default directory. (The
/OBJECT_TYPE qualifier defaults to file.)
$ SET ACL/ACL=(IDENTIFIER=NONEXEC,ACCESS=READ)
_$

/REPLACE=(IDENTIFIER=NONEXEC,ACCESS=NONE)-

/OBJECT_TYPE=DEVICE WORKDISK

Changes the access control entry specified by /ACL to the one specified by
/REPLACE in the access control list of the device WORKDISK.

SET DEVICE/ACL [=(ace,...)] device-name,...
Creates or modifies one or more access control entries in the access control lists of
the specified devices.
PARAMETERS

ace
Access control entries (ACEs) to be modified. If no ACE is specified, the entire
access control list (ACL) is affected.

device-name
Specification of devices whose access control lists are being edited; no wildcard
characters are allowed.
QUALIFIERS

Access Control Lists

acl-19

DCL Commands That Affect ACLs

/DELETE
Deletes the access control entries specified with the /ACL qualifier. If no access
control entry is specified with /ACL, the entire access control list is deleted
(except ACEs specified with the PROTECTED option).

/LIKE=device-name
Deletes the access control list of the specified device and replaces it with the
access control list of the file specified with /LIKE. No wildcard characters are
allowed.

/LOG
/NOLOG (default)
Displays the device name of each device whose ACL is modified as the command
executes.

/NEW
Deletes the access control lists (except ACEs with the PROTECTED option) of the
specified devices and replaces them with the access control list specified with the
/ACL or /LIKE qualifier.

/REPLACE=(ace,...)
Deletes the access control entries specified with the /ACL qualifier and replaces
them with the access control entries specified with /REPLACE.
EXAMPLES
$ SET DEVICE/ACL=(IDENTIFIER=[FRED],ACCESS=NONE) WORKDISK
Adds an access control entry specified by /ACL to the beginning of the access control
list of the device WORKDISK.
$ SET DEVICE/ACL/LIKE=$CONSOLE TERMINAL2
Replaces the access control list of TERMINAL2 with the access control list of the
console terminal ($CONSOLE).

SET DIRECTORY/ACL [=(ace,...)] directory-spec,...
Creates or modifies one or more access control entries (ACEs) in the access control
lists (ACLs) of the specified directory.
PARAMETERS

ace
Access control entries (ACEs) to be modified. If no ACE is specified, the entire
access control list (ACL) is affected.

acl-20

Access Control Lists
DCL Commands That Affect ACLs

directory-spec
Specifications of directory whose access control list is being edited. Device name
and colon are optional. Wildcard characters are allowed. Directories must be on
a Files-11 Structure Level 2 formatted disk volume.
QUALIFIERS

/BEFORE[=time]
Modifies only the ACLs of those directories dated before the specified time.
You can specify time as an absolute time, a combination of absolute and delta
times, or one of the following keywords: TODAY (default), TOMORROW,
YESTERDAY.

/BY_OWNER[=uic]
Modifies only the ACLs of those directories with the specified user identification
code (UIC). The default UIC is that of the current process.

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each modification. The following
responses are valid:
YES

Modify the ACE.

Do not modify the ACE.

TRUE

Modify the ACE.

FALSE

Do not modify the ACE.

Modify the ACE.

Do not modify the ACE.

RETURN

Do not modify the ACE.

ALL

Continue execution of the command with no further confirmation
prompts.

CTRL/Z

Stop execution of the command.

QUIT

Stop execution of the command.

/CREATED
Modifies the ACLs of directories selected according to their creation date.
Relevant only with the /BEFORE and /SINCE qualifiers.

Access Control Lists

acl-21

DCL Commands That Affect ACLs

/EXCLUDE=(directory-spec,...)
Excludes the specified directory from the operation. Wildcard characters are
allowed.

/LIKE=directory-spec
Deletes the access control list of the specified directory and replaces it with the
access control list of the directory specified with /LIKE. Wildcard characters are
not allowed.

/LOG
/NOLOG (default)
Displays the specification of each directory modified as the command executes.

/NEW
Deletes the access control list (except ACEs set with the PROTECTED option)
of the specified directory and replaces it with the access control entries specified
with the /ACL qualifier.

/REPLACE=(ace,...)
Deletes the access control entries specified with the /ACL qualifier and replaces
them with the access control entries specified with /REPLACE.

/SINCE[=time]
Modifies only those directories dated after the specified time. You can specify
time as an absolute time, a combination of absolute and delta times, or one of
the following keywords: TODAY (default), TOMORROW, YESTERDAY.
EXAMPLE
$ SET DIRECTORY/ACL/LIKE=[SMITH.PERSONAL] [JONES.PERSONAL]
Replaces the ACL of the directory [JONES.PERSONAL] with the ACL of the directory
[SMITH.PERSONAL].
$ SET DIRECTORY/ACL=(IDENTIFIER=[123,321]+NETW0RK,ACCESS=NONE)
Adds an identifier that permits no network access to the directory for user [123,321].

acl-22

Access Control Lists
DCL Commands That Affect ACLs

SET FILE/ACL [=(ace,...)] file-spec,...
Modifies one or more access control entries (ACEs) in the access control lists (ACLs)
of the specified files.
PARAMETERS

ace
Access control entries (ACEs) to be modified. If no ACE is specified, the entire
access control list (ACL) is affected.

file-spec
Specifications of files whose access control lists are being edited. Wildcard
characters are allowed. Use a comma to separate file specifications. Each file
must be on a Files-11 Structure Level 2 formatted disk volume.
QUALIFIERS

/BEFORE[=time]
Modifies the ACLs of only those files dated before the specified time. You
can specify time as an absolute time, a combination of absolute and delta
times, or one of the following keywords: TODAY (default), TOMORROW, and
YESTERDAY.

/BY_OWNER[=uic]
Modifies the ACLs of only those files with the specified user identification code.
The default UIC is that of the current process.

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each modification. The following
responses are valid:
YES

Modify the ACE.

Do not modify the ACE.

TRUE

Modify the ACE.

FALSE

Do not modify the ACE.

Modify the ACE.

Do not modify the ACE.

Access Control Lists

acl-23

DCL Commands That Affect ACLs

RETURN

Do not modify the ACE.

ALL

Continue execution of the command with no further confirmation
prompts.

CTRL/Z

Stop execution of the command.

QUIT

Stop execution of the command.

/CREATED
Modifies the ACLs of files selected according to their creation date. Relevant only
with the /BEFORE and /SINCE qualifiers.

/DEFAULT
Creates a new ACL using the default ACEs of the parent (not default) directory.
For a directory file, the /DEFAULT qualifier propagates the entire ACL (except
for ACEs with the NOPROP AG ATE option) so that a particular access protection
can be propagated throughout a directory tree. For all other files, the /DEFAULT
qualifier propagates the DEFAULT option ACEs in the ACL of the parent
directory to the ACL of the specified files.

/EXCLUDE=(file-spec,...)
Excludes the specified files from the operation. You can specify a directory name
but not a device name in the file specifications. Wildcard characters are allowed.
However, you cannot use relative version numbers to exclude a specific version.

/LIKE=file-spec
Deletes the access control list of the input files and replaces it with the access
control list of the file specified with /LIKE.

/LOG
/NOLOG (default)
Displays the file specification of each file modified as the command executes.

/NEW
Deletes the access control list of the input file (except those entries set with the
PROTECTED option) and replaces it with the access control list specified with
the /ACL or /LIKE qualifier.

ACL-24

Access Control Lists
DCL Commands That Affect ACLs

/REPLACE=(ace,...)
Deletes the access control entries specified with the /ACL qualifier and replaces
them with the access control entries specified with /REPLACE.

/SINCE[=time]
Modifies only those input files dated after the specified time. You can specify
time as an absolute time, a combination of absolute and delta times, or one of
the following keywords: TODAY (default), TOMORROW, YESTERDAY.
EXAMPLES
$ SET FILE/ACL=(IDENTIFIER=[200,200],ACCESS=R+W+E+D) *.*;*
Adds the access control entry specified by /ACL to the beginning of the access
control list of each file in the current default directory.
$ SET FILE/ACL=(IDENTIFIER=[200,200],ACCESS=R+W+E+D)/EXCLUDE=*.DAT *.*;*
Adds the access control entry specified by /ACL to the beginning of the access
control list of each file in the current default directory, except those files with a file
type of DAT.
$ SET FILE/ACL/LIKE=[USER]PROTO.TXT [USER...]*.*;*
Deletes the access control lists from all files in the [USER] directory tree and replaces
them with the access control list of the file [USERJPROTO.TXT.
$ SET FILE/ACL=(IDENTIFIER=[200,200],ACCESS=R+W+E+D)_$ /REPLACE=(IDENTIFIER=[200,200],ACCESS=N0NE) *.*;*
Changes the access control entry specified by /ACL to the one specified by
/REPLACE in the access control list of each file in the current default directory.
$ SET FILE/ACL=(IDENTIFIER=[200,200],ACCESS=R+W+E+D)/NEW *.*;*
Replaces the access control list of each file in the current default directory with an
access control list containing the access control entry specified by /ACL.

SHOW ACL object-name
Displays the access control list (ACL) of an object.
PARAMETERS

object-name
The name of the object whose ACL is to be displayed. No wildcards are allowed.

Access Control Lists

acl-25

DCL Commands That Affect ACLs

QUALIFIERS

/OBJECT_TYPE=type
Specifies the type of object whose ACL is to be displayed. Possible keywords
are: FILE (the default), DEVICE, SYSTEM_GLOBAL-SECTION, GROUPGLOBAL-SECTION, or LOGICAL-NAME-TABLE.
EXAMPLE
$ SHOW ACL/OBJECT_TYPE=DEVICE TTA1
Displays the ACL of the device TTA1.

Appendix CHAR
Character Sets
The following tables present the ASCII character set and the DEC Multinational
Character Set.

CHAR.1

ASCII Character Set

The ASCII character set consists of the characters shown in the following table.
The characters with names are not printable. (The ASCII character set comprises
the first 127 characters of the DEC Multinational Character Set; descriptions of
the nonprintable characters are located in the table in Section CHAR.3.) You can
calculate the numeric value of a character by constructing a 2-digit hexadecimal
number in which the column position of the character represents the 16s position of
the hexadecimal number and the row position of the character represents the units
position of the number. For example, an uppercase A has the numeric value 41
hexadecimal. String comparisons are made using these values.

CHAR-2

Character Sets
ASCII Character Set

CHAR.2

ASCII and DEC Multinational Character Set Tables

The table below represents the ASCII character set (characters with decimal values 0
through 127). The first half of each of the numbered columns identifies the character
as you would enter it on a VT200 or VT100 series terminal or as you would see it on
a printer (except for the nonprintable characters). The remaining half of each column
identifies the character by the binary value of the byte; the value is stated in three
radixes—octal, decimal, and hexadecimal. For example, the letter uppercase A has,
under ASCII conventions, a storage value of hexadecimal 41 (a bit configuration of
01000001), equivalent to 101 in octal notation and 65 in decimal notation.

110

ACK

SYN

111

BEL
BS

ETB

9
10

110

HT
LF
VT
FF

1110

1111

10
8

30
24

50
40

11
9
9

12
10
A
13
11
B
14
12

SUB

31
25
19
32
26
1A

ESC

C
15

16
14
E
17
15

)

GS
RS
US

29
ID
36
30
IE
37
31
1F

51
41

9
■
•

43
2B
54
44

73
59
3B

•

72
58
3A

71
57
39

56
38

55
37

67
7

28
1C

13
D

(

66
54
36

47
27

CAN

46
&

56
46
2E

76
62
3E

57
47

77
63

•

KEY
CHARACTER

ESC

OCTAL

DECIMAL

HEX

The ASCII character set comprises the first half
Set. The following table represents the second
Character Set (characters with decimal values 12
each of the numbered columns identifies the cha

Character Sets

CHAR-4

ASCII and DEC Multinational Character Set Tables

VT200 series terminal or printer (these characters cannot be output on a VT100
series terminal). Section CHAR.3 describes how to enter symbols from the DEC
Multinational Character Set.

0
0

201
129
81
202
130
82
203
131
83

A
0

324
212
D4

325
213
D5

STS

223
147
93

CCH

224
148
94

244
164
A4

264
180
B4

225
149
95

245
165
A5

265
181
B5

SPA

226
150
96

246
166
A6

266
182
B6

EPA

227
151
97

247
167
A7

■

267
183
B7

c
£

243
163
A3

263
179
B3

ESA
HTS

210
136
88

230
152
98

250
168
A8

HTJ

211
137
89

231
153
99

251
169
A9

VTS

212
138
8A

232
154
9A

252
170
AA

PLD

213
139
8B

233
155
9B

SS3

323
211
D3

PU2

262
178
B2

207
135
87

217
143
8F

322
210
D2

SSA

SS2

\
0

242
162
A2

206
134
86

216
142
8E

321
209
D1

222
146
92

NEL

320
208
DO

205
133
85

215
141
8D

300
192
CO

PU1

IND

PLU

260
176
BO

241
161
A1

CSI

253
171
AB

261
177
B1

301
193
Cl

A
A

302
194
C2

303
195
C3

270
184
B8

304
196
C4

305
197
C5

306
198
C6

307
199
C7

• •

310
200
C8

271
185
B9

311
201
C9

272
186
BA

A
E

312
202
CA

••
E

313
203
CB

314
204
CC

273
187
BB

274
188
BC

275
189
BD

0
• •
0

326
214
D6

327
215
D7

330
216
D8

331
217
D9

332
218
DA

333
219
DB

••

334
220
DC

••
Y

335
221
DD

u
u

234
156
9C

254
172
AC

OSC

235
157
9D

255
173
AD

315
205
CD

236
158
9E

256
174
AE

276
190
BE

A
1

316
206
CE

336
222
DE

APC

237
159
9F

257
175
AF

277
191
BF

••

317
207
CF

337
223
DF

COLUMN

“ b7 BITS

i
i

0
i

221
145
91

0
0

DCS

15
i

220
144
90

204
132
84

214
140
8C

i
1

0
0
240
160
AO

0
200
128
80

11
1

i
i

b6
b5
b4 b3 b2 bl

ROW

*
a

340
224
EO

360
240
FO

341
225
El

361
241

A
a

342
226
E2

\
o

362
242
F2

343
227
E3

w
O

363
243
F3

344
228
E4

A
O

364
244
F4

345
229
E5

365
245
F5

346
230
E6

366
246
F6

110

347
231
E7

367
247
F7

111

350
232
E8

370
248
F8

371
249
F9

372
250
FA

A
U

373
251
FB

374
252
FC

110

375
253
FD

110

376
254
FE

1110

1111

351
233
E9

352
234
EA

353
235
EB

A
r

354
236
EC
355
237
ED

356
238
EE

*1*

357
239
EF

’'MM' 377
255

KEY
CHARACTER

ESC

OCTAL

DECIMAL

HEX
ZK-1753-84

Character Sets

char-5

DEC Multinational Character Set

CHAR.3 DEC Multinational Character Set
The DEC Multinational Character Set is an 8-bit character set with 256 characters; the
first 128 characters in the set correspond to the ASCII character set. Each character
has a value in the range 0 through 255 decimal.
In the following table, the graphic symbols shown in parentheses represent ASCII
control characters. These are produced on most terminals by pressing the key
indicated while holding down the CONTROL key. On VT200 series terminals,
graphic symbols with decimal values greater than 127 can be entered using the
compose sequences. Press the Compose Character key followed by the EDT symbol;
the graphic symbol is then displayed on your terminal. On VT200 series terminals,
you can enter symbols for characters 128 through 255 either in EDT or at DCL level.

On VT100 series terminals, graphic symbols with decimal values greater than 127
can only be entered from screen mode in EDT. Use the EDT keypad command
SPECINS or the nokeypad command ASC to enter these characters in your text;
EDT then displays the EDT symbol that corresponds to the character rather than
displaying the graphic symbol itself.

char-6

Character Sets
DEC Multinational Character Set

Graphic

EDT
Symbol

(&)
(A)
(B)
(C)
(D)
(E)
(F)
(G)
(H)
(I)
(J)
(K)
(L)
(M)
(N)
(0)
(P)

A(a
AA
AB
AC
AD
AE
AF
AG
AH

(Q)

(R)
(S)
(T)
(U)
(V)
(W)
(X)
(Y)
(Z)

AR
AS
Arp

<LF>
< VT>
<FF>
<CR>
AN
A0
AP

([)
(\)

AU
AV
AW
AX
AY
AZ
<ESC >
A\

(])
(A)
(_)

A1
AA
A

1
n

#
$
%
’

#
$
%
&
’

(

Decimal
Value

Abbrev.

Description

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US
SP
i
ii

null character
start of heading
start of text
end of text
end of transmission
enquiry
acknowledge
bell
backspace
horizontal tabulation
line feed
vertical tabulation
form feed
carriage return
shift out
shift in
data link escape
device control 1
device control 2
device control 3
device control 4
negative acknowledge
synchronous idle
end of transmission block
cancel
end of medium
substitute
escape
file separator
group separator
record separator
unit separator
space
exclamation point
quotation marks (double quote)
number sign
dollar sign
percent sign
ampersand

39
40

’

#
$
%
&
(

apostrophe (single quote)
opening parenthesis
ZK-1737/1-84

(Continued on next page)

Graphic

EDT
Symbol

)
*

Decimal
Value

A
B
C
D
E
F
G
H

A
B
C
D
F
G
H

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

I
J
K
L
M
N
O
P

73
74
75
76
77
78
79
80

/
0
1
2
3
4
5
6
7
8
9

■

0
1

2
3
4
5
6
7
8
9
»

Abbrev.

Description

)

closing parenthesis
asterisk
plus
comma
hyphen or minus
period or decimal point
slash
zero
one
two
three
four
five
six
seven
eight
nine
colon
semicolon
less than
equals
greater than
question mark
commercial at
uppercase A
uppercase B
uppercase C
uppercase D
uppercase E
uppercase F
uppercase G
uppercase H

,
-

0
1

2
3
4
5
6
7
8
9

=
>
?
(«

A
B
C
D

E
F
G
H
I
J
K
L
M
N

O
P

uppercase I
uppercase J
uppercase K
uppercase L
uppercase M
uppercase N
uppercase O
uppercase P

ZK-1

(Continued on nex

EDT
Symbol

Decimal
Value

R
S
T
U
V

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

Graphic

]

R
S
T
U
V
W
X
Y
Z
[
\
]

a
b
c
d
e
f

g
h
i

j
k
1
m
n
0

w
X
Y
Z
[
\

k
1
m
n
0
P

q
r

t
u

Abbrev.

Description

uppercase Q
uppercase R
uppercase S
uppercase T
uppercase U
uppercase V
uppercase W
uppercase X
uppercase Y
uppercase Z
opening bracket
back slash
closing bracket
circumflex
underline (underscore)
grave accent
lowercase a
lowercase b
lowercase c
lowercase d
lowercase e
lowercase f
lowercase g
lowercase h
lowercase i
lowercase j
lowercase k
lowercase 1
lowercase m
lowercase n
lowercase o
lowercase p
lowercase q
lowercase r
lowercase s
lowercase t
lowercase u
lowercase v
lowercase w
lowercase x

R
S
T
U
V

w
X
Y
Z
[

\
]
A

a
b
c
d
e
f
g
h
i
j

k
1
m
n

0
P

q
r
s
t
u
V

w
X

ZK-1737/3-84

(Continued on next page)

Graphic

EDT
Symbol

Decimal
Value

y
z

{
1

}
~
DEL

Abbrev.

Description

y
z

}
~

121
122
123
124
125
126

lowercase y
lowercase z
opening brace
vertical line
closing brace
tilde

127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

DEL

{
I
}
~

...
...
...

IND
NEL
SSA
ESA
HTS
HTJ
VTS
PLD
PLU
RI
SS2
SS3
DCS
PU1
PU2
STS
CCH
MW
SPA
EPA
—
...
...

CSI
ST
OSC
PM
APC
...

delete, rubout
I reserved1
1 reserved I
| reserved1
I reserved1
index
next line
start of selected area
end of selected area
horizontal tab set
horizontal tab set with justif
vertical tab set
partial line down
partial line up
reverse index
single shift 2
single shift 3
device control string
private use 1
private use 2
set transmit state
cancel character
message waiting
start of protected area
end of protected area
I reserved1
I reserved]
| reserved]
control sequence introducer
string terminator
operating system command
privacy message
application program comma
I reserved1

(Continued on nex

Graphic

Symbol

Value

Abbrev.

<!!>

161
162

i
<2
£
___

<Y~>

165

<XA6>

166

<so>

§
X
©
a
«

163
164

167

section sign

<xo>

168

general currency sign

<co>

169

X
©

<a_ >
< < < >

170

a
«
...

feminine ordinal indicator

171
172

I reserved 1

...

Ireservedl
I reserved 1
degree sign

...
o

<XB4>
M1]

181

<P!>

•

177

to
>
V

plus/minus sign

178

superscript 2

<3 A >

179

superscript 3

180

...

Ireservedl

182

micro sign
paragraph sign, pilcrow

<.A >

183

•

middle dot

184

—
i

Ireservedl

<o_ >
< > > >

185
186
187

< 14>

188

< 12>
<XBE>

Ireservedl

...

175

angle quotation mark left

<XAF>

<XAE >

176

A
A
A

I reserved1

173
174

<0A>
< + ->

Va
Vz

pound sign
I reserved1
yen sign

inverted exclamation mark
cent sign

¥
—

Description

superscript 1
masculine ordinal indicator

angle quotation mark right
fraction one quarter

189

V4
Vz

190

...

Ireservedl

<??>

191

inverted question mark

< A' >
<A >

192
193
194
195
196
197
198
199
200
201

A
A

uppercase A with grave accent
uppercase A with acute accent
uppercase A with circumflex
uppercase A with tilde
uppercase A with umlaut,(diaeresis)
uppercase A with ring
uppercase AE diphthong
uppercase C with cedilla
uppercase E with grave accent
uppercase E with acute accent

<c,>

E
E

<E>
<E>

A
A
A
A

Q
E
E

fraction one half

ZK-1737/5-84

(Continued on next page)

Graphic

Symbol

Value

Abbrev.

Description

<E~>

202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230

E
E
I
1

uppercase E with circumflex
uppercase E with umlaut, (d
uppercase I with grave acce
uppercase I with acute accen
uppercase I with circumflex
uppercase I with umlaut, (d
I reserved]
uppercase N with tilde
uppercase O with grave acc
uppercase O with acute acce
uppercase O with circumflex
uppercase O with tilde
uppercase O with umlaut, (d
uppercase OE ligature
uppercase O with slash
uppercase U with grave acc
uppercase U with acute acce
uppercase U with circumflex
uppercase U with umlaut, (
uppercase Y with umlaut, (d
I reserved1
German lowercase sharp s
lowercase a with grave acce
lowercase a with acute acce
lowercase a with circumflex
lowercase a with tilde
lowercase a with umlaut, (d
lowercase a with ring
lowercase ae diphthong

i
f

i
I
N
6
6
6
0
0

(E
0

u
u
u
u
Y
13
a
a
a
a
a
o
a
ae

Q
e
e
e
e
i

l
i

i
n

<0>
<0>
<cr>
<0">
<0" >
<OE >

<0/>

<ir>
<ir>
<U" >
< Y" >
<XDE >
<ss>
<a' >
<a >
<a >
<a~>
<a" >
<a*>
<ae>
<c,>
<e >
<e >
<e >
<e" >

<i'>

231
232
233
234
235
236
237
238
239
240
241
242

i
i
---

N
6
6
6

o
0

(E
0

u
u
u
u
Y
...

13
a
a
a

a
a
a
ae

Q
e
e
e
e
i

l
i

i
...

lowercase c with cedilla
lowercase e with grave acce
lowercase e with acute acce
lowercase e with circumflex
lowercase e with umlaut, (d
lowercase i with grave acce
lowercase i with acute accen
lowercase i with circumflex
lowercase i with umlaut, (d
[reserved]
lowercase n with tilde
lowercase o with grave acce

ZK-17

(Continued on next

Graphic

Symbol

Value

Abbrev.

Description

6
6
6
6
oe
0
u
u
u
ii

6
6
6
6
oe
0
u
u
u
ii

<y»» >

243
244
245
246
247
248
249
250
251
252
253
254
255

lowercase o with acute accent
lowercase o with circumflex
lowercase o with tilde
lowercase o with umlaut, (diaeresis)
lowercase oe ligature
lowercase o with slash
lowercase u with grave accent
lowercase u with acute accent
lowercase u with circumflex
lowercase u with umlaut, (diaeresis)
lowercase y with umlaut, (diaeresis)
[reservedl
[reserved]

...
...

ZK-1737/7-84

Appendix DCL
DCL Commands
The DCL commands that follow are in alphabetical order. The headline for each
command includes the name of the command and the command parameters in their
required order. Bracketed parameters are optional.
A comma followed by an ellipsis indicates that you can enter a list containing
any number of the preceding item. Most list items must be separated by commas,
but some (noted in the documentation) items may be connected by plus signs.
Lists of more than one qualifier value must be in parentheses. You can omit the
parentheses if the list contains only one value. (The documentation always shows
the parentheses.)
Qualifiers are listed in alphabetical order. Qualifiers are global unless otherwise
stated. Explanations of positive/negative qualifiers apply to the positive qualifier
unless otherwise stated.

ACCOUNTING [file-spec,...]
Requires READ access to the input accounting file.
Collects, records, and reports accounting data.
PARAMETERS

file-spec
Specification of the input accounting file. Wildcard characters are allowed. The
default is SYS$MANAGER:ACCOUNTNG.DAT.
QUALIFIERS

/ACCOUNT=([“-”,]account-name,...)
/NOACCOUNT (default)
Selects only those records matching the specified account names (in the user
authorization file) if the first item in the list is not a hyphen enclosed in quotation
marks ("-"). If a hyphen enclosed in quotation marks is the first item, excludes
those records matching the specified account names.

dcl-2

DCL Commands
ACCOUNTING

/ADDRESS=([“-”,]node-address,...)
/NOADDRESS (default)
Selects only those records matching the specified remote node addresses if the
first item in the list is not a hyphen enclosed in quotation marks ("-")• If a
hyphen enclosed in quotation marks is the first item, excludes those records
matching the specified node addresses.
/BEFORE[=time]
/NOBEFORE (default)
Selects only those records created or modified before the specified time. You
can specify time as absolute or a combination of absolute and delta times. The
default is the current time.
/BINARY
/NOBINARY (default)
Generates an output file that contains image copies of the input records. By
default, the output file contains formatted ASCII records. Incompatible with the
/BRIEF, /FULL, and /SUMMARY qualifiers.
/BRIEF (default)
/NOBRIEF
Generates an output file that contains formatted displays of selected items in
the input records as listed below. Incompatible with the /BINARY, /FULL, and
/SUMMARY qualifiers.
DATE

Date in the format yyyy mmm dd

DAY

Day of the month (1-31)

HOUR

Hour of the day (0-23)

YEAR

Year

TYPE

Type of record (for example, process or print)

SUBTYPE

Type of process (for example, batch or interactive)

/ENTRY=([“-”,]queue-entry-number,...)
/NOENTRY (default)
Selects only those records matching the specified queue entry numbers if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching the
specified queue entry numbers.
/FULL
/NOFULL (default)
Generates an output file that contains formatted displays of all the information
in the input records. Incompatible with the /BINARY, /BRIEF, and /SUMMARY
qualifiers.

DCL Commands

DCL-3

ACCOUNTING

/IDENTIFICATION^"-”,]process-id,...)
/NOIDENTIFICATION (default)
Selects only those records matching the specified process identifications if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching the
specified process identifications.

/IMAGE=([“-”,]image-name,...)
/NOIMAGE (default)
Selects only those records matching the specified image file names if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching the
specified image file names.

/JOB=([“-”,]job-name,...)
/NOJOB (default)
Selects only those records matching the specified job names if the first item in
the list is not a hyphen enclosed in quotation marks
If a hyphen enclosed
in quotation marks is the first item, excludes those records matching the specified
job names.

/LOG
/NOLOG (default)
Displays input file names, selected record counts, and rejected record counts on
SYSSOUTPUT as the command executes.

/NODE=([“-’\]node-name,...)
/NONODE (default)
Selects only those records matching the specified remote node names if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching the
specified remote node names. Do not specify a colon (:) in the node name.

/OUTPUT[=file-spec]
/NOOUTPUT
Writes the accounting information to the specified file. By default, the output is
written to SYS$OUTPUT. The file name defaults to that of the input file. The file
type defaults to LIS for formatted files and DAT for binary files.

/OWNER=([“-”,]owner-process-id,».)
/NOOWNER (default)
Selects only those records matching the specified owner process identification
if the first item in the list is not a hyphen enclosed in quotation marks
If
a hyphen enclosed in quotation marks is the first item, excludes those records
matching the specified owner process identifications.

dcl-4

DCL Commands
ACCOUNTING

/PRIORITY=([“-”,]priority,...)
/NOPRIORITY (default)
Selects only those records matching the specified priorities if the first item in the
list is not a hyphen enclosed in quotation marks
If a hyphen enclosed in
quotation marks is the first item, excludes those records matching the specified
priorities.

/PROCESS=([“-”,]process-type,„.)
/NOPROCESS (default)
Selects only those records matching the specified process types if the first item in
the list is not a hyphen enclosed in quotation marks
If a hyphen enclosed
in quotation marks is the first item, excludes those records matching the specified
process types. Possible process-types are: BATCH, DETACHED, INTERACTIVE,
NETWORK, and SUBPROCESS.

/QUEUE=([“-”,]queue-name,...)
/NOQUEUE (default)
Selects only those records matching the specified queue names if the first item in
the list is not a hyphen enclosed in quotation marks
If a hyphen enclosed
in quotation marks is the first item, excludes those records matching the specified
queue names.

/REJECTED[=file-spec]
/NOREJECTED (default)
Writes rejected records (in binary format) to the specified file. The file name
defaults to that of the input file. The file type defaults to REJ.

/REMOTE_ID=([“-”,]remote-id,.„)
/NOREMOTE_ID (default)
Selects only those records matching the specified remote identifications if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching the
specified remote identifications.

/REPORT[=report-item,...]
/NOREPORT (default)
Includes specified items in a summary report; requires the /SUMMARY qualifier.
Specify report-item as:
BUFFERED—IO

Total buffered I/Os

DIRECT_IO

Total direct I/Os

ELAPSED

Total elapsed time

EXECUTION

Total images executed

FAULTS

Total page faults

GETS

Total RMS GETs

PAGE _FILE

Maximum page file usage

PAGE-READS

Total page read I/Os

PAGES

Total pages printed

PROCESSOR

Total processor time consumed

QIOS

Total QIOs issued

RECORDS

Total records in file (default)

VOLUMES

Total volumes mounted

WORKING-SET

Maximum working set size

/SINCE[=time]
/NOSINCE (default)

Selects only those accounting records dated after the specified time. You c
specify time as absolute or a combination of absolute and delta times. The
defaults to midnight of the current day.

/SORT=([-]sort-item,...)
/NOSORT (default)

Sequences the accounting records in the output file. By default, the sequen
is the same as that of the input file. You can sequence records according to
ASCII values of any of the following fields in the order specified. The field
sorted in ascending order unless preceded by a hyphen. Rejected records a
not included in the sort. A record that does not contain a specified key fiel
rejected. Incompatible with /SUMMARY. Specify sort-item as:
ACCOUNT

User's account name

ADDRESS

Remote node address

BUFFERED—IO

Buffered I/O count

DIRECT—IO

Direct I/O count

ELAPSED

Elapsed time

ENTRY

Number of batch or print job queue entry

EXECUTION

Image execution count

FAULTS

Page faults

FINISHED

Termination time or time record was finished

GETS

Total RMS GETS

IDENT

Process identification

IMAGE

Image name

dcl-6

DCL Commands
ACCOUNTING

Name of batch or print job

JOB
NODE

Remote node name

OWNER

Owner process identification

PAGE _FILE

Peak page file usage

PAGE-READS

Page read I/Os

PAGES

Total pages printed

PRIORITY

Process priority

PROCESS

Process type

PROCESSOR

Processor time consumed

QUEUE

Name of queue

QUEUED

Time batch or print job was queued

QIOS

Total QIOs issued

STARTED

Start time

STATUS

Exit status

TERMINAL

Terminal name

TYPE

Record type

UIC

User identification code

USER

User's name

VOLUMES

Total volumes mounted

WORKING-SET

Peak working set size

/STATUS=([“-”,]exit-status,...)
/NOSTATUS (default)
Selects only those records matching the specified exit states if the first item in the
list is not a hyphen enclosed in quotation marks
If a hyphen enclosed in
quotation marks is the first item, excludes those records matching the specified
exit states.
/SUMMARY=(summary-item,...)
/NOSUMMARY (default)
Generates an output file that contains formatted displays of selected items in the
input records as listed below. Incompatible with the /BINARY, /BRIEF, /FULL,
and /SORT qualifiers. Specify summary-item as:
ACCOUNT

Account name from the UAF

DATE

Date in the format yyyy mmm dd

DAY

Day of the month (1-31)

HOUR

Hour of the day (0-23)

DCL Commands

DCL-7

ACCOUNTING

IMAGE

Image name

JOB

Name of batch job or print job

MONTH

Month of year (1-12)

NODE

Remote node name

PROCESS

Process type

QUEUE

Batch or device queue name

TERMINAL

Terminal name

TYPE

Type of record (for example, logout or batch)

RMINAL=([“--”,]terminal-name,...)
/NOTERMINAL (default)
Selects only those records matching the specified terminal names if the first
item in the list is not a hyphen enclosed in quotation marks
If a hyphen
enclosed in quotation marks is the first item, excludes those records matching
the specified terminal names. Specify the physical device name of the terminal
including the colon.

/TITLE=title
/NOTITLE (default)
Specifies a title to be printed in the center of the first line of a summary report.
If the title contains spaces or special characters, enclose it in quotation marks.

/TYPE=([“-”,]record-type,...)
/NOTYPE (default)
Selects only those records matching the specified record types if the first item in
the list is not a hyphen enclosed in quotation marks
If a hyphen enclosed
in quotation marks is the first item, excludes those records matching the specified
record types. Possible record-types are:
FILE

Accounting file forward and backward pointers

IMAGE

Termination of image

LOGFAIL

Unsuccessful conclusion of a login attempt

Termination of a print job

PROCESS

Termination of process

SYSINIT

System initialization

UNKNOWN

Any record not recognized as one of the above

USER

Arbitrary user messages

/UIC=([“-”,]uic,...)
/NOUIC (default)
Selects only those records matching the specified UIC if the first item in the
list is not a hyphen enclosed in quotation marks
If a hyphen enclosed in

dcl-8

DCL Commands
ACCOUNTING

quotation marks is the first item, excludes those records matching the specified
UIC. Wildcard characters can be used in both the group and member fields of the
UIC.

/USER=([“-”,]username,...)
/NOUSER (default)
Selects only those records matching the specified user names if the first item in
the list is not a hyphen enclosed in quotation marks
If a hyphen enclosed
in quotation marks is the first item, excludes those records matching the specified
user names.

ALLOCATE device-name[:],... [logical-name]
Provides your process with exclusive access to a device until you deallocate the
device or terminate your process. Optionally associates a logical name with the
device.
PARAMETERS

device-name
Name of a physical device or a logical name that translates to the name of a
physical device. The device name can be generic: if no controller or unit number
is specified, any device that satisfies the specified part of the name is allocated. If
more than one device is specified, the first available device is allocated.

logical-name
A character string of 1 through 255 characters. Enclose the string in quotation
marks (") if it contains blanks. Trailing colons are not used. The name becomes a
process logical name with the device name as the equivalence name. The logical
name remains defined until it is explicitly deleted or your process terminates.
QUALIFIERS

/GENERIC
/NOGENERIC (default)
Indicates that the first parameter is a device type rather than a device name.
Example device types are: RX50, RD52, TK50, RC25, RCF25, RL02.

/LOG (default)
/NOLOG
Displays a message indicating the name of the device allocated. If the operation
specifies a logical name that is currently assigned to another device, displays the
superseded value.

DCL Commands

dcl-9

APPEND

APPEND input-file-spec,... output-file-spec
Adds the contents of the specified input files to the end of the specified output file.
PARAMETERS

input-file-spec
The specification of the input files. Multiple input files are appended to the
output file in the order specified; separate file specifications with commas or plus
signs. Wildcard characters are allowed.

output-file-spec
A valid file specification. You must specify at least one field of the file
specification. Device and directory default to your current default device and
directory. Other fields default to the corresponding field of the first input file
specification.
QUALIFIERS

/ALLOCATION=number-of-blocks
Qualifies output-file-spec.
Forces the initial allocation of the output file to the specified number of 512-byte
blocks. If you do not specify the /ALLOCATION qualifier, the initial allocation
of the output file is determined by the size of the input file. Relevant only with
the /NEW—VERSION qualifier.

/BACKUP
/CREATED (default)
/EXPIRED
/MODIFIED
Selects files for the append operation according to the dates of their most recent
backups, their creation dates, their expiration dates, or the dates of their last
modifications. Relevant only with the /BEFORE and /SINCE qualifiers.

/BEFORE[=time]
Selects for the append operation only those files dated before the specified time.
You can specify time as an absolute time, as a combination of absolute and delta
times, or as one of the following keywords: TODAY (default), TOMORROW,
or YESTERDAY. Specified with /BACKUP, /CREATED (default), /EXPIRED, or
/MODIFIED.

/BY_OWNER[=uic]
Selects for the append operation only those files with the specified user
identification code. The default user identification code is that of the current
process.

dcl-10

DCL Commands
APPEND

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each append operation. The following
responses are valid:
YES

Perform the append operation

Do not perform the append operation

TRUE

Perform the append operation

FALSE

Do not perform the append operation

Perform the append operation

Do not perform the append operation

RETURN

Do not perform the append operation

ALL

Continue execution of the command with no further confirmation
prompts

CTRL/Z

Stop execution of the command

QUIT

Stop execution of the command

/CONTIGUOUS
/NOCONTIGUOUS
Qualifies output-file-spec.
Specifies that the output file must occupy physically contiguous disk blocks. By
default, the APPEND command creates an output file in the same format as the
corresponding input file and does not report an error if not enough space exists
for a contiguous allocation.

/CREATED
See /BACKUP.

/EXCLUDE=(file-spec,...)
Omits the specified files from the append operation. You can include a directory
but not a device in the file specifications. Wildcard characters are supported for
file specifications. However, you cannot use relative version numbers to exclude
a specific version.

/EXPIRED
See /BACKUP.

/EXTENSIONS
Qualifies output-file-spec.
Sets the extend quantity default for the output file. Relevant only with the
/NEW_VERSION qualifier.

DCL Commands

dcl-ii

append

/LOG
/NOLOG (default)
Displays file specifications of input and output files as well as the number of
blocks or records appended after each append operation. Displays the number of
new files created after the entire append operation.

/MODIFIED
See /BACKUP.

/NEW-VERSION
/NONEW—VERSION (default)

Qualifies output-file-spec.
Creates a new output file if the specified output file does not exist. If the output
file does exist, the /NEW_VERSION qualifier appends the input file to the output
file.

/PROTECTION=(ownership[:access],...)

Qualifies output-file-spec.
Specifies protection for the output file. Specify ownership as SYSTEM, OWNER,
GROUP, or WORLD and access as R, W, E, or D. The default protection is that
of the existing output file; if no output file exists, the current default protection
applies.

/READ—CHECK
/NOREAD-CHECK (default)

Qualifies input-file-spec.
Reads each record in the input files twice to verify that it has been read correctly.

/SINCE[=time]
Selects for the append operation only those files dated after the specified time.
You can specify time as an absolute time, a combination of absolute and delta
times, or as one of the following keywords: TODAY (default), TOMORROW,
or YESTERDAY. Specified with /BACKUP, /CREATED (default), /EXPIRED, or
/MODIFIED.

/WRITE-CHECK
/NOWRITE-CHECK (default)

Qualifies output-file-spec.
Reads each record in the output file after the record is written to verify that it is
written correctly.

dcl-12

DCL Commands
ASSIGN

ASSIGN equivalence-name,... logical-name
Associates equivalence names with a logical name. If you specify an existing logical
name, the new equivalence names replace the existing equivalence names.
PARAMETERS

equivalence-name
A character string of 1 to 255 characters. If the string contains other than
uppercase alphanumeric, dollar sign, or underscore characters, enclose it in
quotation marks ("). Use double quotation marks ("") to denote an actual
quotation mark. Specifying more than one equivalence name for a logical
name creates a search list.

logical-name
A character string of 1 to 255 characters. If the string contains other than upper
case alphanumeric, dollar sign, or underscore characters, enclose it in quotation
marks ("). Use double quotation marks ("") to denote an actual quotation mark.
If you terminate logical-name with a colon, the system removes the colon. If
the logical name is to be entered into the process or system directory logical
name tables, then the name may only have from 1 to 31 alphanumeric characters
(including the dollar sign and underscore).
QUALIFIERS

/EXECUTIVE-MODE
/SUPERVISOR-MODE (default)
/USER—MODE
Requires SYSNAM privilege for executive mode.
Specifies the mode of the logical name. If you specify executive mode, but do not
have SYSNAM privilege, a supervisor mode logical name is created. The mode
of the logical name must be the same as or external to (less privileged than) the
mode of the table in which you are placing the name. If you specify a user mode
logical name in the process logical name table, that logical name is used for the
execution of a single image only; user mode entries are deleted from the logical
name table when any image executing in the process exits; that is, after any DCL
command or user program that executes an image completes execution.

/GROUP
/JOB
/PROCESS (default)
/SYSTEM
Require SYSPRV or GRPNAM privilege for group logical names.
Require SYSNAM or SYSPRV privilege for system logical names.
Specifies the table in which the logical name is to be placed. The /GROUP
qualifier is synonymous with /TABLE=LNM$GROUP. The /JOB qualifier is
synonymous with /TABLE=LNM$JOB. The /PROCESS qualifier is synonymous

DCL Commands

dcl-13

ASSIGN

with /TABLE=LNM$PROCESS. The /SYSTEM qualifier is synonymous with
/TABLE=LNM$SYSTEM.

/LOG (default)
/NOLOG
Displays a message when a new logical name supersedes an existing name.

/NAME_ATTRIBUTES[=(keyword,...)]
Specifies the attributes for a logical name. (By default, no attributes are set. You
can specify the following keywords for attributes:
CONFINE

Does not copy the logical name into a spawned subprocess; Relevant

NO_ALIAS

Prohibits creation of logical names with the same name in an outer (less

only for logical names in a private table.

privileged) access mode within the specified table; deletes any previously
created identical names in an outer access mode within the specified
table.

/PROCESS
See /GROUP.

/SUPERVISOR-MODE
See /EXECUTIVE—MODE.

/SYSTEM
See /GROUP.

/T ABLE=name
Requires WRITE access to the table if the table is shareable.
Specifies the name of the logical name table in which the logical name is to be
entered. You can specify user-defined tables (created with the
CREATE/NAME—TABLE command), the process, group, job, or system logical
name table, or the process or system logical name directory table. The default
is LNM$PROCESS. If you specify a table name that translates to more than one
table, the logical name is placed in the first table found.

/TRANSLATION—ATTRIBUTES[=(keyword,...)]
Qualifies each equivalence-name.
Specifies attributes of the equivalence-name. Possible keywords are:

dcl-14

DCL Commands
ASSIGN

CONCEALED

Indicates that the equivalence string is the name of a concealed device

TERMINAL

Terminates logical name translation after iterative translation of this
equivalence string

/USER_MODE
See /EXECUTIVE_MODE.

ASSIGN/MERGE merge-queue-name source-queue-name
Requires OPER privilege or EXECUTE access to both queues.
Removes all jobs from one queue and merges them into another existing queue.
Does not affect jobs that are executing.
PARAMETERS

merge-queue-name
Name of the queue into which the jobs are being merged.

source-queue-name
Name of the queue from which the jobs are being removed.

ASSIGN/QUEUE execution-queue-name[:] logical-queue-name[:]
Requires OPER privilege or EXECUTE access to both queues.
Assigns, or redirects, a logical queue to a single execution queue.
PARAMETERS

execution-queue-name[:]
Name of the execution queue. The queue cannot be a logical, generic, or batch
queue.

logical-queue-name[:]
Name of the logical queue.

ATTACH [process-name]
Transfers control from your current process (which then hibernates) to the specified
process.

DCL Commands

dcl-15

ATTACH

PARAMETERS

process-name
The name of a parent process or spawned subprocess to which control passes.
The process must already exist, must be part of your current job, and must
share the same input stream as your current process, but cannot be your current
process or a subprocess created with the /NOWAIT qualifier. Incompatible with
the /IDENTIFICATION qualifier.
QUALIFIERS

/IDENTIFICATION=pid
Specifies the process identification (PID) of the process to which terminal control
will be transferred. Leading zeros can be omitted. Incompatible with the
process-name parameter.

BACKUP input-file-spec,... [output-file-spec,...]
Copies files, saves files on save sets, restores files from save sets, lists files on save
sets, and compares files with other files or save sets.
PARAMETERS

input-file-spec
Specification of a file to be copied or saved, or a save set to be restored. Wildcard
characters are allowed in the specifications of regular files, and in those of
save-set files on magnetic tape. DECnet node names are allowed only in save-set
file specifications.

output-file-spec
Specification of a file to be created by a copy or restore operation, or a save set
to be created by a save operation. Wildcard characters are allowed for normal
files. No wildcard characters are allowed for save sets. DECnet node names are
allowed only in save-set file specifications.
QUALIFIERS

/BACKUP
/CREATED
/EXPIRED
/MODIFIED (default)
Qualifies input files.
Selects files for the backup operation according to the dates of their most recent
backups, their creation dates, their expiration dates, or the dates of their last
modifications. Relevant only with the /BEFORE and /SINCE qualifers.

dcl-16

DCL Commands
BACKUP

/BEFORE=time
Qualifies input files.
Processes only those files dated earlier than the specified time, which can be an
absolute time or one of the following keywords:
BACKUP

The date recorded by a previous BACKUP/RECORD; available only on
Files-11 Structure Level 2 volumes

TODAY

The current day at 0 hours

TOMORROW

TODAY plus 24 hours

YESTERDAY

TODAY minus 24 hours

/BLOCK—SIZE=number-of-bytes
Qualifies output save sets.
Defines the block size, in bytes, for data records in a BACKUP save set. The
acceptable range for n is 2048 through 65,534. If you do not specify this qualifier,
the default blocking size for a disk save set is 32,528 bytes; for a magnetic tape
save set, 8464 bytes.

/BRIEF (default)
/FULL
Lists a brief amount of information on each file saved or restored (specification,
size, and creation date), or lists the information in the format of the DIRECTORY
/FULL command. Relevant only when the /LIST qualifier is also specified.

/BUFFER_COUNT=number-of-buffers
Specifies the number of I/O buffers to be used in the backup operation. The
maximum value is 5; the default is 3. Relevant with both disks and magnetic
tape.

/COMMENT=string
Qualifies output save sets.
Places the comment in the save set. The comment is displayed in list operations.
If the comment contains spaces or special characters, enclose it in quotation
marks

/COMPARE
Compares two files, two groups of files, or a save set and a file or group of
files. In the latter case, the save set must be specified as the first parameter. The
default version number is *, which processes all versions of the file.

/CONFIRM
Qualifies input files.
For each file being copied or saved, displays a query to which you must respond
Y to copy the file — any other response skips the copy or save operation for that
file.

DCL Commands

DCL-17

BACKUP

/CRC (default)
/NOCRC
Qualifies input and output save sets.
Performs the Cyclic Redundancy Check on save-set data.

/CREATED
See /BACKUP.

/DELETE
Deletes input files after they are saved.

/DENSITY=n
The /DENSITY qualifier is not applicable to the TK50 tape device.
Specifies the density at which a magnetic tape save set is recorded. Use a
value that is supported by the magnetic tape drive. If you do not specify the
/DENSITY qualifier, the default density is the current density of the magnetic
tape drive.

/EXCLUDE=(file-spec,...)
Qualifies input files.
Excludes the specified files from the copy or save operation. Wildcard characters
are supported for file specification. However, you cannot use relative version
numbers to exclude a specific version. No device names are allowed.

/EXPIRED
See /BACKUP.

/FAST
Requires WRITE access to [0,0]INDEX.SYS on the volume containing the files
being saved, or the volume must be write-locked.
Uses a fast file scan. The /FAST qualifier is ignored if used with the /IMAGE
qualifier.

/FULL
See /BRIEF.

/GROUP_SIZE=number-of-blocks
Qualifies output save sets.
Defines the number of blocks to be placed in each redundancy group. Using the
redundant information, one "uncorrectable" read error in each redundancy group
can be corrected. The value must be from 0 through 100; the default is 10; 0
means no redundancy blocks are written.

dcl-18

DCL Commands
BACKUP

/IGNORE=keyword
Overrides restrictions placed on files. Possible keywords are:
INTERLOCK

Processes files that otherwise could not be processed because of file
access conflicts (specifically, files currently open for writing); requires
SYSPRV privilege

NOBACKUP

Saves or copies the contents of files that are marked with the
/NOBACKUP qualifier of the SET FILE command

/IMAGE
Requires WRITE access to [0,0]INDEXF.SYS and [0,0]BITMAP.SYS on the
volume being processed, or the volume must be write-locked.
Copies, saves, or restores an entire volume. The output volume must be mounted
/FOREIGN. The file specification parameters must consist only of the disk
names. In save and copy operations, other file specification qualifiers are not
allowed.

/INCREMENTAL
Restores an incremental save set to a disk volume. The output file specification
must consist only of the device name. The /INCREMENTAL qualifier assumes
/OWNER_UIC=ORIGINAL, and can be used only on Files-11 Structure Level 2
volumes.

/INITIALIZE (default for /IMAGE)
/NOINITIALIZE (default for sequential disk volumes)
Initializes the output volume (in an image copy or a save operation). An image
copy operation uses the volume initialization data on the input volume. Any
existing data on the output volume is lost.

/INTERCHANGE
Do not use except where explicitly instructed.
Does not copy access control lists or directories not selected as files. Block size
on magnetic tape is limited to 8192 bytes. Magnetic tapes are written using
normal error recovery to eliminate bad records on the resulting magnetic tape.

/JOURNAL[=file-spec]
Maintains a record of save sets, times of creation, and contents. When
/JOURNAL is specified during a save operation, information concerning the
operation is appended to the specified file. A new file is created if the specified
file does not exist. The file specification defaults to SYS$DISK:BACKUP.BJL.
Used with /LIST, the /JOURNAL qualifier displays the contents of the journal.
The /BEFORE and /SINCE qualifiers, when used with /JOURNAL /LIST, refer
to the time at which the save set (not saved files) was created.

DCL Commands

DCL-19

BACKUP

/LABEL=(label,...)
Qualifies output-file-specs.
Specifies the volume label for a save set written on magnetic tape or sequential
disk. For save sets written on tape, you must use a string of 1 to 6 alphanumeric
characters. For save sets written on sequential disk volumes, the string must be 1
to 12 alphanumeric characters.
If you do not specify the /LABEL qualifier, label will be derived from the save-set
name. In a multivolume disk save set, the volume set name will be the save-set
name. The label of each volume in the volume set will be the label string or the
label string derived from the save-set name and followed by a two-digit volume
number, starting with 01.
If you specify a list of labels, BACKUP will label save-set volume n with label n
in the list of labels. If the list of labels is shorter than the number of volumes in
the save set, BACKUP will generate labels for the remaining volumes using the
first label in the list followed by a two-digit relative volume number. Note that
for magnetic tape save sets, the volumes are counted, starting (at 01) with the
tape on which the current save set started. Magnetic tape volume numbers are
not maintained across multiple save sets written on multiple magnetic tapes.

/LIST[=file-spec]
Lists information on the contents of a save set. The listing is written to file-spec,
which defaults to SYS$OUTPUT. This qualifier can stand alone, in which case
the first and only parameter must be the name of the save set; or the qualifier
can be part of a save or restore operation, in which case the listing reflects the
status of the save set after completion of the operation. Do not use /LOG with
/LIST when the output is directed to SYS$OUTPUT.

/LOG
/NOLOG (default)
Displays on SYS$OUTPUT the name of each file as it is processed.

/MODIFIED (default)
See /BACKUP.

/NEW—VERSION
Qualifies output-file-specs.
Creates a new version of a file if you attempt to restore or copy a file to a
directory that has a file of the same name and version number. Files are
processed in decreasing version-number order and created in ascending order, so
that version numbers are inverted. Results are unpredictable if /NEW_VERSION
is used with /COMPARE or /VERIFY.

/OVERLAY
Qualifies output-file-specs.
Overlays the existing named file rather than allocating new space for the file.

dcl-20

DCL Commands
BACKUP

/OWNER_UIC=[uic]
Positional qualifier.
Requires SYSPRV privilege or ownership of the UIC to specify with an output
file or save set.
As an input file qualifier — Processes only files owned by the specified UIC. A
specification of /OWNER_UIC without a value means your process UIC.
As an output file qualifier — Resets the ownership of the copied or restored file.
You can specify a UIC or one of the following keywords:
DEFAULT

Your process UIC

ORIGINAL

Existing UIC of the saved file

PARENT

The UIC of the directory under which the file is being restored

If no /OWNER_UIC is specified, then it is the same as specifying
/OWNER_UIC=DEFAULT. A /OWNER_UIC specification without a value
means ORIGINAL.
As an output save-set qualifier — Specifies ownership of the save set. The
default is your process UIC.

/PHYSICAL
Ignores any file structure on the volume. Output disks must be the same type
as input disks; output disks cannot have a bad block where input disks do
not. A save set written using /PHYSICAL can only be read as a physical save
set. Output disks must have been mounted /FOREIGN; input disks must have
been mounted /FOREIGN or the user must have LOG_IO privilege. The file
specification for a physical volume can contain only a device name. Note that
this should only be used on input and output disks proven to have no bad
blocks.

/PROTECTION[=(ownership[:access],„.)
Qualifies output save sets.
Specifies protection for a save set. Specify ownership as SYSTEM, OWNER,
GROUP, or WORLD. Specify access as R, W, E, or D. Default protection is that
of the current process.

/RECORD
Requires ownership of the file or SYSPRV privilege.
Records in the file header the backup date for each file processed. Valid only for
Files-11 Structure Level 2 volumes.

/REPLACE
Qualifies output files.
Deletes the existing output file and creates a new file if you attempt to restore or
copy a file to a directory that has a file of the same name and version number.

DCL Commands

dcl-21

BACKUP

/REWIND
/NOREWIND (default)
Causes the tape reel to be rewound (/REWIND) or not rewound (/NOREWIND)
to beginning-of-tape (BOT) before BACKUP searches for the save-set name
specified in the input specifier. Use this qualifier only for magnetic tape save
sets.

/SAVE—SET
Qualifies input and output save sets.
Identifies the file specification as a save set, not a normal file. This qualifier is
required for save sets on disk.

/SELECT=(file-spec,...)
Qualifies input save sets.
Restores only the specified files. Wildcard characters are allowed. No device
names are allowed.

/SINCE=time
Qualifies input files.
Selects only those those files dated after the specified time. You can specify time
as an absolute time or as one of the following keywords:
BACKUP

The date recorded by a previous BACKUP/RECORD

TODAY

The current day at 0 hours

TOMORROW

TODAY plus 24 hours

YESTERDAY

TODAY minus 24 hours

/TRUNCATE
/NOTRUNCATE (default)
Truncates a sequential output file at end-of-file when creating it during a copy or
restore operation. By default, a copy or restore operation uses the allocation of
the input file to determine the size of the output file.

/VERIFY
Verifies data transfers. On file-structured copy operations, /VERIFY compares
each file after it has been copied. On physical copy operations, /VERIFY
compares the volume after it has been copied. For save or restore operations,
/VERIFY compares in a separate pass. Incompatible with the /NEW_VERSION
qualifier.

/VOLUME=number-of-volume
Processes a specific disk volume in a disk volume set. Valid only with the
/IMAGE qualifier. The /VOLUME qualifier requires only n+1 drives (rather
than 2*n); during a copy or save operation the entire set must be write-locked
for consistent results. In save operations the save set contains the segments of

dcl-22

DCL Commands
BACKUP

the files located on the specified volume. The input volume set must be fully
mounted. The save set can be restored only with the /VOLUME qualifier. In
restore operations the input save set must have been created using the /IMAGE
qualifier. In restore operations the output volume is a functionally equivalent
copy of the selected relative volume. The input save set can be either an image
save set of a full disk volume set or a selected volume save set created with the
/VOLUME qualifier. You cannot use the /NOINITIALIZE qualifier in a restore
operation with the /VOLUME qualifier. In a selected volume-compare operation
between two disk volume sets, both volume sets must be fully mounted.

CALL label [p1[p2[... p8]]]
Tranfers control to a labeled subroutine within a command procedure. The CALL
command creates a new procedure level as does the @ (execute procedure)
command. The SUBROUTINE and ENDSUBROUTINE commands define the
beginning and ending of the subroutine. The SUBROUTINE command must be
the first executable statement in a subroutine.
PARAMETERS

label
Specifies a 1- through 255-alphanumeric character label appearing as the first
item on a command line. A label may not contain embedded blanks. When
the CALL command is executed, control passes to the command following the
specified label. The label can precede or follow the CALL statement in the
current command procedure. When you use a label in a command procedure, it
must be terminated with a colon. All labels are procedure level dependent except
for those labels that define subroutine entry points. These labels are local to the
current command procedure file level. Labels for subroutine entry points must
be unique.

pi [P2 [... P8]]
Specifies from one to eight optional parameters to pass to the command
procedure. Use quotation marks (" ") to specify a null parameter. The parameters
assign character string values to the symbols named PI, P2, and so on in the
order of entry, to a maximum of eight. The symbols are local to the specified
command procedure.
QUALIFIER

/OUTPUT=file-spec
Requests that all output directed to the logical device SYS$OUTPUT be written
to the file or device specified. System responses and error messages are written
to SYS$COMMAND as well as to the specified file. If you specify /OUTPUT, the
qualifier must immediately follow the CALL command. No wildcard characters
are allowed in the output file specification.

DCL Commands

dcl-23

CANCEL

CANCEL [process-name]
Requires ownership of the process, or GROUP or WORLD privilege.
Cancels wakeup requests for a specified process that were scheduled with either the
RUN command or the $SCHDWK system service.
PARAMETERS

process-name
Name of the process. The specified process must have the same group number
in its UIC as does the current (issuing) process. Defaults to the current process.
Ignored if the /IDENTIFICATION qualifier is specified.
QUALIFIERS

/IDENTIFICATION=pid
Identifies the process by its process identification (PID). You can omit leading
zeros in the PID.

CLOSE logical-name[:]
Closes a file opened with the OPEN command and deassigns the associated logical
name. (Files that are opened for reading or writing at DCL command level stay open
until explicitly closed with the CLOSE command or until the process terminates.)
PARAMETERS

logical-name
Logical name associated with the file.
QUALIFIERS

/ERROR=label
Specifies a label in the command procedure to receive control if the CLOSE
operation results in an error. Overrides any ON condition action specified and
sets $STATUS to success.

/LOG (default)
/NOLOG
Generates a warning message when you attempt to close a file that was not
opened by DCL. If you specify the /ERROR qualifier, the /LOG qualifier has no
effect.

dcl-24

DCL Commands
CONNECT

CONNECT virtual-terminal
Requires that the virtual terminal feature for the system and for your terminal be
enabled with the SYSGEN utility.
Connects your physical terminal to a virtual terminal that is connected to another
process with your UIC. No other physical terminals may be connected to the virtual
terminal.
PARAMETERS

virtual-terminal
Name of the virtual terminal.
QUALIFIERS

/CONTINUE
/NOCONTINUE (default)
Continues execution of your previous process after the connection is established.
Incompatible with the /LOGOUT qualifier.

/LOGOUT (default)
/NOLOGOUT
Logs out your previous process when the connection is established. Incompatible
with the /CONTINUE qualifier.

CONTINUE
Resumes execution of an image or command procedure interrupted by CTRL/Y or
CTRL/C. You cannot resume execution of the image if you have entered a command
that executes another image or if you have invoked a command procedure.

COPY input-file-spec,... output-file-spec
Creates a new file (or files) from one or more existing files. If device or directory is
not specified, your current default device and directory are used.
PARAMETERS

input-file-spec
Specifications of existing files to be copied. Wildcard characters are allowed. Use
a plus sign or a comma to indicate multiple file specifications.

output-file-spec
Name of the resultant output file. Wildcard characters can be used in the
directory name, file name, file type, and/or version number to generate multiple
output files. You must specify at least one field in the output file specification.

DCL Commands

dcl-25

COPY

Normally, the owner of the output file will be the same as the creator of the
output file. However, if a user with extended privileges creates the output file,
the owner will be the owner of the parent directory or a previous version of the
output file if it exists.
QUALIFIERS

/BACKUP
/CREATED (default)
/EXPIRED
/MODIFIED
Selects files for the copy operation according to the dates of their most recent
backups, their creation dates, their expiration dates, or the dates of their last
modifications. Relevant only with the /BEFORE and /SINCE qualifiers.

/BEFORE[=time]
Selects only those files with dates that precede the specified time. You can
specify time as an absolute time, as a combination of absolute and delta times,
or as one of the following keywords: TODAY (default), TOMORROW, or
YESTERDAY. Specified with /BACKUP, /CREATED (default), /EXPIRED, or
/MODIFIED.

/BY_OWNER[=uic]
Selects for the copy operation only those files with the specified user
identification code. The default user identification code is that of the current
process.

/CONCATENATE (default)
/NOCONCATENATE
Creates one output file from multiple input files when wildcard characters are
not used in the output file specification. A specification of /NOCONCATENATE
generates multiple output files. Files from Files-11 Structure Level 2 disks are
concatenated in alphanumeric order; if you specify a wildcard in the file version
field, files are copied in descending order by version number. Files from Files-11
Structure Level 1 disks are concatenated in random order.

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each copy operation. The following
responses are valid:

dcl-26

DCL Commands
COPY

YES

Perform the copy operation

Do not perform the copy operation

TRUE

Perform the copy operation

FALSE

Do not perform the copy operation

Perform the copy operation

Do not perform the copy operation

RETURN

Do not perform the copy operation

ALL

Continue execution of the command with no further confirmation
prompts

CTRL/Z

Stop execution of the command

QUIT

Stop execution of the command

/CONTIGUOUS
/NOCONTIGUOUS
Qualifies output-file-spec.
Specifies that the output file must occupy contiguous physical disk blocks. By
default, the COPY command creates an output file in the same format as the
corresponding input file and does not report an error if not enough space exists
for a contiguous allocation.
The /CONTIGUOUS qualifier has no effect when you copy files to or from tapes
because the size of the file on tape cannot be determined until after it is copied
to the disk. If you copy a file from a tape and want the file to be contiguous, use
the COPY command twice: once to copy the file from the tape, and a second to
create a contiguous file.

/CREATED
See /BACKUP.

/EXCLUDE=(file-spec,...)
Omits the specified files from the copy operation. You can include a directory
but not a device in the file specifications. Wildcard characters are supported for
file specifications. However, you cannot use relative version numbers to exclude
a specific version.

/EXPIRED
See /BACKUP.

/EXTENSIONS
Qualifies output-file-spec.
Sets the extend quantity default for the output file.

DCL Commands

dcl-27

copy

/LOG
/NOLOG (default)
Displays file specifications of input and output files as well as the number of
blocks or records copied after each copy operation. Displays the number of files
created after the entire copy operation.

/MODIFIED
See /BACKUP.

/OVERLAY
/NOOVERLAY (default)

Qualifies output-file-spec.
Overlays the existing specified file rather than allocating new space for the file.

/PROTECTION=(ownership[:access],...)

/READ_CHECK
/NOREAD_CHECK (default)

Qualifies input-file-spec.
Reads each record in the input files twice to verify that it has been read correctly.

/REPLACE
/NOREPLACE (default)

Qualifies output-file-spec.
Deletes an existing file and creates a new file (allocating new space) if a version
number is specified in the output file. If no version number is specified in the
output file specification, a new version of the output file is created (regardless
of /REPLACE). If an existing version number is specified in the output file
specification without /REPLACE, an error occurs.

/SINCE[=time]
Selects only those files dated after the specified time. You can specify time as
an absolute time, a combination of absolute and delta times, or as one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

DCL-28

DCL Commands
COPY

/TRUNCATE
/NOTRUNCATE (default)
Qualifies output-file-spec.
Truncates the output file at end-of-file during the copy operation. By default, the
size of the output file is determined by the allocation of the input file.

/VOLUME=relative-volume-number
Qualifies output-file-spec.
Places the output file on the specified relative volume number of a multivolume
set. By default, the output file is placed arbitrarily in a multivolume set.

/WRITE—CHECK
/NOWRITE—CHECK (default)
Qualifies output-file-spec.
Reads each record in the output files after the record is written to verify that it is
written correctly.

CREATE file-spec,...
Creates a sequential text file (or files). Specify the content of the file on the lines
following the command, one record per line. In interactive mode, terminate the
file input with CTRL/Z. In a command procedure, terminate the file input with a
line beginning with a dollar sign in column 1 (or with the end of the command
procedure).
PARAMETERS

file-spec
Specification of the file being created. Wildcard characters are not allowed. The
file name and the file type default to null strings. If the specified file already
exists, a new version is created.
QUALIFIERS

/LOG
/NOLOG (default)
Displays the file specification of each new file created as the command executes.

/OWNER—UIC=uic
Requires SYSPRV privilege for a UIC other than your own.
Specifies an owner UIC for the file.

/PROTECTION=(ownership[:access],...)
Specifies protection for the file. Specify ownership as SYSTEM, OWNER,
GROUP, or WORLD and protection as R, W, E, or D. The default protection
is the current default protection.

DCL Commands

dcl-29

CREATE

/VOLUME=relative-volume-number
Places the file on the specified relative volume of a multivolume set. By default,
the file is placed arbitrarily in a multivolume set.

CREATE/DIRECTORY directory-spec,...
Requires WRITE access to the master file directory (MFD) to create a first-level
directory.
Creates one or more new directories or subdirectories.
PARAMETERS

directory-spec
Valid directory specification optionally preceded by a device name (and colon);
the directory defaults to the current default. Wildcard characters are not allowed.
QUALIFIERS

/LOG
/NOLOG (default)
Displays the directory specification of each directory created as the command
executes.

/OWNER_UIC=[uic]
Requires SYSPRV privilege for a UIC other than your own.
Specifies an owner UIC for the directory. The default is your UIC. You can
specify the keyword PARENT in place of a UIC to mean the UIC of the parent
directory. If a user with privileges creates a subdirectory, the default is that the
owner of the subdirectory will be the owner of the parent directory (or the owner
of the Master File Directory if creating a main level directory). If you do not
specifiy the /OWNER_UIC qualifier when creating a directory, the command
assigns ownership as follows: (1) if you specify the directory name in either
alphanumeric or subdirectory format, the default is your UIC (unless you are
privileged in which case the UIC defaults to the parent directory); (2) if you
specify the directory in UIC format, the default is the specified UIC.

/PROTECTION=(ownership[:access],...)
Specifies protection for the directory. Specify ownership as SYSTEM, OWNER,
GROUP, or WORLD and protection as R, W, E, or D. The default protection
is the protection of the parent directory (the master directory for top-level
directories) minus any delete access.

/VERSION_LIMIT=limit
Specifies the number of versions of any one file that can exist in the directory.
If you go over the limit, the system deletes the lowest numbered version.
A specification of 0 means no limit. A maximum limit of approximately 60

dcl-30

DCL Commands
CREATE/DIRECTORY

versions applies no matter the specification. The default is the limit for the
parent directory.

/VOLUME=relative-volume-number
Requests that the directory file be placed on the specified relative volume of a
multivolume set. By default, the file is placed arbitrarily within the multivolume
set.

CREATE/NAME—TABLE table
Creates a logical name table.
PARAMETERS

table
A string of from 1 to 31 characters that identifies the logical name table. The
string can include alphanumeric characters, the dollar sign, and the underscore.
QUALIFIERS

/ATTRIBUTES[=(keyword,...)]
Specifies attributes for the table. By default, no attributes are set. Possible
keywords are:
CONFINE

Does not copy the table name or the logical names contained in the table
into a spawned subprocess; relevant only for process-private tables.

NO—ALIAS

Prohibits creation of table names with the same name in an outer (less
privileged) access mode in the same logical name table directory; deletes
any previously created identical table names in an outer access mode in
the same logical name table directory.

SUPERSEDE

If a name exists within the appropriate directory at the indicated access
mode, it is deleted and a new table is created.

/EXECUTIVE_MODE
/SUPERVISOR-MODE (default)
/USER_MODE
Requires SYSNAM privilege for executive mode.
Specifies the access mode of the table. If you specify executive mode without
having SYSNAM privilege, a supervisor mode logical name table is created.

/LOG (default)
/NOLOG
Specifies whether or not an informational message is generated when the
SUPERSEDE attribute is specified or when the table already exists but the
SUPERSEDE attribute is not specified.

DCL Commands

dcl-31

CREATE/NAME_TABLE

/PARENT_TABLE=table
Requires SYSPRV and ENABLE access to specify a shareable table.
Specifies the name of the parent table, which must have the same access mode or
an access mode inner to the access mode of the table you are creating. Defaults
to LNM$PROCESS_DIRECTORY. The parent table determines whether the table
is private or shareable and where the quota of the new table comes from.

/PROTECTION=(ownership[:access],...)
Applies the specified protection to shareable name tables. The ownership
categories are SYSTEM, OWNER, GROUP, WORLD; the access categories
are R (read), W (write), E (enable), and D (delete). The default protection is
(SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)

/QUOT A=number-of-bytes
Specifies the size limit of the table. The size of each logical name entered in the
new table is deducted from this size limit. The new table's quota is statically
subtracted from the parent table's quota holder. The parent table's quota holder
is the first logical name table encountered when working upward in the table
hierarchy that has an explicit quota and is therefore its own quota holder. If
/QUOTA is not specified or the size limit is 0, the parent table's quota holder
becomes the new table's quota holder and space is dynamically withdrawn from
it whenever a logical name is entered in this new table.

/SUPERVISOR-MODE (default)
See/EXECUTIVE —MODE.

/USER-MODE
See /EXECUTIVE-MODE.

DEALLOCATE [device-name]
Makes an allocated device available to other processes (but does not deassign any
logical name associated with the device).
PARAMETERS

device-name
Name of the device to be deallocated. The device name can be a physical device
name or a logical name. On a physical device name, the controller defaults to A
and the unit to 0. Incompatible with the /ALL qualifier.

dcl-32

DCL Commands
DEALLOCATE

QUALIFIERS

/ALL
Deallocates all devices currently allocated by your process. Incompatible with
the device-name parameter.

DEASSIGN [logical-name[:]]
Deletes a logical name. Logical names in private tables are deleted automatically
when your process terminates. All logical names in the job table and the job
table itself are deleted when your process terminates. User mode logical names
in the process table are deleted automatically when the next image exits. All other
logical names in shareable tables remain unless explicitly deassigned. All names in
descendant tables are deleted when the parent table logical name is deassigned.
PARAMETERS

logical-name
The logical name to be deleted. Names containing other than alphanumeric,
dollar sign, or underscore characters must be enclosed in quotation marks ("). If
the name ends with a colon, you must specify two colons. Incompatible with the
/ALL qualifier.
QUALIFIERS

/ALL
Deletes all logical names in the same or an outer (less privileged) access mode.
Incompatible with the logical-name parameter.

/EXECUTIVE_MODE
/SUPERVISOR-MODE (default)
/USER-MODE

Requires SYSNAM privilege to deassign executive mode.
Deletes only entries that were created in the specified mode or an outer (less
privileged) mode. If you do not have SYSPRV privilege for executive mode, a
supervisor mode operation is assumed.

/GROUP
/JOB
/PROCESS (default)
/SYSTEM

Group logical names require GRPNAM or SYSPRV privilege.
System logical names require SYSNAM or SYSPRV privilege.
Specifies the table in which the logical name resides. The /GROUP qualifier is
synonymous with /TABLE=LNM$GROUP. The /JOB qualifier is synonymous
with /TABLE=LNM$JOB. The /PROCESS qualifier is synonymous with

DCL Commands

dcl-33

DEASSIGN

/TABLE=LNM$PROCESS. The /SYSTEM qualifier is synonymous with
/TABLE=LNM$SYSTEM.

/PROCESS
See /GROUP.

/SUPERVISOR-MODE
See /EXECUTIVE—MODE.

/SYSTEM
See /GROUP.

/TABLE=name
Requires WRITE access to the table to delete a shareable logical name.
Requires SYSPRV or DELETE access to delete a shareable logical name table.
Specifies the table from which the logical name is to be deleted. Defaults to
LNM$PROCESS. The table can be the process, group, job, or system table, one
of the directory tables, or the name of a user-created table.

/USER-MODE
See /EXECUTIVE-MODE.

DEASSIGN/QUEUE logical-queue-name[:]
Requires the OPER privilege or EXECUTE access to the queue.
Deassigns a logical queue from a physical device queue. Any jobs in the queue are
left pending until the logical queue is reassigned to another device queue.
PARAMETERS

logical-queue-name[:]
Name of the logical queue.

DECK
Marks the beginning of an input stream for a command or program. DECK is
required in command procedures when the first nonblank character in any data
record in the stream is a dollar sign.

dcl-34

DCL Commands
DECK

QUALIFIERS

/DOLLARS[=string]
Sets the end-of-file indicator to the specified string of 1 through 15 characters.
Enclose the string in quotation marks if it contains literal lowercase letters,
multiple blanks, or tabs. You must specify the EOD command to signal the end
of the stream if you do not specify the /DOLLARS qualifier.

DEFINE logical-name equivalence-name,...
Associates equivalence names with a logical name. If you specify an existing logical
name, the new equivalence names replace the existing equivalence name.
PARAMETERS

logical-name
A character string of 1 through 255 characters. If the string contains other
than upper case alphanumeric, dollar sign, or underscore characters, enclose
it in quotation marks ("). Use double quotation marks ("") to denote an actual
quotation mark. If the logical name is to be entered into the process or system
directory logical name tables, then the name may only have from 1 to 31
alphanumeric characters (including the dollar sign and underscore).
QUALIFIERS

/EXECUTIVE-MODE
/SUPERVISOR-MODE (default)
/USER_MODE
Executive mode requires SYSNAM privilege.
Specifies the mode of the logical name. If you specify executive mode without
SYSNAM privilege, a supervisor mode logical name is created. The mode of the
logical name must be the same as or external to (less privileged than) the mode
of the table in which you are placing the name.

DCL Commands

dcl-35

DEFINE

/GROUP
/JOB
/PROCESS (default)
/SYSTEM
Group logical names require GRPNAM or SYSPRV privilege.
System logical names require SYSNAM or SYSPRV privilege.
Specifies the table in which the logical name is to be placed. The /GROUP
qualifier is synonymous with /TABLE=LNM$GROUP. The /JOB qualifier is
synonymous with /TABLE=LNM$JOB. The /PROCESS qualifier is synonymous
with /TABLE=LNM$PROCESS. The /SYSTEM qualifier is synonymous with
/TABLE=LNM$SYSTEM.

/LOG (default)
/NOLOG
Displays a message when a new logical name supersedes an existing name.

/NAME—ATTRIBUTES[=(keyword,...)]
Specifies the attributes for a logical name. (By default, no attributes are set.)
Possible keywords are:
CONFINE

Does not copy the logical name into a spawned subprocess; relevant only

NO—ALIAS

Prohibits creation of logical names with the same name in a less
privileged access mode within the specified table; deletes any previously

for logical names in a private table.

created identical names in an outer access mode within the specified
table.

/PROCESS
See /GROUP.

/SUPERVISOR-MODE
See /EXECUTIVE _MODE.

/SYSTEM
See /GROUP.

/TABLE=name
Requires WRITE access to the table if the table is shareable.
Specifies the name of the logical name table in which the logical name is to be
entered. You can specify user-defined tables (created with the CREATE/NAME_
TABLE command), the process, job, group, or system logical name table, or the
process or system logical name directory tables. The default is LNM$PROCESS.
If you specify a table name that translates to more than one table, the logical
name is placed with the first table found.

dcl-36

DCL Commands
DEFINE

/TRANSLATION_ATTRIBUTES[=keyword,...]
Qualifies each equivalence string.
Specifies attributes of the equivalence strings. Possible keywords are:
CONCEALED

Indicates that the equivalence string is the name of a concealed device

TERMINAL

Terminates logical name translation after translation of this equivalence
string

/USER-MODE
See /EXECUTIVE—MODE.

DEFINE/CHARACTERISTIC name number
Requires OPER privilege.
Assigns a numeric value to a queue characteristic. The characteristic is created if it
does not exist. Used in conjunction with the /CHARACTERISTIC qualifier of the
PRINT command.
PARAMETERS

name
The name of an existing characteristic or a string of 1 through 31 characters that
defines a new characteristic. The character string can include any uppercase and
lowercase letters, digits, the dollar sign and the underscore, and must include at
least one alphabetic character.

number
An integer in the range 0 through 127.

DEFINE/FORM form-name number
Requires OPER privilege.
Assigns a numeric value to a print forms name. Used in conjunction with the
/FORM qualifier of the PRINT command.
PARAMETERS

form-name
The name of an existing forms type or a string of from 1 to 31 characters to
define a new forms type. The character string can include any uppercase and
lowercase letters, digits, the dollar sign and the underscore, and must include at
least one alphabetic character.

number
An integer in the range 0 through 999.

DCL Commands

dcl-37

DEFINE/FORM

QUALIFIERS

/DESCRIPTION=string
Specifies a string of from 1 to 255 characters to further describe the form. If the
string contains alphanumeric, underscore, or dollar sign characters, it must be
enclosed in quotation marks ("). The default string is the name specified in the
DEFINE/FORM command.

/LENGTH=page-length
Specifies the physical length of a forms page as an integer in the range 1 through
255. Defaults to 66. The print symbiont sets the page length of the device equal
to the form length. This enables the driver to compute the number of line feeds
for devices lacking mechanical form feed.

/MARGIN=(keyword,...)
Specifies one or more margin options. Possible keywords are:
BOTTOM=n

Specifies the number of blank lines between the end of the print image
area and the end of the physical page; the value of n must be between 0
and the value of the /LENGTH parameter and defaults to 6

LEFT=n

Specifies the number of columns between the leftmost printing position
and the print image area; the value of n must be between 0 and the
value of the /WIDTH parameter and defaults to 0

RIGHT=n

Specifies the number of columns between the /WIDTH parameter and
the image area; the value of n must be between 0 and the value of the
/WIDTH parameter and defaults to 0

TOP=n

Specifies the number of blank lines between the top of the physical page
and the top of the print image; the value of n must be between 0 and
the value of the /LENGTH parameter and defaults to 0

/PAGE_SETUP=(module,...)
/NOPAGE_SETUP (default)
Specifies one or more modules that set up the device before every page. The
modules are located in the device control library. When a new page is detected,
the system extracts the appropriate modules from the device control library and
copies them to the printer before the page is printed.

/SETUP=(module,...)
/NOSETUP (default)
Specifies one or more modules in the device control library that set up the device
appropriately for the specified form. When the form is mounted, the system
extracts the specified module from the device control library and copies it to the
printer before the file is printed.

dcl-38

DCL Commands
DEFINE/FORM

/SHEET_FEED
/NOSHEET-FEED (default)
Specifies that print jobs pause at the end of every physical page so that a new
piece of paper can be inserted.

/STOCK=type
Specifies the type of paper stock to be associated with the form as a string
of from 1 through 31 characters. The string must consist of alphanumeric,
underscore, and dollar sign characters.

/TRUNCATE (default)
/NOTRUNCATE
Discards any characters that exceed the current line length (specified by /WIDTH
and /MARGIN=RIGHT). Incompatible with the /WRAP qualifier. If you specify
both /NOTRUNCATE and /NOWRAP, the printer prints as many characters on
a line as possible.

/WIDTH=width
Specifies the physical width of the paper in terms of columns or character
positions as an integer in the range 0 through 65535. Defaults to 132. The
/MARGIN=RIGHT qualifier overrides the /WIDTH qualifier.

/WRAP
/NOWRAP (default)
Causes lines that exceed the current line length (specified by /WIDTH and
/MARGIN=RIGHT) to wrap onto the next line. Incompatible with the
/TRUNCATE qualifier. If you specify both /NOWRAP and /NOTRUNCATE,
the printer prints as many characters on a line as possible.

DEFINE/KEY key-name equivalence-string
Equates a key on the terminal keyboard to a character string.

DCL Commands

dcl-39

DEFINE/KEY

PARAMETERS

key-name
The name of the key to be defined. Permissible keys are as follows:

Key Name

VT100 Key

VT200 Key

PF1

PF2

PF3

PF4

KPO, KP1-KP9

Keypad 0-9

PERIOD

Period Key

COMMA

Comma Key

MINUS

Minus Key

ENTER

Enter Key

FIND, INSERT HERE

—

Find, Insert Here

REMOVE, SELECT

—

Remove, Select

PREV—SCREEN

—

Prev Screen

NEXT_SCREEN

—

Next Screen

HELP, DO

—

Help(F15), Do(F16)

F6-F20

—

Function Keys F6-F20

NOTE:

You cannot define the UP and DOWN arrow keys or function keys FI
through F5. You must issue the SET TERMINAL/NOLINE—EDITING command
before defining the LEFT and RIGHT arrow keys and function keys F6 through
F14. You can also press CTRL/V to enable keys F7 through F14, but CTRL/V
will not enable the F6 key.

equivalence-string
A character string to replace the key as input. Enclose the string in quotation
marks to preserve spaces and lowercase characters.
QUALIFIERS

/ECHO (default)
/NOECHO
Displays the equivalence string on the screen after the key has been pressed.
The /NOECHO qualifier is incompatible with the /NOTERMINATE qualifier.

/ERASE
/NOERASE (default)
Erases the current line before the key translation is inserted.

dcl-40

DCL Commands
DEFINE/KEY

/IF_STATE=(state,...)
/NOIF—STATE (default)
Specifies a list of one or more states, one of which must be in effect for the key
definition to work. The /NOIF_STATE has the same meaning as
/IF_STATE=current_state.

/LOCK_STATE
/NOLOCK—STATE (default)
Specifies that the state set by the /SET_STATE qualifier remain in effect until
explicitly changed. (By default, the /SET_STATE qualifier is in effect only for
the next definable key you press or the next read-terminating character that you
type.) Relevant only with the /SET_STATE qualifier.

/LOG (default)
/NOLOG
Displays a message indicating that the key definition has been successfully
created.

/SET—STATE=state
/NOSET_STATE (default)
Specifies a new state to be set when the specified key is pressed. (By default,
the current locked state is reset when the key is pressed.) Specify the state as a
character string enclosed in quotation marks (").

/TERMINATE
/NOTERMINATE (default)
Specifies that the key definition be processed immediately when the key is
pressed (equivalent to typing the string and pressing RETURN). By default, you
can press other keys before the definition is processed.

DELETE file-spec,...
Requires DELETE access to the file or sufficient privilege to override the protection.
Deletes a file or files.
PARAMETERS

file-spec,...
Specifications of files being deleted. Wildcard characters can be used. The plus
sign can be used in place of the comma between file specifications. Version
numbers must be specified on all file specifications. A null version number (a
semicolon without the number) or a version number of zero deletes the latest
version. A wildcard version number deletes all versions. File specifications
after the first one can omit all parts except the version number, and the defaults
will come from the preceding specification. The first file specification can omit

DCL Commands

DCL-41

DELETE

only the device and directory; the defaults will come from your current device
/directory. Files cannot be deleted from tape devices.
QUALIFIERS

/BACKUP
/CREATED (default)
/EXPIRED
/MODIFIED
Selects files for the delete operation according to the dates of their most recent
backups, their creation dates, their expiration dates, or the dates of their last
modifications. Relevant only with the /BEFORE and /SINCE qualifiers.

/BEFORE[=time]
Deletes only those files with dates that precede the specified time. You can
specify time as an absolute time, a combination of absolute and delta times,
or as one of the following keywords: TODAY (default), TOMORROW, or
YESTERDAY. Specified with /BACKUP, /CREATED (default), /EXPIRED, or
/MODIFIED.

/BY_OWNER[=uic]
Deletes only those files with the specified user identification code. The default
for uic is that of the current process.)

/CONFIRM
/NOCONFIRM (default)
Issues a request for confirmation before each deletion. The following responses
are valid:
YES

Delete the file

Do not delete the file

TRUE

Delete the file

FALSE

Do not delete the file

Delete the file

Do not delete the file

RETURN

Do not delete the file

ALL

Continue execution of the command with no further confirmation
prompts

CTRL/Z

Stop execution of the command

QUIT

Stop execution of the command

/CREATED
See /BACKUP.

DCL-42

DCL Commands
DELETE

/ERASE
/NOERASE (default)
Erases the specified files from the disk so that the deleted data does not exist
physically. By default, a file is just marked as deleted.

/EXCLUDE(=file-spec,...)
Excludes the specified files from deletion. You can include a directory name but
not a device name in the file specifications. Wildcard characters are supported for
file specifications. However, you cannot use relative version numbers to exclude
a specific version.

/EXPIRED
See /BACKUP.

/LOG
/NOLOG (default)
Displays the file specification of each file deleted as the command executes.

/MODIFIED
See /BACKUP.

/SINCE[=time]
Selects for deletion only those files dated after the specified time. You can specify
time as an absolute time, a combination of absolute and delta times, or one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

DELETE/CHARACTERISTIC name
Requires OPER privilege.
Deletes a queue characteristic.
PARAMETERS

name
The name of the characteristic.

DELETE/ENTRY =(job-number,...) queue-name[:]
Requires OPER privilege, EXECUTE access to the queue, or DELETE access to the
job.
Deletes one or more print or batch jobs from a queue. The jobs can be in progress or
waiting in the queue. Job-number specifies the job number of the job being deleted.

DCL Commands

DCL-43

DELETE/ENTRY

PARAMETERS

queue-name[:]
Name of the queue handling the job to be deleted.

DELETE/FORM form-name
Requires OPER privilege.
Deletes a form type for a printer or a terminal queue. When you delete a form
definition, you must ensure that no outstanding references to the form exist in
queues that have been mounted with the form or by jobs requesting that form.
PARAMETERS

form-name
The name of the form.

DELETE/INTRUSION__RECORD source
Requires CMKRNL and SECURITY privileges.
Removes an entry from the breakin database.
PARAMETERS

source
Source field of the entry being removed from the breakin database.

DELETE/KEY [key-name]
Deletes key definitions.
PARAMETERS

key-name
The name of the key to be deleted. Incompatible with the /ALL qualifier.
QUALIFIERS

/ALL
Deletes all key definitions in the specified (or, by default, the current) state.
Incompatible with the key-name parameter.

/LOG (default)
/NOLOG
Displays a message indicating the deletion has taken place.

dcl-44

DCL Commands
DELETE/KEY

/STATE=(state,...)
/NOSTATE (default)
Specifies the name of the state for which the specified key definition is to be
deleted. The default state is the current state.

DELETE/QUEUE queue-name[:]
Requires OPER privilege.
Deletes a print or batch queue and all the jobs in the queue. The specified queue
must have been stopped.
PARAMETERS

queue-name[:]
Name of the queue being deleted.

DELETE/SYMBOL [symbol-name]
Deletes a symbol or symbols.
PARAMETERS

symbol-name
Name of the symbol being deleted. A name is required unless the /ALL qualifier
is specified. Incompatible with the /ALL qualifier.
QUALIFIERS

/ALL
Deletes all symbols at the specified level. The /ALL qualifier is incompatible
with the symbol-name parameter.

/GLOBAL
/LOCAL (default)
Specifies the level of the symbol.

/LOG
/NOLOG (default)
Displays the symbols being deleted.

DCL Commands

dcl-45

DELETE/SYMBOL

DEPOSIT location=data,...
Requires user mode READ and WRITE access to the virtual memory location.
Replaces the contents of the specified locations in virtual memory and displays the
new contents. If the specified address can be read but not written by the current
access mode, the original contents are displayed; if the specified address can be
neither read nor written, asterisks are displayed in the data field. The DEPOSIT
command maintains a pointer at that location (at the byte following the last byte
modified).
PARAMETERS

location
A virtual address or a range of virtual addresses (where the second address is
larger than the first). A location can be any valid integer expression containing
an integer value, a symbol name, a lexical function, or a combination of these
entities. Radix qualifiers determine the radix in which the address is interpreted;
hexadecimal is the initial default radix. Symbol names are always interpreted
in the radix in which they were defined. The radix operators %X, %D, or %0
can precede the location. A hexadecimal value must begin with a number (or be
preceded by %X).

data
The data to be deposited into the specified locations; the data is initially
interpreted as hexadecimal and deposited in longwords by default.
QUALIFIERS

/ASCII
Specifies that the data is ASCII. Only one data item is allowed; all characters to
the right of the equal sign are considered to be part of a single string. Unless
they are enclosed within quotation marks, characters are converted to uppercase;
all blanks are compressed into one blank.

/BYTE
/LONGWORD
/WORD
Deposits the data in bytes, longwords, or words. The initial default is longwords.

/DECIMAL
/HEXADECIMAL
/OCTAL
Interprets the data as decimal, hexadecimal, or octal. The initial default is
hexadecimal.

/HEXADECIMAL
See /DECIMAL.

dcl-46

DCL Commands
DEPOSIT

/LONGWORD
See /BYTE.

/OCTAL
See /DECIMAL.

/WORD
See /BYTE.

DIFFERENCES inputl -file-spec [input2-file-spec]
Compares two files, displaying the records that do not match.
PARAMETERS

inputl-file-spec
Specification of the first file being compared. Wildcard characters are not
allowed.

input2-file-spec
Specification of the second file being compared. Unspecified fields default to the
corresponding fields in inputl-file-spec. If the two file specifications are the same
or input2-file-spec is omitted, the version number defaults to the next lower
version of inputl-file-spec.
QUALIFIERS

/CHANGE_BAR=([change-char][,[NO]NUMBER])
Marks with the specified character each line in the inputl file that differs from
the corresponding line in the input2 file. The change bar character defaults to
an exclamation point (!) for ASCII output. If you specify hexadecimal or octal
output (see /MODE qualifier), the change bar character is ignored and differences
are marked by a "♦♦♦CHANGE***" string. The keyword NONUMBER suppresses
line numbers in the listing. If only one option is specified, the parentheses can
be omitted.

/COMMENT_DELIMITER[=(character,...)]
Ignores lines starting with a specified comment character. If the comment
character is an exclamation point or semicolon, it can appear anywhere in the
line and characters to the right of the character are ignored. If you specify
just one character, you can omit the parentheses. Lowercase characters are
automatically converted to uppercase unless they are enclosed in quotation
marks. Special DCL characters (such as ! and ,) must be enclosed in quotation
marks. You can specify up to 32 comment characters by typing the character
itself or one of the following keywords (keywords can be abbreviated provided
that the resultant keyword is not ambiguous and has at least two characters).

COLON

Colon (:)

COMMA

Comma (,)

EXCLAMATION

Exclamation point (!)

FORM-FEED

Form feed

LEFT

Left bracket ([)

RIGHT

Right bracket (])

SEMI_COLON

Semicolon (;)

SLASH

Slash (/)

SPACE

Space

TAB

Tab

The following characters are the default comment delimiters for files with
specified file types.
B2S, B32, BAS, BLI

CBL, CMD

! and ;

COB

* or / in the first column

COM, COR
FOR

! anywhere and C, D, c, d in the first column

HLP
MAC, MAR
R32, REQ

/IGNORE=(keyword,...)

Inhibits the comparison of the specified characters, strings, or records, and
formats the output file. If you specify only one keyword, you can omit th
parentheses. The first set of keywords determines what, if anything, is ign
during file comparison; the second set of keywords determines whether or
ignored characters are included in the output.
BLANK-LINES

Blank lines between data lines.

COMMENTS

Data following a comment character.

FORM-FEEDS

Form feed character.

HEADER[=n]

First n records of the file, beginning with a record whos
character is a form feed. The first record is not ignored
the only character it contains is a form feed. (N indicat
number of records and defaults to 2. A record with a s
form feed is not counted.)

TRAILING-SPACES

Space and tab characters at the end of a data line

SPACING

Extra blank spaces or tabs within data lines.

dcl-48

DCL Commands
DIFFERENCES

EDITED

Omits ignored characters from the output records.

EXACT

Includes ignored characters in the output records.

PRETTY

Formats output records.

If you specify /PARALLEL, output records are always formatted. To format
output records, specify
Character

Formatted Output

Tab (CTRL/I)

1-8 spaces

RETURN (CTRL/M)

<CR>

Line feed (CTRL/])

<LF>

Vertical tab (CTRL/K)

<VT>

Form feed (CTRL/L)

<FF>

Other nonprinting characters

. (period)

/MATCH=n
Specifies the number of records (n) that should indicate matching data after a
difference is found; defaults to 3.

/MAXIMUM_DIFFERENCES=n
Terminates DIFFERENCES after a specified number of differences (n) is found.

/MERGED[=n]
Specifies that the output file contain a merged list of differences with the
specified number (n) of matched records listed after each group of unmatched
records. The specified number (n) must be less than or equal to the number
specified in the /MATCH qualifier; defaults to 1. If neither /MERGED nor
/SEPARATED nor /PARALLEL is specified, the resulting output is merged, with
one matched record following each unmatched record.

/MODE=(radix,...)
Specifies the format of the output as follows (keywords may be abbreviated):
ASCII (default), HEXADECIMAL, or OCTAL.
If you specify only one radix, you can omit the parentheses. If you specify
/PARALLEL, /MODE is ignored.

/NUMBER (default)
/NONUMBER
Includes line numbers in the listing of differences.

DCL Commands

dcl-49

DIFFERENCES

/OUTPUT[=file-spec]
Specifies an output file to receive the list of differences. If /OUTPUT is omitted,
the list is written to the terminal. File-spec defaults to that of the first input file
with a file type of DIF. No wildcards are allowed.

/PARALLEL[=n]
Lists the records with differences side by side. N specifies the number of matched
records to merge after each unmatched record. N must be less than or equal to
the number specified in /MATCH; defaults to 0.

/SEPARATED[=(input1-file-spec[,input2-file-spec])]
Lists only the records from the specified file that contain differences. If no files
are specified, a separate listing is generated for each file. If only one file is
specified, you can omit the parentheses. To specify inputl-file-spec, use either
the first input file specified as the DIFFERENCES parameter or the keyword
MASTER. To specify input2-file-spec, use either the second input file specified as
the DIFFERENCES parameter or the keyword REVISION.

/WIDTH=n
Specifies the width of the lines in the output file. The default is 132 characters.
If output is written to the terminal, /WIDTH is ignored and the terminal line
width is used.

/WINDOW=n
Searches the number of records specified (n) before a record is declared as
unmatched. By default, DIFFERENCES searches to the ends of both input files.

DIRECTORY [file-spec,...]
Requires READ access to the directories or sufficient privilege to override the
protection to obtain information other than the file name.
Displays the names and attributes of files in a directory or directories.
PARAMETERS

file-spec
Specification of file being listed. Wildcard characters are allowed. If no file is
specified, all files in your default directory are listed. If just a directory name is
specified, all files in that directory are listed. If the file type and version number
are omitted, all versions of all file types of the specified file are listed. If the
version number is omitted, all versions of the specified file are listed. The plus
sign can be used in place of the comma between file specifications.

dcl-50

DCL Commands
DIRECTORY

QUALIFIERS

/ACL
Displays the access control list (ACL) for each file. The /ACL qualifier overrides
the /COLUMNS qualifier.

/BACKUP
/CREATED (default)
/EXPIRED
/MODIFIED
Selects files for the directory operation according to the dates of their most recent
backups, their creation dates, their expiration dates, or the dates of their last
modifications. Relevant only with the /BEFORE and /SINCE qualifiers.

/BEFORE[=time]
Lists only those files with dates that precede the specified time. You can specify
time as an absolute time, a combination of absolute and delta times, or one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

/BRIEF (default)
Displays only a file's name, type, and version number. You can use the /ACL,
/DATE, /FILE _ID, /NOHEADING, /OWNER, /PROTECTION, /SECURITY,
and /SIZE qualifiers to expand a brief display.

/BY_OWNER[=uic]
Displays only those files with the specified user identification code. The default
UIC is that of the current process.

/COLUMNS=columns
Specifies the number of columns in a brief display. The default is four. The
number of columns is restricted by the value of the /WIDTH qualifier. The
/COLUMNS qualifier is incompatible with /ACL and /FULL.

/CREATED
See /BACKUP.

/DATE[=option]
/NODATE (default)
Expands the display to include dates. Possible options are:

DCL Commands

dcl-51

See also /FORM-

MOUNTED.
[NO]TRAILER[=keyword]

Specifies where to print trailer pages. The keyword
ALL places trailer pages after each printed file in the
job. The keyword ONE places a trailer page after the
last printed file in the job.

If you specify any of the keywords BURST, FLAG, TRAILER without specifying a value, the
value ALL is used by default.

/DISABLE_SWAPPING
/NODISABLE—SWAPPING
Allows swapping of the batch jobs.

/ENABLE_GENERIC
/NOENABLE_GENERIC
Allows files queued to a generic queue that does not specify explicit queue names
to be placed in this execution queue for processing.

/FORM_MOUNTED=type
Specifies the form type for a printer, terminal, or server queue. (Form types
are installation specific and are defined as numeric values or form names with
the DEFINE/FORM command. The SFiOW QUEUE/FORM command displays
the available print forms.) If the stock of the mounted form is not identical
to the stock of the default form, as indicated by the DCL command qualifier
/DEFAULT=FORM=type, then all jobs submitted to this queue without an
explicit form definition will enter a pending state. If a job is submitted with an
explicit form and the stock of the explicit form is not identical to the stock of
the mounted form, then the job will enter a pending state. In both cases, the
pending state will be maintained until the stock of the mounted form of the
queue is identical to the stock of the form associated with the job.

/JOB_LIMIT=n
Specifies the number of batch jobs that can be executed concurrently from the
queue. The value of n defaults to 1.

/OWNER_UIC=uic
Requires OPER privilege.
Specifies a UIC for the queue.

DCL Commands

dcl-146

SET QUEUE

/PROTECTION=(ownership[:access],...)
Requires OPER privilege.
Applies the specified protection to the queue. The ownership categories are
SYSTEM, OWNER, GROUP, and WORLD. The access categories are R (read),
W (write), E (create), and D (delete). The default protection is (SYSTEM:E,
OWNERiD, GROUP:R, WORLD:W).

/RECORD-BLOCKING
/NORECORD—BLOCKING
Determines whether the symbiont can concatenate (or block together) output
records for transmission to the output device. If you specify
/NORECORD—BLOCKING, the symbiont is directed to send each formatted
record in a separate I/O request to the output device. For the standard
MicroVMS print symbiont, record blocking can have a significant performance
advantage over single-record mode.

/RETAIN[=keyword]
/NORETAIN
Retains jobs in the queue in a completed status after they have executed.
Possible keywords are
ALL

Retains all jobs in the queue after execution (default)

ERROR

Retains in the queue only jobs that complete unsuccessfully

/SCHEDULE=SIZE
/SCHEDULE=NOSIZE
Specifies whether pending jobs in a printer or terminal queue are scheduled
for printing based on the size of the job. When /SCHEDULE=SIZE is in effect,
shorter jobs will print before longer ones.

/SEPARATE=(keyword,...)
/NOSEPARATE
Specifies the job separation defaults for a printer or terminal queue. Possible
keywords are
[NOJBURST

Prints a burst page (a flag page printed over the paper's
perforations for easy identification of individual files) at the
beginning of every job.

[NOjFLAG

Prints a flag page (containing the job entry number, the name
of the user submitting the job, and so on) at the beginning of
every job.

[NOJTRAILER

Prints a trailer page at the end of every job.

DCL Commands

dcl-147

SET QUEUE

[NO]RESET=(m,...)

Specifies a job reset sequence for the queue. The specified
modules from the device control library (see /LIBRARY) are
used to reset the device each time a job reset occurs.

/WSDEFAULT=n
Defines a working set default for a batch job. The /WSDEFAULT qualifier
overrides the working set size specified in the user authorization file. Possible
values are: a positive integer in the range 1 through 65,535, 0, or the keyword
NONE (the default). The value 0 or the keyword NONE sets the default value to
the value specified either in the UAF or by the SUBMIT command (if specified).

SET QUEUE/ENTRY =job-number queue-name
Changes the status of a queued print or batch job that is not currently executing.
PARAMETERS

job-number
The number of the job to be executed. The job number is displayed at the time
of the job's submission.

queue-name
Name of the print or batch queue.

DCL Commands

dcl-148

SET QUEUE/ENTRY

QUALIFIERS

/AFTER=time
/NOAFTER
Holds the job until the specified time. If the time has passed, queues the job for
immediate execution. The time must be in absolute date/time format.

/BURST
/NOBURST
Prints a burst page (a flag page printed over the perforations between pages for
easy identification of individual files) at the beginning of the job according to one
of the following keywords:
ALL

All printed files contain a burst page

ONE

The first printed file contains a burst page

/CHARACTERISTICS=(characteristic,...)
/NOCHARACTERISTICS
Specifies one or more characteristics for processing jobs on the queue. Use the
SHOW QUEUE/CHARACTERISTIC command to display queue characteristics.
The queue must have all the characteristics specified for a job or the job remains
pending.

/CLI=filename
Specifies the name of a command language interpreter (CLI) to use in processing
the job. The file must be in SYS$SYSTEM and be of type EXE.

/COPIES=n
Specifies the number of copies to print for all files in the job. The value of n can
be from 1 to 255.

/CPUTIME=keyword
Specifies a CPU time limit for the batch job. Time can be specified as: delta
time, 0, NONE, or INFINITE. Both the value 0 and the keyword INFINITE allow
unlimited CPU time; the keyword NONE defaults to your UAF value or the limit
specified on the queue. You cannot specify more time than permitted by the base
queue limits or your own UAF.

/ENTRY=job-number
Specifies the system-assigned number of the job. This qualifier is required and
must precede all other qualifiers and parameters.

/FEED
/NOFEED
Inserts form feeds in print jobs.

DCL Commands

DCL-149

SET QUEUE/ENTRY

/FLAG[=keyword]
/NOFLAG
Prints a flag page (containing the job entry number, the name of the user
submitting the job, and other information about the file being printed) according
to one of the following keywords:
ALL

Prints a flag page before each file in the job

ONE

Prints a flag page before the first file in the job

/FORM=type
Specifies special print form (including width, length, or type of paper) for the job.
The SHOW QUEUE/FORM command displays the available print form. If you
specify a form type different from that of the queue, the job remains pending
until the queue's form type is set to that of the job's specified form type. To
change the form type for the queue, stop the queue, physically change the form,
and restart the queue, specifying the new form type with the /FORM qualifier.

/HEADER
/NOHEADER
Prints a heading line at the top of each page in the print job.

/HOLD
/NOHOLD
Holds the job until released by the /NOHOLD or /RELEASE qualifier. The
/NOHOLD qualifier also releases jobs held in a queue with the /RETAIN
qualifier and jobs refused by a user-written symbiont.

/JOB_COUNT=n
Prints the job n times. The value of n can be from 1 through 255. This qualifier
overrides both the /JOB_COUNT qualifier specified and the default of the
PRINT command.

/KEEP
/NOKEEP
Retains the batch job log file after it is printed.

/LOG_FILE=file-spec
/NOLOG-FILE
Creates a log file with the specified file specification, which can include a device
name as long as the process executing the batch job has access to the device on
which the log file will reside. Logical names in the file specification are translated
in the context of the process that executes the SET QUEUE/ENTRY command.
If this qualifier is not specified, a log file with the file name of the first command
file (or the file name specified with the /NAME qualifier) and a file type of LOG
is created.

dcl-150

DCL Commands
SET QUEUE/ENTRY

/LOWERCASE
/NOLOWERCASE
Prints the job only on a printer that supports lowercase characters.

/NAME=job-name
Names (or renames) the job. The name can be 1 through 39 alphanumeric
characters. The file name defaults to the file name of the first file in the job and
a file type of LOG.

/NOCHECKPOINT
For a batch job, erases the value established by the most recently executed SET
RESTART—VALUE command. For a print job, clears the stored checkpoint so
that the job will restart from the beginning.

/NODELETE
Cancels file deletion for a job that was submitted with the /DELETE qualifier.
If no /DELETE qualifier was specified when the job was originally submitted to
the queue, you cannot use the SET QUEUE/ENTRY to establish file deletion at
a later time. You cannot use the /NODELETE qualifier to specify that individual
files in a multi file job not be deleted.

/NOTE=message
Specifies a message of up to 255 characters to appear on the flag page of the job.
Enclose the message in quotation marks if it contains spaces, special characters,
or lowercase characters.

/NOTIFY
/NONOTIFY
Broadcasts notification of job completion or abortion to any terminal at which
you are logged in.

/OPERATOR=message
Specifies a message string of up to 255 characters to be sent to the operator just
before the job begins execution. Enclose the message in quotation marks if it
contains spaces, special characters, or lowercase characters.

/PAGES=([lower,]upper)
Specifies the number of pages to print for the specified job. By default, all pages
of a file are printed. The lower parameter specifies the first page to print; it
defaults to the first page of the job. The upper parameter specifies the last page
to print; it defaults to the last page of the job. You must specify double quotation
marks (" ") if you omit the upper parameter.

DCL Commands

dcl-151

SET QUEUE/ENTRY

/PARAMETERS=(parameter,...)
Specifies from 1 to 8 optional parameters to be passed to the job. A parameter
can consist of 1 through 255 characters. Enclose the parameter in quotation
marks if it contains spaces, special characters, or lowercase characters. For batch
jobs, the parameters define values to be equated to the symbols named PI
through P8 in each command procedure in the job.

/PASSALL
/NOPASSALL
Specifies whether the symbiont bypasses all formatting and sends the output
QIO to the driver with format suppressed. All qualifiers affecting formatting, as
well as the /HEADER, /PAGES, and /PAGE —SETUP qualifiers, will be ignored.
When you use the /PASSALL qualifier with the SET QUEUE/ENTRY command,
the qualifier applies to the entire job. You cannot use this qualifier to specify
PASSALL mode for individual files within a multifile job.

/PRINTER[=queue-name]
/NOPRINTER
Queues the batch job log to the specified printer queue when the job is
completed. By default, the printer queue for the log file is SYS$PRINT. The
/NOPRINTER qualifier assumes the /KEEP qualifier.

/PRIORITY=n
Requires OPER or ALTPRI privilege to raise the priority above the value of the
SYSGEN parameter MAXQUEPRI.
Specifies the base priority at which a batch job will execute. The value of n can
be from 0 to 31 and defaults to the value of the SYSGEN parameter DEFQUEPRI.

/RELEASE
Releases for processing jobs submitted with the /AFTER qualifier, jobs held in a
queue with the /RETAIN qualifier, and jobs refused by a user-written symbiont.

/REQUEUE=queue-name
Moves the job to the specified queue.

/RESTART
/NORESTART
Restarts a batch or print job after a system crash or a STOP/REQUEUE
command.

DCL-152

DCL Commands
SET QUEUE/ENTRY

/SPACE
/NOSPACE
Double spaces a print job. The default is single spacing.

/TRAILER[=keyword]
/NOTRAILER
Prints a trailer page (containing the job entry number, the name of the user
submitting the job, and other information about the file) according to one of the
following keywords:
ALL

All printed files contain a trailer page

ONE

The last printed file contains a trailer page

/WSDEFAULT=n
Defines a working set default for a batch job. The /WSDEFAULT qualifier
overrides the working set size specified in the user authorization file. Possible
values are: a positive integer in the range 1 through 65,535, 0, or the keyword
NONE (the default). A value of 0 or the keyword NONE sets the default value to
the value specified either in the UAF or by the SUBMIT command (if specified).

/WSEXTENT=size
Defines a working set extent for the batch job. The /WSEXTENT qualifier
overrides the working set extent in the user authorization file. Possible values
are: a positive integer in the range 1 through 65,535, 0, or the keyword NONE
(the default). A zero or NONE sets the default value to the value specified either
in the UAF or by the SUBMIT command (if specified).

/WSQUOTA=size
Defines a working set page size (working set quota) for the batch job. The
/WSQUOTA qualifier overrides the value in the user authorization file. Possible
values are: a positive integer in the range 1 through 65,535, 0, or the keyword
NONE (the default). A zero or NONE sets the default value to the value
specified either in the UAF or by the SUBMIT command (if specified).

SET RESTART-VALUE =string
Sets a value for the symbol BATCH$RESTART.
PARAMETERS

string
A string of up to 255 characters specifying the label at which the batch job
should begin executing again.

DCL Commands

dcl-153

SET RIGHTS_LIST

SET RIGHTS—LIST id-name
Modifies the process or system rights list. You must specify either /DISABLE or
/ENABLE with the SET RIGHTS-LIST command.
PARAMETER

id-name[,...]
Identifiers to be added to or removed from the process or system rights list.
Id-name is a string of 1 to 31 alphanumeric characters, underscores, and dollar
signs. At least one character must be nonnumeric.
QUALIFIERS

/ATTRIBUTES=(keyword[,...])
Specifies attributes to be added to new or existing identifiers. Valid keywords
are:
[NOJDYNAMIC

Indicates whether or not unprivileged holders of the identifiers may
add or remove them from the process rights list.

The default is

NODYNAMIC.
[NO]RESOURCE Indicates whether or not holders of the identifiers may charge resources
to them. The default is NORESOURCE.

/ENABLE
/DISABLE
Adds or removes the identifiers to or from the process or system rights list.

/IDENTIFICATION=pid
/PROCESS[=process-name]

Requires CMKRNL privilege and GROUP or WORLD privilege to affect other
processes on the system.
Identifies the process identification value (pid) or name of the process whose
rights list is to be modified. The process name can contain from 1 to 15
alphanumeric characters. The default is the current process. You cannot use
either of these qualifiers with the /SYSTEM qualifier.

/SYSTEM

Requires CMKRNL and SYSNAM privilege.
Specifies that the desired operation be performed on the system rights list.
Incompatible with /PROCESS or /IDENTIFICATION.

dcl-154

DCL Commands
SET RIGHTS—LIST

SET RMS_DEFAULT
Defines default values for the multiblock and multibuffer counts used by Micro VMS
RMS for file operations. Defaults are set for sequential, indexed-sequential, or
relative access files on a process-only basis, unless a systemwide basis is requested.
For indexed sequential files, SET RMS—DEFAULT defines default prologue level
options. For sequential files, SET RMS—DEFAULT defines default extensions; if your
program does not specify a default extension, the process or system default is used.
QUALIFIERS

/BLOCK—COUNT=count
Specifies a default multiblock count (from 0 through 127) for file operations,
where count is the number of blocks to be allocated for each I/O buffer.

/BUFFER—COUNT=count
Specifies a default multibuffer count (from 0 through 127) for file operations,
where count is the number of buffers to be allocated. If you do not specify the
type of files (/DISK, /INDEXED, /RELATIVE, /SEQUENTIAL, and
/UNIT—RECORD) to which the default is to be applied, /SEQUENTIAL is
assumed.

/DISK
Applies the specified defaults to file operations on disks. (The /SEQUENTIAL
qualifier assumes /DISK.)

/EXTEND—QUANTITY=n
Specifies the number of blocks (n) to extend a sequential file; the value of n can
be from 0 to 65535. If you do not specify /EXTEND-QUANTITY, Micro VMS
RMS calculates its own extend value.

/INDEXED
Applies the specified defaults to indexed file operations.

/MAGTAPE
Indicates that the specified multibuffer default is to be applied to operations on
magnetic tape volumes. If /SEQUENTIAL is specified, /MAGTAPE is assumed.

/NETWORK—BLOCK—COUNT=count
Specifies a default block count for network access to remote sequential, indexed
sequential, and relative files. Specify count as a value in the range of 0 to 127.

/PROLOG=n
Specifies a default prologue level for indexed sequential files where n is 0, 2, or
3. (A value of 1 is not allowed.) By default, the value of n is 0; if n is 0, the
record management system (RMS) sets an appropriate prologue level.

DCL Commands

DCL-155

SET RMS_DEFAULT

/RELATIVE
Applies the specified defaults to relative file operations.

/SEQUENTIAL (default)
Applies the specified defaults to sequential file operations.

/SYSTEM
Requires the change-mode-to-kernel (CMKRNL) privilege.
Indicates that the specified defaults are to be applied to file operations by all
processes.

/UNIT_RECORD
Applies the specified defaults to file operations on unit record devices.

SET SYMBOL
Controls access to local and global symbols in command procedures.
QUALIFIER

/SCOPE=(keyword,...)
Controls access to local and global symbols. Allows the user to treat symbols as
being undefined. Possible keywords are:
[NOJLOCAL

Specifying the NOLOCAL keyword causes all local symbols defined in
outer procedure levels to be treated as being undefined by the current
procedure and all inner procedure levels. Specifying LOCAL removes
any symbol translation limit set by the current procedure level.

[NOJGLOBAL

Specifying the NOGLOBAL keyword causes all global symbols to be
inaccessible to the current procedure level and all inner procedure
levels unless otherwise changed. Specifying GLOBAL restores access to
all global symbols.

Note that when you exit a procedure back to a previous procedure, the symbol
scoping context from the previous level is restored for both local and global
symbols.

SET TERMINAL [device-name]
Sets the characteristics of a terminal. Entering a qualifier changes a characteristic.
Omitting a qualifier leaves the characteristic unchanged. (The /DEVICE_TYPE
qualifier sets the default characteristics for the specified terminal type; the /INQUIRE
qualifier automatically assigns default characteristics according to terminal type.)

DCL-156

DCL Commands
SET TERMINAL

PARAMETERS

device-name
Device name of the terminal. The default is SYS$COMMAND if that device is a
terminal.
QUALIFIERS

/ADVANCED-VIDEO
/NOADVANCED_VIDEO
Specifies that the terminal has advanced video attributes and is capable of
132-column video. If the terminal width is set to 132 columns and
/ADVANCED-VIDEO is enabled, the terminal page limit is set to 24 lines; if
/NOADVANCED-VIDEO is enabled, the terminal page limit is set to 12 lines.

/ALTYPEAHD
/NOALTYPEAHD
Sets the size of the type-ahead buffer when used with the /PERMANENT
qualifier.

/ANSI—CRT (default)
/NOANSI—CRT
Conforms to ANSI standards for terminal transmissions.

/APPLICATION-KEYPAD
/NUMERIC-KEYPAD (default)
Specifies whether the keys of the numeric keypad will be used to type numbers
and punctuation marks (/NUMERIC-KEYPAD) or to enter DCL commands
defined with the DEFINE/KEY command (/APPLICATION-KEYPAD).

/AUTOBAUD
/NOAUTOBAUD
Specifies whether the terminal baud rate is reset when you log in. You must
press the RETURN key two or more times at intervals of at least one second for
the baud rate to be correctly determined. If you press a key other than RETURN,
/AUTOBAUD might detect the wrong baud rate. If this happens, wait for the
login procedure to time out before continuing. The /AUTOBAUD qualifier must
be used with the /PERMANENT qualifier.

/BLOCK-MODE
/NOBLOCK_MODE
Performs block mode transmission, local editing, and field protection.

/BRDCSTMBX
/NOBRDCSTMBX (default)
Sends broadcast messages to an associated mailbox if it exists.

DCL Commands

dcl-157

SET TERMINAL

/BROADCAST (default)
/NOBROADCAST
Enables reception of broadcast messages (such as those issued by MAIL and
REPLY).

/CRFILL[=fill-count]
Generates the specified number of null characters after each carriage return
before transmitting the next meaningful character (to ensure that the terminal is
ready for reception). The value must be an integer in the range 0 through 9 and
defaults to 0.

/DEC_CRT[=(value1 ,value2)]
/NODEC_CRT[=(value1 ,value2)]
Specifies that the terminal conforms to DEC VT 100-family standards and
supports the minimum VT100 standards, which include the VT100 escape
sequences.
Two optional values may be specified. A value of 1 requests that the DEC_CRT
terminal characteristic be set. This is the default. A value of 2 requests that the
DEC—CRT2 terminal characteristic be set. This determines whether the terminal
conforms to DEC VT200-family standards and supports the minimum VT200
standards, including additional DEC escape sequences.
Note that DEC—CRT2 is a superset of DEC_CRT. Clearing DEC—CRT will cause
DEC—CRT2 to be cleared. Similarly, setting DEC—CRT2 will cause DEC—CRT
(and ANSI—CRT) to be set.

/DEVICE—TYPE=device-type
Informs the system of the terminal type and sets characteristics according to the
device type specified. The default characteristics for the VT100, VT102, VT125,
and VT200 series terminals are as follows:
/ADVANCEDVIDEO

/CRFILL=0

/LFFILL=0

/SPEED=9600

/NOALTYPEAHD

/ECHO

/LOWERCASE

/TAB

/ANSI—CRT

/NOEIGHT-BIT

/NODMA

/TTSYNC

/NOAUTOBAUD

/NOESCAPE

/PAGE=24

/TYPE-AHEAD

/NOBLOCK—MODE

/NOFORM

/NOPARITY

/WIDTH=80

/NOBRDCSTMBX

/FULLDUP

/NOPASTHRU

/WRAP

/BROADCAST

/NOHOSTSYNC

/NOREADSYN

/DIALUP
/NODIALUP (default)
Specifies that the terminal is a dialup terminal.

dcl-158

DCL Commands
SET TERMINAL

/DISCONNECT
/NODISCONNECT (default)
Specifies that the process connected to this terminal not be disconnected if
the line detects a hangup. The /DISCONNECT qualifier is only valid when
/PERMANENT is specified.

/DISMISS
/NODISMISS (default)
Makes the terminal driver ignore data causing a parity error (instead of
terminating the currently outstanding I/O with an error status).

/DMA
/NODMA
Controls the use of direct memory access (DMA) mode on a controller that
supports this feature.

/ECHO (default)
/NOECHO
Makes the terminal display the input it receives. With /NOECHO, the terminal
displays only system and/or user application output.

/EDIT_MODE
/NOEDIT-MODE
Specifies that the terminal can perform ANSI-defined advanced editing functions.

/EIGHT_BIT
/NOEIGHT-BIT (default)
Uses 8-bit ASCII protocol rather than 7-bit ASCII protocol.

/ESCAPE
/NOESCAPE (default)
Validates escape sequences.

/FALLBACK
/NOFALLBACK
Displays the 8-bit DEC Multinational Character Set characters on the terminal in
their 7-bit representation. The default depends on the /EIGHTBIT setting of the
terminal.

/FORM
/NOFORM
Transmits a form feed rather than translating it into multiple line feeds.

DCL Commands

dcl-159

SET TERMINAL

/FRAME=n
Specifies the number of data bits that the terminal driver expects for every
character that is input or output. The value of rt can be from 5 through 8. The
default value depends on the /PARITY and /EIGHTBIT settings of the terminal.

/FULLDUP
/NOFULLDUP
Operates in full duplex mode. /FULLDUP is equivalent to /NOHALFDUP.

/HALFDUP (default)
/NOHALFDUP
Operates in half duplex mode. /HALFDUP is equivalent to /NOFULLDUP.

/HANGUP
/NOHANGUP (default)
May require LOG—IO or PHY_IO privilege depending on system parameter
settings.
Hangs up the terminal modem when you log out.

/HARDCOPY
/NOHARDCOPY
Establishes the device as a hardcopy terminal and thus outputs a backslash (\)
when the DELETE key is pressed. The /HARDCOPY qualifier is equivalent to
/NOSCOPE.

/HOSTSYNC
/NOHOSTSYNC (default)
When you specify the /HOSTSYNC qualifier, the system stops transmission to
the terminal (by generating a CTRL/S) when the input buffer is full and resumes
transmission (by generating a CTRL/Q) when the input buffer is empty.

/INQUIRE
Sets the device type according to a response elicited from the terminal; the
default is UNKNOWN. Works only on DIGITAL terminals, and not on the LA36
or VT05 terminals.

/INSERT
/OVERSTRIKE (default)
Specifies whether you can insert a character (/INSERT) when editing command
lines, or type over a character (/OVERSTRIKE). You can use CTRL/A to switch
from one mode to the other.

dcl-160

DCL Commands
SET TERMINAL

/LFFILL[=fill-count]
Transmits to the terminal the specified number of null characters after each
line feed before transmitting the next meaningful character (to ensure that the
terminal is ready for reception). The value must be an integer in the range 0
through 9.

/LINE-EDITING
/NOLINE-EDITING (default)
Enables advanced line-editing features for editing command lines: both RETURN
and CTRL/Z are recognized as line terminators, as are escape sequences.

/LOCAI_ECHO
/NOLOCAI_ECHO (default)
Echoes characters locally (rather than the host echoing them) for command level
terminal functions. (Do not use /LOCAL _ECHO with utilities that require
control over echoing, such as line editing or EDT's screen mode.) Note that
MicroVMS cannot control the echoing of passwords when /LOCAL _ECHO is
set.

/LOWERCASE
/NOLOWERCASE
Passes lowercase characters to the terminal. The /NOLOWERCASE qual¬
ifier translates all input to uppercase. /LOWERCASE is equivalent to
/NOUPPERCASE.

/MANUAL
Indicates manual switching of terminal lines to dynamic asynchronous DDCMP
lines when your local terminal emulator does not support automatic switching.
The /MANUAL qualifier should be specified with the /PROTOCOL=DDCMP
and /SWITCH=DECNET qualifiers.

/MODEM
/NOMODEM
Indicates that the terminal is connected to a modem or a cable that supplies
standard E1A modem control signals. If your terminal has the MODEM
characteristic, typing SET TERMINAL/NOMODEM automatically logs you
out.

/NUMERIC-KEYPAD
See /APPLICATION-KEYPAD.

/OVERSTRIKE
See /INSERT.

DCL Commands

dcl-161

SET TERMINAL

/PAGE[=lines-per-page]
For hardcopy terminals, specifies the number of print lines between perforations.
(When the terminal reads a form feed, it advances the paper to the next
perforation.) The value of n can be from 0 through 255 and defaults to 0 (which
treats a form feed as a line feed).

/PARITY[=option]
/NOPARITY (default)
Passes data with odd or even parity, where option equals ODD or EVEN. If you
specify /PARITY without an option, the value defaults to EVEN.

/PASTHRU
/NOPASTHRU (default)
Passes all data (including tabs, carriage returns, line feeds, and control characters)
to an application program as binary data.

/PERMANENT
Requires LOG_IO or PHY_IO privilege.
Sets characteristics on a permanent basis, that is, over terminal sessions.
However, the characteristics revert to their initial values if the system is halted
and restarted. Use in a system start-up file to establish characteristics for all
terminals on the system.

/PRINTER-PORT
/NOPRINTER—PORT (default)
Specifies that the terminal has a printer port (an attribute not set by the SET
TERMINAL/INQUIRE command).

/PROTOCOL=DDCMP
/PROTOCOL=NONE (default)
Controls whether the terminal port specified is changed into an asynchronous
DDCMP line. The /PROTOCOL=NONE qualifier changes an asynchronous
DDCMP line back into a terminal line. Note that /PROTOCOL=DDCMP is a
permanent characteristic; therefore, the /PERMANENT qualifier is not required.

/READSYNC
/NOREADSYNC (default)
Uses the CTRL/S and CTRL/Q functions to synchronize data transmitted from
the terminal.

/REGIS
/ NOREGIS
Specifies that the terminal understands ReGIS graphic commands.

dcl-162

DCL Commands
SET TERMINAL

/SCOPE
/NOSCOPE
Establishes the device as a video terminal. /SCOPE is equivalent to
/NOHARDCOPY.

/SECURE_SERVER
/NOSECURE_SERVER (default)
Sets the BREAK key on the terminal to log out the current process. The
/SECURE—SERVER qualifier has no effect on terminals set with /AUTOBAUD.

/SET_SPEED
/NOSET-SPEED
Requires either LOG_IO or PHY_IO privilege.
Allows the /SPEED qualifier to be used to change the terminal speed.

/SIXEI_GRAPHICS
/NOSIXEI_GRAPHICS (default)
Specifies that the terminal is capable of displaying graphics using the sixel
graphics protocol.

/SOFT_CHARACTERS
/NOSOFT-CHARACTERS (default)
Specifies that the terminal is capable of loading a user-defined character set.

/SPEED=(input-rate, output-rate)
Sets the baud rate at which the terminal receives and transmits data. If the input
and output rates are the same, specify /SPEED=rate.

/SWITCH=DECNET
Causes the terminal lines at each node to be switched to dynamic asynchronous
DDCMP lines, when specified with the /PROTOCOL=DDCMP qualifier.
Note that /SWITCH=DECNET is a permanent characteristic; therefore, the
/PERMANENT qualifier is not required.

/SYSPASSWORD
/NOSYSPASSWORD (default)
Requires LOG_IO privilege.
Determines whether the terminal requires that a system password be entered
before the USERNAME prompt.

/TAB
/NOTAB (default)
Does not convert tab characters to multiple blanks. The /NOTAB qualifier
expands all tab characters to blanks and assumes tab stops at 8-character
intervals.

DCL Commands

dcl-163

SET TERMINAL

/TTSYNC (default)
/NOTTSYNC
Stops transmitting to the terminal when CTRL/S is pressed and resumes
transmission when CTRL/Q is pressed.

/TYPE_AHEAD (default)
/NOTYPE—AHEAD
Accepts unsolicited input for the terminal to the limit of the type-ahead buffer.

/UNKNOWN
Specifies a terminal type that is unknown to the system, which then uses the
default terminal characteristics for unknown terminals.

/UPPERCASE
/NOUPPERCASE
Passes only uppercase characters to the terminal. /UPPERCASE is equivalent to
/NOLOWERCASE.

/WIDTH=characters-per-line
Specifies the maximum characters per line. This value must be an integer in the
range 1 through 511. With /WRAP, the terminal generates a carriage return and
line feed when the width specification is reached.

/WRAP (default)
/NOWRAP
Generates a carriage return and line feed when the value of /WIDTH is reached.

SET TIME [-time]
Requires both OPER and LOG—IO privileges.
Resets the system clock, which is used both as a timer to record intervals between
various internal events and as a source clock for displaying the time of day.
PARAMETERS

time
A date in the format day-month-year, a time in the format
hour.minuteisecond.hundredth, or both. Day must be an integer in the range 1
through 31. Month must be JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP,
OCT, NOV, or DEC. Year must be an integer in the range 1858 through 9999.
Hour must be an integer in the range 0 through 23. Minute must be an integer
in the range 0 through 59. Second must be an integer in the range 0 through
59. Hundredth (of a second) must be an integer in the range 0 through 99. The
hyphens, colons, and period are required delimiters. Delimit the date and time,
when both are specified, with a colon.

dcl-164

DCL Commands
SET uic

SET UIC uic
Requires CMKRNL (change mode to kernel mode) privilege.
Changes the user identification code (UIC) of your process.
PARAMETERS

[uic]
A valid UIC. Brackets are required around the UIC.

SET [NO]VERIFY [=([NO]PROCEDURE,[NO]IMAGE)]
Controls whether command lines and/or data lines in command procedures are
displayed at the terminal or printed in a batch job log. Specify the keyword
PROCEDURE to write each DCL command line in a command procedure to
the output device. Specify IMAGE to write data lines to the output device. By
default, both types of verification are set or cleared with SET VERIFY and SET
NOVERIFY. The default setting for command procedures executed interactively is
SET NOVERIFY; the default for batch jobs is SET VERIFY.
PARAMETERS

PROCEDURE (default)
/NOPROCEDURE
Writes each DCL command line in a command procedure to the output device.

IMAGE (default)
/NOIMAGE
Writes data lines (input data that is included as part of the SYS$INPUT input
stream) to the output device.

SET VOLUME device-spec[:]f...
Requires WRITE access to the index file on the volume.
Changes the characteristics of a mounted Files-11 volume.
PARAMETERS

device-spec[:]
The name of a mounted Files-11 volume.

DCL Commands

dcl-165

SET VOLUME

QUALIFIERS

/ACCESSED=[n]
Requires OPER privilege.
Specifies the number of directories to be maintained in system space for ready
access. The value of n can be from 0 through 255 and defaults to 3. If you
specify a value greater than the current value, the new value is effective
immediately; otherwise, the new value will not take effect until the next time the
volume is mounted.

/DATA_CHECK[=(keyword,...)]
Defines a default for data check operations following all reads and/or writes to
the specified volume. (If you do not specify the /DATA_CHECK qualifier, no
checks are made.) Possible keywords are
READ

Performs checks following all read operations

WRITE

Performs checks following all write operations (default)

/ERASE_ON_DELETE
/NOERASE_ON_DELETE (default)
Files on the volume are overwritten with zeros when they are deleted.

/EXTENSIONS
Sets the extend quantity default for all files on the volume. The value n can
range from 0 through 65535.

/FILE-PROTECTION [=(ownership[:access],...)]
Sets the default protection to be applied to all files on the specified disk volume.
Specify ownership as SYSTEM, OWNER, GROUP, or WORLD and access as R
(read), W (write), E (execute), or D (delete). A null access specification means no
access.

/HIGHWATER_MARKING
/NOHIGHWATER_MARKING
Sets the File Highwater Mark (FHM) volume attribute, which guarantees that
a user cannot read data that he has not written. Applies to Structure Level 2
volumes only.

/LABEL=volume-label
Specifies a 1 through 12-character alphanumeric name to be encoded on the
volume. Characters are automatically changed to uppercase.

/LOG
/NOLOG (default)
Displays the volume specification of each volume after the modification.

dcl-166

DCL Commands
SET VOLUME

/MOUNT-VERIFICATION
/NOMOUNT—VERIFICATION
Enables mount verification (preventing interruption to user input/output
operations and notifying the operator of problems with the disk).

/OWNER_UIC[=uic]
Sets the owner UIC of the volume to the specified UIC. The default UIC is that
of the current process. Brackets are required around the UIC.

/PROTECTION=(ownership[:access],...)
Specifies the protection to be applied to the volume. The ownership categories
are SYSTEM, OWNER, GROUP, and WORLD; the access categories are R (read),
W (write), E (create), and D (delete). The default protection is all types of access
by all categories of user.

/REBUILD
Recovers caching limits for a volume that was improperly dismounted. If a disk
volume was dismounted improperly (such as during a system failure), and was
then remounted with the MOUNT/NOREBUILD command, you can use SET
VOLUME/REBUILD to recover the caching that was in effect at the time of the
dismount.

/RETENTION=(minimum[, maximum])
Specifies the minimum and maximum retention times to be used by the file
system to determine the expiration date for files on the volume. When a file is
created, its expiration date is set to the current time + maximum. Each time the
file is accessed, the current time is added to the minimum time and if the sum is
greater than the expiration date, a new expiration date is computed. Maximum
defaults to the smaller of (2 x minimum) or (minimum + 7).

/UNLOAD (default)
/NOUNLOAD
Specifies for the DISMOUNT command that the volume is unloaded.

/USER_NAME[=username]
Specifies a user name of up to 12 alphanumeric characters to be recorded on the
volume. The default name is the current process user name.

/WINDOWS[=n]
Specifies the number of mapping pointers to be allocated for file windows. The
value of n can be from 7 through 80; the default value is 7.

DCL Commands

dcl-167

SET WORKING_SET

SET WORKING-SET
Redefines the default working set size of the current process or sets an upper
limit to which the working set size can be changed by an image that the process
executes. (The working set limits cannot be set to exceed those defined in the user
authorization file.)
QUALIFIERS

/ADJUST (default)
/NOADJUST
Enables the system's changing of the process working set.

/EXTENT=n
Specifies the maximum number of pages that can be resident in the working set
during image execution. The extent value must be greater than the minimum
working set defined at system generation and must be less than or equal to the
authorized extent defined in the user authorization file. If you specify a value
greater than the authorized extent, the command sets the working set limit at the
maximum authorized value.

/LIMIT=n
Specifies the size to which the working set is to be reduced at image exit. If
you specify a value greater than the current quota, the quota value is also
increased. If you specify a limit equal to the /QUOTA value, automatic working
set adjustment is disabled.

/LOG
/NOLOG (default)
Displays confirmation of the SET WORKING—SET command.

/QUOTA=n
Specifies the maximum number of pages that any image executing in the
process context can request. If you specify a quota value that is greater than
the authorized quota, the working set quota is set to the authorized quota value.

SHOW ACCOUNTING
Displays the activities for which accounting is currently enabled.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

DCL-168

DCL Commands
SHOW ACL

SHOW ACL
See Appendix ACL.

SHOW AUDIT
Requires the SECURITY privilege.
Displays the set of auditing features that have been enabled with the SET AUDIT
command and the events that they will report.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW BROADCAST
Displays the message classes that are currently enabled by the SET BROADCAST
command.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW DEFAULT
Displays the current default device and directory.

SHOW DEVICES [device-name]
Displays information about the devices on the system.
PARAMETERS

device-name
Name of the device. The name can be generic — if no controller or unit number
is specified, all devices that satisfy that portion of the name are displayed. For
example, D means all disk devices.

DCL Commands

dcl-169

SHOW DEVICES

QUALIFIERS

/ALLOCATED
Displays information on allocated devices.

/BRIEF (default)
/FULL
Provides a brief display or a full display. A brief display contains the following
information: time, device name, status (on line or not), characteristics (if the
device is allocated, if it is spooled, if it has a volume mounted on it, if it has
a foreign volume mounted on it), error count, volume label, free blocks on the
volume, number of transactions, number of mount requests.
A full display contains the information of a brief display plus: number of I/O
operations completed, number of references, process identification and name of
the device owner, default buffer size, UIC of volume owner, volume protection,
volume status (if it is mounted /SYSTEM or /GROUP), name of the volume's
ACP, relative volume number, default cluster size, maximum number of files
allowed on the volume.

/FILES
Requires SYSPRV or BYPASS privilege to read protected files.
Names the open files on the volume. A blank file name indicates a temporary
file. If the /SYSTEM qualifier is also specified, only the names of installed files
and files opened by the system are displayed (including files opened without
the ACP and system files). If /NOSYSTEM is specified, only files opened by
processes are displayed. Incompatible with /ALLOCATED, /BRIEF, /FULL or
/MOUNTED.

/FULL
See /BRIEF.

/MOUNTED
Displays devices with volumes mounted on them.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

/SYSTEM
/NOSYSTEM
Names (when /FILES is specified) only those files opened by the system or only
those files opened by a process (/NOSYSTEM). The default is all open files.

DCL-170

DCL Commands
SHOW DEVICES

/WINDOWS
Displays the window count and total size of all windows for files open on
a volume, as well as the file name and related process name and process
identification (PID). The letter C in the display indicates that the file is open
with cathedral (segmented) windows.

SHOW ERROR
Displays any nonzero error count for the CPU, memory, and devices.
QUALIFIERS

/FULL
Displays the error count for all devices, including those with no errors.

/OUTPUT[=file-spec]
/OUTPUT=SYS$OUTPUT (default)
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW INTRUSION
Requires CMKRNL and SECURITY privileges.
Displays the contents of the breakin database.
QUALIFIERS

/OUTPUT[=file-spec]
Specifies the file to which output is written; by default, the display is written to
the current SYS$OUTPUT device.

/TYPE=keyword
Selects the type of information displayed with one of the following keywords:
ALL (default)

Displays all breakin entries.

SUSPECT

Displays breakin entries for login failures that have occurred but
have not been identified as intruder.

INTRUDER

Displays breakin entries for which the login failure rate was high
enough to warrant evasive action.

DCL Commands

DCL-171

SHOW KEY

SHOW KEY [key-name]
Displays key definitions created with the DEFINE/KEY command.
PARAMETERS

key-name
The name of the key. Permissible keys are as follows:

Keyname

VT100 Key

VT200 Key

PF1

PF2

PF3

PF4

KPO, KP1—KP9

Keypad 0—9

PERIOD

Period Key

COMMA

Comma Key

MINUS

Minus Key

ENTER

Enter Key

FIND, INSERT HERE

Find, Insert Here

REMOVE, SELECT

Remove, Select

PREV_SCREEN

Prev Screen

NEXT-SCREEN

Next Screen

HELP, DO

Help(F15), Do(F16)

F6-F20

Function Keys F6—F20

NOTE:

/ALL
Displays all key definitions in the current state (or the state specified with the
/STATE qualifier), including the state for each definition and all qualifiers that
are associated with each definition. Incompatible wtih the key-name parameter.

/BRIEF (default)
/FULL
Determines whether only the key definition and state are displayed (/BRIEF) or
whether all qualifiers associated with the key definition are displayed as well
(/FULL).

DCL Commands

dcl-172

SHOW KEY

/DIRECTORY
Displays the names of all states for which keys have been defined.

/STATE=(state-name,...)
/NOSTATE
Displays the key definition for the specified state. The current state is the default.

SHOW LOGICAL [logical-name,...]
Displays a logical name or names, equivalences, level of translation, and logical name
table. If no logical name is specified, displays the logical names in the list of tables
specified by LNM$DCL —LOGICAL.
PARAMETERS

logical-name
A logical name or names. The asterisk (*) and per cent (%) wildcard characters
are allowed; however, if a wildcard character is present, iterative translation is
not done.
QUALIFIERS

/ACCESS_MODE=mode
Displays names defined in the specified access mode and any inner access
modes. You can specify one of the following keywords to indicate the access
mode: USER_MODE, SUPERVISOR-MODE, EXECUTIVE-MODE or
KERNEL—MODE. The default is USER—MODE. By default, the system displays
any definitions in all three access modes.

/ALL (default)
Indicates that all logical names in the specified logical name tables are to be
displayed.

/DESCENDANTS
/NODESCENDANTS (default)
Displays names from the specified logical name table and any descendant tables.
(A descendant table is created by the CREATE/NAME—TABLE command,
with the PARENT—TABLE qualifier specifying its parent table.) If you use the
/DESCENDANTS qualifier, you must also use the /TABLE qualifier.

/FULL
Displays more detailed information on the access mode and any attributes for
each logical name, equivalence string, and logical name table.

DCL Commands

dcl-173

SHOW LOGICAL

/GROUP
/JOB
/PROCESS
/SYSTEM
Specifies the table from which the logical name is to be read. The /GROUP
qualifier is synonymous with /TABLE=LNM$GROUP. The /JOB qualifier is
synonymous with /TABLE=LNM$JOB. The /PROCESS qualifier is synonymous
with /TABLE=LNM$PROCESS. The /SYSTEM qualifier is synonymous with
/TABLE=LNM$SYSTEM.
/JOB
See /GROUP.
/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYSSOUTPUT device.
/PROCESS
See /GROUP.
/STRUCTURE
/NOSTRUCTURE (default)
Displays the family tree of all accessible tables. /STRUCTURE is mutually
exclusive with all other qualifiers but /OUTPUT, /ACCESS-MODE, and /FULL.

/SYSTEM
See /GROUP.
/TABLE=(name,...)

Requires READ access to display or search a shareable logical name table.
Displays the specified logical name tables. Wildcards are allowed. Wildcarded
names are used to match table names. Nonwildcarded names are treated both as
table names and table search lists (whichever is appropriate).

SHOW MAGTAPE
Displays the current characteristics and status of a specified magnetic tape device.

DCL-174

DCL Commands
SHOW MAGTAPE

PARAMETER

device-name
Specifies the name of the magnetic tape device for which you want to display the
characteristics and status.
QUALIFIER

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW MEMORY
Displays information about system resources related to memory.
QUALIFIERS

/ALL (default)
Displays information about paging and swapping files, physical memory, use of
pool areas, process entry slots, and balance slots.

/FILES
Displays information about the paging and swap files.

/FULL
When used with the /FILES and /POOL qualifiers, displays additional
information about the usage of each pool area or paging and swapping file.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

/PHYSICAI_PAGES
Displays information about the use of physical memory, including the number of
pages in use and the number of pages on the free and modified page lists.

/POOL
Displays additional information about the use of fixed-size and dynamic pool
areas, including the amount of used and free space and the size of the largest
contiguous block for each pool.

/SLOTS
Displays information about the availability of process entry and balance slots.

DCL Commands

dcl-175

SHOW NETWORK

SHOW NETWORK
If your system is a routing node, displays the name and hardware line for each
accessible network node, plus the number of logical links, the line cost, and the
actual cost (hops) between your node and the other node. If your system is a
nonrouting node, displays the designated router for your system.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW PRINTER device-name
Displays the characteristics of a printer.
PARAMETERS

device-name
Name of the printer.
QUALIFIERS

/OUTPUT=[file-spec]
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW PROCESS [process-name]
Displays information about your process and any current subprocesses. If no qualifier
is entered, only a basic subset of information is displayed: the time, process terminal,
user name and UIC, process name and process identification, priority, default
directory, and allocated devices.
PARAMETERS

process-name

Requires ownership of the process or that you have GROUP privilege and the
process is in your group.
The name of the process about which information is to be displayed.
Incompatible with the /IDENTIFICATION qualifier.

DCL-176

DCL Commands
SHOW PROCESS

QUALIFIERS

/ACCOUNTING
Displays the accumulated accounting statistics for the current session.

/ALL
Displays the basic subset of information plus the accounting statistics, privileges,
quotas, and subprocesses.

/CONTINUOUS
Dynamically displays information about the specified process. Specify the
process name as a parameter (process name defaults to the current process).
Press the V key to display a map of the pages in the virtual address space of the
process. Each character displayed in the map represents the type of page. If the
current program counter (PC) is in the page, the page type is indicated by an at
((a)) sign. Pages locked in the working set are indicated by the letter L. Global
pages are indicated by the letter G. Other valid pages in the working set are
indicated by an asterisk. To terminate the display, press the E key. To return to
the original display, press the spacebar.

/IDENTIFICATION=pid
Requires GROUP or WORLD privilege to access a process other than the
current process.
Displays information about the process with the specified process identification.
Incompatible with the process name parameter and the /SUBPROCESSES
qualifier.

/MEMORY
Displays the process's use of dynamic memory areas.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

/PRIVILEGES
Displays privileges and identifiers currently enabled for the process.

/QUOTAS
Displays, for each resource, either a quota or a limit. The values displayed for
quotas reflect any quota reductions resulting from subprocess creation. The
values displayed for limits reflect the resources available to a process at creation.

/SUBPROCESSES
Displays the current subprocesses in hierarchical order. Incompatible with the
/IDENTIFICATION qualifier.

DCL Commands

DCL-177

SHOW PROCESS

SHOW PROTECTION
Displays your default file protection.

SHOW QUEUE [queue-name]
Displays the current status of batch and print jobs.
PARAMETERS

queue-name
Name of the queue in which the job exists. If queue-name is not specified,
information on all queues is displayed. Wildcard characters are valid; the default
queue name is *.
QUALIFIERS

/ALL
Displays all current and pending jobs in the specified queues.

/BATCH
Displays all batch queues and any jobs in those queues that are owned by the
current process.

/BRIEF (default)
/FULL
Displays a brief or full description of the jobs in the queues.

/DEVICE
Displays jobs owned by the current process in all printer, terminal, and server
queues.

/FILES
Requests a brief listing of information about job entries in the queue with the list
of files associated with each job. The display includes a full file specification for
each file in each job.

/FULL
See /BRIEF.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

dcl-178

DCL Commands
SHOW QUEUE/CHARACTERISTICS

SHOW QUEUE/CHARACTERISTICS [characteristic]
Displays the names and numbers of available queue characteristics.
PARAMETERS

characteristic
The name of a characteristic. You can use wildcard characters. The default is *.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW QUEUE/FORM [form-name]
Displays predefined form names and numbers that are available on queues.
PARAMETERS

form-name
The name of the form. You can use wildcard characters. The default is *.
QUALIFIERS

/BRIEF (default)
/FULL
Displays a brief listing of information about the forms (form name, stock,
number, and form description).

/FULL
See /BRIEF.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW QUOTA
Requires READ access to the quota file in order to display the quotas of other users.
Displays the current disk quota that is authorized for a specific user on a specific
disk. (This display also includes a calculation of the amount of space available and
the amount of overdraft that is permitted.)

DCL Commands

dcl-179

SHOW QUOTA

QUALIFIERS

/DISK[=device-name[:]]
Specifies the disk whose quotas are to be examined. By default, the current
default disk is examined.

/USER=uic
Specifies which user's quotas are to be displayed. By default, the current user's
quotas are displayed.

SHOW RMS_DEFAULT
Displays the current default multiblock count and multibuffer count that RMS uses
for file operations.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW STATUS
Displays the current status of your process: the date, cumulative processor time used,
cumulative buffered I/O operations performed, cumulative direct I/O operations
performed, working set limit, amount of physical memory being used, number of
open files, and cumulative page faults.

SHOW SYMBOL [symbol-name]
Displays the value of the specified symbol.
PARAMETERS

symbol-name
The name of the symbol. The symbol-name parameter is required if /ALL is
not specified and is incompatible with /ALL. If /LOCAL or /GLOBAL is not
specified, symbol-name means the first symbol at: (1) the current command
level, (2) a higher command level, or (3) the global level, in that order. Wildcard
characters are allowed in the symbol-name specification.

dcl-180

DCL Commands
SHOW SYMBOL

QUALIFIERS

/ALL
Displays the current values of all symbols in the specified symbol table.

/GLOBAL
/LOCAL (default when /ALL is specified)
Indicates the level of the symbol.

/LOCAL
See /GLOBAL.

/LOG (default)
/NOLOG
Generates a message indicating truncation of the symbol value. (The symbol
value is truncated if it exceeds 255 characters.)

SHOW SYSTEM
Displays status information concerning current processes: the time, process name
and identification, processing state, priority, total process I/O, cumulative processor
time used, cumulative page faults, amount of physical memory being used, and the
type of process if not interactive (B for batch, N for network, S for subprocess).
QUALIFIERS

/BATCH
/NETWORK
/PROCESS (default)
/SUBPROCESS
Displays all batch jobs, all network processes, all processes, or all subprocesses
on the system.

/FULL
Displays the default status information for current processes, plus process UICs.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYSSOUTPUT device.

DCL Commands

dcl-181

SHOW TERMINAL

SHOW TERMINAL [device-name]
Displays the current characteristics of a terminal. (See SET TERMINAL for a list of
the characteristics displayed.)
PARAMETERS

device-name
Name of the terminal. The default is your terminal (SYS$COMMAND).
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

/PERMANENT
Displays the permanent characteristics of the terminal. Use of the /PERMANENT
qualifier requires LOG_IO or PHY_IO privilege.

SHOW [DAY]TIME
Displays the current date and time.

SHOW TRANSLATION logical-name
Searches one or more logical name tables for a specified logical name and returns
the equivalence name of the first match found. If you do not specify the table, the
tables specified by the multivalued logical name LNM$DCL—LOGICAL are searched.
Unless LNM$DCL—LOGICAL has been redefined for your process, the process, job,
group, and system logical name tables are searched in that order. The translation is
not iterative.
PARAMETERS

logical-name
The logical name to be displayed.
QUALIFIERS

/TABLE=name
Searches the specified table. The default is /TABLE = LNM$DCL—LOGICAL.

dcl-182

DCL Commands
SHOW USERS

SHOW USERS [username]
Displays the user name, process name, terminal name, and process identification
code (PID) of interactive users on the system.
PARAMETERS

username
The user about whom you want information. If you specify a string, all users
whose user names begin with the string are displayed. If you omit username, a
list of all interactive users is displayed.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SHOW WORKING—SET
Displays the working set limit, quota, and extent assigned to the current process.
QUALIFIERS

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies the file to which the display is written; by default, the display is written
to the current SYS$OUTPUT device.

SORT input-file-spec,... output-file-spec
Sorts a file or files into one ordered output file.
PARAMETERS

input-file-spec
Specification of files whose records are to be sorted. All files must have the same
record format and key description, but may have different file organizations.
Wildcard characters are not allowed. The file type defaults to DAT.

output-file-spec
Specification of the file produced by the sort operation. Wildcard characters are
not allowed. The file type defaults to the file type of the first input file.

DCL Commands

dcl-183

sort

QUALIFIERS

/ALLOCATION=file-size
Qualifies output-file-spec.
Required only to override relative and indexed-sequential input file characteris¬
tics. File-size is the number of 512-byte blocks to be allocated for the file and
must be an integer in the range 1 through 4294967295. The /ALLOCATION
qualifier is required if /CONTIGUOUS is specified.

/BUCKET_SIZE=bucket-size
Qualifies output-file-spec.
Required only to override input file characteristics. For relative and indexed
files, specifies the bucket size in blocks. For input and output files of the same
organization, the default is the same as the bucket size of the first input file;
otherwise, the default is 1. Bucket size must be an integer in the range 1 through
32.

/COLLATING_SEQUENCE=sequence
Names the collating sequence for character data. Sequence can be ASCII,
EBCDIC, or MULTINATIONAL. Note that when you specify EBCDIC, the
characters remain in ASCII representation; only the order is changed. The
/MULTINATIONAL qualifier specifies the collating sequence of the Multinational
character set. See Appendix CHAR for the ASCII and Multinational character
sets.

/DUPLICATES (default)
/NODUPLICATES
Deletes records with duplicate keys from the sort operation. The /NODUPLICATES
qualifier is incompatible with the /STABLE qualifier.

/FORMAT=record-format[n:]
Qualifies input-file-spec and output-file-spec.
Specifies record format and size. Possible options for the input file are:
RECORD_SIZE=n

An integer in the range 1 through 32767 for sequential files, 1
through 16383 for relative files, or 1 through 16383 for indexed

FILE_SIZE=n

An integer in the range 1 through 4294967295

sequential files

DCL-184

DCL Commands
SORT

Possible options for the output file are:
FIXED=n

A fixed size record whose maximum size is an integer in the range
1 through 32767 for sequential files, 1 through 16383 for relative
files, or 1 through 16383 for indexed sequential files

VARIABLE=n

A variable size record whose maximum size is an integer in the
range 1 through 32767 for sequential files, 1 through 16383 for
relative files, or 1 through 16383 for indexed sequential files

CONTROLLED=n

A controlled record whose size is an integer in the range 1 through
32767 for sequential files, 1 through 16383 for relative files, or 1
through 16383 for indexed sequential files

SIZE=n

An integer in the range 1 through 255

If /FORMAT is not specified for the output file, the format is based on the sort
process selected: if RECORD or TAG sort is selected, the default is the format of
the first input file; if ADDRESS or INDEX sort is selected, the default is FIXED.

/INDEXED_SEQUENTIAL
/RELATIVE
/SEQUENTIAL
Qualifies output-file-spec.
Specifies the organization of the file. For a record or tag sort, the output file
format defaults to the organization of the input file. For an indexed sort, the
output file must exist and be empty and you must specify the /OVERLAY
qualifier.

/KEY=(option,...)
Defines a sort key. You can specify /KEY up to 255 times to define 255 different
key fields on which to sort. The default is a character data key, beginning in
position 1 of the input record for a length of the LRL (longest record length) for
the input file, up to a maximum length of 32767 bytes. The following keywords
specify position, size, and data type of the key field within the record.

POSITION=start of key

Starting byte of the key within the rec
where the first byte of the record is po
1. The value must be an integer in the
1-32767. The position option is require

CHARACTER (default)
BINARY
F_FLOATING
D_FLOATING
G_FLOATING
H .FLOATING
ZONED
DECIMAL
PACKED-DECIMAL

Data type of the key.

SIZE=n

Size of the key as follows depending o
type;

CHARACTER—Number of ch
specified as an integer in the r
1-32767 (default = 32767)

BINARY—Then integer value
(byte), 2 (word), 4 (longword)
(quadword), or 16

DECIMAL—Number of digits,
counting the sign, specified as
integer in the range 1 to 31

PACKED-DECIMAL—same a
DECIMAL

Do not specify a size for floating-point
types, whose sizes are fixed at 4
(F-FLOATING), 8 (D_ and G-FLOATI
and 16 (H_FLOATING) bytes. The tot
of all keys must not exceed 32767 byte
NUMBER=key order

Priority of the key specified as an integ
the range 1-255, where 1 means the pr
key. The default is the order in which
keys are specified.

ASCENDING(defauIt)
DESCENDING

Order in which records are sorted for t

dcl-186

DCL Commands
SORT

Option

Description

SIGNED (default)
UNSIGNED

Whether or not a sign is stored (binary keys

TRAILING—SIGN (default)
LEADING-SIGN

Byte in which sign is stored — first or last

OVERPUNCHED—SIGN(default)

Whether the sign is superimposed on the
decimal value or is separated from the decimal

SEPARATE-SIGN

only)
(decimal keys only).

(decimal keys only).

/OVERLAY
/NOOVERLAY
Qualifies output-file-spec.
Writes the output to an existing file which must be empty. By default, a new
output file is created for sequential and relative files. If the output file is
INDEXED—SEQUENTIAL, /OVERLAY must be specified.

/PROCESS=keyword
Defines the type of sort with one of the following keywords:
RECORD

Sorts complete records and produces an output file of complete records in
sorted order (default).

TAG

Sorts keys, then reaccesses the input file to produce an output file of
complete records in sorted order (the net result is the same as a record
sort); terminal input is not allowed.

ADDRESS

Sorts keys and produces an output file of pointers; multiple input files
are not allowed; terminal input is not allowed; the output file is in binary
format.

INDEX

Sorts keys and produces an output file of pointers and keys; multiple input
files are not allowed; terminal input is not allowed; the output file is in
binary format.

/RELATIVE
See /INDEXED—SEQUENTIAL.

/SEQUENTIAL
See /INDEXED—SEQUENTIAL.

/SPECIFICATION=file-spec
Identifies the specification file to be used in the SORT operation. File type
defaults to SRT. Any qualifiers specified in the SORT command line override the
qualifiers in the specification file. The specification file can contain the following
qualifiers:

DCL Commands

DCL-187

SORT

QUALIFIERS

/CDD_PATH_NAME=“cdd-path-name"
Specifies a record definition ("cdd-path-name") from the Common Data
Dictionary (CDD) if your system has VAX CDD installed. Once the
fields have been identified, they may be used in later specification file
qualifiers. (The /CDD_PATH_NAME qualifier may be used with or in
place of the /FIELD qualifier.)

/COLLATING_SEQUENCE=(SEQUENCE=sequence[,keywords...])
Specifies the collating sequence for character key fields; the collating
sequence can be ASCII (the default), EBCDIC, MULTINATIONAL, or a
user-defined collating sequence that is specified as a string of characters
(single or double) or a range of single characters. Each character and
range must be separated by commas and enclosed in parentheses. You
can also specify characters by their corresponding octal, decimal, or
hexadecimal values, using the radix operators %0, %D, %X. Specify the
quotation mark by doubling its occurrence within quotation marks by
using a radix operator. Specify the null character with a radix operator
(such as %X0). You must include in the sequence all characters that
appear in the character keys or the character will be ignored (unless the
MODIFICATION or FOLD keyword is specified).
Other optional keywords are as follows. Note that the FOLD,
MODIFICATION, and IGNORE keywords are processed in the order
in which they are specified.
MODIFICATION

Specifies the change you want to make to the collating
sequence (ASCII, EBCDIC, MULTINATIONAL, or userdefined).

Use the format MODIFICATION=(character

operator character).

Specify character as it is in the

collating sequence and operator as > ,

<, or =. You can

specify the following changes to a collating sequence:
(1) Equate a character (single or double) to a character
(single or double) that has already been assigned a
collating value ("a,/="A" or "CH"="SH" or "C"="CH").
(2) Collate a character (single or double) after a single
character that has already been assigned a collating value
("CH"> "C"). (3) Collate a character (single or double)
before a character that has already been assigned a
collating value ("CH" <"C").

dcl-188

DCL Commands
SORT

IGNORE

Specifies the character or range of characters to be initially
ignored in the collating sequence (unless two or more
strings have compared as equal and (1) TIE_BREAK
is in effect or (2) the Multinational sequence is being
used).

Specify in the format IGNORE=character (or

IGNORE=character range,...).
FOLD

Gives all lowercase letters the collating value of their
uppercase equivalents (the Multinational sequence does
this by default).

[NOJTIE—BREAK

Specifies whether or not numeric values are used to break
any ties between characters that have equivalent values.
(The Multinational sequence breaks ties in this way by
default.)

/CONDITION=(NAME=condition-name,TEST=(field-name operator test[logicaloperator,...]))
Defines a conditional test that can be used to change the relative order
of a record (with the /KEY or /DATA qualifier) or to alter the contents
of certain fields of a record (with the /OMIT or /INCLUDE qualifier).
Condition-name specifies the name of the condition; once defined, you
can use the condition name with the /KEY, /DATA, /OMIT, and
/INCLUDE qualifiers. Field-name specifies the name of the field (defined
by the /FIELD qualifier) being tested; logical operator specifies the logical
(AND or OR) or relational (EQ, NE, GT, GE, LT, or LE) operator used
in the test. Operator-test specifies the constant for which you are testing.
Specify the constant with the following syntax: %D decimal—digits, %0
octal—digits, %X hexadecimal—digits, and "character".

/FIELD=(NAME=field-name,POSITIONS,SIZE:n, data-type) [DIGITS:n]
Defines the fields in the input files. (You must specify each field in the
records to be merged, including key fields, field to be compared, and
fields to be directed to your output file.) Field-name cannot have any
embedded blanks, must begin with an alphabetic character, and can be
no longer than 31 characters. POSITION specifies the position of the
field in the record. SIZE specifies the size of a field, according to data
type: character data must not exceed 32,767 characters; binary data must

DCL Commands

dcl-189

sort

be 1, 2, 4, 8, or 16 bytes; and floating-point data has no specified size.
Data-type specifies the data type of the field; the default is character.
Specify data-type as one of the following:
CHARACTER

(default)

BINARY[.SIGNED]

BINARY,UNSIGNED

ZONED

D.FLOATING

F_FLOATING

G.FLOATING

H.FLOATING

PACKED.DECIMAL

DECIMAL,UNSIGNED

DECIMAL[,SIGNED,TRAILING.SIGN,OVERPUNCHED_SIGN]
DECIMAL,LEADING.SIGN,SEPARATE.SIGN[,SIGNED]
DECIMAL,LEADING.SIGN,[OVERPUNCHED.SIGN,SIGNED]
DECIMAL,[TRAILING.SIGN],SEPARATE JSIGN[.SIGNED]

DIGITS specifies the size of a field containing decimal data; n cannot
exceed 31 digits.

/INCLUDE=(CONDITION=condition-name,[KEY=. ..],DATA=...])
Specifies that records are to be conditionally included (according to
a previously defined condition). If you specify multiple /INCLUDE
qualifiers, the order in which you specify them determines the order in
which the input records are tested for inclusion. You unconditionally
include any records not previously omitted or included by specifying
/INCLUDE without a condition. The order of the key fields you specify
determines how the internal key is built for merging; the order of the
DATA fields determines the way in which the output record is formatted.
If you specify a key or data field with /INCLUDE, you must define all
other key or data fields in the record.

/KEY=(field-name[,order])
/KEY=(IF condition-name THEN value ELSE value)
Specifies key fields (up to 255) and the order of their priority
(unnecessary if you are merging on the entire record using character
data). Field-name is the name of the field specified in the /FIELD
qualifier. Order can be ASCENDING or DESCENDING. The conditional
form of the /KEY qualifier specifies a relative order of records; value can
be a constant or a field name that has been defined in a /FIELD qualifier.

dcl-190

DCL Commands
SORT

/PAD=single-character
Specifies a character to be used to fill an incomplete record when you
are reformatting a record or comparing strings of unequal length; the
null character is the default pad character. The pad character can be a
character or a digit (decimal, octal, or hexadecimal). Enclose characters
in quotation marks and precede digits with radix (%X23).
/PROCESS=type
Specifies the type of sort: type can be record (default), tag, address, or
index. You cannot use address or index sort if the output records are
going to be reformatted.
/STABLE (default)
/NOSTABLE (default)
Arranges records with equal keys in the output file in the order of the
input files (by default, the order is unpredictable).
/WORK_FILES=(disk,...)
Assigns work files to the specified disk and/or diskette. (By default,
work files are located in the directory SYS$SCRATCH; placing them
on separate disks with /WORK_FILES permits overlap of SORT'S read
/write cycle.)
/STABLE
/NOSTABLE (default)
Maintains the order of records with identical keys; otherwise, the order is un¬
predictable. The /STABLE qualifier is incompatible with the /NODUPLICATES
qualifier.
/STATISTICS
/NOSTATISTICS (default)
Displays a statistical summary at the end of the sort.
/WORK_FILES=number-of-files
Specifies the number of temporary work files. The value can be from 0 through
10, with a default of 2.

SPAWN [command-string]
Requires TMPMBX or PRMMBX user privilege.
Creates a subprocess.

DCL Commands

dcl-191

SPAWN

PARAMETERS

command-string
A command string of less than 132 characters that is to be executed in the
context of the created subprocess. When the command completes execution,
the subprocess terminates and control returns to the parent process. If both a
command string and the /INPUT qualifier are specified, the specified command
string executes before additional commands are obtained from the /INPUT
qualifier.
QUALIFIERS

/CARRIAGE_CONTROL
/NOCARRIAGE_CONTROL
Prefixes carriage return/line feed characters to the subprocess's prompt string.
The default is the parent process's setting.

/CLI=cli-file-spec
/NOCLI
Specifies the command language interpreter (CLI) that will be used by the
subprocess. The default CLI is that defined in SYSUAF. If you specify /CLI,
context is copied to the subprocess.

/INPUT=file-spec
Specifies an input file containing one or more DCL commands to be executed
by the subprocess. File type defaults to COM. Once processing of the input
file is complete, the subprocess is terminated. If both a command string and
the /INPUT qualifier are specified, the specified command string executes
before additional commands are obtained from the /INPUT qualifier. If none is
specified, SYS$INPUT is assumed (in which case a SPAWN/NOWAIT will be
aborted if CTRL/Y is typed to abort something running in your parent process.

/KEYPAD (default)
/NOKEYPAD
Copies keypad key definitions and the current keypad state from the parent
process.

/LOG (default)
/NOLOG
Displays the assigned subprocess name and any messages indicating transfer of
control between processes.

/LOGICAI_NAMES (default)
/NOLOGICAI_NAMES
Copies process logical names and logical name tables (except those explicitly
marked CONFINE or created in executive or kernel mode) to the subprocess.

dcl-192

DCL Commands
SPAWN

/NOTIFY
/NONOTIFY (default)
Broadcasts a message to your terminal notifying you that your subprocess
has completed or aborted. Incompatible with the /NOWAIT qualifier or the
execution of SPAWN from within a noninteractive process.

/OUTPUT=file-spec
Specifies the output file to which the results of the SPAWN operation are written.
(Do not specify SYS$COMMAND as a file specification with the /NOWAIT
qualifier; both parent and subprocess output will be displayed simultaneously on
your terminal.)

/PROCESS=subprocess-name
Specifies the name of the subprocess to be created. The default subprocess name
format is: username_n.

/PROMPT[=string]
Specifies the prompt string for DCL to use in the subprocess. The default is the
prompt of the parent process. The string must be enclosed in quotation marks if
it contains spaces, special characters, or lowercase characters.

/SYMBOLS (default)
/NOSYMBOLS
Passes global and local symbols (except $RESTART, $SEVERITY, and $STATUS)
to the subprocess.

/TABLE=command=table
Specifies the name of an alternate command table to be used by the subprocess.

/WAIT (default)
/NOWAIT
Requires that you wait for the subprocess to terminate before you issue another
DCL command. The /NOWAIT qualifier allows you to issue new commands
while the subprocess is running. (Use the /OUTPUT qualifier with the
/NOWAIT qualifier to avoid displaying both parent and subprocess output
on the terminal simultaneously.)

START/QUEUE queue-name
Requires OPER privilege or EXECUTE access to the queue.
Starts or restarts the specified queue after it has been initialized. The
/TOP_OF_FILE, /BACKWARD or /FORWARD, /SEARCH, and /ALIGN qualifiers
are processed in that order when more than one occurs in a command line.

DCL Commands

DCL-193

START/QUEUE

PARAMETERS

queue-name
Name of the queue.
QUALIFIERS

/ALIGN[=(option,...)]
Prints alignment pages that enable the operator to properly align the forms in
the printer or terminal. Use this qualifier in restarting an output queue from a
paused state. Possible options are:
MASK

Displays alphabetic characters as x's and numbers as 9's; nonalphanumeric
characters are not masked. The default is not to mask,

Specifies the number of alignment pages to print. The value of n can be
from 1 to 20; the default is 1.

/BACKWARD=n
Restarts a print queue n pages before the current page; n defaults to 1. Use this
qualifier in restarting an output queue from a paused state.

/BASE_PRIORITY=n
Specifies the process priority base at which jobs are initiated from a batch queue.
The value of n can be from 0 through 15. By default, jobs are initiated at the
priority established by DEFPRI at system generation (usually 4).

/BATCH
/NOBATCH (default)
Specifies that the queue is a batch queue. (The queue must have been initialized
as a batch queue.)

/BLOCK__LIMIT=([lower,]upper)
/NOBLOCK_LIMIT (default)
Restricts the size of print jobs that can be executed on a printer or terminal
queue. The lower parameter specifies the minimum number of blocks that will
be accepted by the queue for a print job. The upper parameter specifies the
maximum number of blocks that will be accepted by the queue for a print job. If
a job contains fewer blocks than the number specified by the lower parameter or
more blocks than the number specified by the upper parameter, the job remains
pending until the block limit for the queue is changed. To specify only the lower
parameter, you must use two sets of quotation marks ("") in place of the upper
specifier.

/CHARACTERISTICS=(characteristic,...)
/NOCHARACTERISTICS (default)
Specifies one or more characteristics for processing jobs on the queue. Each time
you specify /CHARACTERISTIC, all previously set characteristics are erased. A

DCL-194

DCL Commands
START/QUEUE

queue must have all the characteristics specified for the job or the job remains
pending.

/CPUDEFAULT=time
Specifies the default CPU time limit for batch jobs. Time can be specified as delta
time, 0, NONE, or INFINITE. Both the value 0 and the keyword INFINITE allow
unlimited CPU time (subject to the restrictions imposed by the /CPUMAXIMUM
qualifier or the user authorization file); the keyword NONE indicates that no
time limit is needed.

/CPUMAXIMUM=time
Specifies the maximum CPU time limit for batch jobs. The /CPUMAXIMUM
qualifier overrides the time limit specified in the user authorization file (UAF).
Time can be specified as delta time, 0, NONE, or INFINITE. Both the value 0 and
the keyword INFINITE allow unlimited CPU time; the keyword NONE specifies
that no time limit is needed.

/DEFAULT=(option,...)
/NODEFAULT
Establishes default options for the PRINT command. The /DEFAULT qualifier
can not be used with the /GENERIC qualifier. Possible options are:
[NO]BURST[=keyword]

Specifies where to print burst pages (flag pages that
are printed over the paper's perforations for easy
identification of individual files in a print job). The
keyword ALL (the default) places burst pages before
each printed file in the job. The keyword ONE places
a burst page before the first printed file in the job.

[NOjFEED

Specifies whether a form-feed is automatically
inserted at the end of a page

[NO]FLAG[=keyword]

DCL Commands

DCL-195

START/QUEUE

FORM=type

Specifies the default form for a printer, terminal,
or server queue.

If a job is not submitted with an

explicit form definition, then this form will be used
to process the job.

The systemwide default form,

form=0, is the default value for this keyword.

See

also /FORM_MOUNTED.
[NO]TRAILER[=keyword]

Specifies where to print trailer pages. The keyword
ALL places trailer pages after each printed file in the
job. The keyword ONE places a trailer page after the
last printed file in the job.

If you specify any of the keywords BURST, FLAG, TRAILER without specifying
a value, the value ALL is used by default.

/DISABLE_SWAPPING
/NODISABLE-SWAPPING (default)
Controls whether batch jobs executed from a queue can be swapped in and out
of memory.

/ENABLE-GENERIC (default)
/NOENABLE—GENERIC
Allows files queued to a generic queue that does not specify explicit queue names
in the /GENERIC qualifier to be placed in this execution queue for processing.

/FORWARD=n
Advances the specified number of pages before resuming printing the current file;
the default is 1. Use this qualifier in restarting an output queue from a paused
state.

/GENERIC[=(queue-name,...)]
/NOGENERIC (default)
Specifies that the queue is generic; jobs in a generic queue are moved to one
of the specified queues for processing. (The /BATCH qualifier of the generic

dcl-196

DCL Commands
START/QUEUE

queue and all the specified execution queues must match.) If you do not specify
a queue, jobs can move to any execution queue (initialized without the printer,
terminal, or server) as the generic queue. (For a generic server queue, the
/PROCESSOR qualifier of the generic queue and the execution queue must
also match.) By default, a generic queue is a print queue; use the appropriate
qualifier (/BATCH, /PROCESSOR, /TERMINAL) to override the default. The
/GENERIC qualifier is incompatible with the /DEFAULT, /FORM_MOUNTED,
and /SEPARATE qualifiers.

/JOB__LIMIT=n
Specifies the number of batch jobs that can be executed concurrently from the
queue; the value of n defaults to 1.

/LIBRARY=filename
Specifies the file name for the device control library. (The /LIBRARY qualifier
can be used to specify an alternate device control library when used to initialize
a symbiont queue.) The default library is SYS$LIBRARY:SYSDEVCTL.TLB. You
can specify only a file name; the library must be in SYS$LIBRARY and the file
type must be TLB.

/NEXT
Restarts the queue with the next job. (By default, the job that was executing
when the queue stopped resumes if it has not been deleted.)

/ON=device[:]
Specifies the device on which this execution queue is located; the default device
name is the same as the queue name. For batch queues, you can only specify the
node name.

/OWNER_UIC=uic
Requires OPER privilege.
Specifies a UIC for the queue. The default UIC is [1,4].

/PROCESSOR=filename
/NOPROCESSOR
Used for a symbiont queue, specifies a print symbiont image in
SYS$SYSTEM:filename.EXE; the default file name is PRTSMB. Used for a generic
queue, the /PROCESSOR qualifier specifies that the generic queue can place
jobs only on queues that have declared themselves as server queues and that are
executing the specified symbiont image.

/PROTECTION=(ownership[:access],...)
Requires OPER privilege.
Applies the specified protection to the queue. The ownership categories are
SYSTEM, OWNER, GROUP, WORLD; the access categories are R (read).

DCL Commands

dcl-197

START/QUEUE

W (write), E (create), and D (delete). The default protection is (SYSTEM:E,
OWNER:D, GROUP:R, WORLD:W).

/RECORD-BLOCKING (default)
/NORECORD_BLOCKING
Determines whether the symbiont can concatenate (or block together) output
records for transmission to the output device. If you specify
/NORECORD—BLOCKING, the symbiont is directed to send each formatted
record in a separate I/O request to the output device. For the standard
MicroVMS print symbiont, record blocking can have a significant performance
advantage over single-record mode.

/RETAIN[=keyword]
/NORETAIN (default)
Retains jobs in the queue in a completed status after they have executed.
Possible keywords are:
ALL

Retains all jobs in the queue after execution (default)

ERROR

Retains in the queue only jobs that complete unsuccessfully

/SCHEDULE=SIZE (default)
/SCHEDULE=NOSIZE
Specifies whether pending jobs in a printer or terminal queue are scheduled for
printing based on the size of the job. When the default, /SCHEDULE=SIZE, is in
effect, shorter jobs will print before longer ones.
Note: If you issue this command while there are pending jobs in any queue, the
effect on future jobs is unpredictable.

/SEARCH=“string”
Resumes printing the current file on the first page containing the specified
string. The string can be from 1 through 63 characters and must be enclosed in
quotation marks. Use this qualifier in restarting an output queue from a paused
state.

Prints a burst page (a flag page printed over the paper's
perforations for easy identification of individual files) at the
beginning of every job.

dcl-198

DCL Commands
START/QUEUE

[NO]FLAG

Prints a flag page (containing the job entry number, the
name of the user submitting the job, and so on) at the
beginning of every job.

[NOjTRAILER

Prints a trailer page at the end of every job.

[NO]RESET=(m,...)

Specifies a job reset sequence for the queue. The specified
modules from the device control library (see /LIBRARY) are
used to reset the device each time a job reset occurs.

/TERMINAL
/NOTERMINAL (default)
Associates a generic queue with terminal queues (instead of printer queues) with
matching characteristics.

/TOP_OF_FILE
Resumes printing at the beginning of the file that was current when the queue
paused. Use this qualifier only when restarting an output queue from a paused
state.

/WSDEFAULT=n
Defines a working set default for a batch job. The /WSDEFAULT qualifier
overrides the working set size specified in the user authorization file. Possible
values are: a positive integer in the range 1 through 65,535, 0, or the keyword
NONE (the default). A zero or NONE sets the default value to the value
specified either in the UAF or by the SUBMIT command (if specified).
When used for an output queue, this qualifier specifies the working set default of
a symbiont process for a printer, terminal, or server queue when the symbiont
process is created.

DCL Commands

dcl-199

START/QUEUE

NONE (the default). A zero or NONE sets the default value to the value
specified either in the UAF or by the SUBMIT command (if specified).
When used for an output queue, this qualifier specifies the working set quota of
a symbiont process for a printer, terminal, or server queue when the symbiont
process is created.

START/QUEUE/MANAGER [file-spec]
Requires both OPER and SYSNAM privilege.
Starts the queue manager for the batch/print facility and opens the job queue
manager file. The START/QUEUE/MANAGER command must be executed before
you can execute any other queue management or job submission command.
PARAMETERS

file-spec
The name of the file containing the information about batch and print jobs,
queues, and form definitions. The default file specification is
SYS$SYSTEM:JBCSYSQUE.DAT.
QUALIFIERS

/BUFFER_COUNT=n
Specifies the number of buffers in a local buffer cache to allocate for performing
I/O operations to the system job queue file. Specify n as a positive integer in the
range of 1 through 127 or 0. If 0 is specified, the default value of n=50 is used.

/EXTEND_QUANTITY=n
Specifies the number of blocks by which the system job queue file is extended
(when this action is necessary). This value is also used as the initial allocation
size when the queue file is created. Specify n as a positive integer in the reange
of 10 through 65,535 or 0. If 0 is specified, the default value of n=100 is used.

/NEW_VERSION
/NONEW_VERSION (default)
Specifies that a new version of the job queue manager file be created to supersede
an existing version. All jobs in the previous version are lost if a new version is
specified.

/RESTART
/NORESTART (default)
The /RESTART qualifier specifies that the queue manager be restarted
automatically on recovery from a job controller abort. In addition, batch and
output queues are restored to the states that existed prior to the interruption of
service. The job queue manager file that is opened is the same file that was open
before the abort. Upon restarting, the job controller uses the default values for

dcl-200

DCL Commands
START/QUEUE/MANAGER

the /EXTEND_QUANTITY and /BUFFER-COUNT qualifiers. Previously set
values are lost.
When the job controller incurs an internal fatal error, the process aborts and
restarts itself. By default, the queue manager is not restarted. Intervention by a
user with OPERATOR privilege is necessary to restart the queue manager and
to restore the queueing environment using START/QUEUE/MANAGER and
appropriate START/QUEUE commands.
Note: In order to prevent a looping condition, the job controller will not restart
the queue manager if it detects an error within two minutes of starting the queue
manager.

STOP [process-name]
Requires GROUP privilege to stop other processes in the same group.
Terminates execution of a command, image, a command procedure, a command
procedure that was interrupted by CTRL/Y, or a detached process or subprocess.
PARAMETERS

process-name

Requires that the process be in your group.
Name of the process running the command procedure or image. The process
name can have from 1 to 15 alphanumeric characters. Incompatible with the
/IDENTIFICATION qualifier. You must use /IDENTIFICATION=pid to specify a
process outside of your group.
QUALIFIERS

/IDENTIFICATION=pid
Specifies the system-assigned process identification. /IDENTIFICATION can be
used in place of the process name parameter.

STOP/QUEUE queue-name
Requires OPER (operator) privilege or EXECUTE access to the queue.
Stops the specified execution queue. All jobs currently executing in the queue are
suspended (until the queue is restarted with the START/QUEUE command) and no
new jobs can be initiated. The /REQUEUE and /RESET qualifiers provide other
ways of stopping queues. To stop individual jobs on the queue, specify the /ABORT,
/ENTRY, or /REQUEUE qualifier.

DCL Commands

DCL-201

STOP/QUEUE

PARAMETERS

queue-name
Name of the queue.
QUALIFIERS

/ABORT
Aborts the current print job, deleting it from the queue, and resumes execution of
the jobs in the queue. (STOP/QUEUE/ABORT is equivalent to STOP/ABORT.)

/ENTRY=job-number
Stops the currently executing job on the specified batch queue.

/HOLD
Places the aborted job on hold; must be used in combination with the
/REQUEUE qualifier. To release the job, use the SET QUEUE/ENTRY
/RELEASE or SET QUEUE/ENTRY/NOHOLD command; to delete, specify
DELETE/ENTRY.

/NEXT queue-name
Stops the queue after all executing jobs have completed processing. No new jobs
can be initiated; the START/QUEUE command will restart the queue.

/PRIORITY=n
Requires OPER or ALTPRI privilege to raise the priority above the value of the
MAXQUEPRI parameter.
Changes the priority of the aborted job. Must be used with the /REQUEUE
qualifier. The value of n is an integer from 0 to 255 that specifies priority; the
default is the current priority of the job.

/REQUEUE[=queue-name]
Stops the current job and requeues it for later processing. Print jobs that have
been checkpointed will resume printing at the checkpoint. Batch jobs containing
SET RESTART—VALUE commands will run those portions of the job that have
not successfully completed. When you use /REQUEUE with a batch queue,
you must also use /ENTRY. If you specify a queue name, the current job is
transferred to another queue.

/RESET
Stops the queue without first terminating currently executing jobs. The START
/QUEUE command restarts the queue. Current jobs that are restartable (all
print jobs and any batch jobs submitted with the /RESTART qualifier) will be
requeued for processing. Current jobs that are not restartable are aborted and
must be resubmitted for processing.

dcl-202

DCL Commands
STOP/ABORT

STOP/ABORT queue-name[:]
Requires OPER privilege, EXECUTE access to the queue, or DELETE access to the
current job.
Aborts the executing print job, deleting it from the queue, and resumes execution of
jobs in the queue. (The STOP/ABORT command is equivalent to the STOP/QUEUE
/ABORT command.)
PARAMETERS

queue-name
The name of the queue in which the job is executing.

STOP/ENTRY =entry-number queue-name[:]
Requires OPER (operator) privilege, EXECUTE access to the queue, or DELETE access
to the current job.
Stops the specified job currently executing in the specified batch queue and resumes
execution of the next pending job in the queue. The job number is the number
assigned to the job when it is submitted to the queue. (The STOP/ENTRY command
is equivalent to the STOP/QUEUE/ENTRY command; use the DELETE/ENTRY
command to stop an entry that is queued and awaiting execution.)
PARAMETERS

queue-name
The name of the batch queue in which the job is executing.

STOP/QUEUE/MANAGER
Requires both OPER and SYSNAM privilege.
Performs an orderly shutdown of the system job queue manager.

STOP/REQUEUE [=queue-name] queue-name[:]
Requires OPER (operator) privilege, EXECUTE access to the queue or DELETE access
to the current job.
Stops the current job on the specified queue and requeues it for later processing;
execution of the next pending job in the queue resumes. Print jobs that have been
checkpointed will resume printing at the checkpoint. Batch jobs (specify /ENTRY)
containing SET RESTART—VALUE commands will run those portions of the job that
have not successfully completed.

DCL Commands

dcl-203

STOP/REQUEUE

PARAMETERS

queue-name
The first queue-name ([=queue-name]) optionally specifies a queue to which the
job is to be requeued. The second, required queue-name (queue-name[:]) specifies
the name of the queue in which the job is executing.
QUALIFIERS

/ENTRY=job-number
Required with batch queues to specify the job; the job-number is the number
assigned to the job when it was submitted to the queue.

/HOLD
Places the aborted job in a hold state for later release with the SET/QUEUE
/ENTRY/RELEASE or SET QUEUE/ENTRY/NOHOLD command. (Use
DELETE/ENTRY to delete a job in the hold state.)

/PRIORITY=n
Requires either OPER privilege or ALTPRI privilege to raise the priority value
above the value of the SYSGEN parameter MAXQUEPRI.
Changes the priority of the requeued job. The value of n can be from 0 to 255;
the default value of n is the job's current priority value.

SUBMIT file-spec,...
Requires OPER privilege, E (execute) access to the queue, or W (write) access to the
queue.
Queues a batch job.
PARAMETERS

file-spec
Name of a file containing a command procedure. Wildcard characters are
allowed. The file type defaults to COM. If a node name is specified, the
/REMOTE qualifier must also be specified.
QUALIFIERS

/AFTER=absolute-time
Holds the job until the specified time. If the time has passed, processes the job
immediately. Time can be an absolute time or a combination of absolute and
delta times.

dcl-204

DCL Commands
SUBMIT

/BACKUP
/NOBACKUP
Selects files according to the dates of their most recent backups. Relevant only
with the /BEFORE and /SINCE qualifiers.

/BEFORE[=time]
/NOBEFORE
Submits only those files dated before the specified time. You can specify time as
an absolute time, as a combination of absolute and delta times, or as one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

/BY_OWNER[=uic]
Submits only those files with the specified user identification code. The default
UIC is that of the current process.

/CHARACTERISTICS=(characteristic,...)
Specifies one or more characteristics for processing the job. A job must have all
the characteristics specified for the job (or it remains pending).

/CLI=file-spec
Specifies the command language interpreter (CLI) that will be used in processing
the job. The file name specifies that the CLI be SYS$SYSTEM:filename.EXE. The
default CLI is that defined in the user authorization file.

/CONFIRM
/NOCONFIRM (default)
Requests confirmation before submitting each file. The following responses are
valid:
YES

Submit the file

Do not submit the file

TRUE

Submit the file

FALSE

Do not submit the file

Submit the file

Do not submit the file

RETURN

Do not submit the file

ALL

Continue execution of the command with no further confirmation
prompts

DCL Commands

dcl-205

SUBMIT

CTRL/Z

Stop execution of the command

QUIT

Stop execution of the command

/CPUTIME=keyword
Specifies a CPU time limit for the batch job. Time can be specified as delta time,
0, NONE, or INFINITE. Both the value 0 and the keyword INFINITE allow
unlimited CPU time; the keyword NONE defaults to your user authorization file
(UAF) value or the limit specified on the queue. Note that you cannot specify
more time than permitted by the base queue limits or your own UAF.

/CREATED
/NOCREATED
Selects files based on their dates of creation. Relevant only with the /BEFORE
and /SINCE qualifiers.

/DELETE
/NODELETE (default)
Positional qualifier.
If you specify the /DELETE qualifier after the SUBMIT command name, all files
are deleted after executing them. If you specify the /DELETE qualifier after a file
specification, only that file is deleted after it is executed.

/EXCLUDE=(file-spec,...)
/NOEXCLUDE
Excludes files from the SUBMIT operation. The qualifier value file-spec cannot
include a device name. Wildcard characters are supported for file specifications.
However, you cannot use relative version numbers to exclude a specific version.

/EXPIRED
/NOEXPIRED
Selects files based on their dates of expiration. Relevant only with the /BEFORE
and /SINCE qualifiers.

/HOLD
/NOHOLD (default)
Holds the job (until released by the SET QUEUE/ENTRY command).

/IDENTIFY (default)
/NOIDENTIFY
Displays the queue name and job number of the job when it is queued.

dcl-206

DCL Commands
SUBMIT

/KEEP
/NOKEEP
Saves the log file after printing it; /NOKEEP is the default unless /NOPRINTER
is specified.

/LOG_FILE=file-spec
/NOLOG-FILE
Names the log file. The default is job-name.LOG. You can use /LOG_FILE to
specify a different device. Logical names in the file specification are translated in
the context of the process that submits the job.

/MODIFIED
/NOMODIFIED
Selects files according to the dates on which they were last modified. Relevant
only with the /BEFORE and /SINCE qualifiers.

/NAME=job-name
Names the job (and possibly the batch job log file). The name must be 1 through
39 alphanumeric characters. Enclose the name in parentheses if it contains any
special characters. The default is the name of the first file in the job.

/NOTIFY
/NONOTIFY (default)
Broadcasts a message to your terminal when the job completes.

/PARAMETERS=(parameter,...)
Provides the values of up to 8 optional parameters (equated to PI through P8,
respectively, in each command procedure in the job). The symbols are local
to the specified command procedure. If the parameter contains spaces, special
characters, or lowercase characters, enclose it in quotation marks. The size of
the parameter (including enclosing quotation marks and the preceding comma)
must not exceed 255 characters. However, the total length of all eight parameter
strings of the /PARAMETER qualifier cannot exceed 480 characters.

/PRINTER=queue-name
/NOPRINTER
Queues the log file to the specified queue for printing. The default is
SYS$PRINT.

/PRIORITY=n

Requires OPER or ALTPRI privilege to raise the priority above the value of the
MAXQUEPRI parameter.
Specifies the job-scheduling priority for the specified job. The value of n is
an integer from 0 to 255; the default is the value of the SYSGEN parameter
DEFQUEPRI.

DCL Commands

dcl-207

SUBMIT

/QUEUE=queue-name
Queues the job to the specified batch queue. The default is SYS$BATCH.

/REMOTE
Queues the job to a queue on another node. The node name must be included in
the file specification. No other qualifiers can be specified with /REMOTE.

/RESTART
/NORESTART (default)
Restarts the job after a system failure or a STOP/REQUEUE command.

/SINCE[=time]
/NOSINCE
Submits only those files dated after the specified time. You can specify time as
an absolute time, as a combination of absolute and delta times, or as one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

/USER=username
Requires CMKRNL privilege and R (read) access to the user authorization file
(UAF).
Submits a job for another user so that the job runs under the username and UIC
of the other user.

/WSDEFAULT=n
Defines a working set default for a batch job; the /WSDEFAULT qualifier
overrides the working set size specified in the user authorization file. Possible
values of n are a positive integer in the range 1 through 65,535, 0, or the
keyword NONE. A value of 0 or the keyword NONE sets the default value to
the value specified either in the UAF or by the working set quota established for
the queue. You cannot request a value higher than the default.

/WSEXTENT=n
Defines a working set extent for the batch job; the /WSEXTENT qualifier
overrides the working set extent in the user authorization file. Possible values of
n are a positive integer in the range 1 through 65,535, 0, or the keyword NONE.
A value of 0 or the keyword NONE sets the default value either to the value
specified in the UAF or set for the queue. You cannot request a value higher
than the default.

/WSQUOTA=n
Defines a working set page size (working set quota) for the batch job; the
/WSQUOTA qualifier overrides the value in the user authorization file. Possible
values of n are a positive integer in the range 1 through 65,535, 0, or the
keyword NONE. A value of 0 or the keyword NONE sets the default value to

dcl-208

DCL Commands
SUBMIT

the value specified either in the UAF or set for the queue. You cannot request a
value higher than the default.

SYNCHRONIZE [job-name]
Holds your process until the specified batch job terminates.
PARAMETERS

job-name
Name of the job (as specified in the SUBMIT command). If you have more
than one job with the same name, the synchronization occurs for the last job
submitted. The job name parameter is overridden by the /ENTRY qualifier.
QUALIFIERS

/ENTRY=job-number
Identifies the job by the system assigned job number. The /ENTRY qualifier
overrides any job name specified. You must specify either the job name or the
/ENTRY qualifier.

/QUEUE=queue-name
Names the queue containing the job. The default is SYS$BATCH.

TYPE file-spec,...
Displays a file or files in text format on SYS$OUTPUT (your terminal unless you
reassign SYS$OUTPUT).
PARAMETERS

file-spec
The specification of the file being displayed. Wildcard characters are allowed.
The plus sign can be used in place of the comma between file specifications. The
file type defaults to LIS.
QUALIFIERS

DCL Commands

dcl-209

type

/BEFORE[=time]
Displays only those files with dates that precede the specified time. You can
specify time as absolute or a combination of absolute and delta times, or as one
of the following keywords: TODAY (default), TOMORROW, or YESTERDAY.
Specified with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

/BY__OWNER[=uic]
Displays only those files with the specified user identification code. The default
UIC is that of the current process.

/CONFIRM
/NOCONFIRM (default)
Requests confirmation before displaying each file. The following responses are
valid:
YES

Type the file

Do not type the file

TRUE

Type the file

FALSE

Do not type the file

Type the file

Do not type the file

RETURN

Do not type the file

ALL

Continue execution of the command with no further confirmation
prompts

CTRL/Z

Stop execution of the command

QUIT

Stop execution of the command

/CREATED (default)
See /BACKUP.

/EXCLUDE=(file-spec,...)
Excludes the specified files from display. The qualifier value file-spec cannot
include a device name. Wildcard characters are supported for file specifications.
However, you cannot use relative version numbers to exclude a specific version.

/EXPIRED
See /BACKUP.

/MODIFIED
See /BACKUP.

dcl-210

DCL Commands
TYPE

/OUTPUT[=file-spec]
/NOOUTPUT
Names a file, rather than SYS$OUTPUT, to receive the typed output.

/PAGE
/NOPAGE (default)
Displays a screenful of the specified file with each RETURN.

/SINCE[=time]
Selects for display only those files dated after the specified time. You can specify
time as absolute or a combination of absolute and delta times, or as one of the
following keywords: TODAY (default), TOMORROW, or YESTERDAY. Specified
with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

UNLOCK file-spec,...
Makes an improperly closed file accessible.
PARAMETERS

file-spec
Specification of file to be unlocked. Wildcard characters are allowed. The plus
sign can be used in place of the comma between file names.
QUALIFIERS

/CONFIRM
/NOCONFIRM (default)
For each file being unlocked, displays a query to which you must respond Y or T
to unlock the file. Any other response aborts the unlock operation.

/LOG
/NOLOG (default)
Displays the file specification of each file being unlocked.

WAIT time
Puts your process into a wait state for the specified amount of time.
PARAMETERS

time
A time interval specified in the format hour:minute:second.hundredth, where
hour is an integer in the range 0 through 59; minute is an integer in the range
0 through 59; second is an integer in the range 0 through 59; hundredth (of

DCL Commands

dcl-211

WAIT

a second) is an integer in the range 0 through 99. The colons and period are
required delimiters. The format is hh:mm:ss.ss.

WRITE logical-name data-item,...
Writes the specified data item as one record to an open file specified by a logical
name. All qualifiers must precede all data-item expressions.
PARAMETERS

logical-name
Logical name of the output file. Use the logical name assigned by the OPEN
command, or, in interactive mode, specify SYS$INPUT, SYS$OUTPUT,
SYS$COMMAND, or SYS$ERROR to mean your terminal.

data-item
Symbol name, character string in quotation marks, literal numeric value, or a
list of expressions. Multiple data items are concatenated into one record which
cannot exceed 255 characters in length.
QUALIFIERS

/ERROR=label
Transfers control on an I/O error to the location specified by label (in a command
procedure). /ERROR overrides any ON condition action specified. The symbol
$STATUS retains the error code.

/SYMBOL
Causes the expression to be interpreted and its expanded value placed in a
2048-byte (instead of a 1024-byte) buffer before the WRITE operation is
performed. If you specify multiple expressions, their values are concatenated
and placed in the 2048-byte buffer. Each expression specified must be a symbol.

/UPDATE
Replaces the last record read with the specified data-item. The specified data item
must be exactly the same size as the record it is replacing. This qualifier can only
be used if the file is opened for both READ and WRITE access.

Appendix DSR
Digital Standard Runoff
Digital Standard Runoff (DSR) creates formatted files from input files consisting of
text, DSR commands, and DSR flags.

DSR.1

DCL Commands for Invoking DSR

Process DSR files with the RUNOFF, RUNOFF/CONTENTS, and RUNOFF/INDEX
commands. A positional qualifier is local when placed after a file name and global
when placed after the command name. A local qualifier applies only to the file it
follows; a global qualifier applies to all files unless overridden by a local qualifier.

RUNOFF dsr-file,...
Creates formatted files from source DSR (RNO) files, unformatted table of contents
(RNT) files, and unformatted index (RNX) files. Optionally creates intermediate
(BRN) files for input to RUNOFF/CONTENTS and RUNOFF/INDEX commands.
PARAMETERS

dsr-file
Specification of an input DSR file. Wildcard characters are not allowed. The
file type defaults to RNO; you must specify the file type for RNT and RNX
files. Specify SYS$INPUT to type the input from your terminal or a command
procedure; terminate input from the terminal by pressing CTRL/Z.
QUALIFIERS

/BACKSPACE
Positional qualifier
Bolds, overstrikes, and underlines by backspacing to each character after it is
printed, if the printer permits. Otherwise, these operations are implemented by
performing a carriage return without a line feed after the entire line is printed.

dsr-2

Digital Standard Runoff
DCL Commands for Invoking DSR

/BOLD[=overstrike] (default)
/NOBOLD
Positional qualifier
Specifies the number of times characters are overstruck in a bolding operation.
The value must be 0 or a positive integer and defaults to 1. A specification of
/BOLD=0 or /NOBOLD disables all bolding, even if the appropriate flags are
recognized and enabled.

/CHANGE__BARS[=character]
/NOCHANGE_BARS
Positional qualifier
Enables change bars (the .BEGIN BAR and .END BAR commands) starting at
the beginning of the DSR file (just as if you had included an .ENABLE BAR
command within the DSR file). The value specifies the character to be used for
the change bar and defaults to a vertical line (I). You can specify the change
bar character as a single printable character or a number preceded by a radix
indicator (%D, %0, or %X) to represent the ASCII value of a printable or
nonprintable character. (For example, you can specify /CHANGE_BARS=%D7
to ring the bell on terminal output.) A specification of /NOCHANGE_BARS
overrides any .ENABLE BAR command in the DSR file.

/DEBUG[=(option,...)]
/NODEBUG (default)
Positional qualifier
Traces certain operations by placing the DSR commands in the output file. The
options are as follows:
CONDITIONALS

Ignores conditional commands (.IF, .IFNOT, .ELSE, .ENDIF) in
processing the DSR file and places them in the output file.

FILES

Places .REQUIRE commands in the output file (as well as the text
of the required file).

INDEX

Places .INDEX and .ENTRY commands in the output file. Index
flags are represented by .INDEX commands before the lines on
which the flag occurs.

CONTENTS

Places .SEND TOC commands in the output file.

A specification of /DEBUG means /DEBUG=ALL.

/DEVICE[=(option,...)]
Positional qualifier
Produces an output file suitable for printing on an LN01 or an LN03 printer. The
options are as follows.

Digital Standard Runoff

dsr-3

DCL Commands for Invoking DSR

LN01

Designates a standard LN01 printer with a paper size of 8

LN01E

Designates a European LN01 printer with a paper size of

1/2 by 11 inches.

European A4. Incompatible with LN01.
LN03

Designates a standard LN03 printer with a paper size of 8

LANDSCAPE

Prints pages with the long dimension at top using a

1/2 by 11 inches.

smaller type size. Allowable page dimensions are 0 to 73
lines per page and 0 to 132 characters per line.
PORTRAIT (default)

Prints pages with the short dimension at top using a larger
type size. Allowable page dimensions are 0 to 66 lines
per page and 0 to 80 characters per line. Incompatible
with LANDSCAPE.
Italicizes characters flagged for underlining.

ITALIC (default)

Italicized

characters can also be bolded.
Underlines characters flagged for underlining. You cannot

UNDERLINE

underline more than 63 consecutive characters (counting a
space as a character). Incompatible with ITALIC.

/DOWN[=lines]
/NODOWN (default except for LN01 or LN03)
Positional qualifier
Shifts the entire page down the specified number of lines. A specifica¬
tion of /DOWN means /DOWN=5, but if you specify /DEVICE=LN01,
/DEVICE=LN01E, or /DEVICE=LN03, /DOWN defaults to /DOWN=3.

/FORM_SIZE=lines
Specifies the maximum number of lines per page including running heads and
running feet. Defaults to /FORM_SIZE=66, which is standard for 11-inch paper.
For laser printers, set the number of lines as follows:
Paper size

Lines

Mode

8.05

Landscape

8.28

Landscape (LN01E default)

8.51

Landscape (LN01, LN03 default)

11.00

Portrait (LN01, LN03 default)

11.66

Portrait (LN01E default)

12.33

Portrait

DSR-4

Digital Standard Runoff
DCL Commands for Invoking DSR

Paper size

Lines

Mode

13.00

Portrait

14.00

Portrait

/INTERMEDIATE[=file-spec]
/NOINTERMEDIATE (default)
Positional qualifier
Creates an intermediate file that can be used as input to a table of contents or
index operation. The directory and file name default to that of the DSR file. The
file type defaults to BRN.

/LOG
/NOLOG (default)
Writes a termination message after successful completion of the DSR operation.
(The message is always written if the operation fails.) The message states the
DSR version number, the number of diagnostic messages (if any), the number of
output pages, and the output file specification. If /INTERMEDIATE is specified,
the message also includes the number of index records produced and the number
of table of contents records produced.

/MESSAGES=(option,...)
Positional qualifier
Directs error messages to the terminal, to the output file, or to both. You cannot
suppress error messages entirely. The options are as follows:
OUTPUT

Output file

USER

Terminal

The default (if you do not specify the qualifier) is /MESSAGES=(OUTPUT,USER).

/OUTPUT[=file-spec] (default)
/NOOUTPUT
Positional qualifier
Specifies that an output file is to be produced and optionally names it. The
directory and file name default to that of the DSR file. The file type defaults to
one of the following:
BLB

For an RNB input file

CCO

For an RNC input file

DOC

For an RND input file

ERR

For an RNE input file

HLP

For an RNH input file

Digital Standard Runoff

DSR-5

DCL Commands for Invoking DSR

LNI

For an RNO input file with /DEVICE set to LN01, LN01E, or LN03

MAN

For an RNM input file

MEC

For an RNT input file

MEM

For an RNO input file with no /DEVICE specification

MEX

For an RNX input file

OPR

For an RNP input file

PLM

For an RNL input file

STD

For an RNS input file

If you specify /NOOUTPUT, no output file is produced.

/PAGES=“range”
Positional qualifier
Specifies the pages that will be produced from the output file. Defaults to all
pages. Specify the range as follows:

start-page-no:end-page-no,...
You can specify up to five ranges; you can omit the colon and the end page
number on the last range to mean the last page. You can omit the quotation
marks if you specify only one range. Page numbers must be specified in their
default form, not the form specified in a .DISPLAY command. You can specify
just the appendix letter or name to produce an entire appendix. You can specify
just the word INDEX to produce an entire index.

/PAUSE
/NOPAUSE (default)
Stops output at the end of each page during processing. You must press the
space bar to continue processing. Do not use /PAUSE if you name a spooled
device as the output file.

/REVERSE-EMPHASIS
Positional qualifier
Directs DSR to change the order in which flagged text is underlined on an output
device. If you use this qualifier, the printer first prints the characters to be
underlined, then issues a carriage return without a linefeed, and then prints the
underscores to underline the flagged text. If you view your file on the terminal,
the flagged characters are overwritten by the underline character.

/RIGHT[=spaces]
/NORIGHT (default except for LN01)
Positional qualifier
Shifts the text on each page to the right the specified number of spaces. This
qualifier does not affect the page width. A specification of /RIGHT means

dsr-6

Digital Standard Runoff
DCL Commands for Invoking DSR

/RIGHT=5. A specification of /RIGHT=0 means /NORIGHT. The defaults (if
/RIGHT is not specified) for LN01 files are as follows:
Mode

LN01

LN01E

LN03

Landscape

Portrait

/SEPARATE_UNDERLINE[=character]
Positional qualifier
Prints underlines as separate characters on the next line instead of overstriking
with underscores on the same line. The value specifies the character to be used
for the underline character and defaults to a hyphen (-). You can specify the
underline character as a single printable character or a number preceded by a
radix indicator (%D, %0, or %X) to represent the ASCII value of a printable or
nonprintable character.

/SEQUENCE
/NOSEQUENCE (default)
Positional qualifier
Precedes the lines in the output file with the line numbers of the corresponding
lines in the DSR file. Sequential numbering is used if line numbers were not
explicitly specified in the DSR file.

/SIMULATE
/NOSIMULATE (default)
Inserts blank lines instead of a form feed to cause an advance to the top of the
next page. Also stops output before the first page is processed; you must press
the space bar to continue processing. Do not specify /SIMULATE if you name a
spooled device as the output file.

/UNDERLINE—CHARACTER[=character]
/NOUNDERLINE_CHARACTER> RUNOFF
Positional qualifier
Specifies the character to be used for the underline character. Defaults to
an underscore (_). You can specify the underline character as a single
printable character or a number preceded by a radix indicator (%D, %0, or
%X) to represent the ASCII value of a printable or nonprintable character.
A specification of /NOUNDERLINE—CHARACTER overrides any .ENABLE
UNDERLINING command in the DSR file. Incompatible with
/SEPARATE -UNDERLINE.

Digital Standard Runoff

dsr-7

DCL Commands for Invoking DSR

/VARIANT=“variant,„.”
Positional qualifier
Identifies conditional structures in the DSR file. You must name conditional
structures introduced by .IF to process them. You must name conditional
structures introduced by .IFNOT to exclude them. You must not name
conditional structures introduced by .ELSE to process them. If you specify
only one variant, you do not need the quotation marks.

RUNOFF/CONTENTS intermediate-file,...
Creates an unformatted table of contents file from an intermediate file.
PARAMETERS

intermediate-file
Specification of an input intermediate file. Wildcard characters are not allowed.
The file type defaults to BRN. You can concatenate input files into a single output
file by connecting the input file specifications with plus signs. (If you separate
the input file specifications with commas, separate output files are created.)
QUALIFIERS

/BOLD
NOBOLD (default)
Bolds header titles that are flagged as bold in the text.

/DEEPEST_LEVEL=level
Writes header titles up to the specified level. Level must be an integer in the
range 1-6. The default is /DEEPEST_LEVEL=6.

/IDENTIFICATION
/NOIDENTIFICATION (default)
Displays the version number of the DSR table of contents facility.

/INDENT
/NOINDENT (default)
Indents each level of header titles another two spaces. The default indents all
levels after the first the same two spaces.

/LOG
/NOLOG (default)
Writes the name of each input file as it is processed and after it is processed, and
the name of each output file created. Error messages are always written.

dsr-8

Digital Standard Runoff
DCL Commands for Invoking DSR

/OUTPUT[=file-spec] (default)
/NOOUTPUT
Specifies that an output file is to be produced and optionally names it. The
directory and file name default to that of the DSR file. The file type defaults to
RNT. If you specify /NOOUTPUT, no output file is produced.

/PAGE_NUMBERS=(option,...)
Displays page number references in the table of contents according to the options
you specify.
RUNNING

Running page numbers (1, 2, 3, and so on)

NORUNNING (default)

Chapter-oriented page numbers (1-1, 1-2, and so on);
incompatible with RUNNING

LEVEL=number

The number of levels for which page numbers are
written (specification of LEVEL=0 writes no page
numbers); defaults to LEVEL=6

You can specify RUNNING or NORUNNING no matter how the text displays
page numbers.

/SECTION-NUMBERS (default)
/NOSECTION__NUMBERS
Writes section numbers to the table of contents.

/UNDERLINE
/NOUNDERLINE (default)
Underlines header titles that are flagged for underlining in the text.

RUNOFF/INDEX intermediate-file,...
Creates a DSR index file from an intermediate file.
PARAMETERS

Digital Standard Runoff

DSR-9

DCL Commands for Invoking DSR

QUALIFIERS

/IDENTIFICATION
/NOIDENTIFICATION (default)
Displays the version number of the DSR index facility.

/LINES_PER_PAGE=lines
Number of lines of index entries on each index page. Defaults to 55 lines. If
the original DSR file specifies other than a layout of 0 (.LAYOUT command)
and a page length of 58 (.PAGE SIZE command), you should explicitly specify
/LINES_PER_PAGE as follows: page length minus 3, minus 1 if subtitles are
used, minus the number of lines reserved by the layout at the bottom of the
page.

/LOG
/NOLOG (default)
Writes the name of each input file as it is processed and after it is processed, and
the name of each output file created. Error messages are always written.

/OUTPUT[=file-spec]
/NOOUTPUT
Specifies that an output file is to be produced and optionally names it. The
directory and file name default to that of the DSR file. The file type defaults to
RNX. If you specify /NOOUTPUT, no output file is produced.

/PAGE_NUMBERS=option
Displays page number references in the index according to the option you
specify.
RUNNING
NORUNNING (default)

Running page numbers (1, 2, 3, and so on)
Chapter oriented page numbers (1-1, 1-2, and so on);
incompatible with RUNNING

You can specify RUNNING or NORUNNING no matter how the text displays
page numbers.

/REQUIRE=file-spec
/NOREQUIRE (default)
Substitutes a user heading for the standard heading on the first page of the index.
The standard heading is the word INDEX centered on the first line, followed by
three blank lines. The substitute heading is contained in the file you specify
which can contain DSR commands and text. See also /RESERVE.

/RESERVE=lines
/NORESERVE (default)
Reserves space at the top of the first page of the index for a user heading.

DSR-io

Digital Standard Runoff
DSR Commands

DSR.2

DSR Commands

The DSR commands in the DSR file determine how the text will be formatted in the
output file. The format of a DSR command is as follows. The first character of a
command must be the control flag, which is a period by default.

.command-name [parameter,...][;]
You must observe the following rules:
•

Period in column 1—The control flag (a period by default) of the first command
on a line must be in column 1. No text can precede a command on a line.

•

Multiple commands on one line—You can place as many DSR commands on one
line as space permits except that commands taking text parameters may not be
followed by another command.

•

Text on a command line—You can follow a command with text if you terminate
the command with a semicolon. The text must immediately follow the
semicolon.

•

Comments—You can put a comment in your DSR file wherever you can put a
command, that is, as the first item on a line or one of a string of commands on
a line. Format a comment as follows. The first character of a comment must be
the comment flag, which is an exclamation point by default.

!Any text except a semicolon[;]

•

Separators—You must separate the command name from the first parameter and
parameters from one another if two consecutive entries are both alphabetic or
both numeric. Otherwise, you can choose to separate or not separate the entities.
Valid separators between commands and parameters are spaces and tabs. Valid
separators between parameters are spaces, tabs, and commas.

•

Abbreviations—Abbreviations exist for the DSR command names. The
abbreviations are listed in parentheses after the command names in the command
descriptions that follow.

•

Case—Command names can be in uppercase or lowercase.

•

Null parameters—You can enter a null value for a parameter by typing just a
comma.

Digital Standard Runoff

dsr-ii

DSR Commands

.APPENDIX (.AX) [title]
Starts an appendix by performing the following actions:
1.

Issues the commands:
.BREAK
.LEFT MARGIN 0
.SPACING 1
.FILL (if .AUTOJUSTIFY is in effect)
.JUSTIFY (if .AUTOJUSTIFY is in effect)
.PAGING
.PAGE

Inserts 12 blank lines.

Centers on the next line the word APPENDIX followed by a space and the letter
or name identifying the appendix.

Inserts one blank line.

Centers on the next line the specified title. The title is written in uppercase
unless case flags indicate otherwise.

Inserts three blank lines.

The appendix identifier is regulated by the .NUMBER APPENDIX and .DISPLAY
APPENDIX commands.
The title becomes the running head. Any subtitle in effect is blanked.

.AUTOJUSTIFY ( AJ)
Causes the following commands to issue .JUSTIFY and .FILL commands:
.APPENDIX
.CHAPTER
.HEADER LEVEL
.NOTE

Initial default.

.AUTOPARAGRAPH ( AP)
Causes a .PARAGRAPH command to be issued whenever a line begins with a space
or a tab. Cancels .AUTOTABLE if it is in effect. The .FILL command must be in
effect.

dsr-12

Digital Standard Runoff
DSR Commands

.AUTOSUBTITLE (.AST) [header-level]
Causes .HEADER LEVEL titles to be used for running head subtitles. Header-level
specifies the highest header level for which subtitles will be written and takes one of
the following forms:
•

Integer in the range 1 through 6—The exact header level.

•

Integer preceded by a plus sign—A value to be added to the last header level
specified in an .AUTOSUBTITLE command.

•

Integer preceded by a minus sign—A value to be subtracted from the last header
level specified in an .AUTOSUBTITLE command.

Header-level defaults to 1.
You must issue a .SUBTITLE command for .AUTOSUBTITLE to work. See
.SUBTITLE for other effects connected with subtitles.

Initial default: .AUTOSUBTITLE 1

.AUTOTABLE ( AT)
Causes a .PARAGRAPH command to be issued whenever a line does not begin with
a space or a tab. Cancels .AUTOPARAGRAPH if it is in effect. The .FILL command
must be in effect.

.BEGIN BAR ( BB)
Begins the insertion of change bars at the beginning of lines. The .ENABLE BAR
command must be in effect.

.BLANK (.B) [lines]
Issues a .BREAK command and inserts blank lines. Specify lines as either:
•

Zero or unsigned integer—The number of blank lines to be inserted.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Lines defaults to 1.
The .BLANK command does not work at the top of a page. (Use the .FIGURE
command.) The .BLANK command does not continue to the next page if lines is
greater than the number of lines left on the page. If the page contains a footnote, the
line directly above a footnote is considered the bottom of the page.

Digital Standard Runoff

dsr-13

DSR Commands

.BREAK (.BR)
Ends the current line without filling or justification. A .BREAK command immedi¬
ately following a .PARAGRAPH, .INDENT, .LEFT MARGIN, .AUTOPARAGRAPH,
or .AUTOTABLE command cancels any specified indentation.

.CENTER (.C) [line-size]
Issues a .BREAK command and centers the text that follows. Specify line-size as
follows:
•

Unsigned integer—Twice the value of the position that you want to center the
text around.

•

Integer preceded by a plus sign—A value to be added to the last centering
position used.

•

Integer preceded by a minus sign—A value to be subtracted from the last
centering position used.

Line-size defaults to the value of the left margin plus the value of the right margin,
which causes the text to be centered between the two margins.
The .CENTER command must be the last command on a line. Enter the text to be
centered on the next line or terminate the command with a semicolon and enter the
text to be centered immediately after the semicolon. The text must all be on one line.
The line can contain flags but not commands. The text can extend beyond margin
and page size settings but cannot extend to the left of position 0.

.CHAPTER (.CH) [title]
Starts a chapter by performing the following actions:
1.

Issues the commands:
.BREAK
.LEFT MARGIN 0
.SPACING 1
.FILL (if .AUTOJUSTIFY is in effect)
.JUSTIFY (if .AUTOJUSTIFY is in effect)
.PAGING
.PAGE

Inserts 12 blank lines.

Centers on the next line the word CHAPTER followed by a space and the
number of the chapter.

Inserts one blank line.

dsr-14

Digital Standard Runoff
DSR Commands

Centers on the next line the specified title. The title is written in uppercase
unless case flags indicate otherwise.

Inserts three blank lines.

The chapter number is regulated by the .NUMBER CHAPTER and .DISPLAY
CHAPTER commands.
The title becomes the running head. Any subtitle in effect is blanked.

.COMMENT ( !) [text]
Ignores the text for output processing.

.CONTROL CHARACTERS ( CC)
Accepts and places in the output file nonprinting characters (characters with ASCII
values in the ranges 0 through 31 and 127 through 160).

.DATE (.D)
Adds the date to running heads. You must issue a .SUBTITLE command for .DATE
to work. Either .LAYOUT 1 or .LAYOUT 2 overrides the .DATE command.

.DISABLE BAR ( DBB)
Disables the .BEGIN BAR and .END BAR commands. If .ENABLE BAR has been in
effect, .DISABLE BAR does not shift the lines of text back to their original positions.

Initial default.

.DISABLE BOLDING ( DBO)
Disables use of the bold flag.

.DISABLE HYPHENATION ( DHY)
Disables use of the hyphenation flag.

Digital Standard Runoff

dsr-15

DSR Commands

.DISABLE INDEXING ( DIX)
Disables use of the index flag and the commands .INDEX and .ENTRY.

.DISABLE OVERSTRIKING ( DOV)
Disables use of the overstrike flag.

.DISABLE TOC (.DTC)
Disables the collection of information for a table of contents.

.DISABLE UNDERLINING ( DUL)
Disables use of the underline flag.

.DISPLAY APPENDIX (.DAX) format-code
Issues a .BREAK command and defines the appearance of appendix identifiers.
Specify format-code as one of the following:
D

Decimal numbers

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

Initial default: .DISPLAY APPENDIX LU

dsr-16

Digital Standard Runoff
DSR Commands

.DISPLAY CHAPTER (.DCH) format-code
Issues a .BREAK command and defines the appearance of chapter identifiers. Specify

format-code as one of the following:
D

Decimal numbers

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

Initial default: .DISPLAY CHAPTER D

.DISPLAY ELEMENTS (.DLE) [“left”,]format-code[,‘“right"]
Issues a .BREAK command and defines the appearance of list-element identifiers.
The command must be specified after the .LIST command and before the first .LIST
ELEMENT command.
List-element identifiers consist of sequential numbers in the format specified by

format-code, preceded by the character specified as left and followed by the character
specified as right. Left, which must be a single character enclosed in quotation marks
or apostrophes, defaults to a space. Right, which must be a single character enclosed
in quotation marks or apostrophes, defaults to a period. Specify format-code as one
of the following:
D

Decimal numbers

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

A .DISPLAY ELEMENTS command remains in effect only until the .END LIST
command occurs. The next list uses the default appearance unless another .DISPLAY
ELEMENTS command is specified.

Digital Standard Runoff

DSR-17

DSR Commands

Default appearance of lists: .DISPLAY ELEMENTS ””,D,”.”

.DISPLAY LEVELS (.DHL) [format-code],...
Issues a .BREAK command and defines the appearance of section identifiers in section
headers. You can specify or omit up to six format-code values, one for each section
level. The first format-code value corresponds to section level 1, the second

format-code value to section level 2, and so on. If you omit a format-code value,
specify the comma unless no more values follow. Specify each format-code value as
one of the following:
D

Decimal numbers

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

Initial default: .DISPLAY LEVELS D,D,D,D,D,D

.DISPLAY NUMBER (.DNM) format-code
Issues a .BREAK command and defines the appearance of page numbers starting with
the next page number written. Specify format-code as one of the following:
D

Decimal numbers'

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

Initial default: .DISPLAY NUMBER D

dsr-18

Digital Standard Runoff
DSR Commands

.DISPLAY SUBPAGE (.DSP) format-code
Issues a .BREAK command and defines the appearance of subpage numbers starting
with the next page number written. (Subpage numbers are the numbers appended to
the page numbers on subpages, for example, page 1-12A.) Specify format-code as one
of the following:
D

Decimal numbers

Octal numbers

Hexadecimal numbers

Uppercase roman numerals

Lowercase roman numerals

Mixed case roman numerals (initial capitals)

Uppercase letters

Lowercase letters

Mixed case letters (initial capitals)

Initial default: .DISPLAY SUBPAGE LU

.ELSE variant
Starts the else portion of a conditional block. Variant must be the same value as in
the .IF command or .IFNOT command. The else portion is processed if the if or ifnot
portion of the conditional block is not processed; otherwise, the else portion is not
processed. Must be paired with an .IF or .IFNOT command.

.ENABLE BAR (.EBB)
Enables use of the .BEGIN BAR and .END BAR commands. Causes all further text to
be shifted three characters to the right to make room for the bars.

.ENABLE BOLDING ( EBO)
Enables use of the bold flag.

Initial default.

.ENABLE HYPHENATION ( EHY)
Enables use of the hyphenation flag.

Initial default.

Digital Standard Runoff

dsr-19

DSR Commands

.ENABLE INDEXING (.EIX)
Enables use of the index flag and the commands .INDEX and .ENTRY.

Initial default.

.ENABLE OVERSTRIKING ( EOV)
Enables use of the overstrike flag.

Initial default.

.ENABLE TOC (.ETC)
Enables the collection of information for a table of contents.

Initial default.

.ENABLE UNDERLINING ( EUN)
Enables use of the underline flag.

Initial default.

.END BAR (.EB)
Ends the insertion of change bars at the beginning of lines. Must be paired with a
.BEGIN BAR command.

.END FOOTNOTE (.EFN)
Ends a footnote and restores case, fill, justify, spacing, and margin settings to what
they were before the footnote began. Must be paired with a .FOOTNOTE command.

dsr-20

Digital Standard Runoff
DSR Commands

.END LIST (.ELS) [lines]
Ends a list and restores case, fill, justify, spacing, and margin settings to what they
were before the list began. Must be paired with a .LIST command. Specify lines as
one of the following:
•

Zero or unsigned integer—The number of blank lines to follow the list.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Lines defaults to the most recent skip lines setting in a .PARAGRAPH or .SET
PARAGRAPH command (parameter 2).

.END LITERAL ( EL)
Ends literal text. Must be paired with a .LITERAL command.

.END NOTE (.EN) [lines]
Ends a note and restores case, fill, justify, spacing, and margin settings to what they
were before the note began. Must be paired with a .NOTE command. Specify lines
as one of the following:
•

Zero or unsigned integer—The number of blank lines to follow the note.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Lines defaults to a value of 1.

.END SUBPAGE ( ES)
Issues the .BREAK command and begins a new page with normal page numbering.

.ENDIF variant
Ends a conditional block. Variant must be the same value as in the .IF or .IFNOT
command. Must be paired with an .IF or .IFNOT command.

.ENTRY (.Y) topic[> subtopic]...
Creates an index entry without a page reference. The parameters specify the text of
the entries. Subtopics are arranged alphabetically under topics.

Digital Standard Runoff

dsr-21

DSR Commands

.FIGURE (.FG) [lines]
Issues the .BREAK command and inserts the number of blank lines specified by lines.
If the current page does not have sufficient room for all the blank lines, the page is
ended and the blank lines are placed on the next page.

Lines must be specified as an integer in the range 1 through the maximum number
of lines permitted on the page (after header, footer, and forced blank lines are taken
into account). Lines defaults to a value of 1.

.FIGURE DEFERRED (.FGD) [lines]
Issues the .BREAK command and inserts the number of blank lines specified by lines.
If the current page does not have sufficient room for all the blank lines, text is added
until the page is complete and the blank lines are placed on the next page.

.FILL (.F)
Causes line endings in the DSR file to be treated as spaces. Lines are created in
the output file by accumulating words until the next word would exceed the right
margin. The .FILL command also restores: the most recent justification setting set by
a .JUSTIFY or .NO JUSTIFY command; any .AUTOPARAGRAPH or .AUTOTABLE
setting that was in effect.

Initial default.

.FIRST TITLE (.FT)
Permits a running head to be written on the first page unless a .CHAPTER or
.APPENDIX command is issued.

.FLAGS ACCEPT (.FL ACCEPT) [character]
Recognizes the accept flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the accept flag is
represented by an underscore (_).

Initial default.

dsr-22

Digital Standard Runoff
DSR Commands

.FLAGS ALL (.FL)
Permits recognition of all enabled flags.

Initial default.

.FLAGS BOLD (.FL BOLD) [character]
Recognizes the bold flag and optionally specifies a character to represent it. Character
must be specified as a single character. By default, the bold flag is represented by an
asterisk (*).

.FLAGS BREAK (.FL BREAK) [character]
Recognizes the break flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the break flag is
represented by a vertical bar (I).

.FLAGS CAPITALIZE (.FL CAPITALIZE) [character]
Recognizes the capitalize flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the capitalize flag is
represented by a left angle bracket ( < ).

.FLAGS COMMENT (.FL COMMENT) [character]
Recognizes the comment flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the comment flag is
represented by an exclamation point (!).

Initial default.

.FLAGS CONTROL (.FL CONTROL) [character]
Recognizes the control flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the control flag is
represented by a period (.).

Initial default.

Digital Standard Runoff

dsr-23

DSR Commands

.FLAGS HYPHENATE (.FL HYPHENATE) [character]
Recognizes the hyphenate flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the hyphenate flag is
represented by an equal sign ( = ).

.FLAGS INDEX (.FL INDEX) [character]
Recognizes the index flag and optionally specifies a character to represent it.

Character must be specified as a single character. By default, the index flag is
represented by a right angle bracket (> ).

.FLAGS LOWERCASE (.FL LOWERCASE) [character]
Recognizes the lowercase flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the lowercase flag is
represented by a backslash (\).

Initial default.

.FLAGS OVERSTRIKE (.FL OVERSTRIKE) [character]
Recognizes the overstrike flag and optionally specifies a character to represent it.

Character must be specified as a single character. By default, the overstrike flag is
represented by a percent sign (%).

.FLAGS PERIOD (.FL PERIOD) [character]
Recognizes the period flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the period flag is
represented by a plus sign (+).

.FLAGS SPACE (.FL SPACE) [character]
Recognizes the space flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the space flag is
represented by a number sign (#).

Initial default.

dsr-24

Digital Standard Runoff
DSR Commands

.FLAGS SUBINDEX (.FL SUBINDEX) [character]
Recognizes the subindex flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the subindex flag is
represented by a right angle bracket ( > ).

Initial default.

.FLAGS SUBSTITUTE (.FL SUBSTITUTE) [character]
Recognizes the substitute flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the substitute flag is
represented by a dollar sign ($).

.FLAGS UNDERLINE (.FL UNDERLINE) [character]
Recognizes the underline flag and optionally specifies a character to represent it.
Character must be specified as a single character. By default, the underline flag is
represented by an ampersand (&).

Initial default.

.FLAGS UPPERCASE (.FL UPPERCASE) [character]
Recognizes the uppercase flag and optionally specifies a character to represent it.

Character must be specified as a single character. By default, the uppercase flag is
represented by a circumflex (").

Initial default.

.FOOTNOTE ( FN)
Places the text that follows up to the .END FOOTNOTE command at the bottom of
the page if it fits, or at the bottom of the next page if it does not fit. Must be paired
with an .END FOOTNOTE command.
The .FOOTNOTE command does not provide any special formatting. Format the
footnote by including DSR commands within the footnote.
If the .NO PAGING command is in effect, all footnotes appear at the end of the
document.

Digital Standard Runoff

dsr-25

DSR Commands

.HEADER LEVEL (.HL) [level] [title]
Starts a section by performing the following actions:
1.

Issues the commands:
.BREAK
.TEST PAGE lines (as specified in .STYLE HEADER)
.SPACING 1
.FILL (if .AUTOJUSTIFY is in effect)
.JUSTIFY (if .AUTOJUSTIFY is in effect)

Writes the section number and header, formatted according to the .STYLE
HEADER values in effect.
Inserts punctuation and/or spacing according to the .STYLE HEADER values in
effect.

Level must be specified as one of the following:
•

Unsigned integer in the range 1 to 6—The exact level of the header.

•

Integer preceded by a plus sign—A value to be added to the last level specified
in a .HEADER LEVEL or .SET LEVEL command (or 1 if a level has not yet been
set).

•

Integer preceded by a minus sign—A value to be subtracted from the last level
specified in a .HEADER LEVEL or .SET LEVEL command (or 1 if a level has not
yet been set).

Level defaults to the value of the last level specified in a .HEADER LEVEL or .SET
LEVEL command (or 1 if the level has not yet been set).
The title must follow on the same line as the command with no intervening
semicolon. If the title exceeds the size of the output line, the first line is filled
(and justified if justification is in effect) and the title continues on the next line.
The title becomes the running head. Any subtitle in effect is blanked.

.HEADERS LOWER (.HD LOWER)
Writes in lowercase the word "page" that precedes the page number in some layouts.
Writes in lowercase the word "index" that is part of the page number in indexes.

DSR-26

Digital Standard Runoff
DSR Commands

-HEADERS MIXED (.HD MIXED)
Writes in lowercase with an initial capital the word "Page" that precedes the page
number in some layouts. Writes in lowercase with an initial capital the word "Index"
that is part of the page number in indexes.

Initial default.

.HEADERS [ON] ( HD)
Writes running heads on each page except the first (unless you also specify .FIRST
TITLE) according to the current .LAYOUT values.

Initial default.

.HEADERS UPPER (.HD UPPER)
Writes in uppercase the word "PAGE" that precedes the page number in some
layouts. Writes in uppercase the word "INDEX" that is part of the page number in
indexes.

-IF variant
Starts a conditional block and introduces the if portion of the block. The if portion
of the block is processed if variant is specified as a value of the /VARIANT qualifier
in the invoking DSR command. The .IF command must be paired with an .ENDIF
command. The conditional block can contain an .ELSE command.
You can nest one conditional block within another. The nested conditional block
must be entirely contained within the if or the else portion of the nesting block.

.IFNOT variant
Starts a conditional block and introduces the ifnot portion of the block. The ifnot
portion of the block is processed if variant is not specified as a value to the
/VARIANT qualifier in the invoking DSR command. The .IFNOT command must be
paired with an .ENDIF command and can be paired with an .ELSE command. The
.ELSE command must precede the .ENDIF command.
You can nest one conditional block within another. The nested conditional block
must be entirely contained within the if or the else portion of the nesting block.

Digital Standard Runoff

DSR-27

DSR Commands

.INDENT (.1) spaces
Issues a .BREAK command and indents a line of text. If you specify a .BREAK
command after .INDENT, the indent operation is canceled. Specify spaces as one of
the following:
•

Zero or unsigned integer—The number of spaces to indent to the right of the left
margin.

•

Integer preceded by a minus sign—The number of spaces to indent to the left of
the left margin. You cannot indent past position 0.

The parameter defaults to the value of the spaces parameter of the most recent
.PARAGRAPH or .SET PARAGRAPH command.
You can enter the line of text after the command (with an intervening semicolon) or
on the next line. The line cannot contain commands.

.INDEX (.X) topic[> subtopic...]
Creates an index entry with a page reference. The parameters specify the text of
the entries. Subtopics are arranged alphabetically under topics with their own page
references.

.JUSTIFY (.J)
Issues a .BREAK command and causes the text that follows to be justified—extra
spaces are inserted between words so that the last character on each line reaches the
right margin.

Initial default.

.KEEP (.K)
Causes blank lines in the input file to be inserted in the output file. The .NO FILL
command must be in effect.

dsr-28

Digital Standard Runoff
DSR Commands

.LAYOUT (.LO) code [.lines]
Issues a .BREAK command and specifies the format for page header and footer
information. Specify code as one of the following:
Code

Description

Running head appears in the upper left of the page. Page number and date appear
in the upper right.

Running head appears centered at the top of the page. Page number appears
centered at the bottom.

Running head appears at the top right of an odd-numbered page and the top left of
an even-numbered page. Page number appears centered at the bottom.

Running head appears in the upper left of the page. Date appears in the upper right.
Page number appears centered between hyphens at the bottom of the page. Page
numbers are consecutive through the entire document.

If code equals 1, 2, or 3, specify lines as an unsigned integer equal to the number of
lines below the last line of text that the page number will appear. If code equals 0,
do not specify lines.

Initial default: .LAYOUT 0

.LEFT MARGIN (.LM) position
Issues a .BREAK command and sets the position of the left margin. Specify position
as one of the following:
•

Unsigned integer—The exact position of the left margin.

•

Integer preceded by a plus sign—A value to be added to the current position of
the left margin.

•

Integer preceded by a minus sign—A value to be subtracted from the current
position of the left margin.

Position defaults to a value of 0.
The left margin must be greater than 0 and less than the right margin.

Initial default: .LEFT MARGIN 0

Digital Standard Runoff

DSR-29

DSR Commands

.LIST (.LS) [lines] [/‘character”]
Starts a list by performing the following actions:
1.

Issues a .BREAK command.

Issues the command .LEFT MARGIN 9 if the left margin is currently 0; otherwise,
issues the command .LEFT MARGIN +4.

Issues a .TEST PAGE command specifying for the lines parameter a value
of 2 plus the value of test-lines in the most recent .PARAGRAPH or .SET
PARAGRAPH command.

Specify lines as one of the following:
•

Zero or unsigned integer—The number of blank lines to be inserted before each
element in the list.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Specify character as a character enclosed in quotation marks or apostrophes. Each list
element is preceded by this character and two spaces. If you omit character, the list
elements are preceded by a sequence of numbers starting with number 1.
The .LIST command must be paired with an .END LIST command. A list can contain
.LIST ELEMENT commands. You can nest one list within another to a maximum
level of 14; a nested list must be entirely contained within one element of the nesting
list.

.LIST ELEMENT ( LE)
Issues a .BREAK command and writes the text that follows as a list element. The
text is terminated by either another .LIST ELEMENT command or an .END LIST
command.
You can specify .LIST ELEMENT without having issued a .LIST command. List
elements not enclosed in lists begin at the left margin and are numbered sequentially
throughout the entire document. Do not issue an .END LIST command.

dsr-30

Digital Standard Runoff
DSR Commands

.LITERAL ( LT)
Issues a .BREAK command, issues the command .RIGHT MARGIN 150, and writes
text as it appears in the input file until an .END LITERAL command occurs. Must
be paired with an .END LITERAL command. When .LITERAL is in effect, flags
are treated as text even if they are recognized and enabled. Commands and flags
in effect before the .LITERAL command are disabled (until the .END LITERAL
command occurs) except for .LEFT MARGIN, .TAB STOPS, the underline flag, and
the bold flag.

.NO AUTOJUSTIFY ( NAJ)
Disables the effects of the .AUTOJUSTIFY command.

.NO AUTOPARAGRAPH ( NAP)
Disables the effects of the .AUTOPARAGRAPH command.

Initial default.

.NO AUTOSUBTITLE ( NAST)
Disables the effects of the .AUTOSUBTITLE command.

.NO AUTOTABLE (.NAT)
Disables the effects of the .AUTOTABLE command.

Initial default.

.NO CONTROL CHARACTERS ( NCC)
Disables the effects of the .CONTROL CHARACTERS command.

Initial default.

.NO DATE ( ND)
Disables the effects of the .DATE command.

Initial default.

Digital Standard Runoff

dsr-31

DSR Commands

.NO FILL (.NF)
Issues a .BREAK command and disables the effects of the .AUTOPARAGRAPH,
.AUTOTABLE, .FILL, and .JUSTIFY commands.

.NO FLAGS ACCEPT (.NFL ACCEPT)
Disables recognition of the accept flag.

.NO FLAGS [ALL] (.NFL [ALL])
Does not permit recognition of flags except the comment and control flags.

Initial default.

.NO FLAGS BOLD (.NFL BOLD)
Disables recognition of the bold flag.

Initial default.

.NO FLAGS BREAK (.NFL BREAK)
Disables recognition of the break flag.

Initial default.

.NO FLAGS CAPITALIZE (.NFL CAPITALIZE)
Disables recognition of the capitalize flag.

Initial default.

.NO FLAGS COMMENT (.NFL COMMENT)
Disables recognition of the comment flag.

.NO FLAGS CONTROL (.NFL CONTROL)
Disables recognition of the control flag.

dsr-32

Digital Standard Runoff
DSR Commands

.NO FLAGS HYPHENATE (.NFL HYPHENATE)
Disables recognition of the hyphenate flag.

Initial default.
.NO FLAGS INDEX (.NFL INDEX)
Disables recognition of the index flag.

Initial default.
.NO FLAGS LOWERCASE (.NFL LOWERCASE)
Disables recognition of the lowercase flag.

.NO FLAGS OVERSTRIKE (.NFL OVERSTRIKE)
Disables recognition of the overstrike flag.

Initial default.
.NO FLAGS PERIOD (.NFL PERIOD)
Disables recognition of the period flag.

Initial default.
.NO FLAGS SPACE (.NFL SPACE)
Disables recognition of the space flag.

.NO FLAGS SUBINDEX (.NFL SUBINDEX)
Disables recognition of the subindex flag.

.NO FLAGS SUBSTITUTE (.NFL SUBSTITUTE)
Disables recognition of the substitute flag.

Initial default.

Digital Standard Runoff

dsr-33

DSR Commands

.NO FLAGS UNDERLINE (.NFL UNDERLINE)
Disables recognition of the underline flag.

.NO FLAGS UPPERCASE (.NFL UPPERCASE)
Disables recognition of the uppercase flag.

.NO JUSTIFY ( NJ)
Issues a .BREAK command and disables the effects of the .JUSTIFY command.

.NO KEEP(.NK)
Disables the effects of the .KEEP command.

Initial default.

.NO NUMBER ( NNM)
Suspends the writing of page numbers, unless .LAYOUT 3 is in effect.

.NO PAGING ( NPA)
Causes the document to be written without page breaks and without reserving room
for headers and footers.

.NO PERIOD ( NPR)
Disables the effects of the .PERIOD command.

.NO SPACE ( NSP)
Causes a space not to be inserted in place of a carriage return between two lines of
text. The .NO SPACE command must be placed between two lines of text and affects
only those lines. The .FILL command must be in effect.

dsr-34

Digital Standard Runoff
DSR Commands

.NO SUBTITLE ( NST)
Causes subtitles not to be written.

Initial default.

.NOTE (.NT) [title]
Performs the following actions:
1.

Issues a .BREAK command.

Issues a .TEST PAGE command specifying for the lines parameter the value of
test-lines in the most recent .PARAGRAPH or .SET PARAGRAPH command.

Issues the command .SKIP 1, writes the specified title, and issues the command
.SKIP 1. The title defaults to the word NOTE in uppercase.

If the left margin is set to position 0, issues the commands .LEFT MARGIN +8
and .RIGHT MARGIN -8. Otherwise, issues the commands LEFT MARGIN +4
and .RIGHT MARGIN -4.

Issues the command .FILL. Issues the command JUSTIFY if auto justification is
in effect. Writes the text that follows the .NOTE command until an .END NOTE
command occurs.

A .NOTE command must be paired with an .END NOTE command.

.NUMBER APPENDIX (.NMAX) [identifier]
Specifies the identifier of the next appendix as follows:
•

Character—A single character.

•

Character string—Up to five characters.

•

Unsigned integer—The sequence number of the letter in the alphabet: 1 means
A, 2 means B, 26 means Z, 27 means AA, and so on.

•

Integer preceded by a plus sign—A value to be added to the sequence number of
the current identifier.

•

Integer preceded by a minus sign—A value to be subtracted from the sequence
number of the current identifier.

Identifier defaults to a value of A.
If you do not explicitly provide an identification for the next appendix with the
.NUMBER APPENDIX command, the identifier assumes the value of the identifier of
the current appendix incremented by one.

Digital Standard Runoff

dsr-35

DSR Commands

Initial default: .NUMBER APPENDIX A

.NUMBER CHAPTER (.NMCH) number
Specifies the identifier of the next chapter as follows:
•

Unsigned integer—The number of the chapter.

•

Integer preceded by a plus sign—A value to be added to the number of the
current chapter.

•

Integer preceded by a minus sign—A value to be subtracted from the number of
the current chapter.

Number defaults to a value of 1.
If you do not explicitly provide an identification for the next chapter with the
.NUMBER CHAPTER command, the chapter assumes the value of the current
chapter number incremented by one.

Initial default: .NUMBER CHAPTER 1

.NUMBER LEVEL (.NMLV) [number],...
Specifies a base section number. You can specify up to six numbers: each number
corresponds to a level. Omit a level by including just the comma, except that trailing
commas can be omitted. A number defaults to the current number in effect for the
level. Specify each number as follows:
•

Unsigned integer—The number of the section for the indicated level.

•

Integer preceded by a plus sign—A value to be added to the current number for
the indicated level.

•

Integer preceded by a minus sign-A value to be subtracted from the current
number for the indicated level.

If you do not explicitly provide a number for the next section header with the
.NUMBER LEVEL command, the section header number assumes the value of the
current section header number incremented by one.

dsr-36

Digital Standard Runoff
DSR Commands

.NUMBER LIST (.NMLS) number
Specifies the number of the next element in a list.
If you do not explicitly provide a number for the next list element with the .NUMBER
LIST command, the list element number assumes the value of the current list element
number incremented by one.

.NUMBER [PAGE] (.NMPG) [number]
Resumes page numbering if .NO NUMBER is in effect. Sets the number of the next
page to the value of number, which must be one of the following:
•

Unsigned integer—The number of the next page.

•

Integer preceded by a plus sign—A value to be added to the current page
number.

•

Integer preceded by a minus sign—A value to be subtracted from the current
page number.

Number defaults to the current page number.
Do not use the .NUMBER PAGE command if the .LAYOUT 3 command is in effect.

.NUMBER RUNNING ( NMR) number
Sets the number of the next page to the value of number, which must be one of the
following:
•

Unsigned integer—The number of the next page.

•

Integer preceded by a plus sign—A value to be added to the current page
number.

•

Integer preceded by a minus sign—A value to be subtracted from the current
page number.

Number defaults to the current page number.
Use only if the .LAYOUT 3 command is in effect.

Digital Standard Runoff

dsr-37

DSR Commands

.NUMBER SUBPAGE (.NMSPG) [identifier]
Specifies the identifier of the next subpage as follows:
•

One or more characters—A letter such as A, B, Z, or AA.

•

Unsigned integer—The sequence number of the letter in the alphabet: 1 means
A, 2 means B, 26 means Z, 27 means AA, and so on.

•

Integer preceded by a plus sign—A value to be added to the sequence number of
the current identifier.

•

Integer preceded by a minus sign—A value to be subtracted from the sequence
number of the current identifier.

Identifier defaults to a value of A.
The .NUMBER SUBPAGE command issues a .SUBPAGE command if .SUBPAGE is
not already in effect.

.PAGE (.PG)
Issues a .BREAK command and starts a new page. The current page must contain at
least one line of text. The .PAGE command works even if .NO PAGING is in effect.

.PAGE SIZE (.PS) [max-lines], [running-width]
Issues a .BREAK command, sets a maximum for the number of lines of text on a
page, and sets the page width for writing running heads (does not affect normal
text). Specify max-lines as follows:
•

Unsigned integer—The maximum number of lines allowed.

•

Integer preceded by a plus sign—A value to be added to the current maximum.

•

Integer preceded by a minus sign—A value to be subtracted from the current
maximum.

Max-lines defaults to the current maximum. The maximum cannot be less than 13.
Specify running-width as follows:
•

Unsigned integer—The width of the page for writing running heads.

•

Integer preceded by a plus sign—A value to be added to the current width.

•

Integer preceded by a minus sign—A value to be subtracted from the current
width.

Running-width defaults to the current width. The width cannot exceed 150.

DSR-38

Digital Standard Runoff
DSR Commands

If the .NO PAGING command is in effect, the .PAGE SIZE command issues a
.PAGING command.

Initial default: .PAGE SIZE 58,70

.PAGING (PA)
Issues a .BREAK command and causes the document to be split into pages.

Initial default.

.PARAGRAPH (P) [spaces],[skip-lines],[test-lines]
Issues a .BREAK command followed by .TEST PAGE, .SKIP, and .INDENT
commands. Specify spaces as one of the following:
•

Zero or unsigned integer—The number of spaces to indent the first line of the
paragraph to the right of the left margin.

•

Integer preceded by a minus sign—The number of spaces to indent to the left of
the left margin. You cannot indent past position 0.

Specify skip-lines as one of the following:
•

Zero or unsigned integer—The number of blank lines to be inserted before the
paragraph.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Specify test-lines as a factor in determining the number of lines that must be left on
the page for the paragraph to start on the page. Otherwise, the paragraph starts on
the next page. The precise algorithm is as follows, where spacing is the current value
of the .SPACING command (initial default is 1):

(skip-lines + test-lines + 1 ) * spacing
All three parameters default to the values specified in the last .PARAGRAPH or .SET
PARAGRAPH command.

Initial default: .PARAGRAPH 5,1,2

Digital Standard Runoff

dsr-39

DSR Commands

.PERIOD ( PR)
Adds an extra space after a period (.), colon (:), question mark (?), or exclamation
point (!). The .FILL command must be in effect, the character must be followed by a
space or carriage return, and the character must not be preceded by the accept flag.

Initial default.

.REPEAT (.RPT) times, “characters”
Repeats the specified characters the specified number of times. The characters must
be enclosed in quotation marks or apostrophes. You cannot specify more than 150
characters.
If the .FILL command is in effect, the characters are repeated horizontally. If the
.NOFILL command is in effect, the characters are repeated vertically starting at the
left margin.

.REQUIRE (.REQ) “file-spec”
Processes the contents of another file as if those contents existed in place of the
.REQUIRE command. The file specification must be enclosed in quotation marks or
apostrophes. The file type defaults to RNO. A .REQUIRE command must be the last
command on a line.

.RESTORE (.RE)
Restores the formatting context saved by the last .SAVE command. Must be paired
with a .SAVE command.

.RIGHT (.R) [spaces]
Issues a .BREAK command and positions a line of text relative to the right margin. If
you specify a .BREAK command after the .RIGHT, the operation is canceled. Specify
spaces as one of the following:
•

Zero or an unsigned integer—The number of spaces to indent to the left of the
right margin. You cannot indent past position 0.

•

Integer preceded by a minus sign—The number of spaces to extend to the right
of the right margin.

Spaces defaults to 0.

dsr-40

Digital Standard Runoff
DSR Commands

You can enter the line of text after the command (with an intervening semicolon) or
on the next line. The line cannot contain commands.

.RIGHT MARGIN (.RM) [position]
Issues a .BREAK command and sets the position of the right margin. Specify position
as one of the following:
•

Unsigned integer—The exact position of the right margin.

•

Integer preceded by a plus sign—A value to be added to the current position of
the right margin.

•

Integer preceded by a minus sign—A value to be subtracted from the current
position of the right margin.

Position defaults to 70.
Initial default: .RIGHT MARGIN 70

.SAVE (.SA)
Saves the current formatting context which includes the following settings: date
status, fill, flags, headers, justification, keep status, margins, numbering, page size,
paging, paragraph parameters, spacing, subtitles, and tab stops. The .SAVE command
must be paired with a .RESTORE command. You can nest one saved-formatting
context within another to a depth of 20.

.SEND TOC (.STC) toc-line
Writes a line to the table of contents. The line can contain text, DSR commands, and
DSR flags.

.SET DATE (.SDT) [[day],[month],[year]]
Issues a .BREAK command and sets the date. Specify day, month, or year as follows:
•

Unsigned integer—The day of the month, month, or year. You can specify the
entire year or the last two digits.

•

Integer preceded by a plus sign—A value to be added to the current value of day,
month, or year.

•

Integer preceded by a minus sign—A value to be subtracted from the current
value of day, month, or year.

Digital Standard Runoff

dsr-41

DSR Commands

You can omit a parameter by including only the comma. Omitted parameters default
to the current values.
If you omit the parameters entirely, the date is reset to the current date (the date on
which the DSR processing occurs).

Initial default: .SET DATE current-date

.SET LEVEL (.SL) [level]
Sets the level used in .HEADER LEVEL commands. Specify level as one of the
following:
•

Unsigned integer in the range 1-6—The exact level of the header.

•

Integer preceded by a plus sign—A value to be added to the current level setting.

•

Integer preceded by a minus sign—A value to be subtracted from the current
level setting.

Level defaults to the last level specified in a .HEADER LEVEL or .SET LEVEL
command (or 1 if a level has not yet been set).

.SET PARAGRAPH (.SPR) [spaces],[skip-lines],[test-lines]
Sets the parameter values used in .PARAGRAPH commands. Specify spaces as one
of the following:
•

Zero or unsigned integer—The number of spaces to indent the first line to the
right of the left margin.

•

Integer preceded by a minus sign—The number of spaces to indent to the left of
the left margin. You cannot indent past position 0.

Specify skip-lines as one of the following:
•

Zero or unsigned integer—The number of blank lines to be inserted before the
paragraph.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

(skip-lines + test-lines + 1 ) * spacing

dsr-42

Digital Standard Runoff
DSR Commands

The parameters default to the values specified in the last .PARAGRAPH or .SET
PARAGRAPH command.

.SET TIME (.STM) [[hour],[minute],[second]]
Issues a .BREAK command and sets the time. Specify hour, minute, or second as
follows:
•

Unsigned integer—The hour of the day, minute of the hour, or second of the
minute.

•

Integer preceded by a plus sign—A value to be added to the current hour,
minute, or second.

•

Integer preceded by a minus sign—A value to be subtracted from the current
hour, minute, or second.

You can omit parameters by including only the comma. Omitted parameters default
to the current values.
If you omit the parameters entirely, the time is reset to the current time (the time at
which the DSR processing occurs).

Initial default: .SET TIME current-time

.SKIP (.S) [lines]
Issues a .BREAK command and inserts blank lines. Lines must be one of the
following. The value is multiplied by the current value of the .SPACING command
(initial default is 1).
•

Zero or unsigned integer—The number of blank lines to be inserted.

•

Integer preceded by a minus sign—The number of lines from the bottom of the
page where writing will resume.

Lines defaults to a value of 1.
The .SKIP command does not work at the top of a page unless lines is negative. (Use
the .FIGURE command.) The .SKIP command does not continue to the next page
if lines is greater than the number of lines left on the page. If the page contains a
footnote, the line directly above the footnote is considered the bottom of the page.

Digital Standard Runoff

dsr-43

DSR Commands

.SPACING (.SP) lines
Sets the spacing between lines of text, where 1 means single spacing (no blank
lines between lines of text), 2 means double spacing, and so on. The following
commands multiply a lines specification by the current .SPACING value to determine
the number of physical lines: .AUTOPARAGRAPH, .AUTOTABLE, .PARAGRAPH,
.SET PARAGRAPH, and .SKIP.
Specify lines as an integer in the range 1 through 5.

Initial default: .SPACING 1

.STYLE HEADERS (.STHL) [code],...
Issues a .BREAK command and sets the formatting for level headers. You can specify
up to nine codes as follows. The codes must be written in the specified position.
Specify a default value by including just the comma.
1.

Run-in format—An integer in the range 0 through 7 specifying the lowest
numbered level of header to have a run-in format. (A run-in format starts the
text on the same line as the header.) Defaults to 3.

Uppercase title—An integer in the range 0 through 7 specifying the highest
numbered level of header to have its title written in all uppercase letters.
Overrides any conflicting code 3 setting. Defaults to 1.

Initial capitals in title—An integer in the range 0 through 7 specifying the highest
numbered level of header to have its title written in uppercase and lowercase
(that is, initial capitals). Defaults to 6.

Section number—An integer in the range 0 through 7 specifying the lowest
numbered level of header not to have a section number written to the left of the
title. Defaults to 7.

Centered title—An integer in the range 0 through 7 specifying the lowest
numbered level of header to have its header centered. (However, run-in headers
are not centered.) Defaults to 7.

Preceding blank lines—An unsigned integer specifying the number of blank lines
preceding a header. Defaults to 2.

Following blank lines—An unsigned integer specifying the number of blank lines
following a header. Defaults to 1.

Test page lines—An unsigned integer specifying the number of lines that must
be left on a page for the level header to be written to that page. Otherwise,
the header is written at the top of the next page. Defaults to 7 plus the most
recent value specified for the test-lines parameter of a .PARAGRAPH or .SET
PARAGRAPH command.

dsr-44

Digital Standard Runoff
DSR Commands

Spaces after section number—An integer in the range 1 through 75 specifying
the number of spaces between the header number and title. Defaults to 2.

Initial default: .STYLE HEADERS 3,1,6,7,7,2,1,9,2

.SUBPAGE ( SPG)
Issues a .BREAK command and starts a new page. Initiates subpage numbering: each
page has the number of the most recent page immediately followed by a subpage
appendix. For example, page 1-12 might be followed by subpages 1-12A and 1-12B.
Must be paired with an .END SUBPAGE command.

.SUBTITLE (.ST) [subtitle]
Issues a .BREAK command and sets subtitle as the running head to be used. Subtitle
must be specified as a character string. A .SUBTITLE command must be the last
command on a line.

.TAB STOPS (.TS) [position],...
Sets the tab stops. Specify position as one of the following:
•

Unsigned integer—The exact position of the tab stop.

•

Integer preceded by a plus sign—A value to be added to the current position of
the tab stop.

•

Integer preceded by a minus sign—A value to be subtracted from the current
position of the tab stop.

Tab stops are set left to right as specified. Each tab stop must be at least two greater
than the preceding tab stop. You can retain the value of the previous tab stop by
specifying just a comma; you must specify the commas to retain trailing tab stops.

Initial default: .TAB STOPS 8,16,24,...

.TEST PAGE (.TP) lines
Issues a .BREAK command and checks the current page for the specified number of
remaining lines. If the page does not contain enough room for the specified number
of lines, a new page is started. Lines must be specified as an unsigned integer.

Digital Standard Runoff

dsr-45

DSR Commands

.TITLE (.T) [title]
Issues a .BREAK command and sets title as the running head title to be used.
Title must be specified as a character string. A .TITLE command must be the last
command on a line.

.VARIABLE (.VR) name [true, false]
Identifies text and commands contained in conditional blocks if the /DEBUG qualifier
is specified with the RUNOFF command.

Name must be the name of a variable in an .IF or .IFNOT command. The .IF or
.IFNOT command must follow the .VARIABLE command.

True must be a single character. This character (followed by a space) will appear as
the first character of each line which is true for the specified variable.
False must be a single character. This character (followed by a space) will appear as
the first character of each line which is false for the specified variable.

.XLOWER ( XL)
Uppercases and lowercases index entries exactly as they appear in the DSR file.

.XUPPER ( XU)
Uppercases the first character of an index entry and lowercases the remaining
characters, except where explicitly overridden by the capitalize or uppercase flag.

Initial default.

DSR.3

DSR Flags

The following conditions must be met for a flag to be used:
•

Master recognition—The .FLAGS ALL command must be in effect, except for the
comment and control flags.

•

Individual recognition—The specific .FLAGS command must be in effect.

•

Individual enabling—The specific .ENABLE command must be in effect.

If a character is not recognized as a flag, the character is treated as normal text. If
a character is not enabled as a flag, the character does not cause the flag action to
occur.

The flags are as follows. The second column lists the initial default character
representing each flag.
Flag Name

Description

—

Treats the next character as text even if the character is a flag that is
in effect, a period, or a space.

BOLD

Writes the next character in bold (by overstriking).

BREAK

Permits a word to be broken between lines at the point where the
flag appears. No hyphen is automatically inserted.
<

CAPITALIZE

COMMENT

CONTROL

Capitalizes all characters that follow until one of the following
occurs: an expandable space, a BREAK flag, a HYPHENATE
flag, a CAPITALIZE flag, a pair of UPPERCASE flags, a pair of
LOWERCASE flags, the end of the line.
Treats the characters that follow as a comment until a semicolon or
the end of the line occurs. A comment can only occur where a DSR
command is legal; otherwise, the COMMENT flag is treated as text.
Treats the characters that follow as a DSR command until a
semicolon or the end of the line occurs. The CONTROL flag is
treated as text if it occurs where a DSR command is not legal.

HYPHENATE

Permits a word to be broken between lines at the point where the
flag appears. A hyphen is automatically inserted.

INDEX

Treats the characters that follow as an index entry.

LOWERCASE

Lowercases the next character.

OVERSTRIKE

Overstrikes the preceding character with the next character.

PERIOD

Inserts an expandable space when the flag is placed after the last
character in a word.

SPACE

Produces one unexpandable space. The word preceding the flag, the
flag, and the next word are all treated as one word in processing.

SUBINDEX

In an .INDEX command, treats the characters that follow as a
subentry. In an .ENTRY command, treats the characters that follow
as a cross-reference.

SUBSTITUTE

Must be paired with itself. See the next table.

UNDERLINE

&
*

Underlines the next character.

UPPERCASE

Uppercases the next character.

The following flag pairs can be used. The second column lists the default characters
representing each flag pair.

Flag Pair

Description

CONTROL COMMENT

Makes an entire line a comment.

CONTROL CONTROL

Inserts an actual period in the text.

LOWERCASE BOLD

Ends the bolding of characters.

LOWERCASE LOWERCASE

Writes the text that follows in lowercase un
another case flag occurs.

LOWERCASE UNDERLINE

Ends the underlining of characters.

SUBSTITUTE SUBSTITUTE

Inserts the date, time, or a part of the date
or time depending on a keyword that follo
the SUBSTITUTE SUBSTITUTE flag pair. T
keyword must immediately follow the flag
and can be uppercase or lowercase. The va
keywords are as follows: DATE, TIME, YE
MONTH, DAY, HOURS, MINUTES, SECO

UNDERLINE SPACE

Inserts an actual underscore into the text.

UPPERCASE BOLD
UPPERCASE CAPITALIZE

Bolds the characters that follow until a
LOWERCASE BOLD flag pair occurs.
A <

Capitalizes the characters that follow until
another case flag occurs.

UPPERCASE UNDERLINE

Underlines the characters that follow until
LOWERCASE UNDERLINE flag pair occurs

UPPERCASE UPPERCASE

Writes the text that follows as it appears in
DSR file until another case flag occurs.

DSR.4 Index Formatting
Indexes are formatted according to the following rules:
•

Punctuation—A comma separates an index entry or subentry from its page
reference. Commas separate multiple page references for the same entry. N
comma follows an entry that does not have a page reference.

•

Position of subentries—Subentries are positioned under an entry and inden
two spaces on their own lines.

•

Case—The .XLOWER and .XUPPER commands control whether index entri
uppercase or lowercase.

•

Merging—Index entries merge with other entries having identical spelling,
spacing, punctuation, and emphasis.

If .XLOWER is in effect, uppercase characters sort before lowercase characte
.XUPPER is in effect, uppercase and lowercase entries are merged.

dsr-48

Digital Standard Runoff
Index Formatting

Entries with different emphasis are sorted in the following order: bolded and
underlined, bolded, underlined, no emphasis.
•

Sorting .ENTRY entries—Entries without page references are sorted at the
beginning of each subindex level.

Appendix EDT
EDT Editor
The following appendix lists the specifications of the DCL command EDIT which
invokes the EDT editor, the keypad and line editing commands available in EDT,
and the nokeypad-editing commands used to redefine keys in EDT.

EDT.1

EDIT Command

Use the DCL EDIT command to invoke EDT.

EDIT/EDT file-spec
Invokes the EDT editor.
PARAMETERS

file-spec
Specification of the file being edited.
QUALIFIERS

/COMMAND=file-spec (default)
/NOCOMMAND
Determines whether EDT executes a startup command file before the editing
session begins and the specification of that command file. The default is
/COMMAND=[default-directory]EDTINI.EDT.

/CREATE (default)
/NOCREATE
Determines whether EDT creates a new file when the specified input file is not
found.

EDT-2

EDT Editor
EDIT Command

/JOURNAL=file-spec (default)
/NOJOURNAL
Determines whether EDT keeps a journal file during an editing session and the
specification of that journal file. The default is /JOURNAL=filename.JOU, where
filename is the name of the file being edited.

/OUTPUT=file-spec (default)
/NOOUTPUT
Determines whether EDT creates an output file during the editing session and
specifies the name of the output file. The default is /OUTPUT=input-file-spec,
where the file name and type remain unchanged and the version number is
incremented by one.

/READ-ONLY
/NOREAD-ONLY (default)
Determines whether both an output file and a journal file are created. With
the default, /NOREAD_ONLY, EDT maintains the journal file in case an
interruption occurs and creates an output file when the EXIT command is issued.
Use the /READ-ONLY qualifier when you are merely looking at a file and
do not intend to make any changes to it. When you use the /READ-ONLY
qualifier, enter the QUIT command to exit from EDT (unless you want to specify
an output file name with the EXIT command).

Invokes EDT to edit the highest version of the file CHAP.TXT. EDT attempts to read
and execute an EDTINI.EDT file in your default directory, creates a journal file, and
when you exit from EDT creates an output file named CHAP.TXT with the highest
version number.
$ EDIT/NOCOMMAND OLDFILE.DAT/OUTPUT=NEWFILE.DAT

Invokes EDT to edit the highest version of the file OLDFILE.DAT, prevents EDT
from attempting to read a startup command file, and creates an output file with the
name NEWFILE.DAT.
$ EDIT/READ.ONLY OLDFILE.DAT

Invokes EDT to read the file OLDFILE.DAT without creating a journal file and
without creating an output file.

EDT Editor

EDT-3

EDIT Command

$ EDIT/RECOVER CHAP.TXT
Invokes EDT to recover edits made during a previously aborted editing session. EDT
reads and executes the editing commands in the journal file CHAP.JOU. Once the
file has finished processing CHAP.JOU, it returns control to the user.

EDT.2

EDT Keypad Editing

In EDT keypad-editing mode, you use keypad keys and control keys to perform
editing functions. To enter change mode for EDT keypad editing you must enter the
EDT line-editing command CHANGE; text appears on the screen and the
keypad-editing keys immediately assume their editing functions.

EDT.2.1 Keypad Commands
Each key on the keypad performs at least one editing command; most perform two.
Pressing a key invokes the primary (or upper) function. Pressing the GOLD key
(labeled PF1) first and then pressing the desired key invokes the alternate (or lower)
function. (Do not hold down the GOLD key while pressing the other editing key.)
In examples, GOLD key sequences are shown with the word GOLD followed by
a backslash (\) and the other editing key. On VT200 series terminals there is a
smaller supplemental editing keypad located between the main keyboard and the
EDT keypad. See Section EDT.2.3 for more information on the supplemental editing
keypad.

EDT Editor

edt-4

EDT Keypad Editing

PF2

PF1
GOLD

HELP

PF3
FNDNXT

PF4
DEL L

FIND

UND L

PAGE

SECT

9
APPEND

DEL W

COMMAND

FILL

REPLACE

UND W

4
ADVANCE

5
BACKUP

BOTTOM

TOP

>
CUT

DEL C

PASTE

UND C

ENTER

WORD

EOL

CHAR

CHNGCASE

DEL EOL

SPECINS

ENTER

•

0
LINE

SELECT

OPEN LINE

RESET

SUBS

ZK-1688-84

The diagram above each command description represents the EDT keypad shown
above.
ADVANCE

□□□
□□□
□□□
mo
Sets the cursor direction forward, from top to bottom of the buffer, for the following
commands: CHAR, WORD, FIND, FNDNXT, CHNGCASE, LINE, EOL, PAGE,
SECT, and SUBS, and remains in effect until after you press BACKUP.

EDT Editor

EDT-5

EDT Keypad Editing

APPEND

□□□
□□□
□□□
nzo
Deletes the select range (see SELECT) and stores it at the end of the PASTE buffer
without otherwise modifying the PASTE buffer's original contents.
BACKUP

□□□
□□□
□□□
i in
Sets cursor direction backward, from bottom to top of buffer, for the following
commands: CHAR, WORD, FIND, FNDNXT, CHNGCASE, LINE, EOL, PAGE,
SECT, and SUBS, and remains in effect until you press ADVANCE.
BOTTOM

□□□
□□□
i in
Moves the cursor to the end, or bottom, of the buffer.
CHAR

□□□
□□□
□□□
mn
Moves the cursor one character in the current direction (depending upon whether
ADVANCE or BACKUP is set.)

EDT-6

EDT Editor
EDT Keypad Editing

CHNGCASE

□□□
□□□
mo
Changes the case (from uppercase to lowercase, or lowercase to uppercase) of all
letters in the selected range (see SELECT) or search string (see SET SEARCH).
If there is no selected range or the cursor is not positioned on the search string,
CHNGCASE changes the case of the current character.
COMMAND

□□□
□□□
□□
Invokes the "Command:" prompt for entering a line-editing command. Use the
ENTER key to process a line-editing command issued at the "Command:" prompt.
CUT

□□□
□□□
□□□
i in
Deletes the selected range (see SELECT) from the current buffer and places the text
in the PASTE buffer.
DEL C

□□□□
□□□□
□□□■

□□□n
□□u
Deletes the character on which the cursor is positioned.

EDT Editor

EDT-7

EDT Keypad Editing

DEL EOL

□□□
□□□
□□
Deletes the text from the cursor to the end of the current line, excluding the line
terminator. If the cursor is already at the end of a line, DEL EOL deletes the next
line.
DEL L

□□□■
□□□
□□□
□□□
rzo

Deletes text from the cursor to the end of the line, including the line terminator. If
the cursor is at the beginning of the line, the entire line is deleted, positioning the
cursor at the beginning of the next line.
DEL W

□□□□
□□□■
□□□□

□□u
Deletes the text from the cursor to the first character of the next word. The line
terminator (EOL) is treated as a word by the DEL W command.
ENTER

□□□□
□□□□
□□□□
□□□■
i nm

edt-8

EDT Editor
EDT Keypad Editing

Enters the response to a "Search for:" or "Command:" prompt, or completes the
processing of the key definition operation.
EOL

□□□
□□□
□□□
mo
Moves the cursor to the end of the current line or the previous line (depending upon
whether ADVANCE or BACKUP is set). If the cursor is already at the end of the line,
EOL moves it to the end of the next or previous line.
FILL

□□□
□□□
1 ILJ
Formats a select range of text by filling each line with as many whole words as
possible within the defined line width. (The SET WRAP command defines line
width.)
FIND

□□□
□□□
□□□
□□
Elicits the "Search for:" prompt as the first step in the FIND operation. The
command sequence is: FIND (type the search string after the prompt) and ENTER (or
ADVANCE or BACKUP). If the string is found, the cursor moves to the first character
in the string; otherwise, the cursor remains in place and the message "String was not
found" appears. The default search string is the line terminator (EOL).

EDT Editor

EDT-9

EDT Keypad Editing

FNDNXT

□□□
□□□
□□□
i in
When pressed before another keypad key, specifies that key's alternate function.
When pressed before a number and another keypad command, GOLD causes the
command to be performed the number of times specified by the number. When used
with SPECINS, inserts a character from the DEC Multinational Character set (see
SPECINS command). GOLD can be used to define GOLD/keyboard key sequences
(see CTRL/K).
HELP

□□□
□□□
□□□
□□
Displays a diagram of keypad keys. When one of the keys is pressed after HELP,
information about that key is displayed. This function has no effect on the text you
are editing. Press the spacebar to return to keypad editing.

EDT-10

EDT Editor
EDT Keypad Editing

LINE

□□□
□□□
□□□
□□□
mn
Moves the cursor to the beginning of the next or previous line (depending upon
whether ADVANCE or BACKUP is set).
OPEN LINE

□□□
□□□
□□□
HID
Inserts a line terminator at the current cursor position.
PAGE

□□□
□□□
□□□
□□
Moves the cursor to the next or previous page boundary (depending upon whether
ADVANCE or BACKUP is set). The page entity defaults to the text between form
feeds and can be defined with the SET ENTITY command.

EDT Editor

EDT-11

EDT Keypad Editing

PASTE

□□□
□□□
CUD
Inserts the contents of the PASTE buffer (the text last affected by the CUT or
APPEND command) at the cursor's current position, positioning the cursor at the
end of the inserted text.
REPLACE

□□□
□□□
rnn
Deletes the selected range and replaces it with the contents of the PASTE buffer (the
text last affected by the CUT or APPEND command). The command sequence is:
store the new text in the PASTE buffer with SELECT and CUT; locate the old text
with FIND and ENTER; mark a selected range of the text to be replaced; and press
REPLACE. If a range of text to be replaced is not selected, the text of the search
string will be replaced.
RESET

■□□□
□□□□
□□□□

□■u
Cancels a selected range, and sets EDT's current direction to ADVANCE.

edt-12

EDT Editor
EDT Keypad Editing

SECT

□□□
□□□
□□□
□□
Moves the cursor 16 lines in the current direction (depending upon whether
ADVANCE or BACKUP is set).
SELECT

□□
□□□ □□□
□□□
□ □□

Marks the current cursor position as the beginning of a selected range. The
selected range consists of all the text between this marked position and the cursor's
subsequent position at the other end of the selected text.
SPECINS

□□□
□□□
run
Inserts a character (using its decimal value) from the DEC Multinational Character
set (see Appendix CHAR). The command sequence is: GOLD, the decimal value of
the character, GOLD, and SPECINS.

EDT Editor

EDT-13

EDT Keypad Editing

SUBS

■ □□□
□ □□□
□ □□□
□ □□■
Deletes the selected range, replaces it with the contents of the PASTE buffer, and
moves the cursor (in the direction set by ADVANCE or BACKUP) to the next
occurrence of the search string. The command sequence is: store the new text in
the PASTE buffer with SELECT and CUT; locate the old text with FIND and ENTER;
replace the old text with the new text and find the next occurrence of the search
string using SUBS. If the string is not found, the cursor remains in place and the
message "String was not found" appears. If the string is found, you can replace any
subsequent occurrences of the search string by entering SUBS.
TOP

□□□
□□□
][
Moves the cursor to the beginning, or top, of the buffer.
UND C

■□□□
□□□■

□□□□
Inserts at the cursor's current position the character most recently deleted with DEL
C or DELETE.

EDT-14

EDT Editor
EDT Keypad Editing

UND L

□□□
□□□
□□□
rnn
Inserts at the cursor's current position the line of text most recently deleted with DEL
L, DEL EOL, or CTRL/U.
UND W

■□□□
□□□■
□□□□
cudJ
Inserts at the cursor's current position the word most recently deleted with DEL W or
LINEFEED.
WORD

□□□
□□□
□□□
□□
Moves the cursor one WORD in the current direction (depending upon whether
ADVANCE or BACKUP is set). You can define the WORD entity with the SET
ENTITY command.
You can use the following directional keys:
DOWN ARROW

Moves the cursor to the character in the line directly below. If the
line of text below does not extend as far as the cursor's position,
DOWN ARROW places the cursor on the last character (EOL) in the
line below.

EDT Editor

edt-15

EDT Keypad Editing

LEFT ARROW

Moves the cursor one character to the left. If the cursor is at the left
margin, LEFT ARROW moves the cursor to the last character (EOL)
in the previous line.

RIGHT ARROW

Moves the cursor one character to the right. If the cursor is at the
end of the line (EOL), RIGHT ARROW moves it to the leftmost
character in the next line.

UP ARROW

Moves the cursor to the character in the line directly above. If
the line of text above does not extend as far as the current cursor
position, UP ARROW places the cursor at the last character (EOL) in
the line above.

EDT.2.2 Keyboard Keys
You can use the following keyboard keys to supplement the keypad:
•

FI 2 (the BACKSPACE key on VT100 series terminals)—Moves the cursor to the
beginning of the current line. If the cursor is already at the beginning of a line,
FI2 (BACKSPACE) moves it to the beginning of the previous line.

•

The Delete (O ) key (DELETE on VT100 series terminals)—Deletes the
character to the left of the cursor.

•

FI3 (the LINEFEED key on VT100 series terminals)—Deletes the text from the
cursor back to the beginning of the word. If the cursor is on the first character in
a word, FI3 (LINEFEED) deletes the previous word.

•

RETURN—Inserts a line terminator at the current cursor position.

•

TAB—Moves the text to the next tab stop.

EDT-16

EDT Editor
EDT Keypad Editing

EDT.2.3 VT200 Supplemental Editing Keypad
The VT200 series terminal has a supplemental editing keypad, which is illustrated in
the figure below:

Help

Find

Select

(Enter)
Do

(Paste)
Insert
Here

(Cut)
Remove

Prev
Screen

Next
Screen

ZK-1677-84

The VT200 supplemental editing keypad keys perform the same functions as some of
the EDT keypad keys, and are described below:
•

DO—Enters the response to a "Search for:" or "Command:" prompt or completes
the processing of line-editing commands. (Performs the same function as the
ENTER keypad key.)

•

FIND—Elicits the "Search for:" prompt as the first step in the FIND operation.
Type the search string after the prompt and then press either the DO or ENTER
key to process the search. (Performs the same function as the FIND keypad key.)

•

HELP—Displays a diagram of EDT keypad keys. When one of the keys is
pressed after HELP, information about that key is displayed. This function has
no effect on the text you are editing. (Performs the same function as the HELP
keypad key.)

•

INSERT HERE—Inserts the contents of the PASTE buffer at the cursor's current
position. (Performs the same function as the PASTE keypad key.)

EDT Editor

EDT-17

EDT Keypad Editing

•

NEXT SCREEN—Moves the cursor forward 16 lines. (Performs the same
function as the ADVANCE SECT keypad sequence.)

•

PREV SCREEN—Moves the cursor backward 16 lines. (Performs the same
function as the BACKUP SECT keypad sequence.)

•

REMOVE—Deletes the select range (see SELECT) from the current buffer and
places the text in the PASTE buffer. (Performs the same function as the CUT
keypad key.)

•

SELECT—Marks the current cursor position as the beginning of the select range.
The select range consists of all the text between this marked position and the
cursor's subsequent position at the end of the text being selected. (Performs the
same function as the SELECT keypad key.)

EDT.2.4 Control Keys
You can use the following control keys in EDT keypad editing.

CTRL/A
Establishes the current cursor position and resets the indentation level count to be the
quotient of the cursor position divided by the SET TAB value. The cursor position
must be a multiple of the SET TAB value (a valid tab stop); otherwise EDT returns
the message "Could not align tabs with cursor" and no action is taken. (GOLD + A
also performs this function.)

CTRL/C
Aborts the currently executing EDT command.

CTRL/D
Decreases the TAB indentation level count one tab setting. (GOLD + D also performs
this function.)

CTRL/E
Increments the TAB indentation level count by one. (GOLD + E also performs this
function.)

EDT-18

EDT Editor
EDT Keypad Editing

CTRL/H
Like BACKSPACE, moves the cursor to the beginning of the line (or to the beginning
of the preceding line if the cursor is already at the beginning of the line).

CTRL/I
Like TAB, moves a line of text to the next tab stop.

CTRL/J
Like LINEFEED, deletes backward from the cursor to the beginning of a word. If the
cursor is on the first character in a word, CTRL/J deletes the previous word.

CTRL/K
Redefines keypad, control keypad, and gold keypad keys for the current terminal
session. When you press CTRL/K, the message "Press the key you wish to
define" appears. After you have responded, the message "Now enter the definition
terminated by ENTER" appears. Enter the key definition, either by pressing one
or more EDT keypad keys or by typing EDT nokeypad editing commands (or
a combination of pressing keypad keys and typing nokeypad commands). The
guidelines for valid definitions are identical to the DEFINE KEY command, except
that you do not need to include the delimiting quotation marks. Terminate the
definition by typing a period and pressing the ENTER key.
The following key definition redefines CHAR to transpose the two characters to the
left of the cursor. It moves the cursor two characters to the left (<— <— ); deletes the
character at the new cursor position (DEL C); moves the cursor one character to the
right (—► ); restores the deleted character (GOLD and UND C); and then moves the
cursor back to its previous position (—► ).
1 CTRL/K |

Press the key you wish to define:

□□□□
□□□□
□□□□
CHAR

□□■n
Now enter the definition terminated by ENTER

EDT Editor
EDT Keypad Editing

LEFT ARROW

□ □□□
□ □□□
□ □□■
□□u
RIGHT ARROW

■ □□□
□ □□□
□ □□■
□□u

EDT-19

EDT-20

EDT Editor
EDT Keypad Editing

RIGHT ARROW

To complete the key definition, type a period on the main keyboard and then press
the ENTER key.

CTRL/L
Inserts a form feed character.

CTRL/M
Like RETURN, inserts a carriage return ([cr] ) into your text.

CTRL/R
Clears and refreshes the screen, removing extraneous characters and restoring the
previous display.

CTRL/T
If you have previously specified a SET TAB value, CTRL/T indents whole lines in
the select range one tab stop to the right. (GOLD + T also performs this function.)

NOTE:

To allow CTRL/T to work correctly in EDT, you must first disable
the DCL function of CTRL/T. By default, DCL displays process statistics when
you enter CTRL/T. To disable the DCL function, enter the DCL command SET
NOCONTROL=T at the dollar-sign prompt.

CTRL/U
Deletes from the cursor to the beginning of the line. If the cursor is positioned at the
beginning of the line, CTRL/U deletes the previous line.

EDT Editor

edt-21

EDT Keypad Editing

CTRL/W
Clears and refreshes the screen, removing extraneous characters and restoring the
previous display.

CTRL/Z
Changes editing mode from keypad editing to line editing. (GOLD + Z also performs
this function.)

EDT.3 Line Editing
Some line-editing commands in EDT require range specifications.

EDT.3.1 Range Specifications
You use the following range specifications as parameters for EDT line-editing
commands.

Range

Description
The current line. (Example: ‘DELETE .)

line number

The line indicated by number. Only decimal integers are
legal. (Example: ‘DELETE 22)

'string' or "string"

The next line(s) containing the specified string. The default
command, when no other command is specified, is TYPE.
(Example: ‘DELETE 'EDT')

buffer-name

The specified buffer (that may contain a line range). Buffer
names must begin with a letter or underscore but may
contain numerics. (Example: ‘DELETE =BUFA 22:33)

BEGIN

The first line in the current buffer. (Example: ‘DELETE
BEGIN)

END

The end of the buffer (marked by the [EOB] symbol by
default). (Example: ‘COPY BEGIN TO END)

LAST

The last line in the previous buffer where the cursor was
positioned. The cursor moves to the beginning of this line.
(Example: ‘COPY BEGIN TO LAST)

BEFORE

All lines in the buffer that precede the current line.
(Example: ‘DELETE BEFORE)

REST

The current line plus all lines after it in the buffer. (Example:
‘DELETE REST)

EDT-22

EDT Editor
Line Editing

Range

Description

WHOLE

The entire buffer. (Example: *DELETE WHOLE)

ALL 'string'

All lines containing the specified string. (Example: ^DELETE
ALL 'EDT')

[range] AND [range]

The specified single lines. (Example: *DELETE 22 AND 33)

[range] , [range]

The specified single lines. (Example: *DELETE 22,33,55)

[range] THRU [range]

The set of lines between the specified ranges. The default
for either range is the current line. (Example: ^DELETE 22
THRU 33)

[range] : [range]

The set of lines between the specified ranges. The default for
either range is the current line. (Example: *DELETE 22:33)

[range] FOR n

Range and the next n lines (where range is a single line that
defaults to the current line). (Example: ^DELETE 22 FOR 10)

[range] # n

Range and the next n lines (where range is a single line that
defaults to the current line). (Example: ^DELETE 22 # 10)

[range] + n

The line that is n lines after the range. Range defaults to the
current line and n to 1. (Example: *DELETE BEGIN + 3)

[range] - n

The line that is n lines before the range. Range defaults to
the current line and n to 1. (Example: *DELETE . - 10)

EDT.3.2 Line-Editing Commands
Enter EDT line-editing commands after the asterisk prompt. (To obtain the asterisk
prompt from EDT keypad-editing mode, enter CTRL/Z.)

CHANGE [range]
Changes EDT editing mode from line to either keypad or nokeypad editing
(depending on whether you have used the SET KEYPAD or SET NOKEYPAD
command). The default is keypad editing. The range specifies the cursor position
when you enter keypad or nokeypad editing mode; the range defaults to the cursor's
current position.
PARAMETERS

range
The line at which the cursor is positioned when you enter EDT keypad or
nokeypad editing mode. If no range is specified, the range defaults to the
cursor's current position.

EDT Editor

EDT-23

Line Editing

EXAMPLE
^CHANGE END
Changes from EDT line editing to keypad editing, positioning the cursor at the end
of the buffer.

CLEAR buffer-name
Deletes the contents of and removes the specified buffer.
PARAMETERS

buffer-name
The name of the buffer to be cleared. The buffer name must be specified, even
if it is the current buffer. The contents of the MAIN and PASTE buffers can be
deleted, but the buffers themselves cannot be removed.
EXAMPLE
*CLEAR PASTE
Deletes the contents of the PASTE buffer.

COPY [range-1] TO [range-2]
Inserts the text specified by range-1 immediately before the line specified by range-2.
The original text remains intact and the cursor is positioned at the end of the inserted
text. You can specify the buffer that contains the range by preceding the range with
=buffer name.
PARAMETERS

range-1
The line or lines and/or buffer name containing the text to be copied. If range-1
is omitted, EDT copies the current line. If a buffer name is specified with no
range, the entire contents of the buffer are copied.

range-2
The line and/or buffer name to be preceded by the copied text. If range-2 is
omitted, EDT inserts a copy of the text preceding the current line. If a buffer
name is specified with no range, the text is inserted at the top of the specified
buffer.

edt-24

EDT Editor
Line Editing

QUALIFIERS

/DUPLICATED
Performs the COPY command n times.

/QUERY
Prompts for verification of each line as it is copied. Possible responses are:
Y (yes)

Copy this text

N (no)

Do not copy this line

A (all)

Complete the remaining copy operations without further query

Q (quit)

Do not attempt any further copy operations

EXAMPLES
♦COPY 5:10 TO END
Duplicates lines 5 through 10 at the end of the current buffer.
♦COPY 25:30 TO END/QUERY/DUPLICATE:3
Duplicates lines 25 through 30 at the end of the current buffer, prompting for
verification of each line before it is copied. The confirmed lines are copied in their
original order three times.
♦COPY =MAIN TO =BUF1/QUERY
Duplicates the contents of the MAIN buffer (MAIN) in the buffer named BUF1,
prompting for verification before each line is copied.

DEFINE KEY parameter AS 'string7
Defines or redefines the function of keys used in EDT keypad editing by assigning
EDT nokeypad-editing commands to keypad, control, or function keys. (See
Section EDT.4.2 for a list of these commands.) You must use EDT's numerical
designations for the keypad and function keys you define. The figures below
illustrate the key numbers for both the VT200 and VT100 series terminals. (To
designate VT200 function keys, you must precede the key number with the word
FUNCTION.)

EDT Editor

EDT-25

Line Editing

ARROW
KEYS

EDT
KEYPAD

3
21

16
ZK-1776-84

F6
FUNCTION
KEYS
17 - 26

F10

F11

FI 2

FI 3

FI 4

{00000 0000
SUPPLEMENTAL
EDITING
KEYPAD

FI 7

FI 8

FI 9

F20
FUNCTION
KEYS
- 34

0000 n

000 000
000 000
0
000
000 000
| 16 |

Parameter consists of the name of the key to be defined, and string consists of EDT
nokeypad-editing commands enclosed in quotation marks. (Valid types of key
sequences are described below.) Use a period (.) at the end of the key definition to
have EDT execute the command immediately.

EDT-26

EDT Editor
Line Editing

To define a key to invoke a prompt, include a question mark (?), in the string
followed by the prompt string in quotation marks. Do not use the same type
of quotation marks to enclose the prompt string as you use to surround the key
definition. You can enter up to 64 characters in response to the prompt, terminated
by the ENTER key. To allow the RETURN key to also be used to terminate a
response, insert an asterisk (*) immediately after the question-mark prompt in the
key definition.
PARAMETERS

[GOLD]number
Specifies the number of the keypad key to be defined. The optional GOLD
specifies the alternate function of the key. (See the preceding figure for an
illustration of the correct EDT key numbers.)

CTRL/letter
Specifies the control/key sequence to be defined. CONTROL can be specified
either with just a keyboard character or with GOLD and a keyboard character
(where the correct sequence is: GOLD CONTROL letter). The following control
keys are used by the operating system to perform special functions; therefore,
you should not redefine them:
CTRL/C
CTRL/O
CTRL/P
CTRL/Q
CTRL/R
CTRL/S
CTRL/T
CTRL/U
CTRL/W
CTRL/X
CTRL/Y
CTRL/Z

FUNCTION number
Definable function keys on the VT200 series terminal include keys FI 7 through
F20 on the function key row across the top of the keyboard. To define a function
key, type the word FUNCTION followed by the function key number.

GOLD character
Specifies the keyboard key to be assigned a new editing function. The keys 0
through 9, !, %, ', -, and " cannot be redefined. To specify the DELETE key, type
the reserved word DELETE to define that key.

'string'
A string can contain multiple nokeypad-editing commands (see Section EDT.4.2).

EDT Editor

EDT-27

Line Editing

EXAMPLES
♦DEFINE KEY GOLD 1 AS ’CHGCW.*
Redefines the function of keypad GOLD + 1 to change (CHGC) a word (W) from
uppercase to lowercase or from lowercase to uppercase.
♦DEFINE KEY GOLD CONTROL A AS ’BACK C DC ADV C UNDC.*
Defines the function of GOLD CTRL/A to transpose the two characters to the left of
the cursor by setting the cursor direction backward (BACK), moving the cursor one
character (C), deleting one character (DC), setting the cursor in the forward direction
(ADV), moving the cursor one character (C), and restoring the first character deleted
(UNDC).
♦DEFINE KEY FUNCTION 19 AS "EXT S/?’REPLACE: ’/?’ WITH: ’/WHOLE."
Redefines the function of key FI9 to substitute one string for another throughout a
buffer by extending the line-editing command (SUBSTITUTE) to EDT keypad editing
(EXT) and substituting the specified text (entered after the prompt REPLACE:) with
the specified text (entered after the prompt WITH:) throughout the buffer (WHOLE).

DEFINE MACRO macro-name
Defines the macro name as an EDT line-editing command. To use the new
command, create a buffer with the same name as the macro and insert the sequence
of EDT commands (the macro) that you want to execute whenever you type the
macro name after the asterisk prompt. A macro can be saved in an external file and
copied into a buffer during your editing session with the INCLUDE command. If
you redefine an ED line-editing command, the original command is not available as
long as the macro definition is in effect. To delete a macro, use the macro name as
the buffer specifier with the CLEAR command. You can nest macros to almost any
depth.
PARAMETERS

macro-name
The name of the EDT macro containing line-editing commands. The macro name
must be the same as the name of the buffer containing the EDT macro.

EDT-28

EDT Editor
Line Editing

EXAMPLE
*DEFINE MACRO HEADING
*FIND=HEADING
INSERT;NAME:
INSERT;DEPT:
INSERT;DATE:
INSERT;SUBJ:
*FIND=MAIN .
Defines a macro named HEADING to insert a heading format whenever you enter
HEADING as an EDT line-editing command. To place the preceding macro in an
EDT startup command file, include the following commands:
DEFINE MACRO HEADING
FIND=HEADING
INSERT;INSERT;NAME:
INSERT;INSERT;DEPT:
INSERT;INSERT;DATE:
INSERT;INSERT;SUBJ:
FIND=MAIN.

The DEFINE MACRO command is necessary to create the macro definition; the FIND
commands are necessary to enter and exit from the buffer containing the macro; and
the INSERT command is necessary to enter each command in the macro sequence
(hence, the double INSERT commands).

DELETE [range]
Deletes the lines specified by the range.
PARAMETERS

range
The line or lines specified for deletion. The range defaults to the current line.
QUALIFIERS

/QUERY
Prompts for verification before each line is deleted. Possible responses are:
Y (yes)

Delete this line

N (no)

Do not delete this line

A (all)

Complete the remaining deletions without further query

Q (quit)

Do not make any further deletions

EDT Editor

edt-29

Line Editing

EXAMPLE
♦DELETE 12:56/QUERY
Deletes lines 12 through 56, prompting for verification.

EXIT [file-spec]
Ends an editing session, writing the contents of the MAIN buffer to an output file.
PARAMETERS

[file-spec]
Defines the file specification of the output file. The default is the highest version
of the input file named in the EDIT command line (or the output file named with
the DCL command EDIT/OUTPUT=file-spec). If you enter EDT with the DCL
command EDIT/READ-ONLY, the EXIT command must include an output file
specification.
QUALIFIERS

/SEQUENCE[:initial[:increment]]
Assigns sequence numbers, which become part of the file. The initial qualifier
defines the starting line number. The increment qualifier defines the increment
between sequence numbers. (This qualifier should not be used to number
programs since references to line numbers within programs will not be changed.)

/SAVE
Saves the journal file, which has the file type JOU and the file name of the input
file specified in the EDIT command line.
EXAMPLES
♦EXIT
Saves the contents of the MAIN buffer in an output file and returns you to DCL
command level.
♦EXIT NAME.NEW/SEQUENCE:5:5/SAVE
Saves the contents of the MAIN buffer in the output file NAME.NEW. The
/SEQUENCE qualifier assigns sequence numbers that become part of the file:
the sequence number of the first line in the file is 5, and the following lines are
incremented by five. The /SAVE qualifier saves the journal file.

EDT-30

EDT Editor
Line Editing

FILL [range]
Reorganizes the text in a select range of lines so that the maximum number of whole
words are fitted within the current line width. The default line width for EDT is 80
characters. Use the line-editing command SET WRAP to change the line width for
the FILL operation.
PARAMETERS

range
A line or lines and/or buffer name to be filled. If you do not specify a range or
buffer name with the FILL command, EDT attempts to fill the text in the active
select range. If no select range is active EDT displays an error message.
EXAMPLE
♦FILL 10 THRU 15
Fills lines 10 through 15 to the value of SET WRAP or SET SCREEN.

FIND [range]
Places the cursor at the first line of the specified range in the specified or current
buffer, but does not display the line at the bottom of your screen. In line mode, once
the specified line has been found, EDT returns the line-mode asterisk (*) prompt.
(Use the TYPE command to display the line.) The FIND command searches either
forward or backward for a string in the current buffer. To search backward toward
the beginning of the buffer, precede the search string (range) with a minus sign (-).
If you specify a buffer that does not exist, EDT creates it. To move the cursor to its
previous position in a buffer, include a period (.) immediately after the buffer name.
(The FIND command is useful for moving from one buffer to another.)
PARAMETERS

range
A line and/or buffer name. When a buffer name is specified without a range,
EDT positions the cursor at the first character of the buffer. When both a buffer
name and range are specified, EDT positions the cursor at the line specified by
range in the specified buffer. Use a space to separate the buffer name from the
range specifier. (If you use a string as a range specifier, EDT performs the search
using the defaults: GENERAL, BEGIN, and UNBOUNDED.)
EXAMPLES
♦FIND =BUFA 45
Positions the cursor at line 45 in the buffer named BUF1.
♦FIND=MAIN.
Returns the cursor to its previous position in the MAIN buffer.

EDT Editor

EDT-31

Line Editing

HELP [topic [subtopic]]
Displays a list of EDT topics on which you can get information.
PARAMETERS

topic
The topic for which you wish to display information.

subtopic
The subtopic for which you wish to display information.
EXAMPLE
♦HELP FILL
Displays information about the EDT command FILL.

INCLUDE file-spec [range]
Copies the specified file to a text buffer, placing it immediately before the range and
positioning the cursor immediately following the inserted text.
PARAMETERS

file-spec
The name of the file you wish to include in the specified buffer.

range
A line number or buffer name. If no buffer is specified, the file is added to the
current buffer. The range defaults to the current line in the specified buffer.
EXAMPLES
♦INCLUDE CHAP1.TXT
Copies the contents of the file named CHAP1.TXT into the current buffer just before
the current line.
♦INCLUDE CHAP1.TXT =BUF1 30
Copies the contents of the file named CHAP1.TXT into the buffer named BUF1,
beginning before line 30.

EDT-32

EDT Editor
Line Editing

INSERT [range]
Inserts text before the specified single line range. To insert a full line or more of text,
press RETURN after the optional range specifier, followed by lines of text terminated
with a CTRL/Z. To insert one line of text, place a semicolon after the range; any text
typed after the semicolon is inserted before the range when you press RETURN. (Use
only the semicolon insertion in startup command procedures.) If lines are inserted
between two lines whose line numbers differ by one or less, EDT will number the
new lines using decimal fractions. (In extreme cases EDT may be forced to renumber
lines after the last line you insert.)
PARAMETERS

range
The line and/or buffer before which the text is to be inserted. When a buffer
name is specified, EDT moves to that buffer and remains there after the insertion
has been made. The buffer name defaults to the current buffer and the range
defaults to the current line.
EXAMPLES
*INSERT 25
Inserts lines of text before line 25.
♦INSERT =BUF1 30;ENTER YOUR BADGE NUMBER
Inserts "ENTER YOUR BADGE NUMBER" before line 30 in the buffer named BUF1.

MOVE [range-1] TO [range-2]
Deletes the lines specified in range-1 and inserts them before the line specified
in range-2 (which then becomes the current line). (COPY inserts the text in both
places.)
PARAMETERS

range-1
The line or lines and/or buffer name containing the text to be moved. If range-1
is omitted, EDT moves the current line. If a buffer name is specified with no
range, the entire contents of the buffer are moved.

range-2
The line and/or buffer name to be preceded by the moved text. If range-2 is
omitted, EDT inserts the text just before the current line. If a buffer name is
specified with no range, the text is inserted at the top of the specified buffer.

EDT Editor

edt-33

Line Editing

QUALIFIERS

/QUERY
Prompts for verification of each line before it is moved. Possible responses are:
Y (yes)

Move this text

N (no)

Do not move this text

A (all)

Complete the remaining move operations without further query

Q (quit)

Do not move any more lines of text

EXAMPLE
*M0VE TO 65
Deletes the current line and inserts it before line 65.

PRINT file-spec [range]
Copies the specified range to a printable file; that is, PRINT inserts a form feed and
two blank lines every 55 lines, and line numbers become part of the new file's text.
The file is submitted to SYS$PRINT and is printed.
PARAMETERS

file-spec
The specification of the file to be printed.

range
The line or lines and/or buffer name containing the text to be printed. The range
defaults to the entire current buffer.
EXAMPLE
★PRINT NEWFILE.DAT 22:30
Copies lines 22 through 30 to the printable file named NEWFILE.DAT.

QUIT
Terminates EDT without saving the edits made during the session.
QUALIFIERS

/SAVE
Saves the journal file, which has the file type JOU and the file name of the input
file (unless you used /JOURNAL in the EDIT command line).

EDT-34

EDT Editor
Line Editing

REPLACE [range]
Deletes the specified range and inserts new text in place of the deleted range. EDT
renumbers the inserted text, using decimal line numbers when the new text is longer
than the old. (When the new text consists of fewer lines than the old, the extra line
numbers are not used.)
PARAMETERS

range
The line or lines containing the text to be replaced. The range defaults to the
current line. To insert a full line or more, press RETURN and type the text,
terminating it with CTRL/Z. To insert one line, enter a semicolon after the range;
all text typed after the semicolon is inserted in place of the range when you press
RETURN.
EXAMPLE
♦REPLACE 3; I regret to inform you that 1 return|
Replaces line 3 with the string "1 regret to inform you that"

RESEQUENCE [range]
Assigns new EDT line numbers to the specified range.
PARAMETERS

range
The consecutive lines or buffer to be renumbered. The range defaults to the
entire current buffer.
QUALIFIERS

[/SEQUENCE[:initial[:increment]]]
Assigns line numbers according to the specified starting number initial and
increment value increment. (The defaults for initial and increment are 1.)
EXAMPLE
♦RESEQUENCE =BUFA
Resequences the line numbers of the lines in the buffer named BUFA.

SET [NOJAUTOREPEAT
Enables EDT to prevent keypad keys (including arrow keys) from repeating faster
than EDT can update the screen. SET AUTOREPEAT is the default.

EDT Editor

EDT-35

Line Editing

EXAMPLE
*SET NOAUTOREPEAT
Prevents keypad keys from repeating more rapidly than EDT can update the screen.

SET CASE [[none][upper][iower]]
Distinguishes uppercase and lowercase letters when you are reading text at a
single-case terminal. No permanent marks are placed in the text itself. The default is
SET CASE NONE.
PARAMETERS

none
Causes no provision to be made for artificially distinguishing between uppercase
and lowercase letters.

upper
Causes each uppercase letter in the text to be preceded by an apostrophe (').

lower
Causes each lowercase letter in the text to be preceded by an apostrophe (').
EXAMPLE
♦SET CASE UPPER
Assuming you are at a single-case terminal, flags all letters that are uppercase in the
original text.

SET COMMAND file-spec
Specifies an additional EDT startup command file (besides the default EDT startup
command file, EDTINI.EDT) when you invoke EDT. The default file type is EDT. If
the specified file does not exist, EDT ignores the SET COMMAND and continues to
process any remaining commands in the current startup command file. (To bypass
the default startup command file, specify a different startup command file in your
EDT startup command file.)
PARAMETERS

file-spec
The specification of the startup command file you wish to process.

EDT-36

EDT Editor
Line Editing

EXAMPLE
★SET COMMAND USEREDT.EDT
As a line in an EDT startup command file, transfers control to another EDT startup
command file, USEREDT.EDT.

SET CURSOR top:bottom
Determines at which lines scrolling begins: top is the upper limit and bottom is the
lower. EDT scrolls the display when the cursor reaches either limit.
PARAMETERS

top
The number of lines from the top of the screen to the cursor. The allowable
limits for top are 0 through 21; the default is top=7.

bottom
The number of lines from the cursor to the bottom of the screen. The allowable
limits for bottom are 0 through 21; the default is bottom=14.
EXAMPLE
♦SET CURSOR 0:5
Sets the scrolling region to the first 6 lines on the screen. (If you try to move the
cursor beyond either limit, EDT scrolls the display.)

SET ENTITY entity 'boundary'
Defines the boundaries for an entity.
PARAMETERS

boundary
The delimiter values for WORD, SENTENCE, PARAGRAPH, and PAGE. The
default boundaries are as follows:
WORD

SENTENCE

PARAGRAPH

PAGE

<LF>

<FF>

<VT>

<FF>

<CR>

EDT Editor

edt-37

Line Editing

entity

The WORD, SENTENCE, PARAGRAPH, or PAGE for which you wish to set
boundaries.
EXAMPLE
♦SET ENTITY WORD ’<LF><VT><FF><CR>.

? !

;

’

Defines the following as delimiters for the WORD entity: line feeds, vertical tabs,
form feeds, carriage returns, periods, question marks, exclamation points, semicolons,
colons, and individual spaces. All commands using the WORD entity (such as DEL
W) work on a unit of characters up to these delimiters.

SET [NO]FNF
Suppresses the "Input file does not exist" message that appears by default when you
use EDT to create a new file.

SET HELP file-spec
Enables you to access HELP files other than the default EDT help files (found in
SYS$HELP:EDTHELP.HLB).
PARAMETERS
file-spec

The specification of the HELP file you wish to access.
EXAMPLE
♦SET HELP DISKI:USEREDTHELP.HLB

Enables you to access the help file USEREDTHELP.HLB on device DISKI.

SET [NO]KEYPAD
Sets either EDT keypad or nokeypad editing as the default editing mode. The default
setting is KEYPAD.
EXAMPLE
♦SET NOKEYPAD

Nokeypad becomes the editing mode when you give the CHANGE command.

EDT-38

EDT Editor
Line Editing

SET LINES number
Sets the number of lines that EDT displays on your screen while keypad editing.
(This command is useful in reducing the time required to refresh the screen image
when editing at low baud rates.)
PARAMETERS

number
The number of lines can be set from 1 to 22; the default setting is 22 lines.
EXAMPLE
♦SET LINES 10

Causes EDT to display 10 lines of text on the screen while keypad editing.

SET MODE CHANGE or LINE
Placed in an EDTINI.EDT startup command file, SET MODE specifies either keypad
(CHANGE) or line (LINE) mode as the initial editing mode. The SET MODE
command should be used only in an EDT startup command file. Change mode
is set by default.
EXAMPLE
SET MODE CHANGE

Causes EDT to enter change mode for keypad editing after the startup command file
has executed.

SET [NO]NUMBERS
Determines whether or not EDT displays line numbers in line-editing mode. The
default setting is NUMBERS.
EXAMPLE
♦SET NONUMBERS

Suppresses the line numbers normally displayed in line-editing mode.

SET [NO]QUIET
Suppresses the ringing of the bell when a message occurs in keypad-editing mode.
The default setting is NOQUIET.

EDT Editor

edt-39

Line Editing

EXAMPLE
*SET QUIET
Causes EDT to suppress the bell when a message occurs in keypad-editing mode.

SET [NO]REPEAT
Controls the use of the GOLD repeat feature, which allows you to repeat EDT
keypad functions by pressing GOLD and keyboard digits; and the SPECINS keypad
function, which enables you to insert any character from the DEC Multinational
Character set into your text by using its decimal equivalent value. SET REPEAT is
the default.
EXAMPLE
♦SET NOREPEAT
Disallows the use of the GOLD repeat feature and the SPECINS keypad function.

SET SCREEN width
Sets the maximum length of line that EDT displays.
PARAMETERS

width
The length of the line to be displayed; the default line width set by VAX/VMS is
80 characters. In EDT keypad editing, when you insert more characters than the
length set for character editing, EDT displays a solid diamond at the line's end.
In line-editing, EDT displays the overflow characters on succeeding lines.
EXAMPLE
♦SET SCREEN 132
Sets the maximum length of line displayed to 132.

SET SEARCH parameter
Controls string searches with the FIND command.

EDT-40

EDT Editor
Line Editing

PARAMETERS

parameter
The characteristics that determine how a search is conducted. Possible
parameters are:
GENERAL (default) or EXACT

Determines whether or not EDT
disregards the case of alphabetic
characters

BEGIN (default) or END

Determines whether EDT positions the
cursor at the beginning or end of the
found string

UNBOUNDED (default) or BOUNDED

Determines whether EDT searches the
entire buffer or stops the search when it
reaches a page boundary marker

EXAMPLE
♦SET SEARCH EXACT
♦SET SEARCH BOUNDED
♦SET SEARCH END
♦TYPE *Mark *
Causes EDT to search between the current cursor position and the next page
delimiter for the first occurrence of the exact string "Mark" (that is, the first character
of the string must be in uppercase and the rest in lowercase). When the string is
found, the cursor will be positioned after the string.

SET [NO]SUMMARY
Controls whether or not EDT prints a summary (the complete file specification and
the number of lines in the file) when you exit from EDT and when you issue the
WRITE command. The default is SET SUMMARY.
EXAMPLE
♦SET NOSUMMARY
Suppresses the summary information generated when you exit from EDT.

SET TAB n or SET NOTAB
Controls the number of columns to which the first tab stop is set. Only the initial tab
stop is affected; the remaining tab stops, multiples of 8, are unchanged. SET NOTAB,
which is the default, sets the first tab stop at 8 columns from the left margin. SET
TAB n sets the first tab stop at n columns from the left margin.

EDT Editor

EDT-41

Line Editing

The numbers below indicate column numbers.
EXAMPLE
123456789
*SET TAB 5
*CHANGE
It is with great pleasure that I announce the winner I return |
<TAB>
of the Steeple Creek sales award: 1 return)
<TAB><TAB>
Roberta Brown of Lancaster County)
By default, the first tab stop is set to 8 columns. The SET TAB 5 command sets the
first tab stop to 5 columns; the second tab stop is still set to 8 columns—the next
multiple of 8 after the SET TAB value. (The third tab stop is at 16 columns, the
fourth at 24, and so on in multiples of 8.)

SET TERMINAL
Resets the following terminal characteristics:
Terminal type (HCPY, VT100)
Scrolling regions (SCROLL, NOSCROLL)
Additional character display (EIGHTBIT,NOEIGHTBIT)
Enhanced screen editing (EDIT,NOEDIT)
Do not specify SET TERMINAL from keypad-editing mode.

SET TEXT
Specifies a string to be displayed at the end of a page (PAGE) or buffer (END) by
controlling the display of the <FF> character. SET TEXT PAGE displays your
string for every form feed in the buffer; SET TEXT END displays your string at
the end of the buffer. Specify the string in quotation marks. The default strings
displayed are: PAGE= <FF> and END=[EOB].
EXAMPLES
♦SET TEXT PAGE "<PAGE BREAK>"
Displays the string <PAGE BREAK>

for each form-feed character.

♦ SET TEXT END " [END OF BUFFER ADD]"
Displays the string [END OF BUFFER ADD] at the end of the current buffer
(replacing the [EOB] symbol).

edt-42

EDT Editor
Line Editing

SET [NO]TRUNCATE
Determines whether the display of lines that are longer than the SET SCREEN value
will be truncated or wrapped to the next line. The default setting is TRUNCATE.
EXAMPLE
♦SET NOTRUNCATE
Causes the display of lines that are longer than the screen width to be wrapped to
the next line.

SET [NO]VERIFY
Displays the commands in startup command files and macros as they are executed.
The default setting is NOVERIFY.
EXAMPLE
♦SET VERIFY
Causes EDT to display the commands in startup command files and macros as they
are executed.

SET WORD [NO]DELIMITER
Controls whether or not EDT treats word boundaries (defined with SET ENTITY)
as words. By default, EDT considers all word boundaries except spaces to be words
when it is deleting words or moving the cursor by word. Specify SET WORD
NODELIMITER to change the default.
EXAMPLE
♦SET WORD NODELIMITER
Causes EDT to use word boundaries to determine where words begin and end but
not to treat these delimiters as separate words.

SET WRAP n or NOWRAP
In keypad editing, specifies a right margin where, when the cursor position exceeds
the value of n, EDT wraps the full word to the next line. This command also sets the
right margin for the FILL command, which fills each line in the select range to the
word delimiter nearest the limit n. The default setting is NO WRAP.

EDT Editor

EDT-43

Line Editing

EXAMPLE
♦SET WRAP 60
Causes EDT to wrap words exceeding 60 characters in length to the next line and
sets the right margin to 60 for the FILL command.

SHOW AUTOREPEAT
Displays the current setting of the SET AUTOREPEAT command.
EXAMPLE
♦SHOW AUTOREPEAT
noautorepeat
Indicates that the SET NOAUTOREPEAT command is in effect.

SHOW BUFFER
Lists the buffers in use during the current editing session and the number of lines of
text in each buffer. The MAIN and PASTE buffers are always displayed in response
to this command, even when empty. The current buffer is marked by an equal sign
before the buffer's name. An asterisk following the MAIN buffer line count indicates
that the input file has not yet been read to the end of the file, and therefore the line
count is not accurate.
EXAMPLE
♦SHOW BUFFER
MAIN
396 LINES
=BUF1
10 LINES
PASTE
4 LINES
Indicates that the buffers MAIN, BUF1, and PASTE are being used in the current
editing session, and that BUF1 is the current buffer.

SHOW CASE
Indicates whether uppercase or lowercase, or neither, has been established by the
SET CASE command.
EXAMPLE
♦SHOW CASE
None
Indicates that the SET CASE NONE command is in effect.

EDT-44

EDT Editor
Line Editing

SHOW COMMAND
Displays the name of the current startup command file when SHOW COMMAND is
included in a startup command file.
EXAMPLE
♦SHOW COMMAND
♦

Indicates that there is no additional startup command file besides the default
EDTINI.EDT.

SHOW CURSOR
Shows the cursor's current scrolling range. EDT responds with "top^ottom," which
are integers indicating the top and bottom lines of the scrolling range. The SET
CURSOR command sets the scrolling range.
EXAMPLE
♦SHOW CURSOR
5:5
Indicates that EDT will scroll at the upper and lower limits of 5.

SHOW ENTITY WORD or SENTENCE or PAGE or PARAGRAPH
Shows the current boundaries for the specified entity. The SET ENTITY command
defines these entities.
EXAMPLE
♦SHOW ENTITY PAGE
<FF>
Indicates that the current boundary for PAGE is a form feed ( <FF> ).

SHOW FILES
Displays the input file and output file for the current EDT session.
EXAMPLE
♦SHOW FILES
Input File: TASKS.DAT
Output File: TASKS.DAT
Indicates that the name of the output file will be the same as the input file with the
version number incremented by one. Use the /OUTPUT=file-spec qualifier of the
DCL command EDIT to set the name of the output file.

EDT Editor

EDT-45

Line Editing

SHOW FNF
Displays the current setting of the SET FNF command.
EXAMPLE
*SHOW FNF
fnf
Indicates that the SET FNF command is in effect.

SHOW HELP
Displays the current EDT HELP file. The default is SYS$HELP:EDTHELP:HLB.
EXAMPLE
*SH0W HELP
SYS$HELP:EDTHELP:HLB
Indicates that the current EDT HELP file is set to the default.

SHOW KEY
Displays the definition of the specified keypad or keyboard key. To refer to a GOLD
or control key sequence, type GOLD then the key or CONTROL plus the key. (The
DEFINE KEY command and CTRL/K define keys.)
EXAMPLE
*SHOW KEY GOLD P
TOP
Shows the current definition for the GOLD + P key sequence set with the SET KEY
command.

SHOW KEYPAD
Displays the current keypad-editing mode: KEYPAD or NOKEYPAD.
EXAMPLE
♦SHOW KEYPAD
keypad
Indicates that the current keypad-editing mode is keypad.

EDT-46

EDT Editor
Line Editing

SHOW LINES
Shows the number of lines displayed on the screen at one time (set with SET LINES).
EXAMPLE
♦SHOW LINES
22
Indicates that the current setting of the SET LINES command is 22.

SHOW MODE
Displays the last SET MODE command setting (which is set in an EDT startup
command file). (Does not display modes set by the CHANGE, CTRL/Z, or EX
commands.)
EXAMPLE
♦SHOW MODE
Change
Indicates that the last command mode setting was SET MODE CHANGE.

SHOW NUMBERS
Indicates whether or not line numbers are currently displayed (set with SET
NUMBERS).
EXAMPLE
♦SHOW NUMBERS
nonumbers
Indicates that the current setting is SET NONUMBERS.

SHOW QUIET
Displays the current setting of the SET QUIET command.
EXAMPLE
♦SHOW QUIET
noquiet
Indicates that the current setting is SET NOQUIET.

EDT Editor

EDT-47

Line Editing

SHOW REPEAT
Displays whether or not you can use the GOLD repeat feature and the SPECINS
function in keypad-editing mode (set with the SET REPEAT command).
EXAMPLE
*SH0W REPEAT
repeat
Indicates that the current setting is SET REPEAT.

SHOW SCREEN
Shows the current setting for the maximum length of a line EDT displays. (The SET
SCREEN command defines line length.)
EXAMPLE
♦SHOW SCREEN
80
Indicates that the maximum length of line displayed is 80 characters.

SHOW SEARCH
Shows the current search parameters (set with the SET SEARCH command).
EXAMPLE
♦SHOW SEARCH
general begin unbounded
Indicates that the current settings are SET SEARCH GENERAL, SET SEARCH
BEGIN, and SET SEARCH UNBOUNDED.

SHOW SUMMARY
Displays the current setting of the SET SUMMARY command.
EXAMPLE
♦SHOW SUMMARY
summary
Indicates that the current setting is SET SUMMARY.

EDT-48

EDT Editor
Line Editing

SHOW TAB
Displays the current setting of SET TAB and the current tab indentation level count.
EXAMPLE
*SHOW TAB
tab size 5; tab level 1
Indicates that the current tab setting is 5 and the tab indentation level count is 1.

SHOW TERMINAL
Displays the current terminal settings.
EXAMPLE
*SHOW TERMINAL
VT100, scroll, noeightbit, edit
Displays the current terminal characteristics.

SHOW TEXT PAGE or END
Indicates what text EDT is currently displaying for the <FF>
with SET TEXT).

and [EOB] marks (set

EXAMPLE
*SH0W TEXT END
[THE END]
Indicates that the current end-of-buffer setting is SET TEXT END "[THE END]".

SHOW TRUNCATE
Displays the current setting of the SET TRUNCATE command.
EXAMPLE
*SHOW TRUNCATE
notruneate
Indicates that the current setting is SET NOTRUNCATE.

SHOW VERIFY
Displays the current setting of SET VERIFY, which controls whether or not the
commands in an EDT startup command file or macro are displayed. SET NOVERIFY
is the default.

EDT Editor

edt-49

Line Editing

EXAMPLE
*SH0W VERIFY
noverify
Indicates that the current setting is SET NOVERIFY.

SHOW VERSION
Displays the current version of EDT.
EXAMPLE
*SH0W VERSION
V3.00-17

1984

Displays the current version of EDT.

SHOW WORD
Displays the current setting of the SET WORD command.
EXAMPLE
♦SHOW WORD
delimiter
Indicates that the current setting is SET WORD DELIMITER.

SHOW WRAP
Displays the current setting of SET WRAP.
EXAMPLE
♦SHOW WRAP
75
Indicates that the current setting is SET WRAP 75.

SUBSTITUTE \string-1 \string-2\[range]
Replaces occurrences of one specified string with another string. A string can
be from 0 to 64 characters. Except for the percent sign (%), you can use any
nonalphanumeric character that does not appear in either of the strings as a delimiter.
You must use the same character as delimiter throughout the command line. (Slashes
preceding qualifiers are required.)

EDT-50

EDT Editor
Line Editing

PARAMETERS

[range]
EDT replaces all the occurrences of string-1 within the specified range with
string-2 and displays the number of substitutions made. At the end of the
substitution, the cursor returns to the first line in the specified range. If you do
not specify a range, EDT replaces only the first occurrence of the string in the
current line.

string-1
The text string to be replaced.

string-2
The replacement text string.
QUALIFIERS

/BRIEF[:n]
Displays the first n characters of the lines containing string-1. The value of n
defaults to 10.

/QUERY
Prompts for verification before each substitution.

/NOTYPE
Prevents the display of lines containing substitutions.
EXAMPLES
* SUBSTITUTE\INADVERTANT\INADVERTENT\WHOLE
Substitutes "inadvertent" for each occurrence of "inadvertant" in the buffer. EDT
displays both the number of substitutions made and the lines containing the
substitutions.
*SUBSTITUTE*section*chapter*20:50/QUERY
Within the range of lines from 20 through 50, substitutes "chapter" for "section,"
prompting for verification before each substitution.

[SUBSTITUTE] NEXT [string-1 /string-2/]
Replaces the next occurrence of string-1 with string-2 and positions the cursor at the
line where the substitution is made. String-1 defaults to the current search string,
and string-2 to the last specified string-2.

EDT Editor

EDT-51

Line Editing

PARAMETERS

string-1
The string to be replaced.

string-2
The replacement text string.
EXAMPLE
♦ NEXT
If your last substitute command was: "SUB/several/some/", the NEXT (SUBSTITUTE
NEXT) command above will find the next occurrence of the word "several" and
replace it with "some", displaying the corrected line (so long as you haven't changed
the search string in the meantime).

TAB ADJUST [-]n [=buffer] [range]
Indents whole lines in the specified range n number of tab stops to create layered
text. A minus sign before the n specifier allows you to move text back toward the
left margin. In order for the command to work you must first establish a SET TAB
value for your editing session.
PARAMETERS

=buffer
The name of the buffer to be indented.

range
The line or lines to be indented. If you include a buffer specifier with no range,
the entire buffer is indented. When you omit both the buffer and range specifiers,
EDT assumes that you have an active select range (see the keypad SELECT
command).

Nn
The number of tab stops you wish to indent the text.
EXAMPLES
♦TAB ADJUST 1 5
Indents line number 5 one tab stop.
♦TAB ADJUST -4 25
Moves (indented) line number 25 four tab stops to the left.

EDT-52

EDT Editor
Line Editing

TYPE [range][:n]
Displays a specified range of lines and positions the cursor at the first line of the
specified range.
PARAMETERS

range
The range of lines to be displayed. The range defaults to the current line.
QUALIFIERS

/BRIEF[:n]
Displays the first n characters of the lines contained in the specified range. The
value of n defaults to 10.

/STAY
Prevents the cursor from moving to the first line of the range.
EXAMPLES
*TYPE WHOLE
Displays the entire contents of the current buffer.
♦TYPE 27
Displays line 27.
♦TYPE 40 THRU END
Displays all lines from line 40 through the last line of the buffer.
♦TYPE 40:END all "news"
Displays all lines containing the string "news" that occur between line 40 and the
end of the buffer.

WRITE filename [range]
Copies the specified range of text to the specified file.
PARAMETERS

range
The line or lines of text to be written. The range defaults to the entire current
buffer.
QUALIFIERS

/SEQUENCE[:initial[:increment]]
Assigns sequential line numbers to the file. The initial qualifier defines the
starting line number; the increment qualifier defines the increment between line
numbers.

EDT Editor

EDT-53

Line Editing

EXAMPLES
♦WRITE NEWCHAP.TXT
Copies the entire contents of the current buffer to the file NEWCHAP.TXT. EDT
displays the specification of the new file and the number of lines written to the file.
♦WRITE NEWCHAP.TXT 10:90
Copies lines 10 through 90 of the current buffer to the file NEWCHAP.TXT. EDT
displays the specification of the new file and the number of lines written to the file.
♦WRITE NEWCHAP.TXT =BUF1/SEQUENCE:10:10
Copies the contents of BUF1 to the file NEWCHAP.TXT and renumbers the lines
(beginning with line 10 and incrementing by 10). EDT displays the specification of
the new file and the number of lines written to the file.

EDT.4 Nokeypad Editing
You can redefine keypad keys and control keys by using the DEFINE KEY
line-editing command with EDT nokeypad-editing commands as the definition. EDT
nokeypad commands cannot contain spaces; for example, to delete two paragraphs
and put the text in a buffer named EXTRA, type CUT2PAR=EXTRA. You can put
several EDT nokeypad commands on the same line; spaces between commands are
allowed but not required. You can repeat a series of commands by preceding the
commands with the repeat count and enclosing them in parentheses 3(V D+EL).

EDT.4.1 Text Entities
You can use the following text entities as parameters for EDT nokeypad-editing
commands. The parameters are presented in uppercase, followed by their functions
in parentheses.
PARAMETERS

C (character)
Single alphabetic, numeric, or special character.

W (word)
User-defined entity. The default boundaries are spaces, line terminators,
tabs, and form feeds. You define the word boundaries with the SET ENTITY
command.

BW (beginning of word)
The string of characters from the cursor to the beginning of the word; when the
cursor is at the beginning of a word, BW is the previous word.

edt-54

EDT Editor
Nokeypad Editing

EW (end of word)
The string of characters from the cursor position to the end of the word,
including the character at the cursor position.

L (line)
Single line of text, where L is a string of characters between line terminators.

BL (beginning of line)
The string of characters from the cursor position to the beginning of the line.
When the cursor is at the beginning of a line, BL is the previous line.

EL (end of line)
The string of characters from the cursor position to the end of the line, including
the character at the cursor position.

NL (next line)
The string of characters from the cursor position to the beginning of the next
line.

V (vertical)
The characters starting at the current cursor character and extending to the
character directly above or below in the next line.

SEN (sentence)
User-defined entity. The default boundaries are a period, a question mark, or an
exclamation point (each of which is followed by a space). You can redefine the
sentence boundaries through the SET ENTITY command.

BSEN (beginning of sentence)
The string of characters from the cursor position to the beginning of the sentence.
If you are at the beginning of a sentence, BSEN selects the entire previous
sentence.

ESEN (end of sentence)
The string of characters from the cursor position to the end of the sentence, not
including the sentence delimiter.

PAR (paragraph)
User-defined entity. The default boundaries are two successive line terminators.
You define the paragraph boundary with the SET ENTITY command.

BPAR (beginning of paragraph)
The string of characters from the cursor position to the beginning of the
paragraph. If you are already at the beginning of a paragraph, BPAR selects
the entire previous paragraph.

EDT Editor

EDT-55

Nokeypad Editing

EPAR (end of paragraph)
The string of characters from the cursor position to the end of the paragraph,
including the character at the cursor, but not the paragraph delimiter.

PAGE (page)
User-defined entity. The default is the text between two form-feed characters,
including the second form feed. You define the page boundaries with the SET
ENTITY command.

BPAGE (beginning of page)
The text from the cursor position to the beginning of the page, not including the
page delimiters.

EPAGE (end of page)
The text from the cursor position to the end of the page, not including the page
delimiters.

BR (beginning of range)
The string of characters from the cursor to the beginning of the buffer.

ER (end of range)
The string of characters from the cursor to the end of the buffer.

SR (select range)
The text between the last SEL command and the cursor position. When select
range is not active (no select command entered) and the cursor is at the present
search string, SR selects the search string. When neither of the above conditions
exists, SR selects a single character in the current direction when used with the
CHGC command.

string'
All characters between the initial cursor position and the beginning of 'string.'

EDT.4.2 Nokeypad Commands
The following list of EDT nokeypad-editing commands presents the commands in
uppercase, followed by their functions in parentheses. The word "count" preceded
by "+" or
specifies either the number of times a nokeypad-editing command is to
be repeated or the number of entities that the command will affect. (The maximum
value for the count specifier is 32767.) The symbol "I" is equivalent to the word "or"
in the commands that follow.

EDT-56

EDT Editor
Nokeypad Editing

ADV (advance)
ADV
Sets the cursor's direction forward. (You can override advance for a single
command by preceding that command with a minus sign.)

APPEND (append)
[+ I -][count]APPEND[+ I -][count]entity[=buffer]
Deletes the specified entities in the current buffer and moves them to the end of
the specified buffer (which defaults to the PASTE buffer).

ASC (ASCII)
[number]ASC
Inserts an ASCII character when you specify the character's decimal representa¬
tion (defaults to 0, or NUL).

BACK (backup)
BACK
Sets the cursor's direction backward. (You can override BACK for a single
command by preceding that command with a plus sign.)

BELL (bell)
BELL
Causes the terminal bell to sound when the command is processed. (Used
primarily in keypad key definitions.)

CHGC (change case)
[+ I -][count]CHGC[+ I -][count]entity
Changes the case of the characters within an entity.

CHGL (change case lower)
[+ I -][count]CHGL[+ I -][count]entity
Changes all uppercase letters within a specified entity to lowercase; existing
lowercase letters remain unchanged.

CHGU (change case upper)
[+ I -][count]CHGU[+ I -][count]entity
Changes all lowercase letters within a specified entity to uppercase; existing
uppercase letters remain unchanged.

CLSS (clear search string)
CLSS
Clears the search string currently in the search buffer.

EDT Editor

EDT-57

Nokeypad Editing

CUT (cut)
[+ I -][count]CUT[+ I -][count]entity[=buffer]
Deletes the specified entities from the current buffer, moves them to the specified
buffer (which defaults to the PASTE buffer), and deletes the previous contents of
the receiving buffer.

DATE (date)
DATE
Inserts the current date into your text at the current cursor position.

DELETE (delete)
[+ I -][count]D[+ I -][count]entity
Deletes a specified number of entities.

DEFK (define key)
DEFK
Defines keypad operations in terms of nokeypad-editing commands.

DESEL (deactivate select)
DESEL
Cancels a select range after you have used the SEL (select) command, the SSEL
(search and select) command, or the TGSEL (toggle select) command.

DLWC (default lowercase)
DLWC
Changes all uppercase letters to lowercase letters wherever you move the cursor
during your EDT session. (Use the DMOV (default move) command to reset EDT
so that case is not affected by move operations.)

DMOV (default move)
DMOV
Returns your editing session to EDT's default state after you have used either
DLWC (default lowercase) or DUPC (default uppercase).

DUPC (default uppercase)
DUPC
Changes all lowercase letters to uppercase wherever you move the cursor during
your EDT session. (Use the DMOV (default move) command to reset EDT so
that case is not affected by move operations.)

EX (exit)
EX
Exits to line-editing mode.

edt-58

EDT Editor
Nokeypad Editing

EXT (extend)
EXT
Accepts the rest of the line (after EXT) as a line-editing command.

FILL (fill)
[+ I -][count]FILL[+ I -][count]entity
Places the maximum number of words (within the bounds set by the SET WRAP
or SET SCREEN command) on a line. The default is 80 characters.

HELP (help)
HELP
Defines a different key or key sequence in keypad-editing mode to carry out the
keypad HELP function.

I (insert)
Itext'Z
I RETURN text CTRL/Z
Inserts the text typed immediately following the I or between RETURN and
CTRL/Z to the left of the cursor.

KS (KED substitute)
[PASTEJKS
Moves the cursor either to the beginning or the end of the inserted text at the
completion of the nokeypad PASTE command. The placement of the cursor
depends upon EDT's current direction. (There should not be a space between the
command words PASTE and KS.)

NULL (move cursor)
[+ I -][count]entity
Moves the cursor to the specified entity.

PASTE (paste)
[+ I -][count]PASTE[=buffer]
Copies the contents of the specified buffer to the left of the cursor.

QUIT (quit)
QUIT
Ends the editing session without saving your edits and returns you to the system
command level prompt.

REPLACE (replace)
[+ I -][count]R[+ I -][count]entity
Deletes the specified entities and replaces them with text you insert. Terminate
the insertion of text with a CTRL/Z.

EDT Editor

edt-59

Nokeypad Editing

REF (refresh)
REF
Refreshes the entire screen.

SEL (select)
SEL
Marks the present cursor position as the beginning of a select range of text.
Move the cursor to the desired position to mark the end of the range.

SSEL (search and select)
[+ I -]SSEL[+ I -]“string”
Both finds a string and designates it as a select range in one operation. The string
must be enclosed in quotation marks.

SHL (shift left)
[count]SHL
Shifts the screen image to the left count number of tab stops, where one tab stop
equals 8 columns.

SHR (shift right)
[count]SHR
Shifts the screen image to the right count number of tab stops, where one tab
stop equals 8 columns.

S (substitute)
[+ I -][count]S/string-1 /string-2/
Replaces one string of characters with another. The value of count defines the
number of substitutions. The characters
(backup) and "+" (advance) specify
the direction of the search. Any nonalphanumeric character will work as a
delimiter (so long as it is not used in one of the strings).

SN (substitute next)
[+ I -][count]SN
Uses strings 1 and 2 defined in the last substitute command (stored in the search
and substitute buffers) to replace the next occurrence of string 1 with string
2. The value of count defines the number of substitutions. The characters
(backup) and "+" (advance) specify the direction of the search.

TAB (tab)
[count]TAB
Moves a line of text to the next tab stop or, if a count is specified, to count
number of tab stops.

edt-60

EDT Editor
Nokeypad Editing

TADJ (tab adjust)
[+ I -][level-count]TADJ[+ I -][entity-count]entity
Indents whole lines level-count number of tab stops to create layered text. A
minus sign before the level-count specifier allows you to move text back toward
the left margin. The entity count determines how many lines, paragraphs, or
pages will be affected by the TADJ command. A minus sign before the entity or
entity count means that EDT will work backward in determining which entities
to indent. You must establish a SET TAB value for your EDT editing session
before issuing this command.

TC (tab compute)
TC
Establishes the present cursor position and resets the indentation level count to
be the quotient of the cursor position divided by the SET TAB value. The cursor
position must be a multiple of the SET TAB value.

TD (tab decrement)
[count]TD
Decreases the current indentation level count by the amount indicated by the
count specifier.

Tl (tab increment)
[count]TI
Increases the current indentation level count by the amount indicated by the
count specifier.

TGSEL (toggle select)
TGSEL
Performs the same function as the DSEL command (cancels the select range)
when there is an active select range. When there is no active select range,
TGSEL performs the same function as the SEL command (initiates the process of
creating a select range).

TOP (top)
TOP
Places the current line at the top of the screen.

UNDO (undelete character)
[count]UNDC
Inserts the contents of the character buffer into the current buffer to the left of
the cursor. The character buffer contains the last character deleted by one of the
delete character commands. Count repeats the UNDC operation count number of
times.

EDT Editor

EDT-61

Nokeypad Editing

UNDL (undelete line)
[count]UNDL
Inserts the contents of the line buffer into the current text buffer just ahead of
the cursor. The line buffer contains the last line deleted by one of the delete-line
editing commands. Count repeats the UNDL operation count number of times.

UNDW (undelete word)
[count]UNDW
Inserts the contents of the word buffer into the current buffer to the left of the
cursor. The word buffer contains the last word deleted by one of the delete word
commands. Count repeats the UNDW operation count number of times.

(circumflex)
[count]~[A...Z]
Enters a control character in your text. The value of count controls the number
of times the operation is performed.

Appendix ESC
Escape Sequences

This appendix describes the escape sequences on VT200 and VT100 series term
Chapter 1 explains how to use them. The escape sequences are arranged here
according to function, and the following table briefly summarizes the common
sequences.
CURSOR x=integer (Default=l)
up
down
right
left

—<ESC> [xA
—<ESC> [xB
— <ESC>[xC
— <ESC>[xD

Position
row, column—<ESC> [r;cH
column, row—<ESC> [c;rf
ERASING
cursor to eol — <ESC> [OK
bol to cursor—<ESC> [IK
entire line — < ESC > [2K
cursor to eos— <ESC> [0]
bos to cursor—<ESC> [1]
entire screen — <ESC> [2J

<ESC> [xm where x is:
0—off
1—bold
4—underscore
5—blink
7—reverse video
double height (top)
double height (bot)
single width (default)
double width

—<ESC>#3
—<ESC> #4
—<ESC> #5
—<ESC> #6

CHARACTER SETS
US
UK
GRAPHIC

on
<ESC> (B
<ESC> (A
<ESC> (0

off
<ESC> )B
<ESC> )A
<ESC>)0

RESET

SCROLLING REGION
<ESC> [t;br

CHARACTER ATTRIBUTES

(t < b)

<ESC> c

ZK-1763-

NOTE: If your terminal is not in the VT200 series or VT100 series, consult y
terminal user guide for the appropriate escape sequences for your terminal.

ESC.1

Moving the Cursor

The following table lists the escape sequences that allow you to move the cursor,
where n represents an integer that determines the number of character positions or
lines that the cursor is to move. If you omit n, the number defaults to one. In the
escape sequence that positions the cursor, r and c represent integers that indicate the
row number and the column number, respectively.
Escape Sequence

Function

<ESC> [nA

Move cursor up; no scrolling

<ESC> M

Move cursor up; scrolls within scrolling region

<ESC> [nB

Move cursor down; no scrolling

Move cursor down; scrolls within scrolling region

<ESC> [nC

Move cursor right

<ESC> [nD

Move cursor left

<ESC> E

Move cursor to the beginning of the next line

<ESC> [r;cH

Position cursor on the screen

<ESC> 7

Save cursor's column position and character attributes

<ESC> 8

Restore cursor's column position and character attributes

A carriage return moves the cursor to the beginning of the next line. Therefore,
if you want text to appear on the screen at a certain place, be sure that the text
immediately follows the escape sequence that positions the cursor. Putting a carriage
return between the escape sequence and the text causes the text to be written at the
beginning of the next line.

ESC.2 Setting Character Sets and Characteristics

Escape sequences allow you to choose a character set from a given group of character
sets. You can choose character sets permanently (using locking shifts) or for the
insertion of just the next character you enter (using single shifts).

Escape Sequences

ESC-3

Setting Character Sets and Characteristics

ESC.2.1 Specifying Character Sets
The VT200 and VT100 series terminals allow you to specify three different character
sets:
1.

US (default)—The ASCII character set. The escape sequence <ESC> (B
specifies the US character set.

UK—The same as the US character set with the exception that pressing SHIFT/3
echoes the pound sign used in the United Kingdom rather than the number sign
used in the United States. The escape sequence <ESC> (A specifies the UK
character set.

Graphic—The graphic character set echoes a different set of characters for ASCII
codes 5F through 7E. The escape sequence <ESC> (0 specifies the graphic
character set.

On VT200 series terminals it is also possible to specify downline loadable (or "soft")
character sets. For information on designating soft character sets, refer to your
terminal's reference manual.
Selecting a character set is a two-step process. The following figure illustrates the
procedure for selecting character sets.

esc-4

Escape Sequences
Setting Character Sets and Characteristics

To select a character set from the graphic repertory, you must first use character set
selection sequences to designate a graphic set. This marks the graphic set and makes
it available (or "on call") for use later in your program. You may designate up to
two character sets each for both locking shift and single shift operations; locking
shifts designate GO and G1 and single shifts designate G2 and G3. Character sets
remain designated until you enter another character set selection escape sequence.
The following table lists the escape sequences you use to designate character sets.

Escape Sequences

esc-5

Setting Character Sets and Characteristics

Character Set
ASCII

U.K. National
Graphic

Escape Sequence

Designate as:

ESC(B

ESC)B

ESC(A

ESC)A

ESC(0

ESC)0

To actually map any one of these sets into GL, you must then invoke any of GO
through G3 into GL. The GL block contains the graphic characters with decimal
values 33 through 127; these are the only characters that are affected when you
invoke different character sets. The CO (Control) block contains graphic characters
with decimal values 0 through 32; these characters are not affected by invoking
different character sets. You invoke character sets using either locking shifts or
single shifts, depending upon whether you want to select a particular character set
for extended use or for the insertion of just a single character. When using locking
shifts, you should always invoke GO first, leaving G1 available for the designation
of another character set. The following table lists the locking shift and single shift
control functions used to invoke character sets.

Control Name

Coding

Function

LSO - Lock Shift GO

Invoke GO into GL (default)

LSI - Lock Shift G1

Invoke G1 into GL

SS2 - Single Shift G2

SS2 (or ESC N)

Invoke G2 into GL

SS3 - Single Shift G3

SS3 (or ESC O)

Invoke G3 into GL

All locking shifts remain active until you issue another locking shift; single shifts
remain active for only the next single graphic character. The default graphic character
set mapping is reset whenever you turn on your terminal.

ESC.2.2 Specifying Display Characteristics
The following table lists the escape sequences that allow you to specify the display
characteristics. (When programming, you should use the screen package rather than
escape sequences.)
Escape Sequence

Function

<ESC> [Om (default)

Write normal characters

<ESC> [lm

Write bold characters

<ESC> [4m

Write underlined characters

<ESC> [5m

Write blinking characters

<ESC> [7m

Write reverse video characters

<ESC> #3

Write double height (top half)

<ESC> #4

Write double height (bottom half)

<ESC> #5

Write single width (default)

<ESC> #6

Write double width

<ESC> 7

Save cursor's column position and character attributes

<ESC> 8

Restore cursor's column position and character attributes

NOTE:

The height functions cannot be used with the graphic character set.

ESC.3 Erasing the Screen
The following table lists the escape sequences that allow you to erase specified
sections of text. After text is erased, the cursor is left where the erasing completed
(for example, erasing from cursor to end of line leaves the cursor at the end of the
line, erasing from beginning of line to cursor leaves the cursor at its original position).
Erasing text does not affect the current character attributes.
Escape Sequence

Erase Function

<ESC> [OK

From cursor to end of line

<ESC> [IK

From beginning of line to cursor

<ESC> [2K

Entire line

<ESC> [OJ

From cursor to end of screen

<ESC> [1J

From bottom of screen to cursor

<ESC> [2J

Entire screen

Escape Sequences

esc-7

Creating a Scrolling Region

ESC.4 Creating a Scrolling Region
A scrolling region is a horizontal section of the screen within which the text scrolls.
The text above and below the scrolling region remains stationary. The following
table lists the escape sequences that allow you to create a scrolling region and to
define whether cursor position 0,0 means the upper left corner of the screen or the
upper left corner of the scrolling region.
In the first escape sequence, t and b represent integers that indicate the first and last
lines of the scrolling region. Both integers must be between 1 and 24; t must be less
than b.

Escape Sequence

Function

<ESC> [t;br

Set up a scrolling region

<ESC> [?6h

Set cursor position 0,0 equal to the upper left corner of the
scrolling region

<ESC> [?61 (default)

Set cursor position 0,0 equal to the upper left corner of the
screen

ESC.5 Setting Terminal Characteristics
Section 1.3 describes the setup functions that allow you to set the terminal attributes.
Many of these attributes can also be set with escape sequences.
The RESET key used in setup to reset the default terminal attributes can be
duplicated with the <ESC> escape sequence.
The following table lists the escape sequences that allow you to set the terminal
attributes that you would normally set from the Display and Tab Set-Up screens on
VT200 series terminals or from SET-UP A on VT100 series terminals.
Escape Sequence

Function

<ESC> [?31

Set screen width to 80 columns

<ESC> [?3h

Set screen width to 132 columns

<ESC> H

Set tab at current column

<ESC> [g or <ESC> [Og

Clear tab at current column

<ESC> [3g

Clear all tabs

Escape Sequences

ESC-8

Setting Keypad Characteristics

ESC.6 Setting Keypad Characteristics
On both the VT200 and VT100 series terminals, the auxiliary keypad to the right of
the main keyboard and the four arrow keys to the left of that keypad can be set to
generate data or escape sequences. By default, the arrow keys and the PFn keys (on
the top row of the keypad) generate escape sequences, and the remaining keypad
keys generate data.
To make the keypad generate numeric values, use the SET TERMINAL/NUMERIC
command or the <ESC> > escape sequence. To make the keypad keys generate
application values, use the SET TERMINAL/APPLICATION command or the
<ESC> = escape sequence.
The following table lists the code generated by the auxiliary keypad keys for both
the numeric and application keys. The values generated by these keys are identical
on VT200 and VT100 series terminals.
Key

Numeric

Application

<ESC> Op

<ESC> Oq

<ESC> Or

<ESC> Os

<ESC> Ot

<ESC> Ou

<ESC> Ov

<ESC> Ow

<ESC> Ox

<ESC> Oy

- (minus)

<ESC> Om

, (comma)

<ESC> Ol

. (period)

<ESC> On

ENTER

RETURN

<ESC> OM

PF1

<ESC> OP

PF2

<ESC> OQ

PF3

<ESC> OR

PF4

<ESC> OS

The following table lists the codes generated by the arrow keys in both Cursor Key
Mode Set and Cursor Key Mode Reset.

Escape Sequences

esc-9

Setting Keypad Characteristics

Key

Cursor Key Mode Reset

Cursor Key Mode Set

Up arrow

<ESC> [A

<ESC> OA

Down arrow

<ESC> [B

<ESC> OB

Left arrow

<ESC> [C

<ESC> OC

Right arrow

<ESC> [D

<ESC> OD

In addition to the keys described above, the VT200 series terminal has a set of six
editing keys located between the main keyboard and the auxiliary keypad and a
row of 20 function keys located above the main keyboard. The first five function
keys (FI through F5) do not transmit codes; they are local keys. Function keys F6
through FI4 are VMS-defined. (See Appendix KEY for a table listing these operating
system-defined keys.) Applications that wish to make use of keys F6 through FI4
(to generate the code listed in the table below) should insert the following command
into their $QIO function code:

IO$_READVBLK ! IO$M_NOFILTR
By default, function keys F15 (Help), F16 (Do), and F17 through F20 generate the
codes listed below.
The following table lists the editing keypad keys and function keys along with the
codes they generate.

Generic Key Name

Code Generated

Find (El)

<ESC> [1~~

Insert Here (E2)

<ESC> [2~

Remove (E3)

<ESC> [3~

Select (E4)

<ESC> [4~

Prev Screen (E5)

<ESC> [5~

Next Screen (E6)

<ESC> [6~

<ESC> [17~

<ESC> [18~

<ESC> [19

<ESC> [20~

F10

<ESC> [21 ~

Fll

<ESC> [23~

F12

<ESC> [24

F13

<ESC> [25~

F14

<ESC> [26

Generic Key Name

Code Generated

Help (F15)

<ESC> [28~

Do (F16)

<ESC> [29~~

F17

<ESC> [31~

F18

<ESC> [32^

F19

<ESC> [33~

F20

<ESC> [34

Appendix EXP
Expressions

The following table lists data operations and comparisons in order of preceden
beginning with the highest.
Operator

Precedence

Description

Indicates a positive number

Indicates a negative number

Multiplies two numbers

/
+

Divides two numbers

(1) Adds two numbers

(1) Subtracts two numbers (2) Subtracts two character strin

.EQS.

Tests if two character strings are equal

.GES.

Tests if first character string is greater than or equal

.GTS.

Tests if first character string is greater than

.LES.

Tests if first character string is less than or equal

.LTS.

Tests if first character string is less than

.NES.

Tests if two character strings are not equal

.EQ.

Tests if two numbers are equal

.GE.

Tests if first number is greater than or equal to

.GT.

Tests if first number is greater than

.LE.

Tests if first number is less than or equal to

.LT.

Tests if first number is less than

.NE.

Tests if two numbers are not equal

.NOT.

Logically negates a number

.AND.

Combines two numbers with a logical AND

.OR.

Combines two numbers with a logical OR

(2) Concatenates two character

The following tables demonstrate the results of logical operations on a bit-by-bi
and a number-by-number basis. In logical operations, a character string beginn

with an uppercase or lowercase T or Y is treated as the number 1; a character string
beginning with any other character is treated as the number 0. In logical operations,
odd numbers are considered true and even numbers and zero are considered false.
Given
Bit A

Bit B

Results
.NOT A

A .AND. B

A .OR. B

Given
Number A

Number B

Results
.NOT A

A .AND. B

A .OR. B

odd

even

odd

even

odd

even

odd

even

odd

even

odd

even

Appendix KEY
Terminal Keys
The following tables present the operating system's interpretation of keys on
terminals in the VT200 and VT100 series.

KEY.1

VT200 Terminal Series

The following table describes how the operating system responds when various keys
and control characters are pressed on VT200 series terminals. The table assumes
that line editing is enabled (the default). (Characters not mentioned in the table are
treated as null characters.)
Character

HEX

System Response
Switches between overstrike and insert modes

CTRL/A

CTRL/B

Recalls previous line

CTRL/C

Interrupts current image (image may define alternate CTRL/C
action)

CTRL/D

Moves cursor left one character

CTRL/E

Moves cursor to end of line

CTRL/F

Moves cursor right one character

CTRL/H

Moves cursor to beginning of line

CTRL/I

Horizontal tab

CTRL/J

Deletes previous word

CTRL/M

Line terminator

CTRL/O

Suspends/resumes echoing of output

CTRL/Q

Resumes output (see CTRL/S)

CTRL/R

Refreshes current line

CTRL/S

Suspends output (see CTRL/Q)

Character

HEX

System Response

CTRL/T

Displays process information (must be enabled with SET
CONTROL=T command)

CTRL/U

Deletes characters from cursor to beginning of line

CTRL/V

Passes next character or escape sequence to the image
without interpreting it as described in this table

CTRL/X

Purges type-ahead buffer; if characters are on the current
line, deletes characters from cursor to beginning of line

CTRL/Y

Interrupts current image

CTRL/Z

Indicates end of file

Data keys

Enter appropriate character

<23

Deletes previous character

CTRL

Modifies another key

CTRL/[ (ESC)

Begins escape sequence

CTRL/F5

Executes answerback message

DOWN ARROW

Repeats current line

FI (No Scroll)

Suspends/resumes output

F5 (Break)

Shuts down transmission line

F6 (Interrupt)

Interrupts the current image

F10 (Exit)

Terminates the current image or command procedure

FI2 (Backspace)

Moves cursor to beginning of line

FI3 (Line Feed)

Deletes previous word

F14 fA)

Switches between overstrike and insert modes

LEFT ARROW

Moves cursor left one character

PFn

Can be defined (see DEFINE/KEY)

RETURN

Line terminator

RIGHT ARROW

Moves cursor right one character

TAB

Horizontal tab

UP ARROW

Repeats current line

KEY.2 VT100 Terminal Series
The following table describes how the operating system responds when various keys
and control characters are pressed on VT100 terminals. The table assumes that line
editing is enabled (the default). (Characters not mentioned in the table are treated as
null characters.)

Character

HEX

System Response

CTRL/A

Switches between overstrike and insert modes

CTRL/B

Recalls previous line

CTRL/C

Interrupts current image (image may define alternate CT
action)

CTRL/D

Moves cursor left one character

CTRL/E

Moves cursor to end of line

CTRL/F

Moves cursor right one character

CTRL/H

Moves cursor to beginning of line

CTRL/I

Horizontal tab

CTRL/J

Deletes previous word

CTRL/M

Line terminator

CTRL/O

Suspends/resumes echoing of output

CTRL/Q

Resumes output (see CTRL/S)

CTRL/R

Refreshes current line

CTRL/S

Suspends output (see CTRL/Q)

CTRL/T

Displays process information

CTRL/U

Deletes characters from cursor to beginning of line

CTRL/V

Passes next character or escape sequence to the image w
interpreting it as described in this table

CTRL/X

Purges type-ahead buffer; if characters are on the curren
deletes characters from cursor to beginning of line

CTRL/Y

Interrupts current image

CTRL/Z

Indicates end of file

Data keys

Enter appropriate character

Backspace (~H)

Moves cursor to beginning of line

BREAK

Shuts down transmission line

CTRL

Modifies another key

CTRL/BREAK

Executes answerback message

DELETE

Deletes previous character

DOWN ARROW

Repeats current line

ESC

Begins escape sequence

LEFT ARROW

Moves cursor left one character

LINE FEED

Deletes previous word

NO SCROLL

Suspends/resumes output

PFn

Can be defined (see DEFINE/KEY)

Character

HEX

System Response

RETURN

Line terminator

RIGHT ARROW

Moves cursor right one character

TAB

Horizontal tab

UP ARROW

Repeats current line

Appendix LEX
Lexical Functions
The following tables list the lexical functions by category. The remainder of the
appendix describes each function in alphabetical order.
Integer/character string conversion:

Function

Description

F$TYPE

Determines whether a symbol is a number or a string

F$INTEGER

Converts a character string to a number

FSSTRING

Converts a number to a character string

F$CVSI

Converts a bit string to a signed integer

F$CVUI

Converts a bit string to an unsigned integer

Character string manipulation:

Function

Description

F$ LENGTH

Returns the length of a character string

FSLOCATE

Returns the location of a substring

F$EXTRACT

Returns a substring

FSELEMENT

Returns one of a list of elements

Text formatting:
Function

Description

F$EDIT

Edits a string

F$FAO

Creates character strings from character strings, numbers, and special
directives

Time:
Function

Description

F$TIME

Returns the current date and time

FSCVTIME

Converts a date/time for comparison

Devices and files:
Function

Description

F$DIRECTORY

Returns the name of the default directory

F$FILE—ATTRIBUTES

Returns information on a file

F$GETDVI

Returns information on a device

FIIDENTIFIER

Returns the numeric equivalent of an alphanumeric identifier or vice
versa

FSPARSE

Returns a file specification given a partial specification and defaults

F$SEARCH

Returns specific file specifications given a file specification containing
wildcards

FSTRNLNM

Returns the equivalence string or attributes of a logical name

Environment:
Function

Description

F$ENVIRONMENT

Returns information about the DCL command environment

F$GETJPI

Returns information about a process

FSPROCESS

Returns the name of the current process

F$PRIVILEGES

Returns the current process privileges

F$SETPRV

Sets process privileges

F$USER

Returns the UIC of the current process in alphanumeric format

F$PID

Returns process identification numbers of processes using the system

F$MODE

Returns the process type—interactive, batch, or network

F$ VERIFY

Returns or sets the verification mode

F$MESSAGE

Returns a system message given the code

FSGETSYI

Returns information about the system

Lexical Functions

lex-3

F$CVSI

F$CVSI (start-bit,number-of-bits,string)
Converts the specified bits in the specified character string to a signed number.
ARGUMENTS

start-bit
The offset of the starting bit.

number-of-bits
The length of the bit string, which must be less than or equal to the number of
bits in the string.

string
The character string to be edited.
The following example converts the low-order four bits of the ASCII character + (the
bit configuration of this character is 00101011—hexadecimal 2B) to a signed number.
$ L0W_F0UR = F$CVSI (0,4,"+")
$ SHOW SYMBOL L0W.F0UR
L0W_F0UR = -5
Hex = FFFFFFFB

Octal = 177773

F$CVTIME ([input-time],[format],[field])
Given a character string containing a time, F$CVTIME returns the time or a field of
the time in the specified format. If you omit arguments, commas to the left of the
last specified argument must be included as place holders.
ARGUMENTS

input-time
A string containing an absolute, combination, or delta time, or TODAY,
TOMORROW, or YESTERDAY. (Section 5.4 describes absolute, delta, and
combination formats.) If input-time is omitted or specified as a null string (""),
the current system date and time, in absolute format, is used. If parts of the date
field are omitted, the missing values default to the current date. If parts of the
time field are omitted, the missing values default to zero.

format
A character string containing one of the following (do not abbreviate):
ABSOLUTE, COMPARISON (default), or DELTA. Comparison format ("yyyymm-dd hh:mm:ss.cc") is used for comparing two times. If input-time is a delta
time, you must specify DELTA. If input-time is an absolute or combination time,
format can be either ABSOLUTE or COMPARISON.

lex-4

Lexical Functions
F$CVTIME

field
A character string containing one of the following (do not abbreviate): DATE,
MONTH, DATETIME (default), SECOND, DAY, TIME, HOUR, WEEKDAY,
HUNDREDTH, YEAR, MINUTE. If input-time is a delta time and format is
DELTA, you cannot specify MONTH, WEEKDAY, or YEAR.
The following example returns the current system time in comparison format.
$ TIME = F$CVTIME ()
$ SHOW SYMBOL TIME
TIME = "1984-10-15 20:42:03.21"
The next example shows which weekday May 6, 1984 lands on:
$ DAY = F$CVTIME ("6-MAY-1984""WEEKDAY")
$ SHOW SYMBOL DAY
DAY = "Sunday"

F$CVUI (start-bit,number-of-bits,string)
Converts the specified bits in the specified character string to an unsigned number.
ARGUMENTS

start-bit
The offset of the starting bit.

number-of-bits
The length of the bit-string, which must be less than or equal to the number of
bits in string.

string
The character string to be edited.
The following example converts the low-order four bits of the ASCII character +
(the bit configuration of this character is 00101011—hexadecimal 2B) to an unsigned
number.
$ L0W.F0UR = F$CVUI (0,4,"+")
$ SHOW SYMBOL L0W.F0UR
L0W.F0UR =11
Hex = 0000000B

Octal = 000013

Lexical Functions

lex-5

F$DIRECTORY

F$DIRECTORY ()
Returns the current default directory as a character string, as shown in the following
example.
$ DEFAULT = F$DIRECTORY ()
$ SHOW SYMBOL DEFAULT
DEFAULT = "[ACCOUNTS]"

F$EDIT (string,edit-list)
Edits the character string as specified by edit-list.
ARGUMENTS

string
A character string to be edited. Quoted sections of the string are not edited.

edit-list
A character string containing one or more of the following keywords (do not
abbreviate, separate keywords with commas).

Edit

Action

COLLAPSE

Removes all spaces or tabs

COMPRESS

Replaces multiple spaces or tabs with a single space

LOWERCASE

Changes all uppercase characters to lowercase

TRIM

Removes leading and trailing spaces or tabs

UNCOMMENT

Removes comments

UPCASE

Changes all lowercase characters to uppercase

The following example compresses the line and removes leading and trailing spaces.
$ LINE = "
Could it have
been a clearer
$ LINE = F$EDIT (LINE. "COMPRESS.TRIM")
$ SHOW SYMBOL LINE
LINE = "Could it have been a clearer day?"

F$ELEMENT (number,delimiter,string)
Extracts one element from a string of elements.

day? "

lex-6

Lexical Functions
F$ELEMENT

ARGUMENTS

number
The number of the element to extract (numbering begins with zero). If number
exceeds the number of elements in the string, F$ELEMENT returns the delimiter.

delimiter
A character used to separate the elements.

string
A string containing the delimited list of elements.
The following command procedure processes files named CHAP1, CHAP2, ...
CHAP6, CHAPA, CHAPB, and CHAPC, in that order. (0 is included in the
CHAPTERS string to clarify the procedure logic).
$
$
$
$
$
$
$
$
$

! INDEX.COM
!
CHAPTERS = "0,1,2,3,4,5,6,A,B,C"
NEXT = 0
LOOP:
NEXT = NEXT + 1
NUM = F$ELEMENT(NEXT,",".CHAPTERS)
RUN INDEX CHAP’NUM’
IF (CHAPTERS .NES. ",") THEN GOTO LOOP

F$ENVIRONMENT (item)
Returns information about the current DCL command environment.
ARGUMENTS

item
A character string containing one of the following (do not abbreviate):
Item

Data

Information Returned

CAPTIVE

string

TRUE if you are logged into a captive account,

CONTROL

string

Control characters currently enabled with SET
CONTROL. Multiple characters are separated
by commas; if no control characters are enabled,
the null string is returned.

DEFAULT

string

Current default device and directory,

DEPTH

integer

Current command procedure depth.

Data

Information Returned

INTERACTIVE

string

TRUE if the process is executing interacti

KEY—STATE

string

Current locked keypad state; see the DE
/KEY command in Appendix DCL.

MAX—DEPTH

integer

Maximum allowable command procedure

MESSAGE

string

Current setting of SET MESSAGE qualifi
each qualifier is prefaced by a slash.

NOCONTROL

string

Currently disabled control characters. M
characters are separated by commas; if n
control characters are disabled, the null s
returned.

ON-CONTROL _Y

string

TRUE if ON_CONTROL_Y is set.
ON—CONTROL—Y always returns FALS
DCL command level.

ON_SEVERITY

string

Severity level at which the action specifi
the ON command is performed.
ON-SEVERITY returns NONE when SE
NOON is in effect or at DCL command

OUTPUT-RATE

string

Delta time indicating how often data is w
to the batch job log file. OUTPUT-RAT
returns a null string if used interactively.

PROCEDURE

string

File specification of the current comman
procedure. PROCEDURE returns a null
used interactively.

PROMPT

string

Current DCL prompt.

PROMPT-CONTROL

string

TRUE if a carriage return and line feed p
the prompt.

PROTECTION

string

Current default file protection.

SYMBOL-SCOPE

string

[NO]LOCAL,[NO]GLOBAL to indicate th
current symbol scoping state.

VERIFY—IMAGE

string

TRUE if image verification is in effect; se
VERIFY=IMAGE in Appendix DCL.

VERIFY—PROCEDURE

string

TRUE if procedure verification is in effec
SET VERIFY=PROCEDURE in Appendix

Item

lex-8

Lexical Functions
F$ENVIRONMENT

The following command procedure saves a user's default device, directory, and
protection, executes a series of commands that may change those defaults, and then
restores the original defaults.
$
$
$
$

! PROCEDURE.COM
!
OLD.DEFAULT = F$ENVIR0NMENT("DEFAULT")
0LD.PR0T = F$ENVIR0NMENT("PROTECTION")
.

! commands

$ SET DEFAULT 1OLD.DEFAULT’
$ SET PROTECTION^’0LD.PR0T’)/DEFAULT

F$EXTRACT (start,length,string)
Extracts the specified characters from the specified string.
ARGUMENTS

start
The offset of the starting character.

length
The number of characters to extract; must be less than or equal to the size of the
string.

string
The character string to be edited.
The following example (which would be in a command procedure) reads a character
string from the terminal and extracts the first character.
$
$
$
$

! PROCEDURE.COM
!
INQUIRE YN /NOPUNCTUATION "Do you want to continue? »
YN = F$EXTRACT (0,1,YN)

F$FAO (format-instructions,[data-entity,...])
Creates character strings from character and numeric input (FAO stands for formatted
ASCII output). Formatting instructions convert numbers to character strings, insert
carriage returns and form feeds, insert text, and so on.

format-instruction

Character string (enclose in quotation marks or equate to a symbol) consis
text and directives. Directives take the following forms:
!code

One directive

!repeat(code)

A directive repeated a specified number of times

!length-code

A directive affecting an output field of a specified

Irepeat(length-code)

A directive affecting an output field of a specified
repeated a specified number of times

data-entity

Arguments required by the FAO directives used in the control string. Spec
data entities as integer or character string expressions.
The directives and their parameter requirements are as follows:
Instruction

Description

Parameter

Character string insertion
!AS

Inserts a character string as is. The field length
defaults to the length of the character string.
Short values inserted in explicit-length fields
are left-justified and blank filled. Long values
inserted in explicit-length fields are truncated on
the right

Character string

Zero-filled numeric conversion
!OB
!OW
!OL

Converts a byte, word, or longword to octal
notation1

!XB
!XW
!XL

Converts a byte, word or longword to
hexadecimal notation.1

A number. For
and word conve
only the low-or
and 16 bits are

^The output field lengths default to 2 (byte), 4 (word), and 8 (longword) for hexadecimal; 3, 6,
for octal; and the required number of characters for decimal.

The numbers in the output field are right-justified and zero-filled on the left. For hexadecimal a
numbers: explicit-length fields longer than the default are blank-filled on the left; explicit-lengt
shorter than the default are truncated on the left. For decimal numbers: explicit-length fields l
than the default are zero-filled on the left; explicit-length fields shorter than the default are fill
asterisks.

!ZB
!ZW
!ZL

Converts a byte, word, or longword to decimal
notation.1

Blank-filled numeric conversion
!UB
!UW
!UL

Converts a byte, word, or longword to decimal
notation without adjusting
for negative numbers.2

!SB
!SW
!SL

Converts a byte, word, or longword to decimal
notation with negative numbers converted
properly.2

A number. For byte
and word conversions,
only the low-order 8
and 16 bits are used.

1 The output field lengths default to 2 (byte), 4 (word), and 8 (longword) for hexadecimal; 3, 6, and 11
for octal; and the required number of characters for decimal.
The numbers in the output field are right-justified and zero-filled on the left. For hexadecimal and octal
numbers: explicit-length fields longer than the default are blank-filled on the left; explicit-length fields
shorter than the default are truncated on the left. For decimal numbers: explicit-length fields longer
than the default are zero-filled on the left; explicit-length fields shorter than the default are filled with
asterisks.
zOutput field lengths default to the required number of characters. Values shorter than explicit-length
fields are right-justified and blank-filled. Values longer than explicit-length fields cause the field to be
filled with asterisks.

Instruction

Description

Parameter

Special formatting

Inserts a carriage return.

!—

Inserts a tab.

Inserts a form feed.

Inserts an exclamation point.

!%I

Converts a longword integer to an alphanumeric
UIC in the format
[group,member].

!%S

Inserts an uppercase S if the most recently
converted number is not 1.

!%U

Converts a longword integer to a numeric UIC in
the format [group,member]. The directive inserts
the brackets and the comma.

!n <...!>

Left justifies and blank fills all data represented
by the ellipsis in fields n characters wide.

!n*c

Repeats the character represented by c n times.

None.

Integer

Lexical Functions

lex-ii

F$FAO

Time
!%T

Inserts the current time.

A literal 0.

!%D

Inserts the current date/time.

A literal 0.

Parameter Interpretation
j_

Reuses the last parameter.

Skips the next parameter.

None.

For example, !SL means convert a number to a character string; !2(SL) means convert
two numbers; !8SL means convert a number and put it in an 8-character field; and
!2(8SL) means convert two numbers and put them in 8-character fields. Character
data other than directives can be mixed with the directives and appears in the output
as it is typed. For example, COMPLAINTS18SL creates a character string consisting
of the word COMPLAINTS followed by a converted number in an 8-character field.
To create a literal exclamation point, type a double exclamation point.
You can specify the repeat and length portions of a directive as literal numbers or in
variable format by substituting a number sign. The number sign indicates that the
repeat or length number is the value of the next parameter.
For each directive that works upon a data entity, you must supply the data entity
as a literal or symbol in the parameter list. The following command, for example,
converts the number equated to COMPLAINT_COUNT to a character string.
$ REP0RT_1 = F$FA0("!SL",COMPLAINT_COUNT)

Parameters must correspond exactly to the order of their respective directives.
Remember that repeat counts require the specified number of parameters. In the
following example, the literal "Complaints" corresponds to the formatting instruction
!AS, while COMPLAINT_COUNT_l and COMPLAINT_COUNT_2 correspond to
the instruction !2(8SL).
$ REP0RT_1 = F$FAO("!AS!2(8SL)",)_$ "Complaints",C0MPLAINT_C0UNT_1,C0MPLAINT_C0UNT_2

If you misplace a parameter, you will probably not receive an error message, but the
output will be incorrect.

F$FILE_ATTRIBUTES (file-spec,item)
Returns a specified item of information about a specified file.

lex-12

Lexical Functions
F$FILE_ATTRIBUTES

ARGUMENTS

file-spec
A character string containing a file specification with no wildcards.

item
A character string containing one of the following (do not abbreviate):
Item

Data Type

Information Returned

ALQ

integer

Allocation quantity

BDT

string

Backup date/time

BKS

integer

Bucket size

BLS

string

Block size

CBT

string

TRUE if contiguous-best-try

CDT

string

Creation date/time

CTG

string

TRUE if contiguous

DEQ

integer

Default extension quantity

DID

string

Directory identification

DVI

string

Device name

EDT

string

Expiration date/time

EOF

integer

Number of blocks used

FID

string

File identification

FSZ

integer

Fixed control area size

GRP

integer

Owner group number

KNOWN

string

TRUE if file is installed.

MBM

integer

Owner member number

MRN

integer

Maximum record number

MRS

integer

Maximum record size

NOA

integer

Number of areas

NOK

integer

Number of keys

ORG

string

File organization (SEQ, REL, IDX)

PRO

string

File protection

PVN

integer

Prologue version number

Item

Data Type

Information Returned

RAT

string

Record attributes (CR, PRN, FTN)

RCK

string

TRUE if read check

RDT

string

Revision date/time

RFM

string

Record format (VAR, FIX, VFC, UDF)

RVN

integer

Revision number

UIC

string

Owner UIC

WCK

string

TRUE if write check

The following example returns the file identification of 1983.DAT.
$ FILEID = F$FILE_ATTRIBUTES ("1983.DAT"."FID")
$ SHOW SYMBOL FILEID
FILEID = "(65,1,0)"

F$GETDVI (device-name,item)
Returns a specified item of information about a specified device.
ARGUMENTS

device-name

A character string containing a physical device name or a logical name eq
to a physical device name.

item
A character string containing one of the following (do not abbreviate):
Item

Data Type

Information Returned

ACPPID

string

ACP process identification

ACPTYPE

integer

ACP type code

ALL

string

TRUE if device is allocated

ALLDEVNAM

string

Allocation class device name

AVL

string

TRUE if device is available

CCL

string

TRUE if carriage control device

CLUSTER

integer

Volume cluster size

CONCEALED

string

TRUE if device is a concealed device

CYLINDERS

integer

Number of cylinders on the volume

DEVBUFSIZ

integer

Device buffer size

Item

Data Type

Information Returned

DEVCHAR

integer

Device characteristics

DEVCHAR2

integer

More device characteristics

DEVCLASS

integer

Device class (value): Disk device (1), Tape
(2), Synchronous communications device
(32), Terminal (66), Real-time (96), Bus (128),
Mailbox (160), Miscellaneous device (200)

DEVDEPEND

integer

Device dependent information

DEVDEPEND2

integer

More device dependent information

DEVLOCKNAM

string

Device lock name

DEVNAM

string

Device name

DEVSTS

integer

Device dependent status information

DEVTYPE

integer

Device type (value): KLESI (5), TK50P (8),
RQDX1 (7), RQDX2 (7), RL02 (10), TK50
(10), RRD50 (13), DEQNA (22), DMV11 (23),
Removable RC25 (23), Fixed RC25 (24), RD51
(25), RX50 (26), RD52 (27), RD53 (28), CDR50
(34), VT100 (96), VT240 (110)

DIR

string

TRUE if device is directory structured

DMT

string

TRUE if device is marked for dismount

DUA

string

TRUE if the device is a generic device

ELG

string

TRUE if error logging is enabled

ERRCNT

integer

Error count

EXISTS

string

TRUE if the device exists on the system

FOD

string

TRUE if file-oriented device

FOR

string

TRUE if device is mounted foreign

FREEBLOCKS

integer

Free blocks left on the volume

FULLDEVNAM

string

Fully qualified device name

GEN

string

TRUE if device is generic

IDV

string

TRUE if device is capable of input

LOGVOLNAM

string

Logical volume name

MAXBLOCK

integer

Number of logical blocks on the volume

MAXFILES

integer

Maximum files on volume

MBX

string

TRUE if device is a mailbox

MNT

string

TRUE if device is mounted

MOUNTCNT

integer

Mount count

NET

string

TRUE if network device

Item

Data Type

Information Returned

NEXTDEVNAM

string

Device name of next volume in volume

ODV

string

TRUE if device is capable of output

OPCNT

integer

Operation count

OPR

string

TRUE if device is an operator

OWNUIC

integer

UIC of device owner

PID

string

Process identification of device owner

RCK

string

TRUE if device has read checking enable

REC

string

TRUE if device is record oriented

RECSIZ

integer

Blocked record size

RND

string

TRUE if device allows random access

ROOTDEVNAM

string

Device name of root volume in volume s

RTM

string

TRUE if device is real-time

SDI

string

TRUE if device is single directory structu

SECTORS

integer

Number of sectors per track

SERIALNUM

integer

Volume serial number

SHR

string

TRUE if device is shareable

SPL

string

TRUE if device is spooled

SPLDEVNAM

string

Spooled device name

SQD

string

TRUE if device is sequential block orient

STS

integer

Status information

SWL

string

TRUE if device is software write locked

TRACKS

integer

Number of tracks per cylinder

TRANSCNT

integer

Volume transaction count

TRM

string

TRUE if device is a terminal

TT_ALTYPEAHD

string

TRUE if terminal has an alternate type a
buffer

TT—ANSICRT

string

TRUE if terminal is an ANSI CRT termin

TT_APP_KEYPAD

string

TRUE if terminal keypad is in applicatio
mode

TT_AUT OB AUD

string

TRUE if terminal has automatic baud ra
detection

TT_AVO

string

TRUE if terminal has a VT100-family dis

TT—BLOCK

string

TRUE if the terminal has block mode ca

string

TRUE if terminal uses mailbox broadcas
messages

TT_BRDCSTMBX

Item

Data Type

Information Returned

TT—CRFILL

string

TRUE if terminal requires fill after RET

TT_DECCRT

string

TRUE if terminal is a DIGITAL CRT terminal

TT_DIALUP

string

TRUE if terminal is connected to dialup

TT_DISCONNECT

string

TRUE if terminal can be disconnected

TT_DMA

string

TRUE if the terminal has DMA mode

TT—DRCS

string

TRUE if terminal supports loadable character
font

TT—EDIT

string

TRUE if terminal edit characteristic is set

TT—EDITING

string

TRUE if terminal advanced editing is enabled

TT—EIGHTBIT

string

TRUE if terminal uses 8-bit ASCII character set

TT-ESCAPE

string

TRUE if terminal generates escape sequences

TT—FALLBACK

string

TRUE if terminal uses multinational fallback
option

TT_HALFDUP

string

TRUE if terminal is in half-duplex mode

TT—HANGUP

string

TRUE if terminal has hangup characteristic set

TT_HOSTSYNC

string

TRUE if terminal has host/terminal
communication

TT_INSERT

string

TRUE if insert-mode is the default line-editing
mode for terminal

TT_LFFILL

string

TRUE if terminal requires fill after LF

TT_LOCALECHO

string

TRUE if terminal has local echo characteristic
set

TT_LOWER

string

TRUE if terminal has lowercase characters set

TT—MBXDSABL

string

TRUE if mailboxes associated with the terminal
will receive unsolicited input notification or
input notification

TT_MECHFORM

string

TRUE if terminal has mechanical form feed

TT_MECHTAB

string

TRUE if terminal has mechanical tabs and is
capable of tab expansion

TT—MODEM

string

TRUE if terminal is connected to a modem

TT—MODHANGUP

string

TRUE if terminal has modify hang-up
characteristic set

TT_NOBRDCST

string

TRUE if terminal will receive broadcast
messages

TT_NOECHO

string

TRUE if terminal does not echo input characters

TT_NOTYPEAHD

string

TRUE if data must be solicited by a read
operation

Item

Data Type

Information Returned

TT—OPER

string

TRUE if terminal is an operator terminal

TT_PASTHRU

string

TRUE if terminal has passall with flow co

TT—PRINTER

string

TRUE if terminal has available printerport

TT__READSYNC

string

TRUE if terminal has read synchronization

TT_REGIS

string

TRUE if terminal has REGIS graphics

TT_SCOPE

string

TRUE if terminal has a video screen displ

TT—SECURE

string

TRUE if terminal can recognize the secur
server

TT_SETSPEED

string

TRUE if you can set the speed on the term
line

TT_SIXEL

string

TRUE if the sixel is supported

TT_SYSPWD

string

TRUE if the system password is enabled
particular terminal

TT_TTSYNC

string

TRUE if terminal/host synchronization ex

TT_WRAP

string

TRUE if a new line is inserted when the
moves beyond the right margin

UNIT

integer

Unit number

VOLCOUNT

integer

Volumes in volume set

VOLNAM

string

Volume name

VOLNUMBER

integer

Current volume in volume set

VOLSETMEM

string

TRUE if disk is in a volume set

VPROT

string

Volume protection mask

WCK

integer

TRUE if write checking is enabled

The following example returns the error count for DUAO.
$ ERR = FSGETDVI ("DUAO","ERRCNT")
$ SHOW SYMBOL ERR
ERR = 0
Hex = 00000000 Octal = 000000

Returns a specified item of information about a specified process.
ARGUMENTS
process-id
A character string containing a process identification number (leading zeros can
be omitted). A null string ("") or a numeric zero identifies the current process.
item
A character string containing one of the following (do not abbreviate):
Item

Data

Information Returned

ACCOUNT

string

Account name string (8 characters filled with trailing blanks)

APTCNT

integer

Active page table count

ASTACT

integer

Access modes with active ASTs

ASTCNT

integer

Remaining AST quota

ASTEN

integer

Access modes with ASTs enabled

ASTLM

integer

AST limit quota

AUTHPR

integer

Maximum priority that a process without the ALTPRI
privilege can achieve

AUTHPRIV

string

Privileges that a process can enable

BIOCNT

integer

Remaining buffered I/O quota

BIOLM

integer

Buffered I/O limit quota

BUFIO

integer

Count of process-buffered I/O operations

BYTCNT

integer

Remaining buffered I/O byte-count quota

BYTLM

integer

Buffered I/O byte-count limit quota

CLINAME

string

Current command language interpreter; always returns "DCL

CPULIM

integer

Limit on process CPU time

CPUTIM

integer

CPU time used in hundredths of a second

CURPRIV

string

Current process privileges

DFPFC

integer

Default page fault cluster size

DFWSCNT

integer

Default working set size

DIOCNT

integer

Remaining direct I/O quota

DIOLM

integer

Direct I/O limit quota

DIRIO

integer

Count of direct I/O operations for the process

EFCS

integer

Local event flags 0 through 31

EFCU

integer

Local event flags 32 through 63

Item

Data

Information Returned

EFWM

integer

Event flag wait mask

ENQCNT

integer

Lock request quota remaining

ENQLM

integer

Lock request quota limit

EXCVEC

integer

Address of a list of exception vectors

FILCNT

integer

Remaining open file quota

FILLM

integer

Open file quota

FINALEXC

integer

Address of a list of final exception vectors

FREPOVA

integer

First free page at end of program region

FREP1VA

integer

First free page at end of control region

FREPTECNT

integer

Number of pages available for virtual memory expans

GPGCNT

integer

Global page count in working set GRP

IMAGECOUNT

integer

Number of images that have been run down for the p

IMAGNAME

string

File name of the current image

IMAGPRIV

string

Privileges with which the current image was installed

JOBPRCCNT

integer

Number of subprocesses owned by the process

LOGINTIM

string

Process creation time

MASTER—PID

string

Returns the process identification of the process at the
the current job's process tree.

MEM

integer

Member number of UIC

MODE

string

Process mode (BATCH, INTERACTIVE, NETWORK, o
OTHER)

MSGMASK

integer

Default message mask

OWNER

string

Process identification of process owner

PAGEFLTS

integer

Count of page faults

PAGFILCNT

integer

Remaining paging file quota

PAGFILLOC

integer

Location of the paging file

PGFLQUOTA

integer

Paging file quota (maximum virtual page count)

PHDFLAGS

integer

Flags word

PID

string

Process identification

PPGCNT

integer

Process page count

PRCCNT

integer

Count of subprocesses

PRCLM

integer

Subprocess quota

PRCNAM

string

Process name

PRIB

integer

Process's base priority

PROCPRIV

integer

Process's default privileges

Item

Data

Information Returned

SITESPEC

integer

Per-process site-specific longword

STATE

string

Process state

STS

integer

Process status flags

SWPFILLOC

integer

Location of the swap file

TERMINAL

string

TMBU

integer

Termination mailbox unit number

TQCNT

integer

Remaining timer queue entry quota

TQLM

integer

Timer queue entry quota

UIC

string

Process's UIC

USERNAME

string

User name string

VIRTPEAK

integer

Peak virtual address size

VOLUMES

integer

Count of currently mounted volumes

WSAUTH

integer

Maximum authorized working set size

WSAUTHEXT

integer

Maximum authorized working set extent

WSEXTENT

integer

Current working set extent

WSPEAK

integer

Working set peak

WSQUOTA

integer

Working set size quota

WSSIZE

integer

Process's current working set size

The following example returns the user name for process 003B0018.
$ NAME = F$GETJPI ("3B0018","USERNAME")
$ SHOW SYMBOL NAME
NAME = "USER
"

F$GETSYI (item,[node])
Returns a specified item of information about the system.
ARGUMENTS

item
A character string containing one of the following (do not abbreviate):
Item

Information Returned and Data Type

ARCHFLAG

Architecture flags (string)

BOOTTIME

Time the system was booted (string)

CHARACTEREMULATED

TRUE if the character string instructions are emulated on
CPU (string)

CLUSTER-MEMBER

TRUE if the node is a member of a cluster; CLUSTER—ME
always returns FALSE on a Micro VMS system (string)

CPU

Processor type: 7 for a Micro VAX I (integer)

DECIMALEMULATED

TRUE if the decimal string instructions are emulated on
CPU (string)

D_FLOAT_
EMULATED

TRUE if the D_floating instructions are emulated on the
(string)

F_FLOAT_
EMULATED

TRUE if the F_floating instructions are emulated on the C
(string)

G-FLOATEMULATED

TRUE if the G—floating instructions are emulated on the
(string)

PAGEFILE-FREE

Returns the number of free pages in the currently install
paging files (integer)

PAGEFILE-PAGE

Returns the number of pages in the currently installed pa
files (integer)

SID

System identification (integer)

SWAPFILE-FREE

Returns the number of free pages in the currently install
swapping files (integer)

SWAPFILE-PAGE

Returns the number of pages in the currently installed sw
files (integer)

VERSION

Version of VMS in use (string)

The following example returns the system identification.
$ SID = F$GETSYI ("SID")
$ SHOW SYMBOL SID
SID = 117441280

Hex = 070003000

Octal = 0700001400

F$IDENTIFIER (identifier,translation)

Converts an alphanumeric UIC to its numeric equivalent, or a numeric UIC to
alphanumeric equivalent. (Alphanumeric UICs are optionally equated to nume
UICs in the rights database.)
ARGUMENTS

identifier
A character string containing an identifier.

lex-22

Lexical Functions
F$IDENTIFIER

translation
If identifier is alphanumeric, specify translation as a character string containing
NAME—TO—NUMBER. If identifier is numeric, specify translation as a character
string containing NUMBER_TO_NAME.
The following example translates the alphanumeric identifier JONES to its numeric
equivalent.
$ NAME = F$IDENTIFIER(MJONES",nNAME_TO_NUMBERM)
$ SHOW SYMBOL NAME
Name = 589926 Hex = 00090066 Octal = 00002200146

F$INTEGER (string)
Converts the specified string to a number. The character string must be null (zero) or
a valid decimal specification (no hexadecimal or octal specifications) of a positive or
negative integer. If the character string does not contain a numeric character string,
it is converted to either a 1 (if the first character is Y,y,T, or t) or a 0.
ARGUMENTS

string
A character string or integer.
The following example (which would appear in a command procedure) reads a
character string from the terminal and converts it to a number.
$ INQUIRE D0G_C0UNT "Number of dogs"
$ D0G.C0UNT = F$INTEGER (D0G.C0UNT)

F$LENGTH (string)
Returns the length of the specified character string.
ARGUMENTS

string
A character string whose length is being determined.
The following example indicates that the character string equated to REPORT_l is 56
characters in length.
$ LINE.LENGTH = F$LENGTH (REPORT.l)
$ SHOW SYMBOL LINE_LENGTH
LINE.LENGTH = 56 Hex = 00000038 Octal = 000070

Lexical Functions

lex-23

F$LOCATE

F$LOCATE (substring,string)
Locates a specified portion of a character string and returns as a number the offset of
the first character. The first character in a string is always offset position 0 from the
beginning of the string. If the substring is not present, the offset of the last character
in the character string plus one is returned.
ARGUMENTS

substring
The character string in string that you want to locate.

string
A character string to be edited by F$LOCATE.
The following example returns the position of the substring DOGS.
$ SHOW SYMBOL LINE_1
LINE_1 = "Number of dogs:"
$ DOGS = F$L0CATE ("dogs",LINE.l)
$ SHOW SYMBOL DOGS
DOGS = 10 Hex = 0000000A Octal = 12

F$MESSAGE (message-code)
Returns as a character string the facility, severity, identification and text associated
with the specified message code.
ARGUMENTS

message-code
An integer for which you are requesting error message text. The message code
must be specified as a number (decimal, hexadecimal, or octal).
The following example returns the success message.
$ MESS = F$MESSAGE (1)
$ SHOW SYMBOL MESS
MESS = "#/oSYSTEM-S-NORMAL, normal successful completion"

lex-24

Lexical Functions
F$MODE

F$MODE ()
Returns the character string INTERACTIVE if you issue the command from the
terminal, the character string BATCH if you issue the command from a batch job,
and the character string NETWORK if you issue the command from a network job.
In the following example, you issue the command from the terminal.
$ MODE = F$MODE ()
$ SHOW SYMBOL MODE
MODE = "INTERACTIVE"

F$PARSE (file-spec,[def-spec1],[def-spec2],[field,...],[type])
Returns either the full file specification for the specified file or one of the following
fields: NODE, DEVICE, DIRECTORY, NAME, TYPE, VERSION. The device name
in the resulting file specification must be a valid device. The directory must be a
valid directory on that device. An error in the resulting file specification returns
a null string (unless the SYNTAX —ONLY type is specified or a specific field is
requested). Logical names and device names must terminate with a colon. If you
omit arguments, commas to the left of the last specified argument must be included
as place holders.
ARGUMENTS

file-spec
A character string containing a file specification. If file-spec is not a full file
specification, defaults are taken from (1) your current default directory if defspecl is not specified; (2) def-specl and then your current default directory if
file-spec and def-specl are specified; (3) def-specl, then def-spec2, and then your
current default directory if both def-specl and def-spec2 are specified. The file
name, file type, and version number are null if not specified in either file-spec or
def-specl. Wildcards can be used.

def-specl
A character string which is substituted in the output string if a particular field in

file-spec is missing.

def-spec2
A character string which is substituted in the output string if a particular field in

file-spec and def-spec2 is missing.

field
A character string containing one of the following fields (do not abbreviate field
names): NODE, DEVICE, DIRECTORY, NAME, TYPE, VERSION.

Lexical Functions

lex-25

F$PARSE

type
The type of parsing to be done. Valid types are:
SYNTAX—ONLY

Does not check for the existence of the directory or device

NO—CONCEAL

Ignores the "conceal" attribute in the translation of a logical name as
part of the file specification

The following example returns the directory name for the file 1983.DAT in your
default directory.
$ D = FSPARSE ("1983.DAT",,,"DIRECTORY")
$ SHOW SYMBOL D
D = "[ACCOUNTS]"
The next example returns the full file specification.
$ D = F$PARSE ("1983.DAT")
$ SHOW SYMBOL D
D = "DUA1:[ACCOUNTS]1983.DAT;"
The next example uses DOG subdirectory as a default directory.
$ D = FSPARSE ("1983.DAT","DUA1: [LICENSES.DOG]")
$ SHOW SYMBOL D
D = "DUA1:[LICENSES.DOG]1983.DAT;")
The device name in the resulting file specification must be a valid device. The
directory name must be a valid directory on that device. An error in the resulting file
specification returns a null string.

F$PID (context-symbol)
Returns a process identification (PID) number, and updates the context symbol to
identify the current position in the system's process list. If context-symbol is equated
to zero or a null string
returns as a character string the process identification
number of the first process on the system. If context-symbol was used in a previous
F$PID function and has not been redefined, F$PID returns the process identification
number of the next process on the system. A null string is returned after the last
process on the system has been examined. If your system has individual accounts,
you may not have access to all processes on the system.
ARGUMENTS

context—symbol
A symbol that DCL uses to store a pointer into the system's list of processes.
The first time you use F$PID, use a symbol that is undefined or equated to the
null string ("").

lex-26

Lexical Functions
F$PID

The following command procedure returns the process identification number of each
process on the system.
$
$
$
$
$
$
$
$

! SYSPID.COM
!
NEXT = 0
START:
PID = F$PID (NEXT)
IF PID .EQS. "" THEN EXIT
SHOW SYMBOL PID
GOTO START

F$PRIVILEGE (priv-list)
Returns a string containing TRUE or FALSE, depending on whether all of the
privileges are set as specified. You can specify either the positive or negative version
of a privilege.
ARGUMENTS

priv-list
A character string identifying a privilege or a list of privileges separated by
commas.
The following example finds that the current process does not have one SYSPRV,
does not have WORLD, or does not have either. To determine which privileges are
not set, you would have to check each individually.
$ PRIVS = F$PRIVILEGE ("SYSPRV,WORLD")
$ SHOW SYMBOL PRIVS
PRIVS = "FALSE"

F$PROCESS ()
Returns as a character string the name of the current process, as demonstrated in the
following example.
$ PROC = FSPROCESS ()
$ SHOW SYMBOL PROC
PROC = "USER"

Lexical Functions

lex-27

F$SEARCH

F$SEARCH (file-spec,[stream-id])
Returns the full file specification of file-spec. If device or directory are omitted, the
current defaults are used. If version is omitted, the latest version number is used. If
file-spec contains wildcards, each time F$SEARCH is called, the next file specification
that agrees with file-spec is returned. A null string is returned after the last file
specification that agrees with file-spec.
ARGUMENTS

file-spec
The file name and type of the file specification to be searched for; wildcards are
permitted.

stream-id
A positive integer used to maintain separate search contexts.
The following command procedure returns the latest versions of all the type EXE files
in the SYS$SYSTEM directory.
$

! SEARCH.COM

$ !
$
$
$
$
$

START:
FILE = F$SEARCH C'SYS$SYSTEM:*.EXE")
IF FILE .EQS. "" THEN EXIT
SHOW SYMBOL FILE
GOTO START

The following command procedure returns all COM and DAT files.
$
$
$
$
$
$
$
$

! C0M_DAT.C0M
!
! find first COM and DOC files
COM = FSSEARCH ("*.COM;*",1)
DOC = FSSEARCH ("*.D0C;*",2)
START:
! set DONE to true
DONE = 1

$
$
$
$
$
$
$

! search for COM file
IF (COM .EQS. "") THEN GOTO END_C0M
SHOW SYM COM
COM = FSSEARCH ("*.COM;*",1)
DONE = 2
! DONE is false
END_C0M:

LEX-28

Lexical Functions
F$SEARCH

$
$
$
$
$
$
$
$
$
$

! search for DOC file
IF (DOC . EQS. "") THEN GOTO END.DOC
SHOW SYM DOC
DOC = F$SEARCH ("*.DOC;*",2)
DONE = 2
! DONE is false
END.DOC:
! if no DOC or COM files, DONE is still true
IF DONE THEN EXIT
GOTO START

F$SETPRV (priv-list)
If the process has the proper authorization, F$SETPRV enables or disables the
specified privileges. In addition, F$SETPRV returns a string containing the state of
the specified privileges before F$SETPRV was executed.
ARGUMENTS

priv-list
A character string defining a privilege or list of privileges separated by commas.
You can specify either the positive or negative version of a privilege.
The following example sets SYSPRV and WORLD. The current process had SYSPRV;
WORLD was set by F$SETPRV.
$ PRIV = FSSETPRV ("WORLD.SYSPRV")
$ SHOW SYMBOL PRIV
PRIV = "NOWORLD.SYSPRV"
$ TEST = F$PRIVILEGE ("WORLD.SYSPRV")
TEST = "TRUE"

F$STRING (expression)
Returns the string that is equivalent to the specified expression.
ARGUMENTS

expression
An integer or string expression. When converting an integer to a string,
F$STRING uses decimal notation, omitting leading zeros. If the integer is
negative, a minus sign precedes the number.

Lexical Functions

LEX-29

F$STRING

In the following example, F$STRING evaluates the integer expression and converts it
to a character string.
$
$
$
$

D0G_1 = 12
D0G_2 = 13
T0TAL_D0GS = FSSTRING (D0G_1 + D0G_2)
SHOW SYMBOL TOTAL.DOGS
TOTAL.DOGS = "25"

F$TIME ()
Returns as a character string the current date and time in absolute time format, as
demonstrated in the following example.
$ TIME = F$TIME ()
$ SHOW SYMBOL TIME
TIME = "21-0CT-1983 12:45:22"

F$TRNLNM (name,[table],[index],[mode],[case],[item])
Finds a logical name and returns the translation or the requested attributes. If the
logical name does not exist, F$TRNLNM returns a null string. (Section 2.3 discusses
logical names.) If you omit arguments, commas to the left of the last specified
argument must be included as place holders.
ARGUMENTS

name
A character string containing the logical name.

table
A character string containing a logical name whose equivalence names are the
logical name tables to be searched (the search order is determined when the
logical name is defined). The table argument defaults to LNM$DEFAULT_
SEARCH whose equivalence names are process, job, group, and system logical
name tables, in that order.

index
The number of the equivalence name to return if the logical name has more than
one translation; defaults to 0.

mode
A character string containing one of the following access modes (do not
abbreviate): USER (default), SUPERVISOR, EXECUTIVE, or KERNEL.

A character string containing one of the following (do not abbreviate):
CASE—BLIND (F$TRNLNM searches for a logical name match without taking
into account character casing; default) or CASE-SENSITIVE (F$TRNLNM
searches for an exact logical name match).

item
A character string containing one of the following (do not abbreviate):
Item

Data Type

Information Returned

ACCESS¬
MODE

string

Access mode associated with the logical name

CONCEALED

integer

TRUE if the logical name is concealed

CONFINE

string

TRUE if the logical name is confined

LENGTH

integer

Length of the equivalence name

MAX-INDEX

integer

Number of logical name translations

NO-ALIAS

string

TRUE if the logical name must be unique within its
access mode and outer access modes

TABLE

string

TRUE if the logical name is the name of a logical
name table

TABLE-NAME

string

Name of the table containing the logical name

TERMINAL

string

TRUE if the logical name cannot be translated
iteratively

VALUE

string

Default. Equivalence name

In the following example, the logical name GROUP—NAMES is confined (it is not
copied to subprocesses).
$ CONFINE = FSTRNLNM ("GROUP JtfAMES",,,,,"CONFINE")
$ SHOW SYMBOL CONFINE
CONFINE = "TRUE"

F$TYPE (symbol)
Returns the data type of the symbol. If symbol forms a valid integer, F$TYPE returns
INTEGER. If symbol is a character string whose characters do not form a valid integer,
F$TYPE returns STRING. If symbol is undefined, F$TYPE returns a null string.

Lexical Functions

lex-31

F$TYPE

ARGUMENTS

symbol
A character string or integer which references the name of the symbol to be
edited.
The following example returns the data type INTEGER.
$ NUM = "673"
$ TYPE = F$TYPE (NUM)
$ SHOW SYMBOL TYPE
TYPE = "INTEGER"

F$USER ()
Returns as a character string the current UIC, as demonstrated in the following
example.
$ UIC = F$USER ()
$ SHOW SYMBOL UIC
UIC = "[DEVELOPMENT.OSGOOD]"

F$VERIFY ([procedure][,image])
Returns a value indicating whether the procedure verification setting is on or off.
If called with the first argument, turns procedure and image verification on if the
argument is 1 and off if the argument is 0. If called with both arguments, turns
procedure verification on or off depending on the value of the first argument and
turns image verification on or off depending on the value of the second argument.
If you specify only the second argument, you must include the comma as a place
holder.
ARGUMENTS

procedure
An integer with a value of 1 to turn procedure verification on or a value of 0 to
turn procedure verification off.

image
An integer with a value of 1 to turn procedure verification on or a value of 0 to
turn procedure verification off.

lex-32

Lexical Functions
F$VERIFY

The following command procedure saves the user's setting of procedure and image
verification at the beginning of the procedure and then restores those settings at the
end of the procedure.
$
$
$
$

! PROCEDURE.COM
!
SAVE_PR0C_VER = F$ENVIR0NMENT ("VERIFY_PR0CEDURE")
SAVE_IMAGE_VER = F$ENVIR0NMENT ("VERIFY_IMAGE")
! commands

$ GARBAGE = F$VERIFY (SAVE_PR0C_VER, SAVE_IMAGE_VER)

Appendix MAIL
MAIL
The DCL command MAIL sends a specified file to a specified user or users. Typing
the MAIL command without a file specification and user name invokes the interactive
Mail Utility.

MAIL.1

DCL Command

Use the DCL command MAIL with parameters and the optional /SELF and
/SUBJECT qualifiers to send a file to other users without invoking the interactive
Mail Utility. Use the DCL command MAIL without parameters and with the optional
/EDIT qualifier to invoke the interactive Mail Utility.

MAIL [file-spec] [username,...]
When the optional parameters are specified, MAIL sends a file to the specified users.
When the optional parameters are not specified, MAIL invokes the interactive Mail
Utility.
PARAMETERS

file-spec
Specification of the file to be sent. No wildcard characters are allowed. The file
type defaults to TXT.

username
Name of the user or distribution list to receive the mail message. If you include
a distribution list, precede the name of the list with an at sign (@), and enclose
both the at sign and the name in quotation marks.

MAIL-2

MAIL
MAIL

QUALIFIERS

/EDIT[=(keyword,...)]
/NOEDIT
Invokes EDT for the Mail Utility commands FORWARD, REPLY, or SEND used
during the current interactive session. If you do not specify a keyword, the
default is MAIL/EDIT=(SEND,REPLY). Possible keywords are:
FORWARD

Invokes EDT to edit the last message read before sending it to
the specified users.

REPLY[=EXTRACT]

Invokes EDT to edit your response to the last message read.
Specify the keyword EXTRACT to edit the message to which
you are replying.

SEND

Invokes EDT to edit the message you are sending.

/SELF
/NOSELF
Sends you a copy of the file you are sending. When you send a message from
the DCL command level (instead of from within the Mail Utility), /SELF or
/NOSELF overrides any setting you have established with the SET COPY_SELF
command.

/SUBJECT=“text”
Specifies the subject of the mail. Enclose text in quotation marks if the subject
consists of more than one word.
EXAMPLES
$ MAIL/SUBJECT="PROJECT DAWN" DAWN.DAT BRUTUS::0SG00DE, PORTIA::RIPLEY
Sends the file DAWN.DAT to user Osgoode on node BRUTUS and to user Ripley on
node PORTIA. The subject of the message is PROJECT DAWN.
$ MAIL DAWN.DAT BRUTUS::OSGOODE,"OALLBUD"
Sends the file DAWN.DAT to user Osgoode on node BRUTUS and to everyone on
the distribution list ALLBUD.DIS.
$ MAIL/NOSELF MYFILE.DAT CHARLES
Sends the file MYFILE.DAT to user CHARLES without sending a copy back to you.
$ MAIL
Invokes the MAIL Utility.

MAIL

MAIL-3

Interactive Mail Utility

MAIL.2 Interactive Mail Utility
The Mail Utility allows you to send, receive, and manipulate messages either by
typing MAIL commands or by entering them on the default MAIL keypad.

MAIL.2.1 MAIL Commands
Type MAIL commands in response to the MAIL prompt.

ANSWER [file-spec]
Sends a response to the message you have just read. If you include a file
specification, the specified file is sent as your answer; otherwise, you will be
prompted for the text of your message. (ANSWER is interchangeable with REPLY.)
PARAMETERS

file-spec
The specification of the file to be sent as a reply.
QUALIFIERS

/EDIT
/NOEDIT (default)
Invokes the editor to create or edit the message you are sending. The EXIT
command completes the ANSWER operation; the QUIT command cancels the
ANSWER operation. The /NOEDIT qualifier overrides the ANSWER/EDIT
default established with the DCL command MAIL/EDIT.

/EXTRACT
Enables you to use the editor to edit the message to which you are replying
rather than starting a new message.

/LAST
Inserts the message most recently sent as text for the reply. The /LAST qualifier
cannot be used with any of the other qualifiers for the ANSWER command or
with a file specification.

/SELF
/NOSELF (default)
Determines whether or not MAIL sends you a copy of your response. The
default is /NOSELF, unless you have used the SET COPY_SELF command to
specify that copies be sent to you automatically.

MAIL-4

MAIL
ATTACH

ATTACH process name
Transfers control of your terminal from your current process (which then hibernates)
to the specified process. (Note that you always SPAWN to a new process and
ATTACH to a process that already exists.)
PARAMETERS

process-name
The name of the process or subprocess to which the connection is to be made.
QUALIFIERS

/PARENT
Indicates that you want to attach to the parent process of your current process.
You cannot specify the process-name parameter with the /PARENT qualifier.
EXAMPLE
$ SPAWN MAIL
#/*DCL-S-SPAWNED, process 0SG00DE_1 spawned
#/,DCL-S-ATTACHED, terminal now attached to process 0SG00DE_1
MAIL> DIRECTORY MAIL

MAIL> ATTACH OSGOODE
#/,DCL-S-RETURNED, control returned to process OSGOODE

ICTRL/Yl

$ ATTACH OSGOODE.1
Enters the DCL command SPAWN to create a subprocess (OSGOODE _1),
which invokes MAIL and uses the ATTACH command to move between MAIL
(OSGOODE_1) and the DCL command level (OSGOODE). The ATTACH command
allows you to transfer control between processes.

BACK
Displays the previous message if the last command issued was READ. When the last
command issued was the DIRECTORY command, the BACK command displays the
previous screen of the directory display.

MAIL

MAIL-5

BACK

QUALIFIERS

/EDIT
Invokes the editor. You can use the editor to peruse the previous message
(enter the QUIT command when finished) or you can edit the previous message
and save the new version in a sequential file (when finished, enter the EXIT
command and supply a file name).

COMPRESS [file-spec]
Makes an ISAM mail file smaller. When you compress a file, the following four steps
occur:
1.

A temporary file named MAIL_nnnn_COMPRESS.TMP is created (nnnn is a
unique four-digit number).

The contents of the file to be compressed are copied to the temporary file and
compressed.

The original (uncompressed) file is renamed with a file type of OLD.

The newly compressed file is renamed from MAIL_nnnn_COMPRESS.TMP to
its original name.

PARAMETERS

file-spec
The name of the mail file to be compressed. If the name of a file is not specified,
MAIL will compress the mail file that is currently open. If there is no open mail
file, MAIL will compress the default mail file, MAIL.MAI.
QUALIFIERS

/OUTPUT=output-file-spec
Specifies the name of the compressed file.
EXAMPLE
MAIL> COMPRESS SOCIAL.MAI
°/0MA IL - S - CREATED, WORKDISK: [OSGOODE] MAIL_08C8_C0MPRESS. TMP; 1 created
#/,MAIL-S-COPIEDt WORKDISK: [OSGOODE]SOCIAL.MAI; 1 copied to
WORKDISK:[OSGOODE]
MAIL_08C8_C0MPRESS.TMP;1 (2 records)
#/oMAIL-S-RENAMED, WORKDISK: [OSGOODE] SOCIAL. MAI; 1 renamed to
WORKDISK:[OSGOODE]
SOCIAL.OLD;2
#/oMAIL-S-RENAMED, WORKDISK: [OSGOODE] MAIL_08C8_C0MPRESS . TMP; 1 renamed to
WORKDISK:[OSGOODE]SOCIAL.MAI;1
Compresses the contents of a file named SOCIAL.MAI.

MAIL-6

MAIL
COPY

COPY foldername [filename]
Copies a message to another folder without deleting it from the current folder. If the
specified folder does not exist, it is created. (Enter CTRL/C to cancel the operation
without exiting from MAIL.)
PARAMETERS

foldername
The name of the folder to which the message is to be copied. If the specified
folder does not exist (and you have not entered the qualifier /NOCONFIRM) you
are asked whether you want to create it. A folder name can be 1 to 39 characters
in length. Valid characters for folder names are A through Z, a through z, $,
and 0 through 9.

filename
The name of the mail file to which the message is copied. The default is the
current mail file. If the specified mail file does not exist, it is created.
QUALIFIERS

/ALL
Copies all the currently selected messages to another folder. (See the SELECT
command for more information on selecting messages.)

/CONFIRM (default)
/NOCONFIRM
Determines whether or not you will be queried about creating a new folder.
EXAMPLE
MAIL> 2

MAIL> COPY
.Folder:
MEMOS
.File:
I return 1
Folder MEMOS does not exist.
Do you want to create it (Y/N, default is N)?

VoMAIL-1-NEWFOLDER, folder MEMOS created
Puts a copy of mail message #2 into the new folder MEMOS in the default mail file.

MAIL

MAIL-7

CURRENT

CURRENT
Displays the beginning of the message you are currently reading.
QUALIFIERS

/EDIT
Invokes the editor. You can invoke the editor to peruse the current message
(enter the QUIT command when finished) or you can edit the current message
and save the new version in a sequential file (enter the EXIT command and
supply a file name).

DEFINE/KEY key-name string
Defines a key to execute a MAIL command. Defining a key enables you to press that
key to enter a command instead of typing the command name. For information on
the MAIL keypad, see Section MAIL.3.
To increase the number of key definitions available on your terminal, you can use
the /SET_STATE qualifier. The same key can be assigned any number of definitions
as long as each definition is associated with a different key state. State names can be
any alphanumeric string (for example, GOLD, SWITCH, SNAG1, or SNAG2).
Any key definitions you define during a MAIL session will disappear when you EXIT
from the Mail Utility. To retain keypad key definitions from one MAIL session to
another, create a file in your top-level directory with a file type of INI containing
these definitions (for example, MAIL_KEYDEF.INI). Enter the following command
in your login command file (LOGIN.COM):

$ DEFINE MAIL$INIT SYS$LOGIN:MAII—KEYDEF.INI
The file you create (MAIL_KEYDEF.INI) containing your key definitions will act as a
login command file for MAIL.
PARAMETERS

key-name
The name of the key you are defining.
The following table lists the key names to use when you define keys:
VT100 Key

VT200 Key

PF1

PF2

PF3

Keyname

VT100 Key

VT200 Key

PF4

KPO, KP1- KP9

Keypad 0- 9

PERIOD

Period key

COMMA

Comma key

MINUS

Minus key

ENTER

Enter key

FIND, INSERT HERE

—

Find, Insert Here

REMOVE, SELECT

—

Remove, Select

PREV_SCREEN

—

Prev Screen

NEXT-SCREEN

—

Next Screen

HELP, DO

—

Help(F15), Do(F16)

FI 7- F20

—

Function Keys FI 7- F20

(Note that you cannot define the arrow keys or function keys FI through FI4.) The keys
PF1- PF4, KPO- KP9, PERIOD, COMMA, MINUS, and ENTER all have default definitions.
You may, however. override those definitions with your own key definitions.
PARAMETERS

string
The MAIL command string to be entered when the specified key is pressed.
QUALIFIERS

/ECHO (default)
/NOECHO
Specifies whether or not the command line is echoed after you press the defined
key. You cannot define a key specifying both /NOECHO and /NOTERMINATE.

/I F—STATE=state-list
/NOIF_STATE=state-list (default)
Specifies a list of one or more states, one of which must be set in order to enable
the specified key definition. If you omit or negate this qualifier, the default is the
current state.

/LOCK_STATE
/NOLOCK_STATE (default)
Retains the state specified by the /SET_STATE qualifier until you use the /SETSTATE qualifier again to change it.

MAIL

MAIL-9

DEFINE/KEY

/LOG (default)
/NOLOG
Specifies whether or not informational messages that signal successfully created
key definitions are displayed.

/SET_STATE=state-name
/NOSET—STATE=state-name (default)
Associates a state with the key you are defining. A state name can be any
alphanumeric string. If you omit or negate this qualifier, the current state
remains unchanged. You cannot define a key specifying both /SET_STATE and
/TERMINATE.

/TERMINATE
/NOTERMINATE (default)
Determines whether or not the specified command string executes when you
press the key. When you use /NOTERMINATE you must press RETURN to
execute the command string. You cannot define a key specifying both
/SET_STATE and /TERMINATE.
EXAMPLE
MAIL> DEFINE/KEY PF4 "SET " /SET_STATE=SUB2
MAIL> DEFINE/KEY KP3 "FOLDER" /ECHO/TERMINATE/IF_STATE=SUB2
The first command defines the PF4 keypad key as the SET command and associates
this key with the state named SUB2. The second command defines keypad key 3 to
be "FOLDER" and makes it dependent on a state named SUB2. When you press the
PF4 key followed by keypad key 3, MAIL executes the SET FOLDER command.

DELETE [message-number]
Moves the specified message to the WASTEBASKET folder. The message is not
actually deleted until you exit from MAIL or read another message file. If you enter
QUIT or CTRL/Y before exiting from MAIL or before reading another message, the
delete operation is canceled. To recover a message from the WASTEBASKET folder,
SELECT the WASTEBASKET folder, READ the desired message, and MOVE it to
another folder.
PARAMETERS

message-number
The number of the message that is to be deleted from the current folder. Defaults
to the most recently read mail message.

MAIL-10

MAIL
DELETE

QUALIFIERS

/ALL
Deletes all the messages in the currently selected folder (see the SELECT
command for more information).
EXAMPLE
MAIL> DELETE 2
Deletes message number 2 from the current folder.

DIRECTORY [foldername]
Displays a list of the currently selected messages in the specified folder, listing
message number, sender's name and node, date, and subject. If there are no
currently selected messages, MAIL displays a directory of the messages in the
NEWMAIL folder (if any unread messages exist) or the MAIL folder. (See the
SELECT command for more information about selecting messages.)
PARAMETERS

foldername
The name of the folder containing the messages you want to display. If the
folder name is omitted, MAIL displays a directory of the current folder.
QUALIFIERS

/BEFORE=date
Lists all the mail messages received before the specified date. Specify the
date as DD-MMM-YYYY or specify one of the following keywords: TODAY,
TOMORROW, or YESTERDAY. The default is the current date ("today").

/FOLDER
Lists all the folders contained in the current mail file.

/FULL
Displays the number of records in the message and indicates whether or not you
have replied to the message.

/NEW
Lists any new (unread) mail messages. When there are no unread messages,
MAIL displays the message "No new messages".

/SINCE=date
Lists all the mail messages received on or after the specified date. Specify the
date as DD-MMM-YYYY or specify one of the following keywords: TODAY,
TOMORROW, or YESTERDAY. The default is the current date ("today").

MAIL

MAIL-11