Digital PDFs

AA-L672B-TC

April 1983

514 pages

Original

24MB

Document:	RSX-11M/M-PLUS Command Language Manual
Order Number:	AA-L672B-TC
Revision:	0
Pages:	514
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/2_Operation/AA-L672B-TC_dcl_198304.pdf

OCR Text

RSX-11 M/M-PLUS
Command Language Manual
Order No. AA-L672B-TC

RSX-11 M Version 4.1
RSX-11 M-PLUS Version 2.1

digital equipment corporation · maynard, massachusetts

First Printing, October 1979
Revised, November 1981
Revised, April 1983
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

1979, 1981, 1983 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:
DIBOL
EduSystem
IAS

DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DEC US
DECwriter

lul~ ~rtn;;~

l'lM...::>..::>OU..::>

PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS

~o~oomn
ZK2248

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call

800-258-1710

In New Hampshire, Alaska, and Hawaii call
In Canada call

603-884-6660

613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corporation
P.O. Box CS2008
Nashua. New Hampshire 03061

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa. Ontario K1G 4C2
Attn: A&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
c!o Digital's local subsidiary or
approved distributor

·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 ISDC\. Digital Equipment
Corporation. Northboro. Massachusetts 01532

CONTENTS

Page

PREFACE
INTRODUCTION

CHAPTER l
1.1
1.2
l . 2 .1
l. 2. 2
L2:3
l. 2. 4
l . 2. 5
l . 2 .6
l . 2. 7
l . 2 .8
l . 2. 9
1.2.10
1.2.11
1.2.12
1.2.13
1.2.14
1.2.15
1.2.16
1.3
l. 3 .1
l . 3. 2
l . 3 .3
l. 3 .4
l . 3. 5
1.3.6
l. 3. 7
1.4
1.5
1.6
1.6 .1
CHAPTER 2
"')
Lo •

RSX-llM/M-PLUS AND DCL: BASIC CONCEPTS
•
THE DCL COMMAND LINE • • • • • •
• •
Prompting
• • • • . . . • . •
Qualifiers • • • • • •
. . • • •
HELP •

•

1-1
1-2
1-3

1-3

•

MCR and DCL Commands •
1-7
Abbreviations
••••
• 1-7
1-8
Numbers and Dates
Multiple Parameters
• • • • • • • • • • • • • • 1-8
• 1-9
Underscore Character
• 1-9
Colon and Equal Sign
• 1-9
Quoting Strings
ANSI File Names
1-10
1-10
DECnet and DCL •
Command Line Continuation • • • •
1-11
1-11
Comments in Command Lines
• • • •
SET DEBUG
• • • • • • • • • • • • • • • • • • 1-12
Errors • • • • • • • • • • •
1-13
FUNCTIONAL GROUPING OF DCL COMMANDS
1-14
The SET and SHOW Commands
1-15
Terminal Operations
• • • • • • • •
1-15
Handling Files • • • • • • • •
1-15
Handling Devices and Volumes •
1-15
1-16
Program Development
• • • • •
Running Tasks
• • • •
1-16
System Control • • • • • • • • • • •
1-16
USING THE QUEUE MANAGER: PRINT AND BATCH JOBS
1-16
INDIRECT COMMAND FILES IN DCL
• • • • • • • • • 1-17
DCL AND RSX-llM/M-PLUS UTILITIES AND SYSTEM TASKS 1-17
RSX-llM/M-PLUS DCL and VAX/VMS DCL • • • • • • 1-19
THE SET AND SHOW COMMANDS

..L

2.2
2.3
2.4
2.5
2.5.l
2.6
2.7
2.8
2.9
2.10
2 .11
2.12

SET AND C"vnvn
SHOW MEMORY
SET AND SHOW TERMINAL
• • • • • • • • •
SHOW DEVICES
SHOW QUEUE •
SHOW PROCESSOR • •
SHOW ASSIGNMENTS • •
SET AND SHOW DEFAULTS
SHOW TASKS • • •
SHOW USERS • • • • • •
SET PROTECTION • • • • •
SET AND SHOW SYSTEM/DIRECTORY AND
LIBRARY/DIRECTORY
• • • • •
SET DEBUG
• • • • • • •
[_J l""\laJ

iii

•
•
• •
•
• •
• •
•
. •

2-i
2-2
2-2
2-3
2-3
2-4
2-4
2-4
2-5
2-5
2-6

• • • • 2-6
• • • 2-7

CONTENTS
Page
CHAPTER 3
3.1
3 .1.1
3 .1. 2
3 .1. 3
3 .1. 4
3.1.4.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.2.7
3.3
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.4.7
3.4.8
3.4.9
3.5
3.5.1
3.6
3.7
3.8
3.8.2
CHAPTER 4
4.1
4 .1.1
4 .1. 2
4 .1. 3
4 .1. 4
4 .1.5
4.2
4.2.1
4.2.2
4.2.3
4.2.3.1
4.2.3.2
4.2.3.3
4.3
4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6

TERMINAL OPERATIONS
LOGGING IN AND LOGGING OUT •
LOGIN
• • • •
LOGOUT •
• • • •
• • • • •
ACNT, the Account File Maintenance Program
Resource Accounting on RSX-llM-PLUS
• • •
SHOW ACCOUNTING/INFORMATION
THE KEYBOARD • • • • • • • • • •
RETURN and Command Line Length
Line Terminators • • • • •
• •
DELETE Versus BACK SPACE
CAPS LOCK and SHIFT
REPEAT • • • • • • • •
SCROLL and NO SCROLL • • • • • • • • • • •
Other Keys
• • • •
THE KEYPAD • • • • • • • •
THE CTRL KEY AND CONTROL CHARACTERS
CTRL/C
• • • • • • • • •
CTRL/S and CTRL/Q
• • • •
CTRL/O • • • • • • • • •
CTRL/Z •
• •
CTRL/U • •
• • • •
• • • •
CTRL/R •
• • • • •
CTRL/X • •
• • • •
• • • •
CTRL/L
• • • • • • • • • • • • •
Other Control Characters
• • • • •
HELP •

•

•
• •
•

• •
• •

•
•
•
•
•

•

Help File Format: Writing a Help File •
BROADCAST • • • • • • • • • • • • • • • • • • •
REQUEST • • • • • •
• • • • • • • •
SET AND SHOW TERMINAL
SHOW TERMINAL

• 3-2
• 3-3
• 3-7
3-9
• 3-9
• 3-9
3-11
3-12
3-12
3-13
3-14
3-14
3-14
3-14
3-17
3-18
3-18
3-19
3-20
3-20
3-20
3-21
3-21
3-22
3-22
3-22
3-26
3-29
3-32
3-33
3-33
3-43

HANDLING FILES
FILES ON RSX-llM/M-PLUS SYSTEMS
• • • •
• 4-1
File Ownership and Location
• • 4-2
File Specification • • • • • •
• • • • • 4-2
Defaults in File Specifications
• • • • • • 4-3
Wildcards in File Specifications • • •
• 4-6
File Protection and Volume Protection • • • • • 4-9
CREATING DIRECTORIES AND SEQUENTIAL FILES
4-10
CREATE • • • • • •
• • • • • •
4-10
CREATE/DIRECTORY •
4-11
EDIT • • • • •
• • • • • • • • •
4-14
EDIT [/EDT] • •
4-14
EDIT/SLP • • • •
• • • • 4-17
EDIT/EDI and EDIT/editor •
• • • •
4-20
MAINTAINING A DIRECTORY • • • •
• • • • • • 4-22
DIRECTORY
• • • • •
• • • • 4-22
DELETE • • • • •
• • • •
• • • • • 4-31
PURGE
4-34
COPY • • • • • • •
• • • • •
4-37
RENAME • •
• • • • 4-41
CONVERT
• • • • •
• • • • •
4-43
OTHER FILE-RELATED COMMANDS
• • • • 4-50
TYPE •
4-50
PRINT
• • • • •
4-52
APPEND
• • • •
4-61
SORT • •
• • • • • • • • • •
4-63
DIFFERENCES
• • • • • • • •
4-69
UNLOCK • • • • •
• • • . • •
4-75
iv

CONTENTS
Page
4.5
4.5.1
4.5.2
4 = 5" 3

CHAPTER 5

4-77
4-77
4-79
4-79

SET AND SHOW •
SET DEFAULT
SHOW DEFAULT •
SET PROTECTION •
HANDLING DEVICES AND VOLUMES

DEVICES ON RSX-llM/M-PLUS SYSTEMS • • • • • • • • 5-1
Volumes and Devices
• • • • • • • • • • • • 5-4
Physical Devices, Pseudo Devices, LUNs, and
5 .1. 2
Logical Names •
• • 5-5
Pseudo Devices • • • •
• • • •
• • 5-5
5.1.2.l
LUNs • • • • • • • • •
• • 5-7
5.1.2.2
Logical Device Names •
.. 5-8
5.1.2.3
Public, Shared, Private and Unowned Devices and
5 .1. 3
Mounted Volumes
• • • • • • • • • • • • • • • • 5-9
How to Prepare a Scratch Disk for Use • • • • 5-10
5 .1.4
How to Prepare a Scratch ANSI Magnetic Tape for
5 .1. 5
5-12
Use
• • • • • • • • • • • •
• • • • •
Summary of Device and Volume Use Commands
5-12
5 .1. 6
ASSIGN • • • • • •
5.2
5-13
5.2.1
ASSIGN/REDIRECT
5-16
ASSIGN/TASK
5-18
5.2.2
5.3
DEASSIGN •
5-19
5-22
ALLOCATE • • • • • • •
5.4
DEALLOCATE •
5-24
5.5
MOUNT
5-26
5.6
Mounting Magnetic Tapes and Tape Sets • • • • 5-38
5.6.1
5-42
DISMOUNT • • • • • • •
5.7
INITIALIZE • • • • • •
5-47
5.8
5-57
INITIALIZE/UPDATE
5.8.1
5.9
BACKUP • • • • • •
5-60
5-72
5el0
SET AND SHOW • • • • • • • •
SHOW ASSIGNMENTS •
5-72
5.10.1
SET DEVICE • •
5.10.2
5-74
5.10.3
SHOW DEVICES • •
5-77
5.1
5 .1.1

CHAPTER 6

PROGRAM DEVELOPMENT

6.1
INTRODUCTION • •
SOURCE LANGUAGES •
6.2
MACRO
6.2.1
BASIC
6.2.2
FORTRAN
6.2.3
COBOL
6.2.4
6.2.4.1
COBOL-81 • • • • •
COBOL-81 EXAMPLES • • • •
6.2.4.2
PDP-11 COBOL • • • •
6.2.4.3
COBOL/Cll Examples •
6.2.4.4
6 .. 2 .. 5

6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.3.9
6.4
6.4.1
6.4.2

CORAL 66

•

LIBRARY • • • • • • • • •
LIBRARY/COMPRESS
LIBRARY/CREATE •
LIBRARY/DELETE • • • • •
LIBRARY/EXTRACT
LIBRARY/INSERT • • • • • •
LIBRARY/LIST • •
LIBRARY/REMOVE •
LIBRARY/REPLACE • • • •
Error Messages from LIBRARY
LINKING THE TASK • • • • •
Introduction to the LINK Command
LINK • •

• •

•

• •

• • •

•

• •

• • 6-1
6-1
• • 6-2
6-11
6-13
6-21
6-21
6-27
6-27
6-32
6-32
6-39
6-42
6-43
6-46
6-47
6-48
6-50
6-54
6-54
6-56
6-62
6-62
6-66

CONTENTS
Page

6.4.3
6.5
6.6
6.6.1
6.6.2
CHAPTER 7

LINK/C81 • • •
DEBUG
• • . • • •
SET AND SHOW • • •
SET GROUPFLAGS •
SHOW GROUPFLAGS

........
.........

RUNNING TASKS

7.1
TASK INSTALLATION AND EXECUTION • • • • • • •
Task Naming • • • • • • • • • •
• • • •
7 .1.1
7.2
INTRODUCTION TO THE RUN COMMAND • • • • • • •
Running Tasks Contained in Task Image Files
7.2.1
Running and Scheduling Installed Tasks
7.2.2
7.3
ABORT
• • • • • • • •
• • • • •
7.4
CONTINUE • •
7.5
CANCEL • •
7.6
STOP/BLOCK •
7.7
START
• •
7.7.1
START/UNBLOCK
7.8
INSTALL
7.9
REMOVE • • •
7.10
FIX • • • •
7 .11
UNFIX
SET AND SHOW •
7.12
SET PARTITION
7.12.1
SHOW PARTITIONS
7.12.2
7.12.3
SHOW TASKS • . • •
SHOW TASKS/ACTIVE • • • • •
7.12.3.1
7.12.3.2
SHOW TASKS/INSTALLED •
SHOW TASKS/DYNAMIC •
7.12.3.3
SHOW TASK:taskname/DYNAMIC •
7.12.3.3.1
SHOW TASKS/ACTIVE/DYNAMIC
7:12 .. 3:3,2
7.12.3.4
SHOW TASK/LOGICAL UNITS
• • • • • • • • •
SET PRIORITY • • • : •
• • • •
7.12.4
7.12.5
SHOW /CLOCK QUEUE
• • • •
• • • •
SHOW COMMON• • • • • • • • •
7.12.6
CHAPTER 8
8.1
8 .1.1
8 .1. 2
8 .1.3
8 .1. 4
8 .1. 5
8 .1.6
8 .1. 7
8 .1.8
8 .1. 9

6-87
6-90
6-91
6-91
6-92

• • 7-1
• • 7-2
• • 7-5
• • 7-8
7-12
• 7-16
7-21
7-22
7-23
7-25
7-25
7-26
7-34
7-35
7-37
7-38
7-38
7-43
7-45
7-46
7-51
7-53
7-53
7-55
• 7-57
7-59
• 7-60
7-61

SYSTEM CONTROL
SET AND SHOW . • . • • • •
SET DAYTIME
SHOW [DAY]TIME
SET SYSTEM • •
SET LIBRARY/DIRECTORY
SYSTEM AND LIBRARY UFDs
SHOW SYSTEM
SHOW LIBRARY •
SHOW USERS • •
SHOW MEMORY • • • •

CHAPTER 9

QUICK REFERENCE

APPENDIX A

COMMON ERROR MESSAGES

APPENDIX B

FUNCTIONS INITIATED BY DCL COMMANDS

• 8-1
. • • • • • • 8-1
• 8-2
• 8-3
• 8-4
• • • • • • 8-5
• 8-5
• 8-7
• • • • • • 8-7
8-9

CONTENTS
Page
APPENDIX C
C.l
C.2
C.3

SUMMARY OF TECHNICAL CHANGES
CHANGED SYNTAX
• C-1
NEW SYNTAX • •
• • • •
• • • • • • C-9
C-14
NEW OR CHANGED COMMANDS AND SYNTAX FOR V4.l/2.l

FIGURES
FIGURE

3-1
4-1
4-2

Terminal Keyboard and Keypad
• • • 3-1
File Organization on a Volume • • • • • • • • • • 4-1
Job Flag Page and File Flag Page •
• • • • 4-55

TABLES
TABLE

3-1
3-2
4-1
5-1
5-2
6-1
6-2
6-3
7-1
7-2

Keyboard and Keypad Characters • • • • • • • • • 3-15
Display of Terminal Attributes from SHOW TERMINAL 3-45
File Types • • • • • • • • • • • • •
4-4
Devices on RSX-llM/M-PLUS Systems
• • • 5-2
Pseudo Devices on RSX-llM/M-PLUS • •
• • • • • • 5-6
The /ENABLE and /DISABLE Qualifiers
6-6
The /SHOW and /NOSHOW Qualifiers
• 6-7
Task Builder Options • • • •
• • • • 6-76
Base and Size Specifications for SET PARTITION • 7-39
Task Status Flags
• • • . •
• • • • • • 7-48

vii

PREFACE

MANUAL OBJECTIVES
The RSX-llM/M-PLUS Command Language Manual provides information needed
to use a terminal to do work on an RSX-llM/M-PLUS system. Important
system concepts are introduced and explained in the context of the
DIGITAL Command Language (DCL).
DCL is a user-oriented command
language with English words and prompting for required command
elements.

INTENDED AUDIENCE
This manual is intended for any user of an RSX-llM/M-PLUS system. The
manual is a reference manual with many tutorial elements, but new
users should read the Introduction to RSX-llM and RSX-llM-PLUS first.
A user is anyone who interfaces with the system to perform some task.
There are two kinds of users:
privileged
and
nonprivileged.
Privileged users have access to functions that control and modify
system operation as well as functions that permit program development
and system maintenance. Nonprivileged users have access to functions
required for program development and local maintenance only.

STRUCTURE OF THE DOCUMENT
The manual is organized around the major operating system functions.
Following the introduction, each major function has a chapter to
itself. All commands relating to the function are described in the
chapter. The last chapter is an annotated alphabetical listing of all
DCL commands.
Chapter 1 introduces the basic concepts of DCL and explains how DCL is
implemented on RSX-llM/M-PLUS, as well as including many hints on
using DCL. The chapter includes summaries of the remainder of the
manual, and other introductory and summary material about DCL, the
operating system, and various utilities and system tasks.
Chapter 2 lists the most common forms of SET and SHOW commands.
Chapter 3 covers terminal operations, including logging in and logging
out, keyboard terminology and functions, setting and displaying
terminal attributes, broadcasting messages, and using the system HELP
commands.

PREFACE
Chapter 4 introduces file-handling operations on RSX-llM/M-PLUS,
including commands to create and delete files, list directories, and
rename, copy, type, and print files.
Wildcards and defaults are
explained.
Chapter 5 covers peripheral devices and introduces the system I/O
terminology.
The chapter explains the relations between hardware
devices and the software file system, and describes how to prepare
scratch disks and magnetic tapes for use on the system. Commands
affecting devices and software volumes are described.
Chapter 6 introduces the program-development facilities of the
and the DCL commands used with these facilities.

system

Chapter 7 explains how tasks run in the system, how they are named,
installed,
fixed in memory, and controlled while running.
In
addition, commands to abort tasks, to place tasks in the clock queue,
and to display information about tasks in the system are described.
Chapter 8 covers the DCL system-control commands.
Chapter 9 is the alphabetical listing of all DCL commands and their
formats,
including comments to remind you of specific points about
many commands and command elements. Each entry in Chapter 9 includes
a cross-reference to the full command description in an earlier
chapter. Chapter 9 is marked by a blue tab for quick reference.
Appendix A explains error messages common to
Other command-specific error messages are
command descriptions.

several DCL commands.
explained in the full

Appendix B lists the
operating system.

and

relations

between

DCL

the

rest

the

Appendix C is a Summary of Technical Changes. This appendix lists all
the command syntax that has changed or been added to DCL since
RSX-llM-PLUS Vl.O. These changes are extensive.

ASSOCIATED DOCUMENTS
Other documents related to RSX-llM/M-PLUS are
RSX-llM/RSX-118 Information Directory and Index.

described

the

Other documents related to RSX-llM/M-PLUS
RSX-llM-PLUS Information Directory and Index.

described

the

are

If you are entirely new to computers or to DCL, you should read the
Introduction to RSX-llM and RSX-llM-PLUS and follow through as
instructed there.
Although this manual is meant to be self-contained, you will find
important information in the RSX-llM/M-PLUS MCR Operations Manual and
the RSX-llM/M-PLUS Utilities Manual.
Programmers should
Development.

see

the

RSX-llM/M-PLUS

Guide

Program

PREFACE
CONVENTIONS USED IN THIS DOCUMENT
A number of conventions are used in the command descriptions
manual:

this

Meaning

Convention

The vertical ellipsis denotes elements of command
input
without
relevance to
the point being
discussed.
[/qualifier]

Any command field enclosed
in
brackets
is
optional.
If the brackets include syntactical
elements, such as dots (.) or slashes (/) , those
elements are required for the field.
If the field
appears in lowercase, you are to substitute a
legal command element if you include the field ..

[ g ,m]

This signifies either a User Identification Code
(UIC) or a user File Directory (UFD}. The g is a
group number and the m is a member number.
Where
a UIC or UFD is required, only one set of brackets
is shown, as [g,m].
Where the UIC or UFD is
ootional. two sets of brackets are shown; as
([g,m]]. · The UIC identifies a user.
The UFD
identifies a directory.

UPPERCASE

Any comand field in uppercase indicates that you
should type the word or letter exactly as shown.

lowercase

Any command field in
lowercase
is
to
be
substituted
for.
Usually the lowercase word
identifies the kind of substitution expected.

/qualifier

is a
Any command element preceded by a slash {/)
qualifier ..
DCL
Command qualifiers alter the
action of a command they are
attached
to.
Parameter qualifiers modify the action of the
command as it affects that parameter.

parameter

Required command fields are generally
called
parameters.
The most common parameters are file
specifications. Parameters are preceded by blanks
or DCL prompts.

: argument

Some parameters and qualifiers can be altered by
the inclusion of arguments preceded by a colon.
Arguments can be either numerical or alphabetical.
The equal sign (=) can be substituted for the
colon to introduce arguments.

PREFACE
Meaning

Convention

f ilespec

A full file specification includes device, UFD,
file name, file type, and version number, as in
this example:
DB1:(303,5]HIPPITY.HOP;2
Full filespecs are rarely needed. If you do not
give
a version number, the highest numbered
version will be used.
If you do not give a UFD,
the
default UFD will be used.
Some system
functions default to particular file types.
See
Chapter
4
for
more
information
on
file
specifications. See also the individual command
descriptions.
Some commands accept a filespec with a DECnet node
name. See Chapter l for more information.

red ink

All user input in examples is printed in red ink.
An oval symbol with
a
2to
6-character
abbreviation indicates that you are to press the
corresponding key on your terminal. For example,
RET indicates that you are to press the RETURN
key, and DEL means that you are to press the
DELETE key.
The oval symbol CTRL/a means that you are to press
the key marked CTRL while simultaneously pressing
another key. Thus, CTRL/Z indicates that you are
to
press
the
CTRL
key
and
the
Z key
simultaneously. This is echoed on your terminal
as AZ. Not all CTRL characters echo. See Chapter
3 for more information.
describes

pink shading

Text shaded in pink
Operating System only.

gray shading

Text shaded in gray describes
Operating System only.

the

See Chapter 1 for more information on DCL conventions.

xii

the

RSX-llM

RSX-llM-PLUS

CHAPTER l
INTRODUCTION

DCL is the DIGITAL Command Language.
DCL provides RSX-llM/M-PLUS
users with an extensive set of commands for interactive program
development, device and file manipulation, and
interactive program
execution and control.
If you are new to computers, or if you wish a quick review of DCL and
the operating system, you should read the Introduction to RSX-llM and
RSX-llM-PLUS.
This manual includes a guided tour of thP operating
system,
including an interactive terminal session that introduces all
of the most commonly used DCL commands.
DCL commands are full words that describe the action to be taken, not
abbreviations or mnemonics.
Thus, if you wish to set a terminal to
lowercase, you type SET TERMINAL/LOWERCASE. Because DCL commands and
command elements are full words, they are self-documenting.
You are not required to use the full
form of DCL commands at the
terminal, however.
Usually, you need type only the command elements
required to form a unique command.
For instance, SE TE/LOW will also
set a terminal to lowercase, but SE TE/LO will not work because there
is also a command SET TERMINAL/LOCAL.
See Section 1.2 for more
information on how DCL commands are parsed.

1.1

RSX-llM/M-PLUS AND DCL:

BASIC CONCEPTS

RSX-llM/M-PLUS systems may have one or more command line interpreters
(CLis).
All systems include MCR (the Monitor Console Routine). Many
systems also include DCL, and some systems include other CLis.
Both
MCR and DCL include commands to invoke most system tasks and utilities
and to set and display certain system characteristics.
In general,
MCR commands name tasks, such as PIP, a utility used to manipulate
files (for example, to copy or type them), while DCL commands specify
actions directly, as in the COPY command or the TYPE command.
MCR is the fundamental command line interpreter
for
the
(CLI)
RSX-llM/M-PLUS Operating Systems. MCR also provides commands to set
and display certain system characteristics.
MCR provides the most
direct
interface with the operating system, either RSX-llM or
RSX-llM-PLUS.
In general, MCR commands must be entered in exact syntax.
MCR
commands follow no set syntax rules, however.
Most MCR commands are
terse abbreviations or mnemonics.
DCL is an optional user-oriented CLI included in most systems with
many users.
Commands in DCL are English-like words and follow
well-defined syntax rules. Full commands are self-documenting.
DCL
is designed for consistency and ease of use.

1-1

INTRODUCTION

DCL is based on the command languages used on a number of DIGITAL
operating systems.
In particular, RSX-llM/M-PLUS DCL is designed for
compatibility with future releases of VAX/VMS DCL.
See Section 1.7
for more information on DCL compatibility.
DCL on RSX-llM and RSX-llM-PLUS systems is a CLI task that translates
DCL commands into MCR commands for execution by the system. The DCL
SET DEBUG command displays the MCR translation for any DCL command on
your terminal.
See Section 1.2.15 for more information on the SET
DEBUG command.
Depending on the kind of use you make of your system and the nature of
your system, you may find it more convenient to use one CLI or the
other, or both.
All nonprivileged system functions are available
directly from DCL, but some privileged functions are not.
All
program-development facilities and all common utility functions are
available from DCL.
Because RSX-llM and RSX-llM-PLUS are designed to be tailored to the
needs of each installation, not every feature of DCL described in this
manual is available on every system.
Some DCL commands depend on
layered products that may not be available at your installation. Many
features, particularly on RSX-llM systems, are system-generation
options that may not have been selected at the time your system was
generated. Shaded text indicates that the feature
is available on
only one system.
You should see your system manager or another
knowledgeable system user if some feature described
in this manual
does not appear to be available at your installation.

1.2

THE DCL COMMAND LINE

A command consists of a command name or verb describing the action the
system is to take. Most commands also include one or more parameters
and qualifiers to further define the action of
the
command.
Qualifiers are preceded by a slash {/) and parameters are preceded by
a space.
Both qualifiers and parameters can
take
arguments.
Arguments are preceded by a colon {:).

Commands are passed to the operating system with a terminator, either
RETURN or ESC.
{The ESC key may be labeled SEL or ALT MODE.
Its
action differs from that of the RETURN key in that the cursor does not
return to the left margin and no monitor prompt is returned after
execution is completed.)
Unless the action of the RETURN differs greatly from what is expected,
the examples and command formats
in this manual do not include an
indication that each line in the command is terminated by a carriage
return.
(See Section 1.2.13, for a discussion of command lines too
long to fit on one line of your terminal.)
Some commands require parameters or arguments as part of the command
line.
If you fail to supply a required command element, DCL prompts
you with one or two words indicating the general nature of the
required element.
If you do not understand the prompt, type a
question mark (?) for help.
{In some cases, an omission causes an
error rather than a prompt.)
Section 1.2.1 discusses prompting in detail.
This section introduces the rules governing the use of DCL.
The
examples in this section are intended to illustrate these rules, not
to illustrate the full capabilities of the command.
For more detail,
see the individual command descriptions.

1-2

INTRODUCTION

Prompting

1.2.1

The prompts teach you the form of a command
supply required command elements.

requesting

that

you

leave

out.

For example, the RENAME command works as follows:
>F~ENAME

From? BROWNS.STL
To? ORIOLES.BLT
The one-line format for RENAME is:

>RENAME BROWNS.STL ORIOLES.BLT
The formats can be mixed.
For example:

DCL prompts for

whatever

you

>RENAME BROWNS.STL
OR IO LES. BLT

To?

There are no defaults for prompts.
You must supply a response to any
If you do not wish to continue with the command, type a
CTRL/Z.
1"'\vn-m~+

.t-'.J- V1Lll:' ' - .

1.2.2

Qualifiers

Qualifiers modify the action of the command.
with a slash (/) and are generally optional.

Qualifiers always

start

Qualifiers are either command qualifiers or parameter qualifiers.
Most qualifiers are command qualifiers.
In this manual, command
qualifiers are always shown as modifying the command verb, as in this
example:

>TYPE/TODAY *•HLP
However, most command qualifiers can appear anywhere in the command
line.
Another name for these qualifiers is floating qualifiers.
The
following examples illustrate how command qualifiers can float:

>TYPE t.HLP/TODAY
or
>TYF'E
File(s)? t.HLP/TODAY

or
>TYF'E
File(s)? !TODAY
F i 1 e ( s ) '?

t • HL F'

You can mix formats, as in the following example:

>TYF'E/TODAY
Filets>? *·HLP/EXCLUDE!HELPF.HLP;*
or

1-3

INTRODUCTION

>TYPE/TODAY
File<s>? *·HLP/
Qualifier? EXCLUDE:HELPF+HLP;*
or

>TYPE/TODAY
File<s>? I
Qualifier? EXCLUDE:HELPF.HLP;11
File(s)? *·HLP
Note that you are prompted for
a qualifier when a slash with no
qualifier attached appears on tr.~ command line. When you supply the
qualifier, do not type the slash
1 ain.
Regardless of where the qualifier appears, it has the same effect.
Almost all command qualifiers can float in this way.
In a few cases,
the command qualifier must appear directly after
the command it
modifies. Whenever two similar commands are described separately,
such as ASSIGN and ASSIGN/REDIRECT or CREATE and CREATE/DIRECTORY, the
distinguishing qualifier cannot float.
Other qualifiers to such
commands can still float, however, as in this example:

>CREATE/DIRECTORY
Devicer UFD? [303,5J/ALLOCATION:5
which is the same as

>CREATE/DIRECTORY/ALLOCATION!5 [303,5J
Qualifiers described as parameter qualifiers, or filespec
cannot float.
Most DCL parameters are filespecs.

qualifiers,

Parameter qualifiers do not modify the action of the command;
they
modify the action of the command as
it concerns that particular
parameter or supply additional information needed for the command to
execute properly.
For instance, in the following example:

>MACRO HIYA, TESTBLD/LIBRARY, PIGEON
the qualifier /LIBRARY identifies a
particular
library.
Obviously, /LIBRARY could not float.

file

being

If, however, a command has parameter qualifiers that are identical
to
command qualifiers,
you may find confusing results from floating
qualifiers.
For instance, the PRINT command has both the command qualifier /COPIES
and
the parameter qualifier /COPIES.
For instance, if you attach the
/COPIES qualifier to the PRINT command, as shown below:

>PRINT/COPIES!2 OZY+TXT
then two copies of the file are queued for printing.
You can include more than one file in a
PRINT command.
Each file
specified is a parameter to the PRINT command, although only the first
file is a required parameter.
The command

>PRINT OZY.TXT, IZZY.TXT/COPIESt2
includes the parameter qualifier /COPIES:2.
The command causes one
copy of OZY.TXT to be printed, which is the default, and two copies of
IZZY.TXT to be printed because the default was overridden.

1-4

INTRODUCTION

(minus)

Many qualifiers can be negated by prefixing NO or
qualifier name.
Thus, the command

the

while

the

>MACRO/OBJECT SIMPLE.MAC
directs the MACR0-11 Assembler to
command

make

object

file,

>MACRO/NOOBJECT SIMPLE.MAC
or

>MACRO/-OBJECT SIMPLE.MAC
directs the MACR0-11 Assembler to o~~t the object file.
In the first
example, /OBJECT is the default qualifier and need not be explicitly
included.
In other words, unless your MACRO command
includes the
/NOOBJECT qualifier, an object file is produced.

1.2.3

HELP

HELP is available from the system for all DCL commands and also for
many other aspects of the system.
You can get help through the HELP
command or by typing a question mark
(?)
in response to any DCL
prompt.
For instance,
following:

you

wish

help

the

TYPE

command,

type

the

>HELP TYPE
lYPE[/Qualifier[sJJ filesPec[sJ
/DATE:dd-mmm-YY
/SINCE:dd-mmm-yy

/THROUGH:dd-mmm-yy
/SINCE!dd-mmm-yy/THROUGH!dd-mmm-yy
/TODAY
/EXCLUDE!filesPec
The TYPE command disPlass the contents of
terminal.

text

files

on sour

The HELP text consists of a brief explanation of the command
followed
by an illustration of the syntax, showing that TYPE accepts one or
more filespecs, and one or more qualifiers.
See Section 4.4.1 for
more
information on TYPE and its qualifiers.
Or, type a HELP command
naming the qualifier to get more information on that qualifier.

>HELP TYPE TODAY
TYPE/TODAY filesPec[sJ
Ttie /TODAY aualifier specifies that sou wish the TYPE command to
tYPe only files created today.

1-5

INTRODUCTION

If you wish help while being prompted by the
following procedure:

TYPE

command,

use

the

your

>TYPE
File(s)? ?
TYPE[/aualifier[sJJ filesPec[sJ
/DATEtdd-mmm-Y'd
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-YY

/TODAY
/EXCLUDE:filesPec
The TYPE command disPlaYs the contents
ter·minal.

text

files

File(s)?

The same help text is printed on your terminal, but the prompt
returns, meaning the TYPE command is still waiting for you to list the
files you wish typed.
You can also get help on a specific subtopic while being prompted by a
command by responding to the prompt with a question mark.
For
example:
>SE ..f

Function? ·7
SET thins
The SET command can be used to set something.
things can be set with this command!

LIBRARY

DEBUG
ENO J PART IT ION

SYSTEM

TERMINAL

rnAYJTIME

For

information

1~CCOl.JNi

the

SET

DEFAULT
PRIOR I TY
ACCOUNTING

The

followins

DEVICE
PROTECT ION
command,

GROIJPFLAGS
QUEUE

see

HELF'

ING SET.

To get help on a specific thing, enter a question mark followed by the
thing:

Function? ? DEFAULT

SET DEFAULT [ddnn:JC(ufdJJ
The SET DEFAULT command sets your default directory

device'

or both.

SET DEFAULT with no Parameters returns a nonPrivileged user to
the losin device and UFD.
For Privile~ed users, the unadorned
SET DEFAULT returns to the login device' but the UFD remains the
same.
Function? ?
You can also get help by typing a question mark
in response
system prompt (>) and to the explicit DCL prompt (DCL>).
1r you should decide after
the wrong command, enter a
execution of the command.
cancels execution of a DCL

the

reading the help text that you have chosen
CTRL/Z in response to the prompt to end the
(A CTRL/Z in response to a prompt always
command.)

1-6

INTRODUCTION
From a DCL terminal, the command HELP provides information on DCL and
the com.~and HELP/MCR provides information on MCR.
The command HELP
SHOW provides information on the DCL SHOW command, and HELP SHOW
TERMINAL provides information on the DCL SHOW TERMINAL command.
From an MCR terminal, the command HELP provides information on MCR and
the command HELP/DCL provides information on DCL.
There may also be special help files providing information on special
aspects of your installation.
In addition, you can create local help
files for your own use.
See Section 3.5 for more information on
files.

the

HELP

command

and

help

DCL

MCR and DCL Commands

1.2.4

You can usually enter MCR commands from terminals set to
commands from terminals set to MCR.

DCL

If you are at a DCL terminal and wish to enter an MCR command,
simply
precede the command with an MCR.
The command is passed directly to
MCR while the terminal remains set to DCL.
Here is the format of the MCR command:
DCL>MCR
MCR command line?

mcrcommand

or
DCL>MCR mcrcommand
And, if you wish to enter a DCL command from an MCR terminal, use the
DCL command.
The command is executed and the terminal remains set to
MCR.
Here is the format of the DCL command:
MCR>DCL dclcommand
There are no prompts from this command.

Abbreviations

1.2.5

It is rarely necessary for you to type either the complete command
name or the complete qualifier name.
You only need to type the
characters needed to distinguish the command or qualifier
from all
others.
For example:
•

TYPE can be abbreviated T because
beginning with that character.

the

INITIALIZE can be abbreviated !NI, but not IN.

•

INSTALL can be abbreviated INS, but not IN.

only

command

Three letters will usually be enough.
Four
letters will always be
enough.
You can often omit other parts of commands as well.
You
should experiment to find how short various commands can be cut.

1-7

INTRODUCTION
For instance, the command
>SET

TERMINAL/VT52

is the documented format for the command that sets a terminal as a
VT52.
The same command to VAX/VMS DCL does the same thing.
However,
the RSX-llM/M-PLUS version of DCL permits you to type the following

>SE VT52
to achieve the same result.
These briefer forms should be used interactively only, and not used
when you are making a permanent record or creating an indirect command
file (or batch job).
You should also see Section 1.6.1 for a
discussion of compatibility between RSX-llM/M-PLUS DCL and other
versions of DCL used on other operating systems.
For your convenience, some frequently used commands have brief
These are:

Command

Brief Form

ABORT
BROADCAST
COPY
DIRECTORY
DEALLOCATE
DEASSIGN
EDIT
FORTRAN

Command
HELP
HELP
LOGOUT
LINK
MACRO
PRINT
RUN
SHOW

A
B

D
DEA
DEAS
E
F

forms.

Brief Form
H
?

LO
L
M
p

These shortened forms replace the command verbs for entering cornmands.
See the Note in Section 1. 6 .1 on support for brief command formats.

1.2.6

Numbers and Dates

DCL recognizes both octal and decimal numbers.
You usually do not
have to identify a number as octal or decimal.
All numbers are
recognized as being octal or decimal, unless otherwise noted.
DCL recognizes dates in two forms:
dd-mmm-yy as in 21-JAN-82
or
mm/dd/yy as in 1/21/82
System displays are always in the first format.

1.2.7

Multiple Parameters

Some commands permit you to enter a single filespec or other parameter
by a
list of parameters.
If you are entering a list of parameters,
each parameter must be set off by commas.
For example:
'>PF:lNT

t1LPHf-1,.TXT

1-8

INTRODUCTION
causes a single file to be printed, while
~-FRINT

ALPHA.TXTr BETA.TXT, GAMMA.TXT
option

causes three files to be printed.
You have the
blanks on either side of the comma in lists.
If you end the list with
parameters. For instance,

comma,

DCL

prompts

you

including

for

further

>PRINT ALPHA.TXT, BETA.TXT,
GAMMA.TXT

File(s)?

Some commands accept a list of arguments
to a single qualifier or
parameter.
In such cases, the list of arguments must be enclosed in
parentheses, with each element set off by commas.
For example:

>MACRO/SHOW!CCALLSrCOMMENTS> HIYA
If you need to enter only a single
parentheses.
For example:
>M~CRO/SHOW:CALLS

l.2a8

argument,

you

not

need

the

HIYA

Underscore Character

The underscore character
is used to make DCL commands more
readable where two words are needed to name a single command element,
such as PRINT/FLAG PAGE.
However, you need not type the underscore to
enter the command.- PRINT/FLAGPAGE is the same as PRINT/FLAG_PAGE.

1.2.9

Colon and Equal Sign

The command descriptions in this manual show arguments set
colon (:) , such as

off

>PRINT/COPIES:2 IZZY.TXT
You can always replace such colons with an equal sign (=), as in
example:
~PRINT/COPIES=2

this

IZZY.TXT

Colons in device names, such as DBl:, and so forth, cannot be replaced
by equal signs.

1.2.10

Quoting Strings

If you wish to include an exact string
in a
string in quotes.
For instance, the message

DCL

command,

put

>BROADCAST/ALL Rock and roll will never die
is broadcast as

11-DEC-82 13:55
From PRINCE::WRITERS CTT64:> to ALL
ROCK AND ROLL WILL NEVER DIE

1-9

the

INTRODUCTION
while

>BROADCAST/ALL "RocK and roll will never die'
is broadcast as

11-DEC-82 13!56
From PRINCE::WRITERS <TT64!) to ALL
"Rock and roll will never die"
You also need quotes
/PARAMETERS qualifier
INSTALL.

1.2.11

when passing commands to tasks using the
to MOUNT or the /COMMAND qualifier to RUN or

ANSI File Names

ANSI file names do not have the same format as Files-11 file
may contain characters that are illegal in Files-11. For
""MONEY$.'"' is a legal ANSI file name, as is '"'CASH$."". To
file names in a command, simply enter them as shown in the
example:

>COPY
From'? MM:
To?

names and
instance,
use those
following

MONEY$.""
MM1!'"CASH$+"A
11

If you are copying a file from a tape to a Files-11 disk, however, you
must use only Radix-50 file specifications, such as

>COPY
F T'OITI? MM! •• MONEY$+ I.
To~

DB:r200,1JRADTX50.TXT

The Radix-50 character set consists of the numbers 0 through 9,
letters of the alphabet, the dollar sign ($) and the period (.).

1.2.12

the

DECnet and DCL

Some commands will accept DECnet node names as
They are:
APPEND

COPY
CREATE

part

filespec.

DELETE
DIRECTORY
TYPE

If the node you name has a DECnet default account, you can simply
the node name to the filespec in the following fashion:

add

>TYPE PRINCE!:DB2![303,5JROMAN.TXT
All the usual rules about file and volume protection
of course.
If the node you name has named
filespec in quotes, as shown:

directories,

you

are
must

>TYPE EEETEE!!"DISKSUSERDISK:[DALTONJDESPERADO.DIS"

1-10

maintained,
enclose

the

INTRODUCTION
1~2.13

Command Line Continuation

The hyphen (-) is used to indicate line continuation. When you end a
command line with a hyphen and a carriage return, the DCL continuation
prompt (->) indicates that you can continue entering the command line.
If you are continuing a line from a prompt, such as Task? that prompt
is the indication that the line is being continued.
This feature permits you to enter command lines
including
characters than your terminal has room for on one line.
Most DCL commands are limited to 250 characters in
line can be longer than 250 characters.

all.

command

Here is an example of line continuation:

>PRINT /COPIES! 2/LENGTH: 60/FLAGPAGE/AFTrn ! ( 04-JUL-80) OZY. TXT, - ID

->IZZY.TXT,

FIZZY.TXT

rBm

The command is not entered until DCL encounters a line ending with a
carriage return not preceded by a hyphen.
In the example, the first
carriage return does not enter the command. Only the second carriage
return enters the command.
The carriage return can be on a line by
itself.
NOTE

·Rsx:_i1M_.'J?I.us·, supports ,'line· c.ontinuation
.for.bo:th.MCR. .and· bc't;.·
RSX ... llM. supports 1 ine continuation for
DCL only. · Therefore, it is possible for
a bCL Command on RSX-UM to t:tahs1ate to
an MCR line fhat
is too long for the
system to. handle.
In such cases, yo.u
should
examLne the command to finct
unnecess.ary elements, such as defaults
that
need
not
be
·specified,
or
'gual.iflers . that
could
be
entered
separately
without
defeating
your
purpose.

1.2.14

Comments in Command Lines

You can include comments in a DCL command line
point (!).

with

the

exclamation

If the comment ends the command line, only a single exclamation
is needed, as in this example:

>PRINT OZY.TXT !Poem

Shelle~

If the comment is within the command line, two exclamation points
needed, as in this example
>PRINT!Parod~

point

Shelle~!

are

IZZY.TXT

These comments are ignored and not interpreted in any way by DCL.
Comments can be placed at any natural break in the command line:
between qualifiers, between parameters, even as part of a response to
a prompt.

1-11

INTRODUCTION
Another example:

>PRINT/FORMS:2!Letter-audlits Printer!
You may want to include comments when
record of a terminal session.

1.2.15

you

IZZY.TXT
are

keeping

permanent

SET DEBUG

SET DEBUG displays the MCR translation of any DCL command.
Format
SET [NO]DEBUG[/qualifier[s]]
Command Qualifiers
/[NO]EXECUTE
/FULL
Command Qualifiers
/[NO]EXECUTE
The /EXECUTE qualifier indicates that you wish the DCL command to
execute after the translation
is displayed.
The default is
/NOEXECUTE, meaning that the translation only is displayed. When
SET DEBUG/NOEXECUTE is
in effect, you can only issue SET DEBUG
commands or MCR commands using the DCL MCR command;
all other
DCL commands are trapped and translated.
You can issue SET
NODEBUG to turn off SET DEBUG.
You can also issue SET DEBUG with
either /FULL or /EXECUTE or both.
/FULL
The /FULL qualifier indicates that you wish SET DEBUG to display
the logical symbols
(!FORM queue) used by DCL to translate the
command as well
as
the
translation
itself.
See
the
RSX-llM/M-PLUS System Management Guide for information on how DCL
uses these logical symbols.
Examples

>SET DEBUG
>SHOW TIME
TIM
>INITIALIZE/EXTENSION:2001PROTECTION!(SYS:RWED,OWN!RWED,GR0,wo>
Device? DK2
Label? HOTROD
INI DK2!HOTROD/EXT=200./PRO=ERWED,RWED,,J
>SET DEBUG/EXECUTE
>S TIM
TIM
21:33:46 11-DEC-82

>SET NODEBUG
In this example, the user first issued SET DEBUG.
Then the user
typed SHOW TIME.
DCL displayed TIM, which is the MCR command to
display the date and time, but no date and
time is displayed
because /NOEXECUTE was
in effect.
Then the user typed an
INITIALIZE command and DCL displayed the MCR translation of the

1-12

INTRODUCTION

same command.
Then the user typed SET DEBUG/EXECUTE and typed
SHOW TIME again.
This time, after disolaying the MCR command
TIM, DCL passed the command TIM to MCR and the date and time were
displayed.
Finally,
the user typed SET NODEBUG to end session
with SET DEBUG.

Notes
Use SET DEBUG to check on the MCR syntax of any DCL command.
This is particularly helpful when learning the brief forms of
commands.
SET DEBUG creates your own copy of DCL that remains present while
SET DEBUG is in effect.
Therefore, SET DEBUG creates a load on
the system.
You should use SET DEBUG sparingly, particularly
when the system is under heavy use.

1.2.16

Errors

You can correct typing errors or change the line completely, by using
the RUBOUT or DELETE key, or CTRL/U (provided you have not terminated
the line}.
You can cancel the execution of any DCL command by typing a CTRL/Z.
If the system detects an error in the command line input,
the appropriate error message at the issuing terminal.
Here are some examples of incorrect commands and
they produce:

the

returns

error

messages

>f:· F: I _.: T I l Z Y • T XT
DCL

Illesal command

~PRINT/PURPLE

IZZY.TXT

Illesal or contradictorw aualifier

PRINT/PURPLE IZZY.TXT
>PRINT/COPIES!T~ELVE

IZZY.TXT

Numeral expected

PRINT/COPIES:TWELVE IZZY.TXT
In the first case, the error was detected by DCL, as indicated by
first part of the error message.
There is no DCL PRIJT command.
entire command was rejected.

the
The

In the second case, the command was entered correctly, but the
qualifier was incorrect.
The first part of the message shows that the
error was detected within the PRINT command itself.
The command
is
reprinted and a circumflex (A) points to the error.
In the third case, the command and qualifier were
argument was in error.
The message explains
circumflex points to the error.

correct, but the
the error and the

Sometimes the circumflex does not point directly at the error, but at
the point at which the command started to go wrong, which may be
several characters before the actual error.

1-13

INTRODUCTION
Typing mistakes are by far the most common cause of errors.
Retyping
the command often eliminates the error. Other common causes of errors
are omitting a space or other delimiter in a command line,
specifying
invalid devices or nonexistent files, issuing privileged commands from
a nonprivileged terminal, and failing to type a sufficient number of
characters to distinguish the command or command element.
The command descriptions include the most common errors produced by
the commands and suggestions for correcting the errors. All the DCL
error messages are listed and explained in Appendix A of this manual.
In some cases, such as file-system errors, you may need to go to
another manual for explanation of the error or seek help from a
knowledgeable system user.

1.3

FUNCTIONAL GROUPING OF DCL COMMANDS

This manual includes seven functional groupings of commands, each
grouping constituting a chapter.
Each of these chapters is described
here.
Fully detailed descriptions of each command are included
in
these functional chapters.
The functional groupings of commands are
described in Sections 1.3.1 through 1.3.7.
Each functional chapter
also includes an introduction to the important concepts of the
functional group.
Command descriptions can have five parts:
•

Brief statement of the function of the command.

Full description of
• prompts,
defaults,

including
the format of the command,
acceptable values for arguments, and the
effects of each qualifier.

•

Examples of the command
in use.
These examples
often
illustrate less obvious aspects of the use of the command.

•

Notes, including warnings about side effects, counteracting
commands, recommendations for further reading, and so forth.

•

Error messages, including an explanation and a suggested
action for each error.

user

All command descriptions start with the function and the format.
Most
include at least one example.
In some cases, there are no notes.
Only error messages specific to the command are
included in the
command descriptions. General error messages, such as those relating
to syntax, are described in Appendix A.
The full command description includes all these parts.
In particular,
you should read the examples carefully. Often the examples clarify
points made in the format descriptions.
In addition, the format of each DCL command
is
alphabetical listing in Chapter 9 of this manual.

presented

the

DCL commands cover the full
range of
nonprivileged
commands.
Nonprivileged commands are those commands needed in everyday use of
the system by all users. Many privileged commands are also included
in DCL.
Privileged commands are those commands that affect system
operations. For instance, the SHOW TIME command
is a nonpriviieged
command, but the SET TIME command is privileged.

1-14

INTRODUCTION

1.3.1

The SET and SHOW Commands

The SET commands dynamically alter system characteristics.
The SHOW
commands
display
system
characteristics.
These commands are
introduced in Chaoter 2.
The most useful functions of SET and
SHOW
are also described in Chapter 2.
However, because such a wide variety
of functions can be altered or displayed, the remaining
functions
of
SET and SHOW are listed in Chapter 2 but described in the appropriate
functional chapter.
SET and SHOW are the last commands described
in
each chapter.
For example, SET DEVICES and SHOW DEVICES are described
in full at the end of Chapter 5, "Handling Devices and Volumes";
and
SET TERMINAL and SHOW TERMINAL are described at the end of Chapter 3,
"Terminal Operations."
The SET or SHOW command and its function are considered
to
form a
single command.
That
is,
rather
than referring
to the TERMINAL
function of the SHOW command, you would refer
to
the SHOW TERMINAL
command.

1.3.2

Terminal Operations

All commands directly related to terminal operations are described
in
Chapter
3.
The commands include LOGIN, LOGOUT, BROADCAST, REQUEST,
HELP, SET TERMINAL,
and
SHOW TERMINAL.
In addition,
Chapter
3
includes a detailed description of the use of the terminal keyboard on
RSX-llM/M-PLUS systems.
All
control
(CTRL)
characters and other
important keys are explained.

1.3.3

Handling Files

Most information in RSX-llM/M-PLUS systems is in files
in User File
Directories
(UFOs).
These files and directories are located within
Files-11 volumes.
All commands relating to files are described in Chapter 4.
The commands
include CREATE, CREATE/DIRECTORY,
EDIT,
EDIT/EDT,
EDIT/SLP,
EDIT/KEO,
COPY,
CONVERT,
TYPE, PRINT, RENAME, DIRECTORY,
DELETE, PURGE, SORT, APPEND, DIFFERENCES, and UNLOCK.
SET and SHOW commands described in Chapter 4
and SET and SHOW DEFAULT.

1.3.4

include

SET

PROTECTION

Handling Devices and Volumes

Volumes are held on magnetic media, usually disks.
The volume is
in
the RSX-llM/M-PLUS format, called Files-11.
The disks are mounted on
hardware devices.
Devices can be public,
available to all
users;
shareable,
available to some users but not others;
or private,
available to a single user only.
All commands relating to volumes and devices are described in Chapter
5.
The
commands
include
ALLOCATE,
DEALLOCATE,
ASSIGN,
ASSIGN/REDIRECT, ASSIGN/TASK, DEASSIGN, MOUNT,
DISMOUNT,
INITIALIZE,
INITIALIZE/UPDATE, and BACKUP.
SET and SHOW commands described in Chapter 5 include SHOW
and SET and SHOW DEVICES.

1-15

ASSIGNMENTS

INTRODUCTION
1.3.5

Program Development

RSX-llM/M-PLUS provides full facilities for program development, which
are described
in Chapter 6.
The commands described include MACRO,
BASIC, COBOL, FORTRAN, LIBRARY, and LINK.
SET GROUPFLAGS and SHOW GROUPFLAGS are also described.

1.3.6

Running Tasks

The task is the fundamental
executable
programming
unit
on
RSX-llM/M-PLUS.
All commands related to running tasks are described
in Chapter 7.
These commands include RUN, ABORT, CONTINUE, CANCEL, INSTALL,
FIX and UNFIX, and START, START/UNBLOCK and STOP/BLOCK.

REMOVE,

SET and SHOW commands described in Chapter 7 include SET and SHOW
and SHOW
PARTITION,
SHOW TASKS,
SET PRIORITY,
SHOW CLOCK_QUEUE,
COMMON.

1.3.7

System Control

System control commands are described in Chapter 8.
Most of these
commands are privileged, but the SHOW commands described in Chapter 8
are nonprivileged.
Only SET and SHOW commands are described in Chapter 8.
These include
SET and SHOW SYSTEM/DIRECTORY, SET and SHOW LIBRARY/DIRECTORY, SET and
SHOW [DAY]TIME: SHOW MEMORY! SHOW USERS! SET and SHOW SYSTEM/POOL: and
SET SYSTEM/[NO]LOGINS.

1.4

USING THE QUEUE MANAGER:

PRINT AND BATCH JOBS

The RSX-llM/M-PLUS Queue Manager provides facilities
for printing
files on line printers or other output devices.
Files can be printed
under user control or under
the control of a system task or
applications task.
See the description of the PRINT command in
Section 4.4.2.
In addition, on RSX-llM-PLUS,
the
Queue
Manager
provides
a
batch-pro·cessing
facility~
Batch jobs use the system without
requiring you to ·be present.
This means that jobs that take a long
time to run,
or otherwise tie up system facilities, can be run when
there are fewer demands on the system, such a,s . at night or on
weeken.ds.
All uses of the Queue Manager are described in a separate manual,
the
RSX-llM/M-PLUS
Batch
and Queue Operations Manual.
The manual
introduces and explains arr-the uses of the Queue Manager and the
batch-processing subsystem.
The manual
includes sample print and
batch jobs, full descriptions of commands to the batch processors, all
commands for placing jobs in queues and displaying queue contents, and
a complete description of the process of setting up the Queue Manager.
In addition,
the manual includes an explanation of writing tasks to
spool output.

1-16

INTRODUCTION
1.5

INDIRECT COMMAND FILES IN DCL

In addition to the batch-processing subsystem, RSX-llM/M-PLUS provides
the Indirect Command Processor (Indirect) as an alternative means of
automatically passing commands to the operating system. If you have a
series of commands to be executed in the same or similar fashion every
time, you can include these commands in a file to be run by Indirect.
Indirect accepts not only DCL and MCR commands, but also special
directives that allow you to program the execution of the indirect
command
file.
Indirect
is
described
in
full
in
the
RSX-llM/RSX-llM/M-PLUS MCR Operations Manual.
An indirect command file can include both MCR and DCL commands.
If
the file contains commands to both of these command line interpreters
(CLis), you must either prefix each CLI command with the CLI name, or
change the CLI setting of your terminal before each CLI command. When
your file has completed, reset the terminal to your usual CLI in the
indirect command file.
For example, if your terminal is set to DCL
and you have MCR commands in your indirect command file, you can
prefix each MCR command with "MCR," or set the terminal to MCR before
each command and then reset it to DCL afterwards.

1.6

DCL AND RSX-llM/M-PLUS UTILITIES AND SYSTEM TASKS

The RSX-llM/M-PLUS Operating System includes a number of utilities and
other system tasks designed to assist you in your use of the system.
Most utilities are used to create or alter files in some way.
Many DCL commands invoke these utilities transparently to the user.
Just as some DCL commands are passed to MCR, other DCL commands are
passed to utilities.
One important utility is PIP, the Peripheral Interchange Program,
which is used to manipulate files. DCL functions such as APPEND,
COPY, DELETE, PURGE, and DIRECTORY depend on PIP. As another example,
the LINK command invokes the RSX-llM/M-PLUS Task Builder. Appendix B
of this manual gives information on the relationships between DCL and
the utilities and other system tasks.
Each utility has its own command structure, but DCL commands allow you
to use the most common functions of the most commonly used utilities
without learning a new command set.
For full access to
the
capabilities of the utilities, however, you may need to use them
directly. To do this, you must run the utilities at your terminal.
This is done with a RUN command in the form
>RUN $utl
where utl is the 3-letter name of the utility. If you wish to access
one of the utilities provided bv Record Management Services-11
(RMS-11), use a command in the form
>RUN $RMSutl
where utl is the 3-letter name of the RMS-11 utility.
Here is some information on each of the RSX-llM/M-PLUS and RMS-11
utilities.
RSX-llM/M-PLUS
utilities
are
described
in
the
RSX-llM/M-PLUS Utilities Manual. RMS-11 utilities are described in
the RMS-11 documentation supplied with your system. Some system tasks
that might be considered utilities, such as the Task Builder, are
described in separate manuals.

1-17

INTRODUCTION

Utilities described in the RSX-llM/M-PLUS Utilities Manual:
•

PIP - Peripheral Interchange Program - a file transfer program
that provides means
for copying, concatenating, spooling,
renaming, listing, deleting, and unlocking files.

•

FLX - File Transfer Program - a file conversion program that
provides means for
transferring files
from one operating
system to another.
Specifically, you can transfer
files
in
DOS-11 and RT-11 format to RSX-llM/M-PLUS format (Files-11),
and vice versa.

•

DMP - File Dump Program - a file listing program that provides
means
for obtaining a
printed copy of the contents of any
file, including object files and task images, in any one of
several useful formats.

•

EDI - Line Text Editor - an interactive editing program for
creating and maintaining text files on a line-by-line basis.

•

SLP - Source Language Input Program - a utility that
a means for maintaining and auditing source files.

•

LBR - Librarian Program - a library maintenance program that
provides a means for creating, modifying, updating, listing,
extracting, and maintaining macro and object library files.

•

VFY
File Structure Verification
Program
a
disk
verification program that provides means for verifying the
consistency and validity of the file structure on a
Files-11
volume.

•

PAT - Object Module Patch Program - a
utility that provides
means to patch, or update~ a relocatable binary object module=

•

ZAP - ZAP Program - a
utility that provides the means to
examine and directly modify locations in a task image or data
file.

•

BAD - Bad Block Locator Program
a
utility that provides
means for determining the number and location of bad blocks on
a magnetic medium holding Files-11 volumes.

•

CMP - File Compare Program - a utility that provides the means
for comparing two files and listing the differences between
them.

provides

The RMS-11 utilities are provided as independent tasks to those who do
not have full access to RMS-11 functionality, either because they are
not programmers or are programming in a language other than MACR0-11.
The RMS-11 utilities are:
•

RMSBCK, a backup utility that transfers any RMS-11 disk file
to another disk or a magnetic tape in a special format that
cannot be read or modified by a user program.

•

RMSCNV, a file conversion utility that moves records between
two RMS-11 files of any organization or record format.

RMSDEF, a file definition utility that creates RMS-11 files,
• defining
their attributes
in an interactive sequence of
questions and requests for data.

1-18

INTRODUCTION

•

RMSDSP,
a display utility that lists the
RMS-11
file
attributes and structural data or the names of RMS-11 backup
files on magnetic tape.

•

RMSIFL, an indexed file load utility that builds an RMS-11
indexed file using records from another RMS-11 file of any
organization.

•

RMSRST, a file restoration utility that reads the backup files
created by the RMSBCK utility and restores them with form,
structure, content, and attributes identical to the original
files.

The RMSDEF utility is an interactive utility.
That is,
it performs
its functions in response to a sequence of questions and requests for
data.
The remaining utilities are command utilities that operate by
means of command strings input from the user's terminal.
For descriptions of other useful and important system tasks,
following manuals:

1.6.l

see

the

•

RSX-llM or M-PLUS System Generation and Installation Guide - a
description of the process of tailoring a
systern--to a
particular installation.

•

RSX-llM/M-PLUS MCR Operations Manual - a description of MCR
plus many details on system startup procedures and system
operations, and a full description of the
Indirect Command
Processor.

•

RSX-llM/M-PLUS Batch and Queue Operations
Manual
a
description of the Queue Manager, which controls the orderly
printing of files and other output, and the batch processing
subsystem, a means of automatic use of the system.
Batch
processing is available on RSX-llM-PLUS systems only.

•

EDT Editor Manual - describes the use of EDT, the DEC Standard
editor.
The manual includes an introduction to EDT.

•

RSX-llM/M-PLUS Guide to Program Development
a detailed
introduction t~e program development facilities, both DCL
and MCR, of RSX-llM/M-PLUS.

•

IAS/RSX-11 MACR0-11 Programmer's Reference Manual
an
introduction to the MACR0-11 Assembly Language and Assembler.

•

RSX-llM/M-PLUS Task Builder Manual - a description of the task
building, or linking, process in RSX-llM/M-PLUS.

RSX-llM/M-PLUS DCL and VAX/VMS DCL

DCL on RSX-llM V4.l and RSX-llM-PLUS V2.l and subsequent releases
is
designed to be compatible with DCL on VAX/VMS V3.
If the ~unction
being performed is identical, the same DCL command will have the same
effect on an RSX-llM/M-PLUS system or a VAX/VMS system.
As other
operating systems adopt DCL, the same will be true for them.
In most cases, the default forms of DCL commands will have the same
effect on either kind of system.
Furthermore, many qualifiers are the
same and also have the same effect.

1-19

INTRODUCTION

On the other hand, operating systems that implement DCL,
including
RSX-llM and RSX-llM-PLUS, will have system-specific extensions to DCL.
For example, RSX-llM/M-PLUS systems have several
features
not
available on VMS systems;
DCL commands have been implemented to
invoke these features.
The command syntax for these features
is
different from any VMS command syntax to avoid confusion.
In addition, many of the features discussed
in this chapter are
RSX-llM/M-PLUS extensions to the basic DCL language. Prompts, HELP,
error messages,
system displays,
and command parsing
{including
abbreviating)
are unique to RSX-llM/M-PLUS and may not be fully
compatible with other DCL implementations.
NOTE

All the short forms and abbreviations in
DCL are intended for the convenience of
interactive users at terminals.
You
should
not
use either these brief
command forms,
or other abbreviations
shorter than four characters per command
element, in indirect command files or
any
other
permanent form.
As new
commands are added
to
DCL,
these
abbreviations
may
change,
but the
full-format commands are stable.

1-20

CHAPTER 2
THE SET AND SHOW COMMANDS

The SET commands dynamically alter system characteristics.
commands display system characteristics.

The

SHOW

These commands affect every part of the operating system.
Some of
them are needed by every user every day.
Others might not be used
once in a year.
SET and SHOW both prompt
Function?
There are more than 20 functions that can be altered or established
with the SET command, and more than 20 others, not all of them the
same, that can be displayed with the SHOW command. Most of the SET
functions include options, values, or negations.
Customarily, the SET or SHOW command and the function are considered
to form a single command.
That is,
rather than speaking of the
TERMINAL function of the SHOW command, you would
refer to the SHOW
TERMINAL command.
Some of the most commonly used variations on the SET and SHOW commands
are described for your convenience in Sections 2.1 through 2.12.
Full descriptions of all the SET and SHOW command functions appear
later in this manual.
Each chapter concludes with the SET and SHOW
commands appropriate to that chapter. Thus, SET and SHOW TERMINAL are
described at the end of Chapter 3, Terminal Operations, and SET and
SHOW DEVICES are described at the end of Chapter 5,
Handling Devices
and Volumes.
See the Table of Contents for references.
The following are the most commonly used SET and SHOW commands,
described here in brief form for your convenience.
All of these
commands are described in detail elsewhere in this manual.

2.1

SET ~.ND SHOW TIME
SET [DAY]TIME [hh:mm[:ss]]

dd-mmm-yy
mm/dd/yy

You can set both the time and the date with this privileged command.
You can enter the date
in either form, for example, 04-JUL-76, or
7/4/76.
In the latter case, mn stands for month number.
No matter
how you enter the date, it will be displayed in the first form.
See Section 8.1.1.

2-1

THE SET AND SHOW COMMANDS

SHOW [DAY]TIME
This command displays the current setting of the day and time on
system.

your

See Section 8.1.2.

2.2

SHOW MEMORY

SHOW MEMORY
This command brings up the RMD display, which provides information on
task activity,
partitions, drivers, CPU usage, and so forth on your
system.
On video terminals, this display is dynamic.
On hard-copy
the command prints a snapshot of the current RMD display.

terminals,

The display provides a rough picture of the current state of the
system.
Alternate displays include the Active Task List or a single
task header.
Not all systems
include this command for
interactive use.
Most
systems, however, do run the display on a slaved video terminal
somewhere near the computer.
See Section 8.1.9 for more information on the memory display.
See
Section 7.12.3 for more information on the task list and task header
displays.

2.3

SET AND SHOW TERMINAL

You can set and display many attributes of your terminal.

The command

SHOW TERMINAL
without any qualifier, displays the current setting
attributes of the terminal, as shown:
TT5:
CLI
LINES
LOWER
ECHO

[303,5)
DCL
BUF
66.
TERM
NOPRIV NOHOLD
NOVFILL NOHHT

(303,5)
132.
HF ILL
LA34
OWNER
NOS LAVE
NOE SC
NOFDX
WRAP

NONE
NOC RT
NOR PA

The display is explained in full in Section 3.8.2.
the more significant fields:

all

settable

SPEED=(300:300)
BRO
NO AB AUD
HFF
NOR EMOTE
NOEBC
TYPEAHEAD

Here, briefly, are

Terminal number, login UIC, default UFD
CLI
BUF
SPEED
LINES
TERM
OWNER
BRO
NOPRIV

Current CLI setting
Buffer-length, that is, the width in columns
Transmit and receive speed
Page length in lines
Terminal model
Tells whether terminal has been allocated
Terminal can receive broadcast messages
Terminal is not privileged

The SET TERMINAL command permits you to set ~ost of
these attributes
for
your
terminal.
Privileged users can set the attributes of any
terminal.
2-2

THE SET AND SHOW COMMANDS

The format of the SET TERMINAL command is:
SET TERMINAL/attribute[/attribute[s]]
Note that you can set more than one attribute at a
such as the following:

time.

command

>SET TERMINAL/VT100/LOWERCASE/DCL
is accepted by the system and executed.
Here is a summary of the most important attributes you can set:
/DCL
/PAGE LENGTH:n
/[NO]BROADCAST

/MCR
/WIDTH
/[NO]PRIVILEGE

/UPPERCASE
/LOWERCASE
/SPEED: (transmit,receive)
/SCOPE
/HARD_COPY

You can also set your terminal as a particular model:
/ASR33
/ASR35
/KSR33
/LA12
/LA30P
/LA30S
/LA34
See Section
attributes.

2.4

3.8

for

/VT102
/VT105
/VT125
/VT131
/VT132

/VT05
/VT50
/VT52
/VT55
/VT61
/VTlOO
/VTlOl

/LA36
/LA38
/LAlOO
/LA120
/LA180S
/RT02
/RT02C

information

the

meaning

these

SHOW DEVICES

SHOW DEVICES
This command displays the name and other information for
known to the system.

all

devices

SHOW DEVICES dd:
This command displays the name and other information for all devices
of a particular type known to the system, where dd is the 2-letter
mnemonic for the device type or pseudo-device type.
See Section
5.10.3.

2.5

SHOW QUEUE

This command displays information about the queue file maintained
the Queue Manager.
Two forms of this command are most useful.

SHOW QUEUE
This command displays information about all jobs in all queues.
In
addition to showing all queue assignments, the information display
includes all Queue Manager QMG jobs and all files
included in those
jobs.

on RSX-llM--PLUS systems,. this a·isplay includes bat~h q~eues as well as
print queues.

2-3

THE SET AND SHOW COMMANDS
SHOW QUEUE/FULL
This command displays full information about all jobs in all queues.
SHOW
In
addition to
the
information displayed by SHOW QUEUE,
in the
QUEUE/FULL displays all the attributes of all
the QMG jobs
queue, such as /FORMS, /COPIES, and /PAGE_LENGTH.
See the RSX-llM/M-PLUS Batch and Queue
information on the SHOW QUEUE commands.

2.5.1

Operations

Manual

for

SHOW PROCESSOR
SHOW processortype processorname[/qualifier[s]]

where processortype is one of the following:
BATCH
CARD READER
DEVICE
INPUT
PRINTER
PROCESSOR
This command displays
information about the card
readers, batch
processors, printers, and other devices under the control of the Queue
Manager.
CARD READER and INPUT are synonyms.
DEVICE refers
to all
nonbatch
output processors and is a synonym for PRINTER.
BATCH refers to all
batch processors.
(Batch
processing
is
available
only
on
RSX-llM-PLUS.)

A simple SHOW PROCESSOR command displays all processors in the system.
See the RSX-llM/M-PLUS Batch and
information.

2.6

Queue

Operations

Manual

for

SHOW ASSIGNMENTS
SHOW ASSIGNMENTS[:ttnn:]

This command displays at
logical-device assignments.

2.7

your
terminal all
See Section 5.10.1.

local

and

SET AND SHOW DEFAULTS
SET DEFAULT: [ddnn:] [g ,m]

where
dd
The 2-letter device mnemonic
nn
The 1- or 2-digit device number terminated by a colon

2-4

THE SET AND SHOW COMMANDS
[g ,m]

The UFD is two octal numbers separated by a comma and enclosed
in brackets.
This command alters your default settings for
Directory {UFD) •

device

and

User

File

The default device name and UFD are included automatically in every
filespec included in a command unless overridden. See Section 4.5.1.
SHOW DEFAULT
This command displays
Section 4.5.2.

2.8

your

current

default

device

and

UFD.

See

system.

Four

SHOW TASKS

This command displays information about tasks
forms of the command are most useful.

the

SHOW TASKS/ACTIVE
This command displays information
terminal.

about

the

tasks

active

your

about

all

tasks

active

the

installed

SHOW TASKS/ACTIVE/ALL
This command displays
system.

information

SHOW TASKS/INSTALLED
This command displays full information about all
the system.

tasks

SHOW TASKS/ACTIVE FULL taskname
or
SHOW TASKS/INSTALLED FULL taskname
These commands
installed task.

2.9

display full
information
See Section 7.12.5.

single

active

UIC

SHOW USERS
SHOW USERS

On RSX-llM, this command displays the terminal number
for each logged-in terminal.
On RSX-llM-PLUS systems
displays the terminal
terminal.

and

without Resource Accounting, this command
number and login UIC for each logged-in

On RSX-llM-PLUS systems with Resource Accounting, this command also
displays for each logged-in terminal the default UFO, the date and
time of logging in, the number of currently active tasks, and the
user's name.
See Section 8.1.8 for more information.

2-5

THE SET AND SHOW COMMANDS

2.10

SET PROTECTION

SET PROTECTION filespec[s]
Protection?
(SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R)
This command alters the access protection of a file or files.
If you
wish to protect more than one file, the filespecs must be separated by
commas.
There are four kinds of access to files and four classes of users who
may access files.
The previous example shows the the code for the
default protection used on the system.
The four classes of users who may access files are:
SYSTEM

Privileged users and the operating system itself

OWNER

Users logged in under the same User Identification
{UIC) the file was created under

Code

GROUP

Users logged in under the same group number as
the file was created under

the

UIC

WORLD

All other users

READ access.
The file can be typed, printed, copied, run
a task image), and so on.

(if

WRITE access.

The file can be written to or altered.

EXTEND access.

The file size can be changed.

DELETE access.

The file can be deleted.

The four kinds of access to files are:

These kinds of access are in hierarchical order.
This means
if you
grant Delete access to a class of user, you are granting Read, Write
and Extend access as well.
The protection status shown at the beginning of this section
default protection status accorded every file on the system.
PROTECTION to change the protection status of files.

is the
Use SET

You must enter the class of user and the type of access
in the form
shown.
If you do not wish to change the access rights of a particular
class of user, simply leave that class out.
All users can set the protection of their own files.
Privileged users
can set the protection of any file.
Note that you can set the
protection of a file so no user, including yourself, can do anything
with the file.
If you do this, you will need a privileged user to
reset the protection when you wish to use the file.
You can display the protection of a file with
and /FULL qualifier.
See Section 4.5.3.

2.11

the

DIRECTORY

command

SET AND SHOW SYSTEM/DIRECTORY AND LIBRARY/DIRECTORY

The Executive, privileged system tasks, and other system files
are
kept
together in a single User File Directory (UFD) called the System
UFD.
In most cases, this will be UFD f3,54) on the system disk.
An

2-6

CHAPTER 3
TERMINAL OPERATIONS

The terminal is your main channel of communication with the computer
system.
The information in this chapter tells you how to use a
terminal to communicate and interface
with
the
RSX-llM
and
RSX-llM-PLUS
Operating
Systems.
For a quick review of basic
operations at a terminal, refer to the Introduction to RSX-llM and
RSX-HM-PLUS.
The discussions in this chapter are organized around three DIGITAL
terminals:
the LA36 hard-copy terminal (DECwriter II) and the VT52
and VTlOO video display terminals (DECscopes) • These terminals do not
always behave in exactly the same way; variations are noted in the
descriptions of terminal functions in this chapter.
If you are using
another type of terminal, check with your system manager for special
instructions.
In any case, you should read the manual shipped with
your terminal to get full use of your terminal on the system.
A typical terminal keyboard is shown in Figure 3-1. A keyboard
is a
set of alphanumeric keys,
similar to the set on a typewriter.
The
keypad shown in the illustration is a set of special keys.
Where
pertinent, the functions of these keys will be explained in this
chapter. All terminals will have some form of a keyboard;
some
terminals will not have the keypad.

rammmmmmmmmmn- rnn
BltSJBBBBBtSJBBBB8S

BACK

rr:l nnn~.

SPACED

0~08
I

ZK-1157-82

Figure 3-1

Terminal Keyboard and Keypad

Each terminal on an RSX-llM/M-PLUS system has a number.
Your terminal
number
is displayed when you log in.
Your terminal number is also
used by the system to identify tasks run from your terminal.
(See
Section 7.1.1 for more information on task naming.)

3-1

TERMINAL OPERATIONS
You can set many characteristics for your terminal using the SET
TERMINAL
command
(Section 3.8.1).
The characteristics of your
terminal can be displayed with the SHOW TERMINAL command
(Section
3.8.2).
In addition, the SHOW USERS command (Section 8.1.8) displays
the terminal number, default UFD, and login UIC for each logged-in
user.

::··'Onr. ;Rsx:~11:1f:t.;S.PI:us ~,f~·y:$ tem:~i l<~ttlj)/R~s· qurc.e Accounting
1

.·:a_):,s,q' · ·<;i;i;,sp);g:tys· ...:i:t.he • u~~.r;·~ .~ ~/Jiaiµe·.· ··.aria·
',·; ';(:?;~~~>~:.:~/;

'·\

~ ,v,.,~;~~

,• ;··=~ '2.·;

·'. ; )

~a,!.ct·i·ve , .. .SHOW. .•. usEf'Rs·

the. number ,of pur~e·Il,·tly:·.~pt:iye·.
\ ' '

Frequently, users work from more than one terminal.
You can always
use the pseudo-device name TI:
to refer to the terminal you are
currently using.
You do not need a specific number.
In most cases,
when a system task requires you to name an output file, you can
specify TI: and the output will be printed on your terminal.
A terminal is said to be attached if all
its
input and output is
directed to or from a task.
If you invoke a task, it may attach your
terminal so that no other task can use the terminal for I/O. When you
exit
(for example by typing CTRL/Z), the task detaches the terminal.
When you are using an editor, the editor has your terminal attached.
Terminals may also be dedicated exclusively to a task. Such terminals
are called slaved terminals.
Tasks can slave terminals, or terminals
can be set slaved through the SET TERMINAL command.
Terminals can
also be set slaved on logging in.
Slaved terminals can communicate
only with tasks soliciting input from the terminal.

3.1

LOGGING IN AND LOGGING OUT

Your terminal must be connected to the system hardware and the system
software before you can use it.
You can assume it is connected to the
hardware.
Connecting to the software is
called
logging
in;
disconnecting from the software is called logging out.
Logging in informs the system that you will be using a terminal.
Logging out informs the system that you are through using a terminal.
Most terminals
power to the
is logged in.
remains logged

have an accessible on-off switch.
This switch supplies
terminal, but it has no bearing on whether the terminal
If you turn the power switch off, a logged-in terminal
in.

You can test whether a terminal is turned on and available by pressing
RETURN or CTRL/C.
The RETURN key causes the right-angle-bracket
prompt (>) to appear.
The CTRL/C causes the explicit prompt (DCL> or
MCR>) to appear.
The SHOW DEFAULTS command tells you whether the terminal is logged
in
or not.
If it is not logged
in,
the command produces an error
message.
If it is logged in, the command displays the current default
device and UFD.
If the terminal is already logged in, you should type CTRL/C to
determine whether the terminal is set to DCL or MCR.
If the terminal
is set to MCR, type in ACT as shown:

MCR>ACT
If the terminal is set to DCL, type in SHOW TASKS/ACTIVE as shown:

DCL>SHOW TASKS/ACTIVE

3-2

TERMINAL OPERATIONS

LOGIN
This command will inform you whether the terminal is in active use or
not.
It is not good practice to take over a terminal while another
user has tasks (other than CLis) active at the terminal, as you may
interfere with the other user's work.
Check also with SHOW DEVICES to
see if the other user has devices allocated or volumes mounted.
If
the other user has no significant activity under way, use your own
judgment as to whether you should log the other user out, using either
DCL>LOGOUT

MCR>BYE
and, after the terminal is logged out, log yourself in.
If you are not sure how to log in, type HELP for help in logging in.
If the terminal is not logged in, you may log in.
Unlogged-in
terminals are not set to either DCL or MCR.
You can log in to an
RSX-llM/M-PLUS multiuser protection system using either HELLO or LOGIN
together with your User Identification Code and your password.
The
system's Account File Maintenance Program (ACNT) identifies each user
as either a DCL or MCR user and sets the terminal accordingly.
See
the description of LOGIN {Section 3.1.1) for
further
information on
the effects of logging in.
Remember, you can change the CLI of your terminal from DCL to
vice versa with the following commands:

MCR

MCR>SET /DCL==TI:

DCL>SET TERMINAL/MCR
All RSX-llM/M-PLUS systems with DCL are multiuser protection systems.
This means that the system includes features, such as LOGIN and LOGOUT
and ALLOCATE (Section 5.4), that enable many users to use the system
without interfering with each other's work.

3 .1.1

LOGIN grants access from a terminal to a multiuser protection system.
LOGIN also establishes certain characteristics of your terminal
session.

Format
LOG [IN]
user id
Password:

password

3-3

TERMINAL OPERATIONS

LOGIN (Cont.)
Parameters
user id
Specifies the User Identification Code (UIC) of the user
in.
Five forms of UIC are accepted by this command:

logging

[g ,m]

g ,m
[ g/m]
g/m
name

If you log in with a comma in the UIC, or if you log in by name,
a
file called LBO: [l,2]LOGIN.TXT is printed on your terminal.
This file is prepared by your system manager and usually contains
information about the system and other announcements.
If your
system displays such messages, using a slash
(/)
instead of a
comma
(,)
between the group and member numbers suppresses these
messages.
Your system may also have a
file called LBO: [l,2]SYSLOGIN.CMD.
This file can contain a number of system-level commands that your
system manager wishes to have executed each time a user logs in.
Finally, you, as an individual user, can prepare a file called
LOGIN.CMD to be kept in your UFO (User File Directory) to be
executed each time you log in.
This LOGIN.CMD file usually
includes commands for setting 11p the terminal and the account for
regular use.
The LOGIN command interacts with the Account File Maintenance
Program
(ACNT)
to establish a number of characteristics of the
terminal session you are beginning.
These include your default
device
(where your files are located), an indication of whether
your account is privileged or not, and whether your terminal
is
to remain slaved after login.
See your system manager for
information on how this will affect you.
password
Your password is limited to six Radix-50 characters.
If you
enter your password in response to the Password: prompt, your
password is not echoed on the screen.
If you type in your
password on the same line as your UIC, the password is echoed.
Your password is established by your system manager as part of
setting up your account.
Examples
>LOG IM
f.icccllmt or name:

KAF~J~

Pa!.'>S~;1ot'd:

RSX-11M-PLUS V02 BL15 Multiuser [3,54] S~stem
20-Nov-82 09:16 Lossed on Terminal TT54!
Good

Mornins

November 20, 1982

S~stem

3-4

Manaser

TERMINAL OPERATIONS

** SYstem will be down tonisht from 21:00 to 24!00 **
** DISK-TO-DISK BACKUPS **
P 1 ease Pu r9e

~our

f i 1 es! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !

November 1, 1982

0Perator

MastaPe drive MM1: is down until further notice.

In this example, full login text is automatically printed on the
terminal because the user
logged in with a name (KAFKA).
The
full login text is also printed if you log in with a UIC entered
with a comma [g,m].
See next example.
The prompt signifies the completion of logging

iu.

>LOGIN 303/5
Passwor·dt

RSX-11M-PLUS V02 BL15 Multiuser [3,54J S~stem
20-NOV-82 09:18 Logsed on Terminal TT56!
Good Mornins

November 20, 1982

S'::lstem Manaser

** Ssstem will be down tonisht from 21!00 to 24!00 **
** DISK-TO-DISK BACKUPS **
Please Purse sour files!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

>
This example shows the
UIC was entered with a
LOGIN.TXT file in full
message
(defined as
manager) was printed.
the first
login of
habitually log in with
example.

first login of the day for this user.
The
slash (303/5) .
The printing of the system
was therefore suppressed.
Only the first
being a priority message by the system
The priority message is printed only on
the day.
This ensures that users who
the slash do not miss anything.
See next

>LOGIN 303/5

RSX-11M-PLUS V02 BL15 Multiuser [3,54] S'::lstem
20-NOV-82 10:36 Lossed on Terminal TT54:
Good Mornins

>
This example shows a subsequent login on the same day by the same
user.
Note that no system messages are displayed.

3-5

TERMINAL OPERATIONS

Password:
RSX-11M-PLUS V02 BL15 Multiuser [3,54] Swstem
20-NOV-82 19:36 Lo~sed on Terminal TT45:

Good Evenins
>@LOGIN.CMD

>SET TERMINAL/LOWER
>ASSIGN RS:

DBi!

>@<EOF>

>
This user has prepared a LOGIN.CMD file in his UFO to set up the
terminal
and make a logical assignment.
The LOGIN.CMD file is
run automatically each time the user logs in.
The commands shown
are
issued by the indirect command file;
the @<EOF> marks the
end of the command file.
Notes
LOGIN and HELLO are identical.
without DCL, however.

work

systems

LOGOUT counteracts LOGIN.
Once you arc legged in and the system display has been printed on
your
terminal,
the system searches the User File Directory you
logged in to for a file named LOGIN.CMD.
This
indirect command
file can contain any commands you wish.
This feature is commonly
used to set up your terminal for regular use,
as shown
in
the
example.
See the RSX-llM/M-PLUS MCR Operations Manual for more
information on indirect command files.
It is wise to log in occasionally without the slash
you have not missed any important messages.

sure

account

file

for

Error Messages
MCR
DCL

Not logged in
Not logged in
Explanation:

The terminal is not logged in.

User Action:

LOG -- Account file open failure
Explanation:
some reason.

The system could not access the

User Action:
Try again.
Wait and try
recurs, see your system manager.

3-6

again.

the

message

TERMINAL OPERATIONS

LOGOUT
LOG -- Invalid account
Explanation1
The name or UIC, or the password,
command is not recorded in the account file.
User Action:

given

the

Retype the command using correct data.

LOG -- Logins are disabled
Explanation:
The system is being shut down, or a privileged user
has issued SET NOLOGINS for some other reasone
You cannot log in. Try again later.
Often, when
user Action:
the operator sends a message to all
logins are enabled again,
terminals.
LOG -- Other user logged on
Explanation:
Another user is logged in.
can log in on a terminal.

Only one user at a time

User Action:
Issue SHOW USERS to find out who is logged
in.
Issue SHOW TASKS ACTIVE to find out what tasks are active on the
terminal.
At your discretion, issue LOGOUT and then log yourself
in.
LOG -- Terminal allocated to other user
Explanation:
The terminal has been allocated (made private)
another user.
You cannot log in on an allocated terminal.

User Action:
Go to another terminal.
Issue SHOW DEVICES
and find out which terminal has your terminal allocated.

TT:

3.1.2

LOGOUT

LOGOUT logs the user off a multiuser protection system.
LOGOUT also aborts any active nonprivileged tasks running
from the
terminal as well as dismounting any private volumes and deallocating
any private devices allocated from the terminal.
Format
LO(GOUT] (/HOLD]
No prompts.
Command Qualifier
/[NO]HOLD
The /HOLD qualifier
is for use on remote or DECnet host
terminals.
If you include the qualifier, the terminal is logged
out but the line is not hung up.
This means you can log back in
without reconnecting the line.
The default is /NOHOLDr meaning
that when you log out, the line is also hung up.

3-7

TERMINAL OPERATIONS

LOGOUT (Cont.)
Examples

>LOGOUT
Have a Sood afternoon
04-NOV-82

12:13

TTl~I

Lossed off. ZENITH

In this example, the user logged off an RSX-llM system.
The
terminal
is free for .logging in.
ZENITH is a DECnet node name.
This information does not appear on systems without DECnet
support.

>LOGOUT
C:on.nec,t tfme::
44
m;inu;tes
CPU JIME. USE.Ii:t; . 25'6 ~e:corrds
Task tot a U.
90
Hav.e
s.od,q ;a::f 'tl~rnqon

OB:-SEP-82 ,16:t:5!S TTtO:

Lostsed of~ PRIN~E
:

In this e:xample·, the. user logg.ed o/f: an Ri~x;-.,1·1M-P~US ;sys:tem.
The
info.rma:tton on . sys.t~. ·use' is . n;o:t. Pr'.in;te<:t on ~y~tems; wi:thout
Resource ,Accounting: runni;ng. Tp;e: ::~e:rmina;l, . i:s f'.cee. ;:f.qr · .L<agging
in. (.ie.RU~C:E is.,.,, P: .QECn~t :OAde,.. ,OICml,e.)

>LOGOUT
DMD -- TTlO: Dismounted from DXO:
Connect time:
32 minutes
CPU time u5ed:
12 seconds
Task total:
21
Have a Sood rnornin~
08-SEP-82 11:17 TTlO: Logged off ROMPER
In this example, the user had a volume mounted on device DXO:.
The LOGOUT command dismounted the volume, as the message states.
If the device was allocated, the LOGOUT command will deallocate
it, but will not issue a message.

>LOGOUT
13:29:36

Task •TTlO
• Terminated
Aborted via directive or CLI

Have a Sood afternoon
19-NOV-82 13t13 TT10:

Lossed off

In this example, the user had a task running from the terminal at
the time the LOGOUT command was issued.
The command caused the
task to be aborted.

Notes
LOGIN counteracts LOGOUT.

You need type only LO to log out.

The LOGOUT command works only on terminals set to DCL.
If the
terminal
is set to MCR, use the BYE command.
Type a CTRL/C to
find out which CLI the terminal is set to.

3-8

TERMINAL OPERATIONS

·sHow· 'ACCOUNTING.
3.1.3

ACNT, the Account File Maintenance Program

Account files on RSX-llM and RSX-llM-PLUS are created and maintained
by ACNT, the Account File Maintenance Program. Whenever a user tries
to log in, the system checks the user identification and the password
against the account file to determine whether the user should be
allowed access to the system, and with what privileges.
The account file describes all the UICs and associated passwords that
have been authorized for a multiuser protection system. ACNT also
associates a CLI (usually DCL or MCR) and a default device with each
user.
Privileged users have full
access to the functions of ACNT, as
described
in
the
RSX-llM/M-PLUS
System
Management
Guide.
Nonprivileged users can change their password with ACNT if Resource
Accounting is active on the system
(see the RSX-llM/M-PLUS MCR
Operations Manual for more information)
but should see the system
manager to change other aspects of their account.
You should not confuse ACNT
described in Section 3.1.4.

with

Resource

Accounting,

which

::3. :1•4 , Resource ·Account.in? . . on RSX:-1 llif:-PLOS
RSX-.llM-PLUS
systems
inclu<Je
· :Resour,ce
Accounting
as
a
system.;.generatfon option that provides a file' of information on system
use •. Data is gathe.red both. for .the · individual user and for
the
. system,.:.·

When yoq lqg ·in:·, a.ftei:;' LO.GI!N chec$'s ·",.:the ;vaJ.l:d;i:ty : ·of-: your utc and
,passworq , .. Resour~e .. Accounting. ·a:ssigns. ~. number .:to . the te;mina1
s~s·s,io,n,.~ .. This numJ?.er. can
optfo~ally .in:cl,.ud~
1;.. to : 3~chatacter
personal. iO.:mtHTer ~ . 'r}lus, each •..t;,ime. ,you fog .. in, · tbe terminal .. sess.ion
is iden.tif.ied, by. the number .ah~.· the· persona1 .~dentffier •.. If you are.
logged ·in on· two .. terminals ·at once, ·each· session has a· different
n,umb~r but the sa.me· .Perso.nc:fl, .identifier,..
'

·:.a ..

When you lo<J out, . R<:;source. Accounting di~p.lays the time
logged in,, the CPU time used, and the n.umb.er pf· .. tasks used.

you

were

Users can also display current Resource Accounting data with the
command SHOW ACCOUNTING/INFORMATION., describ~d .in .the next section.·
The data gathered by Resource. Accounting
individu_a:l

users

for

th.e

system

makes

resou·rces

possible

billing·

us·ea and measurement of

overall system usage.

Fo·r further information on Res·ource Accounbi ng·, see the RSX-llM/M-PLUS
System Management Guide.

3.1.4.1

SHOW ACCOUNTING/INFORMATION

SHOW ACCOUNTING/INFORMATION displays current information on terminal
session.
Privileged users can display this information for any
terminal session.
Nonprivileged users can display information about
their own terminal sessions.
3-9

TERMINAL OPERATIONS

''SHp,vit:·'.~·CQplitt·r,N,a ··<~on.t.r
;. . ~

1 '!

'{[~?~~:;:/'
,'.~: '_,\\:

;

. . ,,, ' /~~'·qwi/"i; ;';:.; . ;, ,' ' ; ,' .:-. ,/' ' "; ' " ., ..: ,: .

;

, • •;;

•

J ';

; ,~:\;(,

p,~_n_.c~tJ F>n~?.: <.,.,licc.p.;q~T,:It~.~:, '. · .r-:, :=-? /'

,~·t;·_~<;';i"

~)'_=«'.°"/-':'<

• ·':";·<· •· • .··.Att,r~1:h~:e.e?: ·~.~:t~~?:t~~t9N'/f
,'1 -~~ <~, .~'(l·'.

·.*':'

:_~~'.·_,.,·::1,;'"'.';;,' ,·,,,~ . /·

..- ~" ,~

t:.tnn;f

<. _:;:~

'"_; ..· ~:<

,:;·,_..

'0., .= ,; ..

."/;i .' }• \,'. ./,' .:·'. t,;S'H6W:'..:~cc9.qN·~IN.G%'r'N·F'OR~f~~lQ.N
[ d~:11·n:.:] .: '
*.
:·
+ ,, . , .' :
}·~

~~~' ~

~. ~/

~i ;'· .. ,

' :- ;"' /

:= '""';

,« . '.·' ~ "'. "' . ,-·· . ~ '~ ;' ;,, . :····

.. : '.

,:.

...-~~

.~ , ;

<' .,. .

.; '

,;i,,,.+

:J?airametei/

~,·

;~:'., ~ ~-' ~'',_~·~'

. ,Sp~d. ·fte·~·· the:· te+itd.t~fal :'f~r ,i.,n/~h· accbuntiri:g inf·o.rmation· ds· t6
'

.oe",

sh(:)wn:'~' .....' Pr.iv11e:~e.d·' · .u·~ers'.; ca.n .displi;iy in,:t:;orrn·a.tion:. for
any
, '·te,rrnt~~l •.· ·.Nonp'r'i vileged u:$ers· can only display information about·

tb''e. t·ermi n~l ~h"ec'Y ,{3;:;-e logged in ,'()n.

'Pri~i.le~·ed users can· specify' CO:

in this field to· display data
for. syste.m tas.ks running on pseudo .device CO: on their terminal.

Privileged users can specify SYS for this
current system totals on their terminal.

field

display

The default for this field is TI:.
Exa:ntple

>SHOW ACCOUNTING/INFORMATION

USER - KENNEDY
T
SESSlON ID =
WRT751
TI: ~ VT3:
ACCOUNT = o.
LOGON urc ::: (303, 5J
LOGGED ON ::: 26,,-JUN-82 09: 51: 29
LOGGED OFF - 00-000-00 00100100
BILLING STOPPED = 00-000-00 00:00:00
CPU ~ 15.
TASKS ACTIVE = 2.
TASKS RUN = 5.
DIRECTIVES = 77.

QIOS

= 25.

'>·

>SHOW TIME.

09:52:21 26-JUN,,-82
},'

' >SHOW,' ACCO,UNTINGIINFORM.ATION
US.ER ~ . KENNEDY

T·

''ses. srON·'.in =· '. WRT751
'LOG'ON. u1c. := '(303,5,J"
"" ' LO.GGE{1. ' OFF

CPU ·:::: ..... 38 :.. ~
.,;DIR.ECT .IVES..

TI: ; ; VT3:

ACCOUNT = o.
LOG{J'E[I ON = 26-JUN~B2 0·9:5u'29

= ()()·•000..:..,()0 00 roo:.o.O . · .· ' Bl,LLl~G S,lOPF'ED" = oo-ooo~op
. · . ·. : " ::TAS.1-;S ACTIVE, ~ 2t
TASKS RUN = 9.•.
14~h

O<U.,0.0: 09

tlIOS';;. 58·.
0

'rn', this ',exampl~·, .the display identifies the user,

including the
sessJon ID and .. the terminal.. The' :ACCOUNT number is not used. In..:
ad~itiqnr the qis.play ... shows .the J.og.inUIC a,nd the time of logging .
in.. . . Sin,ce ,th"e command was issued while the terminal se.ssion.
· :d:>ntinued, .,the ttme of ioggrng o.f.f and the e'nd of billing is not.·
··sh(iwn·•. · (The' times of logging... off and the end of billing may not ·

3-10

TERMINAL OPERATIONS

ti'cR, ,ts%'<le:fij{n,ed··a.t» 'stst,em .> ,<Jenerat:t,oo,·•·· .. · .. ,~,n .'.·mos.t:"'
· ,· ,' cas;es .;.... ·.'·t'he·,, <t eng tib · ~ · of .·<a·:..:· ..ti·¢}(:«; is' . ~e;tetini n.eo· . . by:...y()'l;lr.·' loqaL,/~ i·ne:.,·

, , , ,' ,+~e0' ,Iengtb ,of

:~tµ,~~~~~~£~~;f~~~~1~t:~;{f~~:~[~~=t~i:~~;~~~c:~-

J . .•

;:.,·,~:·'~if~.1d':rrig/·~,/'t;i'ck/,j,·engtfr··o'f.",·l:/S{Jtfr'>o:r·:a
. .·'seconcf;:
· ·some<'<fns:t'aJ:!at,tohs;':·
,;4'
f. >\. .,' ~, ~. ·,~: <~ '~
/* ,, / ~ ,,'
~
,,,= " ,;
·i·~· ~
.~
~-~
/~'
,:<", .t may,.... l''~c,l.lJde:' •a,.pr()grammap!e" .clock•, ,"l!he .. tlcl<.' length, .lS ,:v,,~·171a,bl,e' ''OD:'
'.>// ,,:·:Sy;~.t.enrs,~: ·wl:ttr.·· ,:a;·.:p.r:0,g:ratnnt;a.ble,: . cl'()C)~.,. .: See..·your, syst:em . ,m.ariagst"'
·
/'' ...l.i .>

'{.>.

•

.,.

''-

.: ,

:'·

,.:

'..:o

·;

·"'

»'

:~i~x::~>r.~:~;d+~e/>'.~;ri,~.·?]=~}~·9P:ftl:~·:: " ~ .: :

3.2

.•. :

,,. c

•. " '.

:·

/' . ;'

, " .,

•

;

··'

. ,,'.'· i"

.·

·, '·

. • ::;:

;'·

;' ....

THE KEYBOARD

Most of the keys on the main keyboard are self-explanatory.
They
function much the same as they do on a typewriter. Only the most
important differences from typewriter operation are noted here.
See
Table 3-1 for the names of keyboard characters as used in system
documentation.
You should remember that a computer terminal is not a typewriter.
A
computer terminal has two functions, transmitting input to the
computer and receiving output from the computer.
Usually, when you
press a key, the letter appears immediately on your terminal. When
you pressed the key, you sent a character to some system task or
program.
One of the actions the system normally takes upon receiving
a character is to send it back to your terminal as an echo.
This
usually happens so fast that it appears that you are typing on your
terminal, but you are not. You are sending input to the system and it
is sending output to your terminal. A terminal is an input/output
device.
Occasionally, when heavy demands are being made on the system,
may be a noticeable lag between the input and the echo.

there

You should also remember that keys may behave differently when sending
output to some task other than DCL. For instance, all the keypad
keys, plus the ENTER, BACK SPACE and LINE FEED keys, have special
meanings
when
you are running EDT, the DEC Editor.
Special
applications software at your installation may also use special
meanings for certain keys. This chapter covers key use for DCL, also
called monitor level.

3-11

TERMINAL OPERATIONS
RETURN and Command Line Length

3.2.1

The RETURN key has two functions.
It is used in the conventional way
to supply a line feed and a carriage return, but the key is also used
to signal the system that you have finished
typing a command.
Commands can be quite varied in length;
the RETURN key defines the
length of the command.
The symbol <RET> is used
in this manual to
signify that you press the RETURN key.
Thus,
>PRINT IZZY+TXT

IBIB

is a complete command, and so is
>PRINT /COPIES: 2/FORM ! 1./DELETE IZZY. TXT

00)

If you must enter a command that is longer than a single line on your
terminal, you can override the effect of the RETURN key by ending the
line with a hyphen before pressing the RETURN key.
This works as
follows:
>PRINT/COF'IES!2/FORM!1/DELETE IZZY.TXT, OZY.TXT, MADISON.AVE,-00'.)
->IFUZZY.Txr;i2, GUNGA.[IIN;2 ~

The hyphen tells the system to postpone execution of the command until
it receives a carriage return not preceded by a hyphen.
In the
example given, the user had more files to be printed together than
could be specified on a single line.
The hyphen called for the
special continuation prompt (->) rather than execution of the command.
The carriage return without the preceding hyphen then called for
execution of the full command. For more information on command line
continuation, see Section 1.2.13.
NOTE
In most examples and command formats
in
this manual, the carriage return at the
end of a line containing a command or
command element is assumed and is not
shown.

Line Terminators

3.2.2

You can terminate a command line with either the RETURN key, or with
the key variously labeled ESC, SEL, or ALTMODE. CTRL/Z and CTRL/C are
also line terminators.
Each of these terminators has different
effects.
The RETURN and ESC keys are discussed here.
The control
characters are discussed in Section 3.4.
The ENTER key on the keypad is identical with RETURN
level.

DCL

monitor

When you terminate a command line with the RETURN key, as soon as the
command is processed,
the implicit DCL prompt reappears, ready for
another command. For example:
>SHOW TIME ®TI)

09:59:21 13-DEC-82

>
You need not wait for the
command.

return

3-12

the

prompt

enter

another

TERMINAL OPERATIONS

When you terminate a command line with the ESCAPE key,
DCL
prompt after the command has been processed.
For example:
>'.3HOW TIME

does

not

10t05!38 13-DEC-82

The cursor or print head appears at the beginning of the line with the
time on it.
The LINE FEED key provides a line feed without a carriage return.
cannot be used as part of the command line and is not a terminator.

3.2.3

DELETE Versus BACK SPACE

You should avoid
the BACK SPACE key.
This key is
included on
terminals for compatibility with other systems but is not used in DCL.
The BACK SPACE key does not produce an echo, but it can have confusing
results when used in a file or when entering a command. When you make
a typing mistake, use the DELETE key to correct it, not BACK SPACE.
(The BACK SPACE key may be used for special functions within tasks
such as EDT.}
The DELETE key (labeled RUBOUT on some terminals) works in a
different fashion on video and hard-copy terminals.

slightly

On hard-copy terminals the DELETE key removes the last character typed
and then verifies the removal by repeating the removed character on
your terminal preceded by a backslash.
This action is repeated each
time you press the DELETE key.
For instance, the sequence
>RUH FE EBER [QliJ ~LE

appears on a hard-copy terminal as

>RUN FEEBER\RE\LE
But the operating system receives the command:

>RUN FEEBLE
You can verify this by typing a CTRL/R after the corrected line to
retype it properly, without the intervening deleted characters, thus:
>~\'UN

FEE.BER\RE\LE 'ITf3.loB

:>r.;:uN FEEBLE
On a video terminal, the DELETE key actually erases the last character
typed on your screen and you can replace it directly.
The deleted
characters are not repeated.
For instance,

>HlJ N n:: E BER fil -OED LE
The sequence appears on a video screen in succession as follows:

>RUN FEEBER
>FUJN FEEBE
>RUN FEEB
>FWN FEEBL

.>RUN FEEBLE
If you are using an editor that permits you to move the cursor around
on the screen, the DELETE key deletes the first character immediately
to the left of the cursor location.

3-13

TERMINAL OPERATIONS
3.2.4

CAPS LOCK and SHIFT

On most video terminals, the CAPS LOCK key causes all letters to be
typed in uppercase.
This key affects only letters, not numbers or
symbols. You can engage CAPS LOCK and type
'RSX-llM-PLUS'
without
disengaging it, even though the numbers and the hyphens are lowercase.
The SHIFT keys set your terminal to uppercase for the keys not
affected
by
CAPS LOCK, as well as for
individual alphabetic
characters.
On most hard-copy terminals, CAPS LOCK sets all keys to uppercase.
Different terminal models vary widely in their treatment of CAPS
or the equivalent key.
You should experiment on your terminal.

3.2.5

LOCK

REPEAT

The REPEAT key on the VT52 and LA36 repeats the action of any other
key.
You can use it to insert a series of blanks, characters,
carriage returns, or whatever. Use it by holding down REPEAT and the
key whose action you wish to repeat.
It is particularly handy with
the DELETE key.
Normally, a DELETE-REPEAT combination deletes back to
the left margin of your terminal and no further.
Most keys on the VTlOO repeat automatically if
depressed.
There is no REPEAT key on the VTlOO.

3.2.6

you

keep

the

key

SCROLL and NO SCROLL

The SCROLL key on VT52s is used together with the SET TERMINAL/
HOLD SCREEN
command.
This command limits the terminal to one
screenful of information at a time, allowing you to read output that
requires more than one screen's worth of space.
If HOLD SCREEN is
set, the SCROLL key moves the display up one line at a time.
SHIFT
and SCROLL together bring up a new screenful of information.
(A
CTRL/C or SET TERMINAL/NOHOLD_SCREEN returns the terminal to normal.)
The NO SCROLL key on the VTlOO simply causes the terminal to stop
scrolling.
When you are ready for the terminal to scroll, press the
NO SCROLL key again.
See also the discussion of the
3.4.2.

CTRL/S

and

CTRL/Q

See the documentation provided with your terminal for
controlling scrolling on other terminal models.

3.2.7

keys

Section

information

Other Keys

The COPY key is used only on terminals with a copier.
Other keys are listed in Table 3-1, along with common names for them.

3-14

TERMINAL OPERATIONS
Table 3-1
Keyboard and Keypad Characters
Character

Comments

Name

this
On some keyboards,
character appears as an
up-arrow.
It should not
the
be
confused
with
cursor-control keys on the
keypad,
which also have
arrows.

Circumflex

At monitor level, the CTRL
key sometimes echoes as a
circumflex when struck in
combination with a letter.
If you wish to include
CTRL/a
characters in a
batch job,
the
letter
preceded by the circumflex
will be treated
as
a
CTRL/a.
In BASIC programs,
circumflex
is
mathematical operator
exponents.

the
the
for

Right-angle bracket

General term.

Greater-than

ASCII name of character.
Used
in mathematical and
logical expressions.

Implicit monitor
Prompt

At
monitor
level,
signifies that system is
ready to accept commands.
The
explicit
monitor
prompts are MCR> and DCL>.

Left-angle bracket

General term.

Less-than

ASCII name of character.
Used
in mathematical and
logical expressions.

Period

In text.

Decimal point

In numbers ..

Dot

In filespecs,
terminator
between file name and file
type.
The period keys on the
keyboard and keypad are
identical
at
monitor
level.
(continued on next page)

3-15

TERMINAL OPERATIONS
Table 3-1 (Cont.)
Keyboard and Keypad Characters
Name

Character

Comments

At sign

Indirect
operator.

Commercial at

ASCII name.
Not
in the
international
character
set.

Number sign

Not pound sign.

Ampersand

Percent sign

General term.

Wildcard

Stands
for
"match
one
character
in
this
position"
in file names
and file types.

Asterisk

General term.

Wildcard

Stands for "match any or
no
characters
in this
position"
in file names
and file types, or for any
group, member, or version
number.

Underscore

Used to tie command
together in DCL.

Hyphen

continuation
DCL
for
character.
Used
command lines too long for
terminal
line.
Overrides
RETURN.
Command
not
entered
until
monitor
without
receives
RETURN
preceding hyphen.

Minus

Mathematical operator
subtraction.

for

Plus

Mathematical operator
addition.

for

Colon

beginning
of
Marks
argument in DCL command.

Equal sign

Mathematical and logical
used
operator.
Also
extensively in MCR syntax.

{ }

Braces

()

Parentheses

command

file

words

{continued on next page)

3-16

TERMINAL OPERATIONS
Table 3-1 (Cont.)
Keyboard and Keypad Characters
Character

Name

Cormnents

[]

Square brackets

Delimiters for UIC and UFO
numbers.

Slash

Marks
beginning
of
qualifier in DCL commands.
Must be preceded by
in MCR commands.

3.3

Backslash

space

On hard-copy
terminals,
delimiter
for
deleted
characters.

THE KEYPAD

Some terminals have a second set of keys to the right of the main
keyboard,
arranged much like a bookkeeper's keypad.
These keys make
up the keypad.
The keypad keys are available for special functions.
Some functions
of the operating system use these keys.
They may be used in many
other ways, depending on the particular installation.
The following
description covers only the uses of the keypad by functions at the
monitor level.
The keypad numbers work in the same way as the numbers on the regular
keyboard except
that the symbolic characters are not available from
the keypad.
The period key works in the same way as the period on the regular
keyboard.
It is used for including the decimal point in numbers.
The ENTER key works the same as the RETURN key on the main keyboard.
The three blank keys on the VT52 are reserved for
special
functions.
They are not used at monitor level.
The same is true of the PF keys
on the VTlOO.
The four "arrows" are used for cursor control by EDT, the DEC Standard
Editor, but are otherwise available for special functions.
The blank, PF, and cursor-control keys can have seemingly paradoxical
effects if struck carelessly or accidentally.
These keys each send an
ESCAPE character and one or more characters to the
operating system.
The ESCAPE is a nonprinting character, but the associated letter can
be echoed on the terminal and may make the operating system behave as
if you had typed that letter.
Here is how these special keys are set up on the VT52:
up-cursor
down-cursor
right-cursor
left-cursor
blue blank
red blank
gray blank

types
types
types
types
types
types
types
3-17

A
B

c
D
p
Q

TERMINAL OPERATIONS
If, for instance, you were to type a down-cursor while in DCL mode,
you might find yourself being prompted To? because the down-cursor
key sent a B to DCL, which interpreted it as the short form of the
BROADCAST command.
(To exit from any command or prompt, type a
CTRL/Z.)
Here is how these special keys are set up on the VTlOO:
up-cursor
down-cursor
right-cursor
left-cursor
PFl
PF2
PF3
PF4

3.4

types
types
types
types
types
types
types
types

[A
[B
[C
[D
OP
OQ
OR
OS

THE CTRL KEY AND CONTROL CHARACTERS

The key marked CTRL is called the control key.
It is used much like
the shift key on a regular typewriter.
If you hold down the CTRL key
and then press another key, you are sending a command to the operating
system.
The CTRL key alone has no effect.
The combination is designated by CTRL/a, where a is the chosen
key.

letter

When the combination is echoed on your terminal, the CTRL key is
represented by the circumflex (A).
Type a CTRL/U and you see a AU on
your terminal.
The operating system recognizes 11 letters combined with the CTR~ key.
The letters are C,
I,
K,
L,
O, Q, R, S, U, X, and z. These are
discussed below in approximate order of importance.
With the exception of CTRL/Z,
the control characters are commands
directed to the operating system and not to any task you may be
running from your terminal.
This means that they usually work without
interfering with such tasks.
For instance, CTRL/O is used to skip
over terminal output.
It skips over any output, whether sent by DCL,
the Task Builder, an editor, or any other system function.
It only
skips output.
It does nothing else.
NOTE
Although you must press two keys to
enter a control character, the system
considers a control character as
a
single character.

3.4.1

CTRL/C

CTRL/C is a line terminator.
the operating system.

Its main use is to gain the attention of

3-18

TERMINAL OPERATIONS
In most cases, CTRL/C gives you access to the operating system without
interrupting any tasks you may have running from your terminal.
Typing a CTRL/C causes the CLI to prompt for
command
input with an
explicit prompt.
This prompt will be either DCL> or MCR>, depending
on which CLI your terminal is set to.
You can then type a command
without interrupting any other tasks active at your terminal.
This is particularly convenient when you want to abort a task
from your terminal.

running

CTRL/C also assures you that the command you enter will go to DCL when
the DCL> prompt is showing.
If a terminal is receiving output from a task, CTRL/C interrupts that
output.
After DCL processes the
input directed to it, the system
resumes the interrupted output.
No output is lost.
CTRL/C has special effects in two cases:

3.4.2

•

If you have placed your VT52
in hold-screen mode with
the
command SET TERMINAL/HOLD SCREEN, a CTRL/C and a RETURN takes
the terminal out of hold=screen mode.
It is easier to type a
CTRL/C than to type SET TERMINAL/ NOHOLD SCREEN.
It does not
matter whether you type in a command in response to the DCL>
prompt;
hold-screen mode is disabled anyway.
Hold-screen
mode is available in this form on VT52s only.

•

If a CTRL/S has temporarily halted the output of data
to the
terminal,
a CTRL/C starts it up again.
In this case, CTRL/C
is the same as CTRL/Q.
See the discussion of CTRL/S and
CTRL/Q in the next section.

CTRL/S and CTRL/Q

This pair of control characters is used to alternately stop and start
output to a
terminal.
It is particularly useful on video terminals
where the output may go by too fast
to be read,
but
it works on
hard-copy terminals as well.
CTRL/S delays the output and CTRL/Q resumes it.
effect as CTRL/Q.

CTRL/C has

the

same

If you use these commands, you will not skip over any of the output.
All output that should appear, will appear.
It is simply held back
until you are ready to look at it.
(For skipping output,
see the
discussion of CTRL/0 in the next section.)
CTRL/S can have one unexpected effect.
Often, as you are working your way through a file or some other output
using these commands, you will reach the end of the output and receive
a prompt from DCL or some other system program.
Since you have been
stopping output with a CTRL/S for some time, you may type it once
more.
Then, when you try to respond to the prompt, nothing appears on
the terminal.
This
is because the CTRL/S is holding back output to
the terminal, including the echoes of what you have just typed
in to
the prompt.
A CTRL/Q causes the missing echoes to appear and the
system response follows.

3-19

TERMINAL OPERATIONS
3.4.3

CTRL/0

This control character is used to skip over unwanted output to your
terminal.
It
is analogous to the fast-forward control on a tape
recorder.
If you type a single CTRL/O in response to undesired output,
the
output stops appearing on your terminal, but the system continues to
generate the output.
It can do this much faster when it does not have
to print it on the terminal.
If you type another CTRL/O, the output
picks up at the point the operating system has reached, not the print
at which you typed the last CTRL/O.
If you do not type another
CTRL/O, the system continues to generate the output until
it reaches
the end, whereupon a prompt appears and you may continue in response
to the prompt.
If you are printing multiple files on your terminal, the CTRL/O will
be cancelled at the end of each file.
For example, if you have typed

>TYPE *·LST
the system will start with the first file of the type
.LST in your
directory.
If you suppress this output with a CTRL/O, the system will
start printing again as soon as it reaches the beginning of the next
file of the type .LST.

3.4.4

CTRL/Z

Typing CTRL/Z indicates end-of-file.
It is used to indicate to system
tasks,
such as the MACR0-11 Assembler or the Task Builder, that you
have finished and that the task should exit.
A CTRL/Z in response to a prompt or at
cancels the command.

the

CTRL/Z is also used as
particularly the editors.

within

command

end

many

command
system

line
tasks,

If your terminal appears to be hanging, a CTRL/Z will often clear it.
A CTRL/Z in response to a request for input from an indirect
file cancels the execution of the remainder of the file.

command

Fundamentally, CTRL/Z signals the system that you have finished typing
input.

3.4.5

CTRL/U

CTRL/U deletes the current line on your terminal.
It
is as if the
line had never been typed.
The system responds with a carriage return
and a line feed so that the line can be retyped.
If you use CTRL/U with a CREATE command when typing in a sequential
file, the line you have deleted will appear as a blank line within the
file.
In three instances, a ~U may appear
having typed in a CTRL/U.

3-20

your

terminal

without

your

TERMINAL OPERATIONS

3.4.6

•

A system-generation option automatically sends a CTRL/U to any
terminal
that has been awaiting input past a time-out limit.
This limit can be set by your system manager
in seconds to
anything from one second to 21 minutes.
If this option is
included, any line that is not terminated within the time-out
limit is wiped out, as indicated by the CTRL/U that appears at
the terminal.
If you have typed in a line and then deleted it
with the DELETE key,
the system still interprets this as a
line awaiting input and sends the CTRL/U when the time-out
limit passes.

•

If you try to type more than 80 characters on a
line without
using a hyphen to continue the line, the system automatically
cancels the command and indicates this by sending a AU to
the
terminal.
See Section 1.2.13 for more information on line
continuatione

•

Finally, if there is no available pool space when you type
in
a command,
the system sends a AU to your terminal informing
you that your command has been cancelled.
In this case,
the
condition will usually be corrected shortly.
Try typing the
command again.
If this does not work after some reasonable
interval, inform your system operator of the probleme

CTRL/R

Typing CTRL/R before ending a line causes the line to be retyped as it
currently stands, that is, with any corrections you have made in it.
This command is most useful on hard-copy terminals, where the DELETE
key causes characters to be retyped as they are deleted.
You can also
use it on a video terminal to confirm that a line is what you think it
is.
For example:

>T H I MK\ KM\ NK (CTRL R)
>THINK
You may then continue typing the line.
Although you see two copies of the line, there is only one line as far
as the system is concerned.
If you are typing a command on your
terminal when a broadcast or
system message arrives,
you will see a AR and a second copy of your
command line.
Simply continue typing the command.

3.4.7

CTRL/X

A CTRL/X clears your terminal's typeahead buffer.
This buffer is used
to store input characters temporarily until your terminal can pass
them to the operating system.
Occasionally, this buffer gets full.
When your
typeahead buffer
is
full,
you cannot type on your terminal and any key you strike rings
the bell (buzzer, beeper). When this happens, type a CTRL/X and you
may continue using your terminal.
See Section 3.8.1, the description of the SET
more information on the typeahead button.

3-21

TERMINAL

command,

for

TERMINAL OPERATIONS

HELP
CTRL/L

3.4.8

A CTRL/L performs a form feed.
Form feeds are interpreted differently
by different kinds of output devices.
A form feed will always add
several line feeds at the point at which it is inserted.
On a line
printer,
a CTRL/L will usually move the paper past the next
perforation.

Other Control Characters

3.4.9

CTRL/G inserts a bell (buzz, beep)
in a
cannot be the first character in a line.

file

message.

CTRL/G

CTRL/I is the same as TAB.
The cursor or print head moves to the next
tab position.
Tabs are set every eight places.
CTRL/K inserts a vertical tab by performing four line feeds.
CTRL/M is the same as a RETURN.

3.5

HELP

HELP displays information about DCL and MCR commands and
other information about the operating system.

may

display

HELP is the only command that you can issue without logging in.

Format
>HELP[/OUTPUT:filespec] [/qualifier]

[%]

[parameterl]

[ ••• parameter9]

Command Qualifiers
/OUTPUT:filespec
/LOCAL
/GROUP
/CL! :cliname
/MCR
/DCL
/FILE:filespec
/filename

Parameters
No parameters are required for the HELP command and there are no
prompts.
You can get help on any given DCL command or subtopic,
however, by typing a question mark (?) in response to the prompts
from DCL.
You can also get help by typing a question mark in
response to the system prompt (>) and to the explicit DCL prompt
(DCL>) • Examples follow at the end of this section.

3-22

TERMINAL OPERATIONS

HELP {Cont.)
The HELP command without qualifiers or parameters displays the
list of commands for the command line interpreter (CLI} for which
your terminal is set, DCL, MCR, or some alternative CLI in use at
your installation. This display contains information on getting
more help.
The displays for all forms of the HELP command are stored in help
files,
which are text files in help file format.
See Section
3.5.1 for information on writing help files.
parameterl
If you include a parameter in the HELP command, you will
jump
over the initial HELP display to a display concerning the
parameter you have included.
Examples follow at the end of this
section.

Usually this parameter will be a command name. When seeking help
on a command, you should always start with a single parameter.
The display always includes directions for getting any available
further help.
parameter9
There can be up to nine levels of help.
In any case, the number
of parameters you enter determines the display shown; you always
jump over intervening displays. See Section 3.5.1.

Command Qualifiers
/OUTPUT:filespec
Permits you to name an output file where the requested help
is to be saved.
The default is /OUTPUT:TI:.

text

The following qualifiers are mutually exclusive.
These qualifiers
have the effect of naming a file where the requested help text is
located. No matter which qualifier you use, you can still include up
to nine parameters.
If you are in DCL and use none of these qualifiers,
the default
command is HELP/DCL.
If you are in MCR and use none of these
qualifiers, the default command is HELP/MCR.
/LOCAL
%

Specifies that the help text is in the file HELP.HLP in the
default directory on the default volume.
You can specify a local
help file in two ways:
HELP/LOCAL or HELP%.
Examples follow at
the end of this section.
/GROUP
Specifies that the help text is in the file HELP.HLP in the
directory
[current group,l]
on the default volQme.
All users
with the same group number have access to this file by typing
HELP/GROUP.
Examples follow at the end of this section.

3-23

TERMINAL OPERATIONS

HELP (Cont.)
/CLI :cliname
Specifies that the help text begins in the file LB:[l,2]cli.HLP.
This qualifier is for installations with alternate CLis for which
HELP is provided.
The cliname can be from 1 through 6 Radix-50
characters.
Examples follow at the end of this section.
/MCR
Specifies that you wish help on an MCR command.
For this
qualifier,
the help text begins
in the file LB:[l,2]MCR.HLP.
This is the default for terminals set to MCR.
/DCL
Specifies that you wish help on a DCL command.
For this
qualifier,
the help text begins in the file LB: [l,2]DCL.HLP.
This is the default for terminals set to DCL.
/FILE:filespec
Specifies any file where help text is located.
If you do
give
a
complete
file
specification,
the
defaults
LB:[l,2]filename.HLP.

not
are

/filename
Specifies that the help text

begins

with

LB:[l,2Jfilename.HLP.

When using this qualifier. you cannot specify the device, UFD, o:r
extension, only the filename.

Examples

>HELP
HelP is available for the followins DCL commands:
ABORT
BASIC
CONVERT
DEBUG
EDIT
INITIALIZE
LOGOUT
PURGE
h:UN
BTOP

ALLOCATE
BROADCAST
COPY
DELETE
FIX
INSTALL
MACRO

MCR

RELEASE
SET

REMOVE
SHOW
UNFIX

TYPE

For information
Additional help
b~

APPEND
CANCEL
CREATE
DIFFERENCES
FORTRAN
LIBRARY

ASSIGN
COBOL
DEALLOCATE
DH!ECTORY
HELF'
LINK
MOUNT
RENAME
SORT
UNLOCK

BACKUP
CONTINUE
DEASSIGN
DISMOUNT
HOLD
LOGIN
PRINT
REQUEST
START

on a command,
t~Pe
HELP
commandname.
on a Par·ticular' aualifier· is often available

t'::lP in~!

HELP commandname aualif1er.
You can also ~et an'::! DCL help on DCL commands
in response to a PromPt+

3-24

t~Pins

TERMINAL OPERATIONS

HELP (Cont.)
For information an utilities,
sYstem tasks'
and other system
information, tYPe HELP MORE.
For the short forms of some
tYPe HELP
commands, t~Pe HELP BRIEF.
For help on loss ins in,

LOGIN.
This example shows the initial display from HELP.
The user typed
HELP without parameters or qualifiers at a DCL terminal.
>TYPE
File(s)"?

TYF'E[/aualifier[s] filesPec[sJ
/DATE!dd-mmm-s~

/SINCE: dd-mmm--s\:~
/fHROUGH:dd-mmm-yy
/SINCE:dd-m~-yy/THROUGH!dd-mmm-~Y

/TODAY

/EXCLUDE!filespec
The TYPE command disPlaYs the contents of text files
terminal+

Your

Fileds)?
This example shows the display that results from typing in a
question mark
(?)
in response to a prompt from DCL.
The same
display results from typing HELP TYPE.

>SHOW
Function? '?
SHOW thins
The SHOW command can be used to show somethins+
followins thinss can be shown with this command:

ACCOUNTING
CLOCK-QUEUE
DEFAULT

EDAYJTIME

ASSIGNMENTS

SYSTEM
TERMINAL
PROCESSOR

GROUPFLAGS
COMMON
DEVICES
USERS

The

LIBRARY
MEMORY
TASKS
PAfnITIONS

QUEUE

Abbreviation: S
Function? ?TIME

SHOW DAYTIME
SHOW TIME
The SHOW TIME command disPlaYs the current time and date.
The time is in 24-haur format and the date is formatted as
dd-mmm--yy.
Function?
This example shows the display that results from typing a
question mark (?) and a keyword in response to a prompt from the
SHOW command. The same display results from typing HELP SHOW
TIME.

3-25

TERMINAL OPERATIONS

HELP (Cont.)
3.5.1

Help File Format:

Writing a Help File

The HELP facility requires a specially formatted file or files called
help files.
A help file
is a text file with up to nine levels of
nesting.
The format is much the same as a conventional outline.
The
file starts with a main topic followed by any subtopics.
Each
subtopic can include sub-subtopics, and so on through all nine levels.
The format is the same for any
special purpose.

help

file:

local,

group,

cl i,

You can put all help text in a single file, but for faster processing
on larger help files,
you will probably want to use indirect
referencing.
This is explained further below.
The first
(or only)
help file accessed is called the root file.
In addition to the help text, a help file includes the numbered level
indicators, as well as other operators to indicate synonyms and
indirect references.
The operators must appear in the first column.
Anything else that appears in the first column is ignored by HELP.
The help operators include the level numbers from 1 through 9,
the
number sign
(#) indicating a synonym, and the at sign (@) indicating
an indirect file reference.
The level number in the first column must be followed by at least one
blank or tab before the parameter.
The parameter must be all
uppercase characters without intervening blanks or tabs.
Any text
that appears before the first level-number line is printed in response
to a HELP command without any parameters.
Parameters at each level must have different names, but names can be
duplicated at each different level, as shown in the example.
You need
type only the distinguishing portion of a parameter.
HELP interprets its command line in a strictly nested fashion.
When
interpreting parameters, HELP searches down through the help file for
the first line starting with the numeral 1 followed by the specified
parameter.
If such a line exists, HELP displays all the text between
that line and the next level number.
The lines with level numbers and
parameters in them are never displayed.
If you specify more than one parameter,
HELP searches for a
line
starting with the numeral 1 followed by the first parameter and then
continues the search for a line starting with the numeral 2 followed
by the second parameter.
If HELP encounters a line starting with the
numeral 1 before encountering the appropriate level-2 line, the search
stops.
If the line starting with a 2 followed by the parameter given
is encountered, HELP displays the text between that line and the next
level-number line.
This same procedure is followed for all nine
parameters.
The level-number line is not always followed by text.
The following
line may begin with a number sign (#) or an at sign (@).
If the line
begins with a #, HELP substitutes the synonym given there for
the
original parameter and continues the search.
If the following line
begins with an @, HELP then branches to the file specified by the @
and continues its search in that file.

3-26

TERMINAL OPERATIONS

HELP (Cont.)
All these operators are included,
following help file example:

with

further

commentary,

the

Here is the text displayed by typing HELP without parameters.
Introductory information on the further use of the help file
usually appears here.
For better appearance, the first
character in each line is usually a tab or blank, but there is
no technical requirement that you do this. The HELP processor
ignores any first character except the numerals 1 through 9
and the symbols @ and t.
It is good practice to limit text to
about 20 lines so that the display text can be displayed on a
video terminal without scrolling and with room left to enter a
command without losing help text. Text at each level should
refer to all help available at the next level.
Further help is available.

Type

HELP FIRST-LEVEL!

HELP SECOND-LEVEL!

HELP INDIRECT

HELP SYNONYMS

HELP PURPLE

HELP MAUVE

1 FIRST-LEVEL!

This is the first level-1 help text. The first line
This is
text must begin with the numeral 1.
displayed if you type

of this
the text

>HELP FIRST-LEVEL!
The parameter must be all uppercase characters {CAPITALS) • It
is not necessary to type the full text of the parameter to
display the text, but you must type enough of it
to
distinguish the parameter from all other parameters at the
same level. In this example, typing
>HELP FIRST
would be enough. The parameter must be separated from the
level number by one or more blanks or tabs. The parameter
itself cannot include any blanks or tabs, but phrases can be
tied together with hyphens or underscore characters. If you
do this, make it clear in your reference to that level.
Further help is available.

Type

HELP FIRST-LEVEL! FIRST-LEVEL2

2 FIRST-LEVEL2
This is the text displayed if you type HELP FIRST FIRST.
is the first level-2 help text.
1 SECOND-LEVEL!
This is the text displayed if you type HELP SECOND.
the second level-1 help text.
Further help is available.

Type

HELP SECOND-LEVELl SECOND-LEVEL2

3-27

This

TERMINAL OPERATIONS

HELP (Cont.)
2 SECOND-LEVEL2
This is the text displayed if you type
This is the second level-2 help text.

HELP

SECOND

SECOND.

1 INDIRECT
Help files can also include indirect references to other help
text.
These indirect references greatly decrease search time
because once the HELP processor sees the indirect reference,
the calling file (this file) is left behind. The filespec can
be any legal filespec. The default file type is .HLP. If you
use a file type other than .HLP, that type becomes the default
file type for that session of HELPe
The file referred to in this manner has the same format as
other help files, except that if the indirect file contains
level numbers, these must be greater than the level number in
the calling file. For instance, if the calling file contains
the lines
l INSTANCE
@INSTANCE
then INSTANCE.HLP can contain only level numbers 2 through 9.
Further help is available.

See

HELP INDIRECT EXAMPLE
2 EXAMPLE
@EXAMPLE.HLP
l SYNONYMS
HELP also permits cross-references between two or more similar
or synonymous parameters.
The format for synonyms appears
below. You can greatly assist the user by trying to imagine
what might be typed in seeking particular help text and
including the most likely possibilities as synonyms.
The synonyms must all precede the main entry to which they
refer.
The main entry and all synonym entries must have the
same level number.
1 MAUVE
I PURPLE

1 MAGENTA
I PURPLE

1 PURPLE
Color of a hue between blue and red. Shades of purple include
mauve, violet, plum, lilac, puce, amethyst, and magenta.

3-28

TERMINAL OPERATIONS

BROADCAST
BROADCAST

3.6

BROADCAST displays a specified message at one or more terminals.

Format
BROADCAST
To? [ttnn:]
Message? message
BROADCAST/qualifier
Message? message

BROADCAST @filespec

Command Qualifiers
/ALL
/LOGGED_IN

Parameters
message
The message must fit on a single line, but the
final
character
can go
in column 80.
The message can include any printing
character.
Lowercase letters are converted to uppercase.
If you do not specify a destination for the message, the
is sent to pseudo device CO:, the operator's console.
the equivalent of the REQUEST command.
See Section 3.7.

message
This is

ttnn:
Specifies the terminal to which you wish the message to be sent.
Terminals need not be logged in to receive messages, but they
must be turned on (powered) •

userhame . ·

/_:on;:-- ,RS;1(:::..:11M~$>i!tM.:::s;t~fe~s;:·,:-·~-nt~;·i·":·- spi~'c·i·f~es_: th:e·, use~- 'tp.· .whom you .\#l-i,sh: -:·
the me;S'sage." .;t9':: :~e: sent:,···· ,The·. 'mes.sage: ~io~s to· 'all 'terminal's' 'th'e'
user i;s

10~9~. i'.<rr on~ ·

@filespec
Specifies the name of an indirect command file.
All users can
send multiple messages or multiple copies of the same message
using this method.
The file
should contain messages
in the
following format:
TTnn:message
Privileged users can also use the privileged
following formats:
ALL:message
LOGGED_IN:message

3-29

qualifiers

the

TERMINAL OPERATIONS

BROADCAST {Cont.)
The indirect command file cannot include any Indirect directives
or labels, only destinations and messages.
The destination
cannot be preceded by tabs or blanks.

Command Qualifiers
/ALL
This privileged qualifier sends the same message to
terminals, excluding slaved terminals.

all

powered

/LOGGED_IN
This privileged qualifier sends the same message to all logged-in
terminals.

Examples

>PF:OADCAST
To?

TT20:

Messase?

Meet me in the alley behind the barn.

The message is printed on TT20:

30-0CT-82
FROM: TT10t
MEET ME IN THE ALLEY BEHIND THE BARN.

TO:

TT20:

>
As the message arrives,
the terminal's audio signal sounds.
Notice that the message is printed in uppercase characters on the
receiving terminal.

>BROADCAST TT12:

THIS IS A ONE-LINER+

This is the one-line form of the command.

>BROADCAST/LOGGED_IN
MessaSe1

Ever~bod~

take the rest of the day off.

The message is printed on all logged-in
privileged command.

terminals.

This

>BRO @DAILY
The file DAILY.CMD contains the following messages:

rr11:WHERE IS THE DITKO CONTRACT?
TT13:MEET ME FOR LUNCH AT 11:30
TT27tTHE QUICK BROWN FOX JUMPED OVER THE LAZY DOG
TT35:GET BACK TO WORK
TT41tI LOST MY GREEN EYESHADE. HAVE YOU SEEN IT?
The messages are sent to the designated terminals.
Privileged
users can also include messages preceded by ALL:
and LOGGED IN:.

3-30

TERMINAL OPERATIONS

BROADCAST (Cont.)
Notes
B is the short form of BROADCAST.
Only terminals can receive messages.
If you wish your message to
include lowercase
printed, enclose the message in "quotes."

characters

when

If the message cannot be broadcast within 10 seconds, the system
displays the following message at the initiating terminal:
BRO -- Terminal is busy --TTnn:
If a user specifies multiple destinations, the system returns
error message for each busy terminal.

The BROADCAST command uses the write-breakthrough feature of the
terminal driver.
This means the message breaks through any kind
of I/0 at the destination terminal.
If you are editing,
for
instance,
the message may appear in the middle of your text, but
in fact it has no effect on the text you are editing.
You can
issue a
SET TERMINAL/NOBROADCAST command if you do not wish to
receive broadcasts.
See Section 3.8.1.
This command invokes the MCR BRO task.

Error Messages
BRO -- Command input error

Explanation:

The BROADCAST task

did

not

receive

the

command

line.

User Action: Often this message results from a missing indirect
command file.
Locate the file;
or, check for proper syntax and
enter the command again.
BRO -- Command syntax error

Explanation:

The command syntax was not correct.

User Action:

Check for

proper

syntax

and

enter

the

command

again.
BRO -- Illegal device specified

Explanation:

The destination device was not a terminal.

User Action:

Check for

proper

device

and

enter

the

command

again.
BRO -- Privileged command

Explanation: Nonprivileged users cannot
connected or logged-in terminals.

send

messages

User Action: Use an indirect command file to send
multiple terminals from a nonprivileged terminal.

3-31

all

messages

TERMINAL OPERATIONS

REQUEST
BRO
BRO

3.7

User not receiving messages
TTnn:message
Explanation:
NOBROADCAST.

The

message

was

sent

User Action:

Wait and try again.

terminal

set

REQUEST

REQUEST sends a message to pseudo device CO:, the operator's terminal.
Format
REQUEST
Message?

message

REQUEST message
Parameter
messag_e
The message must fit on a single line, but the final character
can go in column 80.
The message can include any printing
character.
Lowercase letters are converted to uppercase.
The message
terminal.

time-stamped

and

indented

the

operator's

Example

>REQUEST Charlie, the tape drives

are

down again+

The message appears on the operator's console
format:

13::30:45
l.3:32:45
13:32:47

the

following

Lo~in

12-SEP-82
FROM: TTS6:
CHARLIE, THE TAPE DRIVES ARE DOWN AGAIN
13:36:22
14:36:42

TO: CO:

Lasin user QUEEQUEG
LoSin user PEQUOD

The user at TT56:
observed a problem on the system and reported
it to the operator with REQUEST.
The message appears on the
operator's console, time-stamped and indented so that it stands
out from other messages.

3-32

TERMINAL OPERATIONS

SET TERMINAL
Notes
The REQUEST command is very similar to the BROADCAST
The main difference is that no destination is required.

command.

CO:
is usually, but not always, TTO:.
In most installations,
however, any REQUEST message will come to the attention of the
operator or system manager.
See the discussion of COT,
the Console Output Task,
in the
RSX-llM/M-PLUS System Management Guide for more information on
CO:.

3.8

SET AND SHOW TERMINAL

SET TERMINAL and SHOW TERMINAL are complementary commands.
SET
TERMINAL sets terminal characteristics and SHOW TERMINAL displays
information about terminal characteristics. For detailed
information
about these characteristics, see the discussion of the full-duplex
terminal driver in the RSX-llM/M-PLUS I/O Drivers Reference Manual.

SET TERMINAL

3.8.1

SET TERMINAL sets various attributes of your
users can set attributes for any terminal.

terminal.

Format
SET
Function? TERMINAL[:TTnn:]
Terminal Attribute? attribute[/attribute[s]]
SET TERMINAL[ :TTnn:] [/attribute] [/attribute[s]]

Attributes
Group 1:

Common Use

/[NO]LOWERCASE
/[NO]HOLD SCREEN
/DCL
/[NO]PRIVILEGED
/[NO]BROADCAST

Group 2:

/[NO]UPPERCASE
/MCR
/SPEED: (transmit,receive)
/CL I: c l i name
/WIDTH:n

Terminal Setup

/ASR33
/ASR35
/KSR33
/KSR35
/LA12
/LA30P
/LA30S
/LA34
/LA36

/VT05B
/VT50
/VT52
/VT55
/VT61
/VTlOO
/VTlOl
/VT102
/VT105

3-33

Privileged

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
/LA38
/LAlOO
/LA120
/LA180S

/VT125
/VT131
/VT132

/[NO]HARDCOPY
/CRFILL:n
/[NO]FORM FEED
/PAGE LENGTH:n
/[NO]AUTOBAUD

/[NO]SCOPE
/LFFILL
/[NO]TAB
/MODEL:arg

Group 3:

Task Setup

/[NO]ECHO
/[NO]FULL DUPLEX
/[NO]INTERACTIVE
/[NO]LOCAL
/[NO]TYPEAHEAti(:n]
/[NO]EIGHT_BIT

/[NO]ESCAPE
/[NO]PASSALL
/[NO]REMOTE
/[NO]SLAVE
/[NO]WRAP
/ f,.NQ]SERlAL

Command Option
TTnn:
Specifies the terminal for which an attribute is to be set.
For nonprivileged users, only your own terminal number or TI:
is
permitted here~
Since TI:
is the defr.in1 t : nonp:rivileged users
need not give a terminal number.
Privileged users can name any
terminal.
Attributes
You can set several attributes at once. This results in several
commands queued to MCR.
If one of these commands fails, all
others following it in the command line also fail.

Group 1:

Common use

The following parameters set terminal characteristics
regularly needed by the average terminal user.

that

are

/UPPERCASE
/NOLOWERCASE
·

/UPPERCASE is the default.
All characters typed on the terminal
appear in uppercase. /NOLOWERCASE is the same as /UPPERCASE.

/LOWERCASE
/NOUPPERCASE
Characters typed on the terminal
in lowercase
appear
in
lowercase.
It is common practice to set terminals to lowercase
in a LOGIN.CMD file.
Most system tasks will accept input in
lowercase.
Note
that some terminal escape sequences use
lowercase characters.
If, for instance, the keypad commands in
EDT do not seem to be working, you may have to set the /LOWERCASE
a t tr i h 1.1 t e .

3-34

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
/[NO]HOLD_SCREEN
Sets a VT50, VT52, or VT55 terminal to HOLD_SCREEN.
Video terminals can present output much faster than you can read
it.
HOLD SCREEN lets you accept output on your VT50, VT52, or
VT55 terminal one line or one screenful a time.
/NOHOLD SCREEN is the default. Output appears at the bottom of
the screen and scrolls off the top at the rate it is sent to the
terminal.
/HOLD SCREEN first clears the screen, then fills in from the
of the screen to the bottom and stops.
If you want to
another line, press the SCROLL key once.
If you want to
another screenful, press the SCROLL key while holding down
SHIFT key. Data is being held back.
It is not being lost.
If you want to disable HOLD SCREEN, either
NOHOLD_SCREEN or press CTRL/C.

issue

SET

top
see
see
the

TERMINAL/

You can also control output with the CTRL/S and CTRL/Q keys.
On
terminals in the VTlOO series, you can use the NO SCROLL key.
See Section 3.2.6 for more information.
/MCR
Sets terminal to MCR. Terminal no longer accepts
The counteracting MCR command is SET /DCL=TTnn:.

DCL

commands.

/DCL
Sets terminal to DCL. Since this is a DCL command, it is mainly
useful for privileged users who wish to set some other terminal
to DCL, but it is not a privileged command.
/SPEED: (transmit,receive)
Sets terminal's rates for transmission and reception of data.
This software speed setting must be matched by the hardware speed
setting, which is controlled by switches on the terminal itself.
The first number in parentheses is the transmission rate, the
second is the reception rate.
Note the use of the comma.
When
you issue SHOW TERMINAL/SPEED, the output has a colon separating
the two rates, but when you issue SET TERMINAL/SPEED, you must
separate the two rates with a comma. See the examples.
Rates are expressed in baud, or bits per second.
A rate of 110
baud is the equivalent of 10 characters per second. For baud
rates above 110, the rate divided by 10 is the equivalent in
characters per second.
Thus, 300 baud, the usual LA36 rate, is
equivalent to 30 characters per second, and 9600 baud, the usual
video terminal rate, is equivalent to 960 characters per second.
In any case, you are limited to the hardware speed settings for
your
terminal.
See the documentation provided with your
terminal, or your system manager, for further information.

3-35

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
/[NO]PRIVILEGED
Sets a terminal privileged or nonprivileged.
A privileged
terminal can issue all DCL and MCR commands.
The default is
determined by whether you log in privileged or nonprivileged.
Privileged users are those whose UIC has a group number equal to
or lower than 10.
(The group number is the first number of the
UIC.~ Setting this attribute is a privileged option.
/CLI:cliname
Sets a terminal to an alternate command line interpreter
(CLI).
The cliname is from one to six Radix-50 characters.
See your
system manager for information on any alternative CLis at your
installation.
/[NO]BROADCAST
Establishes whether you wish to receive broadcast messages
your terminal.
The default is to receive broadcasts.

This attribute restricts messages from BROADCAST and SHUTUP only.
All BROADCAST messages are intercepted when you set your terminal
/NOBROADCAST. Senders are notified that you are not receiving
messages.
See the examples.
As for SHUTUP, all messages about
the pending shutdown of the system are intercepted except those
issued in the last five minutes of SHUTUP.
These are the only
messages intercepted when you set your terminal /NOBROADCAST.
Messages from other tasks are not affected.
/WIDTH: n
The SET TERMINAL/WIDTH command sets the width of your terminal,
that is,
the length of a line. n can be from 0 through 132.
Note that a line length of zero means no commands can be entered
on the terminal.

Group 2:

Terminal Setup

The following qualifiers set
hardware
characteristics
of
terminals.
For certain common models, you can set a number of
characteristics automatically simply by identifying the model.
For
other
terminals,
you must set these characteristics
explicitly, or alter the terminal driver to recognize them.
Here are the models for which automatic setup is provided:
ASR33
KSR35
LA30S
LA38
LA180S
VT52
VTlOO
VT105
VT132

ASR35
LA12
LA34
LAlOO
VT05B
VT55
VTlOl
VT125

3-36

KSR33
LA30P
LA36
LA120
VT50
VT61
VT102
VT131

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
Those
terminals.
Most of these are DIGITAL
those
terminals;
designations
are
hard-copy
Those with nsRn
designations are video models.
Teletypel
pattern.

"LA 11
with
with "VT 11
follow the

Setting a terminal to a particular model does not mean that the
terminal will behave like that model.
It means only that the
if it were that
operating system will treat the terminal as
model.
This feature is intended primarily to deceive tasks that
to
expect a certain terminal model or to identify a terminal as
what it is.
You can set hard-copy terminals as video terminals and you can
set video terminals as hard-copy terminals.
For the terminal
user, the most noticeable difference will be
in the way the
DELETE key operates.
Setting terminals from hard-copy to video
may prove disruptive;
setting terminals from video to hard-copy
is less likely to cause trouble.
Setting a
terminal
to
a
particular
model
designation
automatically sets a number of attributes for the terminal.
See
the RSX-llM/M-PLUS I/O Drivers Reference Manual
for complete
information on the settings for each terminal model.
You can also set these attributes
individually.
Nonprivileged
users can set them for their own terminals;
privileged users can
set them for any terminal.
The defaults for these attributes depend on how your terminal
is
known to the system when you log in.
You can find out how your
terminal is known to the system by logging in and issuing a SHOW
TERMINAL- command.
/NOHARDCOPY
/SCOPE
Sets terminal as a video terminal.
/NOHARDCOPY.

/SCOPE is the

equivalent

/HARDCOPY
/NOSCOPE
Sets terminal as a hard-copy
equivalent of /HARDCOPY.

terminal.

/NOSCOPE

the

/[NO]AUTOBAUD

The /AUTOBAUD qualifier enables autobaud detection on a remote
dial-up line.
This means that when a remote terminal dials up,
the terminal driver samples the first character sent along the
line to determine the incoming baud rate and sets the interface
speed accordingly.
The default is /NOAUTOBAUD.

1. Teletype is a trademark of the Teletype Corporation.
3-37

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
/CRFILL:n
Sets
the
attribute
used
to
~ccommodate
the
carriage-return/line-feed process on hard-copy terminals. While
the terminal is performing the line feed,
a number of null
characters may be needed to fill in for the time the terminal is
not capable of accepting new characters. The value n can be any
number from 0 through 7.
/LFFILL
o~t.::s

"C.ne
attribute used to accommoaate vertical spacing on
terminals. While the terminal is performing a vertical tab, line
feed, or form feed, four null characters are sent to fill in for
the time the terminal is not capable of accepting new characters.

/[NO]FORMFEED
If the terminal hardware supports form feeds, the terminal should
be set /FORMFEED.
If form feeds are handled by the software
providing line feeds, the terminal should be set /NOFORMFEED.
/[NO]TAB
If the terminal hardware supports horizontal tabs,
the terminal
should be set TAB.
If tabs are handled by the software providing
spaces, the terminal should be set NOTAB.
/PAGE LENGTH:n
Defines the number of lines to a page. By convention, a page is
usually considered the number of lines to a screenful on video
terminals or the number of lines between perforations
on
hard-copy terminals.
This attribute sets the length of the page.
(Width is set through the SET DEVICE command, Section 5.10.2.)
/MODEL:n
This parameter is used primarily to identify terminals that are
not on the automatic setup list.
Your system manager will tell
you if you need to use this parameter.
SYSTEM MANAGERS
n can be any decimal number from 0 through 255
(0-377
octal).
The first half of these numbers (0-127 decimal
or 0-177 octal) is reserved for use by DIGITAL.
Each of
the terminals on the automatic setup list is assigned one
of these numbers.
The second half
(128-255 decimal or
200-377 octal) is available for other terminals.
Setting a terminal with an /MODEL value has little effect by
itself.
If the /MODEL value is that of one of the terminals on
the automatic setup list, the effect will be the same as setting
the terminal to that model.
If the /MODEL value is unused, then
setting the terminal to that value affects nothing but the output
from SHOW TERMINAL/MODEL.

3-38

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
If you wish automatic setup for those terminals not included in the
automatic setup list, you can add /MODEL values to the table in
SYO: (11,lO]TTDAT.MAC and then reassemble and relink the terminal
driver with the new table.
Procedures for adding entries to the table
are given in the comments in TTDAT.MAC.
If you do this, a SET TERMINAL/MODEL command with the proper
You cannot
value will set up such a terminal automatically.
identify such terminals by a name;
only a /MODEL value is
permitted.
Group 3:

Task Setup

The following parameters set terminal characteristics that may be
needed by system or user tasks. Most system tasks that require
these attributes in a terminal will set the attributes when they
attach the terminal.
User tasks can also do this.
This will be
transparent to the user.
These parameters are included for
u~c
in cases where the task does not do this setting. See the
RSX-llM/M-PLUS I/0 Drivers Reference Manual for
information on
how tasks can s~term1nal attributes.
/[NO]ECHO
Enables
(or
terminal.

disables)

echoing

/ECHO is the default.
Characters
echoed on the terminal.

characters
typed

/NOECHO suppresses the echo.
(The system task
feature to keep passwords secret.)

typed

the

terminal

are

uses

this

/NOECHO changes nothing but echoing.
Commands can still
passed to the system, but the system passes no echo back.

/(NO]ESCAPE
Enables (or disables)
terminal.

recognition

escape

sequences

from

/NOESCAPE is the default. When you press the ESC (SEL,
ALTMODE)
key, it is interpreted as a line terminator (with a line feed but
no carriage return).
ESCAPE enables the recognition of escape sequences from the
terminal.
When you press the ESC
(SEL, ALTMODE) key, it is
interpreted as the beginning of an escape sequence. The ESC key
will no longer terminate a line.
This is a rarely used parameter.
Most tasks that recognize
escape
sequences will attach the terminal so that escape
sequences are passed without the user's knowledge, usually from
the keypad.

3-39

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
/[NO]FULL_DUPLEX
Enables (or disables)

full-duplex mode at a terminal.

/NOFULL DUPLEX is the default.
The terminal cannot accept input
and re~eive output at the same time.
"Half-duplex" is the usual
industry term for this attribute.
/FULL DUPLEX allows the terminal to ac9ept
input and receive
output at the same time.
This attribute is useful where echoing
is not required, with split-screen applications, and when the
terminal is communicating with some full-duplex device.
/NOP AS SALL
/INTERACTIVE
Specifies that any characters typed on the terminal should be
interpreted by the terminal driver before they are sent to a
task.
CTRL/A is accepted as a command to an interactive
terminal.
NOPASSALL is the same as INTERACTIVE.
This is the
default setting.
/PASS ALL
/NO INTERACT IVE
Specifies that characters sent by the terminal should not be
interpreted by the terminal driver.
Therefore, the task must
interpret all characters. CTRL/A may be a command to a task,
in
this casei but will not affect the operating system.
This
parameter automatically sets the terminal
to the /EIGHT_BIT
attribute.
/NOR EMOTE
/LOCAL
Specifies that the terminal is not attached to a dial-up line.
/NOREMOTE is the same as LOCAL.
This is the default setting.
/REMOTE
/NO LOCAL
Identifies a terminal number with a dial-up line.
A user can
call
in and attach a remote terminal.
/REMOTE is the same as
/NOLOCAL.
This keyword has nothing to do with the LOCAL/REMOTE switch found
on some terminals, which sets the terminal as a typewriter
(LOCAL) or terminal (REMOTE), nor does it have anything to do
with DECnet host terminals.
/[NO]SERIAL
This qualifier is for RSX-llM-PLUS systems only. The default is
/NOSERIAL.
When you enter a command before the previous command
has completed execution, the second command
is processed
in
parallel with the first.

3-40

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
Setting the terminal /SERIAL means that the first command
completes execution ·befo·re the second .is passed to the system.
When a terminal is.. set /SERIAL, c9mmands: a·re retained in the
terminal's typeahead. buffer . uriti'l i t is time for them to be
passed to the system.
See the discussion ' of /TYPEAHEAD for
informatio.n on now .to: change. the· size of.· the te.rminal' s typeahead
buffer.
/[NO]SLAVE
Enables (or disables) slave status at a terminal.
/NOSLAVE is the default. The terminal can both send unsolicited
input and receive system output. The user has full access to all
facilities of the terminal.
This is a rarely used parameter. Most tasks that need a slave
terminal will attach the terminal without specific action by the
user.
This parameter is not privileged, but if you set your terminal
/SLAVE, you will need to go to a privileged terminal to set the
terminal back to /NOSLAVE.
I

/run1mvn~nu~nnr.~1
LL'tVJ

.L,JaJ:J...ICl..l.lJ...1£""1.L..l'l·•1-1J

This qualifier has different effects on RSX-llM and RSX-llM-PLUS.
On. :RSX-lJM systems, t~e;·,/TYJ:>EAHEAD. qualifier. ·enabl.es ot disables
the terminal's type.ahead attr i bQt·e. /'rYPEAHEAD is the ;default .. ·
The· termin9:l accepts :input las.t~r· ·tqan it · .'.can. · send· · j t •. . Wbil:e
waiti,09. t.o be sent.; . ,:tpi.s input ·is stored in the :teZ-:m.i.na1.•s
typeati.ead ·buffer, wb.~x~h ho:lds · 3:6 chara(:ters:": · This· · hliffe.r ,. :slze·
cann.of be. changed qn RSX::-llM;. no. ·numer: ical. argument · i.s · a;cc~pted.
lf . th.e · blf~fer g·et.s· f4·+.1; · tbe term.inaT ·fl:o 'lo.ng·er , ac.cepts
uns(»lici ted .. input·.·.· ·.· Wh~n th~ buf.fei is ·fu+.L; the, c}la:racters yo'u
type are no longer echoea·,. and'. "the bel.1 (buzz:er, beeper) .. sounds
each time you press: ·a 'key. Y·ou can ·cfear: the typeahead buffet
with a GTRL/X.· ·/NOTYPEAHEAD· disables this feature·.· .. 'The terminal
driver.'cannot sto're charac'te'rs ana: excess.characters';are lost • .
On RSX-llM-PLUS. systems, the /TYPEAHEAD qualifier enables or
disables the terminal's typeahead attribute and also sets the
size of the typeahead buffer. /TYPEAHEAD:86 is the default. The
terminal accepts input faster than it can send it. While waiting
to be sent, this input is stored in the typeahead buffer. ·If the
buffer gets full, the terminal no longer accepts unsolicited
input. When the buffer is full, the characters vou type are no
longer echoed, and the bell (buzzer, beeper) sounds each time you
press a key. You can clear the typeahead buffer with a CTRL/X.
/NOTYP.EAHEAD disables this feature. The terminal driver cannot
store characters and excess characters are lost.
On RSX-llM-PLUS systems, you can set the size of the typeahead
buffer from 0 through 255. If your terminal is set /SERIAL, you
may wish to increase the size of the typeahead buffer so you can
queue more commands.

3-41

TERMINAL OPERATIONS

SET TERMINAL {Cont.)
/[NO]WRAP
Specifies that the terminal automatically
lines longer than its line width.

wrap

(or

not

wrap)

/WRAP is the default.
The terminal automatically issues a
carriage return and a line feed when you type to whatever line
width the terminal is set for.
/NOWRAP overrides this feature and permits unlimited line length.
/[NO]EIGHT_BIT
Enables (or disables) a terminal's /EIGHT_BIT attribute.
/NOEIGHT BIT is the default.
DIGITAL
ASCII (wTthout parity checking).

software

employs

7-bit

/EIGHT BIT allows the terminal to pass all eight bits of the
ASCII -character.
This attribute is used when your terminal is
communicating with some device that sends 8-bit ASCII.

Examples

>SET
Function? TERMINAL
Attribute? LOWER
This example sets the /LOWERCASE attribute for the issuing
terminal.
Lowercase characters sent from the terminal will not
be converted to uppercase.
Most system tasks will accept
commands in lowercase.
The EDT keypad commands will not work
unless your terminal is set /LOWERCASE.

>SET TERMINAL/LOWER
This example is equivalent to the previous· one.
frequently included in a LOGIN.CMD file.

This command

>SET TERMINAL/VT52
This example sets the issuing terminal as a VT52. The operating
If it is in fact a
system "sees" the terminal as a VT52.
hard-copy terminal, output to the terminal may be garbled and the
This command sets a number of
terminal may seem to jam.
defaults.
These are shown in Table 3-2.

>SET TERM/LA36
This example sets the issuing terminal as an LA36.
The operating
system "sees" the terminal as an LA36.
If it is in fact a video
terminal, the only noticeable side effect will be the reprinting
of characters deleted by the DELETE key.
This command sets a
number of defaults. These are shown in Table 3-2.

3-42

TERMINAL OPERATIONS

SHOW TERMINAL
>SET TERM/SPEEDt<ii0,300)
This example sets the issuing terminal to transmit at 110 baud
and receive at 300 baud.
The acceptable values for transmit and
receive rates are inherent in the design of the terminal and
other
hardware.
See the documentation provided with your
terminal. After issuing this command, the user must reset the
hardware to the same transmit and receive rates. You must issue
the SET TERMINAL command first and then set the hardware so that
the terminal driver can communicate with the terminal.
>SET TERMINAL/LA36/SPEED:C300,300)/NOBROADCAST

This example sets the issuing terminal as an LA36, sets its speed
to
300 baud for both transmit and receive, and inhibits
broadcasting to the terminal.
>SET TEF:MINAL./SEF:IAL/TYPEAHEAD: 150 IBTIJ
.>MACRO/SHOW: ALL PETE, JOHN, ROGER' KE ITH
LINK/TASK:WHO KEITH ~
RUN WHO (BTIJ

IBTIJ

In this example, the User set his terminal /SERIAL and increased
the size of the typeahead buffer.
The user then entered a MACRO
command, followed by a LINK command and a RUN command.
The
commands are separated by RETURNs.
The LINK command cannot
execute until the assembly completes, and the RUN command cannot
execute until the task build completes.
In fact, the LINK
command is not even echoed until the MACRO command completes and
the same is true for the RUN command. The unexecuted commands
are stored in the typeahead buffer.

Note
You can find how all attributes are set for your terminal with an
unadorned SHOW TERMINAL command. See Section 3.8.2.

SHOW TERMINAL

3.8.2

SHOW TERMINAL displays information about your terminal and
terminals on your system.

Format
SHOW
Function?

TERMINAL[:TTnn:]

SHOW TERMINAL[:TTnn:] [/attribute] [/attribute[s]]

Attributes
/[NO]LOWERCASE
/[NO]HOLD SCREEN
/MCR
/[NO]PRIVILEGED
/LOGGED_ON

/[NO]UPPERCASE
/DCL
/SPEED
/[NO]BROADCAST
/CL!: cli name
3-43

the

other

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
/[NO]ASR33
/[NO]ASR35
/[NO]KSR33
/[NO]KSR35
/[NO]LA12
/[NO]LA30P
/[NO]LA30S
/[NO]LA34
/[NO]LA36
/[NO]LA38
I [NO] LAlOO
/[NO]LA120
/[NO]LA180S
/[NO]VTOSB

/[NO]VTSO
/[NO]VT52
/[NO]VT55
/[NO]VT61
/[NO]VTlOO
/[NO]VTlOl
/[NO]VT102
/[NO]VT105
/[NO]VT125
I [NO] VT13 l
/iNO] VT132

/[NO]HARDCOPY
/CRFILL
/[NO]FORM FEED
/PAGE_LENGTH

/[NO]SCOPE
/LFFILL
/[NO]TAB
/MODEL

/[NO]ECHO
/[NO]FULL DUPLEX
/[NO] INTERACTIVE
/[NO]LOCAL
/[NO]TYPEAHEAD
/[NO]EIGHT BIT
/HT
/TT

/[NO]ESCAPE
/[NO]PASSALL
/[NO]REMOTE
/[NO]SLAVE
/[NO]WRAP
/[NO]AUTOBAUD

/VT
/TI:

Command Option
TTnn:
Identifies the terminal about which
information.
The default is TI:.

you

wish

display

An unadorned SHOW TERMINAL command, such as the following:
>SHOW TERMINAL
or
>SHOW TERMINAL:TT56:
displays all the attributes set for your terminal or the terminal
you name.
See the examples.
SHOW TERMINAL/ALL displays information about all terminals·on the
system.

Attributes
Each SHOW

TERMINAL attribute is directly related to a SET
ml------.:-of each attribute is discussed
.1. u i::: 111 e c:u .1 ..1. 11 '::I
attribute.
in its place under SET TERMINAL in Section 3.7.1.
In addition,

TERMINAL

3-44

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
each SHOW TERMINAL attribute can have a NO in front of
it to
allow you to determine which terminals do not have a particular
attribute.
You can include more than one attribute in your SHOW TERMINAL
command.
This is the equivalent of entering a series of SHOW
TERMINAL commands.
That is, the command

>SHOW TERMINAL/LA36/DCL
displays a list of all LA36s on your system and a
list of all
terminals set to DCL, but NOT a list of all LA36s set to DCL.
The displays returned by SHOW TERMINAL do not necessarily match
the attribute names used in DCL.
For instance, the command

>SHOW TERMINAL/HARDCOPY
causes a display labeled NOCRT, meaning that the terminal is
a cathode-ray terminal.

not

The same display results from

>SHOW TERMINAL/NOSCOPE
Table 3-2 shows the relationships between SHOW TERMINAL and
its
displays,
and SET TERMINAL.
For further
information on the
displays, see the examples.
/HT
/TI:
/TT

/VT
These qualifiers display information about particular types of
terminals on the system.
/HT displays a list of DECnet host
terminals. /TI:
is the same as SHOW TERMINAL without any
qualifier.
/TT displays a list of real terminals on the system.
/VT displays a Hst
system.

v:ittual

terminals

RSX.;..HM-'PLUS

If your SHOW TERMINAL command produces only a prompt and no output,
there are no terminals on the system that match the attribute given in
your command.
Table 3-2
Display of Terminal Attributes from SHOW TERMINAL
SHOW TERMINAL
Attribute

SHOW TERMINAL
Display

SET TERMINAL
Attribute

AUT OB AUD

AB AUD=

AUTOBAUD

DCL

DCL=

DCL
(continued on next page)

3-45

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
Table 3-2 (Cont.)
Display of Terminal Attributes from SHOW TERMINAL
SHOW TERMINAL
Attribute

SHOW TERMINAL
Display

SET TERMINAL
Attribute

ECHO

ECHO=

ECHO

EIGHT BIT

EBC=

EIGHT BIT

ESCAPE

ESCSEQ=

ESCAPE

FORM FEED

FORMFEED=

FORM FEED

FULL DUPLEX

FOX=

FULL DUPLEX

HARDCOPY

NOCRT=

HARDCOPY
NO SCOPE

CRFILL

HF ILL=

CRFILL_

HOLD SCREEN

HOLD=

HOLD SCREEN

INTERACTIVE

NOR PA=

INTERACTIVE
NO PAS SALL

LOCAL

NOR EMOTE=

LOCAL

NO REMOTE
LOWERCASE

LOWER=

LOWERCASE

NO ECHO

NOECHO=

NO ECHO

NOEIGHT BIT

NOEBC=

NOEIGHT BIT

NO ESCAPE

NOESCSEQ=

NO ESCAPE

NOFORM FEED

NOFORMFEED=

NOFORM FEED

NOFULL DUPLEX

NOFDX=

NOFULL DUPLEX

NOHARDCOPY

CRT=

NOHARDCOPY
SCOPE

NOHOLD SCREEN

NOHOLD=

NOHOLD SCREEN

NO INTERACT IVE

RPA=

NO INTERACT IVE
PASSALL

NO LOCAL

REMOTE=

NO LOCAL
REMOTE
(continued on next page)

3-46

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
Table 3-2 (Cont.)
Display of Terminal Attributes from SHOW TERMINAL
SHOW TERMINAL
Attribute

SHOW TERMINAL
Display

SET TERMINAL
Attribute

NO LOWERCASE

NOLOWER=

UPPERCASE

NOPASSALL

NOR PA=

NOPASSALL
INTERACTIVE

NOPRIVILEGE

NOPRIV=

NOPRIVILEGE

NOREMOTE

NOR EMOTE=

NOR EMOTE
LOCAL

NOSCOPE

NOCRT=

NOSCOPE
HARDCOPY

NOS LAVE

NOS LAVE=

NOS LAVE

NOT AB

NOHHT=

NOT AB

NOTYPEAHEAD

NOTYPEAHEAD=

NOTYPEAHEAD

NOUPPERCASE

LOWER=

LOWERCASE

NO WRAP

NOWRAP=

NOWRAP

MCR

MCR=

MCR

MODEL

TERM=

MODEL

PAGE LENGTH

LINES=

PAGE LENGTH

PAS SALL

RPA=

PAS SALL
INTERACTIVE

PRIVILEGE

PRIV=

PRIVILEGE

REMOTE

REMOTE=

REMOTE
NO LOCAL

SCOPE

CRT=

SCOPE
NOHARDCOPY

SLAVE

SLAVE=

SLAVE

SPEED

SPEED=

SPEED

TAB

HHT=

TAB

TYPEAHEAD

TYPEAHEAD=

TYPEAHEAD

UPPERCASE

NOLOWER=

UPPERCASE
(continued on next page)

3-47

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
Table 3-2 (Cont.)
Display of Terminal Attributes from SHOW TERMINAL
SHOW TERMINAL
Attribute

SHOW TERMINAL
Display

SET TERMINAL
Attribute

LFFILL

VF ILL=

LFFILL

WRAP

WRAP=

WRAP

Examples
SHOW
TERM IN.AL.
[303,12]
CL!
DCL
LINES
66.
LOWER
NOPRIV
ECHO
NOVFIL.L

•..inc ti nn?

Tl3:

BUF
TEHM
NOHOLD
NOHHT

[303,12]
132.
LA36
NOSLAVE
NOFDX

HF ILL
OWNER
NOE SC
WRAP

SELF
NOCF:T
NORPA

SPEED=<300,300)
BRO
NOA BAUD
NOHFF
NOREMOTE
TYPEAHEAD
NOE BC

This example displays all the attributes for
the user's own
terminal.
The command is the equivalent of SHOW TERMINAL:TI:.
These include the terminal number, the login UIC,
the default
UFD, plus all the attributes that can be set with SET TERMINAL.
See Table 3-2 and the remaining examples.
>SHOW TERMINAL: TT56;
[7, 100]
DCL
CL.I
24.
LINES

TT56:

LOWEF:

ECHO

BUF
TERM
NOH OLD
PIU~'
tWVFILL NOH HT

[303,5]
80.
VT100
NOSLAVE
NOFDX

HF ILL
OWNER
NOE SC
WRAP

SELF
CRT
NORPA

SPEED=<9600,9600)
NOABAUD
BRO
NOH FF
NOREMOTE
NOE BC
TYPEAHEAD

This example displays all the attributes for another terminal.

>SHO TERM/ESCAPE

>
This example shows that no terminal on the
set to handle escape sequences.

system

currently

>SHOW TERMINAL/LA36/DCL
DCL=TT5:
Lf~36=COO:
l..A~36=TTO:

!... A36~=T T34:

This example displays all the terminals on the system set as
LA36s and all terminals on the system set to DCL.
Note that the

3-48

TERMINAL OPERATIONS

SHOW TERMINAL {Cont.)
order of the display is not necessarily the same as the order the
attributes were listed in.
Note also that the effect is the same
as a SHOW TERMINAL/LA36 followed by a SHOW TERMINAL/DCL.
In
other words, the display does not show all LA36s set to DCL.

>SAO TERM/LOWERCASE
LOWER=TT1 !
LOWER=TT3:

>SHO TERM/NOUPPERCASE
LOtJER=TT 1:

>SHO TERM/NOLOWERCASE
NOLOWER=TT2:
NOLOWER=TT5:

>SHO TERM/UPPERCASE
NOLOWER=TT2:

>SHO TERM/HOLD_SCREEN
HOLD=TT21:

>SHO TERM/NOHOLD_SCREEN
NOHOLD=TT 1:
NOHOLD=TT2!

>Sl-10 T'ERM/MCR
MCR 0.::fT 14 !

3-49

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
>SHO TERM/UCL
DCL=TT20:

>SHO TERM/PRIVILEGED
PRIV=TT?:

>SHO TERM/NOPRIVILEGED
NOPRIV=TT10:

>SHO TERM/SPEED
SPEED=TT10:9600:9600
This example displays the speed settings for
which the command was issued.

the

terminal

from

Note that the transmission and reception rates are separated by a
colon
in
this display.
When you are setting these rates, the
figures are separated by a comma and enclosed in parentheses.

>SHO TERM/ASR33
1~SR33=TT22 !

This example displays all the terminals on the system that are
set to type ASR33.
All
the SHOW TERMINAL keywords naming
specific models give the same kind of display.
If you use the NO option, the display lists NOASR33=TTn:.

>SHO TERM/HARDCOPY
NOCfn:~cTT1 "?:

>SHO TERM/NOHARDCOPY
CRT=TT21:

3-50

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
>SHO TERM/SCOPE
CRT=TT21:

>SHO TERM/NOSCOPE
NOCRT=TT17:

CRT means cathode ray tube, another name for a
scope.

video

screen

>SHO TERM/CRFILL
HFILL=TT10:0
value

terminal

from

for

the

its

/LFFILL

attribute

This example shows which terminals have their FORMFEED
enabled (or not).

attribute

This example returns
which it was issued.

>SHO TERM/LFFILL
VFILL=TT42t

This example shows
enabled.

which

terminal

has

>SHO TERM/FORMFEED
FORMFEED=TT13:

>SHO TERM/NOFORMFEED
NOFORMFEED=TT15:

>SHO TERM/TAB
HHT=TT12!

>SHO TEFi'.M/NOTAB
NOHHT=TT7:

This example shows which terminals have their
enabled.
HHT means Horizontal Hardware Tabs.

3-51

TAB

attribute

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
>SHO TERM/PAGE-LENGTH
LINES=TT7: 24
This example displays the page size (screen size) of the terminal
from which the command was issued. A nonprivileged user cannot
display the page size of another terminal with this command. Use
the unadorned SHOW TERMINAL.

>SHO TERM/ECHO
ECHO=TT1:

>SHO TERM/NOECHO
NOECHO=TT15:

>SHO TERM/ESCAPE
ESCSEQ=TT11. t
>SHO TERM/NOESCAPE
NOESCSEQ=TTl!

ESCSEQ means ESCape SEQuences.

>SHO TERM/FULL-DUPLEX
FDX=TT2t
>SHO TERM/NOFULL-DUPLEX
NOFDX=TT 1:

FOX means full-duplex.

>SHO TERM/PASSALL
l~PA=TTl t

>SHO TERM/INTERACTIVE
NOF:F'A=TT3 !

3-52

TERMINAL OPERATIONS

SHOW TERMINAL {Cont~)
>SHO TERM/NOPASSALL
NORPA=TT3:

>SHO TERM/NOINTERACTIVE
RPA=TT1:

RPA means Read-Pass-All.

>SHO TERM/REMOTE
F!EMOTE=TT 1:

>SHO TERM/LOCAL
NOREMOTE=TT12:

>SHO TERM/NOLOCAL
REMOTE=TT 1:

>SHO TERM/NOREMOTE
NOREMOTE=TT12:

This attribute has nothing to do with the LOCAL/REMOTE switch
found on some terminals.
Remote terminals access the system
through dial-up lines while local terminals are hard-wired to the
computer.
This attribute has nothing to do with DECnet host
terminals either.
The LOCAL/REMOTE switch on a
terminal
typewriter or terminal, respectively.
>SHO

TEF:M/SLAVE

SLAVE=TT56!
>SHO TERM/NOSLAVE
NOSLAVE=TT1:

3-53

sets

terminal

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
>SHO TERM/TYPEAHEAD
TYPEAHEAD=TT 1:

>SHO TERM/NOTYPEAHEAD
NOTYPEAHEAD=TT27:
>SHO TERM/WRAP
WRAP=TT1:

>SHO TERM/NOWRAP
NOWRAP=TT 45:
>SHO TERM/NOEIGHT_BIT
NOEBC=TT1:

>SHO TERM/EIGHT_BIT
EBC=TT6:
EBC means Eight-Bit
ACSII.

Characters.

3-54

DIGITAL

software

uses

7-bit

CHAPTER 4

HANDLING FILES

4.1

FILES ON RSX-llM/M-PLUS SYSTEMS

The commands in this chapter are used to create files,
list them in
directories,
remove them from directories, print copies of them on
your terminal or the line printer, and alter their contents in various
ways.
Some error messages from commands described in this chapter are
documented in Appendix A of this manual.
Other error messages are
documented in the RMS documentation supplied with your system.
All files are stored on volumes.
These volumes are written on
magnetic media, which can be placed on various physical devices.
Once
the volume is mounted, you can access the files on the volume.
For
more information about volumes and devices, see Chapter 5.
Within each volume, files are organized in directories.
For the
entire volume,
there is a Master File Directory (MFD).
The MFD is a
file named [0,0]000000.DIR. Files in the MFD are all User File
Directories
(UFDs).
The UFD files are named after the group and
member numbers. Thus, UFD [200,1] is a file listed in the MFD and
named [0,0]200001.DIR.
See Figure 4-1 for an illustration of the relationship between volume,
MFD, and UFD.
MFD
[0,0]

-- -

UFO
[200,1]

EJ
A.MAC;1

UFD
[303,5]

I ----

FL Y.TXT;1

Figure 4-1

I -----

-----1_
I

I IZZY.TXT;1

OZY.TXT;1

ZK-289-81

File Organization on a Volume

4-1

HANDLING FILES
4.1.1

File Ownership and Location

When you log in to the system,
you identify yourself with a
Identification Code (UIC).
You log in to your default device and
The default UFD has the same group and member
number as your
Nonprivileged users can change their default UFD, but not their
Privileged users can change both.
The UIC identifies the user;
UFO identifies the directory where files are located.

User
UFD.
UIC.
UIC.
the

The default device is actually a volume mounted on a device.
Most
file-handling commands are directed to the volume and not the device,
but both volume and device are identified in the same format, ddnn:,
where dd
is a
2-letter mnemonic for the device type and nn is the
octal unit number of the device.
The colon is a required terminator.
Usually,
the command description or function makes clear whether the
command is directed to the physical device or to the volume.
Regardless of its physical designation, your default device is always
called SYO:.
This is a logical assignment made each time you log in.
Information on your default device is kept by ACNT, the Account File
Maintenance Program
(Sections 3.1.1 and 3.1.3), and read from there
each time you log in.
When you create a file, the system places the file name in a UFO along
with a User Identification Code (UIC), indicating the ownership of the
file.
Both the UFO and the UIC have the same format, a 1- to 3-digit
octal group number and a 1- to 3-digit octal member number separated
by a comma and enclosed in brackets.
These numbers range from O
through 377 octal.
Directory entries in both MFDs and UFDs consist of the names of files
and pointers to file headers.
The file header holds information about
the file's owner and the location of the file on the mass-storage
medium.
Thus, a full file specification not only identifies the file#
but locates it as well.

4.1.2

File Specification

File specifications, often called filespecs, are required for many DCL
commands.
The format of a file specification is as follows:
ddnn: [g,m]name.typ;ver

ddnn:
Specifies the type of device and unit number on which the volume
containing the file is mounted.
It consists of a 2-letter device
name followed by an optional 1- or
2-digit octal unit number
terminated with a colon.
The 2-letter names for devices found on RSX-llM/M-PLUS are listed
in Section 5.1.

[g,m]
Specifies the UFD.
g and mare octal numbers from 1 through 377.
g
is the number of your group and m is your member number.
You
usually have full access to the UFOs with the same group number
as yours.

4-2

HANDLING FILES
name
Specifies the name of the file, an alphanumeric string from
through nine characters long •

zero

• typ
Specifies the file type.
This field
is
a
0through
3-alphanumeric-character string that usually indicates the file
contents. For example, .FTN is the file type for FORTRAN source
programs.
Always separate the name from the file type with a period (.).
There are no restrictions on file types, but many system tasks
use default file types for
input and output files.
These
defaults and some system conventions on file types are summarized
in Section 4.1.3. Null file types (0 length) are acceptable.

;ver
Specifies the version number, normally an octal number from 1
through 77777. The version number identifies different versions
of the same file. When you create a file without specifying a
version number,
the system assigns the file version number 1.
Each time you create a new version of the file, by editing it,
for instance, the system adds one to the version number.
You must separate
semicolon.

the

file

type

and

version

number

with

You can also create a file with an explicit version number.
If you create a file with version number 77777, you can be sure
that file cannot be inadvertently superseded by a file with a
higher number;
77777 is the highest possible version number.
This is useful where you must have a particular version of a file
for some operation.
In addition, you can name version 0 or version -1 in commands.
Version 0 defaults to the most recent version of the named file;
version -1 defaults to the oldest version of the named file.
In most cases, RSX-llM/M-PLUS systems do not require you to enter the
full
file specification. Defaults are supplied for all fields of the
file specification except the name (see Section 4.1.3).
In addition,
you can use wildcards to specify groups of related files (see Section
4.1.4).

4.1.3

Defaults in File Specifications

Except for the file name,
specification,
the
system
specified here:

i f you omit
automatically

Field
ddnn:

a
field
supplies

of the
file
the field as

Default
Your default device is established when you log in.
SYO:
is always your default device.
Logging in assigns SYO:
to
some physical device.
You can use SET DEFAULT to change the
assignment of SYO:;
you can display the assignment with
SHOW DEFAULT.
{See Section 4.5.) Remember that you do not
have to use the unit number for devices numbered O. DB:
is
the same as DBO:, for instance.
4-3

HANDLING FILES
Field

Default

[g ,m]

Your default UFO is established when you log
in.
The
default
is the UFD that has the same group and member
numbers as your UIC.
You can change the default UFD with
SET DEFAULT;
you can display the default UFD with SHOW
DEFAULT.
(See Section 4.5.)

• typ

Standard file types (see Table 4-1) are used as defaults •
There is not a default file type in every situation.

;ver

For
input files,
the default
is the highest numbered
version;
for output files, it is the next higher version
number, or 1 if no previous version exists.

The defaults make it possible for you to specify files without
to type in the full file specification~

having

Suppose, for example, you log in with the UIC [200,20].
Your default
device is DBO:, as recorded the System Account File, and assigned the
name SYO:, and your default UFO is
(200,20].
Assume further
that
there are three sequentially numbered versions of a file called
TEXT.TXT in the directory.
If you wish to print the highest numbered
version of this
file
(version 3)
on your
terminal,
all of the
following forms of the TYPE command produce the same desired result:

>TYPE TEXT. TXT
>TYPE TEXT.TXT;3
>TYPE TEXT.TXT;o
>TYPE [200120JTEXT.TXT;3
>TYPE DBO:TEXT.TXT
>TYPE DB0:[200r20JTEXT.TX1
>TYPE SY!TEXT.TXT
>TYPE SY!C200r20JTEXT.TXT~3

.::-TYPE SY; [2()0,;.,;:vJ ILXI + l Xl ;o

In most cases, you will use the first form, but if you wish to keep a
permanent record of the terminal session, you may choose one of the
more explicit forms.
In any case, the system uses the final
form
given, as that form has all the defaults supplied.
(Note that version
0 will not always be version 3, but is the highest numbered version,
which is number 3 by definition in this example.)
Table 4-1
File Types
File Type

Use

.BAS

BASIC-11 source program.

System default.

Fil~, .G?fd:C1~ni~g, ,:bcii;'g~
1#p~~~rr'i;~~; ; cbtomarads
;
~-~
.., ., -~· ~~ , •

• BAT

con\rent~iOll ~
>

•

••

~: ;:'·o;:··,,.

·'' ·.,..

:'·· .~. ~- .. _.,. ~~

,·· ,;..;:, }.,,~.,~~;

.BLD

Indirect command file used by the SYSGEN procedure
to create files
needed to build system tasks.
System default •

• B2S

BASIC-PLUS-2 source program.

• CBL

COBOL source program.

System default.

System default •
(Continued on next page)

4-4

HANDLING FILES
Table 4-1 (Cont.)
File Types
Use

File Type
• CMD

Indirect command file.

.COR

SLP file used to
convention.

.DAT

File containing data, as opposed
default.

.DIR

File is either Master File Directory
Directory. System default.

.DMP

Dump file created
default.

.FTN

FORTRAN-IV, FORTRAN-IV-PLUS,
program. System default.

• LOG

Log of batch processing session.

• LST

Listing file.

• MAC

MACR0-11 source program.

• MAP

Task Builder map file.

• MLB

Macro library.

• OBJ

Object module output
System default.

.ODL

File containing Overlay Descriptor Language
used by Task Builder.
System default.

• OLB

Object module library.

.PAT

Correction file used by assembler to create
object module. Must be specified.

• POB

Patched object module input for PAT utility;
must
be specified. See Chapter 14 of the RSX-llM/M-PLUS
Utilities Manual for more information on file types
.PAT and .POB.

• PMD

File containing Postmortem Dump of interrupted task •
System default.
See the RSX-llM/M-PLUS Task Builder
Manual for more information.

.SML

File containing system macro library.
Other macro
libraries have the type .MLB. System default, but
must be specified on input file.

• STB

Symbol definition file created by Task Builder •
System
default.
See
Section
6.4
and
the
RSX-llM/M-PLUS Task
Builder
Manual
for
more
information.

System default •

correct

File

source
to

file.

System

code.

System

User

File

Dump

Utility.

System

FORTRAN-77

source

System default •

System default •
System default •
System default •

System default •
from

assembler

compiler •
to

System default •
patched

(Continued on next page)

4-5

HANDLING FILES
Table 4-1 (Cont.)
File Types
Use

File Type
• SYS

A bootable system image.

• TMP

A temporary file.

System convention •

• TSK

Task image file.

System default •

• TXT

A text file.

• ULB

Universal library.

4.1.4

System default •

System convention •
System default •

Wildcards in File Specifications

In addition to the regular defaults for
the current device,
the
current UFD,
and the most recent version, you can use wildcards with
the commands in this chapter to set up temporary defaults for every
part of the filespec except the device name.
Simple wildcarding uses the asterisk (*)
in the filespec.

to replace all or

any

field

number

303,

For instance, the command

>DIRECTORY l303r*J
lists all files on the default volume
regardless of member number, and

with

the

group

>DIRECTORY C*'5J
lists all files on the default volume with member number 5, regardless
of group number.
The command

>DIRECTORY [*'*JTEXT.TXT
lists the most recent versions of all
files
on the default
named TEXT.TXT, regardless of the group or member number.
Likewise, the

volume

* in place of the version number means "all versions".

The command

>DIRECTORY WOM.BAT;*
lists all versions of the file WOM.BAT on the default
the default UFD.

and

The * can also be used to replace an entire file name or file type
much the same way.

mi...lUt::

volume

------..:J

l__;VllllllOUU

>DIRECTORY *.BAT
lists the most recent versions of all files with the type .BAT and any
name on the default volume and in the default UFD.
4-6

HANDLING FILES
The command

>DIRECTORY CUMMON,*
lists the most recent versions of all files with the name
any type on the default volume and in the default UFD.

COMMON

and

The examples thus far have demonstrated the
simple
form
of
wildcarding,
using the * to replace an entire field in a filespec.
Simple wildcarding works with all the commands in this chapter.
The
PRINT command accepts simple wildcarding, as does the SUBMIT command
for RSX-llM-PLUS batch processing. Many utilities also accept simple
wildcarding.
See the RSX-llM/M-PLUS Utilities Manual for information
on how each utility handles wildcards.
Most of the commands in this chapter work ~hrough PIP, the Peripheral
Interchange Program. For the PIP-related commands, DIRECTORY, DELETE,
PURGE, COPY, RENAME, TYPE, APPEND, UNLOCK, and SET PROTECTION, a more
elaborate form of wildcarding is available.
In these commands, within
file names and file types, the * can be used in a more complex manner.
The * actually means "match zero or all characters in this position."
Therefore, the command

>DIRECTORY L*+TXT
lists the most recent versions of all files with the type
.TXT whose
names start with L on the default volume and in the default UFD.
And the command

>DIRECTORY *L*.TXT
lists the most recent versions of all files with the type
.TXT whose
names include an L on the default volume and in the default UFD.
The same substitutions can also be used in file
command

types,

that

the

>DIRECTORY SNOBLO.L*
lists the most recent versions of all files with the name SNOBLO and
the type beginning with an L on the default volume and in the default
UFD.
You can use more than one wildcard in file names and file types.
The command

>DIRECTORY *F*D*.TXT
lists the most recent versions of all files with the type
names include an F and a D in that order.

.TXT

whose

In addition, the PIP-related commands permit the percent sign
(%)
to
be used as a wildcard, but only within file names and file types.
The
% means "match exactly one character in this position."
The following command, for instance

>DIRECTORY X+TXT
lists all files with the type .TXT and a single-character file name on
the default volume in the default UFD.

4-7

HANDLING FILES
The command

>DIRECTORY NOU%%81-TXT
lists all files with the type .TXT and a file name consisting of NOV
and 81 separated by two characters on the default volume in the
default UFD.
The wildcards can be combined in a single filespec.
The command

>DIRECTORY %L*T.TM%
lists all files whose names begin with a single character followed by
an L and end with a T and with a file type consisting of .TM and
another single character on the default volume in the default UFD.
Wildcarding, combined with systematic policies of UFD assignments,
file names, and file types can add considerable flexibility and
convenience to your use of the system.
In addition, the PIP-related commands, DIRECTORY, DELETE, PURGE, COPY,
RENAME,
TYPE,
APPEND, UNLOCK, and SET PROTECTION also accept several
other qualifiers that add further flexibility to these commands.
First, there are the date-oriented qualifiers:
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
These qualifiers all depend on the creation date of the file as shown
in the DIRECTORY listing. /DATE limits the operation of the command
to files created on the specified date. /SINCE limits the operation
of the command to files created on or after the specified date.
/THROUGH limits the operation of the command to files created before
or on the specified date.
/SINCE and /THROUGH can be combined to
limit the operation of the command to files created within a given
range of dates. /TODAY limits the operation of the command to files
created on the same day the command was issued.
You can enter the date in either of two forms:
dd-mmm-yy

as in 25-DEC-82

or
mm/dd/yy

as in 12/25/82

The system always displays dates in the first form.
The PIP-related commands also accept the following qualifier:
/EXCLUDE:filespec
The /EXCLUDE qualifier allows you to exclude a file or files from the
operation of the command.
The filespec argument to /EXCLUDE must
include a version number, but the version number can be *.
Wildcards
are accepted for all parts of the filespec argument to /EXCLUDE.

4-8

HANDLING FILES
4.1.5

File Protection and Volume Protection

Data privacy and system security are provided by restrictions on
access
to volumes and the files on the volumes through volume
protection and file protection= Volume protection refers to access to
a mounted volume.
You must have access rights to the volume before
you can have access to any file on the volume.
This access
is
determined through a protection code.
Once you have access to the volume, you must then have access to
the
file.
File access is also determined through a protection code.
The
volume protection code and file protection code are slightly different
because their functions are slightly different.
The differences are
noted in the following description.
Each file has a protection code, which specifies whether different
kinds of system users who may access to the file, and what they may do
to the file when they access it.
There are four kinds of users:
SYSTEM

The operating system itself, and privileged users, those
having group numbers of 10 or less.

OWNER

The user having the
created under.

file

was

GROUP

All users having the same group number as that the
was created under.

file

WORLD

All other users.

same

UIC

that

the

There are also four kinds of access to files:
READ

The user, or the user's tasks, may read, copy, print, or
type the file, and if it is a task, run it.

WRITE

The user, or the user's tasks, may add new data
file by writing to it.

the

EXTEND

The user, or the user's tasks, may change the amount
disk space allocated to the file.

DELETE

The user, or the user's tasks, may delete the file.

These forms of protection are expressed with a
single character
for
each.
The default protection applied to all files on the system that
have not been otherwise protected is:
SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R
See also the discussion of directory protection in Section 4.2.2.
Volume protection codes differ from file protection codes
in that
EXTEND protection is called CREATE protection.
The function of the
code is the same.
Either EXTEND protection or CREATE protection
refers to the right to allocate space on a volume. CREATE under
volume protection refers to your ability to allocate space for
a
new
file,
while EXTEND under
file protection refers to your ability to
allocate space within an existing file.
The default protection applied to all volumes on the system that
not been otherwise protected is:
SYSTEM:RWCD,OWNER:RWCD,GROUP:RWCD,WORLD:R

4-9

have

HANDLING FILES

CREATE
In fact, you can use a C in a file protection code or an E in a volume
protection code and the command will be accepted, but it is good
practice to use the correct protection category.

4.2

CREATING DIRECTORIES AND SEQUENTIAL FILES

The CREATE command without a qualifier enables you to create a
sequential file directly at your terminal.
The CREATE/DIRECTORY
command permits a privileged user to create a User File Directory
( UFD) •

CREATE

4.2.1

CREATE creates a sequential file and enables you to type text directly
into the file from your terminal without using an editor.

Format
CREATE
File? filespec
CREATE f ilespec

Parameter
f ilespec
Specifies the name of the file to be created.
As soon as the command is entered, the cursor
(or
moves down a line.
The file is open for input.
type goes into the file.

print head)
Any text you

When you have finished entering text, type a CTRL/Z to close
file.

the

If you wish to create an empty sequential file, simply enter
CTRL/Z first.
See examples.

the

Examples

>CREATE
Fi le'!' COPY. CMD
; Comm;::;nd filP t.c. move f:tle·::, fror;1 Hank'::, UFD tom·~ UFD

.ENr~BL.E

.LOOP:

'.'.iUB~:TJTUTIDN

'filIJ
.~1SKS

C0 F' Y

FI ~Jhe:t t":i.Je

[I B 2 : [ 3 0 3 ~ 2 6 i · i:· f ·

.GOTO L.OOF' ITT

4-10

iliITJ
rBliJ

tBill

HANDLING FILES

CREATE/DIRECTORY
In this example, the user wanted to move a number of files from
one directory to another.
With CREATE, the user created an
indirect command file at the terminal.
After entering the CREATE
command and filespec,
the cursor (or print head) moves to the
left margin.
The terminal is attached for input to CREATE.
Note
that while CREATE is executing, the RETURN key acts only as a
carriage return, and not as a means of entering commands to the
system.
No commands are accepted by DCL until after the CTRL/Z
(echoed as "Z) •
>CREATE JOE. TXT ~
Joe ca 11 e d at 4 : 3 O on Monda~ •
He " 11 b ·~ 1J d c 1-:. f r o n1 S ~.,, .t t z. E· r· 1 and on ~
Thurs d a~ , but he won " t be in the office u n ti :L Fri d <:! ':::! ::: ft. t:· r n ,:; on . (CTRL'z)

>
In this example, the user used CREATE to take notes
call.

phone

>CREATE CHUF<CHYLA. FEM ~
(CTRLZ)

In this example, the user used CREATE to create an empty file for
later use.

Notes
CREATE differs slightly in batch jobs.
See the RSX-llM/M-PLUS
Batch and Queue Operations Manual for further information.
If you create a file without specifying a version number and no
file of that name and type exists, the file is version 1.
If a
file of that name and type exists and you give no version number,
the new file has a version number one higher than the highest
numbered previous version.
If you specify a version number when creating the file,
the
system creates a file with the version number you give.
If there
is already a file with the same name, type, and version number,
that file is deleted and replaced by the file you created.
If you use CTRL/U when creating a sequential file,
the text on
the line is eliminated, but not the line itself.
In other words,
CTRL/U leaves a blank line behind when it deletes a line.
CTRL/U,
CTRL/R, and the DELETE key are the only editing
facilities available to you when creating sequential files at the
terminal.

4.2.2

CREATE/DIRECTORY

CREATE/DIRECTORY creates a User File Directory
(UFD)
on a Files-11
volume and enters the UFD into the volume's Master File Directory
( MFD) •

4-11

HANDLING FILES

CREATE/DIRECTORY (Cont.)
Privileged users can create UFOs on volumes mounted on any device.
Nonprivileged users can create UFOs only on volumes mounted on their
own private (allocated) devices.

Format
CREATE/DIRECTORY[/qualifier[s]]
Device, UFO?
[ddnn:] [[g,m]]
CREATE/DIRECTORY[/qualifier [s]]

[ddnn:] [ [g ,m]]

Command Qualifiers
/ALLOCATION:n
/PROTECTION:code
/LABEL:volumelabel

Parameters
[ddnn:] [ [g,m]]
You must specify at least one of these parameters.
If you
specify one parameter, the default volume or UFO is used for the
other parameter. You cannot create a directory that matches both
your default device and your default UFO.
ddnn:
Specifies

rrP.ntP.

the

Specifies the group and member numbers of the directory you
to create.
This parameter defaults to the current UFO.

wish

+-ho

r!oui,-.o

t.:hirh

t-h.o.

unl nm.o.

vnn

wi.~h

t-o

di rectory i~~ m;~~t;d. -·· Thl ~ -pa~~~et~~ -·d~f ~~its. to SYO: •
The volume must be a mounted, Files-11 volume.
[ g ,m]

Command Qualifiers
/ALLOCATION:n
Specifies the number of directory entries (file names) for which
space is to be allocated. n is rounded up to the next multiple
of 32.
The default is /ALLOCATION:32.
/PROTECTION:(code)
Specifies the protection code for the directory file, not for
files
in the directory.
Since the directory is a file, READ
access is the right to list the directory, and WRITE access
is
the right to create files in the directory.
If you do not have
EXTEND access to a directory, you may be denied the right to
create more than a certain number of files in the directory.
DELETE access means the right to delete the directory file.
If
you delete a directory file,
you must use the VFY utility to

4-12

HANDLING FILES

CREATE/DIRECTORY (Cont.)
recover
files
from the directory.
RSX-llM/M-PLUS Utilities Manual.

See

Chapter

the

The default is the protection co.de the disk was mounted with.
The default
for mount protection is
the protection code the
volume was initialized with.
The default system protection code is:
/PROTECTION: (SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R)
See also Sections 4.1.5 for more information on file
protection.

and

volume

/LABEL:volumelabel
Specifies that the volume label that you supply be compared with
the label
on the volume.
If
the names match, a UFD can be
allocated.
If they do not match, the command is rejected.
If you do not specify this qualifier, the
checked.

volume

label

not

Examples

>CREATE/DIRECTORY
Device'

UFD?

DB2!C30315J

This example creates UFD [303,5) on the volume mounted on device
DB2:.
Nonprivileged users can create directories only on volumes
mounted on a device they have allocated.
Privileged users can
create directories on volumes mounted on any device.

>CREATE/DIRECTORY DB2:C303,5J
This example is identical to the previous one.

>CREATE/DIRECTORY
Device, UFD?

[222,222J

This example creates UFD (222,222]

on the default device.

>CREATE/DIRECTORY
Device,

UFD?

DB6:

This example creates a directory on the volume mounted on
with the same group and member number as the default UFD.

DB6:

>c F: E A T E I D rn E c T I] f;.: yI F' fd) ru ; f J uN : t s YS : f..: wE [I ' 0 ~JN : F ' GR0 : F\ ' w0 ft'. L [I ! F: )
Dev i c e , u F D'j>

Dr.;,: 2 : [ 1 () 0 ' :I. C• 0 :.1

This example creates UFD
(100,100]
on the volume mounted on
device DR2:.
The protection code is the protection code applied
to the actual file containing the directory, DR2: [0,0]100100.DIR.
The code in this example permits privileged users to perform all

4-13

HANDLING FILES

EDIT/EDT
operations on this file:
READ (list the directory), WRITE
(add
files to the directory)/, EXTEND (alter the size of the directory
file), and DELETE (delete the directory file).
All other users
can READ (list) the directory only.
This protection mask has no
relationship to the protection applied to files in the directory,
or to volume protection, both of which may differ from the
protection applied to the directory file.
See Section 4.1.5.

4.2.3

EDIT

EDIT or EDIT[/EDT]

invokes EDT, the DEC standard editor.

EDIT/SLP invokes the Source Language Input Program,
a
program
maintenance utility.
EDIT/EDI
invokes EDI,
the Line Text Editor.
EDIT also invokes KEO and K52, if present, and any unsupported editors
you may have in your installation.
The default is EDIT[/EDT].

4.2.3.1

EDIT[/EDT]

EDIT invokes EDT, the DEC standard Editor.
for more information.

See the EDT Editor

Manual

Format

EDITf /EDTl f /qualifier fsl l infile
or
EDIT [/qualifier [s]] infile
Command Qualifiers
/[NO]COMMAND[:filespec]
/[NO]JOURNAL[:filespec]
/[NO]OUTPUT[:filespec]
/[NO]READ ONLY
/[NO]RECOVER
Parameter
infile
Specifies the file to be edited.
creates it.

If the file does not exist, EDT

You must supply a file name, but the type can be null.
Command Qualifiers
/[NO]COMMAND[:filespec]
Controls whether an EDT initialization file is read by EDT before
editing begins.
These files contain commands that alter the
default setup for EDT, such as custom line-mode commands and
change-mode key definitions.
The default is /COMMAND:EOTTNI(.EDT].

4-14

HANDLING FILES

EDIT/EDT (Cont.)
If you use this qualifier and EDTINI.EDT or some other file you
name does not exist, EDT issues no error message and continues
with the editing session.
If you have a file EDTINI.EDT and do not wish to use it, use
/NOCOMMAND qualifier.

the

/[NO]JOURNAL[:filespec]
Controls whether EDT creates a
journal file for the editing
session.
The default is to create a journal file with a file
name the same as that of the input file with the type .JOU.
You
can specify a different name by including a filespec.
The journal file consists of all editing commands and text
entered
during the session.
If the editing session ends
abnormally, such as through a system crash, or your inadvertently
typing three CTRL/Zs
in succession, the journal file is saved.
In such a case, you invoke EDT again, with the same command line
as before plus the /RECOVER qualifier.
Your editing session is
repeated and all your editing is restored.
If the editing
session ends normally, the journal file is deleted.
If you specify /NOJOURNAL, no journal
recovery is possible.

file

created

and

/[NO]OUTPUT[:filespec]
If you do not specify this qualifier, the default is to create a
file of the same name and type as the input file with a version
number one higher than the input file.
If the file is new,
EDT
creates version number 1. You can alter the name of the output
file by including a
filespec with the /OUTPUT
qualifier.
Otherwise, the qualifier need not be included.
If you specify /NOOUTPUT, you cannot exit EDT without including a
filespec in your EDT EXIT command.
/[NO]READ_ONLY
Specifies whether you wish simply to read the file or to edit it.
If your command line includes /READ ONLY, you can use the full
facilities of EDT, but you cannot exit without including a
filespec
in your EDT EXIT command.
Normally, you would use the
EDT QUIT command if you had specified /READ ONLY. The /READ_ONLY
qualifier is equivalent to a combination of /NOOUTPUT and
/NOJOURNAL.
You can use /READ ONLY to look at files to which you
have no write access.
The default is /NOREAD_ONLY, which need never be specified.
/[NO]RECOVER
Specifies whether EDT reads commands from a journal file prior to
starting the editing session. With a journal file, your editing
session can be restored if interrupted by a system crash or other
problem.
The default is /NORECOVER,
which need never be
specified.

4-15

HANDLING FILES

EDIT/~DT (Cont.)

The /RECOVER qualifier requests EDT to open the input file and
then read EDT commands and text from the file with the same file
name as the input file and the file type .JOU. The command line
with /RECOVER added to it must be identical to the command line
that initiated the original failed editing session.
This means
that if you specified an EDT initialization file, you must
specify the same file in the /RECOVER command line.
And, if you
specified a name for the journal file other than infile.JOU, you
must include the /JOURNAL qualifier with
the
appropriate
filespec.
If journaling was not enabled on the original command
line, you cannot recover the editing session.

Examples
>EDIT

File? HORNBLOW.TXT
InPut file does not exist
CEO BJ

*
This example shows the EDIT command in its simplest form.
file HORNBLOW.TXT is created during the editing session.

The

>EDIT HORNBLOW.TXT
This is the one-line form of the same command.

>EDIT/OUTPUT!UMPIRE.MAC WEAVER.MAC
1
.TITLE WEAVER

*
In this example, the user takes an existing
edits it to create a new file.

file

input

and

>EDIT/COMMAND:FORMAT RAMBLE.RNO
InPut file does not exist
CEOBJ

*
In this example, the user prepared an EDT initialization file
called FORMAT.EDT.
This file contains EDT command definitions
designed to be used with a text formatting program.
See next
example.

>EDIT/COMMAND!FORMAT!RECOVEP RAMBLE.RNO
! This is FORMAT.EDT. Version 2.4
Ambrose Bierce¥ Maintainer

During the editing session started in the previous example, the
system crashed.
Once it was back on the air, the user duplicated
his original command exactly, naming the same EDT initialization
file
and
then added the /RECOVER qualifier.
EDT begins
reproducing the entire editing session, beginning with reading in
the initialization file, the first line of which is seen in the

4-16

HANDLING FILES

EDIT/SLP
example.
All the editing commands
session have been recorded in the
read back in by EDT. The result
session is repeated up to within a

and text entered during the
file RAMBLE.JOU, which is also
is that the entire editing
few keystrokes of the crash.

If you wish to test the recovery procedure, start editing a file
and then enter three CTRL/Zs as line-mode commands. This causes
an unnatural exit from EDT, so the journal file
is saved.
You
can then duplicate the original command line, add the /RECOVER
qualifier, and watch yourself edit.

Notes
See the EDT Editor Manual for more information on journaling,
initialization files, command and key definitions, and the other
editing functions of EDT.
The qualifiers used with EDIT/EDT will not work with other forms
of the EDIT command.
If you use the /EDT qualifier, it must
appear immediately after EDIT on the command line.
Other
qualifiers can float.
You can use the MCR command to invoke EDT in a different format
that some users may find more convenient.
See the EDT Editor
Manual for the alternate command format.

4.2.3.2

EDIT/SLP

EDIT/SLP invokes the Source Language Input Program
(SLP), an editor
designed for maintaining and updating source files.
SLP enables you
to delete, replace, or add lines to an existing file or create source
files.
SLP also has an optional audit trail which enables you to keep
track of changes in the file.
See Chapter 13 of the RSX-llM/M-PLUS
Utilities Manual for more information on SLP.

Format
EDIT/SLP [/qualifier [ s] ] inf ile

Command Qualifiers
/[NO] AUDIT [: arg]
POSITION:n
SIZE:n
/[NO]CHECKSUM[:arg]
/[NO]LIST[:filespec]
/[NO]OUTPUT[:filespec]
/[NO]REPORT
/[NO]TAB
/[NO]TRUNCATE[:n]

4-17

HANDLING FILES

EDIT/SLP (Cont.)
Parameter
inf ile
The input file is the source program to be updated by SLP.

Qualifiers
/[NO]AUDIT[:(arg[s])]
POSITION: n
SIZE:n
Controls whether the output file includes an audit trail, and
optionally allows you to specify the location and size of the
audit trail.
You can specify one or both of these values.
If
you specify only one, you can omit the parentheses, but the
parentheses are required syntax if you specify both POSITION and
SIZE.
Separate the two arguments within the parentheses by a
comma (,) •
The POSITION: argument sets the starting position of the audit
trail.
The value of n can be from 0 through 132, representing
the column at which the first character in the audit trail is to
appear.
This value is rounded up to the next highest tab stop.
The default is to start the audit trail at column 80. Note that
this default causes audit trails of more than a single character
to wrap around when displayed on standard video terminals.
The SIZE:
argument sets the length of the audit trail.
The
value of n can be from 0 through 14. The default is an audit
trail of 8 characters.
The audit trail itself is defined from within SLP.
13 of the RSX-llM/M-PLUS Utilities Manual.

See

Chapter

/[NO]CHECKSUM[:arg]
Controls whether a checksum is calculated for the SLP commands.
If you specify checksum without an argument, SLP calculates the
checksum value and prints it on your terminal.
If you specify an
argument, SLP calculates the checksum and compares it to what you
have specified.
If the numbers differ, a warning message is
displayed, but the execution of SLP is not interrupted.
The default is /NOCHECKSUM.
/[NO]LIST[:filespec]
The /LIST qualifier creates a listing of a
file with line
numbers.
If you do not give a filespec, the default filespec is
filename.LST.
The default is /LIST.
file.

/NOLIST suppresses creation of the listing

4-18

HANDLING FILES

EDIT/SLP (Cont.)
/[NO]OUTPUT[:filespec]
The
Use this qualifier to change the name of the output file.
default output f ilespec is the same name and type as the input
file and a version number one higher than the highest existing
If you do not wish to override this
version of the file.
defauit, you do not need this quaiifier.
The /NOOUTPUT qualifier suppresses
file.

the

creation

output

/[NO]REPORT
Controls whether line truncations that result from audit trails
are reported.
If you specify /REPORT, you receive warning
messages on your terminal and the affected lines are marked with
a question mark (?) in place of the period (.) in the line number
in the listing file.
The default is /NOREPORT.
/[NO]TAB
Controls whether SLP replaces tabs or spaces at the end of each
record containing an audit trail.
If you specify /TAB, tabs are
inserted. If you specify /NOTAB, spaces are inserted.
The
default is /NOTAB.
/[NO]TRUNCATE[:arg]
The TRUNCATE qualifier requests SLP to truncate each record in
the input file when it creates the output file. This qualifier
allows you to delete an audit trail from a file previously
updated with SLP. If you specify /TRUNCATE without a number, SLP
truncates input records at the beginning position of the audit
trail.
If you specify a number, SLP truncates the records
beginning at the column. The value of n can be from 0 through
132.

The default is /NOTRUNCATE.
Notes
You must understand how to use SLP to use this command.
See
Chapter 13 of the RSX-llM/M-PLUS Utilities Manual for more
information.
The qualifiers used with EDIT/SLP will not work with other forms
of the EDIT command. The SLP qualifier must appear immediately
after EDIT on the command line, but other qualifiers can float.
From MCR, you can invoke SLP in a different format that some may
find more convenient. See the Utilities Manual for the alternate
command format.

4-19

HANDLING FILES

EDIT
4.2.3.3

EDIT/EDI and EDIT/editor

EDIT/EDI invokes EDI, the Line Text Editor.
The EDIT command can also
be used to
invoke KEO and K52, which are supported but not bundled
with RSX-llM/M-PLUS systems as well as various unsupported editors.
Format
EDIT [/qualifier]

[ edit-input]

Command Qualifiers
/EDI
/USING:yyy
/SOS
/TECO
/MAKE
/MUNG
/KEO
/K52
/OUTPUT:filespec
/CREATE
/[NO]READ_ONLY
Parameter
edit-input
Any valid input to the chosen editor may be supplied here.
Usually
this will be a
file specification, but anything,
including a carriage return, that is valid for the chosen editor
is a proper parameter for this command.
Command Qualifiers
Only one qualifier can be specified. This
the editor or function you wish to access.

qualifier

identifies

/EDI
Specifies EDI,
the
Line
Text
Editor,
an
interactive,
line-oriented editor used to create and maintain text and source
files.
See Chapter 2 of the RSX-llM/M-PLUS Utilities Manual for
more information on EDI.
/USING:yyy
Specifies that an editor not supplied by DIGITAL is
where yyy is the installed name of the editor.
/SOS
Specifies the unsupported editor, Son of Stopgap.

4-20

being

used,

HANDLING FILES

EDIT (Cont.)
/TECO
/MAKE
/MUNG
Specifies functions of the unsupported editor,
Corrector.

Text

Editor

and

/KED
/K52
The /KED qualifier invokes KED, the Keypad Editor, which is part
of the Forms Management System (FMS-11) software. FMS-11 is not
bundled with RSX-llM/M-PLUS systems. The /K52 qualifier invokes
a version of KED for VT52 terminals.
Other EDIT qualifiers for
use
/OUTPUT, and /[NO]READ_ONLY.

with

KED

K52

are

/CREATE,

/CREATE
Use /CREATE with EDIT/KED or EDIT/K52 when you
file that does not exist.

wish

edit

/OUTPUT:filespec
use /OUTPUT with EDIT/KED or EDIT/K52.
If you do not specify
this qualifier, the default is to create a file of the same name
and type as the input file with a version number one higher than
the input file.
You can alter the name of the output file by
including a filespec with the /OUTPUT qualifier.
Otherwise the
qualifier is not needed.
If you specify /NOOUTPUT, no output file is created when you exit
KED.
/[NO]READ_ONLY
Specifies whether you wish simply to read the file or to edit it.
If your EDIT/KED or EDIT/K52 command includes /READ ONLY, you can
use the editor, but you cannot create a new version-of the file.
/NOREAD_ONLY is the default and need not be specified.

Examples

>EDIT/EDI CHILI.MAc;2
[00066 LINES READ INJ
[PAGE

*-This example invokes EDI and names an existing input file.

4-21

HANDLING FILES

DIRECTORY
>EDIT/SOS HARRY.MAc;s
Edit!DB0t[7,7JHARRY.MAC:5
:+:

This example invokes SOS for a file that already exists.

>EDIT/SOS LONNNY.MAC
I nPut: DBO: [?, 7:J l...ONNl~Y. MfiC; l
00100 -

This example invokes SOS for a file that is being created.

>EDIT/TECO PUNK.TST

*
This example invokes TECO for a file that already exists.

>EDIT/MAKE JUNK.TST

*
This example invokes TECO for a file that does not exist.

>EDIT /MUNG DOIT
OutPut depends on file.

This example invokes TECO where DOIT is a file of TECO commands.

Notes
There are no prompts from this form of the command.
No checking of the edit-input parameter is performed by DCL.
editor does all the checking.
The unsupported editors SOS and
RSX-llM/M-PLUS systems.
Com.~ands
included only for
the convenience
implied.

4.3

The

TECO are found
on
many
to access these editors are
of users.
No support
is

MAINTAINING A DIRECTORY

The following commands provide you with the means
for keeping your
directory up to date.
Disk space on mass storage devices is an
important resource.
You should not keep files that you do not need.

DIRECTORY

4.3.1

DIRECTORY displays information on files in directories.

Format
DIRECTORY[/format-qual] [/destination-qual]

4-22

[filespec[s]]

HANDLING FILES

DIRECTORY (Cont.)
Command Qualifiers
Format
/FULL
/BRIEF
/FREE[ddnn:]
/SUMMARY
/ATTRIBUTES

Destination
/PRINTER
/OUTPUT:filespec

Other
/DATE:dd-mmm-yy
/SINCE:dd-mrnm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

Parameter
filespec[s]
Specifies the file or files
for which information should be
displayed.
If you do not supply a filespec, a complete directory
for the default UFO is displayed.
You can supply one or more filespecs, separated by commas,
directory information on the files you name is displayed.

and

You can use wildcards in place of any filespec field except the
device field.
If you do not supply a version number, only
information on the most recent versions is displayed.
However,
if you do not supply a file type, a null file type is assumed.
If you do not know the file type, use a wildcard.
You can display a directory for another UFO by supplying the uro
in this field.
You can also specify device names in the form
ddnn:
in this field.
If you name files in two directories, you should name files
for
the default UFO first.
If you name files from another device or
directory first, the defaults are canceled. See examples.

Command Qualifiers
Command qualifiers are in three groups:
1.

Format qualifiers control the appearance of the directory.

Destination qualifiers control where the
sent.

Other quaiifiers modify the list of files by creation date or
exclusion.

4-23

command

output

HANDLING FILES

DIRECTORY (Cont.)
If you do not supply a format qualifier, the display is in standard
format,
giving the file name, type, and version number, the number of
blocks the file occupies, and the date and time of creation.
If you do not include a destination qualifier, the display appears
your terminal.
If you do not include any of the other
includes all files that otherwise qualify.

qualifiers,

the

display

and

version

Format
/BRIEF
Specifies that the display give file names,
numbers only.

types,

/FULL
Specifies that the complete directory entry be
displayed,
including File ID number, blocks used and allocated, the owning
UIC, protection status of the file,
in addition to all
the
information in the standard display.
/SUMMARY
Specifies that the display give only the total number of blocks
allocated and used
for
the specified files.
If you give no
filespecs in the command; the display shows the total block~
allocated and used for the default directory.
/FREE [ddnn:]
Specifies that the display give the free space and number of free
file headers on the default device or a specified device.
/ATTRIBUTES
Displays the Record Management Services (RMS-11) attributes of a
file or files.
This display includes file name and type,
creation date and time,
file organization, protection status,
allocation information, last access date and time, record format,
record size, primary and alternate key definitions for
indexed
files,
and bucket size .for indexed and relative files.
This
qualifier invokes the RMS-11 DSP utility.
Note that this display
is produced for any file you specify in a DIRECTORY command,
whether or not the file
is an RMS-11 file.
Some display
information may not be meaningful for non-RMS files.
See the
RMS-11 documentation supplied with your system.

Destination
These qualifiers direct output to an output file or to
printer.

the

line

/OUTPUT:filespec
Specifies that the output of the DIRECTORY command be placed in a
file having the f ilespec you supply.

4-24

HANDLING FILES

DIRECTORY (Cont.)
/PRINTER
Specifies that the output of the DIRECTORY command be printed
your system's line printer.
(RSX-llM-PLUS only.)

Other
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the DIRECTORY command
to list only files created on the date given.
/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish the DIRECTORY
command to list only files created on or since the date given.
/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the DIRECTORY
command to list only files created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the DIRECTORY command to list only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the DIRECTORY
command to list only files created on the same day the command is
being issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the DIRECTORY
command not to list certain files.
The filespec argument to
/EXCLUDE can contain wildcards, but the version number must be
given, either explicitly, or as "*" wildcard.

Examples
>DIF:ECTDRY

Directors DB1:C303,51
1--NOV--82 l 4 ! :l. 6
~i +A; 1

l •

2~3·-SEP-·::32

12~29

ANIML +BAS; 1
AZ+ CM[H 5
BYE+CMD;1
CLEAN+CMD;1
DUN.CMD;4
EDT.CMD;22
LOX+CMD;1
LOG IN. CMIH 6
TI.CM[l;4

6 ·:·

24-Mi;h-·B:.2

1 l ! 5')

1.
1•
1.
1+
1.

0:?.--APH-8:~

13:03
1·2!2si
1 0 ··- J AN- 8 2 0 B : :~:: 9

:2~i--SEP--82

23-JAN-82 08 t O!:i

0 ? -- N0 I) -- 8 2 1 ~~; t ~.) ~;

1•

27-APF:-82 10 ! 21
06·-APF\-82 15: 56

1•

30-t~PR-82

4-25

08: 36

HANDLING FILES

DIRECTORY (Cont.)

F.TSK;1
G.TSK;1
PONG.TSK;2
BUZZ. TXH 2
IZZY+ TXH 1
JIVE.TXH1

4+
4.
12.
4.
2.
1+

c
c
c

25-SEP--82
25-SEP-82
25-SEP-82
12-HAR--82
06-HAR-82
16-NOV-82

12t30
12:30
12:31
09: 13
14:33
13:23

Total of 2906./3043. Blocks in 160. Files

This example shows a directory listing in the standard format.
The device and UFO are named at the head of the listing, along
with the date and the time.
All files in the UFO are listed
because the user did not supply any filespecs.
The files shown
with a C in column 3 are contiguous files, in this case, task
images. You may see files in a directory with an L in this
position, signifying that the files are locked. Files are locked
when they are closed improperly.
See Section
4.4.6
for
information on the UNLOCK command.
>DIRECTORY/SUMMARY
Storage used/allocated for
1-NOV-82 14:15
Total of 2892./3033.

Director~

blocks in 160+

DB1:[3Q3,5J

files

This example displays the output produced by the /SUMMARY
qualifier.
If the user had supplied one or more filespecs in the
command, the summary would cover the blocks used and allocated
for the specified files only.

>DIRECTORY/FREE
DBi: has 13742. blocks free, 3269280. blocks used out of 340670+
Largest contisuous space = 5173+ blocks
124420 file headers are free, 131510. headers used out of 25593.
This example displays information about the default device.

>DIRECTORY/FREE LBO!
DBO: has 6074. blocks free, 334596. blocks used uut of 340670.
Larsest contisuous space = 3520. blocks
3297. file headers are freer 22296. headers used out of 25593.

4-26

HANDLING FILES

DIRECTORY (Cont.)
This example displays information about the pseudo device LBO:.
Notice that the display gives the physical device name for the
pseudo device.
>DIR TI .CMD
Director~

DB1t[303r5J

1-MAY-82 14:17

30--APR-82 08: 36

TI.CMD;4

Total of 1./5. blocks in 1. file

This example displays information on the most recent
the file named.
See next example.

version

>DIR TI.CMDr*
Director~

DB1![303,5J

1-MAY-82 14:P

TI.CMD;4

30--APR--82
27-APR-82
27··-i;Pr.:-B2
27--APR--82

1.
l •
1•
1•

TI.CMD;3
TI.CMD;2
TI .CMD; 1
Total of 4./20.

08!36
16!32
16!29
16!2B

blocks in 4. files

This example displays information on all versions of the file
named because the user supplied a wildcard
for the version
number.

>DIR/FULL TI.CM[I
Director~

DB1![303,SJ

1-MAY--82 14!U
C300r56)

1,/5.

30-APR-82 08!36 [303,SJ

CRWEDrRWED,RWED,RJ

Total of 1.15. blocks in 1. file

This example displays full information on the most recent version
of the file named.
The number
in parentheses
is the file
identification number assigned by the system when the file
is
created.
The first number is the file number, the second is the
sequence number of the file.
The UIC is the UIC of the owner,

4-27

HANDLING FILES

DIRECTORY (Cont.)
and the final column is the protection status of the
notes.

file.

See

Protection status is listed in the order system, owner, group,
world.
See Section 4.1.5 for an explanation of protection status
and how it can be altered.

>DIRECTORY/BRIEF *•CMD
DB1![303,5J

Director~

ADV+CMD;2
AZ+CMD;5
BYE.CMD;1
CLEAN+CMD;:I.

DAY.CMDr1.
DTC.CMD;l
DUN.CM[l;4
EDT.CMD;22
LOX.CMD;l.
VTK.CMD;1

This example displays brief
information on the most
version of all files of the type .CMD in the default UFD.

recent

>DIRECTORY/TODAY
Director~

DB2:C303,5J

5-NOV-82 1 :z.: 44
Da~ of 5·-NOV--B2

05JAN82.LGI;:t.
2051CH4.MEM;1
NElJINSDC3. RNO; 7
2051CH4+MEM;2
FUT.MAI;1
NEWINSDC3. f"<NO; 6
NElJINSDC3.RN0;10
NEWINSDC4. RNO r 3
FRK.CMD;6
NEWINSDC4. RNO; 4
LOG.LOG;1

05--NOV--82
05-N0 1J--82
0 5 -- N0 t) ... 8 2
0 ~:i - N0 l..J -- 2

08!20
10: 11
1Cd05
10!12
0~.1--NOi,i--13 2
i 3: o:::i
05--NO'·..l--8 2 •)9: 55
05--N0 1J--8:2 10 t :y.:i
05--NOV--82 l1: 46
05--NQl)-82 13;43
05--NO'J-82 13: 43
05-NOl..'--82 13!43

339.
l 0+
320.

1+
9.

lO.
/ +

1•
11.

Total of 708./736. blocks in 11. files
In this example, the user asked for a directory of all files
Note that the
created the same day the command was issued.
See next example.
directory listing includes the date.

4-28

HANDLING FILES

DIRECTORY {Cont)
>DIRECTORY/TODAY/EXCLUDE!*.RNO;*
Directory DB2:c303,5]
5-NOV-82 13!45
RNO; % e~·:c l 1Jded

*DaY• of 5-NOlJ-82
05JAN82.LGI;1
2051CH4.MEM;l.
2051CH4.MEMj2
FUT.MAI;1
FRK.CMD;6
LOG. LOG H

05-·NOV-82

339.

05-NOV··82
05-NOV--82
05-NOV--82
05--NOV-82
05--NOV--82

320.
1.
1•
2+

08!20
10:11

10 ! :l 2
13 ! 0~)
13:43
1.3: 43

Total of 672./693. blocks in 6. files
In this example, the user listed all files created the day the
command was issued but excluded all files with the .RNO file
type.
Note that the filespec argument to /EXCLUDE has a wildcard
version number.
Observe also that the exclusion is noted in the
heading of the directory listing.

>DIRECTORY/ATTRIBUTES YACHT.SEQ
FILE ORGANIZATIONS
SEGUUHIAL
CREATED; 25-SEP-1982 12!32
REVISED: 15-NOV-1982 08!19 (5)
FILE PROTECTION:
CRWED,RWED,RWED,RJ
RECORD FORMAT!
VARIABLE
RECORD ATTRIBUTES!
CARRIAGE RETURN
FILE ATTRIBUTES!
ALLOCATION= 10 EXTEND QUANTITY=O
This example shows the display from the /ATTRIBUTES qualifier to
DIRECTORY.
Attributes can be displayed for any file, but the
full display has meaning only for RMS-11 files.

Director~

DB1:L303,5J

20-NOV-82 09!39

CLOCK. TSK; 3
F. TSK; 1
G.TSK; 1

TI CTAC. TSt\ ; 4

19 +

TREK.TSK; 1

4.
4

c
c
c
c
c

Total of 89./89. blocks in 5 +

4-29

15-0CT--82 0 8: 5~.:;
2 5 -- S E P -- 8 2 12!30
2 5 ··- S F F' -· El 2 1 ':) 30
0 l -- 0 L T ··- :3 2 1 ·:i 07
2 5 - S E f-' ·- 8 ::: 1 ··) 31
file~:,

HANDLING FILES

DIRECTORY (Cont.)
Directory DB1:[301,370J
20-NOV·-82 09: 39

FRONT.TXT;l
ED I TNEWS. TXH 12
OZY. TXH 3
TEXT. TXH 1
NEW. TXH 1
AWARE.TXT;2
IZZY. TXH 10

3.
, , C"

.:.. ..J •

2.
151+

o.
,,
.:..

16-JUN-82
11-SEF'-·82
11-·SEP-82
11-SEF'--82
27-JUL-·82
27-JUL-82
22-MAY-82

11:23
10:50
10:50
10!50

14:36
13:48
13:42

Total of 184./205. blocks in 7. files
Grand total of 273./294. blocks in 12. files in 2. directories

In this example, a user with the default UFO of [303,5] requested
directory information on files in two directories. The default
UFO was applied to the first files named, the *.TSK files;
these
were listed first
in the display.
The second set of files
displayed, the *.TXT files, were from UFO
[301,370], which was
explicitly specified in the command.
Note the locked file.
Compare this example with the next one.

Directorw DB1:E3Q1,370J
20-NOV-82 09:40

FRONi.TXT;1
Erl I TNEWS. TXT; 12
OZY. TXH 3
TEXT.rxr;1
NEW. TXH 1
AWARE. TXH 2
IZZY.TXT;10
ADVENT. TSK; 1
DUNGEON.TSK;2
F'ONG.TSK;2
YCLOCK.TSK;6
STAR.TS~~;2

TIC TAC. TSK; 5
VTCHS.TSK;12
XCLOCK.TSK;6
LIFE.TSK;10

..,

.Jot

25.
2.

151.

.:..

2+
151.
242.

12+
9.

102.
19 +
26+
9.
4.

c
c
c
c
c
c
c
c
c

.a,,·
•i•&i
n.-,,
.LO""..JUl't-o.:;.

11-·SEP-82
11--SEF'-82
11-SEF-'-82
27--JUL-82
27-JUL.--82
22-MAY-82

10:50

.. .-.-:r

.L .L • .:;..;>

10:50

10:50
14: :56
13!48

13 ! 42
2:3-MAY-82 14!12
21--AUG-82 09t0B

23-MAY-82
08-JUL-82
13-JUL-·82
01-AUG-82

14: l 3
12:1"?

09!0"/
11t31

06--NOV-82 15:39

03-JUN-82 16!48
0 3 -- AF' R - 8 2 13!2[!

Total of 758 .1780. blocks in 16. files
The command in this example is quite similar to the command used
in the previous one, but notice the difference in results. The
same user, with default directory [303,5], issued the command but
this time the UFO [301,370] was specified first, for the *.TXT
files.
Even though no UFO was specified for the *.TSK files,
these files were also listed from UFO [301,370] -- not from
[303,5].
This demonstrates that specifying a UFO in a DIRECTORY
command resets the default UFO for the rest of the command or
until another UFO is specified.

4-30

HANDLING FILES

DELETE
Notes
For more information on directories in general, see Chapter 3
the RSX-llM/M-PLUS Utilities Manual for more information.

The full format for directory listings may include two dates.
The first
is the creation date of the file.
The second date
indicates the last time the file was opened by the system or a
task, such as for backup.
The decimal number in parentheses
following the second date is the number of times the file has
been opened in this fashion.
Your directory is a file that you own, but which is kept in UFD
[O,O] on the same volume as your UFD. In UFD [O,O] you will find
the Master File Directory {MFD), which is a
file
named
000000.DIR.
The MFD is the directory for UFD [O,O].
All UFOs on
the volume appear in this directory in the same form.
The
directory for UFD
[303,5] is called 303005.DIR;
the directory
for UFD [7,40] is 007040.DIR, and so forth.
These directory files have file protection like all other files.
The protection is for the directory file, not for files in the
directory.
Since the directory is a file,
READ access is the
right to list the directory, and WRITE access is the right to
create files in the directory.
If you do not have EXTEND access
to a directory, you may be denied the right to create more than a
certain number of files in the directory.
DELETE access means
the right to delete the directory file.
If you delete a
directory file, you must use the VFY utility to recover files
from
the directory.
See Chapter 9 of the RSX-llM/M-PLUS
Utilities Manual.

DELETE

4.3.2

DELETE deletes specified files and
files occupy.

releases

Format
DELETE[/qualifier]
File(sj? filespec[s]
DELETE[/qualifier] filespec[s]

Command Qualifiers
/LOG
/QUERY
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yyy
/TODAY
/EXCLUDE:filespec

4-31

the

storage

space

the

HANDLING FILES

DELETE (Cont.)
Parameter
filespec [s]
Specifies the file or files to be deleted.
You must supply the name, type, and version number fields of the
filespecs of the files you wish to delete. Device and UFD fields
default to your current device and UFD.
You can use wildcards in
any filespec field except the device field.
You need not supply
a file type to delete a file with a null file type.
You can only delete files to which you have DELETE access.
To name more than one file for deletion, separate their filespecs
with commas.

Command Qualifiers
/LOG
Specifies that a list of the files deleted be displayed
terminal.

your

/QUERY
Specifies that you wish to decide which files should be deleted
on an individual basis.
Each file that is specified in the
command is namede You may enter one of four characters:
Y - Deletes file named and goes on to next file.
N - Does not delete file named and goes on to next file.
G - (Go) Deletes the file and goes on to delete all other
files specified.
Q - (Quit) Does not delete the file and exits the task.
No more files are deleted.
Remember that you can specify files by default or wildcard.
See
examples.
If you do not specify a version number, /QUERY is the
default. See the examples.
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the DELETE command to
affect only files created on the date given.
/SINCE:dd-mrnm-yy
The /SINCE qualifier specifies that you wish the DELETE
to affect only files created on or since the date given.

command

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the DELETE command
to affect only files created on or before the date given.

4-32

HANDLING FILES

DELETE (Cont.)
/SINCE:dd-mmm-yy/THROUGH:dd-mmrn-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the DELETE command to affect only files created
within that rang~.
/TODAY
The /TODAY qualifier specifies that you wish the DELETE command
to affect only files created on the same day the command is being
issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the DELETE command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,

either explicitly; or as "*" wildcard.
Examples

>DELETE
File(s)?

*·DAT;*

This example deletes all versions of all files of the type .DAT.

>DELETE FILE.FIL;1, ;J,

.TXT~5

This example deletes versions 1 and 3 of FILE.FIL, and version 5
of FILE.TXT.
Note that no filename or type is specified for
version 3, and no name for .TXT;5.

>DELETE/QUEF('f
File(s)!'" *·lMP;*
DB1![303,5JOGRE.TMP
Delete file
DB1:[303,5JTROLL.TMP;1
Delete file
DB1![303,5JORC.TMP;1
Delete file
Delete file
DB1:[303,5JELF.TMP;1
Delete file
DB1![303,5JHOBBIT.TMPil
DB1:[303151SNIPE.TMP;1
Delete file

[Y/N/G/QJ? Y

[Y/N/G/QJ? Y
[ Y /N/G/Q J? Y
[Y/N/G/QJ? N
EY /N/G/Q J? N

[Y/N/G/QJ? G

The followin~ files have been deleted:
DB1![3031SJSNIPE.TMP;1
DB1![303,5JSNOPE+TMP;2
In this example, the user specified all files having the type
.TMP in the DELETE command.
Three files were deleted at the
user's choice, and two were retained.
The user then directed
that all rema1n1ng files with the type .TMP be deleted.
There
were two more files, which were deleted and listed.

4-33

HANDLING FILES

PURGE
>DELETE *·DDC
Delete file
Delete file
Delete file
Delete file
Delete file
Delete file
Delete file

DB0:[303,5JWITCH.DOC;2
DB0:[303,5JDRY.DOC;4
DB0:[3Q3,5JPAYCHECK.DOC;1
DBO ! C:303, ~.i:Jl...OADING +DOC; ~r,
DBO!C303,5JLOADING.DOC;4
DB0![3Q3,5JLOADING.DOC;5
DB0![3Q3,5JLOADING.DOC;6

N/G/QJ'? f
LY N / G/ t1 J ';· t·'
CY N/G/Q ::! 'f y
[Y N/G/Q J ';· y
[Y N/G/QH y
[Y N/G/QJ? y
LY/N/G/QJ'? N
[Y

In this example, the user specified the file type .DOC and a
wildcard for the file name. Because no version number was given,
the DELETE command.defaulted to the /QUERY qualifier, enabling
the user to choose which files to delete.

The followins files have been
DB1!E303r5JRANGER.LST;1
DB1![3Q3,5JTONTO.LST;1
DB1![303r5JREID.LST;1
DB1![303,5JSILVER.L.ST;l
DB1!E3Q3,5JSCOUT.LST;t
DB1!C303,5JHORNET.LST;1
DB1!E303,5JKATO.L.ST;1

delet•~d:

In this example, the user specified all files with the type .LST
in the DELETE command and asked that they be listed as they are
deleted.

Notes
You must have DELETE access to delete a file.
If you wish to delete using wildcards,
it is wise to get a
directory listing using the same filespecs you plan to delete.
In this way, you can be sure you are not deleting more files than
you intend to delete.
Remember that under the default file protection on RSX-llM/M-PLUS
systems, you have DELETE access to your own files and all files
in directories with the same group number.
See Chapter 9 for DELETE commands directed to the queue manager.

PURGE

4.3.3

PURGE deletes all but the latest versions of files, and
storage space the deleted files occupy.

Format
PURGE[/qualifier[s]]
File(s)? filespec[s]
PURGE[/qualifier[s]] filespec[s]

4-34

releases

the

HANDLING FILES

PURGE (Cont.)
Command Qualifiers
/[NO]LOG
/KEEP:n
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec
Parameter
filespec[s]
Specifies the file group or file groups to be purged.
Because of the nature of the command, you cannot include a
version number in the filespec.
Multiple filespecs must be
separated by commas. Wildcards can be substituted for UFO, name,
and type fields.
You can purge any files to which you have DELETE access.
Command Qualifiers
/[NO]LOG
Specifies that the files deleted by
terminal. The default is /NOLOG.

PURGE

listed

your

/KEEP:n
Specifies that the n latest versions of a file be retained.
If you do not use this qualifier, all versions but the most
recent of a given file are deleted. That is, the default form of
the command includes the qualifier /KEEP:l. With the qualifier
explicitly stated, all but the n highest numbered versions are
deleted. PURGE assumes that version numbers are in numerical
sequence and without missing numbers. See example.
If more than one filespec is given with the /KEEP qualifier,
but the latest n versions of all files listed are deleted.

all

/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the PURGE command
affect only files created on the date given.

/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish the PURGE command to
affect only files created on or since the date given.
/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the PURGE command
to affect only files created on or before the date given.

4-35

HANDLING FILES

PURGE (Cont.)
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the
PURGE command to affect only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the PURGE command to
affect only files created on the same day the command is being
issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the PURGE command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly, or as "*" wildcard.

Examples

>PURGE
File<s)?

TEMPER,TSK

In this example, all versions of TEMPER.TSK but
deleted.

>DIRECTORY ASDIC.TM1;*, ELPASO.TEX;*
Directors DB1![3Q3,5J

20--NOV--82 l 3: 4•1
ASDIC.TM1;1
ASDIC.TM1;2
ASDIC.TM1;3
ASDIC. TM1 H
ASDIC.TM1r5
ELPASO. TEX; 1
ELPASO.TEX;2
ELPASO.TEX;3
ELPASO.TEX;5
ELPASO.TEX;6

2 0 ·· NCi 1.J ·· 8 2 l3!4l

1..

20-NOV-82 13:41

1•

20-.. NOtJ--82
20 ..··NOV···82

20--NO'J-82 13:42

l3: 41
U~4:1

n:42

2 0 -- N QI.,) -- 8 2

1.
1•
1+

20-NOV-82 13:42
20-NOV-82 l.3: 42
20-NOV-82 13:43

20-NOV-82

Total of 9./45. blocks in 10+ files

>PURGE/LOG/KEEP:3 ASDIC,TM1
The followins files have been deleted:

DB1:[303,5JASDIC.TM1;1

>
>

4-36

13:4:~

the

latest

are

HANDLING FILES

COPY
>PURGE/LOG/KEEP:3 ELPASO.TEX
The following files have been deleted:

DB1:[303,5JELPASO.TEX;1
DB1:[303r5JELPASO.TEX;2
DB1:[303,5JELPASO.TEXf3

>
>

>DIRECTORY ASDIC.TM1;*, ELPASO.TEX;*
Directory DB1:[303,5J

20-NOV-82

13:46

ASDIC.TM1;3
ASDIC.TM1;4
ASDIC.TM1;5
ELPASO.TEX;5
ELPASO.TEX;6

13!41

1•

20-·NOV--82

20-NOV-82 13: 4 l

1.
1~
1.

20-N0'..!-82

13!4~:

20-NOV-82 13!43
20-NQ\l-82 13 ! 43

Total of 4./20. blocks in 5. files
In this example, the user started with two sets of five files.
The five files named ASDIC.TMl have version numbers in order.
The five files named ELPASO.TEX are numbered 1,2,3,5,6. The user
issued a PURGE command with the qualifier /KEEP:3. versions 4,
5, and 6 of ASDIC.TMl were kept, but only versions 5 and 6 of
ELPASO.TEX.
This is because the /KEEP:3 qualifier does not save
the three highest numbered files, but rather the highest numbered
file and the next two lower numbered files of the same name in
numerical sequence.
If there had been a file ELPASO.TEX;4,
it
would have been saved.
Since there was none, the PURGE command
task exited, its work done.

Notes
You can purge any file to which you have DELETE access.

COPY

4.3.4

COPY copies files.
COPY creates a sequential file copy of one or more sequential files,
or of records with either indexed or relative file organization.

Format
COPY[/qualifier[s]]
From? infile[s] [/qualifier]
To? outf ile
COPY[/qualifier[s]]

infile[s] [/qualifier] outfile

4-37

HANDLING FILES

COPY (Cont.)
Command Qualifiers
/[NO]CONTIGUOUS
/REPLACE
/OWN
/BLOCKSIZE:n
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

Parameters
infile[s]
Specifies the input file or files to be copied.
You must have READ access to a file to copy it.
Multiple filespecs, separated by commas, are accepted.
If you
specify multiple input files,
they will be concatenated in a
single output file in the order that you specify them.
outf ile
Specifies a single output file to which the input file
is copied.

files

You must have WRITE access to the UFO to which you wish to send a
copy.
Under the default protection, you have WRITE access to
your UFO and to all UFOs with the same group number.
You can change the name, type, and version number of the file
when you enter this parameter. Wildcards in the place of the
name and the type leave the name and type unchanged.
If you use

a wildcard in either of these fields, you must use a wildcard in
both.
The output file can be created by COPY.
The output file need not
exist when you issue the command.
If a file of the same name and
type already exists, then the file you create has a version
number one higher than the highest existing version.
If you
specify a version number for the output file field, then a
file
of that version number is created.
If such a file already
exists, the operation fails~
Wildcards are acceptable for output files if the destination is
another UFO.
If you have multiple input files and use wildcards
for the output file, you create multiple output files, each with
the name and type of the corresponding input file.
You can send copies to devices as well as to UFOs.

See examples.

You can also use the COPY command to cEeate multiple
the same file with the same or different names.

4-38

copies

- z:
V.L

HANDLING FILES

COPY (Cont.)
Command Qualifiers
/[NO]CONTIGUOUS
If
this
Specifies that the output file must be contiguous.
qualifier
is not used, then only files
that are already
contiguous remain contiguous when copied.

The default is /NOCONTIGUOUS.
/REPLACE
If the output file, has the same name, type, and version number as
an already existing file at the destination, the first file is
deleted and the file you have sent replaces it. The name, type
and version number stay as they were.
/OWN
Changes the ownership of the file being copied from the source
After execution, both UICs own
UIC to the destination UIC.
copies.
If you do not specify /OWN, the original UIC owns both
If you are copying from another directory to your own,
copies.
use this qualifier.
/BLOCKSIZE:n
Defines block size for magnetic tape. n can be octal or decimal;
if decimal, you terminate n with a decimal point~ For example:
/BLOCKSIZE:25.
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the COPY
affect only files created on the date given.

command

The /SINCE qualifier specifies that you wish the COPY command
affect only files created on or since the date given.

/SINCE:dd-mmm-yy

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the COPY command
to affect only files created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the COPY command to affect only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the COPY command to
affect only files created on the same day the command is being
issued.

4-39

HANDLING FILES

COPY (Cont.)
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the COPY command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly or as "*" wildcard.
Examples

>CDPY
From? [303,4JTSKBLD.CMD
To·?" TSKBLD. CMD
This example copies TSKBLD.CMD from [303,4] to the current
and device.
The file is still owned by the source UIC.

UFD

>COPY *•BAS DKU
This example copies all files with the file type
.BAS from the
current device and UFD to the same UFD on the volume mounted on
device DKl:.

>COPY/OWN TSKBLD.CMD [303·4JBLDFIL.CMD
This example copies TSKBLD.CMD from the current UFO and device to
[303,4], assigns ownership to the destination UIC, and also
~h=nnoc
i~c
..n=mo
-... - ~n ar.n~Tf. rMn
-··-··::i-~

-~~

~-~-~-·--·~·

>COPY/CONTIGUOUS LITTER.DAT

*·*

This example creates a new version of the file
new version is contiguous.

LITTER.DAT.

The

>COPY OLD1.FIL,OLD2.FIL
NEW.ONE

To?

This example copies two previously existing files
file.

into

one

new

>COPY CHARLA.DMP TT41:
This example prints a copy of CHARLA.DMP on TT41:.
This is a
convenient means of sending messages longer than one line.
If
the terminal is busy at the time you send the copy, the copy is
held until the terminal is clear and then sent.

>COPY FLY.TXT SPIDER.TXT
This example creates the file SPIDER.TXT with the
as FLY.TXT, both on the current device and UFD.

4-40

same

contents

HANDLING FILES

RENAME
Notes
C is the short form of copy.
COPY does not affect file organization.
If you wish to change
file organization, use the CONVERT command, Section 4.3.6.
Usually, READ access is much broader than WRITE access.
Under
the default protection setup, your READ access covers the whole
system, but your WRITE access is limited to other UFOs with the
same group number. Thus, you can copy from many places that you
cannot copy to.
Also, when you copy a file, you do not copy its protection code.
Your copy has the default protection code.
Use SET PROTECTION if
you want to change the protection code of the copy.
Note that you can change the name, type, and version number of
single file as you copy it.

RENAME

4.3.5

RENAME changes the name, type, or version number of an existing file.

Format
RENAME[/qualifier[s]]
Old file name?
infile
New file name? outfile
RENAME[/qualifier[s]] infile outfile

Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yyy
/TODAY
/EXCLUDE:filespec

Parameters
inf ile
Specifies the file to be renamed.
You may give a wildcard for either the file name or the file
type, or both.
If you use a wildcard in these fields, you must
supply an entry in the version number field.
This may be a
wildcard.
If you give a wildcard for version number, all versions retain
their old version numbers.
If no version number is supplied,
only the highest version of the named file is renamed.
It has
the same version number as the old file.
If other files having
the new name exist, then you receive an error message.

4-41

HANDLING FILES

RENAME (Cont.)
out file
Specifies the new name for the file.
Wildcards leave that portion of the filespec the same as
No wildcard is needed for the version number.

before.

Command Qualifiers
/DATE:d©-mmm-yy
The /DATE qualifier specifies that you wish the RENAME command to
affect only files created on the date given.
/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish the RENAME
to affect only files created on or since the date given.

command

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the RENAME command
to affect only files created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the RENAME command to affect only files created
within that ranqe~
/TODAY
The /TODAY qualifier specifies that you wish the RENAME command
to affect only files created on the same day the command is being
issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the RENAME command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly or as "*" wildcard.

Examples
>RENAME
Old file name? INTRO.TXT
New file name? APPENDIX.TXT
In this example, the most recent
APPENDIX.TXT; 1.

version

INTRO.TXT

becomes

>RENAME IZZY.Txr;4 FIZZY+*
In this example, IZZY.TXT;4 becomes. FIZZY.TXT;l.
of IZZY.TXT are not affected.

4-42

Other

versions

HANDLING FILES

CONVERT

In this example, AMA.DOC;4 becomes AMA.DOC;ll.

>RENAME MAIN.TSK;* EXTRA.TSK
In this example, all files named MAIN.TSK are renamed EXTRA.TSK.
The version numbers remain the same, regardless of sequence and
order of file creation.

In this example, all versions of MAIN.TSK are renamed SUB.TSK.
Versions are in the order of creation, with numbers unchanged.

In this example, all files named EXHAUST of whatever type are
renamed REFRESH.
Their file types remain the same.
Note that a
wildcard is given for the input file type.
This makes an entry
in the version number field mandatory.

Notes
You cannot rename files across devices.
Using wildcards is also
yourself.

tricky.

Experiment

before

committing

CONVERT

4.3.6

The CONVERT command invokes the RMSCNV utility, which moves records
fom one file to another.
RMSCNV reads records from an input file and
writes them to an output file.
The action of RMSCNV depends on the
organization -- sequential,
relative, or indexed -- of the two files,
and on the qualifiers you include in the CONVERT command.
See the
RMS-11 documentation supplied with your system for more information.

Format
CONVERT[/qualifier[s]]
Input file? infilespec
Output file? outfilespec
CONVERT[/qualifier[s]]

infilespec outfilespec

4-43

HANDLING FILES

CONVERT (Cont.)
Command Qualifiers
/[NO]APPEND
/BLOCK SIZE:n
/[NO]FTXED CONTROL
/[NO] IDENTIFICATION
/INDEXED
/KEY[:n]
/[NO]LOG FILE[:filespec]
/[NO]MASS INSERT
/MERGE
I [ N0] PAD [ : [ # ] a r g ]
/RELATIVE
/[NO]REPLACE
/SEQUENTIAL
/[NO]TRUNCATE

Parameters
inf ile
Specifies the file that is the source of records to be written to
the output file.
CONVERT reads
input records sequentially,
regardless of the organization of the input file.
No wildcards
permitted.
outf ile
Specifie~ th~ file that is to re~eivP the records from the
input
file.
The default file organization for
the output file is
sequential.
If the output file
is not sequential, use the
/RELATIVE or /INDEXED qualifier to indicate the organization.
If
the output file is to be sequential, CONVERT can create the file;
it need not exist prior to your entering the CONVERT command.
CONVERT cannot create indexed or relative files;
these must have
been created prior to your entering the CONVERT command.
See the
RMS documentation supplied with your system.
No wildcards
permitted.

Command Qualifiers
/[NO]APPEND
Specifies that you wish RMSCNV to append records to the end of an
existing sequential file.
If the output file is not sequential,
RMSCNV ignores the qualifier.
You cannot use both /APPEND and
/REPLACE in the same command line.
The default is /NOAPPEND, but the action taken depends on the
presence of the /REPLACE qualifier in the command line.
If you
specified /REPLACE, RMSCNV performs the replace operation.
If
you did not specify /REPLACE,
RMSCNV creates the next higher
version of the file.
This qualifier is the equivalent of the /AP switch in
command line.

4-44

RMSCNV

HANDLING FILES

CONVERT (Cont.)
/BLOCK_SIZE:n
Specifies the
on magnetic
RMSCNV rounds
not specify
characters.

physical block size of an output file being created
tape.
n can be from 18 through 8192 characters.
this value up to the next multiple of 4.
If you do
this qualifier, the default tape block size is 512

This qualifier is the equivalent of the /BL switch in
command line.

RMSCNV

/[NO]FIXED_CONTROL
The
/FIXED CONTROL
qualifier
directs
RMSCNV
to
handle
variable-with-fixed-control
(VFC)
format records in either the
input file or the output file.
If the fixed-control area of the
input file and the output file are the same size, RMSCNV performs
a straightforward copy. See the RMS-11 documentation supplied
with your system for
information on how RMSCNV handles other
combinations.
If you include this qualifier and neither file
specifies VFC records, RMSCNV terminates.
This qualifier is the equivalent of the /WF switch in
command line.

RMSCNV

The default is /NOFIXED CONTROL. This means that if one of the
named files contains VFC records, the fixed-control area of each
record is ignored. That is,
if the input file includes VFC
records and the output file does not, only the variable portion
of each record is written to the output file;
if the output file
includes VFC records and the input file does not, data is written
only into the variable portion of each output record.
/[NO]IDENTIFICATION
Requests that RMSCNV print its current version number and patch
level on your terminal.
See the RMSCNV documentation for more
information.
This qualifier is the equivalent of the /ID switch in
command line.

RMSCNV

The default is /NOIDENTIFICATION.
/INDEXED
The /INDEXED qualifier informs RMSCNV that the output is of
indexed orqanization.
Reqardless of their organization, all
input files-are read sequentially.
RMSCNV reads each record from the input file,
then applies the
output file's record format, that is, key placement within the
record, to the data.
If you do not specify the /KEY qualifier
with
a value, the key of reference is the primary key;
otherwise, it is the key you specify.

4-45

HANDLING FILES

CONVERT (Cont.)
This qualifier is the equivalent of
RMSCNV command line.

the

/FO:IDX

switch

Indicates the key that establishes the order in which records
read sequentially from an indexed input file and written to
output file.
n can be from 0 through 9.
The default is n=O
indicates the primary key;
n=l is the first alternate key;
is the ninth alternate key.

are
the
and
n=9

See the RMSCNV documentation for more information.
/KEY[ :n]

This qualifier is the equivalent of the /KR switch in
command line.

RMSCNV

/[NO]LOG[:filespec]
Directs RMSCNV to summarize processing in a log.
If you do not
include a
filespec,
the log appears on your terminal.
I f you
name a file, that file will be created and written to by RMSCNV.
The log includes the following elements:

The command string in RMSCNV format.
same as DCL format.

Copies of all error messages produced during execution.

An indication of any duplicate-key problems.
If the loq
is
appearing on the terminal, the indication consists only of
the following message:

This will

not

the

SOME DUPLICATE RECORDS NOT WRITTEN
If the log is being written to a file,
RMSCNV supplies the
indicator DUP RCD= followed by the first 72 characters of the
record that could not be written.
This qualifier is the equivalent of the /SL switch in
command line.
The default is /NOLOG meaning that
appear on your terminal.

only

normal

error

RMSCNV
messages

/[NO]MASS_INSERT
Directs RMSCNV to activate the RMS-11 mass insert I/O technique
and then use sequential put operations to insert records into the
output file.
This is the equivalent of the /MA switch
line.

RMSCNV

command

The
default
for
nonsequential
file
organization
is
/NOMASS INSERT.
See the RMS-11 documentation supplied with your
system for further information.

4-46

HANDLING FILES

CONVERT (Cont.)
/MERGE
Directs RMSCNV to copy records from the input file into
output file.
Both files must be of the same organization.

the

/[NO]PAD[: [#]arg]
Directs RMSCNV to pad records read from the input file to the
output file's record length before writing them to the file.
If
you specify the qualifier without an argument, the pad character
is null.
If you do not include the number sign (#), the argument
can be any printing ASCII character except:
the number sign,
question mark (?), or commercial-at sign (@).
If you include the
number sign (#), n can be an octal number from 0 through 377,
representing the full ASCII character set.
This enables you to
use the three excluded characters as pad characters by specifying
43 for #, 77 for ?, and 100 for @.
Use this qua11t1er only
fixed-length records.

when

the

output

file

This qualifier is the equivalent of the /PD switch in
command line.

specifies
an

RMSCNV

/RELATIVE
The /RELATIVE qualifier informs RMSCNV that the output file is of
relative organization.
Regardless of their organization, all
input files are read sequentially.
The /RELATIVE qualifier is the equivalent of the
in an RMSCNV command line.

/FO:REL

switch

RMSCNV reads records from the input file and writes them into
successive record cells of the output file, beginning with cell
1.
If RMSCNV encounters a cell containing a record,
it
terminates with an error message.
All records written to that
point are in the output file.
You should examine the two files
to determine how far the processing went.
See the RMS-11 documentation supplied with your system
information.

for

/[NO]REPLACE
The /REPLACE qualifier directs RMSCNV to supersede an existing
sequential file.
RMSCNV replaces a file in the output account
with the same file name, type, and version number.
You cannot
use /REPLACE and /APPEND in the same command line.
The /REPLACE qualifier is the equivalent
command line.

/SU

RMSCNV

The default is /NOREPLACE, but the default action depends on
whether the command line includes an /APPEND or not.
If you
specify /APPEND, RMSCNV performs the append operation.
If you do
not specify /APPEND,
RMSCNV creates the next higher version of
the file.

4-47

HANDLING FILES

CONVERT (Cont.)
/SEQUENTIAL
The /SEQUENTIAL qualifier informs RMSCNV that the output file
is
of sequential organization.
Regardless of their organization,
all input files are read sequentially.
The default output file
organization for RMSCNV is sequential.
This qualifier is the equivalent of
RMSCNV command line.

the

/FO:SEQ

switch

If you ~o not specify either the /APPEND or /REPLACE qualifier,
and the output file is sequential 1 the output file need not exist
before you issue the CONVERT command.
If the output file does not exist, RMSCNV creates an output file
with the record attributes of the input file.
RMSCNV then reads
records from the input file and writes them sequentially into the
new output file.
If the output file already exists, and the command does not
include the /APPEND qualifier,
RMSCNV creates the next higher
version of the file.
RMSCNV then reads records from the input
file and writes
them sequentially into the new version of the
output file.
If the output file exists and you specify the /REPLACE qualifier,
RMSCNV reads records
from the
input file and writes them
sequentially into the output file, starting with the beginning of
the file.
If the output file exists and you specify the /APPEND qualifier,
RMSCNV reads records from the input file and writes them into the
output file, starting with the record position following the last
record already in the file.
/[NO]TRUNCATE
Directs RMSCNV to truncate records read from the input file to
the output file's
record length before writing them into the
output file.
The trailing bytes of the record are truncated.
The default is /NOTRUNCATE.
If you do not specify /TRUNCATE and
the input records are too long,
RMSCNV terminates with the
following message:
CON -- Input and output record sizes do not correspond
Examples

>CONVERT
Input file'? FOO.BM\
Output file? POOH.BAR
The output file does not exist.
RMSCNV creates the sequential
file POOH.BAR and copies the records from FOO.BAR into it.

>CONVERT FOO.BAR POOH.BAR
This example is the equivalent of the previous one.

4-48

HANDLING FILES

CONVERT (Cont.)
>CONVERT/INDEXED GRIZZLY.BAR CROW.BAR
RMSCNV reads each record of the
input
file
GRIZZLY.BAR
sequentially and examines the contents of the primary key field,
which is defined as an attribute of CROW.BAR.
RMSCNV then
inserts the record into CROW.BAR.

>CONVERT/RELATIVE/KEY!] SAND.BAR MAX.BAR
RMSCNV reads the indexed input file SANDcBAR, using the first
alternate key of the file to establish the sequence of access.
Then RMSCNV writes the records sequentially into an empty
relative output file MAX.BAR, starting with record cell 1.
Note that the /RELATIVE qualifier refers to the organization of
the output file and the /KEY qualifier refers to the organization
of the input file.

>CONVERT/APPEND/SEQUENTIAL/KEY!2 RUNNING.BAR CORNER.BAR
RMSCNV reads the indexed input file RUNNING.BAR, using the second
alternate key of the file to establish the sequence of access.
Then RMSCNV appends the records at the end of the existing
sequential output file CORNER.BAR.
If the /APPEND qualifier had not been specified,
RMSCNV would
have created the next higher version of CORNER.BAR and written
the records from RUNNING.BAR into it.

>CONVERT/RELATIVE/FIXED_CONTROL MAMA.BAR PAPA,BAR
RMSCNV reads fixed-length records from the indexed
input file
MAMA.BAR,
using
(by default)
the primary key of the file to
establish the sequence of access.
The RMSCNV writes the records
sequentially in a VFC format
into the existing relative file
PAPA.BAR.
Record format is an attribute of each file.
As each
record is written, the first bytes become the fixed control area.

>CONVERT/TRUNCATE/BLOCK_SJZE:1024/APPEND/KEY:9 BRER.BAR
MM3!BRER.BCK

OutPut file?

RMSCNV reads the indexed input file BRER.BAR, using the file's
ninth alternate key to establish the sequence of access.
The
RMSCNV writes the records to magnetic tape, truncating them to
the output file's record length before adding them to the end of
the existing file, and formatting the tape blocks to 1024 bytes
each.
Notes
You must have a clear understanding of RMS-11 and the various
forms of file organization it supports before using the CONVERT
command. See the RMS-11 documentation supplied with your system
for further information.

4-49

HANDLING FILES

TYPE
Sequential files used with the CONVERT command have been
by FCS.

created

The CONVERT command replaces some functions of the COPY and MERGE
commands in the previous release of RSX-llM-PLUS DCL.

4.4

OTHER FILE-RELATED COMMANDS

The commands in this section perform varied actions on your
files.
The TYPE command displays files on your terminal.
The PRINT command
prints files on the system line printer.
The APPEND, MERGE, and SORT
commands alter the contents of certain files.
The DIFFERENCE command
displays the differences between two files
and
the UNLOCK command
unlocks locked files.

4.4.1

TYPE

TYPE prints selected files on your terminal.
Format
TYPE[/qualifiei[s]]
File(s)?
filespec[s]

Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec
Parameter
filespec[s]
Specifies the file or files to be printed on your terminal.
You can specify any file to which you have READ access.
The file name and type must be specified explicitly or with a
wildcard
(*).
If no version is specified,
the most recent
version is printed.
A wildcard in any field
prints every file
that matches otherwise.
Both the * and the % wildcards are
accepted.
You can also specify a device and UFO.
If you
fields default to the current device and UFO.
Multiple filespecs must be separated by commas.

4-50

not,

these

HANDLING FILES

TYPE (Cont.)
Command Qualifiers
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the TYPE
affect only files created on the date given.

command

The /SINCE qualifier specifies that you wish the TYPE command
affect only files created on or since the date given.

/SINCE:dd-mnun-yy

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the TYPE command
to affect only files created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the TYPE command to affect only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the TYPE command to
affect only files created on the same day the command is being
issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the TYPE command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly or as "*" wildcard.

Examples

>TYPE
File<s>? LOGIN.CMD
.ENABLE QUIET
.IF <CLI> EQ •McR• SET /DCL=TI:
SET TERMINAL LOWER
ASSIGN DBl t

SYO!

@AZ
This example prints the file LOGIN.CMD from
and UFD on your terminal.

the

current

device

the

current

device

>TYP C303,12JLOGIN.CMD
.IF <CLI> EQ "MCR" ASN DB1:=SY:
.IF <CLI> EQ "DCL" ASSIGN DB1! SYO:
TYPE LOGIN.T:X:T
TYPE A.A
SET /DCL=TI:
This example prints the file LOGIN.CMD from
and UFD [303,12] on your terminal.

4-51

HANDLING FILES

PRINT
>TYPE C*'*J*.FIL;*
This is the bes1nnin~ of a file named ARTHUR.FIL.
It soes on for several lines.

THIS MARKS THE INITIATION OF A FILE CALLED ALBERT.FIL.
IT TOO CONTINUES AT SOME LENGTH.

Now comes a file that starts like this called Z.FIL.
And some more.

At lastr we reach the besinnins of a file named FILLIE.FIL.
Asain some more text and then
The last two lines of FILLIE.FIL.

zzzzzzzzzzzzzzzzzzzzzzzzzzzz
>

This example prints on your terminal all versions of
having the type .FIL located on the current device.

all

files

Notes
In general, RSX-llM/M-PLUS documentation uses the term "print" to
refer to any output sent to a terminal and "type" to refer to any
user input from a terminal.
The name of the TYPE command
is an
exception to this rule.
If you are typing multiple files, the CTRL/O feature works
in a
slightly different fashion. When you enter a CTRL/O, output is
discarded until you type another CTRL/O or until the beginning of
the next file
is reached, whereupon output is sent to your
terminal again.
This leaves you free to use CTRL/O on a
file-by-file basis.
You can type any file, but normally only
readable.

ASCII

text

files

are

4.4.2

PRINT queues files for printing on a line printer.
It can also be
PRINT defines a QMG
used to queue jobs for other output devices.
print job.

Format
PRINT[/qualifier[s]]
File(S) filespec[/qualifier[s]] [, filespec[s]]
PRINT[/qualifier(sJ 1 filespec[/qualifier[s]] [, filespec[s]]

4-52

HANDLING FILES

PRINT (Cont.)
Command Qualifiers

File Qualifiers

/[NO]DELETE
/COPIES:n

'I [ N~l/I'~ANSF:~R

'/['NO l T,RANS'FER

/DEVICE:ddnn:
/[NO]HOLD
/JOB COUNT:n
/[NOJJOB PAGE
/QUEUE:queuename
/[NO]UPPERCASE
/[NO]LOWERCASE
I [NO] WIDE
/PAGE COUNT:n
/NAME:jobname
/PRIORITY:n
/FORMS:n
/LENGTH:n
/[NO]RESTART
/[NO]FLAG PAGE
/AFTER: (dd-mrnm-yy hh:mm)
(mn/dd/yy hh:mm)
I [NO]WIDE
Parameter
filespec[s]
Specifies the file or files to be printed on the line printer.
Multiple filespecs must be separated by commas.
The * can be used in UFD, name, type, and version number
fields,
but only to stand for the entire field.
Wildcarding of the form
L*.TXT is not accepted by PRINT, nor is the % wildcard accepted.
If your filespec includes no file type, the default file type
.LST.

Command Qualifiers
/[NO]DELETE
Specifies that files be deleted or not deleted from the directory
after they are printed.
The default is /NODELETE.
The /[NO]DELETE qualifier to the filespec can be used to override
this qualifier for a given file in a list of filespecs.
/COPIES:n
Specifies the number of copies to be printed.
The default
is
/COPIES:!.
If your PRINT command includes this qualifier and
specifies more than one file,
the resulting QMG print
job
consists of the specified number of copies of the first file
named, followed by that many copies of the second file,
and so
on.
If you wish to print multiple copies of files by sets, use
the /JOB_COUNT qualifier.
See the examples.

4-53

HANDLING FILES

PRINT (Cont.)
The /COPIES:n qualifier to the filespec can be used to
this qualifier for a given file in a list of filespecs.

override

'{,{J.'IQ1~ TJ{'AcNp;E':E;R ..·

·:t i':l'.:'.::1:1"T;r!a;ntSif~r,s1· ;spoo1li:h'9; o'f, .·a, :fHe from

,;;; '.'·,,;/:tp,at ; a.evJc~ .ls; :no,t guhl,ic • .~'LV.&.U~'"'.L,..L..Y;•l1
.::;e· :;-~·l"·!·;a·''.r~ ;pP~
.. ·i'e~f·jtq'. ;:f?~
. :. .·.; ~d:O,:· qie~ide, .SJ~:
~·~,~~

:,.:c'

·,

Iswi ;tbli'. 'daol .;bJ· over:r:idden

· .tl··),01'.inhfis' ·

, :IL . ;,:;.1·~j/i~~~~SFj~~

, :)'

·I.·;:~·f,:. :'.~~: ,~®x~~ea.
-.,~·,:

)

;,.

;

<· .:' . '.:'·n~hlj3~I qu'qli~.ie·t:

'tor

/DEVICE:ddnn:
The /DEVICE qualifier specifies that you want the file printed on
a particular device.
/[NO]HOLD
The /HOLD qualifier specifies that you wish the QMG print job to
be held in its queue until you release it.
See the RELEASE/JOB
or RELEASE/ENTRY commands in Chapter 9,
or the RSX-llM/M-PLUS
Batch and Queue Operations Manual.
The default is /NOHOLD.
/JOB_COUNT:n
Specifies the number of sets of files you wish printed.
The
default is /JOB COUNT:l.
If your PRINT command includes this
qualifier and specifies more than one file,
the resulting QMG
print job consists of a set consisting of the files named in
order, followed by another set, and so on.
If you wish to print
multiple copies of one or more files, but not in sets, use the
/COPIES qualifier.
See examples.
/[NO]JOB_PAGE
Specifies whether you wish a
job flag page printed at the
beginning of the QMG print job.
The default is /JOB PAGE.
Use
/NOJOB PAGE when you are printing on special forms, or- otherwise
do not wish to include a job flag page.
See the /[NO]FLAG PAGE
qualifier for controlling file flag pages.
Figure 4-2 shows- the
difference between job flag pages and file flag pages.
/QUEUE:queuename
Specifies the name of the print queue in which the job is
placed.
The default is the PRINT queue.

/[NO]UPPERCASE
Specifies that the print job can be sent to a line printer
without the lowercase character set.
The default is /UPPERCASE.

4-54

HANDLING FILES

PRINT (Cont.)
** RSX•l IM•P~US VZ **
** RSX•!IM•P~US Ve **

012345678'101 Zl451>7S9

a I Zl45H8901 ll45b78'1
e :Zl45b7e9012l451>7S'I
al2345b78'10 I ZJ45b 78'1

..
••
........
..
•• ••
....

WW
WW
WW
WW

wwww

wwo

~·~·

WW
WW

IIIllI
!IIIII
II
II
II
l!
II
II
Ii
ll

II
ll
Ill!ll
!IIIII

RRRRRRRR
RRRRRRRR
RR
RR
RR
RR
RR
RR
RR
RR
RRRRRRRR
RRRRRRRR
RR RR
RR RR
RR
RR
RR
RR
RR
RR
RR
RR

IIII!I
!IIIII

ZZZZZHZZZ

zzzzzzzzzz
zzzzzzzzzz
zz
zz
zz
zz
zz
zz
z.z
zz
zz
zz
zzzzzzzzzz
zzzzzzzzzz

zzzzzzzzzz
zz
lZ
zz
zz
zz
zz
zz
zz
zz
zz
zzzzzzzzzz
zzzzzzzzzz

TT
TT
TT
TT
TT

ii
II
II
III! II
!IIIII

TTTTTTTTTT
TTTTTTTTTT
TT
TT
TT
TT
TT

xx
xx

TTTTTTTTTT
TTTTTTTTTT
TT

TT
TT
TT
TT

xx
xx
xx
xx

xx
u
xx

TT
TT

xx
xx

01234507aqe123456 789
01Zl451t78901 Zl45b78'1
01ZJ45o78'1e1 i!l45o78'1

EE
EEEEEEEEEE
EEEEEEEEEE

xx
xx

Bl2345b7HllZ3aSUl9
3 ll3~5~7Uil1ii;ii5"7ii
Bl234Sb7Hei2U5•7H
e!Z345978'112Uh7H

10129153

ssssssaa
sssssssa

ssssss
ssssss

ssussu
ssssssu

SS
SS
SS
SS

YY
yy
yy
yy
yy
yy
yy

VZ **
Ve••
Ve**
VZ **

[1, 100] !ZlY
• NO PAGE LIMIT
FORM 10 • ~ORMA~ HARDORE FORMS
NO IMPl.IED FORM FEED
DBZI [7, 100] !ZZY, TXT JI

ZS•JAN•U
25•Jl"•U
25•JAN•8Z
ZS•JAN•82

11129153
191Z915J
l01i! . . s3
U1Z<1153

1112h5b7891112345U89
aUh5b78'11123459789
111234Sb7H&l2US"719
lli!34Se789912345"719

DBel [7, 100] IZZY, TXTJ I
COPY I OF I
DELETION NOT SPECIFIED

25•JlN•8Z
25•JlN•82
25•JlN•82

10lii!'ll5'1
1012 . . 59
U1Z9159

11I2l45078'& IZ3a5UH
lllill45b7899123a5b789
II IZ345"789i11 i!345b719

25•Jll\1•8e
Z5•JAN•82
i!5•JAN•8i!

UIZ915'1
IBIZ9t59
U129t59

11 IZ34Sb7891112345b789
01Zl45b78'11! 2345b78'1
Iii Zl415"78'19 I Z345b78'1

yy
yy
YY
YY

yY
yY

yy
yy

YY
yy

xx
xx

1812 . . SJ
1Sii!915J

Z5•JlN•82

yy
yy

YY
YY

EE
EE

yy
yy

YY
yy
yy
yy
yy

""
,,,,

I II I
I II I

RR
RR
RRRRRRRR
RRRRRRRR
RR RR
RR RR
RR
RR
RR
RR
RR
RR
RR
RR

:z;iQ;SJ

ZS•,/lN•82
2S•JAN•82

SS
SS

25•,llN•U

yy
yy

** RSX•llM•P~US Ve**
** RSX•llM•PLUS VZ **
** RSX•llM·P~US Ve **

II
II
II
II
II
II
II
II
!!III!
!III!!

RRRRRRRR
RRRRRRRR
RR
RR
RR
RR
RR
RR

0 IZ345b78'1~ I i!345b78"
1112345b78'101 i!345b789
111i!l451o78'10I23451>789

EEEEEEEEEE
EEEEEEEEEE
EE
EE
EE
EEEEEEEE
EEEEEEEE

** RSX-llM•P~US
** RSX•llM•PLUS
** RSX•llM•PLUS
** RSX•llM•PLUS

zzzzzzzzzz
zzzzzzzzzz
zz
zz
zz
zz
zz
zz
zz
zz
zz
zz
zzzzzzzzzz
zzzzzzzzzz

oa.z1 c1, !Ul !ZZY. n:r n

TT
TT
TT
TT

zzzzzzzzzz
zzzzzzzzzz
zz
zz
zz
zz
zz
zz
zz
zz
zz
zz
zzzzzzzzzz
zzzzzzzzzz

NO !MP~!ED ~ORM HED

TTTTTTTTTT
TTTTTTTTTT

91Zl45b7890 UJ45b79'1
B!Zl45b7990! ZJ45b78'1
U Z345b 78'10123451> 789
91 Z345b78'1~ I i!l45o 78'1

II 1111
!III!I
II

[7.189] IZZY
• NO PAGE ~IMIT
'ORM •0 • ~OR•AL ~ARDURE FOP.~!

** RSX•iiH•PLUS ¥2 u
** rUX•1JM•PLU9 Y2 **

TT
TT

;;;;

,,",,"
,,,,
,,
,,"

** RSX•llM•PLUS Vi!**
** RSX•llM•PLUS VZ **
** RSX•llM•HUS V2 **

11
II
1111
1111
II
11
ii
11
11
11
II
II
111111
111111

DB21[7,100}1ZZY,TXTJ1
COPY I OF 1
DELETION NOT SPECIFIED

ZK-563-81

Figure 4-2

Job Flag Page and File Flag Page

4-55

HANDLING FILES

PRINT (Cont.)
/[NO]LOWERCASE
Specifies that the print job must be sent to a line printer
The default is /NOLOWERCASE.
having the lowercase character set.
/PAGE_COUNT:n
Sets a limit on the number of pages the job may produce,
from 1 through 32767.

ranging

Without this qualifier, the number of pages is unlimited (n=O).
/NAME:jobname
Specifies a name for the print job.
alphanumeric characters.

Your job name

can

nine

If you specify a job name, that name appears on the flag page at
the beginning of the printed output.
Otherwise, the file name of
the first file is used as the job name.
The job name also appears in the SHOW QUEUE display.
name includes the UIC under which it was entered.

The

job

There can be more than one job of the same name, but each job has
a unique entry number which appears in the SHOW QUEUE display.
/PRIORITY:n
Sets the queue priority of the print job.
For nonprivileged
users,
n can be from 0 through 150.
Privileged users can set n
up through 250.
The default is 50.
The Queue Manager prints the highest priority jobs first.
When
two jobs have the same priority, the job that has been in the
queue longest is printed first.
/FORMS:n
Specifies the type of form on which the job must be printed.
n
can have a value from 0 through 256.
The default is O.
See your
system manager for details on how to specify the particular forms
used at your installation.
/LENGTH:n
Sets the length of a logical page; n can be any number from O
through 255.
The default is n=O.
If you set a length, a form
feed is automatically generated if one is not found within n
lines.
When you set the length at
length is unlimited.

the

default,

the

logical

page

This qualifier has no effect on how the printer handles form-feed
characters.
A form feed still moves the printer to the top of

4-56

HANDLING FILES

PRINT (Cont.)
the next physical form, such as the perforation in a sheet of
line-printer paper.
This qualifier simply adds the requirement
that the printer move to the top of the next physical page if no
form-feed character
is encountered within n lines. See the
example using /LENGTH.
/[NO]RESTART
Controls requeuing of your job if it is stopped or aborted
being processed.
If /RESTART is specified,
beginning if it is aborted.
/NORESTART is the default.
job is active,
the job
printer is started.

your

job

starts

again

from

while
the

If the printer is stopped while your
picks up where it left off when the

in neither case are you missing any
/RESTART your job is all in one piece.

your

job,

but

with

If, however, the paper jams in the line printer, the operator
must see that your job is restarted above where the jam began.
/[NO]FLAG_PAGE
Adds flag pages to each file in your print job. With /FLAG PAGE,
the number of flag pages is equal to the number of job flag-pages
that precede the job.
With /NOFLAG PAGE (the default), your job is still preceded by a
job flag page, but the files in the job are printed without any
file flag page, separated only by form feeds.
You can suppress
the job flag page with the /NOJOB PAGE qualifier.
Figure 4-2
shows the difference between the job flag page and the file
flag
page.
/AFTER:

(dd-mm-yy hh:mrn: [ss])
(rnm/dd/yy hh:rnm: [ss])

Blocks the job until after the specified time. Depending on the
print queues at that time, your job may be run immediately, or
later, when its turn comes up in the queue.
The parentheses, hyphens (or slashes), colons, and the space
between the calendar and clock fields are all necessary syntax.
Note that a space is used only between the calendar and clock
fields.
The space is not necessary if either field is omitted.
You can specify the calendar field in either of two formats:
dd-mrn-yy

Uses a 1- or 2-digit number for the day,
the first
three letters for the month, and two numbers for the
year.

mm/dd/yy

Uses a 1- or 2-digit number for the month, a 1- or
2-digit number for the day, and two numbers for the
year.

4-57

HANDLING FILES

PRINT (Cont.)
If you leave out the calendar field,
current date.

the

yy must be between 77 and 92.
defaults to the current year.

leave

If you

day

defaults
it

out,

the

year

hh:mm:ss is the hour, minute, and second.
If you leave out the clock field, the time defaults
on the given date.

00:00:00

ss need not be

given~
It defaults to 00.
In fact,
you cannot
specify ss.
If you do, it is checked for syntax only.
The Queue
Manager always takes a few seconds to start the job.

Specifying a time using /AFTER is equivalent to issuing a
Print
command at that time.
The job may still have to wait in its
queue to be printed.

I [NO] WIDE
The /WIDE qualifier specifies that the file must be printed on a
processor that has been
initialized /WIDE.
The default is
/NOWIDE.

File Qualifiers
These qualifiers are used to override the corresponding command
qualifiers when you have given multiple filespecs as parameters
to the PRINT command.
/COPIES :n
Overrides the /COPIES
particular filespec.

command

qualifier

when

attached

Overrides the /[NO]DELETE command qualifier when
particular filespec.

attached

/[NO]DELETE

/{NO]TR~FER '.

dve.r'.r;i'.aes1 tne /:[:NO]~R~SFER command qual:ifier when attached to. a
partl~;d"lalr ·; f,f~~~11ec ;'.·~ .RSX-llM-PLUS Syst'ell\9' •.
Examples
>PRHH

File<s>?

PASHA.CMD

PRI -- Job 305, name •PASHA

, submitted to aueue 'PRINT '

This example prints the most recent version of PASHA.CMD from the
default device and UFD on the line printer.
The Queue Manager
returns a message confirming that the job has been submitted and
giving an entry number.
You can use this entry number in QMG
commands.
See Chapter 9, and also the RSX-llM/M-PLUS Batch and
Queue Operations Manual.

4-58

HANDLING FILES

PRINT {Cont=)
>PRINT/COPIES:20
File<s>? PASHA+CMD
PRI -- Job 706' name •PASHA

•, submitted to Gueue 'PRINT •

This example prints 20 copies of PASHA.CMD.
They are
end-to-end with no flag page except at the beginning.

printed

>PRI/COP:20/FLAG_PAGE PASHA+CMD
' submitted to oueue 'PRINT •
PRI -- Job 321, name "PASHA
This example prints 20 copies of
page.

PASHA.CMD,

each

with

flag

>PRIN/COPIES:2 DAVID.TXT, DAN.TXT
submitted to aueue "PRINT •
PRI -- Job 18, name 'DAVID
This example prints two copies of DAVID.TXT followed by two
copies of DAN.TXT.
It does not print two sets of one copy of
each file.
If you wish to print sets of files,
see the next
example.

>PRINT/JOB_COUNT12 DAVID.TXT· DAN.TXT
PRI -- JOB 311~ NAME "DAVID
•, submitted to aueue "PRINT •
This example prints a set consisting of a copy of DAVID.TXT
followed by a copy of DAN.TXT, and then prints another set of
DAVID.TXT followed by DAN.TXT.

>PRI/FLAG PASHA.CMD, RAJAH.CMD, SHEIK.CMD
PRI -- Job 999, .name "PASHA
submitted Lo aueue "PRINT "
This example prints one copy of each file, each with its own flag
page.

>PRI/NAME:ARABY/FLAG PASHA.CMD, RAJAH.CMD, SHEIK.CMD
PRI -- JOB 805, NAME "ARABY
submitteJ to Gueue 'PRINT •
This example prints one copy of each file, each with its own flag
page,
and gives the name ARABY to the job as a whole.
The name
ARABY appears in the print queue and at the head of the entire
printed output.

>PRINT/LENGTH:60 GLADRAG.MAC
PRI -- Job 22, ~ame "GLADRAG

, submitted to

u~eue

"PR[NT •

This example prints a single copy of the file GLADRAG.MAC.
This
is a source program file without form-feed characters in it.
The
user wants to print it on line-printer paper, a physical form 66
lines long.
To avoid printing over the perforations, the user
has specified a logical length of 60 lines.
Each time 60 lines
have been printed, the logical page is complete and the printer
moves to the top of the next physical page.

4-59

HANDLING FILES

PRINT (Cont.)
If the file had form feeds in it, the printer would move to
the
top of a physical page each time it encountered a form feed and
each time it printed 60 lines without encountering a form feed.

>PRI/COPIES:20 MOB.CUR, RIFRAF.COR, RABBLE.COR/COP:19, PROLE+COR
PRI -- Job 77, name •MOB
•, submitted to aueue •PRINT "
This example prints 20 copies each of MOB.CCR, and RIFRAF.COR, 19
copies of RABBLE.CCR, and then 20 copies of PROLE.COR.

>PRI/DELETE LASER.TST, PHASER.TST, RAZOR.TST/NODELE
PR! -- Job 406, name "LASER
submitted tu aueue "PRINT "
1

This example prints the three files and
from the current UFD.

deletes

the

first

two

Only the versions specified in the PRINT command are deleted,
in
this case, the most recent versions of LASER.TST and PHASER.TST.

>PRI/AFTER:<4-JUL-82 13:13> CONST.CON
PR! -- Job 809, name •coNST
•, submitted to

~ueue

•PRINT •

This example blocks the job in its queue until the specified date
and time.
The file itself remains in its UFO.
Deleting the file
from its UFD does not take it out of the queue, but does prevent
it from being printP~-

>PRI/AFTER!<17!00) GUNGA.DIN
PR! -- Job 765, name 'GUNGA

•,submitted to

OUE?t.:C

'F'F:!NT.

This example prints the file after 5 P.M.
on the day the command
is entered.
If the command is entered after the specified time,
the file is printed immediately.
Notes
P is the short form of PRINT.
The PRINT command does not accept the
"%" wildcard.
The
"*"
wildcard can only be used to substitute for a complete part of
the filespec and NOT for part of a file name or file type as
the
PIP-related commands do.
For more information on the PRINT command, see the RSX-llM/M-PLUS
Batch and Queue Operations Manual.
This manual also includes a
description of the SHOW QUEUE command, which displays information
about print jobs in queues.
PRINT is to print jobs as SUBMIT is to
command defines QMG print jobs.

batch

jobs.

Once your job is in a queue, you can modify some job
with
SET
QUEUE.
See the RSX-llM/M-PLUS Batch
Operations Manual.

The

attributes
and

Queue

The Queue Manager automatically deletes .PMT and .DMP files after
they are printed.

4-60

HANDLING FILES

APPEND
The /LOWERCASE and /UPPERCASE qualifiers have no effect on the
nature of your output.
They do not cause your job to be printed
all uppercase or in lowercase.
Rather,
these qualifiers must
match
the
attributes
given to the printer when it was
initialized.
A printer without the lowercase character set can
be
initialized /LOWERCASE and accept print jobs with the
/LOWERCASE qualifier on the PRINT command.
This might be done if
a printer with the lowercase character set was temporarily
unavailable.
In most cases, only printers with the lowercase
character set are initialized /LOWERCASE, however.
Despite your setting of the /[NO]RESTART qualifier, your job may
be restarted by commands to the Queue Manager from your system
manager.
See your system manager
if you have jobs where
restarting or not restarting may be a problem.

ii;:E;~:ar" ·' : ·
·st:,,· Jlea·'7e " ··the" · 'v<»l':tim:€!'
;,t;~i:it::.1~ri~::·:..·:~±;i'.1iif't . ...· · ~ .r .:;1'~d~~i.. .· · ·• . · ·::f;·/tl:ri4~e~} ~lies.:~~i·a1Ji£;:
·/~d· .· . . . . . .~ ·~~Q$bt, u~~is; ·ax~· :~:0·£i!eg.:f.o; i .~n-0t:h~r:. :loc~t:i~.n· .;· and·, the

...

· · the ;·;j/~~R'AN's~R :~ :·

.vo:l·'.~~:\· canJ .: ~e, :·· d.i$mQ·U

~;• : .:r1f 1 ·y.pu: 'do< •riQt+<wlsh:~ y,'<Suirff~ I es" ;to be:

ict<tc~~~~:bc:i~i.~;~[~ii:eii ~~$;.·. ''''""' ' '•. ·'.~~ .· .. ;\t~"Tj1ijq~~~~'ERY '.:'q~~:,ri',fii:~fr.:.:.
F'J.'liiit> . . ~· . .~Letr{ i ·::~:~c j. oo~· · : .J:ezcp~:en4~ ·1wh:€!'~· ;the; ::o::rd.·gi~al. deu ic:e . ;i.s
·sii'>w~;: .i~uc : .~a.~: :.bE~~a~esi,; . ·¢aa{s~;tt;e~~ i ;:?t/:£1op.P,y·'.: .'a;'t'slg; ... ··on. j:lie . . ii:tber
·iia.~<r ~ · 1i: ·:·tJ1ti.~~· · i~:· n~ ''Sp·9c~: . ~:ri }:tj~~··· ps.~;~(j~~· a~.Y:~~e · S:l?:. . •(:ti'~,up i .J.y . tl"le.
·s:ist:~·: d .i:s;k:) .1 ·yoA: tja1fr':·qse· "tl:l'€!' /NOfrJ~.··~NsFE:R gtta:lifler r·~ther than
iWG\i t i.n9;: "f:o1rf :S~~·c~:· .:•o~: ;'.sp;:.~.:... ·' : : . : ,;' ;t .:· : · ....: : .. : ·· · ... · : , · ,: .'. . . ..
· · ·
· ·
The flag pages and the job pages have different formats
for
the
banner text.
The job name page shows the UIC the PRINT command
was issued under on the first line and a
9-character job name
(derived from an explicit job name or the file name of the first
file in the job) on the second line.
The flag page shows the
full
9-character file name on the first line and the file type
and version number on the second line. See Figure 4-2.
Entry numbers run from 1 through 999 and are unique. Various QMG
commands permit you to identify your job either by this number or
by job name.
The job name includes your UIC.
See Chapter 9 and
also the RSX-llM/M-PLUS Batch and Queue Operations Manual.

APPEND

4.4.3

APPEND appends to an existing sequential file records from one or more
sequential files.

Format
APPEND[/qualifier[s]]
File(s)? infile[s]
To? outfile
APPEND[/qualifier[s]]

infile[s]

4-61

outfile

HANDLING PILES

APPEND (Cont.)
Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

Parameters
infile[s]
Specifies the file or files to be appended to
You can use APPEND only on sequential files.

the

output

file.

out file
Specifies the file to which the input files are appended.
The output file must be an existing sequential file.
The output
file has the same version number after the APPEND command is
executed as it had before the command was
issued.
The input
files appear at the end of the output file in the order they were
specified.
No wildcards are permitted in output file specifications.

There are no qualifiers for the output

filespe~-

Although the output file must exist, it may be an empty file.

Command Qualifiers
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish the APPEND command to
affect only files created on the date given.
/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish the APPEND
to affect only files created on or since the date given.

command

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the APPEND command
to affect only files created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the APPEND command to affect only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the APPEND command
to affect Orlly files c:rea":ed on the sa~e day the com.rnand is being
issued.

4-62

HANDLING FILES

SORT
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the APPEND command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly or as "*" wildcard.

Examples

>APPEND
File<s>? BIRD.DOG;*
To'? JOKER.TXT
This example appends copies of all versions of BIRD.DOG in
to the end of the most recent version of JOKER.TXT.

order

>APPEND *·LST LIST.FIL
Appends copies of most recent versions of all files of the type
.LST to LIST.FIL.
Appended files appear in the order they are
listed in the directory.

Notes
APPEND does not delete the input files.
They remain intact.
Copies of the input files are placed at the end of the output
file.

4.4.4

SORT

SORT invokes the unbundled SORT-11 utility.
If your system includes
SORT-11, the SORT command allows you to read an input file, sort the
contents, and write out the sorted data to an output file.
The
sorting sequence is determined by control fields called key fields
within the data.

Format
SORT/KEYS: (abm.n[ :abm.n ••• ] ) [/qualifiers]

infile[/FORMAT:arg] [/qualifier[s]]

Command Qualifiers
/ALLOCATION:n
/BLOCKSIZE:n
/BUCKETSIZE:n
/[NO]CONTIGUOUS
/DEVICE:ddnn:
/WORK FILES:n
/FORMAT: fmt [: n]
/PROCESS:type
/SIZE:n
/SPECIFICATION:filespec

4-63

outfile[/qualifier[s]]

HANDLING FILES

SORT (Cont.)
File Qualifiers
/FORMAT: fmt: n
/INDEXED:n
/RELATIVE
/SEQUENTIAL

Format Arguments
FIXED:n
STREAM:n
UNKNOWN:n
VARIABLE:n

Parameter
inf ile
Specifies the file you wish to sort.
The file must be in a valid
RMS-11 format.
The default file type for input files is .DAT.
out file
Specifies the file where you wish the sorted output

writt~n.

Command Qualifiers
/KEYS: (abm.n)
Specifies the keys on which the sorting is to be based.
This
determines the sequence in the output file.
You must enclose the
argument to /KEYS in parentheses. For defaults, see the first
two examples.
abm.n
Specifies the key field.
You can specify up to
fields, separated by colons, such as the following:

key

/KEYS: (BN1.6:C8.2)
The default is /KEYS: (CNl.9).
a

See the examples.

Describes the data in the file and thus how it is to be
handled.
If the character
is omitted, the default
value is c.
The possible values are as follows:
B, C, D, F,

I, J, K, P,

The meaning of each of these characters
under Data Description Characters.
b

Defines the general sort order.
are:
N
O

The

Ascending order (the default)
Opposite, or descending, order

4-64

described

possible

values

HANDLING FILES

SORT (Cont.)

Ill

A decimal number giving the first byte of the key field
starting
stated.

from

This

number

must

explicitly

A decimal number giving the length of the key field
bytes.
This number must be explicitly stated.

Data Description Characters
B

Two's complement binary.

Alphanumeric.

If the characters are alphabetic,
numeric with the sign
superimposed over the units digit, or contain slashes (/),
use the value of the digits group. For example:
A2CD5

= (+) 12345 and A/47J = (-) 11471

If the characters represent a standard FORTRAN-IV number,
such as 12, -35, 42.98, or -0.76E+3, convert the number to
binary for storage or evaluation.
F

2- or 4-word floating point binary.

Sarne as D, but with the sign leading and separate,
the first byte of the field is a + or -.

Sarne as I but with the sign trailing and separate.

Sarne as D but with the sign leading and overpunched
(54321,
for
instance if positive, would come out as 5432A.
the
negative of 54321 would be 5432J).

Packed decimal format.

ASCII zone.

that

/ALLOCATION:n
Specifies the initial space allocation for
the output file.
Legal values range from 0 through 65,535.
If you do not use this
qualifier, the output file allocation defaults to the input file
size for the record and tag sort processes.
For index and
address routing sort processes, the default size is based on the
number of records sorted.
/BLOCKSIZE:n
This qualifier is valid for magnetic tapes only and
is used to
specify a nonstandard rnagtape block size.
If this qualifier is
not used, the block size defaults to the standard 512-byte block.

4-65

HANDLING FILES

SORT (Cont.)
/BUCKETSIZE:n
Specifies the RMS-11 bucket size (the number of 512-byte blocks
per bucket).
Please note
that the size of the block is the
standard 512 bytes even if the /BLOCKSIZE qualifier is used.
The
default value of this qualifier depends on the organization of
the input file.
If the input and output files are of the same
organization,
the default for the output file is the input file
value.
If the input files differ in organization or the default
is required for the input file, the default value is 1.
/[NO]CONTIGUOUS
Specifies that the output file be contiguous.
This means
that
each block
in the file will be physically located between its
logical predecessor and its logical successor with no filler
or
extraneous
material
separating
blocks.
The
default is
/NOCONTIGUOUS.
/DEVICE:ddn:
Specifies the device on which you want the scratch files.
This
qualifier overrides any device specification from Task Builder
options.
/WORK_FILES:n
Specifies the maximum number of
Legal values are from 3 through 8.

intermediate scratch files.
The default value is 5~

/SPECIFICATION:filespec
Specifies the name of a file containing SORT-11 controls for
kind of sorting process to be used.

the

/PROCESS: arg
RECORD
TAG
ADDRESS ROUTING
INDEX
Specifies the type of sorting process to be used.
RECORD.

The default is

/RELATIVE
Specifies that
organization.

the

output

file

have

relative

file

the

output

file

have

sequential

file

/SEQUENTIAL
Specifies that
organization.

4-66

HANDLING FILES

SORT {Cont.)
/SIZE:n
Specifies the size of the retrieval window.
The ranges and
defaults for this qualifier are determined by the operating
system. See your system manager for further information.

File Qualifiers
/FORMAT: arg
FIXED:n
STREAM:n
VARIABLE:n
UNKNOWN:n
Specifies the record format and the maximum size (n) in a
file.
The maximum record size n is the exact record size in bytes for
FIXED length records. For other formats, n is the size in bytes
of the largest record present. You must specify a value for n
for input files.
The default is /FORMAT:FIXED:84.
This file qualifier specifying the format of input records can be
overridden by the corresponding file qualifier for output files.
/INDEXED:n
Specifies that the input file has
organization.
n specifies the
default for n.

the indexed sequential file
number of keys.
There is no

Examples
>CREATE PHONE.TXT
BAKER

FOX
EASY
CHARLIE

ABLE
DOG
tTRL/Z)

>SORT
InPut file? PHONE.TXT
Output file? PHONE.OUT
SRT -- m: ELAPSED REAL TIME:oo:oo:o4
SRT -- m: TOTAL RECORDS SORTED
6
>TYPE PHONE.OUT

ABLE
BAKER
CHARLIE
DOG
Ef..iS Y

FOX

4-67

HANDLING FILES

SORT (Cont.)
This example illustrates the defaults for the DCL SORT command.
The user created a file where no record (line) is longer than 80
characters. SORT-11 sorted the file on the basis of the first
nine characters.
This sorting is in ASCII sequence, meaning that
symbols are sorted first,
followed by numbers,
followed by
uppercase letters, followed by lowercase letters.

>SORT/KEYS:CCN1.9> PHONE.TXT/FORMAT:FIXED:84 PHONE.OUT
This example is the equivalent of the previous one, with defaults
explicitly stated.
SORT-11 itself has no defaults for these
values.
The defaults come from DCL.
>DIRECTORY SLMINDEX.FIL

DIRECTORY DB1:[303r5J
9-AUG-82 11:40
SLHINDEX.FIU 1

69.

09-AUG-82 11:00

TOTAL OF 69./69. BLOCKS IN 1. FILE
>SORT/KEY:CCN1.9)/DEV:DBO:/FILE:3/SEQ/PROC:REC SLMINDEX,FIL/FOR:VAR:lOO SLMINDEX.TST
SRT -- M:ELAPSED REAL TIME: 00:00:30
SRT -- H:TOTAL RECORDS SORTED:
1410
>DIRECTORY SLMINDEX.*
DIRECTORY DB1:[303r5J
9-AUG-82 11:41
SLHINDEX. F IU 1
SLMINDEX.TST;1

69.
68.

09-AUG-82 11:00
09-AUG-82 11: 4 l.

TOTAL OF 137./138. BLOCKS IN 2. FILES

In this example, the user started out with a file SLMINDEX.FIL, a
variable format file with the largest record size 100 bytes.
The
key field is specifed as CNl.9.
The C indicates the file
is to
be sorted as an alphanumeric file.
The N specifies ascending
order.
The 1 indicates that the sort is to start on the first
byte of each record and the 9 indicates that the sort is to
continue through the ninth byte of each record.
The command
directs that three scratch files be created on DBO:
and then
deleted after the operation completes.
The output file
is
requested to be sequential and the sort is specified as a record
sort.

4-68

HANDLING FILES

DIFFERENCES
In other words, the r11e is a sequential file containing numbers
and letters with up through 100 characters per record (line).
The user wishes these records sorted on the basis of the first
9
characters in each record with the resulting sort in ascending
order, with the lower ASCII values first and the higher ASCII
values following.
Note that while the ASCII values go up as you
go through the alphabet, all lowercase letters have higher values
than any uppercase letter.
Furthermore, characters such as
blanks, tabs, bells, and the like have the lowest ASCII values.
Notice the messages informing you of the time elapsed from the
time you entered the command until the sort completed and of the
number of records sorted.
Notes
SORT-11 is an unbundled product that is not available on all
systems.
The SORT command depends on the presence of SORT-11.
The file SORT.TSK should be located in the system directory on
RSX-llM or the library directory on RSX-llM-PLUS.
Thus, you can also invoke SORT-11 with the command
>RUN $SORT
If you run SORT-11, you must
format, not the DCL format.

enter

commands

the

SORT-11

You cannot use the SORT command without an understanding
SORT-11. See the PDP-11 SORT Reference Manual.

4.4.5

DIFFERENCES

DIFFERENCES compares two ASCII (text) files line by line to determine
if parallel records (lines) are identical, and produces a listing of
the differences between the files, if any.
Format
DIFFERENCES[/qualifier[s]]
Filespecl? infilel
Filespec2? infile2
DIFFERENCES [/qualifier [s]]

infilel infile2

Command Qualifiers
/CHANGE BAR [: n]
/IGNORET(arg[,s])
BLANK LINES
COMMENTS
FORM FEEDS
SPACING
TRAILING BLANKS
/LINES:n
- .
/NONUMBERS
/OUTPUT:filespec
/SLP[:au]

4-69

HANDLING FILES

DIFFERENCES (Cont.)
Parameters
inf ilel
Specifies the first of two files to be compared.
The
must be included.
The default file type is .MAC.

file

name

The file

name

infile2
Specifies the second of two files to be compared.
must be included.
The default file type is .MAC

Command Qualifiers
/CHANGE_BAR[:nnn]
Specifies that the output consists of a listing of
infile2 with
change bars applied to each line in infile2 that does not have a
corresponding line in infilel.
The nnn argument is the number of
the ASCII character to be used for the change bar.
The default
is 041, the exclamation point (!).
Here are the codes for
some
commonly used ASCII characters:

041
043
044

052
053

*
<
>
?

074
076
077
074

/IGNORE:(arg[,s])
BLANK LINES
COMMENTS
FORM FEEDS
SPACING
TRAILING BLANKS
Specifies that you wish certain defaults to be ignored in making
the comparison. Without the /IGNORE qualifier, the comparison is
strictly line-by-line.
If you specify only one argument, you do
not need the parentheses.
If you specify more than one argument,
enclose them in parentheses and separate them with commas (,).
The default is to include all these factors in the comparison.
The BLANK LINES argument specifies that blank lines are to be
The default is to include blank lines
in the comparison.

excluded -from comparison.

The COMMENTS argument specifies that comments,
that
is, text
preceded by a
semicolon (;) not be included in the comparison.
Otherwise, comments are compared like all other text.

4-70

HANDLING FILES

DIFFERENCES {Cont.)
The FORM FEEDS argument specifies that lines beginning with a
single form-feed character (CTRL/L) are to be excluded from the
comparison.
The default
is to include such lines in the
comparison.
The SPACING argument specifies that any sequence of blank and tab
characters is to be interpreted as a single blank for the
comparison. This argument is useful when comparing source files
that differ only in their spacing.
The output listing includes
blanks and tabs as they are found in the input files, but the
blanks and tabs are ignored.
The default is to compare sequences
of blanks and tabs like any other characters.
The TRAILING BLANKS argument specifies that all blanks following
the last nonblank character
in the line be ignored in the
comparison.
The default is to compare trailing blanks like all
other characters.
If you specify both TRAILING BLANKS and
COMMENTS in your /IGNORE qualifier, any blanks preceding a
semicolon (;) are also ignored.
The DCL DIFFERENCES command does not have quite the same defaults
as CMP,
the File Compare Utility, which DIFFERENCES invokes.
Specify /IGNORE: (BLANK LINES,FORM FEEDS)
to duplicate the CMP
defaults for blank lines and form-feeds.
Other CMP defaults need
not be specified.
/LINES:n
Specifies that n lines must be identical before a match
recognized.
The default value for n is 3 identical lines.

/[NO]NUMBERS
/NONUMBERS specifies that lines in the output file not be
preceded
by
line
numbers.
The standard output listing
automatically includes line numbers.
Line numbers start with 1
in increments of one.
All lines are numbered, including blanks.
/OUTPUT:filespec
Specifies that the output listing be written to the file named in
the qualifier.
Normally, this output appears on your terminal.
/SLP[ :auJ
Specifies that the output listing take the form of a SLP indirect
command file.
When you include this qualifier,
the output
listing is an SLP indirect command file that makes infilel
identical to infile2.
The optional au argument, preceded by a
colon, is a 1- through 8-character alphanumeric audit trail
symbol.
For more information on the Source Language Input
Program (SLP), see Chapter 13 of the RSX-llM/M-PLUS Utilities
Manual.

4-71

HANDLING FILES

DIFFERENCES (Cont.)
Examples

The following examples use several slightly different versions of
the same MACR0-11 source file for comparisons.
The full text of
version 1 is printed here. Version 2 is identical except for
that one Executive directive is different;
version 3 has
additional blank lines inserted.
In each instance, the "!DENT"
number matches the version number.
Here is the text of version 1:
.TITLE WRITE PRINT A PREDEFINED MESSAGE ON
.!DENT "01"

THE

USER

TERMINAL

.MCALL ALUN$C, QIOW$C, EXST$C
STRING:
LENGTH

.ASCII "This is a simple MACR0-11 program."
.-STRING
CALCULATE THE STRING LENGTH
.EVEN

START:

ALUN$C l,TI,O
; ASSIGN THE LUN TO USE TO THE TERMINAL
QIOW$C IO.WVB,1,1,,,,STRING,LENGTH,40>
PRINT THE STRING
EXST$C EX$SUC
SUCCESSFUL EXIT IN ALL CASES
.END

START

SETUP THE STARTING ADDRESS

In the following examples, a "difference" as defined by the
DIFFERENCES command, consists of one or more lines that differ in
the two files being compared.
Each "difference" ends when the
first
matching
line is encountered.
The listing of the
"difference" includes all the nonmatching lines AND the first
matching line.

>DIFFERENCES/IGNORE:(BLANK_LINES,FORM.FEEDS>
FilesPecl? TOM.MAC;1
FilesPec2? TOM.MAC;2

**************************************************
1) DB2:[303r5JTOM.MAC;1
2
4
6

.IDENT
.MCALL
STRING: .ASCII

QIOWSC· EXST$C
'This is a simple MACR0-11 Prosram+"

ALUN$C~

***************
2)
DB2:c303,5JTOM.MAc;2
2

.IDENT '02"
.MCALL ALUNSC, QIOWSC, EXSTSS
6
STRING! +ASCII
•this is a simPle MACR0-11 Prosram."
1 differences found
TI:/-BL/-FF/-CB=TOM.MAC;1,TOM.MAC;2
4

In this example, the user compared two files that differ only in
one Executive directive -- EXST$S or EXST$C -- and
in their
version numbers.
The user specified
/IGNORE:(BLANK_LINES,FORM_FEEDS)

so as to reproduce the defaults of CMP, the File Compare utility;
which the DIFFERENCES command invokes.

4-72

HANDLING FILES

DIFFERENCES (Cont.)
The listing of differences between the two files starts with the
!DENT numbers on line 2 of the files. The next line is blank in
both files. Although the line is numbered, it is not printed on
the terminal and is ignored in the comparison. It would not
change the results if one file had the blank line there and one
did not.
The next listed difference is in the Executive calls on line 4.
Again, the blank lines are not shown. The next line of code
listed is the same in both files. This marks the end of a group
of lines that are different in the two files.
The command line reprinted at the bottom of the listing
CMP command line equivalent to the DIFFERENCES command.

the

>DIFFERENCES TOM.MACl1 TOM.MAC;2

**************************************************
1> DB2!E303,SJTOM.MAC;1
2

.IDENT

.MCALL

ALUNSC1

3
4

QIOW$C, EXST$C

***************
2)
DB2![30315JTOM.MAC;2
2

.IDENT

"02"

.MCALL

ALUNSCr QIOWSCr EXST$S

3
4
5

1 differences found

TI:/BL/FF/-CB=TOM.MAC;1,TOM.MACi2
This example illustrates the defaults for the
DIFFERENCES
command.
The results are the same, but the blank lines are
printed. If one file had had more blank lines than the other,
the results would not have been the same. See the examples
comparing version 1 and version 3.
>DIFFERENCES/CHANGE_BAR/IGNORE:CBLANK_LINES,FORM_FEEDS> TOM.MACil TOM.MAC;2
1
.TITLE WRITE PRINT A PREDEFINED MESSAGE ON THE USER TERMINAL
2
.!DENT
02
4
.MCALL ALUNSCr QIOW$Cr EXST$S
6
STRING: .ASCII 'This is a simple MACR0-11 Program.•
7
LENGTH
,-STRING
; CALCULATE THE STRING LENGTH
8
.EVEN
10
START: ALUN$C lrTirO
ASSIGN THE LUN TO USE THE TERMINAL
11
QIOWSC IO.WVBr1,1,,,,sTRI GrLENGTH,40>
1

13
EXST$C EX$SUC
15
.END
START
1 differences found
TI:/-Bl/-FF/CB/VB::o41=TOM.MACi1rTOM.MAC;2

4-73

SUCCESSFUL EXIT IN ALL CASES
SETUP THE STARTING ADDRESS

HANDLING FILES

DIFFERENCES (Cont.)
This example shows the effect of the /CHANGE BAR qualifier.
The
second file
is printed on the terminal with exclamation points
next to the numbers of the changed lines.

>DIFFERENCES/IGNOREt<BLANK-LINES> TOM.MAC;1 TOM.MAC;3

**************************************************
1) DB2:C303,5JTOM.MAC;1
2

.!DENT

MC ALL

01
A·L UN$ C,
1

Q I Ola C,

EX SH C

***************
2) DB2:C303,5JTOM+MAC;3
.!DENT
.MCALL

2
4

03"
ALUNSC, QIOWSC, EXSTSC
1

1 differences found
TI:/-Bl/FF/-CB=TOM.MAC;1,TOM.MAC;J

Versions 1 and 3 differ only in their blank lines and version
numbers.
In this example, with /IGNORE:(BLANK LINES), the only
difference
is
in the !DENT numbers.
The listing of
the
difference ends with the first line that is not different.
Blank
lines are numbered but otherwise ignored.
>DIFFERENCE TOM.MAC;1 TOM,MAC;3

**************************************************
1) DB2:C303,5JTOM+MAC;1
2

+!DENT

"01"

2)
2

DB2:c303,5JTOM.MAc;3
.!DENT "03"

**************************************************
1) DB2t[303,5JTOM.MAC;1
LENGTH

,-STRING

CALCULATE THE STRING LENGTH

.-STRING

CALCULATE THE STRING LENGTH

***************
2)
DB2:c303,5JTOM.MAC;3
7

LENGTH

**************************************************
1) DB2t[303,5JTOM.MAC;1
11

GIOW$CIO.WVB,1,1,,,,grRING1LENGTH140>

***************
12
13

GIOWSCIO.WVB,111,,,,gTRING1LENGTH,40>

3 differences found

rr:1BL/FF/-CB=TOM.MAC;1,roM.MAC;3

Comparing
the
same
two
files
without
specifying
/IGNORE: (BLANK_LINES)
has
quite
different results.
Three
differences are found.
The first is the differing IDENT numbers.
The other two differences are nothing more than blank lines.

4-74

HANDLING FILES

UNLOCK
Notes
You can compare any two text files.
They need not be MACR0-11
source files, but most qualifiers to DIFFERENCE are for use with
MACR0-11 files.
The DIFFERENCES command invokes CMP, the File Compare
See Chapter 12 of the RSX-llM/M-PLUS Utilities Manual.

Utility.

UNLOCK

4.4.6

UNLOCK unlocks locked files.
Locked files are files
that have been
improperly closed because a task aborted or stopped execution while
the file was open.
Locked
files are identified by an L in the
directory listing.

Format
UNLOCK[/qualifier[s]]
File(s)? filespec[s]
UNLOCK[/qualifier[s]J

filespec[s]

Command Qualifiers
/DATE:dd-mmrn-yy
/SINCE:dd-mmrn-yy
/THROUGH:dd-mrnm-yy
/SINCE:dd-mmrn-yy/THROUGH:dd-mmrn-yy
/TODAY
/EXCLUDE:filespec

Parameter
filespec
Identifies the locked file(s)

that you wish to unlock.

Command Qualifiers
/DATE:dd-rnrnm-yy
The /DATE qualifier specifies that you wish the UNLOCK command to
affect only files created on the date given.
/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish the UNLOCK
to affect only files created on or since the date given.

command

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish the UNLOCK command
to affect only files created on or before the date given.

4-75

HANDLING FILES

UNLOCK (Cont.)
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish the UNLOCK command to affect only files created
within that range.
/TODAY
The /TODAY qualifier specifies that you wish the UNLOCK command
to affect only files created on the same day the command is being
issued.
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the UNLOCK command
not to affect certain files.
The filespec argument to /EXCLUDE
can contain wildcards, but the version number must be given,
either explicitly or as "*" wildcard.

Example
>Director~

TOPEKA.KAN

Director~

DBO:E303r5J

2-NOV-82

13:13

TOPEKA.KAN;3

32.

25--NOt..'--82

12: 29

Total of 32./40. blocks in 1. files

>UNLOCK TOPEKA.KAN

>
>

>DIRECTORY

TOPEKA.KAN

Director~

DBO:c303,5J
13:14

2-NOV--82

TOPEKA.KAN;3

32.

25--NOV--B2

Total of 32./40. blocks in 1.

12 t 29

files

In this example, the user found a locked file, perhaps through an
error message stating that the file could not be opened.
The
locked state is indicated by the L in the third column of the
directory listing.
After the user issues the UNLOCK command, the
file is no longer locked.
Notes

In many cases, a locked file has no contents because the task
that opened the file aborted before writing to the file.
In this
case, you do not need to unlock the file before deleting it.
Another common case of file locking is a data file that has been
opened by some task that aborted or exited without closing the
file.
In this case, you have to unlock the data file before
running the task again.
If the file is written to by the task,
it may have been corrupted.

4-76

HANDLING FILES

SET DEFAULT
4.5

SET AND SHOW

You can SET and SHOW your default device and UFD.
You can SET
PROTECTION on any file in your directory, or on a volume mounted on
your private (allocated) device.

SET DEFAOLT

4.5.1

SET DEFAULT establishes your default device or UFO, or both.

Format
SET DEFAULT [ddnn:] [ [g ,m]]

Parameters
If you issue SET DEFAULT without parameters, your default device
and UFD return to your login defaults, if you are nonprivileged.
Privileged users must explicitly reset their login UFD.
ddnn:
Specifies the name of the device you wish to be your default
device.
The device must be a Files-11 device.
The device name
can be a logical name, but the SHOW DEFAULT display names the
physical device.
[g ,m]

Specifies the UFD you wish to be your default directory.
When you change your UFD, the system checks your login UIC for
your
privilege.
If
you
are
nonprivileged, you remain
nonprivileged even if your new default UFD has a group number of
10 or less.
If you are privileged, this command changes your login UIC as
well as your default UFD, but your privileges remain the same.
In some cases, however, privileged users may have to reset their
UFD to a privileged group number
in order to use privileged
commands.

Examples

>SET DEFAULT DK1:c303,5J
This example sets DKl:
as the default device and [303,5] as the
default directory.
All subsequent commands default to this
device and directory unless you explicitly state otherwise.

4-77

HANDLING FILES

SET DEFAULT (Cont.)
>SHOW DEFAULT
DB1![303,5J TT56:
>SET DEFAULT DB2:[200r200J
>SHO DEF
DB2:[200,200J
>SET DEF

>SHO DEF

DB1:[303,~5J

This example illustrates the use of the unadorned SET DEFAULT
command.
The user started with the login default device of DBl:
and the UFD [303,5], as given in the display from the SHOW
DEFAULT
command.
Then,
the
user
set the defaults to
DB2: [200,200]
and checked the setting with
SHOW
DEFAULT.
Finally,
the user
issued SET DEFAULT without specifying any
parameter.
The user's defaults are returned to the login
defaults.
See notes.

>SET DEF DK1!
>ASSIGN DK1!

BYO:

The two commands in this example are equivalent.
In each case,
the default device becomes DKl:.
When you set the default
device, SET DEFAULT actually assigns SYO:
as a logical name for
the device you wish.
SYO:
is the logical device name that
represents your default device.
Notes

SET DEFAULT is an unusual command
in that it has differing
effects depending on the presence or absence of its parameters.
The only way to change your default UFD in DCL is through SET
DEFAULT.
When you issue SET DEFAULT including a UFD, DCL
directly alters the default UFD held in your Unit Control Block
(UCB) •
When you change your default device, however, SET DEFAULT
generates the equivalent of an assignment of the logical name
SYO:
to the physical device you name, as shown in the examples.
Conversely, when you issue the command without any parameters,
SET DEFAULT generates the equivalent of a deassignment of the
logical name SYO:, meaning that your default device assignment
returns to your login SYO:, which is whatever device you log in
to, and, for nonprivileged users resets your UFD to your login
UFO.
Since DCL is issuing two commands, it is possible
succeed while the other fails.

4-78

that

one

may

HANDLING FILES

SHOW DEFAULT
SET PROTECTION
SHOW DEFAULT

4.5.2

SHOW DEFAULT displays the current default
terminal.

device

and

UFD

for

your

giving

the

Format
SHOW DEFAULT

Examples

>SHOW DEFAULT
DB1:[303t5J TT56:
This example shows the display from SHOW DEFAULT,
default device and UFD, plus the terminal name.

>SHOW DEFAUL.l
DB1:[303t5J TT56:

>SET DEFAULT

rrno .:

>SHOW DEF

DB0![30315J TT56:
>SET DEFr4ULT DK1:L1:/J

>SHOW DEF
DK1t[1t7J TT56!
>ASSIGN DT2! YY1:
>SET DEF YY1 !

>SHOW DEF
DT2:C1t7J TT56:
In this example, the user first checked the defaults with SHOW
DEFAULT, and then used SET DEFAULT to change the default device
from DBl:
to DBO:. The user checked with SHOW DEFAULT and
then
set the defaults to device DKl:
and UFD [1,7).
After checking
again, the user assigned the logical name YYl:
to DT2:
and set
YYl:
as the default device.
Note that the subsequent SHOW
DEFAULT display did not give the logical name YYl:,
but the
physical name DT2:.

Notes
See Chapter 5 for more information on logical assignment.

4.5.3

SET PROTECTION

SET PROTECTION establishes the protection status of files.
Protection status determines which categories of user
file and what each kind of user may do to the file.

may

Nonprivileged users can set the protection of any files in
directory.

4-79

access
their

a
own

HANDLING FILES

SET PROTECTION (Cont.)
Privileged users can set the protection of any file.

Format
SET PROTECTION:code[/qualifier[s]]

filespec[s]

SET PROTECTION[/qualifier[s]]
File? filespec[s]
Code? (code)
SET PROTECTION[/qualifier [s]]

filespec[s]

(code)

Command Qualifiers
/DATE:dd-mmm-yyy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

Parameters
filespec[s]
Specifies the file or files
for which protection is to be
established.
Multiple filespecs,
separated by commas, and
wildcards are permitted.
All
files you specify receive the
protection status you specifye
code or

(code}

Specifies which classes of users are permitted access to the file
and what each class of user may do the the file.
The parentheses
are required syntax.
There are four kinds of users:
SYSTEM

The operating system itself, and privileged
users, those with group numbers of 10 or less

OWNER

The user having the same UIC as that the
was created under

file

GROUP

All users with the same group number
the file was created under

that

WORLD

All other users

There are also four kinds of access to files:
READ

The user, or the user's tasks, may read, copy,
print,
type the file, or run it, if it is a
task image

WRITE

The user, or the user's tasks, may
data to the file by writing to it

4-80

add

new

HANDLING FILES

SET PROTECTION (Cont.)
EXTEND

The user, or the user's tasks, may increase
the amount of disk space allocated to the file

DELETE

The user, or the user's tasks, may delete
file

the

These forms of access are hierarchical~
If you specify DELETE
access, you are also granting READ, WRITE, and EXTEND access.
If
you specify WRITE access, you are also granting READ access but
denying EXTEND and DELETE access, and so forth.
The system default protection code is expressed as follows:
(SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R)
Under this code, the system, and privileged users, have full
access to your files,
You,
as well as others with your group
number, also have full access to your files.
Other nonprivileged
users can only read your files.
If no other protection is
specified, all files have this protection.
In addition to the
system default protection,
there is default volume protection.
See Section 4.1.5.
If you wish to protect a file differently, use the same format,
naming only the user group whose access rights you wish to change
and the access form you wish to grant to that group.
If you wish
to deny all access to a group, simply name the group and omit the
colon (:) and the code for the access form.
Whenever any command specifies the protection code, enter
this form.

Command Qualifiers
/DATE:dd-mmm-yy
The /DATE qualifier specifies that you wish to set the protection
only on files created on the date given.
/SINCE:dd-mmm-yy
The /SINCE qualifier specifies that you wish to set
protection only on files created on or since the date given.

the

/THROUGH:dd-mmm-yy
The /THROUGH qualifier specifies that you wish to set the
protection only on files created on or before the date given=
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
The /SINCE and /THROUGH qualifiers can be combined to specify
that you wish to set the protection only on files created within
that range.
/TODAY
The /TODAY qualifier specifies that you wish to set
the
protection only on files created on the same day the command is
being issued.

4-81

HANDLING FILES

SET PROTECTION (Cont.)
/EXCLUDE:filespec
The /EXCLUDE qualifier specifies that you wish the SET PROTECTION
command not to affect certain files.
The filespec argument to
/EXCLUDE can contain wildcards, but the version number must be
given, either explicitly or as a "*" wildcard.

Examples
>SET

FUNCTION? PROTECTION
CODE? CSYSTEM!RWED,OWNER:RWED1GROLJP,WORLDl
>File(s)? SANTONE.TEX

>DIRECTORY/FULL SANTONE.TEX
Directory DB1![303r5 I

5-JUL-82

SANTONE.TEX;l
[303,5]

10!49
!10732r11)

4-,.llH-H2 9;49

CRl.JEihRWED,, J

Total of 2,/5. blocks in 1. file

This example sets file protection so that privileged users and
the owner have full access to the file and all others have no
access to the file.
The DIRECTORY/FULL command displays the
protection of files.
The list is in the same order as before:
SYSTEM, OWNER, GROUP, WORLD.
The commas separate the access
rights of each group.
The commas with nothing following them
signify no access for other users with the same group number and
no access for WORLD.
>SET PROTECTION *.*;* (SYS:RWE,OWN:RWE,GRO:RW,WOR:RW)
This example sets the protection for all files
in the current
default directory. No class of user can delete the files in the
directory;
other nonprivileged users cannot extend files in the
directory.

Notes
Although you can protect your files against access by privileged
users, privileged users can change fhe protection status of any
file.
Thus, you can prevent privileged users or the system from
inadvertently accessing your files, but you cannot prevent them
from changing the protection status and doing what they will with
your files.
Other commands accepting a protection
MOUNT, and CREATE/DIRECTORY.

code

include

INITIALIZE,

If you deny READ access to a task image file, the task cannot
run.

4-82

CHAPTER 5
HANDLING DEVICES AND VOLUMES

Peripheral devices are the actual hardware elements that, with the
computer, make up a computer system.
In general, a peripheral device
is anything that is not part of the CPU or main memory.
All input to the system and output from it is handled by peripheral
devices.
One primary function of the operating system is to manage
efficiently all the peripheral devices in the system.
System generation informs the Executive which devices are to be
included in your installation and describes the characteristics of
those devices.
In RSX-llM/M-PLUS terminology, a file is an owner-named area on a
volume.
A volume is a collection of files or data stored on a
magnetic medium, such as a disk, DECtape,
or magnetic tape.
This
medium must be physically placed on a drive and logically mounted
before the system can access the data on the volume.
This chapter briefly introduces the important concepts concerning
devices and volumes.
In addition,
the chapter describes the DCL
commands that deal with devices and volumes.

5.1

DEVICES ON RSX-llM/M-PLUS SYSTEMS

Table 5-1 lists the devices found on RSX-llM/M-PLUS systems.
Each
installation has a different mixture of physical devices.
Each
physical device has an associated hardware controller, which serves as
an interface between the device hardware and the CPU.
In addition,
each device has a device driver, which is the software interface
between the operating system and the device controller.
The table also lists pseudo devices found on RSX-llM/M-PLUS systems.
A pseudo device is an entity treated as an I/O device by the user or
system although it is not actually any particular physical device.
A
pseudo device name is a pseudonym through which actual physical
devices can always be reached.
See Table 5-2 and Section 5.1.2.1 for
more information-on pseudo devices.
Individual devices are identified by a two-letter mnemonic and an
octal unit number,
terminated by a colon.
If you omit the unit
number, the system defaults to unit number O.
That is, if you wish to
specify DBO:
in a command, DB: will do.

5-1

HANDLING DEVICES AND VOLUMES
Table 5-1
Devices on RSX-llM/M-PLUS Systems
Mnemonic

Device

AD:

AnaJ<:>g'."."'to-Digital Convert~rl
Analog..:to-Digital Converterl
,~a,}>,oratpry, Per ~phe,r(2~ Sub~~St!f1Ill
· :O'TOCT> ,,tfNlBUS Sw1,tch2 ·
,•
:, .
Console Listing Pseudo Device
Console Output Pseudo Device
Card Reader
Cassette (TU60)
RP04/05/06 disk packs
DECtape II (TU58)
RK05/J/F cartridge disk
RL01/RL02 disk drives
RK06/07 cartridge disk
RP02/03/RPR02 disks
RM02/03/05 disks and RM80/RP07
fixed media
RS03/04 fixed-head disks
DECtape (TU56)
RA60/80/81/RC25/RCF25/RD51/RX50 disks
RXOl floppy disk
RX02 floppy disk
Non-Rotating Electronic Memory
Graphics Display• Processor and ·Scopel
I'.ndustrial Control Systeml
Interprocessor Interface2
Industrial Control System
Industrial Control Subsysteml
Laboratory Peripheral Accelerator
System Default Pseudo Device
Line Printer
Laboratory Subsysteml
Parallel Communications Link2
Parallel Communications Link2
TU78 magtape
MKAll :J?r'ogiammable 'Memory Box2
TU45/TU16/TE16/TU77 magtapes
TSll/TSVOS magtape
TS03/TU10/TE10 magtapes
Null Device
Paper Tape Punch
Paper Tape Reader
Reconfiguration Driver2
Spooling Pseudo Device2
User Default Pseudo Device
Terminal Input Pseudo Device
Terminal
Universal Digital Controllerl
Virtual Terminal 2
Workf ile Pseudo Device
Interprocessor Linkl
Intreprocesso~ Linkl
Interprocessor Link
Synchronous Interfacel
Synchronous Interface!
Synchronous Interfacel
Synchronous Interfacel

AF:
AR:

'BSi'
CL:
CO:
CR:
CT:
DB:
DD:
DK:
DL:
DM:
DP:
DR:
OS:
DT:
DU:
DX:
DY:
EM:
GR:
IC:
II:

IP:
IS:
LA:
LB:
LP:
LS:
LT:

LR:
MF:

MK:
MM:
MS:
MT:
NL:
PP:
PR:
RD:
SP:
SY:
TI:
TT:
UD:
VT:
WK:
XB:
XL:
XM:
XP:
XQ:
XU:
XW:

Hardware Controller

1.
Indicates device on RSX-ll~ only~
~In~{c~te~ ~evice:~~ RSX-llM-PLUS only.
N/A Controller not applicable to device.

5-2

ADOl•D
AFCll
ARll
0'1'07·
N/A
N/A
CRll/CMll
TAll
RH11/RH70
DLll
RKll
RL11/RL211
RK6 ll/RK7 ll
RPll
RH11/RH70
RH11/RH70/RS03/RS04
TCll
UDA50/RQDX1
RXll
RX211
MLll

VT11/VS60
ICR/ICSll
DIP-11
IP11/IP300
DRS/DSSll
LPAll-K
N/A
LAll/LPll/LSll/LVll
LPSll
PCL-llB

PCL-llB
RH70/TM78
MK.All
RH11/RH70/TM02/TM03
TSll
TMll/TMAll/TMBll
N/A
PCll
PCll/PRll

N/A
N/A
N/A
N/A
DHll/DLll/DJll/DZll
UDCll
N/A
N/A
DAll-B
DLll-E
DMCll
DPll
DQll
DUll
DUPll

HANDLING DEVICES AND VOLUMES
RSX-llM/M-PLUS systems support a variety of devices.
The terminal,
line printer, disk, and tape unit are the most commonly encountered.
The card reader and line printer are called unit record devices.
Disks
and magnetic tapes are mass-storage devices.
Disks are
random-access devices and magnetic tapes
are
sequential-access
devices.
Each of these device types is discussed briefly in this
section and, if necessary, in more detail elsewhere in this chapter.
Devices are
informally identified by
the
two-letter
mnemonic
identifying the device driver,
such as DT:
for DECtape I, but you
should remember that the driver may support more than one device. For
instance, the DL: driver supports both RLOl and RL02 devices.
Unit record devices operate on data one record at a time.
Unit record
devices can store only one record's worth of data at a time.
For
instance, a line printer (LP:) receives and stores characters until it
has a full
line and then prints that line.
Unit record devices on
RSX-llM/M-PLUS include the paper tape punch (PP:), paper tape reader
(PR:), the TU60 cassette (CT:), and card reader (CR:).
For storing large amounts of data, disks and tapes are used.
These
disks and tapes are called magnetic media.
The information stored on
these media must be arranged in formats suitable to the operating
system and your installation's software.
On RSX-llM/M-PLUS systems, the information contained on the magnetic
medium is called a volume.
Volumes can be of several varieties.
Foreign volumes are those on which the data is organized along
principles not recognized by RSX-llM/M-PLUS systems.
Files-11 volumes
are those on which the data is organized according to the normal file
structure used by RSX-llM/M-PLUS systems.
Devices that accept media
containing Files-11 volumes are all disk devices,
including floppy
disks and disk packs (DB:, DF:, DK:, DL:, DP:, DR:, DS:, DU:, DX:, and
DY:), the TU56 DECtape I
{DT:) I
and the TU58 DECtape II
(DD:).
Files-11 volumes are created through the INITIALIZE command (Section
5.8). The operating system treats all Files-11 volumes identically,
regardless of the device or medium.
NOTE
DECtapes are
random-access
devices.
Therefore,
in this manual and other
system documentation,
the term "disk"
includes DECtapes and the term "magnetic
tape" excludes DECtapes.
Files-11 volumes must be mounted (using the MOUNT command, Section
5.6)
for
the system to access them.
Mounting a volume brings in a
task called an Ancillary Control Processor (ACP), which serves as an
interface between system and user tasks and the device driver, and
maintains the Files-11 structure on the diske
This ACP is called
FllACP.
Magnetic tapes are a sequential-access medium.
Random-access media,
such as disks,
are used where speed is the most important virtue.
Magnetic tapes are used where economy and transportability are more
important than speed.

5-3

HANDLING DEVICES AND VOLUMES
Magnetic tape volumes are of two kinds,
labeled and unlabeled.
Labeled magnetic tape volumes are accessed through the magnetic tape
ACP (MTAACP)
and conform to the ~merican National Standard for
Magnetic Tape Labels and File Structure for Information Exchange (ANSI
X3.27-1978).
Labeled magnetic tapes are sometimes called Files-11
magnetic tapes, but this is an inaccurate term;
the better term is
labeled magnetic tapes or ANSI magnetic tapes.
You can create labeled
magnetic tape volumes through the INITIALIZE command (Section 5.8).
Unlabeled magnetic tapes are in a nonstandard format and require that
you have special software to handle them.
Unlabeled tapes must be
mounted using the /NOLABEL qualifier.
Laboratory and industrial
devices
are
often
encountered
in
process-con tro 1 environments, partii:cu:Iarly on RSX_;l IM systems.
These
devices include analog-to-digital
converters
(AD:,
AF:),
the
laboratory peripheral subsystem (AR:), the graphics display processor
(GR:), industrial control systems (IC:, IP:, IS:), laboratory devices
(LA:, LS:), and the universal digital controller (UD:).
Several physical devices are used by the system in its operations.
There are communications devices, including parallel communications
links
(LT:,
LR:),
interprocessor links
(XB:,
XL:,
XM:),
and
synchronous interfaces (XP:, XQ:, XU:, XW:).
There are system control
peripherals not normally accessed by users (BS:, MK:, II:).
Finally, there are the pseudo devices, a general term used to identify
a number of system features implemented either through device drivers
without associated hardware or through logical device names.
The
pseudo devices include CO:, CL:, LB:, NL:, RD:, SY:, TI:, VT:, and
WK:.
See Section 5.1.2.1.

Vclu~es

5.1.l

and Devices

Since the information in the volume must be on some medium and since
that medium must be physically loaded on a device drive, the device
driver mnemonic sometimes denotes the device itself and sometimes it
denotes the volume.
For instance, if you have files on a volume to
which you wish to have private access, you take the following steps:
1.

Check with SHOW DEVICES dd:
to see which devices of the type
you wish to use are available. The type you wish to use is
determined by the magnetic medium the volume is on.

Make the device your
command.

Physically place the magnetic medium on the device
(This may be done for you by your system operator.)

Mount the volume through the MOUNT command.

private

device

through

the

ALLOCATE
drive.

If.the device you choose is DKl:, both the ALLOCATE and the MOUNT
command refer to DKl:.
In the ALLOCATE command, DKl:
is the device
itself, while in the MOUNT command, OKI:
is the volume.
In most
cases, this distinction is not important, but you should understand
that the expression ddnn:
refers sometimes to a physical device and
sometimes to a volume on the device.

5-4

HANDLING DEVICES AND VOLUMES
5.1.2

Physical Devices, Pseudo Devices, LUNs, and Logical Names

The purpose of devices of any kind is to handle I/O from tasks.
RSX-llM/M-PLUS systems of fer you a number of ways to name and access
physical devices=
In addition to direct access to the physical
devices by naming them in commands or file specifications, there are a
number of forms of indirect access to physical devices.
The operating system often accesses physical devices as pseudo
devices.
Tasks access physical devices through logical unit numbers
(LUNs) that establish a relationship between the I/O done by the task
and the devices on the system.
Finally, you can give any physical
device a logical name.

5.1.2.l

Pseudo Devices

The names of pseudo devices are pseudonyms used by the system to
access physical devices.
System tasks are built to reference various
pseudo devices. When the system is generated, the pseudo device names
are associated with the physical devices that are actually present on
the system.
For instance, the system uses pseudo device LB:
to refer
to the disk location of the system libraries.
At one installation,
this might be DR2:, while at another, this might be DB7:, but whatever
the actual physical device involved, the name LB: will always refer
to the current disk location of the system libraries.
Pseudo devices are implemented in several ways.
Some pseudo device
names are really only logical names.
No system data structures are
associated with logical names other than an entry in the system's
Logical Unit Table (LOT). Other pseudo device names are implemented
through redirection from one physical device to another.
Redirection
requires more system data structures:
a Device Control Block (DCB)
and a Unit Control Block (UCB).
Finally, some pseudo device names are
implemented through device drivers, which require not only full data
structures but also the presence of the driver.
qde_, ps~~dQ dE,=!'V'.~de,, MK:, ,-):,o.und, 9n ,~$4-ll.M'"".'i;iLUS, qnly., also requires the
presence of certain hardware.
Thus, the term pseudo device does not
refer to a single form of software, but rather to the concept that a
usable
device name is known to the system regardless of the
installation's device configuration.
Table 5-2 summarizes the pseudo devices on RSX-llM/M-PLUS systems.
Pseudo device CO:
is handled differently depending on whether the
system includes Console Logging. Without Console Logging,
CO:
is
redirected,
usually to the main operator's terminal, often TTO:.
Including Console Logging means a driver called CO:
is used.
This
driver permits your system manager to send system console output to
any device or to a file.
See the RSX-llM/M-PLUS System Management
Guide for more information on Console Logging.
Pseudo device CL:, the Console Listing pseudo
redirected to LPO:, the system line printer.

device,

commonly

LB:, the Library pseudo device, is the disk on which the system UFD is
located.
On

RSX-~lM~PLUS.systems,

the library UFD is also on pseudo device LB:.

5-5

HANDLING DEVICES AND VOLUMES
Table 5-2
Pseudo Devices on RSX-llM/M-PLUS
Device
Name

How
Implemented

CO:
CO:

Redirection
Driver

CL:

Redirection

LB:

Redirection

MK:"

P.river·

NL:

Driver

M:-PLUS only

Sl?:

Redirectl'on

M-PLUS only

SY:

Assignment

User default device

TI:

Dynamic
Redirection

VT:

Driver

WK:

Assignment

dd:

Driver

Hardware?

Comments
No Console Logging
Console Logging present

M~PLUS

only

M-PLUS only

Yes

Physical devices

Pseudo dev{ce MK: is implemented through redirection for internal use
on ~SX-llM--PLUS systems aQd;requirescertain hardware to be present.'
Pseudo device NL:, the null device, is implemented through the NL:
driver.
Program testing often requires an available input or output
device. The NL: pseudo device can be used for either of these
purposes.
For instance, if you are testing a program that normally generates
large amounts of output, you can assign the appropriate LUN to NL:
rather than wasting paper or disk space. The system discards output
sent to NL:.
On the other hand, if you are testing a program that
ordinarily receives input from a device or file, NL:
can generate
usable input without any other source. When a task reads from NL:,
the driver returns IE.EOF, the code for end of file.
When a task
writes to NL:, the driver returns rs.sue, the code for success.
Pseudo device RD.::
systems only.

is the .Reconfiguration D.riive:r:: found dn RSX-llM-PLUS

'Pseudo d~vice SP:. is used by: the. Queue Manag·er for
. impTem~nte(l ·through. redirect i9n.

spoolin9

a.na·: is

Pseudo device SY:
is the logical name applied to the user's default
or "home" device.
This logical name is usually established by the
LOGIN command and ACNT, the Account File Maintenance Program.
This
names the device to which all commands that do not specify a device
name default. You can display your default device with the SHOW
DEFAULT command.
You can change your default device with the SET
DEFAULT command or with the ASSIGN command.

5-6

HANDLING DEVICES AND VOLUMES
Pseudo device TI:
is always your terminal, regardless of
its number
or type.
If you are logged in on two terminals, you have two TI:s.
TI:
is dynamically redirected on a per-command basis to your current
terminal.
TI:
stands for terminal interface.
,

On ~S~-:-llM-PLUS sy~tems ,. the, VTi

driver is used for yittuat; te±:mfha~.s.

·tn .ba.t<;h processing. ,
The WK: workfile pseudo device is used by a number of
WK:
is named by assignment.

system

tasks.

NOTE
Users can also assign logical
names to
devices (see the ASSIGN command, Section
5.2),
redirect
devices
(see
the
ASSIGN/REDIRECT command, Section 5.2.1),
and write drivers (see the RSX-llM Guide
to
Writing
an
I/O Driver or---uie
RSX-llM-PLUS Guide to- Writing an I/O
Driver).

5.1.2.2

LUNs

Each task includes logical unit numbers, or LUNs,
which establish a
relationship between the
I/0 done by the task and physical device
units.
This relationship can be different for each task.
Tasks may have from 0 through 250 LUNs.
set when the task is linked.

The maximum number of LUNs is

LUNs can be assigned or reassigned in three ways:
•

Any user can specify the ASG option at link time.

•

Privileged users can use ASSIGN/TASK (Section 5.2.2)
the LUN assignments in an installed task.

to change

The task can include the ALUN$ Executive directive
(or CALL
• ASNLUN
from
FORTRAN)
to change LUN assignments during
execution.
The Task Builder defaults build a task with
assignments are as follows:

Device

LUN

SYO:
SYO:

1.
2.
3.
4.

SYO:

SYO:
TIO:
CLO:

six

LUNs.

The

default

5.
6.

This means a
task linked with the default
LUN assignments can
simultaneously refer to up to as many as six files.
Of these files,
four can be on SY:.
In this case, SY:
is logical device name SY:
as
discussed in the previous section.
Further, one file can be on pseudo
device TI:, meaning that the terminal initiating the task can be used
to communicate with the task.
And finally, one file can be on pseudo
device CL:, meaning that the task can send output to the console
listing device, which is usually a line printer or hard-copy terminal.

5-7

HANDLING DEVICES AND VOLUMES
Although the association of LUNs with physical or pseudo devices
is
established
at link time, the actual assignment is not done until the
task
is
installed,
either
explicitly,
or
through
the
install-run-remove form of RUN.
Once the LUN is assigned, a task can map directly to a device without
having
to
search device tables for the physical device.
The LUN is
simply a name used to represent the relationship between the logical
device name and the physical device.
LUN assignments are established on a task-by-task basis,
in contrast
to assignments
through the privileged ASSIGN/REDIRECT command, which
apply to all tasks using a device.

5.1.2.3

Logical Device Names

Logical device names provide a
means by which
tasks can maintain
device
independence.
Logical device names have the same syntax as
other device names, that is, ddnn:.
The 2-character device name can
be the same as a standard RSX-llM/M-PLUS device or pseudo device, such
as DK:
or LB:, or it can use two letters with an arbitrary meaning,
such as AZ:.
When you run a task that refers to a device by a logical name,
first
use the ASSIGN command to assign that logical name to the device.
See
Section 5.2.
There are three types of logical device assignment:
Local assignments, which can be made by any user,
apply only
• to
tasks
initiated
from the terminal
used
to make the

assignment.
Local assignments override both other categories
of assignments.
Different users can assign the same local
logical name to different devices.
•

Login assignments, which can be controlled only by privileged
users
through ACNT,
the Account
File Maintenance Program.
Login assignments are reestablished each time the user
logs
1n.
Login assignments can also be established through
ASSIGN/LOGIN,
a
privileged
command.
Login
assignments
override
the
next category,
global assignments.
Login
assignments apply only to systems with multiuser protection.
Login assignments remain in effect until the user logs off or
until a privileged user deassigns them.

•

Global assignments, which can be made only by privileged
users.
Global assignments apply to all tasks running in the
system.

The Executive keeps a logical unit table that
records all
logical
assignments
and
their
types.
Each time a task assigns a LUN, the
Executive refers to this table before checking the
list of physical
devices and pseudo devices.
Thus, a logical name found in the table
has precedence over a physical device unit having the same identifier.

5-8

HANDLING DEVICES AND VOLUMES
Public, Shared, Private and Unowned Devices and Mounted Volumes

5.1.3

In general, no access to magnetic media on RSX-llM/M-PLUS systems is
permitted without a MOUNT command.
If a disk volume is in Files-11
format, MOUNT grants access to the file system through the Files-11
Ancillary Controi Processor
(FllACP).
If the information on the
medium is in some other format,
or is unformatted, MOUNT/FOREIGN
bypasses the ACP and the file system.
(MOUNT/FOREIGN is required for
foreign volumes on RSX-llM-PLUS. MOUNT/FOREIGN is not required but is
recommended on RSX-llM.
See Section 5.6). Use MOUNT/FOREIGN when
initializing a volume or to use a custom ACP.
Four categories of device ownership are supported on multiuser
protection systems:
Devices can be public, shareable, private, or
unowned. Public devices are accessible to all. Within the limits of
volume
protection
and
file protection, shareable devices are
accessible to all users who have mounted the device.
Volumes on
private devices are accessible only to the owner of the device.
Volumes on unowned devices are accessible to no one on RSX-llM-PLUS.
Volumes on unowned devices can be accessed on RSX-llM.
Volume protection and file protection can greatly alter your rights of
access to a particular volume or file.
See Section 4.1.5 for more
information.
1.

Public devices are accessible to all users;
access is
allowed automatically.
Only a privileged user can set a
device public. Devices are set public through the /PUBLIC
qualifier to the SET DEVICE command (Section 5.10.2) or the
/PUBLIC qualifier to the MOUNT command
(Section 5.6).
A
public device cannot be mounted by any other user.
The
MOUNT/PUBLIC command sets the device public and deallocates
it
if it has been allocated.
(An allocated device is a
private device.)

Shareable devices are accessible to all users who mount the
volume.
A device is made shareable through the /SHAREABLE
qualifier to the MOUNT command.
(Section 5.6)
Nonprivileged
users must know the volume label in order to mount the
volume. Any number of users can mount the volume.
It will
remain mounted until the last user to mount the volume has
dismounted it. You cannot mount a public or private device
shareable.

Private devices cannot be accessed by anyone but the owner,
that is, the person who allocated the device. Devices can be
made private with the ALLOCATE command (Section 5.4), or by
the /NOSHAREABLE qualifier to MOUNT, which also allocates the
device. The DISMOUNT command will deallocate the device.
Users make devices private to prevent any other user from
accessing the mounted volume.
Any user can allocate a
device, but your installation may have restrictions on the
practice.

Unowned devices are those
mounted, or set public.

that

have

not

been

allocated,

RSX-llM systems permit limited access to unowned volumes, but
such use is not advised.
See the discussion under the
/FOREIGN qualifier to MOUNT (Section 5.6).
~SX-'l'.lM'-1?LUS permit:s no ·acces·s ·to unowned volumes.

5-9

HANDLING DEVICES AND VOLUMES
5.1.4

How to Prepare a Scratch Disk for Use

A scratch disk is a blank disk or one on which the data is of no use.
The prime example of a scratch disk is one that has never been used.
Several system utilities and DCL commands are combined to prepare the
scratch disk as a Files-11 volume.
This section summarizes the
process.
1.

Allocate an appropriate device and place the
drive.
Make sure the device is write-enabled.

disk

the

After physically placing the disk on its drive,
spin it up
and mount it using the /FOREIGN qualifier.
This permits the
system to access the disk but bypasses the file system •.·This
st:ep . is
optional on RSX-llM systems but , require<:}' ·on~;
'RSX-:.11M,-.:PLQ$,. ·

You may need to write sector and timing information about the
physical blocks on the disk.
In most cases, disk formatting
is done by the manufacturer, but some disks are shipped
unformatted.
If you have any question about formatting a
disk, see your system manager.
If formatting is necessary, you can use FMT, the Disk Volume
Formatter Utility.
Full information on this utility is given
in Chapter 5 of the RSX-llM/M-PLUS Utilities Manual. To gain
access to FMT from DCL, enter the command:

>RUN $FMT
FMT>
Now you can enter FMT commands.
4~

After you have a formatted disk, you must identify the bad
blocks on the disk.
These are blocks that are physically
unusable for some reason.
This information is often written
on disks when they are manufactured, but you can supplement
this information with BAD, the Bad Block Locator Utility,
described in Chapter 6 of the RSX-llM/M-PLUS Utilities
Manual.
In fact, FMT provides access to BAD, but you can
also run BAD with the following command:
>f.:UN

$Bf.iD

Bf:1D>

Once you have a formatted disk with identified bad blocks,
the disk driver and the disk controller have full use of the
disk.
In most cases, your scratch disk will already have
formatting and bad-block data in place.
Now you must provide
the information that the file system needs to use the disk.
This information is provided through the INITIALIZE command.
Qualifiers to INITIALIZE permit you to set up your volume for
the most efficient use by the system.
The defaults for
INITIALIZE produce a standard volume.
INITIALIZE writes a Volume Home Block, which
contains
information
for
the
system about the initialization,
including the volume label that is used to control access to
the volume by nonprivileged users.

5-10

HANDLING DEVICES AND VOLUMES
INITIALIZE also creates five files
used by the system to
locate or create other files on the volume~ Here are brief
descriptions of these files:

File

Description

000000.DIR

This is the Master File Directory
(MFD).
It is a file that contains a list of User
File Directories (UFDs).
The UFDs contain
pointers to all named files on the volume.

INDEXF .SYS

This
is the volume index file,
which
contains file-control information, such as
file protection,
creation
date,
the
physical location of the file on the
medium, and other information needed for
the system to access the files on the
volume.

BADBLK.SYS

This is the bad-block file. All unusable
blocks are included in this file.
Any
block that is included in a file
is
unavailable for any other use.

BITMAP.SYS

This file contains
information on
blocks used and free on the volume.
information is in the form of one bit
every block.
If a block is used,
corresponding bit is set.

CORIMG.SYS

This is the operating system checkpoint
file.
It is included on every volume.
If
the volume is
not
to
provide
for
checkpointing, the checkpoint file is zero
blocks long.

all
The
for
the

Once the volume is initialized, it is no longer foreign.
You
must dismount it and mount it as a Files-11 volume.
Use this
sequence of commands:
>DISMOUNT ddnn:
>MOUNT ddnn:
volumelabel

Now the volume is a Files-11 volume. The file system has full access
to the volume through a DIGITAL-supported ACP.
If your system has a
custom ACP for any device, you must mount the volume foreign and
specify the ACP.
You can alter some of the data placed in the Volume Home Block by
INITIALIZE by using the INITIALIZE/UPDATE command. See Section 5.8.1.
Certain system functions may also require that the volume be mounted
foreign without specifying an ACP.
You should check the appropriate
documentation to be sure.
This requirement may arise with the
following DCL commands:
e

BACKUP, Section 5.9

INITIALIZE, Section 5.8

5-11

HANDLING DEVICES AND VOLUMES
This requirement may also arise with the following
utilities,
described in the noted chapter of the RSX-llM/M-PLUS Utilities Manual:
•

FLX, File Transfer Utility, described in Chapter 4

•

FMT, Disk Volume Formatter Utility, described in Chapter 5

•

BAD, Bad Block Locator Utility, described in Chapter 6

•

BRU, Backup and Restore Utility, described in Chapter 7, and
accessed from DCL through BACKUP, Section 5.9 of this manual

•

DSC, Disk Save and Compress Utility, described in Chapter 8

•

VFY, File Structure Verification Utility, described in Chapter
9

•

5.1.5

DMP, File Dump Utility, described in Chapter 11

How to Prepare a Scratch ANSI Magnetic Tape for Use
1.

Allocate an appropriate device and place the
drive.
Make sure the device is write-enabled.

tape

the

After you have physically placed the tape on the drive, mount
the tape using the /FOREIGN qualifier. This permits the
system to access the tape but bypasses the file system. This
step
is
optional on RSx-llM systems but · pequ,ired:1 · .O;O;,
RSx-1:u1...;PLUS.'

Now you must provide information that the file system needs
to use the tape.
Tn1s is done tnrough tne INITIALIZE
command. Qualifiers to INITIALIZE permit you to set up your
volume for the most efficient use by the system. The
defaults for INITIALIZE produce a standard ANSI magnetic tape
volume.
INITIALIZE writes an ANSI volume label, which contains the
File Set ID and also creates a dummy file.
This dummy file
is overwritten when the first user file
is written to the
tape.
There are no UFDs in the ANSI magnetic tape
the IAS/RSX-11 I/O Operations Reference
information on ANsr-magnetic tapes.

5.1.6

structure.
See
Manual for more

Once the volume is initialized, it is no longer foreign.
You
must now dismount the volume and remount it as an ANSI
volume, using DISMOUNT and then MOUNT, this time without the
/FOREIGN qualifier.

Summary of Device and Volume Use Commands

All Files-11 volumes and ANSI and unlabeled
mounted for any access.

magnetic

tapes

must

All other volumes are considered foreign volumes.
Foreign volumes are
normally mounted with the /FOREIGN qualifier to MOUNT.
On RSX-llM, you are not required to mount foreign volumes, but if you
do not,
the system and other users have unlimited access to the
5-12

HANDLING DEVICES AND VOLUMES

ASSIGN
volume, as it is considered unowned. MOUNT/FOREIGN is recommended for
most use of foreign volumes on RSX-llM.

"di;iti~sx:~iiM.'..J?t.ids) ~on rilus't ,mou'nt' .· "roi¢f~n: ":.tolunle~;~:: .· fM~o.NifJJE>.oR:~iaNr

~,:·~e5~:?.J~~~;~":·:;~;·~:~;f a.~J ..ui~ /o'~: . if>.~<e'!.~::i: 1v~1.u~s,t ?,ns.~.9~f1;~f;t-:-.~:Lg·~::i / {f ·, · '

Multiple users can mount a volume on a shareable device.
The volume
remains mounted until all users who have mounted it dismount it.
Ownership of a device on a system with multiuser protection is of four
kinds:
•

A volume on a private (allocated) device can be mounted by the
owner only.

•

A volume mounted /SHAREABLE by the first user to mount it can
be mounted by any other user who knows the volume label.
The
volume stays mounted until the last user to mount it dismounts
it.

•

A volume on a public device is usually mounted after the
device is set public.
The system owns public devices.
Mounting a public device means other users can access the
device without mounting it.
Only a privileged user can set a
device public or nonpublic.
Public devices
cannot
be
allocated.

•

A volume on an unowned device can be mounted by anyone.

Any user who mounts a volume has full access to that volume within the
limits of privilege and volume and file protection.
Privileged users
have privileged access.
Nonprivileged users have
nonprivileged
access.
Nonprivileged users have privileged access to volumes mounted
on their private (allocated) devices.
A mounted device cannot be set public
allocated or deallocated.

nonpublic,

and

cannot

LOGOUT issued by any user automatically dismounts any volumes mounted
from that terminal and deallocates any devices allocated from that
terminal. A mounted public device is not dismounted by LOGOUT,
however.

5.2

ASSIGN

ASSIGN associates a logical name with a physical device,
pseudo
device,
or other logical device.
All references to the logical name
are resolved by the system to the associated physical device,
pseudo
device, or logical device.

Format
ASSIGN[/qualifier[s]]
Device? ddnn:
Logical device? logicalddnn:
ASSIGN[/qualifier[s]] ddnn: logicalddnn:

5-13

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)
Command Qualifiers
/LOCAL
/LOGIN
/GLOBAL
/SYSTEM
/TERMINAL:ttnn:
Parameters
ddnn:
Specifies the name of the physical device, pseudo
logical device that is to receive the logical name.

device,

logicalddnn:
Specifies the logical device name to be given
device, pseudo device, or logical device.

the

physical

The logical device name consists of a 2-letter mnemonic followed
by an octal number terminated with a colon (:). There is no
restriction on logical device names.
They may use standard
device mnemonics, such as DKO: or SPO:, or random letters, such
as AZl:.
Command Qualifiers
/r.O!:A f.

Specifies that the assignment is to be a local assignment.
This
is the default qualifier. It need not be specified. Commands
and tasks initiated from your terminal can access devices through
the logical names assigned to them. No automatic deassignment
occurs when you dismount the device. Any terminal can define its
own set of local assignments. The terminal defining the local
assignments is the only one for which th~ logical devices exist.
/LOGIN
Specifies that the assignment is to be a login assignment.
is a privileged qualifier.

This

Login assignments occur only in systems that support multiuser
protection.
When a user issues a LOGIN command to log in to the
system, the system automatically assigns the logical name SYO:
to the user's system device, which is the device that contains
the user's files.
Login assignments are usually established
through ACNT, the Account File Maintenance Program. ASSIGN/LOGIN
does not alter the account file.
/GLOBAL
/SYSTEM
Specifie~

that the assignment is to be a global assignment. This
is a privileged qualifier.
/SYSTEM is a synonym included for
VAX/VMS compatibility.
Global assignments apply to all tasks

5-14

r,D~ning

in rhP system.

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)
/TERMINAL:ttnn:
Specifies that the requested local assignment be applied to
another
terminal.
Only
a
privileged terminal may make
assignments to other terminals. RSX-llM-PLUS only.
Examples

>t1:3SIGi""--1
Di:. ~vice·"
DBl ~
Logical device 7

TP1:

This example assigns the logical name TPl:
to the physical
device DBl:. The user may now issue commands referring to device
TPl:
in any command that accepts a device specification and DBl:
will be substituted for it.

>ASSIGN LBO!

PR2:

This example assigns the logical name RR2:
LBO:.

to the pseudo

device

This .example ass1grls 'the .logical. name LNl:
to· the p«tw:sfcal
de.vtCe DBT:
all commands' 'and tasks ini Hated fr.om. TT22: •.
·This: command must ·be ··issued from ·a. prf.J~\eged:: · ·:t:er:ird:n~r~
Rsx.;..;11,M-PLUS only •..

for .

>ASSIGN/GLOBAL DKl:
This example assigns the logical name XXl:
to the physical
device DKl:. All users and tasks on the system can refer to XX!:
when they initiate commands and tasks.
This command must be
issued from a privileged terminal.
DKl: can also be used to
reference DKl:.
Notes
Local assignments have precedence over both login and global
assignments.
Login assignments have precedence over global
assignments. When a user deassigns a local logical name,
the
system defaults to any login assignment of the same name.
You can display current assignments
described in Section 5.10.1.
ASSIGN is counteracted by DEASSIGN.
with

You can assign SYO:
4.5.1.
ASSIGN/REDIRECT is
5.2.1.

with

SHOW

ASSIGNMENTS,

See Section 5.3.

SET

DEFAULT,

described

Section

separate

command,

described

Section

ASSIGN/TASK is a separate command, described in Section 5.2.2.

5-15

HANDLING DEVICES AND VOLUMES

ASSIGN/REDIRECT
ASSIGN/QUEUE is
a
separate
command,
described
RSX-llM/M-PLUS Batch and Queue Operations Manual.

the

ASSIGN/REDIRECT

5.2.1

ASSIGN/REDIRECT redirects output from one physical device to another.
You can also redirect a physical device to a pseudo device, or vice
versa. Use this privileged command when a device is unavailable and
you have another device that can take its place.
The devices need not
be of the same type.

Format
ASSIGN/REDIRECT
From? oldddnn:
To? newddnn:
ASSIGN/REDIRECT oldddnn:

newddnn:

Parameters
oldddnn:
Specifies the device from which requests have been redirected.
newddnn:
Specifies the device to which subsequent
are to be redirected.

requests

for

oldddnn:

Example

>ASSIGN/REDIRECT DTO:

>s H0 lJ Dn1 l c: : i:: r '( p E DT :

DTO:
DT1:

DT3:

DT2:

L.Ot1DED
UlADFl.1

DT3:

L.OADEU

DT3!

LOADED

>ASS I GN/F:ED I HECT

FROM?

DTO!

TO?
DTO:
>SHOW DEtJ DT:
DTO:
L01~DED
DT1:
LOADED
DT2:
LOf'1DED
DT3:
LOADED

This example shows the process of redirection.
Following the
first ASSIGN/REDIRECT,
any output for DTO:
is sent to DT3:, as
indicated by the first SHOW DEVICES display.
Later, when DTO:
is again available,
the user issues ASSIGN/REDIRECT again to
redirect DTO:
to DTO:.

5-16

HANDLING DEVICES AND VOLUMES

ASSIGN/REDIRECT (Cont.)
Notes
Redirection does not affect any I/O requests already in
queue.

the

I/O

The following restrictions apply to this command:
•

You cannot redirect from or to a logical device name.

•

You cannot redirect from one pseudo device to another pseudo
device.
You can, however, redirect a pseudo device to a
physical device or vice versa.

•

You cannot redirect pseudo device TI:.

•

You cannot redirect an attached or spooled device.

•

You cannot redirect a device unit containing a mounted volume.

•

You cannot redirect a logged-on terminal
than another terminal.

device

other

Error Messages
A** -- Circular redirect error

Explanation: Command attempted to establish a circular
redirections.

list

User Action: Check available devices with SHOW DEVICES
up legal redirection list.
Reissue command.

and

set

A** -- Device not redirectable

Explanation: Command attempted to redirect a device that
be redirected.
User Action:

cannot

Check command for proper device names and reenter.

A** -- New device not known to system

Explanation: An ASSIGN/REDIRECT attempted to redirect to
device that is not in the current system.

new

User Action: Check the devices on the system with SHOW DEVICES.
Retype the command after checking for proper device names.
A** -- Old device attached

Explanation:
or spooled.
User Action:
accordingly.

The oldddnn:
Find

the

specified in the command is

attached

cause

proceed

5-17

the

error

and

HANDLING DEVICES AND VOLUMES

ASSIGN/TASK
A** -- Old device mounted

Explanation: The oldddnn:
mounted volume.
User Action:

specified in the command

contains

Wait for device to become available.

A** -- Old device not known to system

Explanation:

An ASSIGN/REDIRECT attempted to redirect an unknown

device.

User Action:

Check devices with SHOW DEVICES.
after checking for proper device names.

Reenter

command

A** -- Pseudo device redirect error

Explanation:

Command attempted to redirect a
another pseudo device.

pseudo

device

User Action:

pseudo

device

None.
You
another pseudo device.

cannot

redirect

A** -- TI redirect error

Explanation:

Command attempted to reedirect pseudo device TI:.

User Action:

None.

TI:

cannot be redirected.

ASSIGN/TASK

5.2.2

ASSIGN/TASK reassigns an installed task's logical unit numbers
from one physical device to another.

{LUNs)

The reassignment overrides the static LUN assignments
disk image file.

task's

the

This is a privileged command.

Format
ASSIGN/TASK
Task? taskname
Device? ddnn:
Logical Unit? lun
ASSIGN/TASK:taskname ddnn:

lun

Parameters
task name
Identifies the installed task whose LON you wish to reassign.

5-18

HANDLING DEVICES AND VOLUMES

DEASSIGN
ddnn:
Specifies the new device to which you wish the LUN reassigned.
This can be a physical device, pseudo device, or logical device
name.
lun
Specifies which LUN you wish to reassign to the new device.

Examples

>ti SS I GN/ T f~l S 1-:; ! NI \:. 14
It e vice·;.

DP 1

Lo~.lical

unit'r

i'.'."1

'.~)

This example overrides the assignment of
link time and reassigns LUN 5 to DBl:.

LUN

established

This example overrides the assignment of
link time and reassigns LUN 4 to TTl:.

LUN

established

This example overrides the assignment of LUN 3 established
link time and reassigns LUN 3 to logical device name AZl:.

>ASSIGN/fASK!GIVBON All!

Notes
ASSIGN/TASK has no effect on a memory-resident task.
Thus,
this
command has no effect on currently executing tasks or tasks fixed
in memory.
You can use ASSIGN/REDIRECT for dynamic device
reassignments.

Error Message
A** -- Lun out of range

Explanation:

Command attempted to reassign a LUN that was higher
than the maximum number of LUNs allocated during the task link.

User Action:

Issue SHOW TASK:taskname/LOGICAL UNITS to determine
how many LUNs were allocated.
-

5.3

DEASSIGN

DEASSIGN deletes logical-device assignments.
DEASSIGN disassociates
logical names
from physical device names, pseudo device names, or
logical device names assigned by ASSIGN.

5-19

HANDLING DEVICES AND VOLUMES

DEASSIGN (Cont.)
Format
DEASSIGN[/qualifier(s]]
Logical device? logicalddnn:
DEASSIGN(/qualifier[s)]

logicalddnn:

Command Qualifiers
/LOCAL
/ALL
/GLOBAL
/SYSTEM
/LOGIN
/TERMINAL:ttnn:
Parameter
logicalddnn:
Specifies the logical device name, assigned by ASSIGN, that is to
be deassigned.
This is a required parameter except with the /ALL
qualifier. Logical device names have the same format as all
other device names,
a
2-letter mnemonic followed by an octal
number terminated with a colon (:).
Command Qualifiers
Any other qnalifier can be used with /ALL.
qualifier can be used with /LOGIN or /LOCAL.

The

/TERMINAL

/LOCAL
Specifies that a local logical name is to be
the default.

deleted.

This

/ALL
Specifies that all assignments of the specified type are to be
deleted.
If this qualifier is used alone, all local assignments
are deleted. This qualifier can be used with other qualifiers.
/GLOBAL
/SYSTEM
Specifies that a global assignment is to be deleted.
/TERMINAL
may not be specified with /GLOBAL. /SYSTEM is a synonym included
for VAX/VMS compatibility.
This is a privileged qualifier.
/LOGIN
Specifies that a login assignment is to be deleted.
This is a privileged qualifier.

5-20

HANDLING DEVICES AND VOLUMES

DEASSIGN {Cont=)
/TERMINAL:ttnn:
Specifies that the logical assignment to be deleted applies to
another terminal.
/TERMINAL may not be specified along with
/GLOBAL.
Only privileged terminals can delete assignments made from
terminals.
This qualifier is for RSX-llM-PLUS only.

other

Examples

>DEASSIGN
Losical device?

TPO:

This example deletes the assignment of logical device
to a device.

name

TPO:

>DEASSit'3Nl't1L.L

This example deletes all local logical-name assignments.
>DEAS/L.CCt.i... ./t.11...L.

This example is the equivalent of the previous
is the default qualifier.

example.

/LOCAL

>DEr'.~S/LOCtil../(11 . L /TEF'h l NF1L.. ! Tr;;;: l t

This example deletes all local assignments from terminal
This command must be issued from a privileged terminal.

TT21:.

Notes
DEASSIGN counteracts ASSIGN.
You must type at least the first four characters of DEASSIGN.
Login assignments are normally established
Account File Maintenance Program.

through

You can display assignments with SHOW ASSIGNMENTS.
5.10.1.

ACNT,
See

the

Section

All local assignments disappear when you log out.
DISMOUNT does not delete logical name assignments.
DEASSIGN/QUEUE is a separate command.
See the RSX-llM/M-PLUS
Batch and Queue Operations Manual for more details.

Error Message
DEA -- Device not terminal

Explanation:

The /TERMINAL qualifier named a device that is

a terminal.

User Action:

Retype command after checking proper syntax.
5-21

not

HANDLING DEVICES AND VOLUMES

ALLOCATE
5.4

ALLOCATE

ALLOCATE declares a specified device to be a private device.

Format
ALLOCATE[qualifier[s]]
Device? dd [nn:] [logicalname]
ALLOCATE[/qualifier[s]] dd[nn:]

[logicalname]

Command Qualifier
/TERMINAL:ttnn:
/TYPE:devicetype

Parameters
dd [ nn:]
Specifies the device or device type to be allocated.
The device name can be entered in one of two forms.
•

If you use the form ddnn:,
allocated, if available.

the

specified

device

•

If you use the form dd without the number or the colon, the
first available device of the specified type is allocated.
This is called generic allocation.

logicalname
Assigns a logical name to the device as you
parameter is optional.

allocate

it.

The logical name must be of the form xxnn:.
the
same
form as device names.
The
automatically.

Logical names
assignment
is

This
take
done

Command Qualifiers
/TERMINAL:ttnn:
Allocates the device to
privileged qualifier.

the

specified

terminal.

This

/TYPE:devicetype
Specifies the type of device you wish to allocate.
Use this
qualifier with the generic allocation feature.
If you issue an
ALLOCATE command with the device name specified in the form dd
without unit number or colon, the first available device with the
name dd is allocated.
Since devices with names beginning with DB
can be RP04s, RP05s, or RP06s, and since the disk packs for these
devices are not compatible, you could do a generic allocation
specifying /TYPE:RP04 to allocate the first available RP04.
See
the examples.

5-22

HANDLING DEVICES AND VOLUMES

ALLOCATE (Cont.)
Examples

>~1 L L DCf1 T E f ! 1<
ALL -- DKO:

Now allocated

This example allocates the first available RK05
message gives the name of the device allocated=

drive.

The

This is an example of a generic allocation.
>ALLOCATE-~
IH~l t

Device?

This example allocates the specified device. The allocation
confirmed by the return of the prompt.
No message.
>r-=1LL TJt<1:
AL L - -· De v :i c e a 1 l o c a t P d

c1 t he r

~J ·:; e r

This example shows an allocation that failed because
named was not available.
>t1LL.. DB3 !

the

device

TF'O ~

ALL -- DB3!

Now

alloc~te~

This example allocates the specified device and
logical name TPO:.

assigns

the

>ALLOCATE/TYPElRP04 DB
.~LL

- -

DB3 !

Now .:;, 11 o ca t E·~ (";

This example shows the use of the /TYPE qualifier.
The user
wished to allocate the first available RP04 but to ignore any
other devices using the DB driver.
This
is also a generic
allocation.

Notes
When you allocate a device, no other user can gain access to
device.
DEALLOCATE counteracts ALLOCATE.

the

See Section 5.5.

If more than one user needs to access a volume on a device,
the
device should not be allocated.
Each user should mount the
volume.
It remains mounted until all users who have mounted
it
have dismounted it •
.You cannot include ALLOCATE in RSX-llM-PLUS batch jobs. See the
RSX-llM/M-PLUS Batch and Queue Operations Manual for information
on private devicesln batch jobs.

5-23

HANDLING DEVICES AND VOLUMES

DEALLOCATE
Error Messages
ALL -- Device allocated to other user
Explanation:
Command attempted
allocated by another user.

allocate

device

already

User Action: Wait to allocate the device until the other user
has deallocated it.
(The terminal from which the device was
allocated can be displayed by SHOW DEVICES.)
ALL -- Device attached
Explanation: Command attempted to allocate
running task.
User Action:

device

attached

Wait to allocate device until task is finished.

ALL -- Pseudo device error
Explanation: Command attempted to
Pseudo devices cannot be allocated.
User Action:

allocate

pseudo

device.

Retype command after checking proper device name.

ALL -- Public device
Explanation:

Command attempted to allocate a public device.

User Action:

Public devices cannot be allocated.

ALL -- User logged on terminal

5.5

Explanation: Command attempted to allocate a terminal logged
by another user.

User Action:
allocated.

Only terminals

that

are

not

logged

can

DEALLOCATE

DEALLOCATE counteracts ALLOCATE.
by other users.

It frees a private device for access

Format
DEALLOCATE[/qualifier]
Device? ddnn:
DEALLOCATE[/qualifier] ddnn:
Command Qualifiers
/ALL
/DEVICE
/TERMINAL:ttnn:

5-24

HANDLING DEVICES AND VOLUMES

'
DEALLOCATE
(Cont.)
Parameter
ddnn:
Specifies the device to be deallocated.
Command Qualifiers
/ALL
The /ALL qualifier frees all devices allocated from the terminal
being used.
If you use this qualifier, you cannot specify a
device name.
/DEVICE
This qualifier is a no-op.
/TERMINAL:ttnn:
This qualifier enables a privileged user to deallocate
allocated from another terminal.
(RSX-llM-PLUS only.)

devices

Example
>DE~1LLOC1~;TF

Device?

DBo:

This example deallocates the device DBO:
the user.

previously allocated by

Notes
Nonprivileged users can deallocate only those devices that they
have previously allocated.
Privileged users can deallocate any
private device.
DEA is the short form of DEALLOCATE.
Error Messages
DEA -- Device allocated to another user
Explanation: Command attempted to deallocate a device
by another user.

allocated

User Action: Nonprivileged users can only deallocate devices
they have allocated from the same terminal.
SHOW DEVICES
displays the terminal from which the device was allocated.
DEA -- Device mounted
Explanation:

Command attempted to deallocate a mounted device.

User Action:
the device.

You cannot deallocate a mounted

5-25

device.

Dismount

HANDLING DEVICES AND VOLUMES

MOUNT
5.6

MOUNT

MOUNT declares a volume to be logically known to the system, on line,
and available for use.
Some qualifiers can be used with any MOUNT
command;
some
are
limited
to
mounting
disks
(and
other
random-addressable devices),
and others are limited to mounting
magnetic tapes.

Format
For Disks and Other Random-Addressable Devices
MOUNT[/qualifier[s]] ddnn:

volurnelabel

For Magnetic Tapes
MOUNT[/qualifier[s]] ddnn: [,ddnn: ••• ] fileset-ID

Command Qualifiers for Both Disks and Tapes

/~E~~q~1r'.: ~ rg, .
SAVE
.Ii'

1
'

[NdJUN~OAt>

/FILE PROTECTION:{code)
/FOREIGN
/OVERRIDE:IDENTIFICATION
/PARAMETERS:"user parameters"
/PROCESSOR:arg
acpname
UNIQUE[:acpname]
/PROTECTION:(code)
/PUBLIC
/[NO]SHAREABLE
/[NO]SHOW
/SYSTEM (synonym for /PUBLIC)
/[NO]WAIT
/[NO]WRITE

Command Qualifiers for Disks and Other Files-11 Devices
/ACCESSED:n
/EXT ENS ION: n
/OWNER: [uic]
/UNLOCK
/WINDOW:arg
n

{USER:n,INDEX:n)
FULL

5-26

HANDLING DEVICES AND VOLUMES

MOUNT {Cont~)
Command Qualifiers for ANSI and Unlabeled Tapes
/BLOCK SIZE:n
/CARRIAGE CONTROL:arg
FORTRAN
LIST
NONE
/DENSITY:arg
800
1600
6250
/[NO]HDR3
/[NO]LABEL
/OVERRIDE: (arg [, s] )
ACCESSIBILITY
EXPIRATION DATE
SET IDENTIFICATION
/RECORD SIZE:n
/TRANSLATE:arg
EBCDIC
NONE
UTl
UT2
UT3
/VOLUME IDENTIFICATION: (volume-ID[,volume-ID[,s]])
Parameters
ddnn:
Specifies device on which the volume is to be mounted.
You can
mount only one disk or other random-addressable device, but you
can mount several magnetic tapes. See the discussion of mounting
tapes and tape sets in Section 5.6.1.
NOTE
Disks and magnetic tapes differ
in the
way
labeling
is handled.
See the
separate discussions of volumelabel and
fileset-ID.
See also Section 5.6.1 for
more on magnetic tape Volume IDs and
File Set IDs.
volumelabel
Specifies the volume label, that is, the name associated with the
volume.
Volume labels are mandatory for nonprivileged users.
You must supply a volume label for each volume you wish to mount.
Disk and random-addressable volume labels can be as many as 12
characters.
Volume labels
(or identifiers)
can include any alphanumeric
character
without
restriction,
and
can
also
include
nonalphanumeric symbols, including the following:
<space> !

()*+,-.

5-27

<=>?

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
Labels including these characters must be enclosed in "quotes".
If the label includes the quotation mark itself ("), the
quotation mark must be followed by another quotation mark.
The
extra quotation marks do not count in figuring the length of the
label. See the examples.
Note that the at sign (@), semicolon (;), and dollar sign ($) are
not accepted in volume labels.
f ileset-ID
Magnetic tape Volume Identifiers or File Set Identifiers can be
as many as six characters in length. By default, the Volume
Identifier on the first tape named in a MOUNT command is taken as
the File Set Identifier as well. See the discussion in Section
5.6.1 for
the distinction between magnetic tape File
Set
Identifiers and magnetic tape Volume Identifiers.
Command Qualifiers

/DEFAULT:arg
SAVE

'[NO'] UNLOAD
This quant:ier is for Rsx:..uM-P.LUS systems only.
DB:, oM:i1: 'and DU: devkes only.

apJ?lies;

Speci f:ie:s the default th.at , will ~J?ply when the volum~i : ,is
di:sJnount~:.. SAVE' i's .a pxivileged argumen:t and. spec1,f1es
;tn~:
·mepii um; disi not 1un;ljoapeP ~;ndi :cap! be aqce15s~~l #>r re~ds anp w;rjiteis
by ' pri1vi;leged: . tas~ 1s. ,. UNLOAD: s;1?eCi f.ies ·th.a,t the ,medium is. ,t:o .~
<u~lbadek:i: la:f'.ter" :th~ cfismou·nt.: 1 !rhi;s· 'i:sl ;the: : d~f:ault. · f-Ofr . F,J.'1~:-1:1
vo:1iume!s .: 1 ~ lNOUN4d,Aq . ;s,pebHie~11 1 tha,;t :. ;th;e ~<Hum is n.ot 1!t!o. :Qe
un:l\Oad;e;a.:
;This' is ,t:hie:
<J.e:f;auTt;.
'.for f'oir~:ig;n;
:Volume~.
:: ·
l ;
. s, !
,. .
.
. , ..
.
. , , ,

that!

<·

Ortly p.ri~ileged' u;se:rs can specify /DEF,AULT=UNLOAD fo'r a mul t;fon it
dev!ice· Cf,or exami>;l~·,_ an) RC25) •
·
can' . also be,
See sect ion 5. 7.

RetneJObF.r ,' these v;alue's'_
DISMOUNT

command:.

set,

when

yqu

issue

the

/FILE_PROTECTION: (code)
Specifies the default file protection for any new files created
on the volume while it is mounted. The file-protection code is
enclosed in parentheses. See Section 4.1.5 for more information
on file-protection codes and the relationship between file
protection and volume protection.
See also the /PROTECTION
qualifier to MOUNT.
The default file protection can be overridden
another protection when the file is created.
If this qualifier is not included, the value
time the volume was initialized is applied.

specifying

specified

the

For ANSI magnetic tapes, this qualifier specifies the protection
applied to the volume.
See the RSX-llM/M-PLUS I/O Operatiqns
Manual for further information on '~Ene·~ -fra·nsration···· f'rom-·"thTS
coding to ANSI label coding.
5-28

HANDLING DEVICES AND VOLUMES

MOUNT {Cont.)
/FOREIGN
Specifies that the volume being mounted is not in Fi les-11
format.
Such volumes are called foreign volum~s. Note that
before a disk or tape has been initialized, it is a foreign
volume.
This qualifier functions slightly differently on RSX-llM
and RSX-llM-PLUS~
On. RSX-llM, /FOREIGN is recommended but not required fo.r mounting
toreign .. volumes.
If you do not mount the volume, access to the
volume. is ur;irestricted ~
If you mount a foreign :volume /FOREIGN,
no one else can access it.
I f yo.u include /FOREIGN when mounting
thi=· foreign volume· /SHAl~EAB.LE, then other. users must also mount
the ·volume to access it •.·
··

on :,i RSX ~,1::1 M;.::.;PL.Q;S~:;:: ;!: iJ;.:. itjt1 aFI ;l,:':f;. .~·t'
\r.Ql'Um~$ ~ /,; :· .::·'."' ..<. .: .:::,: ;,/' ;.:t :' /. ;. '.: t}. ;: i.t::
/OVERRIDE: IDENTIFICATION
Allows privileged users to mount a volume without using the
volume
label
(or
the
File Set ID for magnetic tape).
Identification is the default argument for /OVERRIDE.
If you are mounting a magnetic tape, you may want to combine the
IDENTIFICATION argument with other /OVERRIDE arguments that are
limited to use with magnetic tape.
See the description of
/OVERRIDE in the magnetic tape section.
/PARAMETERS:"user parameters"
Enables you to enter commands to an ACP that is not DIGITAL
standard.
MOUNT/PARAMETERS passes a maximum of 40 characters
enclosed in quotation marks to a foreign ACP. You must use the
/FOREIGN and /PROCESSOR qualifiers with this qualifier.
If the
quoted command includes the quotation mark itself
("), the
quotation mark must be followed by another quotation mark. The
extra quotation marks do not count in figuring the length of the
command.
/PROCESSOR:arg
acpname
UNIQUE[:acpname]
Allows privileged users to specify the name of the ACP to use to
support file activity on the volume.
In most cases, you can use
the default ACP. The default ACP depends on the device type.
If the device is a disk, MOUNT searches for an ACP with a name in
the form ddnnFl. Failing that, MOUNT searches for an ACP with a
name in the form ddAACP, and finally, for an ACP named FllACP.
Thus,
for an RK05 device, which uses the device name DK:, MOUNT
looks first for an ACP named DKnnFl, where nn is the device
number.
If no ACP of that name exists, MOUNT looks for an ACP
named DKAACP, and finally, for FllACP.

5-29

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
If the device is a DECtape, MOUNT first looks for an ACP with a
name in the form ddnnFl.
Thus, for a TCll DECtape, which uses
the device name OT:, MOUNT looks first for an ACP named DTnnFl,
where nn is the device number. For a TU58 DECtape II, which uses
the device name DD:, MOUNT looks for an ACP named DDnnFl.
If no
ACP of the appropriate name exists, MOUNT looks for an ACP named
ddAACP. Failing that, MOUNT seeks an ACP named DTAACP, and
finally, for the FllACP.
If the device is a magnetic tape, MOUNT first looks for an ACP
with a name in the form ddnnFl. Thus, for a TS04 device, which
uses the device name MS:, MOUNT looks first for an ACP named
MSnnFl, where nn is the device number.
If no ACP of that name
exists, MOUNT looks for an ACP named MSAACP, and finally, for the
MTAACP.
You only have to specify an ACP in special cases.
If an ACP has
been written for a custom application in your installation, you
will need to use that ACP for volumes used by that application.
You will also have to include the /FOREIGN qualifier in this
case. You may also need to use the /PARAMETERS qualifier to
enter parameters used by that ACP.
The UNIQUE argument specifies that a dedicated ACP is to be used
for the volume being mounted.
If you do not name an ACP with the
UNIQUE argument, MOUNT creates a copy of the FllACP if the device
is a disk or DECtape, or of the MTAACP if the device is a
magnetic tape. This unique ACP will be given a name of the form
ddnnFl
or ddnnACP.
When the volume is dismounted and the file
processor exits, the ACP is automatically removed.
Qn RSX-11M-.PLUS 1only, if the ACP (FllACP or MTAACP) is
in second:ary 'pool, /PROCESSOR:UNlQUE is the default.

,installed

If you specify the UNIQUE argument naming a foreign ACP, that ACP
is created and dedicated to your volume.
If you name a foreign
ACP, you need the /FOREIGN qualifier.
You may also need the
/PARAMETERS qualifier.
SYSTEM MANAGERS
You can control the resources dedicated
to
file
processing
by
choosing
appropriate names for installing ACPs.
For example, if you wish DBO:
to have a
dedicated ACP and for DBl: and DB2: to
use a shared ACP, install the FllACP as
DBOOFl and as DBAACP.
If you mount a volume /FOREIGN but do not specify an ACP, no ACP
can access the volume, but tasks such as INITIALIZE, DSC, BAD, or
user tasks with non-file-structured device QIOs can access the
foreign volume.

5-30

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
/PROTECTION: (code)
Specifies the volume protection for Files-11 disks.
This
protection overrides the volume protection established when the
volume was initialized. The /PROTECTION qualifier combines with
the /OWNER qualifier to control access to the volume. See
Section 4.1.5 for more information on volume protection.
/PUBLIC
/SYSTEM
These two qualifiers are synonyms.
included for VAX/VMS compatibility.

The

/SYSTEM

qualifier

Privileged. Specifies that the mounted volume be available to
all users who are allowed access under the volume-protection and
file-protection codes established for the volume when mounted.
See the discussion of file protection and volume protection in
Section 4 .1. 5.
If you state this qualifier explicitly when mounting a volume on
an allocated
(private)
device,
the device is automatically
deallocated and set public, if necessary.
If you do not state this qualifier explicitly, and the device
already set public, the mount will default to /PUBLIC.

See the discussion of public, private, and shareable
Section 5.1.3.

volumes

/[NO]SHAREABLE
Specifies whether the volume is to be mounted shareable.
A volume mounted /SHAREABLE can be mounted multiple times by the
same or different users. See the discussion of multiple mounts
in Section 5.1.3.
Each user's access is determined by the
volume-protection and file-protection codes established for the
volume when mounted.
See the discussion of file protection and
volume protection in Section 4.1.5.
If you mount the volume /SHAREABLE and the device is allocated or
set public, the device is automatically deallocated or set
nonpublic.
A volume mounted /NOSHAREABLE is dedicated for your private use.
No other user can access the volume.
For Files-11 volumes
mounted /NOSHAREABLE, your privileges are SYSTEM privileges. See
the discussion of file protection and volume protection in
Section 4.1.5.
If you specify /NOSHAREABLE explicitly when mounting a volume
a
device,
the device is allocated and set nonpublic,
necessary.

on
if

If the device
/NOSHAREABLE.

defaults

default

already

allocated,

If the device is not allocated or
/SHAREABLE.

5-31

set

the

mount

public,

the

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
If the device is set public, the
/SYSTEM) •

default

/PUBLIC

See the discussion of public, private, and shareable
Section 5.1.3.

(synonym:
volumes

I [NO] SHOW
Specifies that information about the volume being mounted
be displayed on your terminal.

Here is the display format for disks and other random-addressable
devices:
Volume Information
Files-11 or Foreign
Class:
ddnn:
Device:
Volume label: label
Pack Serial: serial number supplied by manufacturer
[g ,m]
Owner:
Protection:
code
code
Default:
acpname
Processor:
The owner field indicates the owner of the volume. The UIC must
be matched for protection checks for owner privileges.
The owner
UIC can be changed with the /OWNER qualifier. See Sections 5.1.3
and 4.1.5 for more information.
Protection indicates volume
protection; Default indicates file protection.
The information displayed by /SHOW is similar for magtapes.
If
multiple tape volumes are being mounted, the device and volume
label information is repeated for each volume.
The Protection
and Default fields are omitted from the volume information for
magtapes.
/[NO]WAIT
Specifies whether you require operator assistance in performing
the mount.
The main use of this qualifier is for batph jobs,
indirect command files, or terminals distant from the machine
room.
The default is /WAIT for mounts in batch jobs arid indirect
command files, and /NOWAIT for interactive mounts.
If the mount is included in a .batch j·ob oi: indirect command file,
or if you specify /WAIT in an interactive mount, a message
concerning the mount is sent to the operator's console and the
mount is not completed until the operator physically places the
disk on the drive and spins it up.
If you specify /NOWAIT in a
batch
job or indirect command file,
or if the mount is
interactive, no message appears.
The medium must have been
placed on the device and readied for access (spun up/on-line) •
See the examples.

Batch prodessing
available on Rsx..'..nM:.pL'tJS sysiems only~·
For
·more.· . inforµtation on mounts. from. b~tcn jo.bs} ~~e t,he q s·cu~~i9.n of
f;tOtJtiT·· in, th'e ··!{sx:-llM/~•·PLUS·~ ~a~?h, and', Quetle'. Opera'ti'on Manual··

5-32

HANDLING DEVICES AND VOLUMES

MOUNT (Cont)
/[NO]WRITE
Specifies whether the volume is to be write-protected.
The
default is /WRITE.
If /WRITE is specified or implied, the volume
can be written to as permitted by the volume-protection and
file-protection codes established for the volume when mounted.
See the discussion of volume protection and file protection in
Section 4.1.5.
If /NOWRITE is specified, no one may write to the
volume.

Command Qualifiers for Files-11 Devices
/ACCESSED:n
Specifies the approximate number of directories that will be
accessed simultaneously during the mount.
Legal values for n
range from 1 through 127.
FllACP maintains a list of most
recently used directories.
The value specified for /ACCESSED
sets the number of entries in this list.
In general, directory operations can be significantly speeded up
by increasing this value.
If a directory appears in the list, no
disk I/O is required to find the directory in the MFD.
In
addition, directory operations take place without the necessity
of reading the directory file header.
If this qualifier is not
explicitly stated, the default is the value specified at the time
the volume was initialized. Note that increasing the /ACCESSED
value increases the amount of system pool used.
/EXTENSION :n
Specifies the number of blocks by which a file will be extended
if it exhausts its space allocation.
The value of n can be from
1 through 127. The default is the value specified when the
volume was initialized.
/OWNER: [g ,m]
Specifies the owner of the volume.
The brackets are required
syntax.
This qualifier overrides the OWNER value established
when the volume was initialized. The owner value is used with
file and volume protection. See Section 4.1.5.
/UNLOCK
Specifies that the volume index file,
[O,O]INDEXF.SYS,
is
unlocked.
This means the file can be read and written to.
Normally, this file is locked and can be read only.
This qualifier has
write-locking.

nothing

5-33

with

hardware

software

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
/WINDOW: arg
n

(USER: n, INDEX: n)
Specifies the default number of mapping pointers to be allocated
for file windows when the file is accessed. Legal values for n
range from 1 through 127 or the word FULL.
A file window
consists of a number of mapping pointers stored in memory when
the file is opened. If you specify FULL, windows are created
that map as much of the file as possible.
If you wish, you can specify different values for the user
default and index file.
If separate values are specified, the
volume default will be the same as the user default specified and
the index file window is created with the value specified.
The default for /WINDOWS is the value specified in the Volume
Home Block.
This value is established when the volume is
initialized.
If you wish to change that value, see
the
INITIALIZE/UPDATE command
(Section 5.8.1)
for information on
altering the Volume Home Block.
Command Qualifiers for ANSI and Unlabeled Tapes
/BLOCK_SIZE:n
Specifies the block size in characters for unlabeled magnetic
tapes at the time of the mount= Values for n can be from 18
through 16000. This qualifier also works on ANSI Level 1 or 2
magnetic tapes, that is, those without HDR2 records (labels).
/CARRIAGE_CONTROL:arg
FORTRAN
LIST
NONE
Specifies the record type for an unlabeled tape.
The arguments
correspond to the FORTRAN keywords for the OPEN statement. This
qualifier also works on ANSI Level 1 or 2 magnetic tapes, that
is, those without HDR2 records (labels). This qualifier also
works for ANSI Level 3 magnetic tapes that do not have a system
code (HDRl CP 61) beginning in DEC or OS •
. .\

/DENSITY:arg
800
1600
6250
Specifies the density at which data is to be written to the tape.
The default is the lowest density supported by the specified tape
unit.
If the specified tape unit does not support the density
given, the command is rejected.
/[NO]HDR3
Specifies whether an HDR3 label is to be written when creating
new files.
The /NOHDR3 qualifier is needed only in the situation
where it is ~nown that the target system cannot handle a taoe
with a HDR3 label.
This qualifier has no other effect or
application. The default is /HDR3.
5-34

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
/[NO]LABEL
Specifies whether the tape volume is ANSI or unlabeled. An ANSI
tape
is specified by the /LABEL qualifier.
This is the default.
An unlabeled tape is specified by the /NOLABEL qualifier.
/OVERRIDE:(arg[,s])
ACCESSIBILITY
EXPIRATION DATE
IDENTIFICATION
SET IDENTIFICATION
This is a privileged qualifier.
Specifies that you wish to override one or more characteristics
of a
tape volume that are normally checked when you mount a
magnetic tape. The parentheses are optional if you wish to
specity only one argument~
Tf you wish to specify more than one
argument, the arguments must be enclosed
in parentheses and
separated by commas.
The ACCESSIBILITY argument specifies that you
the protection on ANSI magnetic tapes.

wish

override

The EXPIRATION DATE argument specifies that you wish to
the expiration-date on ANSI magnetic tapes.

override

The IDENTIFICATION argument specifies that you wish to mount the
tape or tape set without specifying a File Set ID.
By default,
the File Set ID is the Volume ID of the first tape reel
in the
set.
See Section 5.6.1.
The SET IDENTIFICATION argument specifies that you wish to mount
a tape or tape set that does not follow ANSI standard.
This
argument is not otherwise needed.
/RECORD_SIZE:n
Specifies the record size in characters for unlabeled magnetic
tapes.
The value for
n can be from 1 through the value for
blocksize on the volume.
/TRANSLATE:arg
EBCDIC
NONE
UTl
UT2
UT3
Specifies the character translation to take place for
reading
from and writing to the mounted unlabeled tape volume.
NONE
specifies no translation and is the default.
EBCDIC specifies
translation from ASCII
to EBCDIC for writes and from EBCDIC to
ASCII for reads.
Note that the translation is not one-to-one
because some characters are found only in EBCDIC or only in
ASCII.
UTl, UT2, or UT3 specify user-supplied translation tables
that have been previously linked into the MTAACP.
See the
RSX-llM/M-PLUS I/O Operations Manual for further
information on
character translation.

5-35

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.}
/VOLUME_IDENTIFICATION: (volumeID[,volumeID[,s]])
Specifies Volume Identifiers.
If you wish to check Volume IDs,
you must specify this qualifier.
If the File Set ID is not the
same as the volume ID of the first tape in the set, you must use
this qualifier and
include all Volume IDs in the set.
See
Section 5.6.1 for more information and
for examples of this
qualifier in use.
Examples

>MOUNT
Dt;:~vicer~,

D~:.:1.:

Volume ID? HOTROD
This example mounts the volume labeled HOTROD on device DKl:.
If
you are doing nothing more than mounting a volume to read from it
or write to it, you will probably not need a more complicated
MOUNT command than this.
All default values for the mount come from the Volume Home Block.
This block is written when the volume is created by INITIALIZE or
by some other system task, such as a backup utility, that creates
a
file structure on the volume. Most of the qualifiers to MOUNT
are used to override values in the Volume Home Block.

Specifies that a three-volume ANSI magnetic tape set be mounted
on devices MMO:, MMl:, and MM2:.
The volume labels are W*MB*T,
FOOBAR, and FOO. The first label is included in quotes to allow
specification of the asterisk (*).
Note that the comma between
"W*MB*T" and FOOBAR is outside the quotation marks.

>MOUNT/PROCESSOR:MRXACP/FOREIGN/PARAMETERS;"MUMBLFRAZ"
Device? DRO!
Volume label? HARPO
This example mounts the volume labeled HARPO on device ORO:. The
volume's file structure is controlled by a non-DIGITAL ACP named
MRXACP, so the ACP must be named and the volume mounted foreign.
This ACP accepts special commands.
These are entered using the
/PARAMETERS qualifier with the command string in quotation marks.
>M 0 UN T / N 0 U·1 BEL .I BL.DC l< : 2 0 4 8 / F~ EC i) f.: D ~ 6 4 / Cf.i F: F< : F 0 RTF: AN/ T F'. ANS L ! EB CDT C i"-"i MJ. ~

The example mounts an unlabeled magnetic tape on device MMl:,
specifying a block size of 2048 characters and a record size of
64 characters. The volume includes FORTRAN carriage control, so
that
is specified.
The volume's records are written in EBCDIC
characters, so the user included the /TRANSLATE qualifier.
The
characters will be translated to ASCII
for handling by the
operating system and translated back to EBCDIC for writing to the
tape volume.

5-36

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
>MOUNT/WAIT DBl:

WHIZZER

The user wishes an operator to place the medium containing the
proper volume in place on DBl:.
The command may appear in a
batc.h· j.O}:), indirect command file, or interactive mount, perhaps
from a user on a remote terminal. The following message appears
on CO:, the operator's console:

co:

Please mount volume WHIZZER an DB1:

T':IPe
UNS <DCL START> when

read~

RES <DCL CONTINUE> to reJect reouest.
The operator performs the requested operation and the mount takes
place,
if the device was available and the operator typed START
(MCR UNS).
If the device was not available and the operator
typed CONTINUE
( MCR RES) , the mount fails. ·tI:ie :ba·tch :· p.r:Qee·ssqt
.~.ft:~mpts;· to continue the: 'job:.:
The same is true if the command
appeared in an indirect command file.

Notes
You should not confuse mounting with physically placing the disk
or other magnetic medium on a drive.
Naturally, you must place
the medium on a drive and spin it up (for a disk) or load it (for
a tape) before you can do anything else with it, but mounting is
enabling the system software to access the medium, either to read
or write data, or to establish a file structure for the volume.
I f you attempt to mount a volume on a device where
the disk
is
not properly spun up, MOUNT will wait 30 seconds and try the
mount again.
If the disk is not spun up after 30 seconds,
the
This feature has nothing to do with the /WAIT
mount fails.
qualifier.

There are four states of device ownership:
Private

The device has been made private through the
ALLOCATE command or the /NOSHAREABLE qualifier to
MOUNT.
Only you can access the volume.

Shareable

The device has been mounted /SHAREABLE.
can mount the volume.

Public

The device has been made public through the SET
DEVICE/PUBLIC command or the /PUBLIC (or /SYSTEM)
qualifier to MOUNT. Only a privileged user can
set a device public.

Unowned

No one has mounted a volume on the device, nor is
it allocated or set public.

See the discussion of public, private,
unowned,
devices and mounted volumes in Section 5.1.3.
You cannot put comments in a MOUNT command line.

5-37

and

Any user

shareable

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
DISMOUNT counteracts MOUNT.
DISMOUNT with examples.

See Section 5.7 for a description of

Some file attributes and positioning information for magnetic
tape volumes or tape sets can be supplied after mounting using
the MAG utility. For more information,
see the RSX-llM/M-PLUS
I/O Drivers Reference Manual.
See the introduction to this chapter for more information on how
the operating system deals with devices and volumes.
See also
the description of the INITIALIZE command in Section 5.8.

5.6.1

Mounting Magnetic Tapes and Tape Sets

Mounting
MTAACP.
standard
formats.

magnetic tape volumes is handled by a special ACP,
the
This ACP handles not only magnetic tapes that meet the ANSI
but also the most commonly encountered unlabeled tape

The MOUNT command can only mount a single random-addressable volume,
but magnetic tapes can be mounted by the set.
In fact, when you mount
a single magnetic tape, you are mounting a set consisting of only one
tape.
A magnetic tape set consists of logically related records
written on one or more individual reels of tape. Only the first
tape
in the set need be loaded on a device at the time the MOUNT command is
issued. However, all tapes in the set can be loaded on different
devices at the time the MOUNT command is issued.
Therefore,
the terminology used for mounting magnetic tapes is
somewhat different from that used in mounting disks.
The tape set is
identified by a File Set Identifier (File Set ID).
Each individual
tape in the file set is identified by a Volume Identifier (Volume ID).
By default, the File Set ID is the same as the Volume ID of the first
individual reel of tape in the set.
If you wish to use a File Set ID other than the Volume ID of the first
reel
in the set, you can do so on the first mount of a newly
initialized tape as shown in the examples.
Each installation using magnetic tapes extensively will have policies
on File Set IDs and Volume IDs.
See your system manager or supervisor
for information on how they are used in your installation.
The following examples establish the relationship between File Set IDs
and Volume IDs.
The following command

>MOUNT MMO:

FOO

mounts a tape set (consisting of a single physical reel)
whose File
Set ID is FOO and whose Volume ID is FOO.
The reel FOO must be loaded
on device MMO:
at the time of the mount.

5-38

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
The following command

>MOUNT MMO:

DRAG/VOLUME_IDENTIFICATION!CFOO,BAR~MORE)

mounts a tape set whose File Set ID is DRAG and that consists of three
physical reels with Volume IDs of FOO, BAR, and MORE.
The reel with
the Volume ID FOO must be loaded on device MMO:,
but the other two
reels are not loaded at the time of the mount.
The File Set ID of the
tape set was established with the first mount of the newly initialized
tape set, using this same command.
If this were the first mount, the
File Set ID DRAG would be established by the MOUNT command,
but the
actual change of the File Set ID (from the default of FOO) does not
take place until the first record is written to the tape.
The command

>MOUNT/OVERRIDE!SET_IDENTIFICATION MMO:

\FOO~ BM~ v MDf~F !

mounts a tape set whose File Set ID is immaterial and that consists of
three physical reels with Volume IDs of FOO, BAR, and MORE.
FOO must be loaded on device MMO:, but the other two reels
loaded at the time of the mount.

The reel
are not

The following command

>MOUNT MMO!

FOO /VOLUME-IDt<A312,A387rB231)

mounts a tape set whose File Set ID is FOO and that consists of three
physical reels with Volume IDs A312, A387, and B231.
The reel A312
must be loaded on device MMO:, but the other two reels are not loaded
at the time of the mount.
The following command

>MOUNT <MMO! ,MM1: ,MM2!) <FOO,I!AR,MDF:E)
mounts a tape set whose File Set ID is FOO and that consists of three
physical reels with Volume IDs FOO, BAR, and MORE.
At the time of the
mount, the reel FOO must be loaded on device MMO:, the reel BAR must
be loaded on device MMl:, and the reel MORE must be loaded on device
MM2:.
NOTE
There is no theoretical limit to the
number of physical tape reels in a set,
but your
DCL
MOUNT
command
must
translate to an MCR MOU command of 80
characters
or
fewer.
There
are,
therefore, mounts that are permitted by
the system but that cannot be translated
successfully from DCL to MCR within that
limit.
In those cases, jou cannot use
the DCL MOUNT command but must use the
MCR MOU command.
Remember, you can use
the MCR command to enter MCR commands
from a DCL terminal.

5-39

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
Error Messages
MOU -- ACP not in system
Explanation: The task specified as the ACP, or the default
is not installed in the system.
Oser Action:

ACP,

See your system manager.

MOU -- Device not in system -ddnn:
Explanation:
system.

The command specified a device not present

User Action: Retype command after checking
DEVICES) or see your system manager.

device

list

the
(SHOW

MOU -- Device specified twice
Explanation:

The command specified the same device twice.

User Action:

Retype command after checking proper syntax.

MOU -- Driver not loaded

MOU

Explanation:
loaded.

The command named a

device

User Action:

See your system manager.

whose

driver

not

attached

find

-- Failed to attach device -ddnn:
Explanation: The command named a device
another task and could not be mounted.

that

was

User Action: Check device list (SHOW DEVICES) and
See your system manager.
the device is in use.
MOU

out

-- Horne block I/O error
Explanation: An I/O error was detected in trying to read the
Volume Horne Block.
This message often indicates that the device
is not ready, or that the disk has not been initialized.
user Action:
try again.

Wait until the disk is spinning at full

speed

and

MOU -- Illegal keyword combination
Explanation:

The command specified conflicting qualifiers.

User Action:

Retype command after checking proper syntax.

MOU -- Index file I/O error
Explanation: MOUNT could no~ read either the index
or the storage allocation file.
User Action:

See your system manager.

5-40

file

header

HANDLING DEVICES AND VOLUMES

MOUNT (Cont)

MOU -- No such device available

Explanation:

The command named

device

not

present

the

system.

User Action:

Retype command after checking
DEVICES) or see your system manager.

device

list

(SHOW

MOU -- Not file-structured device

Explanation: The command named a device that is not supported as
a Files-11 device, including ANSI magnetic tape.
User Action:

Retype command after

checking

for

proper

device

name.
MOU -- Parameter conflicts with mounted volume

Explanation: An attempt was made to mount a previously mounted
volume using qualifiers that conflict with those specified when
the volume was originally mounted.
User Action:
other user.

Check with SHOW DEVICE and confirm qualifiers
See your system manager.

with

MOU -- Storage bit map file I/O error

Explanation:

An I/0 error
storage allocation file.

was

encountered

while

reading

the

User Action: Check to be sure you have the correct magnetic
medium,
or the volume has not been initialized.
See your system
manager.
MOU -- Task not ACP

Explanation:

The task named with the
have the characteristics of an ACP.

User Action:

/ACP

qualifier

does

not

Check to be sure you have named the right task.

MOU -- Undefined density selection

Explanation:

The command specified an illegal density value.

User Action:

Retype command after checking proper syntax.

MOU -- Unit allocated to or in use by another user

Explanation:

The command specified a device that is

already

use.

User Action:

Check on the status of the device with SHOW DEVICES
and take the appropriate action.

5-41

HANDLING DEVICES AND VOLUMES

DISMOUNT
MOU -- Unit does not support density switch
Explanation: The command included a /DENSITY qualifier but named
a device that does not accept it.
User action:

Retype command after checking proper syntax.

MOU -- Unit does not support 800 BPI
Explanation: The command specified
support the 800 BPI density.
User Action:

device

that

does

not

Retype command after checking proper syntax.

MOU -- Unit does not support 1600 BPI
Explanation: The command specified
support the 1600 BPI density.
User Action:

device

that

does

not

Retype command after checking proper syntax.

MOU -- Unsupported file header format
Explanation: The Volume Home Block does not conform to
format.
Volume may be corrupted.
User Action: Volume could be mounted
qualifier, or see your system manager.

with

the

Files-11
/FOREIGN

MOU -- Volume aiready mounted -ddnn:
Explanation: An attempt was made to mount a volume on a device
that already had a mounted volume.
In multiuser protection
systems, only random-access devices can be mounted by multiple
users.
User Action:

See your system manager.

MOU -- Wrong volume label
Explanation: The volume label on the label and the volume
in the command do not match.

label

User Action: Retype command after checking for proper volume
label.
Privileged users can use the /OVERRIDE:IDENTIFICATION
qualifier.

5.7

DISMOUNT

DISMOUNT marks the volume mounted on the specified device to be
logically off line and disconnected from the file system. Marking a
volume for dismount prevents programs from opening new files on the
volume.
After all open files on the volume have been closed, the ACP
dismounts the volume.

5-42

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont.)
Format
DISMOUNT[/qualifier[s]]
Device? ddnn: [volumelabel]
DISMOUNT[/qualifier[s]] ddnn:

[volumelabel]

Command Qualifiers
/ALL
/PUBLIC
;fSAVJ!l•,

/SYSTEM (synonym for /PUBLIC)
,,f~JE

M~;~,

'C :·ttnhi!
,:9~µl}t : '

Parameters
ddnn;
Specifies the device on which the volume is mounted.
volumelabel
Specifies the volume label or File Set ID for magnetic tape.
This parameter is optional, but if it is specified, the label or
File Set ID is checked against the mounted volume.
The volume
label or File Set ID can be a quoted string, following the same
rules as explained in the discussion of MOUNT, Section 5.6.1.
There is no prompt for this parameter.
Command Qualifiers
/ALL
Specifies that all volumes mounted from the terminal at which the
commmand is issued be dismounted. A message informs you of each
dismount as it takes place. No device name or volume label is
accepted with this qualifier. See the example.
/PUBLIC
/SYSTEM
Causes all users to be dismounted from a volume.
This is a
privileged qualifier.
A DISMOUNT/PUBLIC frees the device, no
matter who has mounted the volume on it. This is the only way to
dismount a public volume.
/SYSTEM is a synonym for /PUBLIC,
included for compatibility with VAX/VMS.

/J:JAV'I!.

, ;Thfs' '<iualif"fer 'fs for"' . .'Jis'x-liM-P.L'iJs~: .systems. ;on:ly;. . I t applies
DB:, OM:, and DU:

devices only.

Specifies' th~t 'the disk is to.remain ~pinnin,g ill the· 'ariv7 . ,~nd.
, ,:· ::dan 'be adcessed'' for "read or wr'i te by pri v·i1e9ed tasks~ This· ~is a
p~ivileged qua11 fier.

5-43

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont.)
The, mos't collimon<us~ «>f ./S~VE is ~hen s'aving or backing up the
sy.stem dis,k~ I f you·.,.$fmpiy wish. t.o leave t.t:ie disk .spinning, use
the' /NOUNLOAD ql.la+ifier .• ··Remember, these, .values can also be set
with the /DEE'.AUI,.'T qual'i ~ier te MOUNT. ·See S.eption S. 6.
/TERMINAL:Hnn,·:
This· gu'9U.per. is. for· RSX~·HM-;-PLUp, only.

Allows' a·. priv~le,g.ed . user
another· ter.minal.

dismo.unt · ·a· volume

mounted

from

/[NOJUNLOAD.
'The /UNLOAD and /NOUNLOAD qualifiers are for RSX-HM-PLUS systems
only.
They apply to DB:, DM:, and DU': disks and magnetic tapes
only.
The· /UNLOAD qualifier specifies that the disk is to spin down
after the dismount.
This is the default for Files-11 volumes.·
For magnetic tapes, this qualifier allows the tape to be
completely rewound.
You can spin down the removable unit of a multiunit device
(for
example, 'the RC25) only if you are a privileged user.
If you are
a nonpr i viileged user and you try to dismount the unit or spec i'fy
/UNLO!AI» lin the ~omma,nd l;ine, you will get a warning message: that
the· volµm~ cannot be spun: down.
I,

l ~ t
i; f

The /~OµNjLOAD quaht1er sp~pities that the cusK is to rema'in
spin:nli.n~i 1 afte r
the dism!ou,nt.
This is the default for fore·ign
mount~d! :v;olumes •. ,The v'N,O~~LOAD
qualifier is useful when . the
voluffib. l 'iis to be: immed'ia'te:ly remountea. For magnetic tapes,· this
qual{fi~X: rewinds tne tpp~ to t.he first file position.
'
s~e :~edt'i,Jon 5. 1r. 7 'fbr· tnPii~ 1h fo'rma t ion on /[NO] UNLOAD and the
rela~Jed •. >/SAV:E quali f.i~f.·.' . R~member, these :values can also be set
with tqie :/DE~AUl:..T q:Uali·f~et: to MOUNT.. See Section 5. 6.
1

Examples

>DISMOUNl
Device'?

DIS -- TT11!

DKO:
[ljsmownted from DK0:

*** cinal Dismount Initi2t2rj *~*

This example dismounts a volume on device DKO:.
No other user
had the volume mounted when the DISMOUNT command was issued.

>DISMOUNT DKlt
DIS -- TT56!

HOTROD
Disrnuwnt~d

f rorn

DKO:

This example dismounts a volume on device DKl:.
The user
specified the label HOTROD to be sure the correct volume was
mounted on the device.
The volume was mounted shareable and some
other user also has it mounted, so the informational message does
not include the notification of final dismount.

5-44

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont)
>LOGOUT
DM0 -- -- TT1 1 !

Di s mo u n t. e d i' ·r · r.i :;·1 DX(:. !
Have a Sood mornins
22-NOV-82 TT11:
Lo~sed uff

:t. :f. F. i r 1 ~:, t d :l ~;; mc 1J r: t

This example dismounts a volume as part of the LOGOUT procedure.
The user had the volume mounted on the device and had not
dismounted it before logging off. LOGOUT dismounted the volume.
If the device was allocated, LOGOUT also deallocated it.
This is
the equivalent of DISMOUNT/ALL.
The informational message is headed by OMO rather than DIS
because, at this point, DCL is no longer involved in the
dismount.

>DISMOUNT/ALL.
DIS
TT11
DIS
TTl 1

DIS

TT11

. **

D:i. ·5mouri Led from [It< 0 t
Dismo1..Jnted f ·,~(!Iii D~~ 1 +
D i s mo 1.1 n L i:! d f f'(Jll'i MM2!

***

Fi rid l
F in.:i J.

di~~.mou11L

d i s:.111 u u n t

This example dismounts all volumes mounted from the
which the DISMOUNT was issued. See next example.

***
***

terminal

>D I SM0 UN1 / f.1 L L.
DIS
TT11!
DIS -- TT11:
DI t; - ... TT 11 ~

Dismounted from DKO!
Dismounted fro~ DXl!
Di~.:. mCi u n t e d

from MM 2 :

CRUCIAL.

>MOUNT DX1!

***
Final disruount ***
** in al d :ism u •Jn t. ***

'i<

1=-

This example dismounts all volumes mounted from the terminal at
which the DISMOUNT was issued. The message reminds the user that
a volume was mounted on DXl:. As this volume was necessary to a
running task, the user immediately issued a new MOUNT command
using the volume label CRUCIAL. So long as the task did not
attempt to open a file and did not close its last file between
the time of the message and the time of the new MOUNT,
the
DISMOUNT has no effect on the task.
All files that the task had
open remain open.

>D I SM0 U~H f' UB LI C DB 3 '.;
DIS
DIS
DIS
DIS

TT21
TT271
TT31

TT55:

Di. smouritE:d from DB3!
Di c.;mount ;0d f r om DB3!
111 ·smuunted -r· ·,··om DB3i
Di':'.:I1ountt.'d from Li B 3 !

*** F=-irial dismount ***

In this example, a privileged user dismounted all users
mounted the volume on DB3:.

who

had

Notes
DISMOUNT counteracts MOUNT.
LOGOUT issues a
DISMOUNT/ALL
automatically.
DISMOUNT/ALL
dismounts all volumes mounted from the terminal, whether mounted
explicitly through a MOUNT command or implicitly through a task
that spawns a MOUNT command.

5-45

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont.)
You cannot include comments in a DISMOUNT command line.
The messages from the ACP to your terminal indicate only that the
volume is marked for dismount.
The actual completion of the
dismount is noted on the operator's console.
CAUTION
When the dismount operation is complete, the ACP prints
the following message on the operator's console (CO:):

*** ddnn Dismount complete
This message does not appear until all files open on the
volume are closed.
Do not remove the medium from the
drive until this message appears on CO:.
If you remove
the medium before the message appears, the present volume
may be corrupted and the next volume mounted on that
device will be corrupted.
Error Messages
DIS -- Warning

All units of multiunit drive will spin down <ddnn:>

Explanation: When a unit of a multiunit device is spun down
(by
a privileged user), all other units of the device are also spun
nown.
This warning message appears on RSX-llM-PLUS systems onlya
DIS -- Warning -- Volume will not spin down <ddnn:>
Explanation: An attempt was made by a nonprivileged user to spin
down the removable unit of a multiunit device, either implicitly
-with the DISMOUNT command or explicitly by specifying /UNLOAD in
the command line.
Only privileged users can spin down multiunit
devices.
(For nonprivileged users,
the volume is logically
dismounted but not spun down.) This warning message appears on
RSX-llM-PLUS systems only.
DIS -- Checkpoint file still active
Explanation: The command attempted to dismount a volume that
contained an active checkpoint file.
The volume cannot be
dismounted until the checkpoint file has been closed.
User
Action: Wait,
or,
if
privileged,
issue
a
SET
DEVICE:ddnn:/NOCHECKPOINT
and
reissue
the
DISMOUNT after
receiving the system message indicating that the checkpoint file
is no longer active.
DIS -- Volume not mounted
Explanation:
mounted.

The

command

User Action: Retype command
mounted devices.

specified
after

5-46

device

checking

that

SHOW

was

not

DEVICES

for

HANDLING DEVICES AND VOLUMES

INITIALIZE
DIS -- Volume not mounted by TI:
Explanation: The command attempted to dismount a volume
from another terminal.
User Action: Dismount the volume from the proper
have a privileged user dismount the volume.

mounted

terminal,

DIS -- Wrong volume label
Explanation:

The command included an incorrect volume label.

User Action:
Reissue the command without specifying a volume
label or check the volume label to be sure you are dismounting
the right volume.

5.8

INITIALIZE

INITIALIZE produces a volume in Files-11 format.
For disks and DECtapes, INITIALIZE destroys all existing files, writes
a dummy bootstrap and a Volume Home Block, and builds the directory
structure.
For magnetic tapes, INITIALIZE writes an ANSI standard
and a dummy file that destroys all existing files.

volume

label

Many of the values specified in the INITIALIZE command can be changed
with the INITIALIZE/UPDATE command without disturbing existing data on
the volume. See Section 5.8.1.
Format
INITIALIZE[/qualifier[s]]
Device? ddnn:
Label? volumelabel
INITIALIZE[/qualifier[s]] ddnn:
Command Qualifiers
/ACCESSED:n
/DENSITY:arg
800
1600
6250
/EXTENSION: n
/HEADERS:n
/INDEX:arg
BEGINNING
MIDDLE
END
n

5-47

volumelabel (volume-ID)

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
/MAXIMUM FILES:n
/OWNER: [g ,m]
/FILE PROTECTION: (code)
/PROTECTION:(code)
/[NO]SHOW
/BAD BLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
/WINDOWS:n

Parameters
ddnn:
Specifies the name of the device on which the magnetic medium
contain the volume has been placed·.

volumelabel
Specifies the label the volume is to be initialized with.
The
label names the volume and must be specified by nonprivileged
users when they mount the volume. The volume label is in effect
a password controlling access to the volume.
For magnetic tapes,
the situation is more complex. See Section 5.6.1.
For disks and
characters.

DECtapes,

volumelabel

can

many

For magnetic tapes, Volume ID can be as many as six characters.
See Section 5.6, the MOUNT command description,
for details on
the characters that can be included in volume labels and Volume
IDs.

Command Qualifiers
Selecting command qualifiers for
INITIALIZE requires a good
knowledge of the Files-11 file structure. You should see the
Reference
Manual
for
further
IAS/RSX-11 I/O
Operations
information.-Defaults to INITIALIZE enable you to initialize a volume in a
standard fashion, but the qualifiers allow much more flexibility
in using the system.
/ACCESSED:n
This qualifier specifies the number of directories that will be
accessed
simultaneously.
FllACP maintains a list of most
recently used directories.
If a directory is in this list, no
disk
I/O is required to find the directory in the Master File
Directory, nor do directory operations require that the directory
file header be read.
In general, directory operations can be
speeded up significantly by increasing the /ACCESSED count but at
the potential cost of pool.
The default n is 3.

Legal values for n range from 1 through 127.

5-48

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont}
/DENSITY:arg
800
1600
6250
HIGH
LOW
Specifies the density in bits per inch
(bpi)
for
the medium
loaded on ~ne device.
The argument can be 800, 1600, 6250, HIGH,
or LOW, depending on the device type. Only volumes on media for
certain devices can be initialized at different densities. You
must mount the volume at the same density with which it was
initialized.
This value can be altered on an existing
See Section 5.8.1.
INITIALIZE/UPDATE command.

volume

Here are the acceptable density values for DIGITAL
switchable density:

Mnemonic

Device

Densities

with

the

devices

with

MF:

(magnetic tape)

TU78

1600
6250 (default)

MM:

(magnetic tape)

TE16

800 (default)
1600

MM:

(magnetic tape}

TU16

800 (default)
1600

MM:

(magnetic tape)

TU45

800 (default)
1600

MM:

(magnetic tape)

TU77

800 (default)
1600

MS:

(magnetic tape)

TSll

1600

DY:

(floppy)

RX02

LOW (or single)
HIGH (or double) (default)

/EXTENSION: n
Specifies the number of blocks by which the file
is to be
extended when its allotted space is exhausted. Default n is 5.
This value can be altered on an existing
INITIALIZE/UPDATE command.
See Section 5.8.1.

volume

with

the

/HEADERS:n
Specifies the number of file headers to be allocated initially in
the index file.
The five system files INDEXF.SYS, BITMAP.SYS,
CORIMG.SYS, BADBLK.SYS, and 000000.DIR are not included in the
value for n.

5-49

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.}
The default value of n is proportional to the
medium;
the minimum allocation is 16 headers.
Mnemonic

Device

DD:
OF:
DK:
DK:
DK:
DL:
DL:
DP:
DP:
DP:
DP:
DR:
DR:
DR:
DS:
OT:
DU:
DU:
DU:
DU:
DU:
DU:
DU:
DX:
DY:
EM:

DECtape I I
RFll
RKOS
RK06
RK07

capacity

the

File Headers
Allocated Initially (n)
16
16
147
834
1654
314
629
1230
2460
5283
10478
4049
25593
51699
16
16
12308
7314
51699
3020
602
7461
16
16
16
Varies

RLOl
RL02
RP02
RP03
RP04/05
RP06
RM02/03
RM05
RP07
RS03/04
DECtape
RA60
RASO
RA81
RC25/RCF25
RD51
RM80
RXSO
RXOl
RX02
MLll

/MAXIMUM_FILES:n
Specifies the maximum number of files permitted on the volume.
The value of n includes the five system files.
The value of n
must be less than or equal to the maximum value of n given in the
table.
The following table also includes the default values of n
for each device.
Mnemonic

Device

Default n

Maximum n

DD:
OF:
DK:
DK:
DK:
DL:
DL:
DP:
DP:
DP:
DP:
DR:
DR:
DR:
DR:

DECtape I I
RFll
RK05
RK06
RK07
RLOl
RL02
RP02
RP03
RP04/05
RP06
RM02/03
RM02/03
RM05
RPO?

30
62
294
1668
3308
629
1259
2460
4920
10567
20956
8099
8099
30781
62007

247
499
2357
13344
25600
5034
10074
19680
25600
25600
25600
25600
64798
65500
65500

5-50

HANDLING DEVICES AND VOLUMES

INITIALIZE {Cont.)
RS03
RS04
DECtape
RAGO
RASO
RA81
RC25/RCF25
RD51
RM80
RX50
RXOl
RX02
MLll

DS:
OS:
OT:
DU:
DU:
DU:
DU:
DU:
DU:
OU:
DX:
DY:
EM:

62
125
34
24617
14629
54815
6040
1204
14923
48
29
60
varies

499
1003
278
65500
65500
65500
48326
9633
65500
388
238
481
varies

This value can be altered on an existing
INITIALIZE/UPDATE commandw
See Section 5.8.1.

volume

with

the

/INDEX:arg
BEGINNING
MIDDLE
END
n

Specifies the location of the index file on the volume.
This
qualifier forces a specified location for the index file, the
Master File Directory, and the storage allocation file.
This is
usually done to minimize access time.
Four possibilities are available for the argument field:
BEGINNING

The beginning of the volume.
for tapes and DECtapes.

MIDDLE

The middle of the volume.
most disks.

END

The end of the volume.

Logical block n.

This is the

default

This is the default for

/FILE_PROTECTION:(code)
Specifies the default protection for all files on the volume
being initialized.
See Section 4.1.5 for more information on
file protection codes.
Default protection code:
(SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R)
This value can be altered on an existing
INITIALIZE/UPDATE command. See Section 5.8.1.

volume

with

the

/OWNER: [g ,m]
The /OWNER qualifier specifies the owner of the volume.
Group
and member numbers range from 1 through 377. The default owner
is [1,1]. The /OWNER value is used for checking volume and file
protection. See Section 4.1.5 for more information on volume and
file protection.

5-51

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
/PROTECTION: (code)
The /PROTECTION qualifier specifies the default protection for
new files created on the volume.
See the discussion of volume
protection in Section 4.1.5.
The code for volume protection is
similar to that for
file protection, except that the "E" for
EXTEND protection is replaced by a "C" for CREATE protection.
/[NO]SHOW
The /SHOW qualifier specifies th~t yo~ ~i~h ~o see all the values
with which the volume
is being in1t1al1zed. /NOSHOW is the
default.
These values are identified in
equivalents:

MCR

terms.

Here

Display

DCL Equivalent

Label
/Bad
/Cha
/Ext.
/FPro.
/Indx.
/Inf.
/Lru.
/Mxf.
/Pro,
/Uic.
/Win

Label
/BAD BLOCKS
Not used by RSX-llM/M-PLUS
/EXTENSION
/FILE PROTECTION
/INDEX
/HEADERS
/ACCESSED
/MAXIMUM FILES

are

the

DCL

/PROTP.C:TTON

/OWNER
/WINDOWS

/BAD_BLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
/BAD_BLOCKS:AUTOMATIC specifies that bad-block information for
the volume is to be determined automatically from a file named
BADBLK.SYS created by the BAD utility.
This is the default.
/BAD BLOCKS:MANUAL specifies that bad-block information
volume is to be entered manually.

for

the

/BAD BLOCKS:OVERRIDE specifies that bad-block information
be ignored.
See Chapter 6 of the RSX-llM/M-PLUS
information on BAD.

Utilities

Manual

for

/WINDOWS :n
Specifies the number of mapping pointers to be allocated for file
windows.
A file window consists of a number of mapping pointers
stored in memory when the file is opened. Default n is 7.
This value can be altered on an existing
INITIALIZE/UPDATE command. See Section 5.8.1.

5-52

volume

with

the

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
Examples

>INIIALIZE
Device'? DKO:
Volume ID? HONOLULU
This example initializes a volume with the volume label
on device DKO:. See next example.

HONOLULU

>ALLOCATE DKO:
>MOUNT/FOREIGN DKO:
>INITIALIZE DKO! HONOLULU
>DISMOUNT DKO!
>MOUNT DKO: HONOLULU
This example illustrates the process necessary to turn a fresh
disk into a volume in Files-11 format that you can use.
(This
example assumes bad block information from BAD has already been
written on the medium.)
See Section 5.1.4 for a more detailed
treatment of this process.
First the device is allocated, or made private, so that no other
user
can
access
the
device during this process.
Then
MOUNT/FOREIGN provides access to the disk although it is not yet
in Files-11 format.
The volume is initialized and given the name
HONOLULU.
The volume is then dismounted. Finally, the volume is
mounted conventionally using the volume label HONOLULU.
The
/FOREIGN qualifier is not required on RSX-llM.

>I N I T I I NDE X : E NDI F' F' 0 T EGT I (Ji·~ + ( S YS T E M: RWEli ' 0 lJ ME F: ! ~ Gf:: 0 lJ F' ~
->WORLD:> DK1:

7 •·•

MIRACLE

This example initializes a volume named MIRACLE on a medium
The index file is placed at the end of
mounted on device DKl:.
Files on the volume are accessible to the system and
the volume.
privileged users only.
The user used the continuation character
(-) to make room for the command on a narrow terminal.

Notes
Nonprivileged users must allocate the device on which the
is to be initialized.
On RSX-llM

initiali.zed,
recommended.

volume

syste,ms, the medium need not be mounted to
mounting with the /FOREIGN qualifier
but

be
is

On RSX-HM-PLUS, ;YOU must use MOUNT/FOR:EIQN before INITIALIZE.
See Section 5.6 for a discussion of MOUNT/FOREIGN as
differently to RSX-llM and RSX-llM-PLUS.

5-53

applies

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
Error Messages
INI -- Allocation for syst file exceeds volume limit
Explanation: The system was unable to allocate a system file
from the specified block because of intermediate bad blocks or
end of volume.
User Action: Enter
/INDEX: qualifier.

command

with

different

argument

for

the

INI -- Bad block file corrupt - data ignored
Explanation: Although the /BAD BLOCKS qualifier was selected, or
defaulted to, the bad block- data on the disk was not in the
correct format and was therefore ignored.
User Action: Process
initialize again.

the

medium

with

the

BAD

utility

and

INI -- Block(s) exceed volume limit
Explanation: The specified block or blocks exceeded the physical
size of the volume.
User Action:
values.

Retype command after checking for proper

qualifier

INI -- Boot block write error
Explanation:
boot block.

An error was detected in

User Action: Reenter the command.
see your system manager.

writing

out

the

volume

If it still

does

not

work,

INI -- Checkpoint file header I/O error
Explanation:
file header.

An error was detected in writing out the checkpoint

User Action: Reenter the command.
see your system manager.

If it still

does

not

work,

INI -- Command I/O error
Explanation:
INITIALIZE encountered an I/O error
the command line.
User Action: Retype command
system manager.

line.

while

this

fails,

bad

block

reading
see

your

number

INI -- Data error
Explanation: The command specified
contiguous region that was too large.
User Action:

Retype command after checking proper syntax.

5-54

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont9)
INI -- Device allocated to other user - ddnn:
Explanation: Command specified a private device not allocated to
your terminal.
User Action: Retype command
proper device name.

after

checking

SHOW

DEVICES

for

INI -- Device not in system
Explanation:
system.

Command specified

User Action: Retype command
proper device name.

device

after

not

checking

in
SHOW

the

current

DEVICES

for

INI -- Device not ready -ddnn:
Explanation:

The device was not up to speed (spun up).

User Action:

Wait and try again.

INI -- Driver not loaded
Explanation:
not loaded.

Command specified a device for which the driver

User Action: Retype command
proper device name.

after

checking

SHOW

DEVICES

is
for

INI -- Failed to attach device -ddnn:
Explanation:

INITIALIZE failed to attach the specified device.

User Action: Wait and try again.
system manager.

Check SHOW DEVICES.

See

your

Explanation: Command attempted to initialize a magnetic
volume without specifying the required volume label.

tape

INI -- Magtape label must be specified

User Action: Retype command after checking proper
syntax.
Magnetic tape volume labels are limited to six characters.
INI -- Magtape write error -ddnn:
Explanation: While writing to
encountered an I/O error.
User Action:

the

magnetic

tape,

the

system

Retype command.

INI -- No bad block data found
Explanation: Although the /BAD BLOCKS:AUTOMATIC qualifier
specified, or defaulted to, no bad-block data was found.

was

User Action:
again.

try

Process the medium

5-55

through

BAD

utility

and

HANDLING DEVICES AND VOLUMES

INITIALIZE {Cont.)
INI -- Not file structured
Explanation:
The system does not support the device named
Files-11 device.

User Action:
Nonprivileged users can only initialize volumes
private devices.

User Action:

Retype command after checking proper syntax.

INI -- Public device -ddnn:
Explanation: Command attempted
public device.

initialize

volume

INI -- Undefined density selection
Explanation: Command specified an illegal density
the device named.
User Action:
argument.

Retype command after checking

for

argument
proper

for

density

INI -- Unit is not at high density
Explanation: Command specified that floppy disk in RX02
(DYnn:)
drive be initialized at low density, but floppy was formatted at
high density.
User Action:

Reformat floppy, or change it.

INI -- Unit is not at low density
(DYnn:)
Explanation: Command specified that floppy disk in RX02
drive be
initialized at high density,
but the floppy was
formatted at low density.
User Action:

Reformat floppy, or change it.

INI -- Volume mounted Files-11
Explanation:
Files-11.

Command attempted to initialize

volume

mounted

User Action:

Check to make sure you have the right volume.

INI -- Volume mounted foreign with ACP
Explanation: Command attempted to initialize
/FOREIGN but with the /ACP qualifier.
User Action:

volume

mounted

Remount the volume without the /ACP qualifier.

INI -- Volume name too long -- volumelabel
Explanation:

Command included a volume label that was too long.

User Action:
Retype command but limit volume label for disks
DECtapes to 12 characters; magnetic tapes to six characters.

5-56

HANDLING DEVICES AND VOLUMES

INITIALIZE/UPDATE
5.8.l

INITIALIZE/UPDATE

INITIALIZE creates a Volume Home Block that
includes a number of
values used by the ACP when you mount the volume.
INITIALIZE/UPDATE
uses the HOME utility to alter some of those values without affecting
the other data on the volume.
The INITIALIZE/UPDATE command is only
for disk and DECtape volumes in Files-11 format.
Format
/INITIALIZE/UPDATE[/qualifier[s]] ddnn:

volumelabel

Command Qualifiers
/ACCESSED:n
/DENSITY:arg
800
1600
6250
/EXTENSION :n
/FILE PROTECTION:code
/OWNER: [g,m]
/MAXIMUM FILES:n
/PROTECTION:code
/[NO]SHOW
/LABEL:newvolumelabel
/WINDOWS:n

Command Qualifiers
/ACCESSED:n
Specifies the approximate number of directories that will be
accessed simultaneously during the mount.
Legal values for n
range from 1 through 127.
FllACP maintains a
list of most
recently used directories.
The value specified for /ACCESSED
sets the number of entries in this list.
In general, directory operations can be significantly speeded up
by increasing this value.
If a directory appears in the list,.no
disk I/O is required to find the directory in the MFD.
In
addition, directory operations take place without the necessity
of reading the directory file header.
Note that increasing the
/ACCESSED value increases the amount of system pool used.
/DENSITY:arg
800
1600
6250
Alters the /DENSITY value established when the volume was
initialized. See the description of the /DENSITY qualifier under
INITIALIZE (Section 5.8) for more information.
/EXTENSION: n
Specifies the number of blocks by which a file will be extended
if it has exhausted
its space allocation.
n can be from 1
through 127. The default is set by your system manager.

5-57

HANDLING DEVICES AND VOLUMES

INITIALIZE/UPDATE (Cont.)
/FILE_PROTECTION:code
Specifies the protection for new files created on the volume.
See Section 4.1.5 for more information on file protection.
/OWNER: [ g ,m]
Specifies the owner of the volume.
information.

See Section

5.1.4

for

/MAXIMUM_FILES:n
Specifies the maximum number of files permitted on the volume.
This value must be greater than the maximum value on the current
volume.
See the discussion of /MAXIMUM FILES under MOUNT for
more
detailed information on the maximum number of files
permitted on various media.
/PROTECTION:code
Specifies the volume protection for the volume.
4.1.5 for more information on volume protection.

See

Section

/[NO]SHOW
Specifies that the information about the volume whose home block
is being updated is to be displayed on your terminal.
/NOSHOW is
the default.
Here is the display format for disks and other random-addressable
devices:
Volume Information
Class:
Files-11 or Foreign
Device:
ddnn:
Volume label:
label
Pack Serial:
serial number supplied by manufacturer
Owner:
[g,m]
Protection:
code
Default:
code
Processor:
acpname
The owner field indicates the owner of the volume. The UIC must
be matched for protection checks for owner privileges.
The owner
UIC can be changed with the /OWNER qualifier. See Sections 5.1.3
and
4.1.5 for more
information.
Protection indicates volume
protection; Default indicates file protection.
/LABEL:new volumelabel
Permits you to change the volume label. Volume labels can be as
many as 12 characters.
See the discussion of volume labels under
MOUNT (Section 5.6) for more information about volume labels and
which characters can be included.
/WINDOW:n
Specifies the default number of mapping pointers to be allocated
for
file windows when the file
is accessed.
A file window
consists of a number of mapping pointers stored in memory when
the file is opened.
Legal values for n range from 1 through 127.
5-58

HANDLING DEVICES AND VOLUMES

INITIALIZE/UPDATE (Cont.)
Notes
INITIALIZE/UPDATE
invokes
the
HOME
RSX-llM/M-PLUS MCR Operations Manual.

utility.

See

the

You should not use INITIALIZE/UPDATE without a good understanding
of the Files-11 disk volume structure and a clear idea of the use
the system makes of the values in the volume home block.
For
more information, see the !AS/RSX I/O Operations Reference
Manual.
Error Messages
INITIALIZE/UPDATE shares many error messages with INITIALIZE.
<bell>***ATTENTION***<bell>
This volume is operating with a replacement home block.
Please take the action outlined in the dopumentation.
Explanation:
The HOME utility could not ensure that a good home
block will be written on the volume,
so it has placed an
alternate home block on the first free block on the MOUNT search
path.
The new home block is not allocated to or mapped by any
file.
User Action: Copy the volume using BACKUP (BRU)
or DSC before
initiating any further
operations.
Otherwise, the replacement
home block could be destroyed, making the data on the volume
unrecoverable.
IN! -- Failed to find home block
Explanation:

HOME could not locate the home block of the volume.

User Action:
Reenter the command, including /SHOW to determine
whether
it is a foreign volume or not.
See your system manager
for further help.
IN! -- Failed to place alternate home block
Explanation: When HOME cannot ensure that a good home block will
be written back to the volume, it attempts to place an alternate
home block on the first free block of the MOUNT search path.
This message indicates the attempt failed.
User Action:
The message may indicate a hardware problem, most
commonly that the device is write-locked.
See your system
manager.
!NI -- MXF less than or equal to the existing value
Explanation:
The value specified in the /MAXIMUM FILES qualifier
was less than or equal to the value already specified for the
volume.
User Action: Reenter the command
value larger than the current one.

5-59

specifying

/MAXIMUM_FILES

HANDLING DEVICES AND VOLUMES

BACKUP
5.9

BACKUP

BACKUP backs up and restores Files-11 volumes.
It transfers files
from a volume to a backup volume and retrieves files from the backup
volume.
The data is directed to a volume
(or volumes} during a backup
operation.
More than one backup set can be contained on a tape or
disk, or a backup set can extend over several tapes or disks.
Format
BACKUP[/qualifiers]
From? sourceddnn: [filespec[s]]
To? destinationddnn:
BACKUP[/qualifiers] sourceddnn: [filespec[s]] destinationddnn:
Command Qualifiers
Group 1:

Selective Backup and Restore

/CREATED:BEFORE:(dd-mmm-yy nn:mm)
AFTER: (dd-mmm-yy nn:mm)
/EXCLUDE
/IMAGE:arg
SAVE
RESTORE
/NEW VERSION
/MODIFIED:BEFORE: (dd-mmm-yy nn:mm)
AFTER:(dd-mmm-yy nn:mm)
/[NO]REPLACE
Group 2:

Initialization

/INITIALIZE
/BAD BLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
/ACCESSED:n
/EXTENSION:n
/HEADERS:n
/MAXIMUM FILES:n
/INDEX:arg
BEGINNING
MIDDLE
END
n

/FILE PROTECTION:code
/WINDOWS:n
/SAVE_SET:name

5-60

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
Group 3:

Tape Control

/APPEND
/DENSITY:arg
800
1600
6250

/ERROR LIMIT:n
/LENGTH:n
/REWIND
/LABEL:TAPE:fileset-ID
Group 4:

Verification

/COMPARE
/VERIFY
Group 5:

Display

/[NO]LOG
/LIST
Group 6:

Disk Processing

/DIRECTORY
/LABEL:INPUT:volumelabel
/NO IN IT IALI ZE
/MOUNTED
/[NO]PRESERVE
/LABEL:OUTPUT:volurnelabel
Parameters
sourceddnn:
Specifies the name of the device on which the input
containing the data to be transferred has been placed.

volume

For tapes and disks, if you are using the /IMAGE qualifier, you
may specify in the following format, more than one input device
for tapes and disks:
>BACKUP MMO:,

MM1:,

MM2:

DU1:,

DU2:

or
>BACKUP Duo:,

You can specify as many as eight drives on each command, but
can specify a particular tape or disk drive only once.

you

destinationddnn:
Specifies the name of the device on which the output
which data is being transferred has been placed.

volume

For tapes and disks (if you are using the /IMAGE qualifier), you
can specify more than one output device separated by commas, as
described above.

5-61

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
filespec
Indicates the file specification used to select particular
or categories of files to be backed up or restored.

files

A filespec takes the form:
[g,m]filename.typ;version
You can specify as many as 16 filespecs per command.
Files can be backed up or restored selectively by UFD, file name,
file
type, or version number. Note, however, that BACKUP does
not accept 0 or -1 as version numbers.
When you enter a command without a file specification,
all
files on the input volume are copied to the output volume.
Any filespec
If you do
assumed;
if
all versions

the

field that is not specified is taken as a wildcard.
not specify version number,
all versions will be
you specify only type, all files of all names and
of that type will be assumed;
and so forth.

Command Qualifiers
Unless otherwise noted, the defaults for these qualifiers are the
same as the equivalent attributes of the input volume.
R~r.KTJP

prnvic1P.s six grnnps of command qm=ilifiP-rs:

•

Selective Backup and Restore

•

Disk Initialization

•

Tape and Disk Control

•

verification

•

Display

•

Disk Processing

Group 1:

Selective Backup and Restore

/CREATED:BEFORE:arg
AFTER:arg
Specifies selection of files created before or after the date and
time given by arg.
The required date/time argument can be in several formats.
You
must specify either a date or a time or both.
If you do not
specify a date, the default is today.
If you do not specify a
time, the default is now.
Here are some examples:
/BEFORE:31-JUL-82
/AFTER:l4:00
/BEFORE: (l-APR-82 12:00)
/AFTER: (l-APR-82 12:00)
/BEFORE:4/l/82
/AFTER: (4/1/82 12: 30}

5-62

HANDLING DEVICES AND VOLUMES

BACKUP {Cont.)
Note that if you wish to enter both a date and a time,
you must
use the parentheses.
These formats are used wherever you specify
a date or a time or both in a BACKUP command.
/EXCLUDE
Specifies that all files specified with the source device are to
be excluded from the backup or restore operation, instead of
included in it. For example, the command

>BACKUP/EXCLUDE DBO:C306,6J*·* MMO:
transfers all files except those in the UFD [306,6].
/IMAGE:arg
SAVE
RESTORE
Specifies that you want to do a multiple disk-to-disk
restore operation.

backup

If you want to do a backup operation, you must use /IMAGE:SAVE
when you create the backup file that represents the image copy of
the input disk or disks.
For example,
this qualifier must be
used when you copy a large disk to several small disks, or if you
copy several small disks to a mounted large disk.
If you are doing a restore operation, you must use /IMAGE:RESTORE
if you are restoring from a backup file that represents the image
copy of the original disk.
/NEW_VERSION
Specifies that a new version of the file be created in the event
of conflicts that occur during restore operations and during
backups to a mounted disk when using the /IMAGE:SAVE qualifier.
Compare with /REPLACE.
/MODIFIED:BEFORE:arg
AFTER:arg
Specifies selection of files modified
specified date or time, or both.

before

after

the

The required date/time argument can be in several formats.
You
must specify either a date or a time or both.
If you do not
specify a date, the default is today.
If you do not specify a
time, the default is now.
Here are some examples:
/BEFORE:31-JUL-82
/AFTER:l4:00
/BEFORE; (l-APR-82 12:00)
/AFTER: (l-APR-82 12:00)
/BEFORE:4/l/82
/AFTER: (4/1/82 12:30)
Note that if you wish to enter both a date and a time,
you must
use the parentheses.
These formats are used wherever you specify
a date or a time or both in a BACKUP command.

5-63

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.}
/[NO]REPLACE
Specifies whether or not files from the input volume should
replace files having identical file specifications on the output
volume.
A conflict occurs when a file on the input volume and a file on
the output volume have identical file specifications.
The
default qualifier /NOREPLACE resolves that conflict by keeping
the file on the output volume rather than replacing it with that
on the input volume. A message informs you that the file has not
been superseded. /REPLACE resolves the conflict by deleting the
file on the output volume and replacing it with the file being
restored from the input volume.
Group 2:

Initialization

/INITIALIZE
/INITIALIZE specifies that you wish to initialize the output disk
before proceeding with the data transfer.
You must specify this
qualifier if you wish to use any of the other initialization
qualifiers discussed here.
If you do not specify this qualifier,
but specify other initialization qualifiers, you will be asked by
a prompt whether you wish to initialize before proceeding or not.
The default is /NOINITIALIZE. See the discussion in Group 6.
See Section
qualifiers ..

5.8

for

description

INITIALIZE

and

its

/BAD_BLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
Enters the locations of bad blocks
See Chapter 6 of the
initialized.
Manual for more information on BAD,
Utility.

on the
volume
being
RSX-llM/M-PLUS Utilities
the Bad Block Locator

/BAD_BLOCKS:AUTOMATIC
Specifies that bad-block information for the volume be determined
automatically from the file BADBLK.SYS, created by the BAD
utility. This is the default.
/BAD:AUTOMATIC is the default.
/BAD_BLOCKS:MANUAL
Specifies that bad-block information for
entered manually.

the

volume

/BAD_BLOCKS:OVERRIDE
This qualifier applies only to last-track devices.
It makes the
disk appear not to have bad-block information written in the last
track, even if this information is actually present.

5-64

HANDLING DEVICES AND VOLUMES

BACKUP {Cont.)
/ACCESSED:n
Specifies the default number of File Control Blocks per volume to
be kept
in memory by the ACP.
See the description of the
/ACCESSED qualifer to MOUNT (Section 5.6) for more information.
/EXTENSION: n
Specifies the number of blocks by which the file will be extended
when its allotted space is exhausted.
/HEADERS:n
Specifies the number of file headers to be allocated initially in
the index file.
The five system files
(INDEXF.SYS, BITMAP.SYS,
CORIMG.SYS,
BADBLK.SYS, and 000000.DIR) are not included in the value for n.
The default value for n is proportional to the capacity of the
magnetic medium. See the description of /HEADERS in Section 5.8
for information on the different magnetic media.
/MAXIMUM_FILES:n
Specifies the maximum number of files permitted on the volume.
The value of n includes the five system files.
The value of n
must be less than or equal to the maximum value of n given in the
description of /MAXIMUM FILES in Section 5.6.
The description
also includes the default value of n for each device.
/INDEX:arg
BEGINNING
MIDDLE
END
n

The beginning of the volume.
for tapes and DECtapes.

MIDDLE

The middle of the volume.
disks.

END

The end of the volume.

Logical block n.

default

This is the default for

The default position is the position of the
volume.

5-65

This is the

file

the

input

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
/FILE_PROTECTION: (code)
Specifies the default protection for all
files created on the
volume being initialized.
See Section 4.1.5 for more information
on file protection.
Default system protection code:
(SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD:R)
The default protection code is the protection code of
volume.

the

input

/WINDOWS:n
Specifies the number of mapping pointers to be allocated for file
windows.
A file window consists of a number of mapping pointers
stored in memory when the file is opened.
The default is the
volume.

number

mapping

pointers

See the discussion of the /WINDOWS qualifier in Section
more information.

the
5.6

input
for

/SAVE_SET:name
Specifies the name of the backup set to be placed on tape or
disk~
For tapes and unmounted disks, the default name is the
volume name for the disk being backed up.
This name can be up to
12 characters long.
For an image backup or restore operation to
a mounted input or output disk, you can specify the full backup
set file name with /SAVE SET.
If you do not specify a file name,
the default name is [O,OJBACKUP.SYS.
When you use /SAVE SET with an output volume, the backup set name
becomes the name- of the backup set being placed on the output
volume.
You can place multiple backup sets on a single volume.
When you apply /SAVE SET to an input tape volume, BACKUP searches
the first tape for the specified backup set name.
If you do not
specify a backup set name with the input volume, when you do a
restore operation BACKUP restores the first backup set it finds
on the tape. You can restore several sequential backup sets from
the same device without rewinding the tape between operations.
BACKUP does not rewind the first device in a backup set unless
you specify the /REWIND qualifier.
When you apply /SAVE SET to an input disk volume, BACKUP searches
the entire disk for each backup set you specify. Each backup set
is then restored in the order in which you provided the backup
set names of the backup set names you provided.

5-66

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
Group 3:

Tape and Disk Control

/APPEND
Appends new data to a tape or disk that already contains one or
more backup sets.
If the tape is not positioned at the
beginning, /APPEND causes output to be written where the tape is
currently positioned.
If you want to start writing at logical
end-of-tape, you must specify /APPEND/REWIND, which rewinds the
tape and then spaces forward to the end of the volume.
If the output device is a disk, and you are using the /IMAGE
qualifier, /APPEND causes BACKUP to check the container file
header for the logical end-of-file on the output disk.
BACKUP
then starts writing at the logical end-of-file.
You cannot use the /APPEND qualifier during a backup operation to
a mounted disk=
/DENSITY:arg
800
1600
6250
Specifies the density in bits per inch
(bpi)
for the medium
loaded on the device.
See Section 5.6 for a list of acceptable
densities for DIGITAL devices.
The default is 800 bpi.
/ERROR_LIMIT:n
Specifies the number of nonfatal I/O errors that BRU tolerates on
tape reads before terminating execution.
The default value for n is 25.
/LENGTH:n
Specifies the length of the output tape in decimal feet.
You may
want to use this qualifier when you know that the last part of a
tape is defective and must riot be usede
You can specify a
shorter length and ensure that you do not write on that part of
the tape.
The default length is the physical length of the output tape.
/REWIND
Rewinds the first tape of a tape set before executing the command
line.
See /APPEND for further information on /REWIND.
/LABEL:TAPE:fileset-ID
Specifies a 6-character ANSI fileset-ID.
On output operations
this ID is written on the tape.
On input operations the ID is
compared with the ID already on the input tape to ensure that you
have mounted the correct tape.

5-67

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
Group 4:

Verification

The following qualifiers allow you to verify the accuracy of data
transfers.
/COMPARE
Compares the data on the output volume to the data on the input
volume and reports any differences. /COMPARE does not copy any
data. See /VERIFY.
You must compare equivalent volumes.
You can assure that the
volumes are equivalent by including the /COMPARE qualifier in a
command that is otherwise identical to the BACKUP command that
was entered when the output volume was created.
The restriction does
/COMPARE qualifiers.

not

apply

the

/[NO]INITIALIZE

and

/VERIFY
Copies data from the input volume to the output volume,
performs a compare operation, and reports any differences.
Group 5:

then

Display

The following
transferred.

qualifiers

display

information

about

the

data

Displays at your terminal the UFD and file name of
being backed up or restored. /NOLOG is the default.

each

file

/[NO]LOG

/LIST
Displays at your terminal
specified tape or disk
directory is on the first
set, the directory is
example.
Group 6:

the backup set names or files on the
volume.
In a multivolume tape set, the
tape of a set.
In a multivolume disk
on the first disk of the set. See the

Disk Processing

The following qualifiers allow you to control the
operating system manages disk data transfer operations.

way

the

/DIRECTORY
Directs BACKUP to create UFOs (if they do not already exist) on a
mounted output volume, then copy into the UFOs the files from the
same UFD on the input volume.
If you do not specify /DIRECTORY,
BACKUP does not copy the file.
/DIRECTORY is used only with the
/NOINITIALIZE qualifier.
/LABEL:INPUT:volumelabel
Specifies the volume label of the input disk.
This is not a
required parameter;
if you specify it, ~owever, BACKUP checks
the volume label.

5-68

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
/NOINITIALIZE
Specifies that you do not want to initialize the output disk,
as
it already contains a
Files-11 structure and is mounted as a
Files-11 volume.
/MOUNTED
Allows you to back up files
from a disk
that is mounted
Files-11.
Transfers are faster from an unmounted volume.

/[NO]PRESERVE
/NOPRESERVE specifies that you do not want BACKUP to preserve
file
identifiers during a disk-to-disk transfer.
The default is
/PRESERVE.
/LABEL:OUTPUT:volumelabel
Specifies a volume label for the output disk.
The default label is the label of the input volumea

Examples

>BACKUP/LABEL:INPUT:RANDOM/SAVE_SET:19JUL82
F T'OITI'?

To!

DKO:

MMO!

BAC - Startins taPe 1 on MMO!
BAC - End of taPe 1 on MMO:
Bt-iC --

Comr:-l•~ted

This example transfers all files on the RKOS disk labeled RANDOM
to the tape mounted on MMO:.
The backup set name 19JUL82
identifies the data written on the output tape.

>BACK UF' / F: ElJ I ND / Et:i 1,1 E_ '.:l ET ~ 18 JUL. 8 :.;-" / NCl I N:i: T I AL : : £: E MM 0 !

fl i·i C '

This example rewinds the tape on drive MMO:,
then locates the
backup set with the name 18JUL82 {there may be more than one
backup set on a tape) and transfers all files in the backup set
to DMO:
which is mounted and has a Files-11 structure.
The
/NOINITIALIZE qualifier instructs BACKUP not to initialize DMO:.

>BACKUP/LIST MMO:
iJ 0 L1

IJOLl
IJOLl

1 8 J UL P .2
BACIWF'2

I N F' U Tl

19JUL82

PANltOM

Itff·L;:·:

1B - -.I Ul. -- i:l ;~
1 :;:· - Jl.ll..-·P:.:1
l'-7 ·,11..!L--:~:~.'

This example shows a directory of a tape volume.
It displays the
tape volume number, VOLl, the names of three volumes, and three
backup sets contained on the tape.

5-69

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
BACKUP can also be used to display the names of the files
in a
given backup set by specifying the backup set name along with the
/LIST qualifier, as in the following example:
>BACKUF'/SA 1..,1 E __ SET: 1 1.i._IULB:'./L IST MMO;

VOL1 19JUL82

RANDOM

19-JUL-82

23:37:11

[303113)

27DECE+LST;1
t-iSTCRSH. MAC; 2
AF'NDXC. TXT; 1
X.MAC;:L
X.OBJ;1
X. TSK; :I.

X.MAP;1
[30616J

2'7DECE. CiJA; l.
RSX11M. ~3"fB H
BAC -

ComFlet~d

on MMO!

Notes
The BACKUP command invokes BRU, the Backup and Restore Utility.
For more information on BRU, see Chapter 7 of the RSX-llM/M-PLUS
Utilities Manual.
You must specify either /INITIALIZE or /NOINITIALIZE.
If you
soecifv neither; BACKUP will ask if you wish to initialize the
output-device.
BACKUP is not a privileged command, but you should not use it
you are not familiar with BRU.

Error Messages
For many nonfatal errors, BACKUP continues with the
but prints a warning message such as the following:

operation,

BAC

*WARNING* APPENDING AT 800 BPI

BAC

*WARNING* BOOT BLOCK IS BAD

BAC

*WARNING* CANNOT RESTORE CONTIGUOUSLY

BAC

*WARNING* EOT MARKER ERROR

BAC

*WARNING* FILE IDS WILL NOT BE PRESERVED

BAC

*WARNING* NONFATAL QUALIFIER CONFLICTS BEING IGNORED

These and other warning messages are explained in
the RSX-llM/M-PLUS Utilities Manual.

Chapter

BACKUP also issues purely
following:

such

informational

Completed
Starting tape n on ddnn:

5-70

messages

7
as

of
the

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
These messages require no response.
BACKUP requests response from the user•with messages such as
following:

the

Please answer Yes or No
Mount another tape
The following are the most common error
Other
error
messages are described
Utilities Manual.

messages from BACKUP.
in the RSX-llM/M-PLUS

BAC -- *FATAL*-Allocation for sys file exceeds volume limit

Explanation: One of the five files created when a volume is
initialized does not fit on the output disk.
This message
usually occurs when the output disk is smaller than the input
disk.
User Action: Reinitialize the disk using the /INDEX:BEGINNING
qualifier to BACKUP or
INITIALIZE to force the allocation to
start at the beginning of the disk.
You can also use the
/MAXIMUM FILES or /HEADERS qualifiers to reduce the size of
INDEXF. SYS.
BAC -- *FATAL*-Attach failed on ddnn:

Explanation:

BRU could not attach the specified device.

User Action: Check to see if another task has the
attached, or if the device has a volume mounted on it.

device

BAC -- *FATAL*-Device conflict

Explanation: Command specified both a tape and a disk
part of the input or output device specification.

drive

User Action: You can specify either a disk or a tape but not
both.
Check command for proper device names and reenter the
command.
BAC -- *FATAL*-Device not in system

Explanation: Command specified a device that is not part of
current system.
User Action:

the

Check command for proper device names and reenter=

BAC -- *FATAL*-Device not supported

Explanation:
disk.

Command specified a device that is not

User Action:

Check command for proper device names and reenter.

5-71

tape

HANDLING DEVICES AND VOLUMES

SHOW ASSIGNMENTS
BAC -- *FATAL*-Disk read error

Explanation:
disk.

An unrecoverable read error occurred on the output
This error could be caused by an undetected bad block.

user Action: Run BAD on the disk and then use
/BAD_BLOCKS:AUTOMATIC qualifier.

BACKUP

with

the

BAC -- *FATAL*-Disk write error

Explanation:
disk.

An unrecoverable write error occurred on the output
This error could be caused by an undetected bad block.

User Action:

Run BAD on the disk and then use
/BAD_BLOCKS:AUTOMATIC qualifier.

BAC-- *FATAL*-End of volume encountered.

BACKUP

with

the

Backup set not found

Explanation: The backup set specified for a restore operation is
not on the tape volume.
User

Action:

Mount

the

correct

tape

volume

and

retry

and

display

certain

the

operation.

SET AND SHOW

5.10

c;rn display
characteristics.

Vern

5.10.1

assignments

set

device

SHOW ASSIGNMENTS

SHOW ASSIGNMENTS displays at your terminal all local and login
logical-device assignments.
Privileged users can display assignments
from other terminals and global assignments.
Logical-device assignments are established by ASSIGN, by SET
and by ACNT, the Account File Maintenance Program.

Format
SHOW ASSIGNMENTS[/qualifier]

Command Qualifiers
/LOCAL
/GLOBAL
/TERMINAL:ttnn:
/LOGIN
/SYSTEM (synonym for /GLOBAL)

Parameters
None.

5-72

DEFAULT,

HANDLING DEVICES AND VOLUMES

SHOW ASSIGNMENTS {Cont.)
Command Qualifiers
/LOCAL
Specifies that local and
login logical assignments
from your
This is the
terminal are to be displayed on your terminal.
default.
/GLOBAL
Specifies that all logical assignments in the system,
global assignments,
are to be displayed on TI:.
privileged .qualifier.

including
This is a

/TERMINAL:ttnn:
Specifies that local and login assignments
from terminal
ttnn:
are to be displayed on TI:.
This is a privileged qualifier.
/LOGIN
Privileged qualifier
included for
completeness.
terminals, this qualifier is the same as /LOCAL.

For

all

Examples

>SHOW
Function? ASSIGNMENTS
LPO:
DK1!
LOCAL
TPO:
TT11:
LOCAL
SYO:
DB1:
LOGIN

TI - TT11:
TI -- TT1U
TI -- TT1U

This example shows the display for a user who has used ASSIGN to
assign local logical names to a number of devices.
These logical
names can be used in place of the device names.
The logical name
is displayed on the left and the physical device name (or pseudo
device name) is on the right.
The type of assignment -- LOCAL or
LOGIN -- is given, and the TI:.
Output to LPO: will actually go
to DKl:.
In this case, the logical name takes the place of a
physical device name.
The user cannot direct output to physical
LPO:.
Output to TPO:
will go to TTll:,
which
is TI:.
In
addition,
the user has
the login assignment of SYO:
to DBl:.
This means that DBl:
is the default device for this user.

>SHOW ASSIGNMENTS/LOCAL
This example is the equivalent of the previous example.

>SHOW ASSIGNMENTS/TERMINAL:TT37!
MPO:
SYO:
LOCAL
TI - TT37:
SYO:
SYO:
LOGIN
TI - TT37!
This example, which requires a privileged terminal, displays
the
logical assignments from terminal TT37:.
This user has given the
local logical name MPO:
to the pseudo device, SYO:.
The
login
assignment gives the
login logical
name SYO:
to the pseudo
device SYO:.
SYO:
is the name of the default device.

5-73

HANDLING DEVICES AND VOLUMES

SET DEVICE
>SHOW ASSIGNMENTS/GLOBAL
LOCAL
TI
DBl:
SYO:
SYO:
DBl:
LOGIN
TI
TI
LOGIN
SYO:
SYO:
SYO:
LOGIN
TI
SYO:

WKO:
!NO:
EXO:

LBO:
SYO:
SYO:

TT42:
VT4:
TT4:
TT15:

GLOBAL
GLOBAL
GLOBAL

This example, which requires a privileged terminal, displays
logical assignments for the entire system.

5.10.2

all

SET DEVICE

SET DEVICE establishes certain device attributes. With the
of SET DEVICE:TI:/WIDTH:n, this is a privileged command.

exception

Format
SET DEVICE
Device? ddnn:
Attribute? attribute
SET DEVICE:ddnn:/attribute

Device Attributes
/[NO]CHECKPOINT FILE:n
/[NO]LOWERCASE /[NO]PUBLIC
/[NO]SYSTEM
/WIDTH :n

Parameter
DEVICE:ddnn:
Specifies the device for which attributes are to be set.
Note
that,
when the one-line form of the command is used, the
parameter is ddnn: preceded by a colon (:) at the end of the
word DEVICE.

Device Attributes
/[NO]CHECKPOINT_FILE:n
The /CHECKPOINT FILE:n attribute sets aside n (decimal) blocks on
the specified -volume in
[O,O]CORIMG.SYS, the checkpoint file.
The volume must be in Files-11 format.
Only one checkpoint file
is permitted on each volume, but several volumes may have
checkpoint files.
Tne system searches for
checkpoint files
in
the order they were created.
If space is not available in the

5-74

HANDLING DEVICES AND VOLUMES

SET DEVICE (Cont.)
first checkpoint file created
(the primary file),
the system
searches in the second file to be created, and so on. Checkpoint
files can be allocated on volumes mounted on private devices.
In
general, the system should have checkpoint space equal to twice
the total amount of memory that all running tasks are using.
The /NOCHECKPOINT FILE attribute makes the checkpoint
file
unavailable.
If the specified file contains checkpointed tasks,
the file is not deactivated until the tasks have returned to
memory, but no new tasks will be checkpointed to the file.
The
checkpoint file is still on the volume but is zero blocks long.
/[NO]LOWERCASE
The /LOWERCASE attribute sets a terminal or line printer so that
lowercase characters are not converted to uppercase for printing.
The /NOLOWERCASE attribute sets a terminal or line printer so
that
lowercase
characters are converted to uppercase for
printing. This is the default.
Nonprivileged users can use the SET TERMINAL/LOWERCASE command to
set TI:
in this fashion.
/[NO]PUBLIC
/[NO]SYSTEM
The /PUBLIC attribute sets the device as a public device.
This
command also mounts the device.
Public devices are accessible to
all users.
The /NOPUBLIC attribute removes the public status
This is the default setting.

device.

/[NO]SYSTEM is a synonym included for VAX/VMS compatibility.
Section
devices.

5.1.3

contains

discussion

public

and

private

/WIDTH :n
Sets the size of a device's I/O buffer. The value of n (decimal)
is the length in characters of a line on the device.
For line printers, n must be greater than 0 and not greater than
255.
The line-printer driver discards all characters in a record
(line) that do not fit in the I/O buffer.
For terminals, n must be greater than 2 and not greater than 255.
The terminal driver does not discard excess characters, but puts
them in a record of their own.
That is, excess characters appear
one line below the line in which they should appear.
Nonprivileged users can set the width of
this command or SET TERMINAL/WIDTH:n.

5-75

their

terminals

using

HANDLING DEVICES AND VOLUMES

SET DEVICE (Cont.)
Examples

>SET
Function? DEVICC

Device? LP1:
Attribute?

WIDTH:ao

This example sets the I/O buffer size
(line
(decimal) characters on the line printer LPl:.

length)

>SET DEV!CE:LP1:/LOWERCASE
This example sets LPl: so that all lowercase characters sent to
it will be printed in lowercase. The command must be issued even
if the printer is controlled by the Queue Manager and has been
initialized lowercase.
>SET DE'-.1 I CE: DB3: /CHEC1<Fi:1 r NT ... FI L.E ~ ::~~·t,

This example creates a checkpoint file of 256 (decimal) blocks on
DB3:.
Notes
SHOW DEVICES displays the attributes set by SET DEVICE.
Error Messages
SET -- Feature not supported
Explanation: The command specified an optional feature that
not incorporated into the system at system generation.
User Action:

was

See your system manager.

SET -- Pseudo device error
Explanation:

Command attempted to set a pseudo device public.

user Action: A pseudo device cannot
command using physical device name.

set

public.

Retype

SET -- Write check not supported
Explanation: Command attempted to
device that does not support it.

enable

write-checking

User Action: Write-checking is not supported on magnetic
RLOls, or RXOls.

5-76

tapes,

HANDLING DEVICES AND VOLUMES

SHOW DEVICES
5.10G3

SHOW DEVICES

SHOW DEVICES displays information about the devices
system.

included

the

Format
SHOW DEVICES [/attribute]

Device Attributes
/dd [nn] :
/[NO]PUBLIC
/WIDTH: ddnn:
/[NO]SYSTEM (synonym for /PUBLIC)

Device Attributes
If you do not include an attribute, SHOW DEVICES displays a
list
of all the devices on the system, including terminals and pseudo
devices.
/[NO]PUBLIC
/[NO]SYSTEM
Displays a list of all devices set
(or not set)
PUBLIC.
/[NO]SYSTEM is a synonym included for VAX/VMS compatibility.
/dd [nn]:
Displays information about all devices of a particular type on
the system. dd:
is the 2-letter device mnemonic terminated with
a colon, which indicates the type of device controller.
The
display shows the devices under that type of controller by model
name.
The command SHOW DEVICES/dd[nn:]
is useful when you plan to
allocate a drive, as it shows you which drives are available.
Since the same controller may control devices whose disks are not
interchangeable, a generic allocate (ALLOCATE DB) may allocate a
device which cannot accept your disk. See examples.
/WIDTH :ddnn:
Displays the size of the I/O buffer
particular device, including a terminal.

(line

length)

for

Display Information
The display from SHOW DEVICES can include a number of messages.
ddnn:
A device name in the first column indicates the device or pseudo
device for which information is being displayed. A device name
in the second column indicates a
device
to
which
the
corresponding device in the first column has been redirected
(logically assigned).

5-77

HANDLING DEVICES AND VOLUMES

SHOW DEVICES {Cont.)
TTnn:
A terminal name in the second column,
followed by the word
PRIVATE,
indicates that the device named in the first column has
been allocated by the user logged on to the terminal in the
second column.
MOUNTED
Indicates that the device is mounted. For privileged users,
message also includes the volume label.

the

BUF=
Indicates the line length (I/O buffer size).
PUBLIC
Indicates that the device has been set public.
If your command was SHOW DEVICES /PUBLIC,
display is PUB=ddnn: or NOPUB=ddnn:

/NOPUBLIC,

the

TYPE=
Indicates the device type by model name, for example, RLOl, RX02.
If you wish to display devices by type, use the 2-letter device
mnemonic.
MARKED FOR DISMOUNT
Indicates that a mounted device has been marked for dismount, but
that the dismount has not been completed, meaning that files are
still open on the volume. The volume can be remounted while it
is marked for dismount.
OFFLINE
Indicates that the system tables contain entries for the device,
but that it is not included in the current configuration.
[g,m] LOGGED ON
Indicates that the user identified by [g,m] is logged on
terminal.

the

LOADED
Indicates that a loadable device driver is currently loaded.
UNLOADED
Indicates that a loadable device driver is currently not loaded.
SPOOLED
Indicates that a
Manager.

device

under

5-78

the

control

the

Queue

HANDLING DEVICES AND VOLUMES

SHOW DEVICES (Cont)
WCHK=
NOWCHK=
Indicates a device with write-checking enabled or not enabled.

Examples

>SHOW DEVICES
DBO:
PUBLIC MOUNTED LOADED TYPE=RP06
DB1J
PUBLIC MOUNTED LOADED TYPE=RP06
DB2:
PUBLIC LOADED TYPE=RP04
DB3t
PUBLIC MOUNTED LOADED TYPE=RP06
DRO:
VT3! - PRIVATE MOUNTED LOADED TYPE=RM03
DR1:
LOADED TYPE=RM03
DKO!
LOADED
LPO!
DBO: SPOOLED LOADED
LP1t
DBO: SPOOLED LOADED
coo~

no:

TTC:
-11:
TT2:

LOADED
[7,40J
[J,40J

C111J
- LOGGED ON LOADED
[14,lOJ - LOGGED ON LOADED

TT.\:

L303,5J

[303,:=:;:i

TT66:
TT67:
H .. O!

LOADED
LOADED
LOADED
LOADED

IJT 0:
VT1:

lJT2:
VT4!
TIO t

[1 dJ

[303,5]

no:

SPO;

DBO:
DBO!
DBO:

SYO!

LOGGED ON LOADED

LOf.iDFD

CLO!
L.BO:

[ 1 '1]
[303,5]

- LOGGED ON LOADED
- LOGGED ON LOADED

This example shows the display from SHOW DEVICES.
All devices
and pseudo devices are included.
For terminals, the first [g,m]
field is the login UIC and the second is the default UFD.
The
only
information shown for pseudo devices is the name and the
device to which they are redirected.
Privileged users also see
volume labels.

>SHOW DEVICES DB:
DBO!
PUBLIC MOUNTED LOADED TYPE=RP06
DB1:
PUBLIC MOUNTED LOADED TYPE=RP06
DB2:
PUBLIC LOADED TYPE=RP04
DB3:
PUBLIC MOUNTED LOADED TYPE=RP06
This example displays information about all devices of the
type
DB:.
The mnemonic (DBnn:) identifies the device controller and
the model name (RP04) indicates the physical device type.
RP04
disks do not fit RP06 drives, even though the device controller
is the same.

5-79

HANDLING DEVICES AND VOLUMES

SHOW DEVICES (Cont.}
>f) H0 W DE l) I CE E) / F' LI BL I C
F'UB=-DBO t
FUB·:: DB 1 !
F' U l~ ~.:: [t f: 2 :;

uH :: !.I H3 !
FLJB=DSO!
p u ~:· :: [Is 1 :
? 1. I [i :: L P o ~
t'lJB=:L.P 1 !

1·:·

This example displays
information about all public devices.
Public devices are accessible to all users~
They may be mounted
by any user to assure continued access to the volume mounted on
the device.
>EHOW lJE'..1 ICE: LPO Z /WIDTH
HUF==L PO: lJOl 32.

<;HOlil DE· 'JI CF~ TT 11.: /WIDTH
HUF::T"I 11t000BO +

This example displays the line lengths of a line printer and a
terminal.
The line length is determined by the size of the I/0
buffer, which is established through SET DEVICE:ddnn:WIDTH.

5-80

CHAPTER 6
PROGRAM DEVELOPMENT

6.1

INTRODUCTION

Program development on RSX-llM/M-PLUS is accomplished in four steps:
1.

Creating a program in a supported source
editor

Compiling or assembling the source program to create a binary
object file

Turning the object file into a runnable task image using
Task Builder

Running the program as a task on the system

If you are not familiar with the rudiments of this
Introduction to RSX-llM and RSX-llM-PLUS.

language

process,

using

see

the

To create a source program, you must be
familiar
with
the
file-creation facilities of the system discussed in Chapter 4 of this
manual.
You will also need knowledge of one of the programming
languages available on your system.
Commands described in this chapter on program development include
commands directed to various language compilers or interpreters and
the MACR0-11 Assembler, commands for maintenance of libraries used by
programs, and the LINK command, which controls the operation of the
Task Builder.
RSX-llM/M-PLUS systems offer extensive program development facilities.
These facilities are introduced in the RSX-llM/M-PLUS Guide to Program
Development. This manual introduces the most important software tools
used in program development and takes you through the program
development process in considerable detail.

6.2

SOORCE LANGUAGES

RSX-llM and RSX-llM-PLUS support a number of programming languages,
also called source languages.
Not all of these languages are
available on all systems, but all systems have one or more source
languages available.

6-1

PROGRAM DEVELOPMENT

MACRO
For each language or language group, there is a DCL command.
The
MACRO command gives access to the MACR0-11 Assembler. The BASIC
command gives access to either the BASIC-11 interpreter or the
BASIC-PLUS-2 interactive compiler.
The FORTRAN command gives access
to the FORTRAN-IV, FORTRAN-IV-PLUS, and FORTRAN-77 compilers.
The
COBOL command gives access to the PDP-11 COBOL and COBOL-81 compilers.
The CORAL command gives access to the CORAL 66 compiler.
Documentation is available for all DIGITAL-supplied languages included
in your system.
Your system may also have other languages not
described here. See your system manager for
information on the
languages available at your installation.
All systems include the MACR0-11 Assembler for processing MACR0-11
source code. MACR0-11 is the assembly language for PDP-11 computers,
but this language includes many features considered the province of
high-level languages.
MACR0-11 is named for
its capacity to use
macros, where a single line of code can stand for a long series of
assembly-language instructions.
Regardless of your usual programming language, you should look into
MACR0-11. MACR0-11 is capable of doing anything that can be done on a
PDP-11. All DIGITAL-supplied high-level languages have the means for
incorporating MACR0-11 routines. Since the high-level languages are
designed for use on computers from many different manufacturers, some
functions that are difficult to achieve in a generalized high-level
language may be easier to perform in MACR0-11, which is designed
specifically for PDP-lls.
In addition to the RSX-llM/M-PLUS Guide to Program Development, you
should review the following manuals -ror information on MACR0-11
programming on RSX-llM or RSX-llM-PLUS:
•

PDP-11 MACR0-11 Language Reference
assembly-language programming.

Manual,

which

describes

!AS/RSX System Library
• describes
the routines
RSX-llM-PLUS.

Routines Reference Manual,
which
used by system tasks on RSX-llM and
These routines can be included in programs.

Executive Reference Manual, which
• RSX-llM/M-PLUS
system
directives
and their processing.
You

describes
can call

Executive routines in your programs.
•

6.2.1

PDPll/xx Processor Handbook.
Describes
including its instruction set.

each

PDP-11

model,

MACRO

MACRO invokes the MACR0-11 Relocatable Assembler, which assembles one
or more MACR0-11 source files into a single relocatable object module
suitable for processing by the Task Builder.
Format
MACRO[/qualifier[s]] filespec[/qualifier[s]]

6-2

[,filespec[,s]]

PROGRAM DEVELOPMENT

MACRO (Cont.)
Command Qualifiers
/[NO]CROSS REFERENCE
/DISABLE: (arg[,s])
ABSOLUTE
BINARY
CARD FORMAT
GLOBAL
LOCAL
LOWERCASE
REGISTER DEFINITIONS
TRUNCATION
/ENABLE: (arg [ ,s])
ABSOLUTE
BINARY
CARD FORMAT
GLOBAL
LOCAL
LOWERCASE
REGISTER DEFINITIONS
TRUNCATION
/[NO]LIST[:filespec]
/[NO]OBJECT[:filespec]
/[NO]SHOW[: (arg[,s])]
ALL
BINARY
CALLS
COMMENTS
CONDITIONALS
CONTENTS
COUNTER
DEFINITIONS
EXPANSIONS
EXTENSIONS
LISTING DIRECTIVES
OBJECT BINARY
SEQUENCE NUMBERS
SOURCE SYMBOLS
I [NO] WIDE

File Qualifiers
/LIBRARY
/PASS:n

Parameter
f ilespec [ s]

Specifies input files for the MACR0-11 Assembler.
These
input
files must contain MACR0-11 source code.
Multiple filespecs must
be separated by commas.
Filespecs must include a file name.
If
no file type is given, the default file type (.MAC) is applied.
If the parameter qualifier /LIBRARY is used, .MLB is the default
file type.
No wildcards are accepted by MACRO.

6-3

PROGRAM DEVELOPMENT

MACRO (Cont.)
NOTE
The MACR0-11 Assembler uses the name of
the last file named in the command as
the default name for output files.
The
last file named cannot be a library.
All other language commands, and the
LINK command, use the first file named
in the command as the default name for
output files.

Command Qualifiers
/[NO]LIST{:filespec]
Specifies whether an assembly listing should be generated.
The
default is /NOLIST, meaning no assembly listing is generated.
If you do not supply a file specification for this qualifier, the
listing has a file name derived from the name of the last source
file in the MACRO command with the file type .LST.
If you wish
the listing to have a different name, supply the name as an
argument to the /LIST qualifier.
If you do supply a name, the
listing file appears in your directory but is not printed on the
line printer.
The /LIST qualifier behaves in a different manner depending on
whether it is given as a command qualifier or a filespec
qualifier.
If /LIST is used as a command qualifier, the listing
file is placed in your directory and printed on the line printer.
If /LIST is used as a filespec qualifier,
the listing file
appears in your directory but is not printed on the line printer.
If your command line includes the /CROSS REFERENCE qualifier,
/LIST is implied and need not be specified~ /CROSS REFERENCE as
a command qualifier causes the file to be printed on the line
printer;
/CROSS REFERENCE as a filespec qualifier prevents the
listing file from-being printed.
If your command line includes listing-control arguments to either
/SHOW or /NOSHOW, /LIST is implied and need not be specified.
/[NO]SHOW as a command qualifier causes the file to be printed on
the line printer; /[NO]SHOW as a filespec qualifier prevents the
listing file from being printed.
The only time you need to use /LIST with /CROSS REFERENCE or
/[NO]SHOW is when you wish to give the listing file a filespec
other than the default.
In such cases, the position of the
qualifiers in the command line has no effect;
the listing file
appears in your directory but is not printed on the line printer.
See the examples.

6-4

PROGRAM DEVELOPMENT

MACRO (Cont.)
/[NO]OBJECT[:filespec]
Specifies whether an object module should be generated.
The
default is /OBJECT, meaning an object module is generated.
If
you do not supply a file specification, the object file has a
name derived from the name of the last source file and the file
type .OBJ.
If you wish the object file to have a different name,
give the name as an argument to the /OBJECT qualifier.
You can name the object file after any of the source files listed
in the MACRO command by using /OBJECT as a filespec qualifier.
If used as a filespec qualifier, /OBJECT cannot take a
filespec
argument.
The qualifier /NOOBJECT specifies that no object module is
generated.
You can use this qualifier if you wish to use other
facilities of the assembler, to get an assembly listing,
for
instance, without doing the assembly.
/[NO]CROSS_REFERENCE
Specifies whether a cross-reference listing should be generated
and
appended
to
the
assembly listing.
The default is
/NOCROSS_REFERENCE.
The cross-reference listing locates all user-defined
symbols that appear in the source program.

and

MACRO

When you specify this qualifier, you are also specifying the
/LIST
qualifier
by
implication.
An assembly listing is
generated.
It appears in your directory and is also printed on
the line printer.
If you wish to change the name of the listing
file, you must use /LIST with a file specification in addition to
/CROSS_REFERENCE.
/CROSS REFERENCE as a command qualifier causes the file to be
printed on the line printer;
/CROSS REFERENCE as a filespec
qualifier prevents the listing file from being printed. See the
examples and the discussion under /LIST.
/ENABLE:(arg[,s])
/DISABLE: (arg[,s])
These qualifiers override the
.ENABL and
.DSABL
assembler
directives included in the source program being assembled.
The
.ENABL and .DSABL directives invoke or inhibit various aspects of
the assembly.
Table 6-1 summarizes the arguments to /ENABLE and
/DISABLE and gives their MACR0-11 equivalents.
There is a
default setting for each of these directives, even if you do not
specify them in your code or command line.
These qualifiers affect the entire assembly.
If,
for example,
your MACRO command includes the qualifier /ENABLE:LOWER CASE, the
assembler does not convert any lowercase source -text
to
uppercase, regardless of any .DSABL LC or .ENABL LC directives in
the source code.
The same goes for /DISABLE:LOWER CASE.
All
.ENABL or .DISABL LC directives are ignored.
-

6-5

PROGRAM DEVELOPMENT

MACRO (Cont.)
If you specify only one argument to /ENABLE or /DISABLE, you need
not include the parentheses, but if you have more than one
argument, they must be separated by commas and enclosed in
parentheses.
Table 6-1
The /ENABLE and /DISABLE Qualifiers
Assembly Functions Disabled by Default
ABSOLUTE

AMA

Enabling
this
function
causes
relative mode addresses (mode 67) to
be assembled as absolute addresses
(mode 37) •

BINARY

ABS

Enabling
absolute
format.

CARD FORMAT

CDR

Enabling this function causes source
columns 73 and greater to be treated
as a comment.

LOCAL

LSB

this
function
produces
binary output in Files-11

Enabling this function permits the
disabling or enabling of a local
symbol block.

LOWERCASE

Enabling
this
function
causes
MACR0-11 to accept lowercase ASCII
input. The default is to convert it
to uppercase.

TRUNCATION

FPT

Enabling
this
function
causes
floating-point
truncation.
The
default is floating-point rounding.

Assembly Functions Enabled by Default
REGISTER DEFINITIONS

REG

Disabling this function inhibits the
normal
MACR0-11 default register
definitions.
The default is R0=%0,
Rl=%1 • • • SP=%6,PC=%7. Under most
circumstances, you should use these
defaults.

GLOBAL

GBL

Disabling
this
function
causes
MACR0-11
to
treat
all
symbol
references that are undefined at the
end of Assembly Pass 1 as undefined
symbols. The default is to treat
all such symbols as global symbols.

6-6

PROGRAM DEVELOPMENT

MACRO (Cont.)
/[NO) SHOW[: {arg [ ,s)))
These qualifiers override the
.LIST and
.NLIST
assembler
directives
included
in the source program being assembled.
The
.LIST and .NLIST directives control the content and format of the
assembly listing.
Table 6-2 summarizes the arguments to /SHOW
and /NOSHOW and gives their MACR0-11 equivalents.
There
is a
default setting for each of these directives, even if you do not
specify them in your code or command line.
These qualifiers affect the entire assembly.
If,
for example,
your MACRO command
includes the qualifier /SHOW:COMMENTS, the
assembly listing includes all comments, regardless of any
.NLIST
COM or
.LIST COM directives in the source code.
The same goes
for /NOSHOW:COMMENTS.
All .LIST COM or
.DISABL COM directives
are ignored.
If you specify only one argument to /SHOW or /NOSHOW,
you need
not
include the parentheses, but if you have more than one
argument, they must be separated by commas and enclosed
in
parentheses.
/SHOW implies /LIST, but if you wish the listing file to
name other than the default, you must still use /LIST.

have

/SHOW as a command qualifier causes the file to be printed on the
line printer;
/SHOW as a filespec qualifier prevents the listing
file from being printed.
See the example and
the discussion
under /LIST.
Table 6-2
The /SHOW and /NOSHOW Qualifiers
Listing Functions Disabled by Default
EXPANSIONS

Enabling
this
function
causes
MACR0-11
to
include
all macro
expansions in the listing.

BINARY

MEB

Enabling
this
function
causes
MACR0-11 to
list only those macro
expansions that
generate
binary
code.
This
is
a
subset
of
EX PANS IONS.

LISTING DIRECTIVES

Enabling
this
function
causes
MACR0-11 to list all listing control
directives without arguments,
that
is,
those listing directives that
alter the listing level count.
(Continued on next page)

6-7

PROGRAM DEVELOPMENT

MACRO (Cont.)
Table 6-2 (Cont.)
The /SHOW and /NOSHOW Qualifiers
Listing Functions Enabled by Default
SEQUENCE_NUMBERS

SEQ

Disabling this function suppresses
the inclusion of sequence numbers in
the listing.
Sequence numbers are
replaced by tabs.

COUNTER

LOC

Disabling this
function suppresses
the location counter field and does
not replace it with a tab.

OBJECT B !NARY

BIN

Disabling this function suppresses
the listing of generated binary code
and does not replace it with a tab.

EXTENSIONS

BEX

Disabling this function suppresses
the listing of binary extensions,
that is, all binary code that will
not fit on the first line.
This is
a subset of OBJECT BINARY.

SOURCE

SRC

Disabling this function suppresses
the listing of source lines.

COMMEN'l'8

COM

uisabiing this function suppresses
the listing of comments.
This is a
subset of SOURCE.

DEFINITIONS

Disabling this function suppresses
the listing of macro definitions and
repeat range expansions.

CALLS

Disabling this function
the
listing of macro
repeat range expansions.

CONDITIONALS

CND

Disabling this function suppresses
the
listing
of
unsatisfied
conditional coding.

CONTENTS

TOC

Disabling this function suppresses
the listing of table of contents
during assembly pass 1.
The full
assembly listing
is still prepared
during assembly pass 2.

SYMBOLS

SYM

Disabling this
function suppresses
the listing of the symbol table
resulting from the assembly.

6-8

suppresses
calls and

PROGRAM DEVELOPMENT

MACRO (Cont.)
I [NOj WIDE
Specifies whether you wish the assembly listing in wide or narrow
format.
The default can be set by your system manager.
As
supplied, the default is /WIDE, also called line printer format.
/NOWIDE is sometimes called teleprinter format.
This qualifier overrides any .LIST TTM or .NLIST
included in your source program.

TTM

directives

Parameter Qualifier
/PASS:n
Specifies that the file thus qualified is only to be assembled
during the pass specified.
The assembler makes two passes;
n
can be either 1 or 2.
/LIBRARY
Specifies that the file thus qualified is a macro library.
The
default file type is
.MLB. A user macro library file must be
specified in the command line before any source files that use
the macros defined in the library.
A library may not be the last
file named in the command line. Remember that the system macro
library has the type .SML.
If you are referencing this library,
you must explicitly state the type.
Examples

>MACRO
File? NOODLE
This example assembles the source file
relocatable object module named NOODLE.OBJ.

NOODLE.MAC

into

>MACRO NOODLE
This example is equivalent to the previous one.

>MACRO NOODLE,DOODLE1YANKEE
This example assembles the source files NOODLE.MAC, DOODLE.MAC,
and YANKEE.MAC into a relocatable object module named YANKEE.OBJ.

>MACRO/LIST NOODLE
This example assembles the source file NOODLE.MAC into the object
file
NOODLE.OBJ,
and
also produces an assembly listing,
NOODLE.LST.
The assembly listing appears in your directory and
is also printed on the line printer.

6-9

PROGRAM DEVELOPMENT

MACRO (Cont.)
>MACRO/LIST:PRINCE NOODLE
This example assembles the source file NOODLE.MAC into the object
file
NOODLE.OBJ,
and also produces an assembly listing named
PRINCE.LST.
The assembly listing appears in your directory and
is printed on the line printer.

>MAC/LIST!Tit NOODLE
NOODLE

MACRO M1113

02-SEP-82 11:41

PAGE 1
• TITLE

1
2
3
4
5
6
7

• LIST
.NUBT

NOODLE

TTM

BEX

MACRO LI BRA RY CAL.LS
.MCALL

8
9

EXITSS,QIOWS,DIRS

This example assembles the source file NOODLE.MAC into the object
r11e NOOULE.OBJ and types the assembiy iisting on your terminal.
No permanent copy of the listing file is retained, nor does the
listing appear on the line printer.

>MAC/OBJECT:ROTINI NOODLE
This example produces an object file with the name ROTINI.OBJ.

>MACRO

NOODLE/LIBRARY~ROTINI~SPIRELL!,SHELL

This example assembles a concatenated object file named SHELL.OBJ
from the source files NOODLE.MLB, ROTINI.MAC, SPIRELLI.MAC, and
SHELL.MAC.

>MACRO/NOSHOW!COMMENTS/WIDE NOODLE
This example produces an object module and an assembly listing.
Any
.LIST or .NLIST directives with TTM or COM as arguments are
ignored.
The directives themselves appear in the listing, but
they have had no effect.
The listing produced by this command
includes no comments and is
in wide format.
The listing
is
printed on the line printer and appears in your directory as
NOODLE.LST.

6-10

PROGRAM DEVELOPMENT

BASIC
>MACRO/NOSHOW:CCOMMENTS, OBJECT .. BINARY)/SHOW!EXPANSIONS ELBOW

This example produces an object module and an assembly listing.
Any .LIST or .NLIST directives with COM, BIN, or ME arguments are
ignored. The listing includes no comments and no binary code,
but
does
include
macro expansions.
Observe the use of
parentheses where two arguments are given for /NOSHOW and the
lack of parentheses where only one argument is given for /SHOW.
Notes
You must be familiar with MACR0-11 Assembly Language to use the
MACRO command successfully.
In particular, see the chapter on
operating procedures in the PDP-11 MACR0-11 Language Reference
Manual.
See also the chapter on assembler directives for
information on the /[NO]SHOW and /ENABLE and /DISABLE qualifiers.

6.2.2

BASIC

BASIC invokes an interpreter or compiler for the BASIC language.
BASIC stands for Beginners All-Purpose Symbolic Instruction Code.
Format
BASIC[/qualifier]

[@filespec]

Command Qualifiers
/Bll

/BP2
/USING:userbasic
Parameter
@f ilespec
Specifies an indirect command file that contains BASIC-PLUS-2
commands.
Command Qualifiers
/Bll

Specifies the BASIC-11 interactive language interpreter.
Under
this interpreter, programs are not compiled or task built. The
BASIC-11 interpreter is a task that interprets and executes
BASIC-11 instructions.
BASIC-11 includes an immediate or "desk-calculator" mode.
If
your system includes BASIC-11, you should look into it even if
you do not plan to program in BASIC-11. See the examples.
BASIC-11 is compatible with Dartmouth BASIC.
The BYE command causes an exit from BASIC-11.

6-11

PROGRAM DEVELOPMENT

BASIC (Cont.)
/BP2
Invokes the BASIC-PLUS-2 compiler, which is the default. The BP2
compiler can create Task Builder Command and Overlay Descriptor
Language (ODL) files and a listing file in addition to the object
module file for the program it compiles. See Section 6.4 for
information on how to use 'these files with the LINK command.
The EXIT command or a CTRL/Z causes an exit from BASIC-PLUS-2.
/USING:userbasic
Invokes an installed interpreter or compiler different from
either of the DIGITAL BASIC systems discussed here. See your
system manager for further information.

Examples

>BAS I C/B 11
IAS/RSX BASIC V02-01

READY
BYE

>
In this example, the user invoked the BASIC-PLUS-2 interpreter
with the BASIC/Bll command. READY is the BASIC-11 prompt.
The
'n't7T:1

.U.1..L:.1

------...::
1...Vlllll!ClUU

--~·--l...ClU.:>C.:>

-ClU

- ... .::..
ChJ.\..

-=---

.L.LVUl

n"C"'IT~
'1 1
unlJJ.v-..1....1...

>BASIC

PDP-11 BASIC-PLUS-2

v2.o BL-00

BASIC2
EXIT

>
In this example, the user invoked by default the BASIC-PLUS-2
compiler.
BASIC2 is the BASIC-PLUS-2 prompt. The EXIT command
causes an exit from BASIC-PLUS-2 (as does CTRL/Z).

>BASIC/B11
!AS/RSX BASIC V02-01

READY
PRINT C10+2>*<38*9>*<PI/3)
4297.7
READY
10 FOR I=1. TO 10
20 PRINT <I*PI)/3
30 NEXT I
READY

6-12

PROGRAM DEVELOPMENT

FORTRAN
RUN
26-0CT-82

17:11:55

1. 0472

2.0944
3.14159

4.18879
5.23599
6.2831~;

7. :no:rn
s. 3 :n:::;s
9.424"78
10.472
RE?1DY

BYE

>
In this example, the user used the
immediate mode of BASIC-11
(without line numbers) to perform a calculation.
Then, the user
typed in a small program (with line numbers) to produce a table.
This program can be saved;
the immediate mode example cannot.
BASIC-11 includes many mathematical functions and others can be
defined.

Notes
See the BASIC documentation, if any, supplied with
Not all systems include BASIC=

6.2.3

your

system~

FORTRAN

FORTRAN invokes a FORTRAN compiler.
RSX-llM/M-PLUS systems may use two DIGITAL FORTRAN source language
compilers:
FORTRAN IV/IAS-RSX
(commonly called FORTRAN IV), and
FORTRAN-77.
FORTRAN IV-PLUS is described in this section for
those
users who still have this compiler on their systems; however,
FORTRAN-77 is superseding the FORTRAN IV-PLUS compiler.
Since these
compilers are optional software, your installation may have no FORTRAN
compiler at al 1.

Format
FORTRAN[/qualifier[s]] filespec[,s]

Command Qualifiers
/[NO]CHECK
/CODE:arg
EAE
EIS
FIS
THREADED

6-13

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
/CONTINUATIONS:n
/[NO] DLINES
/[NO]EXTEND SOURCE
/FOR
/F4P
I [NO] F77
/IDENTIFICATION
/[NO]I4
/[NO]LINE NUMBERS
/[NO]LIST(:filespec]
/[NO]MACHINE CODE
/[NO]MAP
/[NO]OBJECT[:filespec]
/[NO]SHAREABLE
/SOURCE
/[NO]STANDARD:arg
ALL
NONE
SOURCE
SYNTAX
/[NO]TRACEBACK:arg
ALL
BLOCKS
LINES
NAMES
NONE
/USING:usercompiler
/[NO]VECTORS
/[NO]WARNINGS
/WORK_FILES:n

Parameter
filespec[,s]
Specifies the file or files to be compiled.
If you
than one file, separate the filespecs with commas.

name

Files input to any of the FORTRAN compilers must contain FORTRAN
source language to match that compiler.
In other words, the
FORTRAN IV compiler works only on FORTRAN IV source code, and so
forth.
See the FORTRAN documentation supplied with your system
for more information.
The default file type for all FORTRAN compilers is .FTN.
NOTE
The FORTRAN compilers use the name of the first
file
named in the command as the default name for output
files.
Except for MACR0-11, all language commands and
the LINK command use the first file named in the command
as the default name for output files.

6-14

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
Command Qualifiers
/FOR
Specifies the FORTRAN IV compiler.
This is the default for
the
FORTRAN command, so it is not necessary to use this qualifier.
Your system must include the FORTRAN IV Object Module Library
(OLB)
and Object Time System (OTS) for this qualifier to work.
Therefore, your system or library UFD must include the following
files:
FOROTS.OLB
FOR.TSK
/F4P
Specifies the FORTRAN IV-PLUS compiler.
The system must include
the FORTRAN IV-PLUS Object Module Library (OLB) and Object Time
System (OTS) for this qualifier to work.
Therefore, your system
or library UFD must include the following files:
F4POTS.OLB
F4P.TSK
Please note
FORTRAN-77.

that

FORTRAN

IV-PLUS

has

been

superseded

equivalent

compiler

/[NO]F77
Specifies the FORTRAN-77 compiler.
/F4P.

/NOF77 is the

/[NO]CHECK
The /CHECK qualifier specifies that you wish the
check that all array references are within bounds.
The default is /NOCHECK.
This qualifier is for FORTRAN IV-PLUS and FORTRAN-77.
/CODE:arg
EAE
EIS
FIS
THREADED
The /CODE qualifier specifies that the code
has
certain
characteristics.
EAE means the code uses the Extended Arithmetic
Element.
EIS means that the code uses the Extended
Instruction
Set.
FIS means the code uses the Floating Instruction Set;
FIS
also includes EIS.
THREADED means the code is threaded.
The /CODE qualifier is for FORTRAN IV only.

6-15

PROGRAM DEVELOPMENT

FORTRAN {Cont.)
/CONTINUATIONS:n
The /CONTINUATIONS qualifier specifies the maximum number of
continuation lines permitted in the code.
The value of n can be
from 0 through 99.
The default is 5.
The /CONTINUATIONS
FORTRAN-77.

qualifier

for

FORTRAN

IV-PLUS

and

/[NO]DLINES
The /DLINES qua.Llr1er specifies that lines with a
"D" character
in column 1 are to be compiled.
The default is /NODLINES,
meaning these lines are treated as comment lines.
Use this
feature for debugging.
The /DLINES qualifier is for FORTRAN IV-PLUS and FORTRAN-77.
/[NO]EXTEND_SOURCE
The /EXTEND SOURCE qualifier specifies that you wish the compiler
to accept more than 72 columns of source input for each line.
The default is /NOEXTEND SOURCE, meaning the compiler reads only
columns 1 through 72 and-treats lines after that as comments.
The /EXTEND_SOURCE qualifier is for FORTRAN IV only.
/IDENTIFICATION
The /IDENTIFICATION qualifier causes the compiler to
identification and version number on your terminal.

its

/[NO]I4
The /I4
integer
causes a
given an

qualifier causes a
two-word default allocation for
variables.
The default is /NOI4, meaning the compiler
single-word allocation for
any integer variables not
explicit length specification.

/[NO]LINE_NUMBERS
The /LINE NUMBERS qualifier specifies that you wish the compiler
to
include
Internal Sequence Numbers.
Although these numbers
create more object code and increase program execution time, they
inform you which line caused your program to err, should it err.
The default is /NOLINE_NUMBERS.
The /LINE_NUMBERS qualifier is for FORTRAN IV only.
/[NO]LIST[:filespec]
Specifies whether a compiler listing should be generated.
The
default is /NOLIST, meaning no compiler listing is generated.
If you do not supply a file specification for this qualifier, the
listing has a file name derived from the name of the first source
file in the FORTRAN command with the file type .LST.
If you wish
the listing to have a different name, supply the name as an
argument to the /LIST qualifier.
If you do supply a
name,
the
listing file appears in your directory but is not printed on the
line printer.
6-16

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
The /LIST qualifier behaves in a different manner depending on
whether
it
is given as a command qualifier or a filespec
qualifier.
If /LIST is used as a command qualifier, the listing
file is placed in your directory and printed on the line printer.
If /LIST is used as a
filespec qualifier,
the listing file
appears in your directory but is not printed on the line printer.
If /LIST is used as a filespec qualifier, the listing file takes
the name of that file.
The /MACHINE CODE, /MAP, and /SOURCE, qualifiers all
contents of the compiler listing file.

affect

the

/[NO]MACHINE_CODE
The /MACHINE CODE qualifier specifies that you wish the compiler
listing to -include binary machine code and diagnostics.
The
default is /NOMACHINE_CODE.
/MACHINE CODE implies /LIST.
You do not need to include the
/LIST qualifier unless you wish to use it to establish a name for
the listing file different from any of the file names included in
the compilation.
The /MACHINE CODE qualifier behaves in a different
manner
depending on whether
it is given as a command qualifier or a
filespec qualifier.
If /MACHINE CODE is used as a command
qualifier,
the listing file
is- placed in your directory and
printed on the line printer.
If /MACHINE CODE is used as a
filespec qualifier,
the listing file appears in your directory
but is not printed on the line printer.
If /MACHINE CODE is used
as a filespec qualifier, the listing file takes the-name of that
file.
/[NO]MAP
The /MAP qualifier specifies that you wish the
to include a storage map and diagnostics.

compiler

listing

/MAP implies /LIST.
You do not need to include the /LIST
qualifier unless you wish to use it to establish a name for the
listing file different from any of the file names included in the
compilation.
The /MAP qualifier behaves in a different manner depending on
whether it is given as a command qualifier or a filespec
qualifier.
If /MAP is used as a command qualifier,
the listing
file is placed in your directory and printed on the line printer.
If /MAP is used as a filespec qualifier, the listing file appears
in your directory but is not printed on the line printer.
If
/MAP is used as a filespec qualifier, the listing file takes the
name of that file.
/[NO]OBJECT[:filespec]
Determines whether or not an object module is generated by the
compiler.
The default is /OBJECT, which does create a module.
The default name of the object file created by FORTRAN is the
name of the last-named source file with the file type .OBJ.
If
you wish the object file to have a different name, supply the
name as an argument to the /OBJECT qualifier.

6-17

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
/NOOBJECT specifies that no object module is created.
You can
use the /NOOBJECT qualifier to get a compiler listing file to
check for errors without generating object code.
_/SMARE;AB,~E,'
'

/SOURCE
The /SOURCE qualifier specifies that
listing to include the source code.

you

wish

the

compiler

/SOURCE implies /LIST.
You do not need to include the /LIST
qualifier unless you wish to use it to establish a name for the
listing file different from any of the file names included in the
compilation.
The /SOURCE qualifier behaves in a different manner depending on
whether
it is given as a command qualifier or a filespec
qualifier.
If /SOURCE is used as a command qualifier,
the
listing file is placed in ~our directory and printed on the line
printer.
If /SOURCE is used as a filespec qualifier, the listing
file appear::.:; ..1.Il your: uir12ctory but is not p:;:inted vu the lir.e
printer.
If /SOURCE is used as a filespec qualifier, the listing
file takes the name of that file.
/[NO]STANDARD:arg
ALL
NONE
SOURCE
SYNTAX
The /STANDARD qualifier directs the compiler to look in your
source code for extensions to ANSI standard (X3.9-1978) FORTRAN
at the full-language level.
If the compiler finds extensions, it
flags them and produces informational diagnostics.
Although PDP-11 FORTRAN-77 conforms to the ANSI FORTRAN standard
at the subset level, the compiler flags only those features that
are extensions to the full
language.
See Appendix G of the
PDP-11 FORTRAN-77 User's Guide for a list of flagged extensions.
The ALL argument produces
detected extensions.

informational

diagnostics

for

all

The SOURCE argument produces informational diagnostics
lowercase letters and tab characters in the source code.

for

The NONE argument produces no informational diagnostics.

The SYNTAX argument is the same as /STANDARD with no argument.
The default is /NOSTANDARD.
The /[NO]STANDARD qualifier is for FORTRAN-77 only.
6-18

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
/[NO]TRACEBACK:arg
ALL
BLOCKS
LINES
NAMES
NONE
/TRACEBACK controls the amount of extra code included in the
compiled output for use by the OTS during error traceback.
This
code is used in producing diagnostic information
and
in
identifying which statement in the FORTRAN source program caused
an error condition to be detected during execution.
This
qualifier is for FORTRAN IV-PLUS and FORTRAN-77.
The ALL argument states that error traceback information is to be
compiled for all source statements, and function and subroutine
entries.
The LINES argument is the same as ALL.
The BLOCKS argument states that traceback information is to be
compiled
for
subroutine and function entries and initial
statements in sequences called blocks. This is the default.
The NAMES argument states that traceback information
compiled only for subroutine and function entries.

The NONE argument states that no traceback information is
produced.

/USING:usercompiler
Invokes a FORTRAN compiler other than one of the DIGITAL-supplied
compilers.
/[NO]VECTORS
The /VECTORS qualifier specifies that you wish vectored arrays.
This increases the size of object modules but decreases execution
time. The default is /VECTORS.
The /VECTORS qualifier is for FORTRAN IV only.
/[NO] WARNINGS
The /WARNINGS qualifier specifies that you wish the
issue warning diagnostics.
This is the default.

compiler

The /WARNINGS qualifier is for FORTRAN IV only.
/WORK_FILES:n
The /WORK_FILES qualifier specifies the number of temporary
on-disk files you wish used during the compilation. n can be
from 0 through 3; the default is 2.
Increasing the number of
work files
increases the maximum possible size of your program
but decreases the speed of compilation.

6-19

PROGRAM DEVELOPMENT

FORTRAN (Cont.)
Examples

>FORTRAN
File<s>'?

CODY

This example compiles the FORTRAN IV source
the relocatable object module CODY.OBJ.

file

CODY.FTN

into

file

CODY.FTN

into

>FORH:~1N/F77
File(s)'?

CODY

This example compiles the FORTRAN-77 source
the relocatable object module CODY.OBJ.

>FOR SAX,CODY,GERARD
The FORTRAN IV compiler compiles the source files SAX.FTN,
CODY.FTN, and GERARD.FTN into a relocatable object module named
SAX.OBJ.
The commas (,) cause the three source files to be
concatenated.

>FOR/LIST CODY
This example creates an object module, CODY.OBJ, and a compiler
listing, CODY.LST, from a source file, CODY.FTN.
The listing
file and object module appear: in you.L UFD ci(HJ the listing file is
printed on the line printer.

>FOR/LIST:CODY GERARD
This example creates the object module GERARD.OBJ and a compiler
listing, CODY.LST, from the source file, GERARD.FTN. Both output
files appear in your UFD, but the listing file is not printed on
the line printer. To print this file, issue a PRINT command.

>FOR/LIST:TI:

CASSADY

This example creates the file CASSADY.OBJ and prints the assembly
listing on your terminal.
No listing file is printed on the line
printer or retained in your directory.

>FOR/F77/0BJ:CASSADY STELLA
The FORTRAN-77 compiler creates an
from the source file STELLA.FTN.

object

module,

CASSADY.OBJ,

>FORTRAN/LIST CODY,LOWELL
This command creates the object module CODY.OBJ and the listing
file CODY.LST using the files CODY.FTN and LOWELL.FTN as input.
CODY.LST is printed on the line printer. See the next example.

6-20

PROGRAM DEVELOPMENT

COBOL
>FORTRAN CODY,LOWELL/LISl
This command creates the object module CODY.OBJ and the listing
file LOWELL.LST using the files CODY.FTN and LOWELL.FTN as input.
LOWELL.LST is not printed on the line printer.

>FORTRAN DHARMA1MEXICO/MAP
This command creates the object module DHARMA.OBJ and the listing
file MEXICO.LST using the file DHARMA.FTN and MEXICO.FTN as
input. The listing file includes a storage map and diagnostics.
The listing file is not printed on the line printer.
Notes

It is not uncommon for
installations to have more than one
FORTRAN compiler available.
Since the default file type is the
same for all DIGITAL FORTRAN compilers, you will have to use some
care in differentiating source files for the different compilers.
See the FORTRAN documentation supplied with your system.

6.2.4

COBOL

COBOL is a language widely
used
for
business
applications.
RSX-llM/M-PLUS systems support both COBOL-81 and PDP-11 COBOL.
Since
~nese products are optional software, your
system may include one,
both, or neither of these compilers.
Both the COBOL-81 and PDP-11 COBOL compilers convert source files
written in the COBOL language to relocatable object modules.
The Task
Builder uses these modules to produce task-image files that can be run
on your system (see Section 6.4).
The next two sections discuss how to invoke each COBOL compiler.
For
COBOL-81, use the COBOL command (see Section 6.2.4.1).
For PDP-11
COBOL, use the COBOL/Cll command
(see Section 6.2.4.3).
Section
6.2.4.2 gives examples for the COBOL-81 compiler. Section 6.2.4.4
gives examples for the COBOL/Cll compiler.

6.2.4.1

COBOL-81

This section discusses the command line format and compile-time
qualifiers
for
COBOL-81.
Normal defaults for qualifiers are
indicated. However, these defaults will not apply to your system if
your system manager changed the default settings when installing the
compiler.
If you are using a compiler that has not been supplied by DIGITAL,
specify the COBOL command with the /USING qualifier.
The format is:
COBOL/USING:usercompiler

6-21

PROGRAM DEVELOPMENT

COBOL (Cont.)
Format
COBOL[/qualifier[s]]

filespec

Command Qualifiers
/[NO]ANSI FORMAT
/[NO]CHECK:arg
[NO] BOUNDS
[NO] PERFORM
ALL
NONE
/CODE: [NO]CIS
/[NO]CROSS REFERENCE
/[NO]DEBUG/[NO] DIAGNOSTICS [ :filespec]
/[NO]LIST[:filespec]
/NAMES:xx
/[NO]OBJECT[:filespec]
/[NO]OVERLAY DESCRIPTION
/[NO]SHOW:[NO]MAP
/[NO]SKELETON
/[NO]SUBPROGRAM
/TEMPORARY:device
/[NO]TRUNCATE
/USING:usercompiler
/[NO]WARNINGS: [NO] INFORMATIONAL

Parameter
filespec
Specifies the source file to be input to the COBOL-81 compiler.
File input to the COBOL-81 compiler must contain COBOL source
code.
File specifications must have file names.
The default
file type is .CBL.
Command Qualifiers
/[NO]ANSI_FORMAT
The /ANSI FORMAT qualifier specifies that the source file
is
in
conventional
(or
ANSI)
format.
Conventional format has
SO-character lines with Area A beginning in character position 8.
The /NOANSI FORMAT qualifier specifies that the source file is in
terminal format, a DIGITAL-specified format that permits variable
length lines with Area A beginning in character position 1.
The default is /NOANSI_FORMAT.

6-22

PROGRAM DEVELOPMENT

COBOL {Cont.)
/[NO]CHECK:arg
[NO] BOUNDS
[NO] PERFORM
ALL
NONE
The /CHECK and /CHECK:ALL qualifiers are equivalent -- both to
each other,
and also to /CHECK:BOUNDS and /CHECK:PERFORM in
combination.
They add object code that checks the ranges of
subscripts, indexes, and nested perform statements at run time.
The /CHECK:BOUNDS qualifier compares subscript and
index ranges
at run time against the ranges defined by corresponding OCCURS
clauses.
If any range is exceeded during program execution,
COBOL-81 issues an error message.
The /CHECK:PERFORM qualifier determines whether or not your
program's PERFORM statements are nested properly (if nested at
all) •
If COBOL-81 detects improper nesting during program
execution, it issues an error message.
The /NOCHECK and /CHECK:NONE qualifiers are equivalent -- both to
each other,
and also to /CHECK:NOBOUNDS and /CHECK:NOPERFORM in
combination.
They suppress all range checking.
The /CHECK:NOBOUNDS qualifier suppresses range checking only
subscripts and indexes.

for

The /CHECK:NOPERFORM qualifier suppresses range checking only for
nested PERFORM statements.
The qualifiers that suppress range checking reduce task size
improve program performance.

and

The default is /CHECK (/CHECK: ALL).
/CODE: [NO]CIS
The /CODE:CIS qualifier tells the compiler to use CIS (Commercial
Instruction Set) in the object code it produces.
The /CODE:NOCIS qualifier tells the compiler not to use CIS.
These qualifiers override the default for your system.
They are
used to develop programs that will execute on a different system
than the one used for program development.
For example, if your
system has CIS, you use /CODE:NOCIS to compile a program that
will run on a system without CIS~
If your system has the Commercial Instruction Set installed,
the
default is /CODE:CIS.
Otherwise, the default is /CODE:NOCIS.

6-23

PROGRAM DEVELOPMENT

COBOL (Cont.)
/[NO]CROSS_REFERENCE
The /CROSS REFERENCE qualifier causes the compiler to produce a
list file and to add two cross-reference tables to the end of the
list file:
one for data-names and one for procedure-names.
In
each table,
the names you use in your COBOL program are listed
alphabetically.
Opposite each name is a list of every line
number in which that name occurs.
A "D" after a number indicates
the line in which you define the name.
An asterisk (*)
after a
line number
indicates a destructive reference, such as a value
assignment to a data-name.
The /NOCROSS REFERENCE qualifier
cross-reference tables.

suppresses

production

the

The default is /NOCROSS_REFERENCE.
/[NO]DEBUG
The /DEBUG qualifier indicates that you plan to include the
COBOL-81 Symbolic Debugger
in your task image.
To support the
Symbolic Debugger, the compiler generates symbol information in
the object module for all data-names and procedure-names in your
program.
If you include the Symbolic Debugger in your program, you must
also use the /DEBUG qualifier to the LINK/C81 command (see
Sec t i on 6 • 4 • 3 ) •
The /NODEBUG
qualifier
suppresses
information in the object module.

generation

symbol

The default is /NODEBUG.
/[NO]DIAGNOSTICS[:filespec]
The /DIAGNOSTICS qualifier creates a diagnostics file that
contains the compiler diagnostic summary.
If you do not append a
file specification, the diagnostics file has the same file name
as your source file, and the file type .DIA.
The /NODIAGNOSTICS
diagnostics file.

qualifier

suppresses

the

creation

The default is /NODIAGNOSTICS.
/[NO]LIST[:filespec]
The /LIST qualifier produces a list file which contains both the
complete source code and any diagnostic messages.
If you do not
append a file specification, the list file has the same file name
as the source file and has the file type .LST.
The /NOLIST qualifier suppresses the production of a list file.
The default is /NOLIST.

6-24

PROGRAM DEVELOPMENT

COBOL (Cont.)
/NAMES: xx
The /NAMES:xx qualifier tells the compiler to use the two
alphanumeric characters you specify as the PSECT kernel for your
program.
You use this qualifier to ensure unique identification
for PSECT kernels when your task image uses both subprograms and
segmentation.
/[NO]OBJECT[:filespec]
The /OBJECT qualifier produces an object module.
If you do not
append a file specification to the qualifier, the object module
has the same file name as the source, and the file type .OBJ.
The /NOOBJECT qualifier suppresses production of an object module
and its associated skeleton ODL file.
(See the description of
/[NO] SKELETON.)
The default is /OBJECT.
/[NO]OVERLAY_DESCRIPTION
The /OVERLAY DESCRIPTION qualifier produces two
files -- an
indirect command file and an Overlay Descriptor Language file.
The indirect command file has the same file name as the source
and the file type .CMD.
It can be input to the Task Builder to
create the task image.
The Overlay Descriptor Language file has the same file name as
the source and the file type .ODL.
It contains pointers to
certain support routines that must be included in your task image
(for example, system support for file input/output).
If you plan to use the LINK/C81 command to task-build your
program, do not use the /OVERLAY DESCRIPTION qualifier.
LINK/C81
also creates a .CMD and an .ODL file, and cannot reference the
.CMD and .ODL files created during program compilation.
The /NOOVERLAY DESCRIPTION qualifier suppresses
.CMD and .ODL files during program compilation.

production

The default is /NOOVERLAY_DESCRIPTION.
/[NO] SHOW: [NO]MAP
The /SHOW and /SHOW:MAP qualifiers are equivalent.
They cause
the compiler to produce a list file and to append two offset maps
to the list file.
One offset map refers to the Data Division and
one to the Procedure Division.
The compiler provides these maps
for use with ODT
(the On-Line Debugging Tool).
Consult the
IAS/RSX-11 ODT Reference Manual for more information.
The /NOSHOW and /SHOW:NOMAP qualifiers
suppress production of the offset maps.
The default is /NOSHOW (/SHOW:NOMAP).

6-25

are

equivalent.

They

PROGRAM DEVELOPMENT

COBOL (Cont.)
/[NO]SKELETON
The /SKELETON qualifier produces a skeleton ODL file, which
specifies the overlay structure for the object module. This file
has the same file name as the source and the file type .SKL.
You cannot use the /SKELETON qualifier to override the /NOOBJECT
qualifier.
That is, an .SKL file cannot be produced when the
.OBJ file is suppressed.
The /NOSKELETON qualifier suppresses production of the .SKL file.
You cannot use the /NOSKELETON qualifier if you plan
to
task-build your program with the LINK/C81 command (see Section
6.4.3).
LINK/C81 assumes the presence of the .SKL
file.
Although the .SKL file is not strictly necessary for all
programs, DIGITAL does not recommend that you suppress its
production
unless
you
are
familiar
with
task-building
alternatives to LINK/C81.
The default is /SKELETON.
/[NO]SUBPROGRAM
The /SUBPROGRAM qualifier tells the compiler to treat the source
file as a subprogram.
You should use this qualifier only if the
subprogram does not use parameters from the main program;
that
is, if it does not contain the Procedure Division USING header.
The /NOSUBPROGRAM qualifier
source as a main program.

tells

the

compiler

treat

the

The default is /NOSUBPROGRAM.
/TEMPORARY:device
The /TEMPORARY qualifier tells the compiler to store
the
temporary work files it uses during program compilation on the
device you specify. Since the default device is the system disk
(SY:), this qualifier is useful if there is little system disk
space available.
/[NO]TRUNCATE
The /TRUNCATE qualifier tells the compiler to perform decimal
truncation on the values of COMP data items. With decimal
truncation, the maximum value the data item can contain depends
on the item's PICTURE character-string.
The /NOTRUNCATE qualifier tells the compiler to perform binary
truncation on the values of COMP data items.
With binary
truncation, the maximum value a COMP item can contain depends on
its storage allocation.
The default is /NOTRUNCATE.

6-26

PROGRAM DEVELOPMENT

COBOL/C11
/[NO]WARNINGS: [NO] INFORMATIONAL
The /WARNINGS
and
/WARNINGS:INFORMATIONAL
qualifiers
are
equivalent.
They cause the compiler to issue informational,
warning, and fatal diagnostics.
The /NOWARNINGS and /WARNINGS:NOINFORMAT!ONAL qualifiers are
equivalent.
They suppress production of informational, warning,
and fatal diagnostics.
The default is /WARNINGS (/WARNINGS: INFORMATIONAL).

6.2.4.2

COBOL-81 EXAMPLES

>COBOL
File(s)'?

DULUOZ

This example compiles the COBOL-81 source
relocatable object module DULUOZ.OBJ.

file

DULUOZ.CBL

into

the

>COBOL/LIST!TI! SAX
This example creates the object file SAX.OBJ from the COBOL-81 source
file SAX.CBL and prints the compiler listing on your terminal.
No
listing file is printed on the line printer or retained
in your
current UFO.
For more detailed
information on compiling your COBOL-81
program, refer to the COBOL-81 RSX-llM/M-PLUS User's Guide.

6.2.4.3

source

PDP-11 COBOL

This section discusses the command line format and compile-time
qualifiers for PDP-11 COBOL plus gives you the MCR equivalents to the
DCL qualifiers.
The defaults for the qualifiers are included
in the
qualifier descriptions.
You can override these defaults only in the
PDP-11 COBOL compiler command line.
Format

COBOL/Cll[/qualifier[s]]

filespec

Command Qualifiers

DCL Mode

MCR Mode Equivalent

/ANSI FORMAT
/NO ANSI FORMAT

/CVF

/CHECK
/NOCHECK
/CM6
/NOCM6

/-BOU
/CM6

6-27

PROGRAM DEVELOPMENT

COBOL/C11 (Cont.)
/CROSSREFERENCE
/NOCROSSREFERENCE

/CREF
(default listing)

/LARGESYMBOLTABLE:n

/SYM:n

/LIST[:filespec]
/NOLI ST

(default listing)

/NAMES:xx

/KER:xx

/NEST:n

/PFM:n

/OBJECT[:filespec]
/NOOBJECT

,=T

/OVERLAY
/NOOVERLAY
/POOLLITERALS
/NOPOOLLITERALS

/OV

/-PLT

/READONLY
/NOREADONLY

, /RO

/SHOW:COPYLIST
/NOSHOW:COPYLIST

(default listing)
/NL

/SHOW: MAP
/NOSHOW:MAP

/MAP
(default listing)

/SHOW:VERBLOCATION
/NOSHOW:VERBLOCATION

/OBJ
(default listing)

/SKELETON
/NOSKELETON

/-SKL

/SUBPROGRAM
/NOSUBPROGRAM

/SUB

/TEMP:dev

/TMP:dv

/WARNINGS
/NOWARNINGS

/ERR:l
/ERR:2

Parameter
f ilespec
Specifies a source file to be input to the PDP-11 COBOL compiler.
File input to the PDP-11 COBOL compiler must contain COBOL source
code.
File specifications must have file names.
The default
file type is .CBL.

Command Qualifiers
/[NO]ANSI_FORMAT
The /~NSI FORMAT qualifier specifies that the source file
is in
conventional format:
80-character lines with Area A beginning in
character position 8.
The default is /NOANSI_FORMAT.
6-28

PROGRAM DEVELOPMENT

COBOL/C11 (Cont.)
/[NO]CHECK
The /CHECK qualifier specifies that the code generated will check
that subscripts and indexes are in their legal bounds when they
are used.
The /NOCHECK qualifier suppresses this checking, which increases
execution speed for programs with a large number of subscripted
or indexed references.
The default is /CHECK.
/[NO]CM6
The /CM6 qualifier specifies that you wish the compiler to change
all COMPUTATIONAL references to COMPUTATIONAL-6.
The default is
/NOCM6.
/[NO]CROSS_REFERENCE
The /CROSS REFERENCE qualifier
cross-reference listing to be
file.

specifies that you
wish
a
included as part of the listing

/CROSS REFERENCE implies /LIST.
You do not need to include the
/LIST qualifier unless you wish to use it to establish a name for
the listing file different from the source file.
The /CROSS REFERENCE qualifier leaves the listing
current directory.

file

your

/LARGE_SYMBOL_TABLE[:n]
The /LARGE SYMBOL TABLE qualifier specifies that you wish the
compiler to obtain more symbol-table space, where n is a number
from 1 through 4.
The default is 1. Here are the results of
using this qualifier:
n

1
2
3
4

Maximum
Data Names
{approximate)
761
1021
1531
2039

Maximum
Procedure Names
(approximate)
761
1021
1531
2039

/[NO]LIST[:filespec]
Specifies whether a compiler listing should be generated.
The
default is /NOLIST, meaning no compiler listing is generated.
If you do not supply a file specification for this qualifier, the
listing has a file name derived from the name of the source file,
with the file type .LST.
If you wish the listing to have a
different name, supply the name as an argument to the /LIST
qualifier.
If your command line includes the /CROSS REFERENCE
/LIST is implied and need not be specified.

qualifier,

If your command line includes listing-control arguments to either
/SHOW or /NOSHOW, /LIST is implied and need not be specified.
6-29

PROGRAM DEVELOPMENT

COBOL/C11 (Cont.)
The only time you need to use /LIST with /CROSS REFERENCE or
/[NO]SHOW is when you wish to give the listing fTle a filespec
other than the default.
The listing file appears in your
directory.
/NAMES:xx
The /NAMES qualifier specifies that you wish the compiler to
generate program section names that use the 2-character kernel,
xx,
to make them unique for this compilation.
xx is
a
2-character text string that may include the numerals 0 through 9
and the letters A through z.
/NEST:n
The /NEST qualifier allows you to specify the maximum number of
nested PERFORM statements in the program.
The compiler generates
a nested PERFORM stack equal in depth to the decimal number n.
The default is 10.
/[NO]OBJECT[:filespec]
The /NOOBJECT qualifier specifies that you do not wish to create
an object file.
Use this qualifier if you wish only to check for
errors or generate a listing.
/OBJECT is the default and specifies that you wish to create an
object file.
The optional filespec argument enables you to give
the object file a name different from that of the source file.
/[NO]OVERLAY
The /OVERLAY qualifier specifies that you wish the compiler to
make all procedural program sections overlayable. This is done
by keeping procedural statements out of the root section.
/NOOVERLAY is the default.
/[NO]POOL_LITERALS
The /POOL LITERALS qualifier specifies that you wish the compiler
to pool literals automatically to minimize the memory required to
store them.
This is the default. Since pooling literals slows
down
the
speed
of
the
compilation,
you
can specify
/NOPOOL_LITERALS to speed it up.
/[NO]READ_ONLY
The /READ ONLY qualifier specifies that you wish the compiler to
generate -a read-only program section for the procedure division
object module.
The default is /NOREAD ONLY, which means these
object modules are read/write.
/[NO]SHOW: (arg[,s])
COPY LIST
MAP

VERB LOCATION
The /SHOW and /NOSHOW qualifiers specify elements you wish
If you specify
included in or excluded from the listing file.

6-30

PROGRAM DEVELOPMENT

COBOL/C11 (Cont.)
only a single argument, the parentheses are not
command line can include both /SHOW and /NOSHOW.

needed.

/SHOW implies /LIST, but if you wish the listing file to
name other than the default, you must still use /LIST.

Your
have

The qualifier /NOSHOW:COPY LIST specifies that you do not wish
the listing file to include source statements copied from a
library file.
The resulting listing includes only the COPY
statement.
The default is /SHOW:COPY_LIST.
The /SHOW:MAP qualifier specifies that you wish the listing to
include any external subprograms that were referenced plus the
following special maps:
•

Data Division

•

Procedure Division

•

Data and Control Program Sections

•

OTS Routine References

•

Segmentation

The default is /NOSHOW:MAP.
The /SHOW:VERB LOCATION qualifier specifies that you wish the
listing file to include the object location of the code for each
program verb.
The information is listed on the line preceding
The
default
is
the
source
statement
it
describes.
/NOSHOW:VERB_LOCATION.
/[NO]SKELETON
The /SKELETON qualifier specifies that you wish the compiler to
create a skeleton Overlay Description Language (.SKL) file.
This
is the default operation. The file is named after the file named
in the COBOL/Cll command, with the file type .SKL.
If you do not
wish the .SKL file created, specify /NOSKELETON.
/[NO]SUBPROGRAM
The /SUBPROGRAM qualifier tells the compiler to treat the source
file as a subprogram. You should use this qualifier only if the
subprogram does not use parameters from the main program;
that
is, if it does not contain the Procedure Division USING header.
The /NOSUBPROGRAM is the default and
treat the source as a main program.

means

the

compiler

will

/TEMP:dev
The /TEMP qualifier tells the compiler to store the temporary
work files
it uses during program compilation on the device you
specify. Since the default is the system disk
(SY),
this
qualifier is useful
if there is little system disk space
available. Do not specify a colon (:) as a delimiter after dev.

6-31

PROGRAM DEVELOPMENT

CORAL 66
/WARNINGS
The /WARNINGS qualifier specifies that you wish both warning
fatal diagnostics printed in the listing.
See /NOWARNINGS.

and

The default, without either /WARNING or /NOWARNING specified,
to print informational, warning, and fatal diagnostics.

/NOWARNINGS
The /NOWARNINGS qualifier specifies
diagnostics printed in the listing.

that you wish
See /WARNINGS.

only

fatal

Notes

See the PDP-11 COBOL documentation supplied with your system
further information.

6.2.4.4

for ·

COBOL/Cl! Examples

>COBOL/Cll LEDlJ>'.
This example compiles the COBOL/Cll source
relocatable object module LEDUX.OBJ.

file

LEDUX.CBL

into

the

>COBOL/C11/LIST MARDOU
This example creates an object module, MARDOU.OBJ, and a COBOL-11
compiler listing, MARDOU.LST, both of which appear in your current
UFD.

>COBOL/C11/l.IST!MARDOU LEDUX
This example creates the object module LEDUX.OBJ and a compiler
listing, MARDOU.LST, from the COBOL-11 source file LEDUX.CBL.
Both of
the output files appear in your current UFD.

>COBOL/C11/LIST:GALLOWAY/SHOW:MAP
This example creates an object module called GALLOWAY.OBJ and a
listing file called GALLOWAY.LST.
The listing file includes the
special map with the data divisions, procedure map, segmentation map,
program
sections, and so forth,
as described under the /SHOW
qualifier.

6.2.5

CORAL 66

RSX-iiM/M-PLUS systems support CORAL 66, a high-ievei block-structured
programming language.
CORAL stands for Computer On-Line Real-Time
Applications Language.

6-32

PROGRAM DEVELOPMENT

CORAL 66 {Cont.)
CORAL 66 is the standard general-purpose language prescribed by the
British Government for real-time and process-control applications.
It
is defined in BS 5905, British Standard Specification for Computer
Programming Language CORAL 66.
CORAL 66 is designed to replace assembly-level programming in modern
industrial and commercial applications.
It is used for long-life
products where ease of maintenance and flexibility are required.
Because this compiler is optional software, your system may not
include it.
Format
CORAL[/qualifier[s]] filespec[,s]
Command Qualifiers
/[NO]CHECK
/CODE:arg
EIS
FIS
FPP
PIC
(EIS,PIC)
(FIS,PIC)
(FPP,PIC)
/[NO]EXTEND SOURCE
/[NO]LIST[:filespec]
/[NO]MACHINE CODE
/NAMES:x
/[NO]OBJECT[:filespec]
/[NO]OPTIMIZE[:LEVEL:n]
/READ ONLY[:arg]
ALL
NONE
PURE DATA
/[NO]SHOW[:(arg[~s])]

ALL
EXPANSIONS
NONE
OVERRIDE
SOURCE
STATISTICS
SYMBOLS
/[NO]STANDARD
/TEST [: n]
/[NO]TRACEBACK
/WIDTH: n
Parameter
filespec[,s]
Specifies the file or files to be compiled.
If you
than one file, separate the filespecs with commas.

name

Files input to the CORAL 66 compiler must contain CORAL 66 source
code. The default file type is .COR.

6-33

PROGRAM DEVELOPMENT

CORA~ 66 (Cont.)

Command Qualifiers
/[NO]CHECK
The /CHECK qualifier specifies that the code generated will check
that all subscripts used in array and switch references are
within bounds.
The default is /NOCHECK.
/CODE:arg
EIS
FIS
FPP
PIC
The /CODE qualifier allows you to choose (at compile time)
the
instruction set for which the code is to be generated regardless
of which machine is used to compile the source program.
EIS means that the code uses the Extended Instruction
default is /CODE:EIS.

Set.

The

FIS means that the code uses the Floating Instruction Set.
FPP means that the code uses the Floating Point Processor.
NOTE

You cannot specify any combinations of EIS, FIS, and
codes.

FPP

PIC means that the code is position-independent.
With the
qualifier set to /CODE:PIC,
a SWITCH declaration in the CORAL
source is compiled as a list of relative jumps in instruction
space.
If you specify /CODE:NOPIC
(the normal default), a SWITCH
declaration is compiled as a list of addresses in data space.
If you want to GOTO a switch that has been declared in COMMON and
any target switch label is in an overlaid segment of your task,
you must use /CODE:PIC for the Autoload mechanism to work.
As with other qualifiers, the supplied default, /CODE:NOPIC,
be changed when the CORAL 66 compiler is installed.

may

You can combine EIS, FIS, and FPP codes with PIC as follows:
/CODE: (EIS,PIC)
/CODE: (FIS,PIC)
/CODE: (PPP,PIC)
/[NO]EXTEND_SOURCE
The /NOEXTEND SOURCE qualifier causes

only

the

fi~st

process

72 characters of source input per line.

This is

6-34

the

compiler

PROGRAM DEVELOPMENT

CORAL 66 (Cont.)
usea it your input is on punched cards and the
sequencing information in columns 73 through 80.

cards

contain

The default is /EXTEND SOURCE, meaning that all characters in
input line are processed.

NOTE
The compiler treats a TAB as a single character.
/[NO]LIST[:filespec]
The /LIST qualifier allows you to specify whether a compiler
The default is /NOLIST, meaning no
listing should be generated.
compiler listing is generated.
If you do not supply a file specification for this qualifier, the
listing has a file name derived from the name of the first source
file in the CORAL command and the file type .LST.
If you want
the listing to have a different name, supply the name as an
argument to the /LIST qualifier.
If you do supply a name,
the
listing file appears in your directory but is not printed on the
line printer.
The /LIST qualifier behaves in a different manner depending on
whether it is given as a command qualifier or a filespec
qualifier.
If /LIST is used as a command qualifier with no
filespec,
the listing file
is placed
in your directory and
printed on the line printer.
If /LIST is used as a
filespec
qualifier,
the listing file appears in your directory but is not
printed on the line printer.
If /LIST is used as a
filespec
qualifier, the listing file takes the name of that file.
/[NO]MACHINE_CODE
The /MACHINE CODE qualifier specifies that you wish the compiler
listing
to- include a
representation of the machine code
generated.
The default is /NOMACHINE_CODE.
/MACHINE CODE produces a listing of the object code produced by
the compiler, correlated with the source file and line number.
The first octal number is the offset of the instruction in the
current program section (segment) • This is followed by an octal
representation of the internal code format and the instruction in
a format similar to MACR0-11.
/MACHINE CODE implies /LIST.
You do not need to use the /LIST
qualifier unless you wish to specify a name for the listing file
that is different from any of the names included in the
compilation.
The /MACHINE CODE qualifier behaves in a different
manner
depending on- whether it is given as a command qualifier or a
filespec qualifier.
If /MACHINE CODE is used as a command
qualifier,
the listing file
is- placed
in your directory and
printed on the line printer.
If /MACHINE CODE is used as a
filespec qualifier, the listing file takes tne name of that file.
The listing file appears in your directory but is not printed on
the line printer.

6-35

PROGRAM DEVELOPMENT

CORAL 66 (Cont.)
/NAMES:x
The
/NAMES
qualifier
causes
the
first
character
of
compiler-generated program-section names to be the character 'x'
in order to make them unique for this compilation.
If you do not
specify /NAMES, compiler-generated program-section names start
with the character 'S'.
/[NO]OBJECT[:filespec]
This qualifier allows you to specify whether or not the compiler
must generate an object module.
The default is /OBJECTr which
creates an object module.
The default name of the object file
created by CORAL 66 is the name of the last-named source file and
the file type .OBJ.
If you wish the object file to have a
different name,
supply the name as an argument to the /OBJECT
qualifier.
/NOOBJECT specifies that no object module is created.
You can
use the /NOOBJECT qualifier
to get a compiler listing file to
check for errors without generating object code.
/[NO]OPTIMIZE[:LEVEL:n]
The /OPTIMIZE qualifier allows you to optimize the function of
CORAL 66 source programs.
The qualifier allows code generated by
the compiler to be replaced, where possible, by more efficient
code constructions.
/NOOPTIMIZE or /OPTIMIZE:LEVEL:O means no optimization occurs.
/OPTIMIZE or
/OPTIMIZE:LEVEL:l
allows
iterations.
The default is /OPTIMIZE.

three

optimization

/OPTIMIZE:LEVEL:2 allows as many iterations as necessary.
/RE AD ONLY [ : a r g ]
ALL
NONE
PURE DATA
The /READ ONLY qualifier allows you to alter
READ-WRITE attributes of program sections.

the

READ-ONLY

/READ ONLY:ALL creates pure data and instruction program sections
with -the READ-ONLY attribute and impure data program sections
with the READ-WRITE attribute.
/READ ONLY:NONE creates all program sections with the
attribute.

READ-WRITE

/READ ONLY:PURE DATA creates pure data program sections with the
READ-ONLY attrTbute and all other program sections with the
READ-WRITE attribute.
The default is /READ_ONLY:PURE_DATA.

6-36

PROGRAM DEVELOPMENT

CORAL 66 (Cont.)
/ [NO] SHOW [: ( arg [ , s] ) ]
ALL
EXPANSIONS
NONE
OVERRIDE
SOURCE
STATISTICS
SYMBOLS
The /SHOW and /NOSHOW qualifiers specify elements you wish
included in or excluded from the listing file.
If you specify
only a single argument, the parentheses are not needed.
Your
command line can include both /SHOW and /NOSHOW.
/SHOW implies /LIST, but if you wish the listing file to
name other than the default, you must still use /LIST.

have

/SHOW as a command qualifier causes the file to be printed on the
line printer. /SHOW as a filespec qualifier prevents the listing
file from being printed.
The default is /SHOW.
/SHOW:ALL is equivalent to:
/SHOW: (EXPANSIONS,OVERRIDE,SOURCE,STATISTICS,SYMBOLS)
The /SHOW:EXPANSIONS qualifier causes the compiler to produce a
source listing with all macros expanded.
Line numbers are not
incremented during macro expansions, so if an error occurs,
the
line number printed will refer to the source line in which the
macro was used.
The default is /SHOW:NOEXPANSIONS.
The /SHOW:NONE qualifier performs the same function as /NOSHOW.
The /SHOW:OVERRIDE qualifier overrides
code.
The default is /SHOW:NOOVERRIDE.

/NOLIST

the

source

The /SHOW:SOURCE qualifier causes the compiler to produce a
source listing.
The default width of the listed file is 132
characters but may be changed to another width by using the
/WIDTH qualifier.
Each listed line of the source file is
prefixed by the current file number and
line number.
When
several files are compiled, the line numbers restart with each
new file.
The listing may be made more readable by, for example,
including form feeds in the source at the start of each segment
or large procedure.
Each page is printed with a two-line
gives the following information:

header.

The

first

line

program name
compiler name and version
time and date at the start of compilation
page number
If a 'TITLE' statement has been processed,
the text in that
statement is printed on the second line.
The 'TITLE' text may be
up to 64 characters in length.
The /SHOW:NOSOURCE qualifier means a
produced.
The default is /SHOW:SOURCE.

6-37

source

listing

not

PROGRAM DEVELOPMENT

CORAL 66 {Cont.)
The /SHOW:STATISTICS qualifier causes the compiler to produce
statistics displaying information on the internal working of the
compiler.
The /SHOW:NOSTATISTICS qualifier suppresses
this
function.
The default is /SHOW:STATISTICS.
The /SHOW:SYMBOLS qualifier causes the compiler to print out data
and label maps,
sorted by symbol names in alphabetical order.
Where symbols declared in different contexts have identical
names,
these are further sorted into ascending file and line
number order.
The /SHOW:NOSYMBOLS qualifier means the compiler does not create
a listing of the symbol table.
The default is /SHOW:SYMBOLS.
/[NO]STANDARD
The /STANDARD qualifier highlights non-IECCA keywords in the
listing as warning messages.
(IECCA is an acronym for the Inter
Establishment Committee for Computer Applications, the body
responsible for approving computer hardware and software for
British military applications.)
For
example,
the
keyword
'INCLUDE' will generate a message of the following format:
Error 213 in File 2 Line 10 Character 1
Warning-Non-Standard Keyword
The /NOSTANDARD qualifier suppresses this function.
is /NOSTANDARD.

The

default

/TEST [: n]
The /TEST qualifier allows you to retain or omit declarations and
statements from a particular compilation without editing the
source text.
This qualifier is used
in conjunction with the
'TEST'
keyword.
You may specify any declarations or statements
in the source program as follows:
'TEST'

(x}

'INTEGER' VAR;

where x is any positive integer.
If you specify the /TEST[:n] qualifier, the compiler will process
all
'TEST'
(x}
statements where x is less than or equal to n.
Therefore, to ignore all 'TEST' statements, set /TEST:O or omit
the qualifier at compile time.
The default is /TEST:O.
/[NO]TRACEBACK
The /TRACEBACK qualifier generates additional
source-file
and
line-number information in
messages.

code to
run-time

/NOTRACEBACK suppresses this function and is the default.

6-38

print
error

PROGRAM DEVELOPMENT

LIBRARY
/WIDTH:n
The /WIDTH:n qualifier allows you to set the listing
specific width in the decimal range 8 through 132.

file

The default width is /WIDTH:l32.

6. 3

LIBRARY

LIBRARY creates and maintains user-written
library
files,
or
libraries.
Libraries can contain macro definitions, object modules,
or, in the case of universal libraries, anything.
Maintenance functions of LIBRARY include
extracting,
deleting,
inserting, and replacing library entries.
Libraries can be compressed
(squeezed) to save disk space.
Library contents can also be listed.
User-written object module libraries can be used as input to the Task
Builder, either directly or through LINK.
The Task Builder (TKB)
searches for definitions of all global symbols referenced
in your
program in the following fashion.
First, TKB searches other modules
included in the LINK command, then it searches a user-written object
module library included in the LINK command, and finally it searches
the system library.
User-written macro libraries hold source macros for use as input by
the MACR0-11 Assembler, either directly or through MACRO.
The
assembler searches the library you specify for macros listed in .MCALL
statements and called in your source program before searching the
system macro library.
In general, LIBRARY handles object module libraries and
macro
libraries in the same way.
This means that references in this section
to modules can be usually taken as referring to macros as well as
object modules.
Libraries are direct access files containing one or more modules of
the same type.
These files are organized for rapid access by the Task
Builder and MACR0-11 Assembler.
Universal libraries can contain
virtually anything to which you wish to have rapid access, such as
text files.
Library files contain two directory tables.
The entry point table
(EPT)
contains entry point names (global symbols) • The module name
table (MNT) contains module names. Both tables are in alphabetical
order.
Object module names are derived from .TITLE directives, while
entry point names are derived from defined global symbols.
Once an
entry point is located,
its associated module can be accessed
directly. Macro module names are derived from
.MACRO directives;
macros are linear code and do not have entry points.
This section does not teach you how to use the Librarian utility, but
only how to use the LIBRARY command. See the Notes for suggested
further reading.

6-39

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Format
LIBRARY
Operation? operation[/qualifier[s]]
LIBRARY operation[/qualifier[s]]
LIBRARY @f ilespec
LIBRARY performs the following operations:

COMPRESS
LIST

CREATE
REMOVE

DELETE
REPLACE

EXTRACT

INSERT

Each of these operations is treated as a separate command in this
description.

Notes
LIBRARY invokes the Librarian Utility Program (LBR).
To use this
command successfully, you must familiarize yourself with this
utility, which is described in Chapter 10 of the RSX-llM/M-PLUS
Utilities Manual.
LBR format differs from the format of the DCL LIBRARY command.
DCL translates the DCL command line into LBR format.
The
descriptions presented here
include cross-references to the
equivalents
in LBR format of the DCL command elements.
Use the
SET DEBUG command to see the translation.
If you wish to use indirect command files with LIBRARY,
the
indirect command file must be
in LBR format, not DCL format.
Only one level of indirect referencing is permitted.
You should also be familiar with the way the MACR0-11 Assembler
and the Task Builder use libraries.
See the IAS/RSX-11 MACR0-11
Reference Manual, the RSX-llM/M-PLUS Task Builder Manual, and the
RSX-llM/M-PLUS Guide to Program Developffient for more information.
You cannot use wildcards
operations.

(*, %)

in file specifications in LIBRARY

Library modules are limited to 65536 words per module.
Libraries are limited to 65536 blocks.
The LIBRARY command operates on three kinds of libraries:
•

Object module libraries.
These can be user libraries
one of the following DIGITAL-supplied libraries:

LBO: [l,l]SYSLIB.OLB

System library (this
is the
library searched by the Task
Builder by default).

LB 0 : [ l , l ] VM LIB • 0 LB

Virtual
library

LBO: rl.llEXELIB.OLB

Executive library

6-40

Memory

Management

PROGRAM DEVELOPMENT

LIBRARY (Cont.)

•

Services

LBO: [l,l]RMSLIB.OLB

Record Management
library

LBO: [l,l]FOROTS.OLB

FORTRAN IV library (optional)

LBO: [l,l]F4POTS.OLB

FORTRAN-IV-PLUS
(optional)

Macro libraries.
These can be user libraries or
the following DIGITAL-supplied libraries:

library
one

LBO: [l,l]RSXMAC.SML

System macro library.
This
is the library searched by
the assembler by
default.
(Note nonstandard file type)

LBO: [l,l]EXEMAC.MLB

Executive macro library

LBO: [l,l]RMSMAC.MLB

Record Management
library

Services

The Librarian utility can also be used to create and maintain a
third form,
universal libraries, using the /UNIVERSAL qualifier
on some of the LIBRARY commands.
The LIBRARY command and utility have no relationship to the other
kinds of libraries used on RSX-llM/M-PLUS systems.
Specifically,
LBR has no relationship to supervisor mode
libraries
or
core-resident libraries created by the Task Builder.
;Q[j .:·.~~~,:t;lM..;~~pS,; .:~r,ro:: ::yF,os,/'/ th~.i.: s~~.:te~,.:,,.ilEfl)/; . . ([#~ti.: :tA,?f4),.!;} .·.tf'nti·~ll.::
.:eofiJt:~z1pit: :;:pf.:i:~i):~9'~.~:::L .s¥~·t.~Iii. :·. :::.t.~·~k!i>.·i .: .· :su.~ir:.: :: .a_s:·. ::·i~:m~man,<l.$):'. . ;.~n,~: · th:e'.·
.·;i.~~lf:a'r:Y: .:;CJ;F;O'. .: ;:(I:J3·o ~ {;3}~~5:4.1' I
w.tli.q;q: . ;c·~n,:ta,i 1l)$ ;: ..Q~.rl1?;::c::·:t:'.¥±1·e<jed: }' :$Y:3±;~m
.'6lS}f$. I ' :S'UCil .: a:S . '.th~~ .:·uti~ i.t;fer;;) .'1.' ; are ~lgt).' :cal:h~d
a des .. "
!

•

':;!~~~::;£~~;gz9 t!~~~~!~@,~~fif~-: ~~ •. . . n~~P;:.• ;?h' ;;·a

The /SQUEEZE qualifier causes all text to the right of the
rightmost semicolon to be deleted.
This convention permits you
to preserve any meaningful semicolon by adding another semicolon
to its right.
Examples of meaningful semicolons include using
the ASCII value of the semicolon in code, or a semicolon marking
a comment you wish to preserve.
The following line of code moves
the ASCII value of the semicolon to register 1:
MOVB

#I ; '

but emerges after the /SQUEEZE as
MOVB

To preserve the meaningful semicolon, use the following form:
MOVB

#I ; , Rl

THIS DUMMY COMMENT SAVES THE CODE

which emerges after the /SQUEEZE as
MOVB

#I ; I Rl

6-41

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Similarly, the following comment:
;NEXT 5 LINES ARE CRUCIAL
disappears after the /SQUEEZE, but this form
;NEXT 5 LINES ARE CRUCIAL
emerges after the /SQUEEZE as
;NEXT 5 LINES ARE CRUCIAL
Keep this convention in mind whenever you are using the
qualifier.

/SQUEEZE

All error messages are described in Section 6.3.9.
Some error
messages are closely related to particular LIBRARY operations.
Descriptions of these messages are repeated in the section on the
operation to which they pertain.

6.3.l

LIBRARY/COMPRESS

LIBRARY/COMPRESS physically deletes modules that have been
deleted
through
LIBRARY/DELETE.
You can rename the
compressed library.

logically
resulting

Format
LIBRARY/COMPRESS[: (arg[,s])]
GLOBAL:n
MODULES:n
BLOCKS:n

libspec [newlibspec]

Parameters
libspec
Specifies the name of the library file to be compressed.
The
default type is
.OLB, specifying an object module library.
If
you wish to compress a macro library (standard file type
.MLB),
or a universal library
(standard file type .ULB), you must
specify the file type explicitly.
newlibspec
This optional parameter specifies a name for the newly compressed
library.
If you do not specify a name, the new file has the same
name as the old one. The old file is not deleted after you
create a new library with this command.
Arguments
If you are specifying more than one argument, the arguments must
be enclosed
in parentheses and separated by commas.
If you are
specifying only one argument, the parentheses are not necessary.

6-42

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
GLOBALS:n
The GLOBALS argument specifies the number of global symbols
(entry point table entries) to allocate.
The default n is the
number of global symbols allocated in the old library.
The
maximum n is 4096. The value of n is always forced to zero for
macro and universal libraries.
MODULES:n
The MODULES argument specifies the number of entries to allocate
in the module name table.
The default value is the number of
entries in the old library. The maximum number of module names
is 4096.
BLOCKS:n
The BLOCKS argument specifies the size of the library in 256-word
blocks. The default size is the size of the old library.

Example
>LIBRAr<Y/COMPf;:ESS l...B: C1, 1 JSYSL.IB + OLB

This example compresses the system object module library.

Notes
This command is equivalent to the LBR /CO
library file.
If you like,
compressing a
operation.

switch

applied

you can use LIBRARY/LIST before
and
after
library to see the effects of the compress

LIBRARY/CREATE

6.3.2

LIBRARY/CREATE creates a library and optionally inserts
modules into it.

one

The library is a contiguous file created on a volume
random-access device, that is, disk or DECtape.

mounted

more
on

Format
LIBRARY/CREATE[: (arg[ ,s] )] [/qualifier[s]]
GLOBALS:n
MODULES:n
BLOCKS:n

Command Qualifiers
/[NO]GLOBALS
/MACRO
/OBJECT
/SELECTIVE SEARCH
/SQUEEZE
/UNIVERSAL

6-43

libspec [infilespec[ ,s]]

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Parameters
libspec
Specifies the name of the library file being created.
The
default file type is .OLB if an object module library is being
created, .MLB if a macro library is being created, and .ULB if a
universal library is being created.
infilespec [s]
Specifies the file or files to be used as input to the new
library file.
If no input files are specified, an empty library
file is created. The default file types are .OBJ when creating
object module libraries, .MAC when creating macro libraries, and
.UNI when creating universal libraries.

Arguments
If you are specifying more than one argument, the arguments must
be enclosed in parentheses and separated by commas.
If you are
specifying only a single argument,
the parentheses are not
necessary.
GLOBALS:n
The GLOBALS argument specifies the number of global symbols
(entry point table entries) to allocate.
The default is 512 for
object lib~~ries. This v~lu~ i~ ~lw~y~ forced to 0 for macro and
universal libraries. n can be from 0 through 4096.
MODULES:n
The MODULES argument specifies the number of entries to
in the module name table.
The default value is 256.
from 0 through 4096.

allocate
n can be

BLOCKS:n
The BLOCKS argument specifies the size of the library in 256-word
blocks.
The default size is 100 blocks.

Command Qualifiers
/[NO]GLOBALS
/NOGLOBALS specifies that global symbols are not to
in the entry point table.

included

Use this qualifier if you wish to use the same global symbols in
more than one module. /GLOBALS is the default but is a no-op.
/SELECTIVE_SEARCH
Sets the selective search attribute bit in the module header of
object modules as they are inserted into an object library.
You
must specify an input file or files.
This qualifier has meaning for object module libraries

6-44

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Object modules with the selective search attribute are given
special treatment by the Task Builder. Global symbols defined in
modules with the selective search attribute are only included in
the
Task
Builder's symbol table if they were previously
referenced by other modules.
/SQUEEZE
The /SQUEEZE qualifier reduces the size of macro definitions by
eliminating all trailing blanks and tabs, blank lines, and
comments from macro text.
You must specify an input file or
files.
This qualifier has meaning for macro libraries only.
Macros that have been squeezed not only take up less room in
macro library file, but also take up less memory.

the

See the Notes to Section 6.3 for
/SQUEEZE qualifier.

the

important

information

This /SQUEEZE qualifier is the equivalent of the LBR /SZ switch
applied to the output library file when using the /CR switch.
/MACRO
The /MACRO qualifier specifies that the library being created
a macro library.

/OBJECT
The /OBJECT qualifier specifies that the library being created is
an object module library.
This is the default and need not be
spec i f ied.
/UNIVERSAL
The /UNIVERSAL qualifier specifies that the library being created
is a universal library.

Example

>LIBRARY
Qperation? CREATE:<GLOBALS:128,MODULES:64)
Librar~? CARNEGIE
Modules? DEWEY,CONGRESS,MODERN
This example creates the library CARNEGIE.OLB with a size of 100
blocks
(the default), 128 entry points, and 64 module names, and
inserts object modules from
the
input
files
DEWEY.OBJ,
CONGRESS.OBJ, and MODERN.OBJ.

Notes
This command is the equivalent of applying the LBR /CR switch
the output file.

6-45

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Tables should be allocated
Expanding table allocations
copy the entire file.

to
maximum
anticipated
size.
requires using LIBRARY/COMPRESS to

If the qualifiers /SELECTIVE SEARCH and /SQUEEZE are used
LIBRARY/CREATE, you must specify an input file or files.

with

LIBRARY/DELETE

6.3.3

LIBRARY/DELETE deletes modules from any library.
See LIBRARY/REMOVE
for removing global symbols (entry points) from a library.

Format
LIBRARY/DELETE libspec module[,s]

Parameter
libspec
Specifies the name of the library from which modules
deleted.

are

module [ ,s]
You can specify as many as 15 names of
separated by commas.

modules

If you do not specify the module list, you will be
it.

deleted,

prompted

for

Example

>LIBRARY/DELETE
Librar~? BUMPERS
ModuleCs>? BUGGY, BABY, RUBBER
Mod•J 1 es de 1 eted:

BUGGY
BABY
RUBBEF:
This example deletes the modules BUGGY, BABY, and RUBBER from the
latest version of the object module library BUMPERS.OLB.

Notes
This command is the equivalent of the LBR /DE switch
the output file.

applied

When you delete an entry from a
library,
the entry is not
This means that
physically removed, but is marked for deletion.
although the module is no longer accessible, the file space it
use the
occupied
is not available.
To clear this space,
LIBRARY/COMPRESS operation, Section 6.3.1.

6-46

PROGRAM DEVELOPMENT

LIBRARY {Cont.)
If a specified module is not contained in the
following message is printed on your terminal:

library,

the

LBR -- *FATAL*--No module named "name"
All the modules in your list up to the incorrect module name will
have been deleted.
None of the modules following the incorrect
module name will have been deleted.
You should use LIBRARY/LIST,
Section 6.3.6, to check which modules have been deleted and which
have not.
See LIBRARY/REMOVE (Section 6.3.7) for
global symbols from libraries.

6.3.4

information

removing

LIBRARY/EXTRACT

LIBRARY/EXTRACT reads one or more modules from a
them into a specified output file.

library

and

writes

You can extract up to eight modules with a single LIBRARY/EXTRACT
operation.
If more than one module is extracted, the modules are
concatenated in the output file.

Format
LIBRARY/EXTRACT/qualifier[:filespec] libspec module[,s]

Command Qualifier
/OUTPUT[:filespec]

Parameters
libspec
Specifies the library from which modules are to be extracted.
The default file type is .OLB, corresponding to an object module
library.
If you wish to extract from a macro or universal
library, you must specify the appropriate file type.
module[,s]
Specifies the modules that are to be extracted.
If you do not
include a
list, all modules
in the library are extracted and
concatenated in the output file in alphabetical order,
You can
specify up to eight modules, separated by commas.

Command Qualifier
The /OUTPUT qualifier specifies the file to which the extracted
modules or macros are to be written.
If you specify /OUTPUT
without a filespec, the default is to write the modules to your
terminal.
This makes sense only for macro libraries or universal
libraries containing text modules.
If you do not include the qualifier, you will be prompted To?, to
which you are to reply with a filespec.
You can reply TI:
to
have the output printed on your terminal.
6-47

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Examples

>LIBR/EXTRACT/OUTPUT:MATH LB0![1,1JSYSL.IB ARITH
This example extracts the module named ARITH from the library
SYSLIB.OLB,
the system object library.
The module is placed in
the default directory as a file named MATH.OBJ.

>LIBR/EXTRACT/OUTtTII LB0:[1,1JRSXMAC.SML SlOPSS
.MACRO STOPSS ERR
.MCALL. DIH$
MOV
<PC)t,-<SP>
.BYTE
l.31. '1
DIR$
,ERR
.ENDM
STOP$Fl
This example extracts the macro named STOP$S
macro library and prints it on the terminal.

from

the

system

Notes
This command is the equivalent of the LBR /EX switch
the library file as an input file.

applied

LIBRARY/EXTRACT has no effect
modules are extracted.

which

the

6.3.5

the

library

from

LIBRARY/INSERT

LIBRARY/INSERT inserts modules from one or more files into a library.

Format
LIBRARY/INSERT libspec filespec[,s]

Command Qualifiers
/[NO]GLOBALS
/SELECTIVE SEARCH
/SQUEEZE -

Parameters
libspec
Specifies the library into which modules are to be inserted.
The default file type is .OLB.
If you wish to insert modules
into a macro library
(file type .MLB) or a universal library
(file type .ULB), you must specify the file type explicitly.
f ilespec [ s]
Specifies the file or files containing concatenated modules to be
inserted into the specified library.
Any number of files can be specified and each
any number of concatenated modules.

6-48

file

can

contain

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
The default file type is determined by the library into which
modules are being inserted.
It is .MAC for macro libraries and
.OBJ for object module libraries, and
.UNI for
universal
libraries.

Command Qualifiers
/[NO]GLOBALS
/NOGLOBALS specifies that entry points for the specified
are not to be included in the entry point table.

modules

Use this qualifier if you wish to insert global symbols having
the same name as symbols already in the library file.
The
default, /GLOBALS, does not permit this operation.
/SELECTIVE_SEARCH
Sets the selective search attribute bit in the module header of
object modules as they are inserted into an object library.
You
must specify an input file or files.
Object modules with this attribute are given special treatment by
the Task Builder.
Global symbols defined in modules with the
selective search attribute are not included in the Task Builder's
symbol table unless they were previously referenced by other
modules.
/SQUEEZE
Reduces the size of macro definitions by eliminating all trailing
blanks and tabs, blank lines, and comments from macro text.
You
must specify an input file or files.
Macros that have been squeezed not only take up less room in
macro library file but also take up less memory.

the

See the Notes to Section 6.3 for
/SQUEEZE qualifier.

the

important

information

This qualifier is the equivalent of the LBR /SZ switch applied to
the output file.

Example
>LI BR/INSERT
Librar~? LB0t(1r1JSYSLIB
Module<s>? USERSUB

This example inserts object modules from the file USERSUB.OBJ
into the system object module lbrary, LBO: [l,l]SYSLB.OLB.
Notes

This command is the equivalent of the LBR /IN command.
Note that a single input file can contain more
module or macro.

than

one

object

If you are inserting macros into a macro library, LIBRARY/INSERT
insert only the .MACRO and .ENDM lines and what appears between
6-49

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
them.
All text in the file not bracketed by these assembler
directives is ignored.
This feature is in addition to the action
of the /SQUEEZE qualifier.
If you attempt to insert a module that already exists in the
library file, the following message is printed on your terminal:
LBR -- *FATAL*Duplicate module name "name" in filename
If you attempt to insert a module with an entry point that
duplicates one that is already in the EPT, the following message
is printed on your terminal:
LBR -- *FATAL*Duplicate entry point "name" in filename
In the case of either of these messages, all operations up to the
point at which the error occurred should have been successful.
No operations past that point will have taken place.
Use
LIBRARY/LIST to check which modules have been inserted and which
have not.

LIBRARY/LIST

6.3.6

LIBRARY/LIST lists the names of all
terminal or in an output file.

modules

library

your

E'crm.at
LIBRARY/LIST[:filespec]

libspec

Command Qualifiers
/BRIEF
/FULL
/[NO]NAMES

Parameter
libspec
Specifies the library you wish listed. The default file type is
.OLB.
If you wish to list a universal or macro library, you must
specify the appropriate file type.

Command Qualifiers
/LIST [: f ilespec]
If you do not include a filespec as an
library is listed on your terminal.

argument

/LIST,

the

If you include a filespec as an argument, the default device and
UFD are the same as those of the library you are listing and NOT
your current defaults. See the examples.
/BRIEF
The /BRIEF qualifier specifies that you wish the list to include
only the module names.
This is the default.
See the examples.

6-50

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
/FULL
The /FULL qualifier requests a listing of all module names, along
with a module description, including size, date of insertion, and
module-dependent information.
See the examples.
/[NOJNAMES
The /NAMES qualifier requests a list of modules in the
along with their entry points.
The default is /NONAMES.
examples.

library,
See the

Examples
>LIBRARY/LIST LB0t[111JSYSLIB
Directory of file SYSLIB+OLB~1002
ObJect module library creat~d by!
LBR V06+00
Last insert occurred 25-NOV-82 at 19:34:32
MNT entries allocated: 768; Available! 549
EPT entries allocated: 2048; Av~Jlable: 873
File space available: 00309 words
Recoverable deleted space: 14892 words
. AL ERR
ALSCT
ALT PR I
ANSPAI:t
Af\ITl-·1

This example shows the default display from LIBRARY/LIST.
the module names appear.
The information appears on
terminal.

>LIBRARY/LIST/FULL LB0:[1,1JSYSLIB
Directorw of file SYSLIB.OLB;1002
ObJect module libr~1r·\~ created by!
Lt:R '.!06.00
Last insert occurred 25-JUN-79 at 19:34!32
MNT entries allocated: 768; Available: 549
EPT entries allocatedt 2048f AvailablP: 873
File space av~ilable: 00309 words
Recoverable deleted space: 14892 words

ALERR

Size:00073

Inserted:22-0ST-82

IdenttOO

A L SC T

Si z e ! 0 0 13 4

I n s e r t e d ! 2 2 -- :J C T -- B ·::~

I d ~.n. t, : •) ·!

ALT PR I

S i z e ! 0008 1

I n s e r t e d : 2 2 -- 0 CT-- 8}

Td ~· r: t, : 0 O

ANSPAD

Size!00068

Inserted:25-NOV-82

Ident:20.0P~

ARITH

Size:oooss

Inserted:22-0CT-82

Ident:o3.03

6-51

Only
your

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
This example shows the display from LIBRARY/LIST/FULL, which
includes full module descriptions. This information appears on
your terminal.

>LIBRARY/LIST/NAMES LBO:c1,1JSYSLIB
Directory of file SYSLIB+OLB;1002
ObJect module library created bw:
LBR V06.00
Last insert occurred 25-NOV-82 at 19:34:32
MNT entries allocated: 768; Available: 549
EPT entries allocated! 2048; Available: 873
File space available! 00309 words
Recoverable deleted sPace: 14892 words

** Module:ALERR
$ALERR

** Module:ALSCT
ALSCT

** Module:ALTF'RI
ALTPRI

** Module:ANSF'AD
~ • ANSP

** Module!ARITH
$DIV

$MUL

This example shows the display from
lists entry points for each module.

LIBRARY/LIST/NAMES,

which

>LIBRARY/LIST/FULL/NAMES LBO![lrlJSYSLIB
Directory of file SYSLIB.OLB;1002
ObJect module library created b~:
LBR V06.00
Last insert occurred 25-NOV-82 at 19:34:32
MNT entries allocated! 768; Available: 549
EPT entries allocated: 2048; Available! 873
File space available: 00309 words
Recoverable deleted sPace: 14892 ~urds

** Module!ALERR

Si ze t 00073

$ALEF:R
6-52

I n s e r t €:' d : 2 2 -- 0 C T -- 8 2

I d (?. n t ! 0 0

PROGRAM DEVELOPMENT

LIBRARY (Cont=)

** Mod1Jle:ALSCT

Size:00134

Inserted!22-0CT-82

Ident!OO

Size!00081

Inserted:22-0CT-82

Id~?nt!OO

Size:00068

Insertedt25-0CT-82

Identt20.0P6

Size!00088

Inserted!22-0CT-82

Ident!03.03

ALSCT

** Mo du 1 e: AL TPF: I
ALTPRI

** Module:
+ •

ANSPf~D

ANSP

** Mo du 1 e: AR ITH

This example shows the display from LIBRARY/LIST/FULL/NAMES,
which includes not only module descriptions but also entry points
for each module.

>SHOW DEFAULT
DB2!
E303,5J
TT56!
>LIBRARY/LIST:FRED+LIS LB0![1,1JSYSLIB
LBR -- *FATAL*-DPen failure on file FRED.LIS

In this example, the user
intended to create a list of the
modules in SYSLIB in the default UFD on the default device.
The
error message indicates that the listing file cannot be opened.
This is because LBR attempted to place FRED.LIS on LBO:
in
[1,1], where the user did not have file creation privileges. See
next example.

>SHOW DEFAULT
DB2:
[303,5J
TT56!
>LIBRARY/LIST:DB2![303,5JFRED.LIS LB0![1,1JSYSLIB
..··

In this example, the user explicitly stated the
for the listing file and the command succeeded.

device

and

UFD

This command is the equivalent of applying the LBR /LI,
/LE switches to the listing file.

/FU,

Notes

Note that there are
command.

four

possible

6-53

listing

formats

with

this

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
LIBRARY/REMOVE

6.3.7

LIBRARY/REMOVE removes global symbols (entry points) from a
library.
See LIBRARY/DELETE for deleting object modules from a library.

Format
LIBRARY/REMOVE libspec global [global[,s]]

Parameters
libspec
Specifies the name of the library from which you wish
global symbols.

remove

global[,s]
Specifies the globals you wish to remove from the
can specify as many as 15 global symbols.

library.

You

This example deletes the globals TINKER, EVERS, and
the library DOUBLE.OLB.

CHANCE

from

This command is the equivalent of the LBR /DG switch
the output file.

applied

library,

the

Example

>LIBRARY/REMOVE DOUBLE TINKER,EVERS,CHANCE
Entr~

Points deleted:

TINKER
EVERS

CHANCE

Notes

If a specified global
is not included
in the
following message is printed on your terminal:
LBR -- *FATAL*

No entry point named "name"

All the global symbols (entry points) in your list up to the
incorrect name will have been deleted.
None of the globals
following the incorrect name will have been deleted.
You should
use LIBRARY/LIST (Section 6.3.6) to check which globals have been
deleted and which have not.

6.3.8

LIBRARY/REPLACE

LIBRARY/REPLACE replaces a module in a library with a
the same name and deletes the oid moduie.

new

module

When a match occurs on a module name, the existing module is logically
its entries are removed from the qlobal symbol table.

dPlPtPd and all

6-54

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Format
LIBRARY/REPLACE libspec filespec[,s]

Command Qualifiers
/[NO]GLOBALS
/SELECTIVE SEARCH
/SQUEEZE -

Parameters
libspec
Specifies the library in which modules are to be replaced.
The
default file type is .OLB, corresponding to object libraries.
If
you wish to replace macros in a macro library (file type .MLB) or
a universal library (file type .UNI), you must specify the file
type expiici tiy.
f ilespec [ ,s]
Specifies the file or files containing the new modules.
The
default file type is determined by the type of library in which
modules are being replaced.
It is
.OBJ for object module
libraries,
.MAC for macro libraries,
and
.UNI for universal
libraries.
If the module to be replaced does not
LIBRARY performs an insert operation.

exist

the

library,

If the module to be replaced exists, a message is printed.
See
example.
If the module does not exist, it is inserted, but no
message is printed.

Command Qualifiers
/[NO]GLOBALS
/NOGLOBALS specifies that entry points for the specified modules
are not to be included in the entry point table.
The default is
/GLOBALS.
/SELECTIVE_SEARCH
Sets the selective search attribute bit in the module header
object modules as they are inserted into an object library.

Object modules with the selective search attribute are given
special treatment by the Task Builder. Global symbols defined in
modules with the selective search attribute are only included in
the
Task
Builder's symbol table if they were previously
referenced by other modules.
/SQUEEZE
Reduces the size of macro definitions by eliminating all trailing
blanks and tabs, blank lines, and comments from macro text.

6-55

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Macros that have been squeezed not only take up less room in the
macro library file but also take up less memory in the assembler
when they are invoked.
See the Notes in Section 6.3 for more information on the /SQUEEZE
qualifier.
This is the equivalent of the LBR /SZ switch applied to the input
file.
Example

>LIBR/REPLACE LB0:[1,1JSYSLIB USERSUB
MODULE

USERSUB

REPLACED

This example replaces the modules in the file SYSLIB.OLB with new
modules bearing the same names in the file USERSUB.OBJ.
Entry
points are also redefined.
Notes
This command is the equivalent of the LBR /RP command.
There must be enough space in the library's tables for both the
modules being replaced and their replacements since the new
modules are entered before the old modules are deleted.
The old modules are logically deleted only.
You must use
LIBRARY/COMPRESS to eliminate the modules themselves and free the
space they occupy.

6.3.9

Error Messages from LIBRARY

LIBRARY has two kinds of error messages, diagnostic and fatal.
Diagnostic messages are marked *DIAG* and
inform you of conditions
that require your consideration but do not warrant termination of the
command. Depending on the message and the operation, you can decide
what further action is called for.
The operation completes.
Fatal messages are marked *FATAL* and describe conditions that caused
LBR to terminate execution of your command.
The operation does not
complete.
In general, fatal output errors leave the library in an indeterminate
state.
You should use LIBRARY/LIST to determine how much of the
operation completed before the fatal error occurred.
Some errors result from corrupted library files.
You can use VFY, the
File Structure Verification utility, to determine whether a file is in
Files-11 format.
A library file can be in Files-11 format and still
be corrupted as a library, however.
If a library file is corrupted, the library must be recreated.

6-56

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
Error messages appear on your terminal in the following formats:
LBR -- *DIAG*-message
LBR--*FATAL*-message
Note that error messages from LIBRARY are tagged LBR after the utility
and not LIB after the command.
This is an exception to the general
rule on DCL error messages.
LBR -- Bad library header
Explanation:

The file either is not a library or is corrupted.

User Action: Make sure the file is a library.
If the file is a
library, use VFY, the File Structure Verification utility, to
determine if it is corrupted.
See
Chapter
9
of
the
RSX-llM/M-PLUS Utilities Manual.
LBR -- Command I/O error
Explanation: There are two possible causes. The problem may be
with the physical device, such as not being spun up.
Or, the
file may be corrupted or have an incorrect format, such as a
record length exceeding 132 bytes.
User Action:
Determine the condition that caused the message and
correct the condition. Reenter the command line.
LBR -- Command syntax error
command line
Explanation:

The reprinted command 1 i ne has a syntax 'error.

User Action:
line.

Check for proper syntax

and

reenter

the

command

LBR -- Duplicate entry point name "name" in filename
Explanation: Your command attempted to insert
(not replace)
a
module containing the given entry point name into a library
already containing an entry point of that name.
User Action: Make sure you have named the correct input file.
If not, reenter the command naming the correct input file.
If
the input file is correct, you can delete the duplicate entry
point from the library and reenter the command.
LBR -- Duplicate module name "name" in filename
Explanation:
Your command attempted to insert
(not replace)
a
module with the given name into a library that already contains a
module of that name.
Oser Action: Make sure you have named the correct input file.
If the input file is correct, you must decide whether or not to
use LIBRARY/REPLACE to replace the module that is already in the
library.

6-57

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
LBR -- EPT or MNT exceeded in filename

Explanation: The GLOBAL or MODULE table limit has been
during the execution of a REPLACE or INSERT operation.

reached

User Action: Copy the library using LIBRARY/COMPRESS and include
the /MNT or /EPT qualifier to increase table size.
LBR -- EPT or MNT space exceeded in compress

Explanation: A GLOBAL or MODULE table size was specified in a
COMPRESS operation for the output library file that is not large
enough to contain the EPT or MNT entries used in the input
library.
User Action: Reenter the command line with a larger EPT
table size specified.

MNT

LBR -- Error in library tables, File "filename"

Explanation:
library.

Either the library is corrupted

not

User Action:
If the file is corrupted, no recovery is possible.
The file must be reconstructed.
If the file is not a library,
reenter the command line with the correct file named.
LBR -- Fatal compress error

Explanation: The input library
corrupted or is not a library.

COMPRESS

operation

Explanation: System error. LBR attempted to execute a Get
Parameters directive and failed.

Time

User Action: Reenter the command line.
If the error
is
repeated, see your system manager.
Plan to submit a Software
Performance Report. Save console dialogue and other pertinent
information.
LBR -- Input error on filename

Explanation:

The file system has detected an error.

User Action: Reenter the command.
your system manager.

If the error is repeated, see

LBR -- Insufficient dynamic memory to continue

Explanation:

The partition in which LBR is running is too small.

User Action:

See your system manager.

6-58

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
LBR -- Invalid EPT and/or MNT specification
Explanation: Command included
greater than 4096.
User Action:

argument

for

/MNT

/EPT

Check for proper syntax and reenter command.

LBR -- Invalid module format,

insertion-module

Explanation: Command attempted
definition into an object module

insert

the

named

macro

library~

User Action: Correct error by reentering command with object
module for object module library or macro for macro library.
LBR -- Invalid format, input file filename
Explanation:
Your command named either an input file that is not
in the standard format or a file that is corrupted.
User Action:
command.

Make sure you have named the right file and reenter

LBR -- Invalid library type specified
Explanation:
Your command attempted to set an
illegal library
type as the default.
The file types .OBJ and .MAC are the only
valid default file types for the command.
User Action:

Reenter command after checking proper syntax.

LBR -- I/O error on input file "filename"
Explanation:
A read error occurred on an input file.
can have two causes:
such

This error

•

A problem with the physical device,
spun up.

not

being

•

The input file is corrupted or in the wrong format,
as records exceeding 132 bytes in length.

such

User Action:
Determine the cause of the error
condition.
Reenter the command line.

and

correct

the

LBR -- Library file specification missing
Explanation: Your
command
was
specification of the library file.
user Action:

entered

without

proper

Check for proper syntax and reenter the command.

LBR -- Mark for delete failure on LBR work file
Explanation:
LBR automatically creates a work file when it
begins processing commands and marks it for delete. For some
reason this marking failed.
The work file is a
lost file and
does not appear in any UFD.

6-59

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
User Action:
See your operator or system manager. The file must
be deleted using VFY, the File Structure Verification utility.
See Chapter 9 of the RSX-llM/M-PLUS Utilities Manual.
LBR -- No entry point named "name"
Explanation:
Your command named an entry
that is not in the library.

point

deleted

User Action: Check command for proper syntax and
reenter
command.
You may have misspelled the entry point name or named
the wrong library.
LBR -- No module named "module"
Explanation:
Your command named a module to be deleted
not in the library.

that

reenter
User Action: Check command for proper syntax and
command.
You may have misspelled the module name or named the
wrong library.
LBR -- Open failure on file "filename"
Explanation: The file system detected an error while attempting
This error is caused by one of the following
to open a file.
conditions:
•

The user directory area
operation.

protected

against

Write

There is a problem with the physical device, such as
• being
spun up.

not

• The volume is not mounted.
• The UFO does not exist.
• The file does not exist.
is insufficient space to allocate the library file
• There
on a LIBRARY/CREATE or LIBRARY/COMPRESS.
•

There is insufficient pool space (DSR)

in the Executive.

User Action: Determine the cause of the error and correct it
you can.
If you cannot, see your operator or system manager.

LBR -- Open failure on LBR work file
Explanation: The file system detected an error while attempting
to open the LBR work file.
The LBR work file is created on the
volume from which LBR was installed.
One of the following
conditions can cause this error:
•
•

The volume is full.
The

device

which

write-protei:tea.

6-60

the

volume

mounted

PROGRAM DEVELOPMENT

LIBRARY (Cont.)
•

There is a problem with the physical device.

•

There is insufficient pool space (DSR)

in the Executive.

User Action:
you can.

Determine the cause of the error and correct it
If you cannot, see your operator or system manager.

LBR -- Output error on filename

Explanation: A write error has occurred on the output file.
of the following conditions can cause this error:
•

The volume is full.

•

The device on which
write-protected.

•

The hardware has failed.

the

volume

One

mounted

Determine the cause of the error and correct it
If you cannot, see your operator or system manager.

User Action:
you can.

LBR -- Positioning error on filename

Explanation: The device on which the volume is mounted
write-locked or some other hardware difficulty exists.

User Action:

Determine the cause of the error if
you cannot, see your operator or system manager.

you

can.

LBR -- Virtual storage requirements exceed 65536 words

Explanation: This error may occur with maximum size libraries in
conjunction with a single command line that logically deletes a
large number of modules and entry points and continues to replace
them with an equally large number of modules and entry points
having highly dissimilar names.
Normally, this message indicates
some sort of internal system error.
User Action:

Rerun the job after dividing the command line
several smaller lines that perform the same operations.

into

LBR -- Work file I/0 error

Explanation: A write error has occurred on the LBR work
One of the following conditions can cause this error:
•

The volume is full.

•

The device on which
write-protected.

•

The hardware has failed.

mounted

Determine the cause of the error and correct it
If you cannot, see your operator or system manager.

User Action:
you can.

6-61

the

volume

file.

PROGRAM DEVELOPMENT

LINK
6.4

LINKING THE TASK

After the MACR0-11 Relocatable Assembler or high-level language
compiler has translated the source program file into a binary object
file, the object file must be linked or task built.
This process
makes a runnable task out of one or more object files plus object
modules from user-written or system library files.

Introduction to the LINK Command

6.4.1

The LINK command invokes the Task Builder, a system utility that
builds the tasks, formally called task images, that run on the system.
The unadorned LINK command includes a number of defaults that produce
a
standard task image file,
having the file type .TSK.
The Task
Builder (TKB), however, provides you with many choices that are not
included in the defaults.
You can use qualifiers to the LINK command
to create TKB output files in addition to the task image file,
to
identify certain kinds of unusual tasks, to use hardware options that
may not be present on all systems, and
in general to control the
nature of the task build
itself.
In addition to the LINK command
qualifiers, there are also Task Builder options that permit you to
specify characteristics of the task you are building.
The defaults provide you with a simple means of building a standard
task.
You pass the Task Builder an object file (default file type
.OBJ) oroduced bv the MACR0-11 Relocatable Assembler or one of the
high~l~vel
language compilers, and the Task Builder produces a
runnable task image.
This is done with a command such as the
following:
>LINK

File<s>?

SAMPLE

>
This command produces a single output file called SAMPLE.TSK.
The
return of the implicit prompt tells you the task build completed
successfully.
If, in addition to the task image file, you should want a Task Builder
map file showing the size and location of parts of the task, issue a
command such as the following:

>LINK/MAP SAMPLE

>
This produces two output files, SAMPLE.TSK and SAMPLE.MAP.
SAMPLE.MAP is automatically printed
appears in your directory.

the

line

printer

and

also

The following command also requests that a map be made:

>LINK SAMPLE.OBJ/MAP

>
This produces two output files, SAMPLE.TSK and SAMPLE.MAP.
SAMPLE.MAP
appears in your directory but is not printed on the line printer.

6-62

PROGRAM DEVELOPMENT

LINK (Cont.)
If you are linking more than one object module to form a task,
the
Task Builder, by default, names the output files after the first task
named in the command line. For example, the command

>LINK MOE' CURLYr LARRY

>
produces a task image file named MOE.TSK.
Use the /TASK qualifier
change the name of the task image file.
For instance, the command

>LINK/TASK:SHEMP MOE, CURLY, LARRY

>
produces a task image file named SHEMP.TSK.

Or, use the command

>LINK MOE, CURLY/TASK, LARRY

>
to produce a task image file named CURLY.TSK.
Note, however, that the command

>LINK/MAP MOE, CURLY/TASK, LARRY

>
produces a task image file
MOE.MAP.

named

CURLY.TSK

and

map

If, in addition, you want the task build to abort after
Builder finds three errors, issue a command such as this:

file

named

the

Task

>LINK/MAP/ERROR_LIMIT:3 SPARKY

>
This produces two output files, the task image and the map, as before.
In addition,
if the Task Builder finds three errors, it sends a
message to your terminal and aborts the task build.
Finally, there are Task Builder options.
qualifier in your LINK command, you
input.
For instance,

If you specify the /OPTION
will be prompted for further

>LINK/MAP/OPTIONS BIGJON
0Ption?

UNITS==7

The UNITS option specifies the number of I/O units for the task.
There are more than two dozen options you can specify.
They are
listed in Table 6-3.
If you wish to specify options, there are two ways of doing so.
must first include the /OPTION qualifier in your LINK command.
will be prompted Option? Then:
1.

You
You

You can specify options on separate lines. Simply enter an
option with its arguments and press RETURN.
You will be
prompted Option? until you terminate the prompt with just a
RETURN.

6-63

PROGRAM DEVELOPMENT

LINK (Cont.)
2.

You can specify them in a separate file and name the file
to the Option? prompt with an at sign (@) •

~esponse

Here are two examples.
>LI NK/MAF' /OPT IONS BI GJON
0Ption!' UNITS:=7 (BIT)
0Ption? ASG==SYO :i:·: 7 ~

(BIT)

Option? rfilf)

>
or
>LINK/MAP/OPTIONS BIGJON
0Ption? @SPARl\Y.CMD ~

0Ption'?

>
These commands are all DCL commands and the format is DCL format.
The
Task Builder, however, does not recognize DCL format.
It recognizes
only Task Builder format.
The translation from DCL format
to TKB
format is performed by DCL.
Issuing the LINK command to DCL initiates the following process:
1.

DCL reads the command line and
format.

checks

for

correct

DCL translates the command line into correct TKB format.

DCL places the TKB-format command in a TKB indirect command
file and passes the
indirect command
file
to the Task
Builder.

The Task Builder builds the task as directed and creates
requested output files.

all

The Task Builder returns control to DCL and DCL
TKB indirect command file.

the

deletes

DCL

If you are building standard tasks using the defaults and
following
the examples given in the command description (Section 6.4.2), this
process will serve you well.
However, you will have to refer to the RSX-llM/M-PLUS Task Builder
Manual
for
information on how the Task Builder responds~your LINK
command.
The Task Builder manual explains all
the output files
produced by TKB and how TKB interprets your LINK command.
All the
options are explained in the manual, all the terms used in the TKB
environment are defined, and,
in general, the capabilities of this
complex and flexible software tool are elucidated.
The description of the LINK command in this manual is not intended to
teach you how to use the Task Builder, but only to teach you how to
use the LINK command.
To learn to use the Task Builder, you must go
to the Task Builder manual.

6-64

PROGRAM DEVELOPMENT

LINK (Cont.)
Since TKB format and DCL format are different, this may be difficult
at first.
The TKB translation of your LINK command is available to
you in two forms.
First, you can use the SET DEBUG command
(Section
1.2.15), which echoes on your terminal the translation of any DCL
command. Second, you can use the /SAVE qualifier to LINK.
The /SAVE
qualifier preserves the indirect command file created by DCL to be
passed to the Task Builder.
This file is named ATLNK.TMPa
This file
is also useful if you wish to repeat a particular task build. See the
discussion of /SAVE.
The following description should help you switch from
TKB format.

DCL

format

In TKB format, you name any output files you want produced, separated
by commas, to the left of an equal sign (=).
The order you name them
determines which output files you receive.
The DCL command

>LINK SAMPLE. OBJ
produces the following command in
command file:

TKB

format

the

TKB

indirect

TKB>SAMPLE.TSK=SAMPLE.OBJ
In each case, the Task Builder takes SAMPLE.OBJ as its input file and
produces as its only output file the task image SAMPLE.TSK.
The task
image file takes the first position in the list of TKB output files to
the left of the equal sign (=).
The DCL command

>LINK/MAP SAMPLE.OBJ
produces the following command in TKB format:

TKB>SAMPLE.TSK,SAMPLE.MAP=SAMPLE.OBJ
In each case, the Task Builder takes SAMPLE.OBJ as its input file and
produces two output files, SAMPLE.TSK and SAMPLE.MAP.
The map file
takes the second position in the list of TKB output files to the left
of the equal sign.
The third kind of output file produced by the Task Builder is called a
symbol definition file and has the file type .STB.
The DCL command

>LINK/MAP/SYMBOL_TABLE SAMPLE.OBJ
produces the following command in TKB format:

TKB>SAMPLE.TSK,SAMPLE.MAP,SAMPLE.STB=SAMPLE.OBJ
In each case, the Task Builder takes SAMPLE.OBJ as its input file and
produces three output files, SAMPLE.TSK, SAMPLE.MAP, and SAMPLE.STB.
The symbol definition file takes the third position in the list of TKB
output files to the left of the equal sign.

6-65

PROGRAM DEVELOPMENT

LINK (Cont.)
In TKB format, you can add switches, consisting of a slash and two
letters, to each of these output file specifications to alter the
output file.
For instance, the DCL command

>LINK/CODE!FIS SAMPLE.OBJ
produces the following command in TKB format:

TKB>SAMF'LE.TSK/FF'=SAMPL..E.Of:J
In each case, the Task Builder builds a task that
Point Processor, which is optional hardware.
Qualifiers can also be used on map files.

uses

the

Floating

The DCL command

>LINK/CROSS_REFERENCE SAMPLE.OBJ
produces the following command in TKB format:

In each case, the
cross-references
/MAP qualifier if
that implies that

In the

Task Builder map includes a listing of symbol
in the program. DCL does not require you to use the
you use another qualifier, such as /CROSS_REFERENCE,
you want a map file.

description

the

LINK

~o~~~na

th~t

follows:

each

DCL

qualifier is identified with its equivalent in TKB format.
You can invoke the Task Builder from DCL in four ways:
•

Issuing the LINK command with DCL qualifiers

•

Invoking a DCL indirect command file including a LINK
with DCL qualifiers, such as DCL>@LINKFILE

command

•

Issuing the LINK command and calling a
file, such as DCL>LINK @TKBFILE

TKB

indirect

command

•

Running the
commands

$TKB

and

Task

Builder

with

RUN

issuing

TKB

The first two methods of invoking the Task Builder require the LINK
command and DCL format.
The latter two methods require commands in
TKB format.

6.4.2

LINK

LINK invokes the Task Builder, which links object modules and routines
from user and system libraries to form an executable task.
If you are using LINK with the COBOL-81 compiler, please
6.4.3, which describes the LINK/C81 command.

6-66

see

Section

PROGRAM DEVELOPMENT

LINK (Cont.)
Format
LINK[/qualifier [s]] filespec [/qualifier [s]] [ ,filespec [ ,s]]

Command Qualifiers
/ANCILLARY PROCESSOR[:n]
/[NO]CHECKPOINT:arg
SYSTEM
TASK
/CODE: (arg [ ,s])
UA'R;A' ;s~:AGE'

EAE FPP
PIC
POSITION INDEPENDENT
/COMPATIBLE
/[NO]CROSS REFERENCE
/[NO]DEBUG[:filespec]
/[NO]EXECUTABLE[:filespec]
/ERROR LIMIT:n
VTN<!r$x'P1t!i$~~J:i

/FAST
/FULL SEARCH
/[NO]HEADER
/[NO] IO PAGE
/LONG /MAP [: f ilespec]
/[NO]MEMORY MANAGEMENT[:n]
/OPTIONS[:optionsspec]
/OVERLAY DESCRIPTION
/POSTMORTEM
/[NO]PRIVILEGED[:n]
/[NO]RECEIVE
/[NO]RESIDENT OVERLAYS
/SAVE
/[NO]SEGREGATE
/SEQUENTIAL
/SHAREABLE [ : a r g]
COMMON
LIBRARY
TASK

/SLAVE
/SLOW
/SYMBOL TABLE[:filespec]
/[NO]SYSTEM LIBRARY DISPLAY
/[NO]TASK[:filespec]
/TKB
/TRACE
/[NO]WARNINGS
/WIDE

File Qualifiers
/[NO]CONCATENATE
/DEFAULT LIBRARY
/[NO]GLOBALS
/LIBRARY
/INCLUDE: (modulel [: ••• :modulen])

/OVERLAY DESCRIPTION
/SELECTIVE_SEARCH

6-67

PROGRAM DEVELOPMENT

LINK (Cont.)
Parameter
f ilespec [ s]
Specifies the file or files to be linked. The default file type
is .OBJ for object modules and .OLB for object module libraries.
You can have any number of object modules as input files,
separated by commas.
These can be specified in any order.
If,
however, one or more input files must reference an object library
(.OLB)
file,
the .OLB file must be entered in the list of input
files directly after the files that reference it.

Command Qualifiers
/ANCILLARY_PROCESSOR[:n]
Identifies the task as an ancillary control processor (ACP). The
parameter n specifies the base relocation register.
Acceptable
values are O, 4, or 5. The default is 5.
In TKB format, apply the /AC switch to the .TSK filespec.
/[NO]CHECKPOINT:arg
SYSTEM
TASK
Specifies that the task is to be
(or
is
not
to
be)
checkpointable.
Checkpointability of tasks is an important part
of the operating system's ability to share resources.
When a
higher
priority
task
seeks
access to system memory, a
checkpointable task of lower priority is checkpointed, or rolled
out to the disk to be stored in its current state until the
higher priority task exits, whereupon the lower priority task
returns and takes up where it left off.
If you do not use the /CHECKPOINT qualifier, your task is built
noncheckpointable.
The
default
is
/NOCHECKPOINT.
A
noncheckpointable task cannot be dislodged by a task of higher
priority.
Therefore,
you should always build your tasks
checkpointable unless you have some important reason for not
doing so.
You can specify how the checkpointing of the task is handled
through the arguments to the /CHECKPOINT qualifier.
Your task
can be checkpointable to the system checkpoint file with the
SYSTEM
option.
This is the default.
LINK/CHECKPOINT and
LINK/CHECKPOINT:SYSTEM are equivalent commands.
Tasks built with system checkpointing cannot be checkpointed if
the system checkpoint file is full.
(The size of this file is
set with the SET DEVICE command.)
You can also reserve checkpoint
own task image file by using
are always checkpointable.
(If
file, you can only run one copy

6-68

space for the task as part of its
LINK/CHECKPOINT:TASK. Such tasks
there is no system checkpoint
of such tasks.)

PROGRAM DEVELOPMENT

LINK (Cont.)
It should be apparent that the checkpointability of a task has an
impact on the efficient operation of the entire system as well as
on the task itself.
If the task is built noncheckpointable,
it
can block more important tasks from running.
If it is built with
task checkpointability, mass-storage space is reserved that may
never be used.
If it is built with system checkpointability,
there may be no room for it in the system checkpoint file.
Check with your system manager for advice on
selection among these checkpointing qualifiers.

the

preferred

In TKB format, for /CHECKPOINT:SYSTEM, apply the /CP switch to
the task image file.
For /CHECKPOINT:TASK, apply the /AL switch
to the task image file.
For /NOCHECKPOINT, apply the /-CP switch
to the task image file.
/CROSS_REFERENCE
Specifies that a listing of symbol cross-references
appended to the Task Builder map file.

If you include this qualifier, you automatically include the /MAP
qualifier as well.
You do not need the /MAP qualifier unless you
wish to supply a name for the map file.
If you supply a name,
the map file appears in your current UFO but is not printed on
the line printer.
In TKB format, apply the /CR switch to the .MAP filespec.
/CODE: (arg[,s])
J~ATA :'$)?ACE:.

EAE
FPP
PIC
POSITION INDEPENDENT
The /CODE qualifier specifies that the code for the task relies
on certain hardware elements or employs certain techniques.
See
the RSX-llM/M-PLUS Task Builder Manual for more information.

;The ~TA SPAtE ·arg'umerit: :<(RSX.'..··I!IM::.·prlµs
,'~~CI·:¥']'.'·~.~·:~ '1·t:n:~~t~ )fn;J.
employ · tiSEH·-~ode' I- and D-space. · In T~.: ,f;O~~:bi ,?;'pP~YL.th~
·;ro :swit~ch. to: the: .TSK :filespep;. · ·
··
,,
..

'o!!:ryf

·task

The EAE argument specifies that the task uses the Extended
Arithmetic Element.
This hardware is optional and may not be
part of your system.
In TKB format, apply the /EA switch to the
.TSK filespec.
The FPP argument specifies that the task uses the Floating Point
Processor.
This hardware is optional and may not be part of your
system.
In TKB format,
apply the /FP switch to the
.TSK
f ilespec.
The PIC and
POSITION INDEPENDENT arguments are identical and
specify that the resident common or library being built is
position-independent.
In TKB format, apply the /PI switch to the
.TSK or .STB filespec.
If you wish to use more than one
parentheses, separated by commas.
6-69

argument,

enclose

them

PROGRAM DEVELOPMENT

LINK (Cont.)
/COMPATIBLE
Specifies that the task be built in compatibility mode.
This
means that memory-resident overlay segments are aligned on
256-word boundaries for compatibility with other implementations
of the mapping directives.
Without this qualifier, overlay
segments are aligned on 32-word boundaries.
In TKB format, apply the /CM switch to the .TSK filespec.
/DEBUG[:filespec]
Specifies the inclusion of a debugging aid in the task image.
A
debugging aid permits you to interrupt the running of a task and
inspect registers and other memory locations at various stages.
If you give no filespec, the default is LBO: [l,l]ODT.OBJ, which
is ODT, the On-line Debugging Tool, a DIGITAL-supplied utility.
ODT is incorporated
in the task you are building. ODT can be
used only on tasks written in the MACR0-11 Assembly Language.
See the IAS/RSX-11 ODT Reference Manual for further information.
If you have a user-written debugger, name the file it is in when
you use this qualifier.
This file should be an object module.
In TKB format, apply the /DA switch to the .TSK filespec
if you
wish to use ODT.
If you wish to use a user-written debugger,
apply the /DA switch to the input filespec naming the debugger.
/ERROR LIMIT:n
Directs the Task Builder to abort LINK after n diagnostics errors
have been produced.
In TKB format, apply the /XT:n switch to the .TSK filespec.
/[NO]EXTERNAL
Specifies that the task be built to run with its header
pool. RS:X-llM-PLUS only.
The default is /EXTERNAL.

out

In TKB format, apply the /XH switch to the .TSK filespec.
/POSTMORTEM
Requests a
Postmortem Dump should the task be
abnormally.
See the RSX-llM/M-PLUS Task Builder
information on Postmortem Dumps.

terminated
Manual for

In TKB format, apply the /PM switch to the .TSK filespec.
/FAST
Specifies that the Fast Task Builder be used to build the task.
The Fast Task Builder is considerably faster than the default
Task Builder.

6-70

PROGRAM DEVELOPMENT

LINK (Conte)
Several restrictions apply to tasks to be built by the Fast
Builder:

Task

• Tasks may not be overlaid.

• Tasks may not be privileged.
• Tasks may not link to resident libraries.
• The Task Builder cannot produce an .STB output file.

• The Task Builder cannot create resident libraries.
•

The LINK command is limited to the following qualifiers:
- /CROSS_REFERENCE, /MAP, /LONG, /WIDE
- /[NO]CHECKPOINT:SYSTEM
- /[NO]MEMORY_MANAGEMENT
- /CODE:FPP
- /DEBUG[:filespec]

•

The Task Builder is limited to the following options:
- ASG
- STACK
- UNITS
- EXTSCT
- ACTFIL
- MAXBUF

In addition, the map format is nonstandard and undocumented.
You can also invoke the Fast Task Builder from DCL with the
command RUN $FTB. You must follow TKB format if you run the Fast
Task Builder in this fashion.
See the RSX-llM/M-PLUS Task Builder Manual for more details.
/FULL_SEARCH
Specifies that when processing modules from the default object
module library, the Task Builder should search all co-tree
(overlay) segments for matching definitions or references.
Without this qualifier,
unintended global references between
co-tree overlay segments are eliminated. Definitions of global
symbols from the default library are restricted
in scope to
references in the main root and the current tree.
In TKB format, apply the /FU switch to the .TSK filespec.

6-71

PROGRAM DEVELOPMENT

LINK (Cont.)
/LONG
Specifies that the map file produced by the Task Builder include
additional file
information on modules used in the task build.
The long map does not include file information on modules from
the system library.
If you include this qualifier, you automatically include the /MAP
qualifier as well.
You do not need the /MAP qualifier unless you
wish to supply a name for the map file.
If you supply a name,
the map file appears in your current UFD but is not printed on
the line printer.
In TKB format, apply the /-SH switch to the .MAP filespec.
/MAP [: f ilespec]
Specifies that you wish a memory allocation, or map, file
produced.
If you use /MAP as a command qualifier, without a
filespec argument, the map appears in your UFD with a file name
derived from the name of the first
input file named in the
command line and a file type of .MAP.
The map is also printed on
the line printer.
If you use /MAP with a filespec argument, either as a command
qualifier or a
filespec qualifier, the map appears in your UFO
with a file name you have given. The map is not printed on the
line printer.
If you use /MAP as a
filespec qualifier, without a
filespec
argument, the map appears in your UFO with a file name derived
from the name of the .OBJ or .OLB file to which the qualifier was
attached.
The map is not printed on the line printer.
The following qualifiers automatically direct the Task Builder to
produce a map with special characteristics:
/CROSS REFERENCE
/LONG /SYSTEM LIBRARY DISPLAY
/WIDE You do not need the /MAP qualifier with these qualifiers unless
you wish to add a
filespec argument to /MAP.
These other
map-related qualifiers can be used as either command or filespec
qualifiers, but they have no effect on file names.
In TKB format, the /MAP qualifier corresponds to the second
position in the list of TKB output files and has the default file
type .MAP.
/[NO]HEADER
/NOHEADER sets the Task Builder STACK option to O.
If you are
building a shared region or a driver, you should specify this
qualifier.
If you specify this qualifier, you may not use the
STACK option.
The default is /HEADER.
In TKB format, apply the /-HD switch to either the .TSK or
filespec and specify the STACK=O option.
See /SHAREABLE.

6-72

.STB

PROGRAM DEVELOPMENT

LINK (Cont.)
/[NO]IO_PAGE
/NOIO PAGE indicates to the Task Builder that the task is over
12K and purposely does not map to the I/O page.
This qualifier
is for building privileged tasks only. The default is /IO_PAGE.
/[NO]MEMORY_MANAGEMENT[:n]
Specifies that the task is being built for a system with
(or
without)
memory
management
hardware.
Use
the
/NOMEMORY MANAGEMENT qualifier when you are building a task on a
system with memory management to be run on an RSX-llM (or
RSX-llS)
system without the Memory Management hardware.
n
specifies the highest physical address of a task on the target
system and can be 28 (the default) or 30.
The default is /MEMORY_MANAGEMENT.
In TKB format, apply the /-MM switch to the .TSK filespec.
/SHAREABLE[:arg]
COMMON
LIBRARY
'.TASi<'

/s'ahRiEABL~;:TASK ·l S: the. '.qe'.f.aul't·· '.ahd. •is ...f:o·r:· '.RSx:..:11zi.t.;.;pr.us . only;.
'

/SHAREABLE:COMMON and SHAREABLE:LIBRARY are for RSX-llM/M-PLUS.

: ' .:z"S~.Att~A8t~::·:'l'1'.~i< :·i<l~n·tr f(~s:'.111~'. ~ta $k. :.·a:s· ·a . ··m.ut tJ.use~ ... 1:ask. . sucih.;; :·

·<t.e·~~£?·: ·~~!'m.~.P: . . :.:lll?~.te .•tu~ri:: p~~: :u~:ter:•tJ;;<>

h.~re·t:&he ;r,~~9·"79n~.r .. p~r{i:2l).~·· o,f.;.{

·i';;r:~~.9,-on·l:Y · · ... p<:rrt;·i<:m>: :O~·· «th7::.· ·ti3Sk.~·

t. ;When.':: m:u'lt:lJJse:r.... ta.s.kf:r.· . . a;r:·e>J

,:;;~!~7t!~~i~1f~~~il,l~~~1?s~:4Wf~~~;j;T~;f:
n$:ta'.J. :red.~ ' .mu;+;t :fp~:e·· ie<lU~~t:s:'. }:bit .. " . "tas·('.' {:(); run ::ca'use:·' :the...isy.s::t~n\t;
:i.;~9 :'· :'&~E>1i.cate ::.: .on1y'·:·th~'.,'·
e "E>oi.~;i.o:n·:. :bt:' th$. "t.~~1c· ;p~r: ::~·a~~{.::
>Jl'equest:::~ft~~· th~;:.:'f'.lrst ~ :. .:. . .:.Th,e '.ROPAR: ~op:ti.onJ{>e:imits,: J'oµ .··fo / .;:nam;~:: .
}:he po·:i;·HoJl; .::icn :waich: r,e9ion; ;i·.:rs .. to '.';eside:•'/;·In: i'l!1:<~ :·f9);:ma::Y:~.: app1'.·y,::
;1'. :i'.

:reaa:.:wrl

;··~~~.:·/~Pt:~:rW'~5f:P:· ~p:· :t.~e'. ~:t~~I( :~,i:!·esP:ec,;

.'. · , .

' ·, , · · : :· · ·, · .. :~' · · . · ; :·.; ",

:· .Pn.·~s}f.;~.~M~~LP~ sy~~;ems;·,. /S~AR.EABLE:TASK,.de:(~1:1p:s ..t 0:, /S.~GREGATE.:·.
1

/SHAREABLE:COMMON informs the Task Builder that a shareable
common is being built.
You should always use the /NOHEADER
qualifier with /SHAREABLE:COMMON.
If you do not specify CODE:PIC
or CODE:POSITION INDEPENDENT, TKB builds an absolute shared
common. All program sections in the common are marked absolute.
If you specify CODE:PIC or CODE:POSITION INDEPENDENT, all program
sections in the common are marked relocatable.
In either case,
the .STB file contains all the program section names, attributes,
lengths, and symbols. The .STB file of a common built /SHAREABLE
contains all defined program sections.
In TKB format, apply the
/CO switch to the
.TSK or
.STB filespec.
On RSX-llM-PLUS
systems, /SHAREABLE:TASK defaults to /SEGREGATE.
/SHAREABLE:LIBRARY informs the Task Builder that a shareable
library is being built.
You should always use /NOHEADER with
iSHAREABLE:LIBRARY. TKB includes only one program section in the
.STB
file.
If
you
do
not
specify
CODE:PIC
or
CODE:POSITION_INDEPENDENT, TKB names the program section .ABS,

6-73

PROGRAM DEVELOPMENT

LINK (Cont.)
makes the library position-dependent, and defines all symbols as
absolute.
If you specify CODE:PIC or CODE:POSITION INDEPENDENT,
TKB gives the program section the same name as the root segment
of the library.
TKB forces this name to be the first and only
declared program section in the library.
TKB declares all global
symbols in the
.STB file relative to that program section.
In
TKB format, apply the /LI switch to the .TSK or .STB filespec.
/OPTION[:optionsspec]
Specifies one or more Task Builder options.
Use this qualifier
if you need to use any of the Task Builder options.
Information
on these options is summarized in Table 6-3. See Section 6.4.1
for
information on using this qualifier.
For full information,
or options, see the RSX-llM/M-PLUS Task Builder Manual.
You can supply options for this qualifier in two ways:
you can
supply the filespec of a file containing the options, or you can
specify the options themselves.
If you do not include a filespec
with this qualifier, you are prompted for options.
If you wish
to enter multiple options, you must use a comma after each option
listed.
If you wish to list multiple options on individual
lines, you must end each line with a comma.
If you include a filespec with this qualifier, this file should
contain only the option names, comments, and the arguments
associated with the options, as shown:
rJNITSo::8

ASG=TT0:7:8
; COMMENTS, PRECEDED BY SEMICOLON, ALLOWED
PAR=KROBAR:50000:40000
This file should not include anything but the option statements
and comments preceded by the semicolon (;). Comments preceded by
the exclamation point (!) are not accepted in this instance.
Do
not put any slashes in this file.
Note that the ABORT option is the only means of preventing a task
build once you have begun issuing commands to the Task Builder.
A CTRL/Z simply directs the Task Builder to begin the task build
based on whatever instructions you have issued up to that point.
Thus, if you want to be sure of being able to stop a task build
in this way, you must include the /OPTIONS qualifier in the LINK
command line. This assures the availability of the ABORT option.
If you are typing the command line and make a mistake, specify
the /OPTIONS qualifier, press RETURN, and enter the ABORT=O
option.
Then press RErURN and the task build aborts.
/OVERLAY_DESCRIPTION
Specifies that the input file is an overlay description file
(type .ODL)
that controls the linking of the task.
No other
input file can be specified if you use this qualifier. The
.ODL
file specifies input files to LINK. /OVERLAY DESCRIPTION can be
either a command qualifier or a filespec qualifier.
In TKB format, use the .ODL file as the only input file to the
right of the eqDal sign (=) with the /MP switch applied to the
• ODL f ilespec.

6-74

PROGRAM DEVELOPMENT

LINK (Cont.)
/PRIVILEGED [: n]
Indicates that task is privileged.
The argument n specifies
base relocation register.
Acceptable values are O, 4, or 5.
default is 5.

the
The

In TKB format, apply the /PR switch to the .TSK filespec.
/[NO]RECEIVE
Indicates that the task may (or may not)
receive messages by
means of the Executive directive SENDs
/RECEIVE is the default.
In TKB format, apply the /SE switch to the .TSK filespec.
/[NO]RESIDENT_OVERLAY
Enables (or disables) recognition of the memory-resident overlay
operator
(!)
in an overlay description file~
The qualifier is
used with the /OVERLAY DESCRIPTION qualifier when the task has
memory-resident overlays.
The default is /RESIDENT_OVERLAY.
In TKB format, apply the /RO switch to the .TSK filespec.
/SAVE
The /SAVE qualifier specifies that you wish to retain the
indirect command file created by DCL to pass your LINK command to
TKB.
See Section 6.4.1 for a description of DCL's handling of
the LINK command.
If you
include /SAVE in your LINK command
line, a file named ATLNK.TMP appears in your UFD after
the task
build completes.
Since this file always has the same name, you
should give it a name related to the task
it builds,
such as
SHEMPBLD.CMD.
Then you can issue a command in the form
>LINK @SHEMF'BLD

and duplicate the task build that originally produced the command
file.
This file is also useful for comparing LINK command syntax with
TKB syntax because it includes the full translation of the LINK
command into TKB format.
/[NO]SEGREGATE
/SEGREGATE causes the Task Builder
to order program sections
alphabetically by name within access code (RO followed by RW).
If you also specify /SEQUENTIALi TKB orders program sections
in
their input order by access code.
/NOSEGREGATE is the default.
TKB interleaves RO and
RW program
sections.
When combined with /SEQUENTIAL, /NOSEGREGATE results
in a task with program sections allocated in input order with its
RW and RO sections interleaved.
If you use /NOSEQUENTIAL and
/NOSEGREGATE together, which is the default for both, TKB orders
program
sections
alphabetically
with RW and
RO sections
interleaved.
In TKB format, use the /[-]SG switch on the .TSK filespec.
On RSX-llM--,PLUS systems, /SHAREABLE: TASK defaults to /SEGREGATE.

6-75

PROGRAM DEVELOPMENT

LINK (Cont.)
Table 6-3
Task Builder Options
Description and
Language Key 1

Format and Defaults 2
Control
ABORT=O
Number used for format only.
number will do.

Direct TKB to terminate
build (M, H)

Any

Identification
Declare task name (M,H)

TASK=l-6 alphanumeric characters
TASK=first six characters of first
file name

Set task's User Identification Code (M,H)

UIC=[g,m]
UIC=terminal UIC

Declare task's priority
(M, H)

PRI=decimal integer 1-250
PRI=set by INSTALL; 50, for
nonprivileged users

Declare task's partition
name and size (M,H)

PAR=parname[:base:length]
PAR=GEN

De!C1la;r:e tp~ ;part;i tfon: :~P:
which ,the ,r,ead.-only
,
cpo1rt:i10!n '()lf\ ia :mul't i usex: '.

. ,, :,RQP'AR=iParnam:e .
,. ' ' ..
1 0

··:·t , "ROPAR~GEN

, ta:s'k' ais: htoi :residie c:r-t,lff?;.

Decla,,r:e the completion
ro.uti1ne the s.uperv isor
.ro:~r: ·V9r.3;~:Y ~,n,1 . us:~ ;tA
re~Of~n '?~~ro.1, ·tt:o yout» "

CM.f~T=l'""'.6 a.J.pham.-.m~r·~<: ch;f;lr,a\c'~:e,;$

No·.<tef:au:Lt

pr<>gt'a,m ·:~n :user mode ·u1f,H)
1. Language key:
M - Option is of interest to MACR0-11 programmers.
H - Option is of interest to programmers
using
languages.

high-level

2. The first entry in the format and default column gives the
format, the second entry gives the default, if any. This chart is
only a reminder of the options, their formats, and their defaults.
You must read the RSX-llM/M-PLUS Task Builder Manual for full
information on these options.

(Continued on next page)

6-76

PROGRAM DEVELOPMENT

LINK (Cont.)
Table 6-3 (Cont.)
Task Builder Options
Description and
Language Keyl

Format and Defaults 2

Declare number of active
files (H)

ACTFIL=decimal integer
ACTFIL=4

Declare extension to
FORTRAN record buff er (H)

MAXBUF=decimal integer for record
size in bytes (larger than
default)
MAXBUF= 13 2.

Declare extension of
buffer used for processing format strings (H)

FMTBUF=decimal integer for number
in longest format description
(larger than default)
FMTBUF=l32

Declare extension of
program section (M,H)

EXTSCT=psectname:extension
No default

Declare extension of
task's portion of memory;
extends D-space of rand D-space tasks
(M,H)

EXTTSK=decimal integer for increase
in task memory allocation (in
words)
Default from PAR option

Declare virtual base
address and size of
virtual program section (H)

VSECT=psectname:base:window[:length]
No default

Declare number of additional window blocks
needed by task (M,H)

WNDWS=0-5
WNDWS=O

Declare size of stack
(M,H)

STACK=decimal integer for number of
words needed for stack
STACK=256.

1. Language key:
M - Option is of interest to MACR0-11 programmers.
H - Option is of interest to programmers
using
languages.

high-level

2. The first entry in the format and default column gives the
format, the second entry gives the default, if any.
This chart is
only a reminder of the options, their formats, and their defaults.
You must read the RSX-llM/M-PLUS Task Builder Manual for full
information on these options.

(Continued on next page)

6-77

PROGRAM DEVELOPMENT

LINK {Cont.)
Table 6-3 (Cont.)
Task Builder Options
Description and
Language Keyl

Format and Defaults2

Sharing Storage
Declare intention to
access system-owned
common block for
data in memory; if
used with I- and
D-space tasks, common
mapped with D-space
APRs only (M, H)

COMMON=name:access-code[:apr]
No default

Declare intention to
access system-owned
resident library for
code; if used with
I- and D-space tasks,
library mapped with
I- and D-space APRs
(M,H)

LIBR=name:access-code[:apr]
No default

Declare intention to
access user-owned common;
if used with I- and
D-space tasks, common
mapped with D-space APRs
only (M,H)

RESCOM=filespec/access-code[:apr]
Standard defaults on filespec

Declare intention to
access user-owned library;
if used with I- and
D-space tasks, library
mapped with I- and
D-space APRs (M,H)

RESLIB=filespec/access-code[:apr]
Standard defaults on filespec

1. Language key:
M - Option is of interest to MACR0-11 programmers.
H - Option is of interest to programmers
using
languages.

high-level

2. The first entry in the format and default column gives the
format, the second entry gives the default, if any.
This chart is
only a reminder of the options, their formats, and their defaults.
You must read the RSX-llM/M~PLUS Task Builder Manual for full
information on these options.

(Continued on next page)

6-78

PROGRAM DEVELOPMENT

LINK {Cont.)
Table 6-3 {Cont.)
Task Builder Options
Description and
Language Keyl

Format and Defaults2

Declare 'jnt:en':t.:i;on' :to::·. ,,
:r
REP,SoJ?~td~es:p;ec/{;7J S'rt :ap/:r;J
ac:~~~s · .?!, us~!. ::.Q,w.f!~ft . . .,:· / ,, << , st'andar'd ;·a:e:f'au·l:t;s .ob·· fi·llesne·c·
superyiso,r:,'rhOd.e·•,i;i:btary . r.:;";;;:;:··;:·p;·:;J; :., t::,;',,''.' ,;,,::: · /:::i>f:'
'(M,H)

, , ,, , .

, .'

Allow task to dynamically
map memory-resident
shared regions at
run time. One task
address window maps
the libraries into
the same span of virtual
address space. (M, H)

CLSTR=libraryl,library2, ••• libraryn:switch:[apr]
libraryl is default library
switch can be RW: or RO:
apr is starting APR
No default

Declare" intention. to·
access ·;a. s.y·stecm~aw;ned •·.. ,
:superv,is'or .. mo<iJ~ ··1ibr'a,:t~.:

SUP LIB,= f ilespec/:[ ·-:- 1S;\1{ : ap•r l :
:$~~P;d3q:.r'd}~e:fag~ ts,: .·p;n,: :'f'i1:espe:c.

(M,H}

;·

Device
Declare number of I/O
(logical) units (M,H)

UNITS=decirnal integer 0-250
UNITS=6

Declare logical device
assignment to units (M,H)

ASG=ddnn:unit-num:unit-num •
ASG=SY0:1:2:3:4,TI0:5,CL0:6

Alterations
Declare definition of
global symbol (M)

GBLDEF:syrnbol-name:symbol-value
No default

1. Language key:
M - Option is of interest to MACR0-11 programmers.
H - Option
is of interest to programmers
using
languages.

high-level

2. The first entry in the format and default column gives the
format, the second entry gives the default, if any.
This chart is
only a reminder of the options, their formats, and their defaults.
You must read the RSX-llM/M-PLUS Task Builder Manual for full
information on these options.

(Continued on next page)

6-79

PROGRAM DEVELOPMENT

LINK (Cont.)
Table 6-3 (Cont.)
Task Builder Options
Description and
Language Keyl

Format and Defaults2

Declare global symbol
reference (M)

GBLREF=symbol-name
No default

Declare series of patch
values; patches I-space
of I- and D-space
tasks ( M}

ABSPAT=seg-name:address:val-1

Declares series of patch
values; patches D-space
of I- and D-space tasks

(up to 8)

No default
DSPPAT=seg-name:address:val-1
(up to 8)
· No default

(M)

Declare series of patch
values relative to global
symbol (M)

GBLPAT=seg-name:sym-name[+/-offset] :val-1
(up to 8)
No default

Exclude the specified
symbols from the symbol
definition file of a
supervisor mode library

GBLXCL=syml:sym2: ••. :sym8
No default

(M)

Declare address and size
of ODT SST vector (M)

ODTV=symbol-name:vector-length
No default

Declare size of task SST
vector (M)

TSKV=symbol-narne:vector-length
No default

Include specified symbols
in .STB file (M,H)

GLBINC~syrnbol-name,symbol-name, ••• ,symbol-name

No default

1. Language key:
M - Option is of interest to MACR0-11 programmers.
H - Option is of interest to prograwmers
using
languages.

high-level

2. The first entry in the format and default column gives the
format, the second entry gives the default, if any.
This chart is
only a reminder of the options, their formats, and their defaults.
You must read the RSX-llM/M-PLUS Task Builder Manual for full
information on these options.

6-80

PROGRAM DEVELOPMENT

LINK (Cont.)
/SEQUENTIAL
Directs Task Builder to construct a task image from program
sections in the order in which they appear.
Normally, the Task
Builder finds all program sections referenced in all modules
in
an overlay segment and then builds the task with those program
sections in alphabetical order= Do not use this qualifier to
build tasks that rely on alphabetical allocation of program
sections, such as FORTRAN I/O handling modules and FCS modules
from SYSLIB.
See also /SEGREGATE.
In TKB format, apply the /SQ switch to the .TSK filespec.
/SLAVE
Specifies that the task is to be slaved to a sending task.
When
a slaved task successfully executes the Executive directive
Receive Data, it is given the UIC and TI: of the sending task~
This qualifier applies only to systems with multiuser protection.
Slaved tasks cannot be run with a RUN command.
by the sending task.

They must be

run

In TKB format, apply the /SL switch to the .TSK filespec.
/SLOW
Invokes the Slow Task Builder. You should specify the Slow Task
Builder only if your link or task build produces the following
error message:
NO VIRTUAL MEMORY STORAGE AVAILABLE
The default Task Builder and the Fast Task Builder use a symbol
table structure that can be searched quickly, but which requires
more work file space than the Slow Task Builder.
If you receive
the error message shown, you have the choice of reducing
work-file size as described in the Task Builder manual or of
using the Slow Task Builder.
Except for the use of different symbol table structures, the
default Task Builder and the Slow Task Builder are identical.
All qualifiers to LINK and all TKB options are available for the
Slow Task Builder.
You can also invoke the Slow Task Builder from DCL with the
command RUN $STK.
You must follow TKB format if you run the Slow
Task Builder in this fashion.
/SYMBOL_TABLE[:symboltablespec]
Directs that a symbol table file be produced.
The default name
is that of the first input file and the default type is .STB.
The filespec parameter overrides the defaults.
This qualifier is
used when building shared regions.
In TKB format, this qualifier corresponds to the third position
in the list of TKB output files, called the .STB filespec.

6-81

PROGRAM DEVELOPMENT

LINK {Cont.)
/[NO]SYSTEM_LIBRARY_DISPLAY
Directs the Task Builder to produce a map that includes (or does
not include)
global symbols defined or referenced by the task.
These symbols are found
in LBO: [l,l]SYSLIB or
in any shared
regions linked to using TKB options.
This map is usually
considerably longer than the default map.
The information
displayed
illuminates the contribution that SYSLIB or the shared
regions make to the task.
If you include this qualifier, you include the /MAP qualifier as
well.
You do not need
the /MAP qualifier unless you wish to
supply a name for the map file.
If you supply a name,
the map
file appears
in your current UFO but is not printed on the line
printer.
See the RSX-llM/M-PLUS Task Builder Manual for more information.
In TKB format, apply the /MA switch to the .MAP filespec.
/TASK [: taskspec]
/EXECUTABLE[:taskspec]
Specifies a name for the task image file different from that of
the first
input file plus the type .TSK.
If used as a filespec
qualifier, the task name is derived from the name of the file to
which the qualifier is attached.
/EXECUTABLE is a synonym.
In TKB format, thi8 qualifier co~r~$ponds to th~ first position
in the list of TKB output files, called the .TSK filespec.
/NOT ASK
/NOEXECUTABLE
Specifies that LINK produce no task image file.
This qualifier
is useful when you wish to use some facility of the Task Builder
without building a task,
to check for
unresolved
symbol
references or make a map,
for
instance.
/NOEXECUTABLE is a
synonym.
In TKB format, leave the first position in the list of TKB output
filespecs blank, followed by a comma (,).
/TKB
Specifies that the default Task Builder be used to build the
task.
This
is the default;
the qualifier
is included for
completeness.
You can also invoke the default Task Builder from DCL with the
command RUN $TKB.
You must follow TKB format if you run the
default Task Builder in this fashion.
/TRACE
Specifies that the task is to be traceable.
qualifier,
a
trace trap occurs on the
instruction when the task is run.

When you use
completion of

In TKB format, apply the /TR switch to the .TSK filespec*

6-82

this
each

PROGRAM DEVELOPMENT

LINK {Cont.)
/[NO] WARNINGS
/NOWARNINGS suppresses diagnostic messages issued by the the Task
Builder.
Two messages are suppressed:
n undefined symbols segment "segname"
and
Module "modulename" multiply defines P-section "psectname"
The default is /WARNINGS.
In TKB format, use the /[-]NM switch on the .TSK filespec.

I [NO] WIDE
Specifies that the Task Builder map
format.
The default is /NOWIDE.

printed

132-column

If you include this qualifier, you include the /MAP qualifier as
well.
You do not need the /MAP qualifier unless you wish to
supply a name for the map file.
If you supply a name,
the map
file appears in your current UFD but is not printed on the line
printer.
In TKB format, apply the /WI switch to the .MAP filespec.

Parameter Qualifiers
Any input file can have a parameter qualifier
identifying the kind of file that it is.

applied

it,

/[NO]CONCATENATE
Identifies the input file as a concatenated object file;
this is
the default.
All modules in the file are processed to form the
task image. /NOCONCATENATE specifies that only the first object
module encountered is to be processed, regardless of how many are
present.
In TKB format, apply the /CC switch to an input
concatenated object modules.

file

containing

/LIBRARY
Identifies the file as an object module library. This qualifier
is required for any input library file and is prohibited for any
other type of file.- The default file type for object libraries
is .OLB.
The Task Builder searches the library file to resolve all
undefined global symbol references from files appearing to the
left of the library file in the LINK command line.
The Task
Builder then extracts any and all modules that resolve undefined
references and
includes them in the task image.
See also
/INCLUDE.

6-83

PROGRAM DEVELOPMENT

LINK (Cont.)
/INCLUDE:modulel[: ••• modulen]
You can specify as many as eight module names from a library
using /INCLUDE.
You must specify at least one.
If you use the
optional module arguments, the Task Builder takes only those
modules from the library.
The module names are defined at
assembly time.
I f you wish
both to resolve undefined references to global
symbols and to specify modules, you must use this qualifier
twice.

In TKB format, apply the /LB switch to an input library file
both /LIBRARY and /INCLUDE.

for

/DEFAULT_LIBRARY
Specifies that the file to which it is appended replace the
system object module library, LBO: [l,l]SYSLIB.OLB, as the default
library that is searched to resolve unresolved global references.
This qualifier can be applied to only one file and that file must
be an object module library, type .OLB.
In TKB format, apply the /DL switch to an input library file.
/[NO]GLOBALS
Specifies that global symbols referenced and defined by the input
file are (or are not) to be included in the map output file.
The
default is /GLOBALS.
In TKB format, apply the /-MA switch to the input file.
/SELECTIVE_SEARCH
Instructs the Task Builder to search the file only for undefined
references to global symbols.
This qualifier is most useful when
building an Ancillary Control Processor or other privileged task
that maps into the Executive.
If you do not specify this
qualifier, all the Executive's global symbol definitions are
included
in
the task build, whether there are undefined
references to the global symbol or not.
The Executive contains a
myriad of modules.
In these and similar circumstances, this
qualifier considerably shortens the symbol table search and
improves system performance.
If you do not use this qualifier, all global
input file are included in the task image.

symbols

from

the

In TKB format, apply the /-SS switch to an input file.

Examples
>LINI\
File(s)'? WF:AY

>
This example task builds the object file WRAY.OBJ into the task
image file WRAY.TSK.
For the LINK command to work properly,

6-84

PROGRAM DEVELOPMENT

LINK (Cont.)
WRAYeOBJ must be an object file.
Since the user did not specify
a
file type for the object file, the LINK command supplied the
default file type .OBJ.
The return of the implicit prompt indicates successful completion
of the task build.
>LINK WRAY

This example is equivalent to the previous one.
>LINK/MAP WRAY

This example is similar to the previous two except that a Task
Builder map is also requested. When the task build is completed,
the map WRAY.MAP is printed on the line printer and also appears
in your directory.
>LINK/MAP!NEWLINK

WRAY

This example is similar to the previous one, except that a
filespec
is provided with the /MAP qualifier. When the task
build is completed, the map file NEWLINK.MAP appears in your UFO.
If you want a copy of this file, issue a PRINT command.
>LINK WRAY/MAP

This example illustrates another way of using the /MAP qualifier.
In this case, when the Task Builder exits, a file called WRAP.MAP
appears in your UFO but is not printed on the line printer.
If
you want a copy of this file, issue a PRINT command.
>LINK/DEBUG WRAY

This example builds the task WRAY.TSK including OOT, the
Oebugg i ng Tool.
>LINK/OPTIONS i1.Jf~'.~~,y

0Pt1on·?UNITS=:8

0Ptian?ASG=TT0!7~B

0Ptian?

>·

On-line

ru
ru

This example illustrates the use of the /OPTIONS qualifier.
The
command sequence builds the task with eight logical units (LUNs),
with LUNs 7 and 8 assigned to TTO:.
See the discussion in
Section 6.4.1.
The entire LINK command is entered by the final
RETURN in response to the Option? prompt.

6-85

PROGRAM DEVELOPMENT

LINK (Cont.)
>LINK/OPTIONS/NOMEMORY_MAN WRAY
Option?PAR=KROBAR:S0000!40000
This example builds the task to run on an unmapped system in the
partition named KROBAR, which has a base address of 50000 and a
size of 40000.

>LINK/CHECKPOINT:SYSTEM WRAY
>LINK/CHECKPOINT WRAY
The commands in this example are equivalent. The task
checkpointable to the system checkpoint file.

built

>LINK/CHECKPOINT:TASK WRAY
In this example, the task is built with checkpoint space reserved
where the task image file is stored.

>LINK WRAY, 3TRACK
In this example, the task is built from two object modules,
WRAY.OBJ and 3TRACK.OBJ.
The task image file has the name
WRAY.TSK.
It is installed and run under that name.

>LINK/TASK:SHACK WRAY, 3TRACK
In this example the task
is built from the same two object
modules as in the previous example.
However, the task image file
is given the name SHACK.TSK by the /TASK qualifier.
It is
installed and run under that name.

>LINK/OPTIONS WRAY,
0Ption?TASK=SHACK

3TRACK

>
In this example, the task is built from two object modules.
The
task image file has the name WRAY.TSK, but the default task name
(specified by the TASK option) is SHACK.
The default task name
is used by the INSTALL command (see Section 7.8) if the user does
not specify a task name explicitly. Only privileged users can
issue the INSTALL command.
This means that to run the task from
a file, you use the command RUN WRAN, but if you run it after
it
has been installed, you use the command RUN SHACK.

>LINK/OVERLAY RAYMEN
In this example, the Task Builder uses the file RAYMEN.ODL to
build an overlaid task.
(.ODL is the default file type for the
/OVERLAY qualifier.) The input file RAYMEN.ODL must be written in
the Overlay Description Language.
Only one file can be specified
with this qualifier.
The files that form the overlaid task are
~allea

~u~n~Ati~Ally~

6-86

PROGRAM DEVELOPMENT

LINK {Cont.)
>LINK @WF:AYBLD

This example specifies the indirect command file WRAYBLD.CMD as
input to the Task Builder.
This file must be written in Task
Builder format, not DCL format.
This file can be the ATLNK.TMP
file renamed.
See the discussion under /SAVED.

Notes
You must read the appropriate documentation to use
fully.
This is true without exception.

this

command

The RSX-llM/M-PLUS Task Builder Manual does not use the term
"link."
In the Task Builder manual,
the preferred term is
"build."
Note that nonprivileged users can build privileged tasks and
high-priority tasks, but those users cannot run the privileged
tasks.
Nor can they run tasks at any but the default priority of
50.
Remember that for nonprivileged users, the RUN command is always
a
combination
of
three commands.
In effect,
it is an
INSTALL-RUN-REMOVE command.
Thus, references to installation in
the preceding discussion refer
to explicit installation by
privileged users through the
INSTALL command and
implicit
installation through the RUN command as well.
See Chapter 7 for
further details.
You can include comments in the LINK command line in the usual
DCL fashion.
However, comments
in a list of TKB options must
appear on a line by themselves preceded by a semicolon.
Do not
use the exclamation point (!) for comments in a list of options.

Error Message
LIN -- Library invalid on last input file

Explanation:

The syntax of LINK requires that the last input
file specified must be a valid (single} object file that is not
part of a library.

User Action:

6.4.3

Check for proper syntax and reenter the command.

LINK/C81

This section explains how you can
produce a task image (.TSK file}.

link

Format
LINK/C81[/qualifier[s]]

filespec[,s]

LINK/COBOL[/qualifier[s]]

filespec[,s]

6-87

COBOL-81

object

files

PROGRAM DEVELOPMENT

LINK (Cont.)
Command Qualifiers
Although the format shows them as command qualifiers, you can
append the following qualifiers to either the command or a file
specification. When you use the LINK/C81 command, the two
locations are equivalent.
/[NO]FMS
/FMS:NORESIDENT
/OTS:[NO]RESIDENT
/[NO] RMS: [NO] RESIDENT
/[NO]MAP
/[NO]DEBUG

Parameter
filespec [ ,s]
Specifies the file or files to be linked.
is .SKL.

The default file

type

The LINK/C81 command links object modules indirectly through
their associated
.SKL files.
Therefore,
if you include file
types in any file specifications, you must use .SKL rather than
.OBJ.
Each .SKL file corresponds to an object module (,OBJ file)
that is included in the task image. Except for the file type,
the
.SKL
file
and
object
module
have identical file
specifications.
You can list any number of .SKL
order, separated by commas.

files

input

files

any

Qualifiers
/OTS: [NO] RESIDENT
The /OTS:RESIDENT qualifier includes memory-resident OTS in your
task
image.
When
you specify /RMS:RESIDENT as well as
/OTS:RESIDENT, LINK/C81 clusters these two libraries by default.
If you can take advantage of the clustering feature,
the
resulting task image is smaller and program execution speed is
improved.
However, do not use /OTS:RESIDENT if memory-resident
OTS is not installed on your system because an error condition
will result.
The /OTS:NORESIDENT qualifier
library in your task image.

includes

the

disk-resident

OTS

The default is /OTS:NORESIDENT.
/[NO] RMS: [NO] RESIDENT
The /RMS:RESIDENT qualifier creates a reference to the shared
RMS-11 memory-resident library,
RMSRES.
This library includes
input/output support for sequential, indexed, and relative file
organizations.

6-88

PROGRAM DEVELOPMENT

LINK (Cont.)
When you specify /OTS:RESIDENT as well as /RMS:RESIDENT, LINK/C8l
clusters these two libraries by default.
If you can take
advantage of the clustering feature, the resulting task image is
smaller and program execution speed is improved.
However, do not
use the /RMS:RESIDENT qualifier if memory-resident RMS is not
installed on your system because an error condition will result.
The /RMS:NORESIDENT qualifier includes the disk-resident RMS
overlays in your task.
By default,
LINK/C81 provides the
smallest RMS overlay structure available. This provides you with
the smallest task image you can achieve using disk-resident RMS
overlays.
The /NORMS qualifier is equivalent to /RMS:NORESIDENT.
/[NO]MAP
The /MAP qualifier causes LINK/C81 to produce a Task Builder
file with the file type .MAP.

map

The /NOMAP qualifier tells LINK/C81 not to produce a
file.

map

memory

The default is /NOMAP.
/[NO]DEBUG
The /DEBUG qualifier tells LINK/C81
Symbolic Debugger in your task image.

include

the

COBOL-81

To use this qualifier, you must also use the /DEBUG qualifier
the COBOL command (see Section 6.2.4.1).

The /NODEBUG qualifier tells LINK/C81 not to include the COBOL-81
Symbolic Debugger in your task image.
The default is /NODEBUG.
/[NO]FMS
/FMS: NO RES ID ENT
The /FMS qualifier causes LINK/C81 to include Forms Management
Services
(FMS) library support in your task image. You must use
this qualifier if you call FMS routines from your program.
The /NOFMS qualifier tells LINK/C81 not to include FMS support.
The default is /NOFMS.
The /FMS:NORESIDENT qualifier causes LINK/C81 to include support
for a non-memory-resident FMS library in your task image.
Since
no resident FMS libraries are supported under RSX, this qualifier
is equivalent to /FMS.
For more detailed information about how to create a task image
LINK/C81, refer to the COBOL-81 RSX-llM/M-PLUS User's Guide.

6-89

using

PROGRAM DEVELOPMENT

DEBUG
.6.;5

DEBUG

'DEBOG forces ·a task. on an.. 1tsx~1114~.PLUS,·.sys·tem .. to. t~··ap ·'to. ·a' 'deb.u9ge.t' . py·
. sett.iqg the :T.~hit. ·in' ttie task'·s Processor' Sfatus.·wo:ra· •. ··.The.··J:ask m~s''t. ·
have .been"-bqilt using ·the /PEBUG.qual.i{ie~ to .. the ·LI,NK.:comma·na .. o;r· have
, issued tpe .·syQB$. ·Executive ·directive., (·Specify "S.ST. ·Vecto·r{ .'fab1~· f.oi"
Del:rngging.i\id,) •.
· ··· ····· · · · · ·
·· · ···· ·· '· · · :·
· ·
Nonpl:ivileged users c·an, iss~e···this .comtna'nd fo'r any no'rtpri~ll~~~A ·. i:a·sk·
running from their t'erminals •· 'Pr.ivJ'lege,d us,er·s can.'.hc:i:rne. any·.,·t:ask1 · bfrt':
the. command mu,S"I;: be is;sued:·~ftom the ,same terrnh:iaL.,'. the:· task'' W?tS r,un·
f,i;9rri.

;

)

;

•

Format
DEBUG [taskname)

Parameter
taskname
Specifies the name of the task you wish tQ trap. If you do not
specify a task name, the default is a task named after the
terminal from which the command was issued, such as TT56.

Example

>RUN JOE
>SHOW TASKS/ACTIVE

SHOT56

<TT56!)
CTT56!)

TT56

(TT56~)

MCR+++

>DEBUG
TE:002452

In this example, the task was bui 1 t
including OD'l'.
The user
issued the DEBUG command, which defaulted to the task named after
the terminal. The display from ODT gives the T--bit · exception
code and the address following the loc.ation. in er'ror a·na i.ssues
its prompt.
The user can proceed with debugging•
ODT is,
documented in the IAS/RSX-11 ODT Re.ference Manual.
Notes

The DEBUG command Ls useful when a task is caught ·in an inffnite
loop betwe~n ~reakp6int~ or is 'waiting foJ an fpcorrerit or·
none~istent event flag.
See the RSX.;..llM/M..;.PLUS Executive Reference Manual for,irifqrmation
on the SVOB$ .directive.
The /DEBUG qualifier to the LINK command ts equivalent to the /DA
switch on . a TKB command.
See also. th.e RSX-llM/M-PLOS .Task
Builder Manual •.

6-90

PROGRAM DEVELOPMENT

SET GROUPFLAGS
:Etror· Mess~g:e.

u~iftie 1'

*** "~a.sknqme.'~ do~s n,oi,,; ;cont,a·in a. d~bugging ?,,id

. Expl~amit:i.oA::· '- An·1 ]a.t.:t:.:e~pf:J#?s,, ina;.(fo \6:·.aebµg.·a task .. 'that : was
,: :' ·tiu.ilt 'wi,th· .a, o;e.b'.i..:fgg:ipg ·afa ..• · ·. ·.. , · ·. ·. ,·: .. ·.. ·,
<

6.6

not

SET AND SHOW

You can ~et and show group global event flags.
These are a set of 32
global event flags available only to tasks run from one group of UICs.
Otherwise, these flags are identical to other global event flags.
Event flags are used for communication between tasks.
See the
RSX-llM/M-PLUS Executive Reference Manual for further information.

6.6.1

SET GROOPFLAGS

SET GROUPFLAGS creates and deletes group global event flags.
Privileged users can create and delete group global event ·flags for
any group.
Nonprivileged users can create and delete global event
flags for the group of which they are members.

Format
SET GROUPFLAGS(/qualifier]
Flag? n
SET GROUPFLAGS:n(/qualifier]

Command Qualifiers
/CREATE
/DELETE

Command Qualifiers
/CREATE
Specifies that you wish to create a set of group global
flags.
This is the default and need not be specified.

event

n is the group with
which
the
flags
are
associatedr
Nonprivileged users can create and delete group global event
flags for their own login group.
Privileged users can create and
delete group global event flags without restriction.
/DELETE
Specifies that you wish to delete a set of group global event
flags.
n is the group with which the flags are associated.

6-91

PROGRAM DEVELOPMENT

SHOW GROUPFLAGS
Example

>SHOW GROUPFLAGS
7

200

0
0

000000
000000

>SET GROUF'FLAG
Fl as? 303

>SHOW GROUPFLAG
7

200
303

0
0

000000
000000
000000

In this example, the user first displayed all the current group
global event flags on the system and found that there were two
sets but none for the user's group, which was 303. Then the user
created a set of group global event flags for his group and
verified their presence with the SHOW GROUPFLAGS command.

6.6.2

SHOW GROUPFLAGS

SHOW GROUPFLAGS displays the group global event flags currently in the
system.

Format
SHOW GROUPFLAGS

Example

>SHOW GROUPFLAGS
7
200
201
303
333

1
1
1
1
1

000000
000000
000000
000000
000000

This example shows the display from SHOW GROUPFLAGS.
The first
column is the group number with which the flags are associated.
The second column is the access count. The two 6-digit numbers
are the octal words that give the current state of each group
global event flag.
Group global event flags are flags 65 through 96. The first word
starts at flag 80 and goes right to flag 65.
The second word
starts at flag 96 and goes right to flag 81. The final column is
reserved for the delete flag DEL, which means the group global
event flags are marked for delete and are not available.
See
Section 6.6.1.

6-92

CHAPTER 7
RUNNING TASKS

The task is the fundamental executable programming unit.
Tasks are built (linked) from one or more object modules.
Tasks on
RSX-llM/M-PLUS systems include tasks built from user programs as well
as system tasks, such as compilers or utilities.
Commands described in this chapter are used to initiate and
execution of tasks and to display the status of tasks.

7.1

terminate

TASK INSTALLATION AND EXECUTION

Tasks cannot execute unless they are installed
in the system.
The
System Task Directory
(STD), a data structure in the Executive's
dynamic storage region (pool), is the list of installed tasks.
Each
installed task is identified by a Task Control Block (TCB) in the STD.
You can display the contents of the STD with SHOW TASKS/INSTALLED.
See Section 7.12.5.
Nonprivileged users can install their own tasks through the RUN
command.
These tasks remain installed as long as they are executing,
and are removed from the system when they finish.
Privileged users
can install tasks.
These tasks can also be caused to execute with the
RUN command. The tasks remain installed after execution.
Many system tasks can be caused to execute with other commands.
For
instance, EDIT/EDT causes EDT,
the DEC Editor, to execute on your
terminal, and LINK causes the Task Builder to execute.
Installed tasks are not necessarily resident in memory or competing
for system resources. Most installed tasks are dormant, meaning they
are installed but have not been requested to run. A dormant task uses
little memory, yet it is immediately available when it is needed, such
as to service a real-time event.
Installed tasks can be in either of two states:
Dormant

Installed but not requested to run

Active

Installed and requested to run

Tasks remain active until they abort, exit, or terminate in some other
way.
During this time, they can be in one of two substates:
Ready-to-run

Competing for CPU time on the basis of priority

Blocked

Unable to compete for CPU time either because a
needed
resource
is
not
available,
or for
synchronization purposes, or through the STOP/BLOCK
command (Section 7.12.4).
7-1

RUNNING TASKS
You can display the list of active tasks with SHOW TASKS/ACTIVE.
Section 7.12.4.

See

Tasks run at priorities of from 1 through 250, with 250 being the
highest priority.
The priority of a task can be established through
the LINK, INSTALL, or RUN commands. Nonprivileged users are limited
to priority 50
in the commands they issue, but if a privileged user
has built or installed the task to run at a higher priority, then it
will run at that priority for both privileged and nonprivileged users.
Tasks can be
built,
installed,
or
run
as
checkpointable.
Checkpointable tasks are liable to being checkpointed, or rolled out
of memory to disks, in an incomplete state if a higher-priority task
needs the memory space they are occupying~
All memory is divided into partitions, which are subdivisions devoted
to a particular task or tasks or to system functions.
Partitions can
be dedicated to a single task or shared by several tasks.
If you do
not specify a partition when you install and run a task, it will be
installed in the default partition, named GEN. All partitions have a
name and a size.
Refer to the RSX-llM/M-PLUS Task Builder Manual for much more
information on how tasks are built;-installed, and run in partitions.

7.1.l

Task Naming

Tasks are installed under names from one through six Radix-50
characters.
The names identify the task in the STD.
All commands and
other operations affecting installed tasks require you to use the name
of the installed task.
Tasks acquire their installed names in a number of ways.
Many task names include the number of the terminal from which the task
was initiated. Terminal numbers are octal. Unless otherwise stated,
all commands in examples in this section are assumed to have been
issued from terminal TTlO:.
Tasks resulting from system commands are named after the command and
the terminal from which the command was issued. Thus, the following
command, issued from terminal TTlO:

>SHOW TIME
results in a task named SHOTlO in the STD while the task is executing.
Likewise, the following batch command, issued
VT4:

from

virtual

terminal

$SHOW TIME
results in a task named SHOV4 in the STD while the task is
Batch processing is, available on RSX-UM-PLUS only.
And, the following command, passed through
number 6:

DECnet

host

executing"
terminal

SHOW TIME
results in a task name SHOH6 while the task
terminal is a DECnet virtual terminal.)

7-2

executing.

host

RUNNING TASKS
For tasks that are installed and run explicitly, task names can be
established through the LINK command, the INSTALL command, and the RUN
command.
If you begin with a source file named ROBOT.MAC and use the default
LINK command after assembling the object file, you will end up with a
task image file named ROBOT.TSK.
You can install this task image in
two ways,
through the privileged INSTALL command or through the
nonprivileged RUN command.
If you issue the privileged command

>INSTALL ROBOT.TSK
you will find the task name ROBOT in the STD.
If you issue the command

>RUN ROBOT. fSK
you will find the task name TTlO
in the STD while the task is
executing.
The installation is through the install-run-remove form of
RUN, which assigns a task name based on the name of the terminal from
which the command was issued.
You can override these defaults at every step.
The TASK= option of LINK permits you to specify the name under which
you wish the task image file you are creating to be installed. If you
thus specify the installed name of ROBOTl.TSK to be EANDO when you
build the task, the privileged command

>INSTALL ROBUT1.TSK
results in the task name EANDO in the STD.
If, however, you issue the command

>RUN ROBOT1.TSK
you will again find the task name TTlO in the STD while the task
executing, despite the specification of EANDO at task build time.

The command

>RUN/TASK_NAME!EANDO ROBOT1+TSK
results in the task name EANDO in the STD while the task is executing.
Since the RUN command defaults to a task name that is based on the
terminal designation (without the colon), you must use the /TASK NAME
qualifier if you wish to use the RUN command to initiate execution of
more than one task at a time from the same terminal.
This is true
because all task names in the STD are unique;
you cannot have two
tasks named TTlO installed at the same time, for example.
See the
examples in Section 7.2.

7-3

RUNNING TASKS
Finally, most DCL and MCR commands work by running tasks, although you
do not have to issue a RUN command. The LINK command, for instance,
runs the Task Builder. Such tasks are named after the first three
letters of the command word, plus the terminal identifier. Thus, when
you issue a command such as the following:
>LINK RUMBLE

the result is a task named LINTlO.
In fact, the RUN command
results in the brief existence of a task named RUNTlO.

itself

If you are running a utility, using a command in the form
>MCf~:

F' If·

your task will have a name of the form PIPTlO.
On RSX-llM systems only, there is a possibility of a slight variation
in the task~naming rules.
If,.when you run a. utility, you are the
only user using tha_t _ utility, the utility is installed under its
prototype name, which has a name · prededed by three dots~ such as
••• PIP. Any subsequent users run the utility under a name in the form
P~PTlO.
It makes no difference to you whether you aie running the
prototype or a copy.
You never run the prototype on

RSX-llM~PLUS

systems.

See Section 7.2 for more information on including the dollar-sign
in a RUN command.

($)

On RSX-llM-PLUS systems with more than 64 terminals, tasks run from
the higher-numbered terminals cannot be named directly after their
terminals because of restrictions on the number of characters in a
t-;H~k
name.
The following discussion describes the problem and its
solution.
Remember that terminal numbers are octal. The first 64 terminals on
an RSX-UM-PLUS system are numbered 1 through 77 (octal). The system
supports as many as 256
terminals.
Terminals 65 through 256 are
numbered
100 through 377
(octal).
Tasks initiated from these
terminals cannot be named directly after their terminals, because the
task name is limited to six characters and their numbers, if used
explicitly, are too large for task names. For example, SHOT107 is an
illegal task name.
Therefore, when the RUN command is issued from terminals numbered 100
through 377 (octal), a slightly different derivation of task name~ is
employed. Assume your terminal· is. TT107:. The command
>FWN ROBOT

initiates a task named TTA7.
The letter A stand's for the first · two
digits of the . un.it number of the t,erminal, 10 in this case. To
minimize the. confusion resulting f.rqm this convention, the display
fromSHOW TASKS/ACTIVE includes .the nam,e 9f th,e· initiating terminal in
parenthe.ses next to the .nam·e. of the active tas~. · The SHOW task itself
wi11 be n.amed SH OTA 7 •.

7-4

RUNNING TASKS

RUN
, .. '

.. ·

·Th~ renumber:ing · :'s'ystem replaces title first 'two digl''ts : .of the unit
number.; wi:th 'a si·ngle•le'tter·;;: a:e're: fs' a:: full' l i t• <:>:f 'the'! p~:ssib1e' task:
n'umbeis'- .:and~: th~..;~q.uivaJent.: .'tier~i:m~l: · u.ni t.:' :n11mbe.ts,{ : , ·• .· ·
·· .

•I

~ask .~uJD~~~··· · .

·. ·.· .

. • ~~~~n~i)n~(~um;~·.:

" ··~;; :Ao:..:.'A7
tF-7 7 .: ·
: .·;

::r·.·. o•.; ..,··. :· .· .
·, ·. . · 0.·10.....
·
. :;J:lQ::;:.;117.
or.
·;:-

;..t4:07-1.~p:: . · : :
:1:so;1si.: · ·

;

•

:·go;;::.;:f,67::

;

'.":

•

·'I

· /Ko:..:rn .·

'.'.'

L'(J...:.L7'
MO-MT

~ ~

JJ ".UJ':.;12~~·

:·:10.:..p 1. :
;':.J0417
'

•.

' i fo--.l.2·7.
13·0..::.1:37:

:·

:.: oe.:01· ·
: .'.-¥ ;:E:o5?·? .,·. ;: ./: :· .·
.... :1,0.~ .1Fz ,. •..
· : : · ;;.uo·;G;7; .: · ·:; .: !
Hd ;-H'.7.' •
II

7_:·. .

;;S:Q...;;;B7:
CQ;-C,7

20.0-:.2:01.

,'. ;;

·2;ti)7~;17'. ·. ·.

;

· '2·20:;.;2·21: ~ .: .
230.:..2'37'
240:-247

I''

~O--N:'?;
00;,0]
Po..:~7

: ;·250·~~57: :·
. 26(}~267. .

·Qo:...01

· · 300-:-~01:

.RO.:..R7
, so..;;;5;7:
. TO~T7

310-317
·j20:...321· ·
330·~337:

.UO-U7

14-0-347
- ,~ , 35!0 =,~,3, 5,:7 ~ .

, --

••

: 2i.to12i1

·,v(J ~ V~7

WO-W7

3,6()..:.357

.:*9:~q:

•

.:.,.3'.7f:J~3;'17::

Only uninstalled tasks initiated with the RUN command have task names
preceded by VT, TT, or HT. Tasks initiated by other DCL commands are
named after the first three letters of the command that initiated the
task, plus a T, ·v~ or H (for physical, v~ttu~l, or DECnet host
terminal) plus the unit number.

7.2

INTRODUCTION TO THE RUN COMMAND

RUN initiates the execution of a task.
four ways:
•

This command can

used

To install, run, and remove upon execution a task from a task
image file stored in a user's UFD. This is the most common
use of the command.

•

To install, run, and remove after execution a task from a task
image file stored in the system UFD, or library UFIJ"()'n
Rsx~11M-PLUS

systems.

•

To run immediately a task previously installed by a privileged
user

•

To run at some future time, or according to a schedule, a task
previously installed by a privileged user

These functions
sections.

are

introduced

7-5

detail

the

following

RUNNING TASKS

RUN (Cont.)
The first and most common use of RUN is to initiate execution of tasks
contained in task image files.
The command

>RUN PUF'PET.TSK
directs the operating system to look in the default UFO on the default
device for a task image file named PUPPET.TSK. When the file is
found, the image is read in to memory and execution commences.
When
the task has executed, the image is removed from memory and from the
STD.
Whenever a RUN command includes any element of a
this procedure is followed.
The command

file

specification,

>HUN DBO!MUPPET
directs the operating system to look in the default directory on
device DBO:
for a file named MUPPET.TSK and install it, run it, and
remove it when it has completed execution. The default file type in
this case is .TSK, which is also the default file type for a task
image file created by the Task Builder.
The second use of RUN is to initiate execution of tasks contained in
task image files in a system UFD (on RSX-llM) ., <>r·····~ :EWsft-em . ~·.·
Hhl:'a:r~ Uffis, {onlJ~SX::::l'.lM::~LJUp}.;i
The dollar sign ($)
in a
f ilespec
indicates that you wish to use this form of RUN. The purpose of this
convention is to relieve you of the necessity of knowing exactly where
on the system various system tasks are stored. Simply include the $
in your RUN command and the system takes overG
If you receive the
error message
RUN -- File not found
or
INS -- File not found
your system manager has chosen not to include that particular task or
utility in one of these UFOs, perhaps to conserve disk space.
In this
case, see your system manager.
In general, you can use the $ to run most system tasks and utilities.
These usually have three-letter names like PIP or TKB, but the RMS-11
utilities have six-letter names like RMSDSP or RMSCNV. See the RMS-11
documentation supplied with your system for more information on
RMS-11.
(Your system manager may also have added other task image
files
not
supplied by DIGITAL to these directories for your
convenience.)
On RSX-llM systems, copies of many or all system tasks are placed in
the system UFO on pseudo device LB:. The directory is usually [1,54],
but it can be some other number. You can display the identity of this
directory with the command SHOW SYSTEM/DIRECTORY. You can list the
contents of the directory with a DIRECTORY comma~d.
On RSX-llM-PLUS systems, copies of many or al.l privileged system tasks
placed in the system UFD on. pseudo device LB:.· The directory fs
usually [ l, 54 J , but. it can·. be some other number·. You can display the
identity cf this . ~irectory with the ,command SHOW SYSTEM/DIRECTORY.
You can list the contents of the directory with a DIRECTORY command.

are

7-6

RUNNING TASKS

RUN (Cont.)
In addition, on. HSX~llM-Pto·us. systems, copie.s of many ...or .. all.
nonprivileged system tasks are placed in the . iibrary .tlFD ..on pseudo:
device LB:. The directory is usually [3,54], but ib can be some... otber
.number.
You ca.n display· the identity of this. ·airectory wi,.th' :the:
·command SHOW LIBRARY/DIRECTORY •.. You can· also list the contents C>f: ~the.
directory with a DIRECTORY command.
·
The system responds to the $ in a filespec as follows.
>RUN

The command

$ Tl\B

directs the operating system to look for a file called TKB.TSK and to
install,
run, and remove it when it has completed execution.
Since
the Task Builder is a privileged task, it will be found in the system
UFD on either RSX-llM or RSX-llM-PLUS.
The system installs, runs, and
removes TKB just like any other task •
.On. RSX.;llM~PLU.S., i f . th~ :comlll.ana · h.aa ·nam:ed .
a S in the fo ll:O:Wi ng command :

.a: nionprivi:1eged.: . task',·: :sµcb

>RUN $F'IP

the system .would still star.t by sear.cbing the system UFD, 'but;1\faili.ng~
to find PIP.TSK there, wou1d have gone on to the i·ibrary UFD ·~to se.arch·
for PIP.TSK there.

NOTE
Privileged users can also use the dollar
sign
($) with the INSTALL command. See
Section 7.8.
The third use of RUN is to execute immediately a previously installed
task.
The task must have been installed by a privileged user.
The
command
>RUN

TU~:TL..L

directs the operating system to look in the list of installed tasks
(STD)
for a
task named TURTLE.
Once the system has found the task
TURTLE in the STD, the task commences its execution.
The task need
not be installed since it is already installed, nor is it removed when
it has completed its execution. The task runs under the name TURTLE,
not TTlO.
(If the system does not find an installed task of the name you give,
command defaults to the install-run-remove form and looks in the
default UFD on the default device for a
file named TURTLE.TSK,
and
continues as described earlier.)
1..u~

Finally, privileged users can use RUN to schedule the execution
task in several forms.
Scheduling options include:
•

Run the installed task after so many hours, minutes,
or ticks.

•

Run the installed task at an absolute time of daye

7-7

seconds,

RUNNING TASKS

RUN (Cont.)
•

Run the installed task in synchronization with the next hour,
minute, second, or tick, that is, at the beginning of the next
interval.

•

Run the installed task at regular intervals.

In addition, these scheduling options can be combined.
RUN as used to install, run, and remove tasks contained in task image
files is described in Section 7.2.1. RUN as used with previously
installed tasks is described in Section 7.2.2.

7.2.1

Running Tasks Contained in Task Image Files

When used to run an uninstalled task, RUN is actually a combination
command, encompassing INSTALL, RUN, and REMOVE. This command is the
only way a nonprivileged user can install or remove a task.
Format
RUN[/qualifier[s]]
Task? [$]filespec
RUN[/qualifier[s]]

[$]filespec

Command Qualifiers
/[NO] CHECKPOINT
/COMMAND:"taskcommand"
/[NO]POSTMORTEM
/EXTENSION:n
/PARTITION:parname
/PRIORITY:n
/STATUS:arg
TASK
COMMAND
/TASK NAME:taskname
/TIME~LIMIT: n [ u]
/UIC:(g,m]
Parameter
[$]filespec
Specifies a task image file on a mounted Files-11 volume.
This
task is installed, run, and then removed when it has finished
executing.
The default file type is .TSK.

See Notes.

The dollar sign ($) directs the system to search first for the
file in the system UFD and, on RSX-ilM;;_PLUS- systems, also in the
Libra~y UFO.
In this case, the $ specifies a device and
directory and thus counts as an element of a file specification.
Command Qualifiers

These qualifiers establish how
installed.
7-8

uninstalled

task

RUNNING TASKS

RUN (Cont.)
/[NO]CHECKPOINT
Specifies whether or not the task is to be run checkpointable.
The default is established when the task is built (linked). This
qualifier is used to override the default.
In other words, this qualifier allows you to
tasks as noncheckpointable and vice versa.

run

checkpointable

/COMMAND:"taskcommand"
Use the /COMMAND qualifier to pass a command to the task you are
running.
The command must be inside the "quotes" and not more
than 40 characters long. For example, the command
>RUN I c OMMAN D: II/LI II $ p I p
runs PIP and then passes the /LI switch to it.
directory listing.

This results in a

/[NO]POSTMORTEM
Specifies whether or not a Postmortem Dump is to be generated
the task terminates unexpectedly.

The default is determined when the task is built.
If not
specified, the LINK command defaults to /NOPOSTMORTEM. See the
RSX-llM/M-PLUS Task Builder Manual for more information on
Postmortem Dumps-.~/EXTENSION: n
Specifies that n additional decimal words
allocated to a task.

address

space

/PARTITION:parname
Specifies the partition in which the task is to run. The default
is established when the task is built (linked). This qualifier
is used to override the default.
If no partition is established at task build or with the
command, the task will run in the default partition GEN.

RUN

/PRIORITY:n
Specifies at what priority the task is to run.
This is a
Privileoed aualifier.
The default is established when the task
ls built (li~ked).
This qualifier is used to override the
default.
The default priority for the Task Builder, INSTALL, and RUN is 50
(decimal).
If a task has been built or installed at another
priority, nonprivileged users can run it at that priority.
Otherwise, nonprivileged users are limited to running tasks at
the default priority.
Priorities range from 1 through 250 (decimal).

7-9

RUNNING TASKS

RUN (Cont.)
/STATUS:arg
TASK
COMMAND
Specifies whether exit status is to be returned
from the
command or
from the
task being run with the RUN command.
default is /STATUS:COMMAND and need not be specified.

RUN
The

The /STATUS:TASK qualifier may be necessary in user batch jobs
that run installed tasks where the batch processor must wait for
the installed task to exit before attempting to execute the next
command.
/TASK_NAME:taskname
Specifies the name under which the task is to be run.
The
default is to run the task under a name derived from the name of
the terminal from which the RUN command was issued, as discussed
in Section 7.1.1.
Use this qualifier when you wish to run two tasks simultaneously
using
the RUN command.
Otherwise, the second RUN command causes
the following error message to appear on your terminai:
RUN -- Task name already in use
See the examples.
Task names are restricted to six Radix-50
characters.
The
Radix-50
character set consists of the 26 uppercase letters, the
10 numerals, and the period { .) and dollar sign ($).
/TIME_LIMIT: n[ u]
This RSX-llM-PLUS qualifier allows you to limit the amount of CPU
t~me
the task ¢an run.
The default is /TIME LIMIT:3M.
The "M"
stands for minutes.
If you give simply a number as an argument,
the time unit defaults to minutes, but you can also specify a
time limit in seconds by using a number and an "S 0 ,
as in
/TIM~_LI.MIT:30S.

/UIC:[g,m]
Specifies the default UIC for the task.
This is a
privileged
qualifier.
This UIC determines in what protection class the task
belongs, and thus determines file access.
The square brackets are required syntax.

Examples

>RUN
Task"!'

F:OBOT

This example installs,
runs,
and
removes upon completion of
execution the
task contained
in ~ne
~d~K
image file named
ROBOT.TSK from the default UFD on the default device.

7-10

RUNNING TASKS

RUN (Canta)
>RUN ROBOT
>RUN ROBOT+Hl!\

The two commands in this example
command in the previous example.

are

the

equivalent

the

The following examples illustrate the task-naming convention.
See Section 7.1.1 for more information on task naming.
On RSX-llM systems1 t~e 't.ermil),~1 ·number · i!l: ,·parentheses

disp+:ay~d ~ ·

not·

· ' "'

j:Q~,: ;~S,Xf1~;.lfM+R~iG?J.ii~.r.~.~~·ln!~·;?'t.\t,ii~.:·i;:.~~.~fu;~;~~pi· j:·n.~li¢fd'i.1i.~;:·:;··.;·.~:f;~~~~se~.?

.: i.na:tc::a;tes .: ( }t'he .: ·te:nn;t:n:a:i: /,:fr~:· ;i~h!iqhJ. tb~.,: .t.:.
)~bits' exampl'.e~~ ,·tfi:e ·~ern\;foal ·'nbni&e.r: i~ <1·ow~r
"t.h~ ,•next exampl,e •. ,· "
. , · · .:
'
'., :.
*'

r ,;· -: :;'·'
;'.~

~::

~'.~

·,~

,;-·

· ·" ,

~~-

s.·: i.t:r:e:· be:J.:ng:"runi.·: In
~~'. ::?tJ:; (odt~:J) ~;.: .:/ :s~~'.

~;s H:~:J·; .l;t~t1~iV~:i 1':c
;~

M:CFi:. ,:+··;· : ;·
;: :,SHO·--r:·fo\7

f·

.;>,

~;, ~ '

··.TTtA7.·
Thi~'. ~~9mple· ·. is,, ~.or..
ta,sk-.n~mi.ng , ponvention . q·s;

only .. ~nd . llusf;:rateS• .:the
.applied fr.om .a terminal· with a unit·
n:Um;·ber· .grea.ter them 77 .{octal) ,'·in:· 'thi's · <;asei. · .'I'Tl<r7::· ~ .N()ti:c~ :.the :
name given· to: the.· saow. tas.k'. ·
>RLJN/TASK_NAME:CAPEK ROBOl
>SHOW TASKS/ACTIVE
MCR •••

SHOT10
CAPEK

:'.<·r:r:io :.:).:.

.'(. :ft i. o\··>:·.

; {;rH:Q>; ~

This example shows how the task-naming convention can
be
overridden for the RUN command by running the task under another
name using the /TASK_NAME qualifier.
>RUN ROBOT
>SHOW TASKS/ACTIVE
MCR
<THO :;J
SHOT10
<HJO:>
TT 10
cr"'r1ot:;·
>RUN t-18 I MOV

+..

RUN -- Task name alreads in use

>RUN/TASK!BINDER ASIMOV
>SHOW TASKS/ACTIVE
MCR...
<TT10:>

sHoTlo:

cn1on

TT10

£TT10:>

BINDER

<ITH>:)

This example shows how you can run two tasks simultaneously using
the RUN command and the /TASK_NAME qualifier.

7-11

RUNNING TASKS

RUN (Cont.)
Notes
The return of the implicit monitor prompt (>) signifies that the
task initiated by the RUN command has exited.
However, you need
not wait for the prompt to return to issue another command.
Simply enter a carriage return or CTRL/C and enter the command.
This section describes RUN as it works with any portion of a file
specification included.
In general, you do not have to include
the file type, as
.TSK is the default.
In one
unusual
circumstance, however, you must explicitly enter a file type.
If
there is a task already installed in the system that has the same
task name as the file name of the task image file containing the
task you wish to run, the RUN command will run the installed task
rather than the one you wish to run.
In such an instance, you
must include the file type to force the RUN command to access the
task image file.
Some error messages resulting from RUN are labeled INS rather
than RUN because this form of RUN installs the task automatically
and the error occurs during the installation.

Running and Scheduling Installed Tasks

7.2.2

RUN also initiates the execution of installed tasks.
Privileged users
can use RUN to initiate the execution of installed tasks on a schedule
by creating entries in the system clock queue.
Tasks that run as a result of entries in the clock queue run with
pseudo device COO:
as their TI:.
For this reason, these commands are
privileged.
Such tasks send output to COO:
and not to the terminal
they were run from.

Format
RUN[/qualifier[s]]
Task? taskname
RUN[/qualifier[s]]

taskname

Command Qualifiers
/DELAY:nu
/INTERVAL:nu
/SCHEDULE:hh:mm:ss
/STATUS: COMMAND
TASK
/SYNCHRONIZE:u
/UIC: [ g ,m]

Parameter
taskname
Specifies the name of the installed task to be run. The names of
installed tasks are one through six Radix-50 characters.

7-12

RUNNING TASKS

RUN (Cont.)
If the System Task Directory (STD) contains no entry under the
task name you supply, the system searches the default directory
on the default device for a file named taskname.TSK.
If RUN
finds such a file, it installs, runs, and removes it.
Command Qualifiers
The time-oriented qualifiers to RUN create entries in the system
clock queue.
The contents of the clock queue can be displayed
with the command SHOW CLOCK_QUEUE. See Section 7.12.9.
/DELAY:nu
Specifies that the task be run after the stated amount of time
passes. This qualifier is privileged. The argument nu specifies
the amount of the delay as a number of units. n is the number of
units and u is the time unit as follows:
T S MH -

Ticks
Seconds
Minutes
Hours

If your system has the standard line-frequency clock, the length
of a tick depends on the line frequency of the electric power
source serving your location. Most commonly, this frequency is
60 Hz, which results in a tick length of l/60th of a second.
If your system has an optional programmable clock, the length of
a tick depends on the choice made at system-generation time. See
your system manager for more information.
Acceptable values for these units are as follows:
T - Any positive value to a maximum of 15 bits, or 32767.

s - Any positive value to a maximum of 15 bits, or 32767.
M - The maximum value is 1440.
H - The maximum value is 24.
The system always waits at least one interval.
the system treats it as a 1.

If you specify O,

/INTERVAL:nu
Specifies that the task is to be run at regular intervals.
This
qualifier is privileged. The argument nu specifies the interval
as a number of units of time. n is the number of units, and u is
the unit as follows:
T S MH -

Ticks
Seconds
Minutes
Hours

See the /DELAY qualifier for
units.

7-13

detailed

description

these

RUNNING TASKS

RUN (Cont.)
/SCHEDULE:hh:mm:ss
Specifies that the task be run at a particular time of day.
is a privileged qualifier.

This

/STATUS:arg
COMMAND
TASK
Specifies whether exit status is to be returned from the RUN
command or from the installed task being run with the RUN
command. This is not a privileged qualifier.
The default is
/STATUS:COMMAND and need not be specified.
The /STATUS:TASK qualifier may be necessary in user bat~h jobs
that run installed tasks where the batch processor must wait for
the installed task to exit before attempting to execute the next
command.
See the examples using /STATUS:TASK.
/SYNCHRONIZE:u
Specifies that the execution of the task be synchronized on the
next occurrence of a particular clock unit.
This is a privileged
qualifier. u is the time unit as follows:
T S M H -

Ticks
Seconds
Minutes
Hours

See the /DELAY qualifier for
units.

detailed

description

these

/UIC:[g,m]
Specifies the default UIC for the task.
This is a privileged
qualifier.
The task's UIC determines what file-protection class
it belongs in, and thus directly influences file access.
The square brackets are required syntax.
Examples

>RUN/DELAY:5S PINBAL
This example initiates execution of the installed
five seconds after the command is entered.

task

PINBAL

task

WIZARD

task

TOMMY

>RUN/INTERVAL:20M WIZARD
This example initiates execution of the installed
immediately and every 20 minutes thereafter.

>RUN/DELAY:10M/INTERVAL:1H TOMMY
This example initiates execution

the

installed

after ten minutes and every hour thereafter.

7-14

RUNNING TASKS

RUN (Cont.)
>RUN/SCHEDULE:12:00:00 NOON

This example initiates execution of the installed task NOON at
the next 12:00:00 after the command is entered.
If you entered
the command before noon today, NOON would run at noon today.
If
you entered the command after noon today, NOON would run at noon
tomorrow.

>RUN/SYNCHRONIZE!H BOGUS
This example initiates execution of the installed task named
BOGUS on the next hour.
If you entered the command at 9:15,
BOGUS would begin running at 10:00:00.
>RUN/SYNCHRONI!..E: H/INlE.r~t.JAI... ! lH BEL.TUL

This example initiates execution of the installed task named
BELTOL every hour on the hour, starting with the next hour.

$INSTALL $HIFI
$RUN/STATUS:TASK HIFI
$EOJ
This example illustrates the use of the /STATUS:TASK qualifier in
a
user batch job.
First the job installs the task HIFI from the
library UFD.
Then the task is run.
If the user had
not
included the /STATUS:TASK qualifier, the RUN command would have
returned a status of success,
the batch processor would have
executed the EOJ, and the EOJ would have aborted the task that
had just started running. With the qualifier,
the EOJ is not
executed until after the task has exited.
See next example.

$INSTALL CAVIAR
$RUN/STATUS:TASK CAVIAR
$PRINT/FLAG_PAGE FISHEGGS.LST, SHADROE.LST

This example also
illustrates the use of the /STATUS:TASK
qualifier in a user batch job.
First the job installs the task
CAVIAR.
When run, this task writes
two
listing
files,
FISHEGGS.LST and SHADROE.LST.
After these files have been
written and closed, the batch job prints them both.
With the
/STATUS:TASK qualifier on the RUN command, the batch processor
waits for the installed task CAVIAR to exit before attempting to
print the files.
Without the qualifier, the batch processor
would attempt to print the files while they were still being
written.

7-15

RUNNING TASKS

ABORT
Notes
The implicit prompt returns immediately after you issue a RUN
command for an installed task and does not indicate that the task
has completed its execution.
You can display entries in the clock queue with SHOW CLOCK_QUEUE,
Section 7.12.9.
The clock queue is kept in pool and must be restored whenever the
system is rebooted.
Error Message
RUN -- Invalid time parameter

7.3

Explanation:

Command specified an invalid time argument.

user Action:

Check for proper syntax and reenter command.

ABORT

ABORT forces an orderly end to a running task or to the
specific command.

action

Tasks can also be aborted by other tasks or by error-handling
routines.
If this happens, some of the messages discussed below can
appear on your terminal without your having issued an ABORT command.
Nonprivileged users can abort any task
users can abort any task.

running

TI:.

Privileged

you

are

aborting

Format
ABORT[/COMMAND] [/qualifier[s]]
ABORT/TASK[/qualifier[s]]

commandname

[taskname]

Command Qualifiers
/COMMAND
/TASK
/TERMINAL:ttnn:
/[NO]POSTMORTEM
Parameters
The parameters differ depending on whether
command or a task.
The default is to abort a command.

See the examples.

commandname
Specifies the command whose effect you wish to cancel.
This
parameter can be used only when the /TASK qualifier is not
present. You must specify at least the first three characters of
the command verb.

7-16

RUNNING TASKS

ABORT (Cont.)
task:name
Specifies the name of the task you wish to abort.
This parameter
requires the presence of the /TASK qualifier.
If you use the
/TASK qualifier and do not specify a task name, you will get an
error message, "Illegal task name."

Command Qualifiers
/COMMAND
Specifies that you wish to abort a command.
qualifier and need not be included.

This is the

default

/TASK
Specifies that you wish to abort a task by name.
/TERMINAL:ddnn:
Specifies that a task from some terminal other than your own be
aborted.
This is a privileged qualifier for RSX-llM-PLUS only.
/[NO]POSTMORTEM
Specifies that a Postmortem Dump be taken (or not taken)
of the
task before it is aborted.
See the RSX-llM/M-PLUS Task Builder
Manual for more information.
If the task is memory-resident, the contents of its registers are
listed on the terminal.
If it is checkpointed, no register
contents are listed.
You can specify a Postmortem Dump when you build a task or when
you install
it {including install-run-remove).
The default for
this qualifier is determined by previous specification of the
/DUMP qualifier.
If no /POSTMORTEM qualifier has been specified,
the default is /NOPOSTMORTEM.

Examples
>ABO RUN
11:11:11 Task 1 TTl0 1 terminated
Aborted via directive Cl!:~ CL.I
This example aborts a task initiated with the RUN command running
on your terminal.
See next example.

>RUN H:EK
ORDERS: STAR DATE = 2000
YOU MUST DESTROY THE KLINGON INVASION FORCES OF 29 BATTLE
CRUISERS. YOU HAVE 40 SOLAR YEARS TO COMPLETE YOUR MISSION.
RE A [I y ?

[CTRL c

DCU·ABORT RUN
12:11:09 Task TT10 terminated
Aborted via directive or CLI
1

In this example, the user installed the interactive task TREK by
means of a RUN command.
Then, instead of providing the task with
requested input, the user issued a CTRL/C to return to the DCL

7-17

RUNNING TASKS

ABORT (Cont.)
monitor level and then issued the ABORT command.
DCL prompted
for the command to be aborted and RUN was specified.
The task
was aborted and removed, and the message displayed.
The message
mentions MCR because DCL does not actually perform the abort.

>ABORT/TASK

MACT~

This example aborts the task named MACT3.
Nonprivileged users
can abort tasks running on their own terminals.
Privileged users
can abort tasks by name running on any terminal.
See next
example.

>DIRECTORY

*·R~O

Directors DB2![303,5J
2 0 -- NQ\I -·· 8 2 1 6 : 2 8

27--i-"-\UG-·82 16: 52
ALTCLI.RN0;3
213.
30-JUL--82 O'i: :·50
ANNI.RN0;6
3.
l '.:.•-- t:1f' R-B ~~ i 0: 3~:i
APRCOM.RN0;4
9.
2 8 -- .~ UG··- 8 2 1 5 ; '5 0
BEST.RNo;s
40.
~2--MAY-82 i'.Vi' t y;;·
CATCH.RNQ;4
7.
1 ~3 -- 0 CT -- 8 2 1 <.) ~ :fo
CHAP11SMG.RN0;13
49.
08--0CT-82 L5: l~5
CHAP12SMG.RNQ;51
223.
15--JUN--82 11!57 tTRLc)
CHARSET.RN0;5
6.
DCL>ABORT DIRECTORY
16!29!45 Task •n1RT56
terminated
Aborted via directive or CLI
1

>
In this example, the user issued a DIRECTORY command and soon saw
that the file he was checking for was present.
Rather than wait
for the directory listing to complete, the user typed CTRL/C and
entered the ABORT command in response to the explicit DCL prompt.
The ABORT command defaults to ABORT/COMMAND.

>ABORT/TERMINAL!TT3!

MACRO

This example, issued by a privileged user, aborts the MACRO task
running on another terminal.
Notification of the abort appears
on TT3:
but not on the terminal from which the ABORT command was
issued. RSX-llM-PLUS only.

>ABORT/DUMP RUN
14!41!11 Task •1110
~ terminated
Aborted via directive or CLI
RO==OOOOOO

R1=10007?

R2=135600
R3=000000
R4=:00000J
1~5::'.:000000
sp;:~o12s40

PS=:l.70017

>
In this example, the user
requested a Postmortem Dump.
The
contents of the task's registers at the time of the abort are
7-18

RUNNING TASKS

ABORT {Cont.}
listed on the terminal along with notification of the dump.
dump file will be printed on the system's line printer.

The

Notes
A is the short form of ABORT.
ABORT forces an orderly termination of a task.
termination, the system performs four steps:

effect

the

•

Alters the task's priority to 247. A task must be memory
resident to be aborted.
This step usually forces the
quick return of a checkpointed task.

•

Performs I/O rundown:
cancels I/O for nonfile-structured
devices;
completes I/O for file-structured devices and
deaccesses files;
detaches all attached devices.

Notification
program
the Task Termination
• Executes
which displays messages on the aborted task's
(TKTN)
I

TI:.
•

Releases any memory allocated to the task if the task
not fixed.

The TKTN routine can list a number of messages about
These messages are explained below.

the

abort.

LOGOUT

from

your

also

aborts

nonprivileged

tasks

running

terminal~

Tasks can also be aborted by Executive directives issued by other
tasks, in particular, by error-handling routines.
TKTN Messages
These messages appear as part of the notification of the abort.
Often
a
list
of
register
contents also is displayed.
Understanding these messages requires an understanding of how the
PDP-11 executes instructions.
If you receive these messages and
do not understand them, you should copy them, along with any
other terminal output, and show them to your system manager.
Aborted via directive or CLI
Explanation: Either a CLI or an Executive directive
another task caused the task to be aborted.

issued

the

AST

AST abort. Bad stack
Explanation: An AST could not be effected
parameters could not be pushed on the stack.

because

Checkpoint failure. Read error
Explanation: The task could not be read back into
being checkpointed.

7-19

memory

after

RUNNING TASKS

ABORT (Cont.)
IOT execution
Explanation: The task executed an IOT instruction,
routine was specified to process the trap.

and

SST

Load failure. Read error
Explanation:
error.

The task could not be loaded because of a

hardware

Memory protect violation
Explanation: The task encountered a memory-protect violation and
no SST routine was specified to process the trap.
Non RSX EMT execution
Explanation: The task executed an EMT instruction with an
argument other than 377 (octal) or, in the case of a privileged
task switching to system state, 376 (octal), and no SST routine
was specified to process the trap.
Odd address or other trap four
Explanation: The task executed a word instruction with an odd
address, or it referenced a nonexistent memory location, and no
SST routine was specified to process the trap.
Parity error
Explanation: A parity error occurred while the
task
was
executing.
The task was fixed in memory so that the memory could
not be reused by another task.
Reserved INST instruction
Explanation: The task executed an illegal instruction,
SST routine was specified to process the trap.

and

the

SST

SST abort. Bad stack
Explanation: An SST could not be effected because
parameters could not be pushed onto the task's stack.
Task exit with outstanding IO
Explanation: The task exited with one or more outstanding I/O
requests.
Tasks should terminate all I/O operations before
exiting. The system does, however, clean up all outstanding I/O.
T bit trap or BPT instruction
Explanation: The task either set the T bit in the Processor
Status Word or executed a BPT instruction, and no SST routine was
specified to process the trap.
Trap execution
Explanation: The task executed a Trap instruction,
routine was specified to process the trap.

7-20

and

SST

RUNNING TASKS

CONTINUE
Error Messages
ABO -- Task marked for abort

Explanation: A previous command requested that the task be
aborted, but the abort has not yet completed.
This may mean the
task marked for abort is not currently resident in memory.

user Action:

None.

ABO -- Task not active

7.4

Explanation:

The specified task is not currently active.

User Action:

Check command for proper task name and reenter it.

CONTINUE

CONTINUE resumes execution of a previously suspended task.
Nonprivileged users can continue tasks initiated from their
terminals. Privileged users can continue any suspended task.

own

Format
CONTINUE [/TERMINAL: ddnn:]

[ taskname]

Command Qualifier
/TERMINAL: ddnn:

Parameter
If you do not supply a
parameter, the task
running
terminal initiated by the RUN command is continued.

your

Tasks are suspended through the execution of a SPND$S directive
within the task.
A RSUM$ directive is another way of continuing
a suspended task.
taskname
Specifies the suspended task you wish to continue.
If you do not
specify a
task name,
the default is a task named after the
terminal.

Command Qualifier
/TERMINAL: ddnn:
Allows you to continue a suspended task running on some other
terminal.
This is a privileged qualifier for RSX-llM-PLUS only.

7-21

RUNNING TASKS

CANCEL
Example

>RUN YOYO

"Messase from Yowo:

Yowo is suspended"

>SHOW TASK/ACTIVE TTlO
TT10

070530

STATUS!

GEN

00677100-00701600

PRI - 50.

DPRI - 50.

-CHK SPN -PMD REM MCR

TI - TT10!
IOC - O.
EFLG 000001 000000 PS 170000 PC 001254
REGS 0-6 001372 000037 000012 140311 001254

>CONTINUE

"Messase from Yowo:

Not susPended. Climbins strins•

>
In this example, the user ran a task that issues a message and
then suspends itself.
Not all suspended tasks issue such
messages, but you can identify a suspended task through SHOW
TASKS/ACTIVE.
The user issued SHOW TASKS/ACTIVE and named the
task.
Included in the listing under STATUS on the second line
the mnemonic SPN verifies that the task was suspended. The user
issued CONTINUE without naming the task.
Since ~ne task was
initiated by RUN, CONTINUE defaulted to a task name based on the
name of the terminal.

Notes
A task cannot suspend any task other than itself.
For more information on task
Executive Reference Manual.

states,

see

the

RSX-llM/M-PLUS

Batch jobs may include the noninteractive form of CONTINUE as a
no-operation command.
See the RSX-llM-PLUS Batch and Queue
Operations Manual for more information.

Error Message
CON -- Task not suspended

7.5

Explanation:

Command attempted to continue an unsuspended task.

User Action:

None.

CANCEL

CANCEL eliminates entries from the clock queue.
Entries are placed in
the clock queue through the RUN$ directive or from the privileged
time-based forms of the RUN command.
Nonprivileged users can only cancel entries from a task initiated from
the entering terminal.
Privileged users can cancel any clock queue
entries.
CANCEL does not affect a currently
pending entries in the clock queue.

7-22

executing

task,

but

only

the

RUNNING TASKS

STOP/BLOCK
Format

CANCEL
Task? taskname
CANCEL taskname
Parameter

taskname
Specifies the name of the installed
entries you wish to eliminate.

task

whose

clock-queue

Example

>RUN/DELAY:5M ARDVRK
>SHOW CLOCK_QUEUE
ARDVRK Scheduled at 17-JUL-82 10!44!31;09
>CANCEL ARDVRK
>SHOW CLOCK_QUEUE
.>

In this example, the user issued a command to run the installed
task ARDVRK at exactly five minutes from when the command was
entered. The user verified that ARDVRK was in the clock queue
(as the only entry) • Then the user issued the CANCEL command to
eliminate the scheduled run of ARDVRK. The user issued a second
SHOW CLOCK QUEUE to verify that the scheduled entry was cleared~
If ARDVRK had been running at the time, the CANCEL would have had
no effect.
Notes

See Section 7.12.9 for information on SHOW CLOCK_QUEUE.

7.6

STOP/BLOCK

STOP/BLOCK blocks an installed running task.
The task no longer
executes or competes for memory. Nonprivileged users can block tasks
running from their own terminals.
Privileged users can block any
task.
Format

STOP/BLOCK [/qualifier]

[ taskname]

Command Qualifier

/TERMINAL: t tnn:
Parameter

taskname
Names the task to be blocked. If you do not name a task, the
task initiated with the RUN command and named after the terminal
is blocked.

7-23

RUNNING TASKS

STOP/BLOCK (Cont.)
Command Qualifier
/TERMINAL:ttnn:
This is a privileged qualifier for RSX-llM-PLUS only.
Specifies
that a task running from the named terminal is to be blocked.

Example
>RUN ADVENT
>SHO TASK/ACTIVE
MCR •••
SHOTS
TT5

>STOP/BLOCK
>SHOW TASK!TT5/FULL
TT5
100604
GEN
073464 00541000-005436 PRI - 50.
DPRI 50.
STATUS:
BLK -CHK WFR -PMD REM MCR
TI - TT5:
IOC - O. BIO - O.
EFLG - 000001 000000 PS - 170000
PC - 002206 REGS 0-6 001637 040066 040060 140311 163500 000000 001252

>
>

>SiARi/UNBLOCK

>SHOW TASK:TT5/FULL
TTS
100604
GEN
073464 00541000-005436 PRI - 50. DPRI - 50.
STATUS:
-CHK WFR •PMD REM MCR
TI - TT5:
IOC - 1. BIO - O. EFLG - 000001 000000 PS - 170000
PC - 002206 REGS 0-6 006173 042066 040060 140311 163500 000000 001260

>
In this example, the user on terminal TT5:
ran a task with the
RUN command, giving the task the name TT5 by default.
The user
then issued the STOP/BLOCK command, without naming the task. The
/FULL display from SHOW TASKS shows task TT5's status as blocked
(BLK flag).
Then the user issued the START/UNBLOCK command and
checked the status again.
This time, the BLK flag is not
present.

Notes
The START/UNBLOCK and ABORT commands
canceling the STOP/BLOCK command.

are

the

only

means

A blocked task has an effective priority of O.
If it is
checkpointable, any task can checkpoint it.
Once checkpointed,
the blocked task stays checkpointed because it is ineligible to
compete for memory.
A blocked, checkpointed task is unblocked
when it is aborted.
A task can also be blocked by the system while waiting
needed resource or for synchronization purposes.

for

some

There are no prompts from this command.
See Section 7.12.3 for an explanation of the task status flags.
There are several STOP/function commands associated with the
Queue Manager.
See the RSX-llM/M-PLUS System Management Guide.

7-24

RUNNING TASKS

START
STARVUNBLOCK
7.7

START

The START command resumes execution of a task that was stopped by the
STOP$S directive. Note that starting a stopped task is different from
continuing a suspended onee
Format
START[/TERMINAL:ddnn:]

[taskname]

Parameter
taskname
Specifies the name of the task you wish to start. If you do not
specify a taskname, the task running at your terminal that was
initiated by the RUN command is started, that is, a task named
after your terminal.
Command Qualifier
/TERMINAL:ttnn:
The /TERMINAL qualifier allows a privileged user to
stopped task that is running on some other terminal.

start

Notes
Several other forms of the start command are used to control the
Queue Manager. See the RSX-llM/M-PLUS Batch and Queue Operations
Manual and the RSX-llM/MPLUS System Management Guide for more
information.

7.7.1

START/UNBLOCK

START/UNBLOCK continues the execution of a task blocked by the
STOP/BLOCK command. Nonprivileged users can unblock any task running
from their own terminal. Privileged users can unblock any task.
Format
START/UNBLOCK[/qualifier]

[taskname]

Command Qualifier
/TERMINAL:ttnn:
Parameter
taskname
Names the task to be unblocked. If you do not name a task, the
task initiated with the RUN command and named after the terminal
is unblocked, if blocked.

7-25

RUNNING TASKS

INSTALL
Command Qualifier
/TERMINAL:ttnn:
This is a privileged qualifier for RSX-llM-PLUS only.
Specifies
that a task running from the named terminal is to be unblocked.

Notes
See the description of STOP/BLOCK for an example.
START/UNBLOCK does not unblock tasks blocked by the Executive
while waiting for system resources or for synchronization. You
can only unblock tasks blocked with the STOP/BLOCK command.
The START/UNBLOCK and ABORT commands
canceling the STOP/BLOCK command.

are

the

only

means

The system automatically unblocks a blocked task when the blocked
task is aborted.

7.8

INSTALL

INSTALL includes a specific task in the System
making it known to the system.

Task

Directory,

thus

An installed task is dormant until it is requested to run by the
Executive.
You can request an installed task to run through the RUN
command or through a variety of Executive directives, including RQST$
(Request) , RUN$ (Run) , and SPWN$ (Spawn) •
This is a
privileged command.
Nonprivileged users install tasks
temporarily through RUN, which includes most of the same qualifiers as
INSTALL.
See Section 7.2.

Format
INSTALL[/qualifier[s]]
File(s)? [$]filespec
INSTALL[/qualifier[s]]

[$]filespec

Command Qualifiers
/[NO] CHECKPOINT
/COMMAND:"taskcommand"
/[NO]POSTMORTEM
/EXTENSION:n
/MULTIUSER PARTITION:parname
/PARITITION:parname
/PRIORITY:n
/READONLY COMMON
/[NO]SLAVE
/TASK NAME:taskname
/UIC:[g,m]

7-26

RUNNING TASKS

INSTALL. (Cont.)
Parameter
[$] filespec

Specifies the name of the task image file containing the task you
wish to install. .TSK is the default file type. The dollar sign
{$), if present, directs the system to search for the file in the
system UFD 'apd,:,,,, c?n' ~;:>>t-~Jl'·1hP;E.J1,S, ~;yst~m,s;,; ,;:'.fn }1:,h~, ,:'].;ib:tary' UFf),;~ I f
you do not include the /TASK NAME qualifier, the task will be
installed under a name based on the first six characters of the
file name unless another name was assigned through the TASK=
option of the Task Builder. See examples.
1

Command Qualifiers
/[NO]CHECKPOINT
Specifies whether or not the task is to be checkpointable.
The
default is set at link time.
This qualifier overrides the
link-time checkpointability specification.
/COMMAND:"taskcommand"
Use the /COMMAND qualifier to pass a command to the task you are
installing. The command must be inside the "quotes" and not more
than 40 characters long. For example, the command
>INSTALL/COMMAND:" /LI" $PIP
installs PIP and then passes the /LI switch to it.
in a directory listing.

This

results

/[NO]POSTMORTEM
Specifies whether or not a Postmortem Dump {PMD) is to be
generated if the task aborts because of an SST error condition.
The default is set at link time. This qualifier overrides the
link-time specification.
See the RSX-llM/M-PLUS Task Builder
Manual for further information.
/EXTENSION:n
Specifies that n (octal) additional words of address space are to
be allocated to a task.
/MULTIUSER_PARTITION:parname
Specifies the partition into which the
multiuser task is to be installed.

read-only

portion

/PARTITION:parname
Specifies the partition into which the task is to be installed.
The default is set at link time. This qualifier overrides the
link-time specification.
If you name a partition that does not exist, you receive a
warning message and the system attempts to install the task in
the default partition GEN.

7-27

RUNNING TASKS

INSTALL (Cont.)
/PRIORITY:n
Specifies the priority at which the task is to run. The default
is set at link time.
This qualifier overrides the default set at
link-time. n can be from 0 through 250.
/READONLY_COMMON
Specifies that a common region is to be installed as a
common.

read-only

/[NO]SLAVE
Specifies whether or not the task is to be slaved.
Data sent to a slaved task is marked with the TI: of the sending
task. When the installed task receives the data, the system sets
The default is
the task's TI:
to that associated with the data.
set at link time.
This qualifier overrides the link-time
specification.
Note that data may not be sent to a
virtual terminal.

slaved

task

running

/TASK_NAME:taskname
Specifies the name by which the task is to be referenced.
The
default is set at link time.
This qualifier overrides the
link-time specificatione See examples.
/UIC:[g,m]
Specifies the default UIC for the task.
This task UIC determines
in what protection class the task belongs and thus directly
influences file access.
The brackets are required syntax.

>INSTALL FATE
This example looks for a task image file named FATE.TSK on the
default device and in the default UFD and installs it as FATE in
the STD, assuming no other name was specified at link time.

>INSTALL $LATE
This example looks in the system UFD (by convention, [1,54]) and,
on RSX-llM-PLUS systems, the library UFD (by convention, [3,54])
for a task image file named LATE.TSK and installs it as LATE in
the STD, assuming no other name was specified at link time.
>INSTALL BUCKING

This example looks for a task image file named BUCKING.TSK on the
tiefault device and in the default UFD, and installs it as BUCKIN
in the STD, assuming no other name was specified at link time.

7-28

RUNNING TASKS

INSTALL (Cont.}
>INSTALL/TASK:DOOR GATE
This example looks on the default device in the default UFO for a
task image file named GATE.TSK and installs it as DOOR in the
STD, overriding any task name specified at link time.
>INSTALL/PARTITION!LEROY KILROY
This example installs the task image file named KILROY.TSK
partition named LEROY.

>INSTALL/CHECKPOINT!POSTMORTEM/PRIORITY:75/TASK!LARGO KEY
This example looks for a task image file named KEY.TSK in the
default location and installs it in the STD under the name LARGO.
The task is installed as checkpointable and at a priority of 75
(decimal).
If the task should exit unexpectedly, a Postmortem
Dump is generated.
Notes
REMOVE counteracts INSTALL.

See Section 7.9.

Tasks can also be installed through the install-run-remove form
of the RUN command. Such tasks remain installed only while they
are executing.
While such tasks are installed, they are similar to other
installed tasks. You cannot, however, count on the presence of a
task installed through install-run-remove.
Several situations require tasks to be explicitly installed
through INSTALL.
If you wish for other tasks to be able to
communicate with the task while it is not active, it must be
installed. If you wish to run the task on a schedule, it must be
installed and then scheduled using the RUN command. If a task is
commonly used, you may wish to sacrifice pool space to improve
system performance by installing the task.
You can display the attributes of installed
TASKS/INSTALLED. See Section 7.12.5.

tasks

with

SHOW

Explanation: Command attempted to access a common that
installed specifying a protection status that excludes you.

was

User Action: Find out why protection
fashion and proceed accordingly.

that

Error Messages
INS -- Access to common block denied

was

established

INS -- Addressing extensions not supported
Explanation: Command tried to install a task with a VSECT
(virtual section) in a system that does not support this feature.
User Action:

None.

7-29

RUNNING TASKS

INSTALL {Cont.)
INS -- Base address must be on 4K boundary
Explanation:
4K boundary.

The base virtual address of the task was not

User Action:

Relink the task.

Explanation: A nonprivileged user attempted to
install
privileged task through the install-run-remove form of RUN.

INS -- Can't install privileged task from non-privileged terminal

User Action:
INS

None.

Checkpoint area too small
Explanation: The area allocated for checkpointing the task was
smaller than the partition into which the task was being
installed.
User Action: Allocate
more
checkpoint
DEVICE/CHECKPOINT and reenter the command.

space

using

SET

INS -- Checkpoint space too small, using checkpoint file
Explanation: Warning message.
The checkpoint space allocated in
the task image file
is too small for
the size of the task
(probably because of the /EXTENSION qualifier).
The system
supports
dynamic
allocation of checkpoint space and will
therefore use a checkpoint file on the volume to contain the task
if it must be checkpointed.
User Action: None necessary. The task can be relinked with more
checkpoint space, or you can remove it and reinstall it with a
different value for /EXTENSION if you wish.
INS -- Common block not loaded common-name
Explanation: The specified common block was linked to
but had not been installed.
User Action:

the

task

Install the common block, then install the task.

INS -- Common block parameter mismatch common-name
Explanation: Parameters of a common block did not match those in
the task's label block.
User Action:

Correct the mismatch.

INS -- File not contiguous
Explanation: Command attempted to install a task
from
a
noncontiguous file.
Task images must be contained in contiguous
files.
User Action: Make sure you
Reenter the command.

have

7-30

specified

the

correct

file.

RUNNING TASKS

INSTALL (Cont.)
INS

File not task image
Explanation: Command attempted to install a
task from
whose label block indicated it was not a task image.
User Action: Make sure you
Reenter the command.

have

specified

the

correct

file
file.

INS -- Illegal device ddnn:
Explanation: Warning
message.
The
device
specified
at
task-build time by the ASG option is not in the system.
The task
will be installed but may not execute as you wish.
User Action:
accordingly.

Determine

the

impact

the

omission

and

act

Explanation: Command specified a device that
task-residence device.

was

valid

User Action: Make sure
reenter command.

proper

device

and

INS -- Illegal device/volume

you

specified

the

not

INS -- Illegal first APR
Explanation: A privileged task, built to run using APR 4 or 5 as
its base, was too large.
Using APR 4, the task was larger than
12K; using APR 5, the task was larger than 8K.
If the Executive
has been built to support 20K of address space, APR 5 is the only
valid base APR for tasks mapping into the Executive.
A
privileged task that does not map into the Executive must use APR
0 as its base.
User Action: See the RSX-llM/M-PLUS Task Builder Manual for a
description of the /PR keyword (/PRIVILEGED qualifier to LINK).
INS -- Illegal priority
Explanation: Command specified a priority value of less
or greater than 250.
User Action:

than

Reenter command after checking proper syntax.

INS -- Illegal use of parname partition or region
Explanation: Command attempted to install task
secondary pool partition.
User Action:

into

CPU

Reenter command, specifying proper partition.

INS -- Length mismatch common block blockname
Explanation:
The length parameter for the common block, as
described
in the label block for the task image, did not match
the length parameter defined in the system. A task's label block
data must match system data
for
that task before it can be
installed.
User Action:

See your system manager.

7-31

RUNNING TASKS

INSTALL (Cont.)
INS -- No checkpoint space, assuming not checkpointable
Explanation: Warning message on systems that do not support
dynamic allocation of checkpoint space. Command attempted to
install the task as checkpointable, but the task was not built as
checkpointable and therefore had no checkpoint space allocated.
Since the system does not support dynamic
allocation
of
checkpoint space, the system considers the task to be not
checkpointable.
User Action:
If
checkpointable=

you

wish,

you

can

the

relink

task

INS -- No pool space
Explanation: No dynamic memory (DSR)
was available for
the
Common Block Directory (CBD) or Partition Control Block (PCB).
If

does

Explanation: No dynamic memory
(DSR)
was available for
Control Block
(TCB)
in the System Task Directory (STD).
cannot be installed.

Task
Task

User Action: Wait.
Pool space may free up
not, see your system manager.

soon.

INS -- No room available in STD for new task

User Action: Wait. Pool space may free up
not, see your system manager.

soon.

does

INS -- Not enough APRs for task image
Explanation: The Task Builder allows you to specify the virtual
base address of a
task image as a multiple of 4K.
Privileged
tasks start at virtual 100000 (octal) to map the 16K Executive or
virtual 120000 (octal) to map the 20K Executive.
If the virtual
base address is set too high, the task image may not be able to
be map?ed with the remaining mapping registers.
User Action: See the RSX-llM/M-PLUS Task Builder Manual for more
information on the /PR keyword (/PRIVILEGED qualifier to LINK).
INS -- R/O partition
partition

parname

not

system

defaulting

task's

Explanation: Warning message. Command attempted to
install a
read-only
common
in a nonexistent partition.
Common was
installed in task's partition.
User Action:

If you wish, you can create the missing partition.

INS -- Specified partition too small
Explanation: Command attempted to install task
that was smaller than the task.
User Action:
command.

Increase the size

7-32

the

partition

and

reenter

RUNNING TASKS

INSTALL {Cont.)
INS -- Task image already installed
Explanation: The requested task image, which was checkpointable,
had already been installed.
On systems that do not support the
dynamic allocation of checkpoint space, checkpointable tasks that
have checkpoint space allocated can be installed only once.
Other tasks can be installed more than once
(under different
names) •
User Action:
If the system has dynamic allocation of checkpoint
spaces
rebuild
the
task
without task checkpoint space.
Otherwise, make the task noncheckpointable.
INS -- Task image I/O error
Explanation:
INSTALL either could not read the task image file,
or could not rewrite the task image header because the device was
write-locked.
User Action: Determine the cause of the error and correct it
you can.
If you cannot, see your system manager.

INS -- Task image virtual address overlaps common block blockname
Explanation:
The virtual addresses reserved for the task
image
overlap those reserved for the common block named in the message.
A corrupt task image file probably caused the overlap.
User Action: Determine the state of the task image file and
correct the error if you can= You may have to rebuild the task=
INS -- Task name already in use
Explanation: Command attempted to install a task with
name as one already in the system.

the

same

User Action: Determine if the two tasks are the same.
If not,
install your task using the /TASK_NAME qualifier to change the
name.
INS -- Too many common block requests
Explanation:

Task made too many common-block requests.

User Action: Tasks are limited to seven common-block references.
This error can result from an improper task build or coding
errors. Find the cause of the error and correct it.
INS -- Too many LUNS
Explanation:

Task requested more than 250 LUNs to be assigned.

User Action:
Recheck task build and code for source of the error
and correct it.

7-33

RUNNING TASKS

REMOVE
INS -- WARNING -- Privileged task overmaps the I/O page
Explanation: A privileged task that is mapped into the Executive
is usually also mapped into the I/O page in order to access the
KTll registers and other devices. Many tasks do not require this
access and can use the additional 4K words of virtual address
space for the task image. The message warns that a task that may
require access to the I/O page might have grown too large.
User Action:
necessary.

7.9

Determine the cause of the error and correct it

REMOVE

REMOVE takes a task name out of the System Task Directory.
is no longer installed.
REMOVE/REGION takes the name of a
Directory and the partition list.

region

out

the

The

task

Common

Block

This is a privileged command.
Format
REMOVE[/qualifier]
Task? taskname
REMOVE[/qualifier]

taskname

Command Qualifier
/REGION

Parameter
taskname
Specifies the name of the task you wish to remove.
If you wish to remove a region, specify the /REGION qualifier and
the name of the region.
Command Qualifier

/REGION
Specifies t,hat you wish to remove a region from the Common Block
,This,qualifier is' for RSX-UM-PLUS systems only.

Dir~ctoty~,

Examples

>REMOVE LJONTON
This example removes the task named WONTON from the
Directory. It is no longer installed.

7-34

System

Task

RUNNING TASKS

FIX

, T~is RSX7"l lm~I:J,L,,l}~" 'e~:·aR1pl:e'.:·}t'emoy~$/t~e::· .;cqmmon·: <reg:i,.on
. ~;~·~~?ID:.;;:theF,:CQ~JnO!\ :·~107~:·'.·IJ,i:~::'c,t:o:~:·/ : /. , . :. '' •' ..· ·.',·. : ; ;:'
Notes
To remove an active task, you must first abort it.
If a task is fixed, REMOVE first unfixes it and then removes it.
REMOVE cancels all time-based requests for the task to run.
REMOVE deallocates all receive-by-reference and receive-data
packets for the task and detaches all attached regions. See the
RSX-llM/M-PLUS Executive Reference Manual for more information.

7.10

FIX

FIX causes an installed task or region to be loaded and locked into
memory.
Subsequent requests for the task or region may be serviced
more quickly because it is memory-resident and does not have to be
loaded from the disk.
This is a privileged command.
Format
FIX [/qualifier]
Task? taskname
FIX[/qualifier] taskname
Command Qualifiers
':/;l=t8AOONLY:.SEGMEN~

t~.E:~1l,10Ni ;·

.;? } J . ' :;· ::';(

Parameter
taskname
Specifies the installed task or region you wish to fix in memory.
Command Qualifiers

.~e~~;. ~~al:iif:ter~s: a~re,;. ~.~:r~ R8X;-IJM~PLU~f,.,sy:st:e~,S,. o'!1Y.• .. J:t>,.Yo,u do.
,no.~ speoi,,fo/'" a. qua•lui.f;~r\;,,ian ~instal1 led ·~task· ia~·f lX·'EKI·:'· •1n• melll<>iflf •

Al,l:ows you to fi;x in memory ·the .read"-only segment .·of a. multiuser
task.

Allows you to fix in memory a common r·e9ion.

7-35

RUNNING TASKS

FIX (Cont.)
Example

>FIX ACNT

>SHOW TASK/INSTALLED/FULL ACNT
ACNT
061724 GEN 100630 02264100-02342000
S T AT US :

- E XE

TI - NONE

-- CHI'~

roe - 0

··- P MD P F· 1)

PRI - 50. DPRI - 50.

F XD

EFLG - 000000

000000

>UNFIX AeNT

>SHO TAS INS FU ACNT
ACNT 061.724
GEN
035370
0047000-·005~:i4700
STATUS!
-EXE -CHK -PMD PRV
TI - NONE
roe - o. EFLG - 000000 000000

PRI - 50. UPRI - 50.

In this example, the user fixed in memory the installed task
ACNT. The task's status, as displayed, includes the mnemonic FXD
under STATUS and also gives the task's location in the partition
GEN.
Notes
UNFIX and REMOVE counteract FIX.
After a task is fixed, it need not be loaded into memory because
it is already memory-resident. Requests to run the task can be
serviced more quickly.
Fixed tasks remain memory-resident even after they exit or abort.
Fixing a checkpointable task makes it noncheckpointable.
Active tasks cannot be fixed.
before it can be fixed.

However, a task must be

The system can fix a task in memory only when
which it is to be fixed becomes available.

the

installed

partition

Not all tasks will run properly when fixed.
Certain tasks may
require data areas to contain certain values when loaded in from
the disk. The first time the task is run, these data areas may
be modified and the task may run unpredictably thereafter. Tasks
that initialize their data areas, and therefore do not have this
problem, are called serially re-entrant.
Overlaid tasks may be fixed and, if their root segments are
serially re-entrant, will run correctly. However, since their
overlaid segments must still be read in from disk (unless the
task was built using memory-resident overlays), not much is
gained by fixing them.
Error Messages
FIX -- Partition busy
Explanation: The partition in which the task was to be fixed
occupied, so the task cannot be fixed.
User Action:

Wait or install the task in another partition.
7-36

RUNNING TASKS

UNFIX
FIX -- Task already fixed
Explanation:

The specified task is already fixed.

User Action:

None.

FIX -- Task being fixed
Explanation:
fixed.

The specified task

user Action:

None.

7 .11

the

process

being

UNFIX

UNFIX frees a fixed task or region from memory.
The effect is to
allow tasks that have been waiting for space in the partition in which
the fixed task resides to compete for that space.
This is a privileged command.
Format

UNFIX[/qualifier]
Task? taskname
UNFIX[/qualifier] taskname
Command Qualifiers

Parameter

taskname
Specifies the name of the task you wish to unfix.
If you wish to unfix a region, specify the name of the region for
this parameter.
Command Qualifiers
, , These,'quql~:fl:el(,~,,~~e< fi>tr: '·asx: 7 1'f~f-PLUS :·systein's:.,onl'Y,'~:',

..\.

/REGION
. Bp.e,c.l.fies that you .wi.sh to, unfcix 'a common region , rathe·r
task.

than ··a

/REA:DONLY~SEGMENT

Specifies tha't you wish to. unfix
multiuser task.
Exampie

See example in Section 7.10.
7-37

the

read-only

segment

of,

RUNNING TASKS

SET PARTITION
Notes
Therefore,

A fixed task remains fixed after it exits or aborts.
it must be explicitly unfixed or removed.
Error Message
UNF -- Task not fixed
Explanation:
fixed.

Command attempted to unfix

User Action:

None.

7.12

task

that

was

not

SET AND SHOW

All users can display information about partitions, active and
installed tasks, the clock queue, and logical-unit-number assignments.
Privileged users can establish and eliminate partitions and change the
priority of active tasks.

7.12.1

SET PARTITION

SET fNOJPART!T!ON creates or eliminates partitions in
This is a privileged command.

A partition is a contiguous area of memory with
fixed base address, and a type.

system

name,

memory.
size,

RSX-llM partitions can be of
four
types:
system-controlled,
task-controlled, common regions, and device commons.
In addition,
task-controlled partitions can have subpartitions.
~

' ,, , '

-RS-X--ll~?i,;u;$· ·.pa~p~i t.~~9~~ :-c,an /be
devic~: ~o~ll'tol1s..:,

Format
SET NOPARTITION:parname
SET PARTITION:parname/qualifier[s]
Base? n
Size? n
Required Qualifiers
/BASE:n
/SIZE:n
Qualifier
/TOP:arg

7-38

RUNNING TASKS

SET PARTITION {Cont~)
RSX-UM Partition Types

/COMMON
/DEVICE
/SYSTEM
/TASK
/TOP:arg
.
/[NO]SUBPARTITION:subparname
RSX-llM..;.PLUS Parti,tfc:m Type,~

/DEVICE .
, /[)IAGNOSTI'C

/SY$'!'EM ,
Required Argument
parname
Partition names are from one through six Radix-SO
Each partition (or subpartition) must have a name.

characters.

SET NOPARTITION eliminates the named partition.
Required Qualifiers
/BASE:n
Specifies the starting address of the partition.
physical base address specified in 64-byte unitse

the

64-byte

/SIZE:n
Specifies the size of the partition.
units.

n is the

size

The argument for the base and size of the partition can be
entered in a number of formats. In all formats, n is a number
that is multiplied by a factor to calculate the value to be used.
See Table 7-1.
Table 7-1
Base and Size Specifications for SET PARTITION

Format
Octal
Decimal
Octal K
Decimal K

nnnn
nnnn.
nnnK
nnnK

Calculated
Value

Base Range

Size Range

(nnnn*lOO)
(nnnn.*640)
(nnn*4000)
(nnn.*2048.)

O<base<l 77777
O.<base<65535.
O<base<3777K
O<base<2047.K

O<size<2000
O<size<l024.
O<size<40K
O.<size<32.K

For system-controlled partitions, these values can range from O
through 1920.K, or any valid representation of these limits. The
upper limit is the size of your system's memory.

7-39

RUNNING TASKS

SET PARTITION (Cont.)
Qualifier

/TOP:arg
The /TOP qualifier moves the top boundary of the specified system
according to the form the argument is stated in. The argument is
a number of 64-byte blocks, expressed in one of the five
following formats:
+n

Moves the top boundary of the partition up by
specified amount, making the partition larger.

the

-n

Moves the top boundary of the partition down by
specified amount, making the partition smaller.

the

Makes the partition the specified size by
top boundary.

the

[+]*

Moves the top boundary of the partition up as
possible.

Moves the top boundary of the partition down as far as
possible.

moving
far

Partition Types

/SYSTEM
Both RSX-llM and RSX-llM-PLUS have system partitions.
System
partitions are sometimes called system-controlled partitions.
They are the most common type of partition on mapped systems.
All systems including DCL are mapped systems.
In system partitions, the Executive allocates available space to
accommodate as many tasks as possible at one time.
This
allocation may involve moving resident tasks to arrange available
space into a contiguous block large enough to contain a requested
task.
/DEVICE
Both RSX-llM and RSX-llM/M-PLUS have device partitions.
Device
partitions are device commons, which are used by tasks to access
the device registers of the I/O page.
Device commons provide
direct access to specialized I/O equipment, such as that used in
industrial and laboratory settings. See the Processor Handbook
supplied with your system for more information on the I/O page.
/TASK
Only
RSX-llM
systems
have
task-control led
partitions.
Task-controlled partitions are sometimes called user-controlled
partitions. Task-controlled partitions are generally used for
real-time
applications
where
explicit
control of memory
allocation is
important.
Task-controlled
partitions
are
exclusively allocated to one task at a time unless divided into
subparti tions.

7-40

RUNNING TASKS

SET PARTITION (Cont.)
/[NO]SUBPARTITION:subparname
Only RSX-llM systems
have
subpartitions~
Task-controlled
partitions can be divided into as many as seven subpartitions.
SET. PARTITION/NOSUBPARTITION eliminates the named subpartition.
/COMMON
Only RSX-llM syste.ms have common.partitions.
Common partitions
are sometimes called common regions. Common partitions are used
for task communications or data. o.r .code used in.·. common· . by more
than· one tasl<.
See the RSX-HM/M,.:,.PLUS Task Builder )ianual for
more information: on common regions~· '
/0:~,AGtf()$,~P.I¢ ·

· ·

' ·

· '·

'··: ; ·,

'··

.·'iii H ~~le ;lr·r~_.ffer: Q$, ~~~~~ins have ~i~~J;,st i!!.\ ~ah1 ~i.6n~; . · :~ev ,l)r e

· ;ci$e'd. ~ .. fo,r ;, ,:. ·oJ. ~gpo•st i·c · .. ;'.6Jn9.t.ioq·s' .: .:· o;h: :m aiJ:i i.p:r.Q\:e·ss~r .::systems:~.: .. · T·he .
·,t;pec~~i·ed. par'tition· is
ct.eat.ea · wf'!::l:lo·u:~ ::cMc:::.kfosi: ·:th~·.· ~dp,· .of·
..m~mor~~· . ·

··

Examples

>SET PARTITION!TOMPAR/SYSTEM
Base? 002010

Size? 1000

>SHOW PARTITION!TOMPAR
PAR=TOMPAR:oo2010:1ooo:sys
This example creates a partition named TOMPAR with a base address
of 002010 and a size of 1000 (octal) bytes. The partition is
system-controlled. Since this is the default, the user need not
have specified /SYSTEM in the command.
The display from SHOW PARTITIONS is slightly different on RSX-llM
systems in that the word MAIN appears where PAR appears in this
example.
>SET NOF'ART IT ION
Partition name? TOMPAR

>SHOW PARTITION:TOMPAR
SET -- Partition not in ssstem
This example eliminates the partition TOMPAR.

>SET NOPARTITION!TSTPAR/NOSUBPARTITION
SubPartition nBme?

SMOKE

This RSX-llM example eliminates the subpartition SMOKE
task-controlled partition TSTPAR.

from

the

Notes

Partitions are one of the key elements in tuning RSX-llM/M-PLUS
systems and making the best use of available memory.
You can specify the partition you wish your task to run in with
the PAR option of the LINK command.
You can override this
specification with the /PARTITION qualifier to the INSTALL or RUN
commands.

7-41

RUNNING TASKS

SET PARTITION (Cont.)
A system partition cannot include subpartitions specifically
defined by the SET command.
The Executive dynamically defines
subpartitions in a system partition as needed for tasks installed
in
the
partition.
You should not confuse these dynamic
partitions containing tasks with the task-controlled partitions
of RSX-llM.
On RSX-llM systems only, you can define subpC.lrtitions
task-controlled partitions with the SET command.
·

You can display the name, size, address and type of one or more
partitions with the SHOW PARTITIONS command (Section 7.12.2).
You can display the allocation of
partitions
in
memory
graphically with the SHOW MEMORY command (Section 8.1.9).
See the RSX-llM/M-PLUS Task Builder Manual for information
tasks run in part1t1ons-.---

about

If a partition currently contains an installed task, common,
loaded driver, you cannot eliminate it with SET NOPARTITION.

If, on an RSX-llM system, you eliminate a
task partition, you
automatically eliminate any subpartitions associated with it.
Error Messages
SET -- Alignment error
Explanation; Command attempted to create a partition but the
base address or size conflicted with existing partitions or with
the size of physical memory.
User Action:

Check command for proper values and reenter.

SET -- Nonexistent memory
Explanation: Command
nonexistent memory.
User Action:

attempted

define

partition

Check command for proper values and reenter.

SET -- Partition already exists
Explanation: Command attempted to define a partition with a name
already in use.
User Action:

Use another name.

SET -- Space used
Explanation: Command attempted
storage area already occupied.
User Action:

create

partition

Check command for proper values and reenter.

SET -- Task installed in partitions
Explanation:

Command

attempted

t:'.'ont;:iini.ng an installed task.

7-42

eliminate

partition

RUNNING TASKS

SET PARTITION (Cont.)
user Action:
accordingly.

Determine

the

cause

the

error

and

proceed

SET -- Too many subpartitions
Ex,planation: An RSX-llM user attempted to define more than seven
subpartitions in a task partition.

User Action:

None.

You are limited to seven subpartitions.

SET -- Unknown main partition
Explanation: An RSX-llM user attempted to
in a nonexistent task partition.
user Action: Determine
appropriate action.

7.12.2

the

cause

create
the

error

subpartitions
and

take

SHOW PARTITIONS

SHOW PARTITIONS displays address and content information about the
partitions of the system.
You can display information about all
partitions or about a single partition.

Format
SHOW PARTITIONS[:parname]

Parameter
If you do not specify a partition name, all partitions in the
system are displayed.
The format of the display is as follows:
parname pcbaddr baseaddr parsize MAIN
If the partition includes subpartitions,
this description is
followed
by one or more lines describing the contents of the
subpartitions.
The format of these lines is as follows:
pcbaddr baseaddr parsize partype contentname
In both of these displays, parname is the name of the partition,
pcbaddr is the address of the Partition Control Block (PCB),
baseaddr is the starting
address
of
the
partition
or
subpartition, parsize is the size of the partition in bytes, and
partype is one of the following:
MAIN
TASK
SUB
DRIVER
RO COM
RW COM
DEVICE
SEC POOL

Main partition
Dynamic task subpartition - not /TASK
(user-controlled)
Subpartition - RSX-llM only
Device driver partition
Read-only common partition
Read-write common partition
Partition is a common mapped to the I/O page
Partition is a secondary pool

7-43

RUNNING TASKS

SHOW PARTITIONS (Cont.)
In addition, contentname is indicated as follows:
[taskname] An inactive resident task
<'l'ASKNME> ,· .·Afr ,:ac:t,i v.e,, :e? sk. ,<:m' .'RSX"~l'lM""':P,L'US'
(TASKNAME) An. active task on .RSX-llM

~n10::~:',''"':' ;rr"· ·~. ~::::fn1if.i.efya*E~sr' spe'ai)'f'ik!""al~Vi!a~·ari::v:et -'oh'. nsx.;;.1:1r-t;ptus. :
4

--dd:
+ xxxx +

Indicates specific device driver on RSX-HM
Indicates the name of the first
installed task that is associated with a
an unnamed common, usually the read-only
segment of a multiuser task
Indicates the name of the common

yyyy
parname

Specifies the name of the partition about which you wish
information to be displayed. , W,hen. iYO,ll; ppe,ci,f:y ~ .. par'titiOp.", · t.he
dis·play /On RS~~ lJM-?Lus· form.at is .a·s .·• 1.fol:J:9ws,: ··
· 'PARk=pa r;name;: ba~se~ddr;: pars'i ze:.: Si'lf
'

•

;

•

s, ·
~

.In th;is ,disPjlay,; :;thie ·µ~d:resp ~nd, . sl;z~~ ;',;fi•eT!(i;s: .· ;~f the single ·
partition, . d,is,play , ar.e . 64-byte values }:octal 100), while in the
mu1 tip'1e: ~par:u;ti:O:n ° d"isplay ,~ ~ h1£te'. ' V:a1.~1\es~ :ar:e: .:displayed..
See
ex a mpTes'.
;
··
·
·
·
On RSX-llM, the display is identical for system partitions.
For
task (user-controlled partitions), any subpartitions are also
displayed, as follows:
MAIN=parname:baseaddr:parsize:TASK
SUB=parname:subparname:baseaddr:parsize

Examples
>SHOW PMn IT IONS
SYSPAR 035720 00201000 00010000 MAIN
036330 00201000 OOOl.0000

T~1:::lh

<MCR+++>

DRVPAR

035610 00224000 OC· 140000 Mt1 IN
035324 00224000 00002600 DR I l.JEF: <DB: )
035260 00227600 0000 l ~500 Tll~Jl..'EI~~ ( IH '.:

LDRPAR

035544 00364000 00003000 MAIN
033774 00364000 00003000 TASK

SECPOL
GEN

035434 0042'7000 00050000
035370 004 77000 04701000
il}2i0 004 77000 00024000
041324 00523000 00004400
062l.24 00545100 00012600

7-44

SEC

<. • .L.DF:>

F' 0 0 L

i·rnIN

TA St<
TAGI'\

! FCSF!::;t..
POOL.
l..F'PO

RUNNING TASKS

SHOW TASKS
046340 00763300 00006100 TASK

TT35

This example shows the display from SHOW PARTITIONS when no
partition is named~
Information on all partitions and dynamic
task subpartitions in the system is displayed. DRVPAR contains a
number of device drivers, each in its own subpartition. Notice
that SYSPAR's base address is 00201000 and its size is 10000
(octal) bytes. See next examplee

>SHOW PARTITION! SYSPAR
PAR=SYSPAR!002010:ooo1oo:SYS
This example shows the display from SHOW PARTITIONS when a
partition is named~ No information about subpartitions or about
any tasks in the partition is displayed.
Notice that SYSPAR's
base address is given as 002010 and its size is 100 64-byte
blocks.

>SHOW PARTITIONtTSTPAR
MAIN=TSTPAR:003657:ooo7oo:TASK
SUB-TSTPARtSMOKE 10-03657:000010
This RSX-llM example shows the display when SHOW PARTITIONS names
a task-controlled partition, that inclu,des a subparti tion.
Notes
SHOW PARTITIONS unadorned
command.

the

equivalent

the

MCR

PAR

SHOW PARTITIONS with a partition name is the equivalent of the
MCR SET /PAR=parname command on RSX-llM-PLUS or the MCR SET
/MAIN=parname command on RSX-llM.

7.12.3

SHOW TASKS

You can display information about active and installed tasks on the
system in a number of ways. Section 7.12.3.1 covers the display of
static information about tasks active on your terminal or elsewhere on
the system in full or brief format. Section 7.12.3.2 explains the
display of static information about installed tasks in full u1 brief
format.
Section
7.12.3.3.1
explains
the dynamic display of
information about active tasks and Section 7.12.3.3.2 explains the
dynamic display of the Active Task List. Section 7.12.3.4 explains
the display of the LUNs of an installed task.

7-45

RUNNING TASKS

SHOW TASKS (Cont.)
7.12.3.1

SHOW TASKS/ACTIVE

SHOW TASKS/ACTIVE displays information about active tasks in brief and
full format.
Brief Format
>SHOW TASKS/ACTIVE[:ttnn:] [/qualifier[s]]
Command Qualifiers
/BRIEF
/ALL

ttnn:
If you name a terminal in the command, the display shows in brief
form the tasks active at that terminal. If you do not name a
terminal, the display shows in brief form the tasks active at
your terminal.
Command Qualifier
/BRIEF
Specifies that you wish to display information about active tasks
in the brief format.
This is the default and need not be
specified.
On RSX-llM systems, the brief format includes task names only.
On :asx«-'1'1M-PLUS systems, the brief format includes task names and
th~ '.pli,9·~nati'ng ..'t;ermi:n?l in:.·parentheses' next to eacbi\•ta·sk'· nanwe~:·
/ALL

Specifies that you wish to display information about all tasks
active on the system. The default is to show information about
tasks active at your terminal only.
Examples
>SHOW TASKS/ACTIVE
MCR •••

<TT5!/

SHOT5

\·T:ts·.;::>

This example shows the brief display from SHOW TASK/ACTIVE.
In
this case, the tasks are MCR ••• , the central command dispatcher,
and SHOTS, the SHOW task itself.
·onRsx-nM.-PLus ..systems;·.tbe·.terminal ·~~oil\·· whictr
·.rnn1lltll9; ls. also• displayeq:,.
·
~ <·'. •• ; C,:·

';..

••

'..

•

•:

••

• •

•

:? . .

>SHOW lASKS/ACTIVE/ALL
.CCOO :>

LDR, • •

1:~MDEMO

<TTOf)

~~HOH2

NETACF'

MGf~,

(TT i·:f:-Y

7-46

tbe

't~sk ..

is:·

RUNNING TASKS

SHOW TASKS (Cont.)
r'.:·)

\ T l :~; t )

.•.JC:_T'.:i

(TJSt)
( C0 0 t )

:: ;

·i i"J

Dn(i F L 1~·

rrs.::.

<TT56.H

EL:·1··12~~i

<H25!)
( T:T:Hi r >

L. D r r 3 o

This example shows the brief display from SHOW TASK/ACTIVE/ALL.

61) as}{...:ilt1~'I'i~qs,. sy~te[t\s~< t.h. e ,'t:_er:rni~a1
1
•l'runt'l:iqg»,:i'.sl alsci,;a'is'pla:ye<L.: ,' J: ' I '
' 1

•I

1''

:·',,

frofu' ?which:•;: ,::the;',,
I I :I':,,•;: ':,';: ;'
I ,"

',.

//'°T

:•1

;·

·~ t

Full Format
SHOW TASKS/ACTIVE/FULL [taskname]
SHOW TASK[:taskname]/ACTIVE/FULL
taskname
If you include a task name, the display shows full information on
that task.
If you do not name a task, the display shows full
information on all currently active tasks.
Command Qualifier
/FULL
Requests the full
format display for
the SHOW TASK/ACTIVE
command.
This format includes detailed information on the state
of one or all tasks active on the system.
The format of the
display is as follows:
taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri
STATUS: statusflags
TI - ttnn: IOC - iocount BOC -buffiocount EFLG -eventflags PS -pswval
PC - pcval REGS 0-6 rrlval r2val r3val r4val r5val r6val
In this display:
tcbaddr

The physical address
Block (TCB)

parname

The name of the task's partition

pcbaddr

The physical address
Control Block (PCB)

taskaddrlimits

The base and top of the task's
subpartition as physical addresses

dynamic

pri

The priority at which the task
running

actually

defpri

The default priority at which the
built or installed to run.

STATUS

The task's
status
flags.
identified in Table 7-2.
7-47

the

Task

the

Control

Partition

task

was

These

are

RUNNING TASKS

SHOW TASKS (Cont.)
TI

The initiating terminal

roe

The decimal I/O count for the task

BIO

The decimal count of I/O buffered
terminal driver and Executive

EFLG

Local event flags

pswval

The Processor Status Word

pcval

The Program Counter

REGS

The contents of the task's other registers.
If the task was spawned by another task, the
name of the parent task is also displayed.

the

If the task is not in memory (OUT flag displayed, see Table 7-2),
the PC, PSW, and other registers are not displayed.
This display shows the state of the task at the time the command
was issued. You can display similar information dynamically (in
real time) for a single task with the /DYNAMIC qualifier, as
explained in Section 7.12.6.
Table 7-2
Task Status Flags
Status
Flag

TCB
Flag

ABO
ACP
AST
BLK

T2.ABO
T3.ACP
T2 .AST
TS.STP

C.li.F

T2.CAF

Dynamic checkpcinting allocation failure

CAL
-CHK
CIP

T3. CAP

CKD
CKP

TS.CKD
TS.CKP

CKR
CLI
DST
-EXE
FXD
GFL
HLD
HLT
MCR
MSG
NET
NSD

TS.CKR
T3. CLI
T2.DST
TS.EXE
T2.FXD
T3.GFL
TS.HLD
T2.HLT
T3.MCR
TS.MSG
T3.NET
T3.NSD

Checkpoint space allocated in task image
Not checkpointable
Blocked for checkpoint in progress
(RSX'.'""llM-PJ:;US only)
Checkpointing disabl~d
Ctieck:pointt?d {RSX-llM:-P,LgS 'o;n~y)
Checkpoint fo p"rogress'"
checkpointed
(RSX-llM only)
Checkpoint request pending
Command Line Interpreter
ASTs disabled
Not executing
Fixed in memory
Task has own group global event flags locked
Half-loaded, awaiting pool for task header
Being terminated
Activated by MCR
Aborted, waiting for TKTN message
Network protocol level
Cannot receive data (no send data allowed)

TS.CHK
TS.CIP

Meaning
Being aborted
Ancillary Control Processor
AST state
Blocked externally by CLI command

"o"r,

(Continued on next page)
7-48

RUNNING TASKS

SHOW TASKS {Cont.)
Table 7-2 (Cont.)
Task Status Flags

Status
Flag

TCB
Flag

-PMD
OUT
PRV
RDN
REM
REX
ROV
RST
SEF
SLV
SPN
SPNA
STP
STPA
WFR
WFRA

T3.PMD
TS.OUT
T3.PRV
T3. RDN
T3. REM
T2.REX
T3.ROV
T3.RST
T2.SEF
T3.SLV
T2.SPN
T2.SPN
T2.STP
T2.STP
T3.SWS
T2.WFR
T2 .WFR

Suppress PMD on SST abort
Out of memory
Privileged
I/0 being run down
Remove on exit
Abort AST effected or in progress
Resident overlays
Restricted - used by layered software
Stopped for event flag
Slaved
Being suspended
Suspended prior to AST
Stopped
Stopped prior to AST
Reserved for software services
In a wait-for state
In a wait-for state prior to AST

DSP

ri~.bsJ?q

J'a1Sk , ,~aq bul
for us.er-m,ode' !- ,a)1ii:1 D".:"$pac;
'Ta sk:1 :s load: 'device nas oeen aiSmodn:tea:: .:' ,,

sws

LD0:'>

.MUT'

PRO.
'PRV ',·
S~Qj,·

Meaning

T4•:'LDDrn

T.:lSk'
is muH:iq$e r
1

task
T~ S J< ,· i'.s: t 6 r.·: sho ii1 a< ,: be} .::~ P~:~ to t~pe , 1tas~ :'.'.' ,: ,:· ,:
T4~PRV .. Task: was, ptiv'Tleged bu,t has, cleared :T3:.PRV·
,:'. :,;.~Lj°3ji~fl T,?:S:k: 'us~:s' ;:qQJf\m9n~ ,JQ;r: :$f:Mbrrq:ni ~.!ft~o.n :·; t / "I,:
T4»;.MUT

,.··

T4, ..,PRO

·•I

;

,;
I

•·

.••.·· . •

Note: These status flags are displayed by several forms of the
SHOW TASK command.
They give information on what is happening
within the task and between the task and the system.
They also
identify certain kinds of tasks.
Names prefixed by a minus (-)
indicate the complement of the condition. Thus, -CHK means the
task is noncheckpointable.
You must understand how the system
runs tasks to understand the meanings of all these flags.
See
the
RSX-llM/M-PLUS Task Builder Manual, the RSX-llM/M-PLUS
Executive Reference Manual, and the RSX-llM/M-PLUS Crash Dump
Analyzer Reference Manual for more information.
The CDA manual
has a full explanation of the contents of the TCB.

Examples
~SHO~

fT7

TAS/ACT/FULL TT7
066734

GEN

064244

01676500-02062100

PRI - 50.

DPRI - 50.

-CHK WFR -PMD REM MCR
TI - TT7: IOC - 1. EFLG - 000000 040000

STATUS:

REGS 0-6

PS-70004 PC-072132
041130 051172 000000 000040 010400 051520 001472

This example shows the display in full format for the task named
TT7 (initiated by a RUN command from terminal TT7:).
The task is
running in the default partition GEN at a priority of 50.
The
task is not checkpointable.
It is in a "wait-for" state. No PMD

7-49

RUNNING TASKS

SHOW TASKS (Cont.)
will be generated. The task is to be removed on exit (meaning it
was installed with the install-run-remove form of RUN), and it
was activated by MCR.
(Many tasks requested from DCL are
actually activated by MCR.)
>SHO TAS/ACT/FUL
••• LDR 034210 LDRPAR 033774 00364000-00367000 PRI - 24S.
DPRI - 248.
STATUS: STP - PMD PRU NSD FXD
TI - COO:
IOC - O.
EFLG - 000001 000000 PS - 170000 PC - 120526
REGS 0-6 000162 024207 177777 066640 066610 066314 120250
RMDEMO 046320 GEN
046640 01367700-01415100 PRI - 225.
DPRI - 225.
STATUS:
-CHK WFR -PMD PRV MCR
TI - TT62:
IOC - O.
EFLG - 000035 040000 PS - 170010 PC - 125014
REGS 0-6 000002 131316 131436 000000 135055 000000 121240
MCR ••• 116464 SYSPAR 036330 00201000-00211000 PRI - 160.
DPRI - 160.
STATUS: STP -PMD PRV CLI NSD CAL
TI - TTO:
IOC - O.
EFLG - 000001 040000 PS - 170000 PC - 124412
REGS 0-6 000000 120556 000400 120512 000100 120572 120442
DCL ••• 115530 GEN
037344 00624700-00634700 PRI - 160.
DPRI - 160.
STATUS: STP -PMD PRU CLI NSD CAL
TI - TT10:
IOC - O.
EFLG - 100001 040000 PS - 170000 PC - 124470
REGS 0-6 025550 025550 000000 120426 123530 000000 120362
SHOT10 066314 GEN
066610 02221700-02261700 PRI - 160.
DPRI - 160.

STATUS:

-PMD REM PRV

TI - TT10:
IOC - O.
EFLG - 000001 040000 PS - 170017 PC - 121202
REGS 0-6 000000 131574 050712 000000 000000 000000 001216
DBOOF1 117570 GEN
036770 00537000-00624700 PRI - 149,
DPRI - 149+
STATUS: STP ACP -PMD PRU NDS CAL ROU
TI - COO:
IOC - O.
EFLG - 000002 040001 PS - 170000 PC - 120546

LPPO
061444 GEN
062504 00725200-00740000 PRI - SO+
DPRI
STATUS: STP PRU
TI - COO:
IOC - O.
EFLG - 000400 140000 PS - 170000 PC REGS 0-6 121526 121640 000115 124676 000000 000001 120342
PARENT TASK NAME - GMG •• ,
LPP1
062024 GEN
062374 01351200-01364000 PRI - 80,
DPRI
STATUS: STP PRV
TI - COO:
IOC - O.
EFLG - 000400 040000 PS - 170000 PC REGS 0-6 120362 000061 000060 140164 140440 000000 120342
r1Ar'1l""".UT
r t1 f\ ~rt I

TAir."Lo"
I M

w ''

UA:Ur""

l't M I I L.

nu~

\.'OIU't

- 80.
120644
- SO.
120644

AT.T10 041174 GEN
040640 02062100-02142000 PRI - SO.
DPRI - 80,
STATUS: SEF STP WFR -PMD REM PRV MCR
TI - TT10:
IOC - O.
EFLG - 000000 140000 PS - 170010 PC - 141604
REGS 0-6 123551 123416 000122 115530 000000 000000 120664
QMG ••• 061340 GEN
056354 01327700-01351200 PRI - 75,
DPRI - 75.
STATUS: STP PRV
TI - COO:
IOC - O.
EFLG - 000000 040000 PS - 170000 PC - 120656
REGS 0-6 121750 123350 122350 001006 000000 000000 120372
EDIT10 057420 GEN
057340 02142000-02262100
PRI - 65.
DPRI - 65.
STATUS:
WFR -PMD REM
TI - TT10:
IOC - O.
EFLG - 000002 100000 PS - 170000 PC - 006706
REGS 0-6 000001 000000 017764 000000 103666 1015708 001700
PARENT TASK NAME - AT.T10

7-50

RUNNING TASKS

SHOW TASKS {Cont.)
This example shows the display from SHOW TASKS/ACTIVE/FULL.
Tasks are displayed in order of priority.
Note the tasks
displayed below the first break.
Tasks LPPO and LPPl are
line-printer processors. They are spawned by the Queue Manager.
AT.TlO represents an indirect command file that spawns EDT by
including an EDIT/EDT command, but the resulting task EDITlO is
not slaved=

7.12.3.2

SHOW TASKS/INSTALLED

SHOW TASKS/INSTALLED displays information
either brief or full format.

about

installed

tasks

Format
SHOW TASKS[:taskname]/INSTALLED[/qualifier]
Command Qualifiers
/BRIEF
/FULL
Parameter
taskname
Specifies the task for which you wish information displayed.
If
you do not specify a task name, information on all installed
tasks is displayed.
Command Qualifiers
/BRIEF
Requests information on installed tasks in a brief format.
This
is the default and need not be specified. The format of the
display is as follows:
taskname ident parname priority size ddnn:-lbn [memstate]
In this display, taskname is the name of the task, ident is the
task version identification (or the version of the prototype
task}, parname is the partition in which the task is installed,
priority is its priority, size is the size of the task in bytes,
ddnn: is the device from which it is to be loaded, lbn is the
logical

block

number

its disk address, and memstate is the

task memory state, which can be FIXED, CHECKPOINTED, or blank.
If the task version identification is missing (with the rest of
the line moved left} or if it is garbage, the task was installed
from a disk that is no longer present.
If the task version
number is a date, such as 07JUL, the task was compiled on that
day.

7-51

RUNNING TASKS

SHOW TASKS (Cont.)
/FULL
Requests the full format of the SHOW TASKS/INSTALLED command.
This format displays a detailed list of the states of one or all
of the installed tasks in the system, depending on the presence
of the taskname parameter.
The format of the display is as
follows:
taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri
STATUS:
statusflags
TI - ddn:
IOC - iocount EFLG - eventflags
This display is in the same
format
as
that
of
SHOW
See Section 7.12.4 for a description of the
TASKS/ACTIVE/FULL.
display.
taskname
Specifies a task for which full information is to be displayed.
If you do not specify a task name,
information about all
installed tasks is displayed.
Examples

>SHOW TASKS/INSTALLED
L DR •••
TKTN
RMDEMO
MTAACP
F11MSG
NET ACF'
EVP •••
••• MCR
SHOT5
••• MOU

••• DCL
MCR •••

12.15
04.}
Vl.03

LDRPAR
TKNPAR
GEN

() () 1 :·~

f;FN

i..1 0010

GEN

lJ02.00
vo1.oo
1.1
1. 1
2502
00
2.02

GEN
GEN
GEN
GEN
GEN
SY SPAR

GEN

248+
248+
200+
200.
200+
200.

00002500
00010000
00026700
00013600
00025500
0002~3500

199. 00013100
160.
160.
160+
160+
160.

00020300
00020300
00037700
00035600
00010000

This example shows the brief format of
TASKS/INSTALLED.
LDR ••• ,
the loader,
task EVP •••
is checkpointed. The final
the system command dispatcher.
See next

LBO :--00163310 FIXED
L B0 : ·- 0 0 1 "71 0 2 2
LB0!-00171022
EMO! --0000031 ~:i

LB0!--0016720/
DBO: --00644640
DBO ! --00644640 CHE CI\ P 0 I NT ED
LB0!--0016246?
LBO ! ···0() 16246'7
LBO t ·-00222416
DBO! -00212612
LB 0 ! ·- 0 0 1 6 2 4 «D

the display from SHOW
is fixed in memory.
The
entry shown, MCR ••• ,
is
example.

>SHOW/TASK:MCR ••• /INSTALLED/FULL
MCR ••• 110160 SYSPAR 11454 00202700-00212700 PRI - 160 • DPRI - 160
STATUS: STP -PMD PRU MCR CLI NSD CAL
TI - TT5: IOC - O. BIO - O. EFLG - 000001 040000 PS - 170000
PC - 122436 REGS 0-6 000000 120476 000102 120516 057020 040220 120366

This example shows the full
format of the display from SHOW
TASKS/INSTALLED.
In this case, the user named a single task.
The default is to show the full display for all installed tasks.
The status flags in the second line of the display are explained
in Table 7-2.

7-52

RUNNING TASKS

SHOW TASKS (Cont.)
Notes
The brief format of SHOW TASKS/INSTALLED is the MCR TAS command.
The full format of SHOW TASKS/INSTALLED is the MCR TAL command.
The /DYNAMIC qualifier enables you to watch
display as it is updated.
See Section 7.12.6.

7.12.3.3

the

full

format

SHOW TASKS/DYNAMIC

SHOW TASKS/DYNAMIC displays a moving picture on a video terminal of
either a single task's activity, or of all or part of the Active Task
List.
The command also works on hard-copy terminals, providing a snapshot
display that is different in format from the conventional SHOW TASKS
display.
This command is privileged if the Resource Monitoring Display {RMD) is
not installed on the system.
The command is nonprivileged if RMD is
installed under the name ••• RMD, or if your system supports flying
installs.
See your system manager for information.

7.12.3.3.l

SHOW TASK:taskname/DYNAMIC

SHOW TASK:taskname/DYNAMIC displays a moving picture of the task's
activity on a video terminal or a snapshot display on a hard-copy
terminal.
Format
SHOW TASK:taskname/DYNAMIC[/qualifier]
Command Qualifier
/RATE: n
Argument
taskname
Specifies the task you wish to inspect.
Qualifiers
/DYNAMIC
Specifies that you wish the moving display.
This function
performed by the RMD task.
RMD has four display pages:

•

Task, which displays a task header

•

Active, which displays all or part of the Active Task List

•

Memory, which displays the contents of memory

•

Help, which provides help on RMD
7-53

RUNNING TASKS

SHOW TASKS (Cont.)
Once you have invoked any one of these pages, through either a
SHOW TASK/DYNAMIC command or a SHOW MEMORY command, you can move
from one page to the other without leaving RMD.
The first
character of each page name is a command to RMD to go to that
page. In addition, an ESC entered from a page permits you to
enter setup commands for that page. See Section 8.1.9 for more
information on the features of RMD.
The setup commands for the Task page permit you to change the
task header being displayed.
The task you name remains the
default display for the Task page. This means you can observe a
single task header, then jump to the Memory page or the Active
page, and then back to the Task page and the named task will
still be on display.
/RATE:n
The /RATE qualifier allows you to set the rate at which the RMD
display screen is to be replotted on the first display. n is the
number of seconds between replots. The default n is 1. You can
change the rate by pressing ESC and entering a new rate. The
rate setting returns to 1 as soon as you change pages.
If you
wish a slower rate, you must reset the rate each time you change
the page.
Use this qualifier to slow down the display.
Task headers may change more often than once per second, but once
per second is the most rapid rate available.
Example
>SHOW TASK:CORT5/DYNAMIC

The screen is cleared and the following display appears:
RSX-11M V4.1 BL33 512K
Task:
Own:
RO
PC

CORT5
TTS:
022120

= 005330

14-NOV-82

10:15:33

Partition:
I/O = O.

GEN STATUS: -CHK -PMD REM PRU CLI
DPri: 160 Pri: 160 SPri:
155 Len: 000356000

R1
PS

R2
SP

000764

= 170000

002230

= 022224

LUN File

R3 = 000746
$DSW = O.

R4 = 024626 RS = 022136
EflS = 0000001 040000

LUN File

svo:
3. svo:
4. svo:
1.

2. DB0:[3t33JDEEP.DAT

5. TIO:
6. CLO:
7. DBO:

This display changes once per second and shows the task header
for a task named CORT5. The top line of the display identifies
the operating system by name, version, base level and memory
size, and also gives the date and time. The next line of the

7-54

RUNNING TASKS

SHOW TASKS (Cont.)
display includes the task name, the partition in which the task
is running, and the task's status flags.
(See Table 7-2 for an
explanation of the status flags.) The next line lists the task's
owner
(terminal, not UIC);
the outstanding I/O count;
the
default priority, running priority, and swapping priority;
and
the length of the task in octal bytes (top minus base). The next
two lines display the contents of the task's general-purpose
registers, program counter, Processor Status Word, stack pointer,
Directive Status Word, and local event flags.
The remainder of
the display shows the logical-unit-number assignments of as many
as 25 LUNs.
(Tasks can have as many as 250 LUNs.) This task has
conventional LUN assignments except for LUN 2, which is an open
file.

Notes
You must understand how tasks
run in
the
RSX-llM/M-PLUS
environment to understand all the elements of this display.
On
the other hand, this display is a useful tool for
understanding
how tasks run on the system.
Tasks built including ODT can be observed using this command, but
if you are single-stepping through the task or otherwise using
breakpoints, the registers displayed will be those of the ODT
task, not those of the named task.
This display is particularly useful for observing
complex
assemblies, as you can tell how far the assembly has gone by
which files are open. You may also be interested
in observing
the Task Builder at work.

7.12.3.3.2

SHOW TASKS/ACTIVE/DYNAMIC

SHOW TASKS/ACTIVE/DYNAMIC displays a moving picture of the Active Task
List on a video terminal or a snapshot display on a hard-copy
terminal.

Format
SHOW TASKS/ACTIVE/DYNAMIC[/qualifier[s]]

Command Qualifiers
/OWNER:ddnn:
/PRIORITY:n
/RATE:n

Command Qualifiers
/OWNER:ddnn:
ALL
Specifies the terminal or other device from which the tasks
displayed are being run.
You can name any device, pseudo device,
logical device name, or terminal number for this argument.
The
default argument is ALL,
which displays tasks owned by all
devices on the system.

7-55

RUNNING TASKS

SHOW TASKS (Cont.)
You can change the owner displayed by pressing ESC and entering a
new device name.
Note that this qualifier differs from other "owner" qualifiers in
DCL in that it names a terminal and not a UIC as the owner.
/PRIORITY:n
Specifies the highest priority to be displayed.
250, the highest priority on the system.

The

default

Use this qualifier to shorten the display to within one
worth.
You can change this value by pressing
priority.

ESC

and

entering

screen's
a

new

/RATE:n
The /RATE qualifier allows you to set the rate at which the RMD
display screen is to be replotted on the first display.
n is the
number of seconds between replots.
The default n is 1. You can
change the rate once the display begins by pressing the ESC key
and entering a new rate. The rate setting returns to 1 as soon
as you change pages.
If you wish a slower rate, you must reset
the rate each time you change the page.
Use this qualifier to slow down the display.
The Active Task List may change more often than once per
but once per second is the most rapid rate available.

second,

Example

>SHOW TASKS/ACTIVE/DYNAMIC
The screen is cleared and the following display appears:
RSX-11M V4.1

BL.33

Name
LDR •••
RM DEMO
SHOHO
NETACP
EVP, ••
DCLT5
DBOFCP

Lensth
00002500
00026700
00026700
00025500
00014200
00035600
00044000

LPO
TT5

512K

OWN= ALL

14--NOV--82 19:os:55

coo

200.
199.
160.
149.

1/0 Status fl ass
0. -·CHK FXD STF' ··-PM[I
0. . -CHK WFR --F'M D F'R!J
o. --CHK --PMD PF:V MCR
0. STP ACF' --PMD PR\1
o. STP -PMD PRV
o. -CHt-:: SH· REM PRlJ
o. --CHK STP ACF' -PMD

00014100 coo
00002600 TT5

70.
50.

O. STP
1. -CHK

F' r i

coo

248+

TTO

...... .J.

HTO

... ,;..~ t

coo
coo
TT5

'")'")C"

PRV

NSD

MCF~

NSD

CLI
PRV

NSD

SLV

WFR -PMD

REM

MCR

The screen changes once per second and displays the Active Task
List.
The
first line identifies the operating system, version
number, base level, memory size, the current owner of the tasks
being displayed, and the date and time.
Since the current owner
is ALL, the remainder of the display is the Active Task List

7-56

RUNNING TASKS

SHOW TASKS (Cont.)
itself.
The display includes the task name, its length in octal
bytes,
its running priority, outstanding I/O count, and the
status flags for each task.
(See Table 7-2 for an explanation of
the status flags.)

>SHOW TASKS/ACTIVE/DYNAMIC/OWNER:TT5:
The screen is cleared and the following display appears:

RSX-11M V4.1 BL33
Name

Lens th

SHOT5

00026"700

512K

21-NOV-82

OWN=TT5:

14!57!19

Pri I/O Status f lass

TT5 O.

CHK -PMD

REM

PRV

MCR

This example displays the Active Task List for a single terminal.
The only task active at the terminal is the SHOW command itself.

Notes
The RMD display is in order of priority. When a new task comes
in, all tasks below it in priority are displaced on the screen.
See Section 8.1.9 for more information on RMD.

7.12.3.4

SHOW TASK/LOGICAL_UNITS

SHOW
TASK:taskname/LOGICAL UNITS
logical-unit-number assignments (LUNs)

displays
the
for an installed task.

static

Format
SHOW TASK:taskname/LOGICAL_UNITS

Argument
taskname
Specifies the task for which you want LUN assignments displayed.
This must be the name of a task installed through INSTALL, and
not through the install-run-remove form of RUN.
devices
and
The display consists of a list of physical
corresponding static LUN assignments. The display does not show
any dynamic LUN assignments, even when the specified task is
running.
Tasks installed through the install-run-remove form of RUN do not
have any static LUN assignments.

7-57

RUNNING TASKS

SHOW TASKS (Cont.)
Examples
>SHOW TASK:TEWKSY/LOGICAL_UNITS
DBl:

DBi:
DB1t

DB:lt
TIO:

CLO:

1+
2.
3+
4+
C-

J+

This example shows the display.
>SHOW TASKITT7/LOGICAL
SHO -- Task not in s~stem
This example shows the error message received when you attempt to
show the LUNs of a task installed through the install-run-remove
form of RUN.
Notes
You can display information
about
a
terminal's
assignments with SHOW ASSIGNMENTS, Section 5.10.1.

logical

You can display information about the LUNs of a task installed
with the install-run-remove form of the RUN command with the SHOW
TASKS/DYNAMIC command. See Section 7.12.6.
SHOW TASK/LOGICAL_UNITS is the equivalent of the MCR LUN command~
For more information on logical units, see Chapter 5.
the RSX-llM/M-PLUS Task Builder Manual.
Tasks can dynamically alter their
ALUN$ Executive directive.

LUN

assignments

See

also

through

the

Error Messages
SHO -- No LUNS

Explanation: Informational message.
logical units.
User Action:

The task did not

have

any

None.

SHO -- Task not in system
Explanation: Informational message. Command specified a task
that is not in the system, or that was installed by means of the
install-run-remove form of RUN.
User
Action: SHOW
ASSIGNMENTS
displays
logical
device
assignments for your terminal. SHOW TASKS/DYNAMIC can display
LUN assignments for tasks installed with the install-run-remove
form of RUN.

7-58

RUNNING TASKS

SET PRIORITY
7.12.4

SET PRIORITY

SET PRIORITY alters the priority of an active task.
This is a privileged command.
Format
SET PRIORITY
Priority? pnum
Task? taskname
SET PRIORITY:n taskname
Parameters
pnum
Specifies the new priority you wish to assign to the task.
Priority numbers are in the range of from 1 through 250. n is
octal or decimal. You must add a decimal point to decimal
numbers.
taskname
Specifies the name of the active task whose priority you wish
alter.

Example
>SHOW TASKITT7/FULL/ACTIVE
I I/
066734 GEN 064244 01676500-02062100 PRI - 50.
DPRI - 50.
STATUS:
-CHK WFR -PMD REM MCR
TI - TT7: roe - 1. EFLG - 000000 040000 PS-70004 PC-072132
REGS 0-6 041130 051172 000000 000040 010400 051520 001472
>SET PRIORITY
TASK'? TT7
PRIORITY'? l.99
SET -- s~ntax error

>
>
>SET PRIORITY TT7 199.
>SHOW TAS ACT FUL TT7
TT7
066734 GEN 064244 01676500-02062100 PRI - 199,
DPRI - 199.
STATUS:
-CHK WFR -PMD REM MCR
TI - TT7: IOC - 1, EFLG - 000000 040000 PS-70004 PC-072132
REGS 0-6 041130 051172 000000 000040 010400 051520 001472

>
>SET PRIORITY TT7 225
>SHOW TAS ACT FULL TT7
TT? 066734 GEN 064244 01676500-02062100 PRI - 149.
DPRI - 149.
STATUS: -CHK WFR -PMD REM MCR
TI - TT7!
roe - 1. EFLG - 000000 040000 PS-70004 PC-072132
REGS 0-6 041130 051172 000000 000040 010400 051520 001472

This example shows the effects of SET PRIORITY. The user first
displayed the priority of task TT7 with SHOW TASKS/FULL/ACTIVE.
The user then issued SET PRIORITY to change the task's priority
to 199 but did not terminate the priority number with a decimal
point. The system rejected the command because it recognized

7-59

RUNNING TASKS

SHOWCLOCK_QUEUE
that a number containing a 9 was not an octal number.
The user
then issued the command with the decimal point and it was
processed. The user then attempted to change the task's priority
to 255, again omitting the decimal point.
This time the command
was processed without an error message, but the priority was
changed to 255 octal, which is 149 decimal.

Notes
Notice that SET PRIORITY changes both the running and default
priority of a task. A task can change its own priority through
the ALTP$ Executive directive. With this directive, only the
running priority is changed.
SET PRIORITY is the equivalent of the MCR ALT command.
There is no SHOW PRIORITY
instead.

7.12.5

command.

You

must

use

SHOW

TASKS

SHOW /CLOCK_QUEUE

SHOW /CLOCK QUEUE displays information about tasks currently in the
clock queue.
The information consists of the task names, the next
time each task is to be run, and each task's reschedule interval, if
one was specified.

Format
SHOW /CLOCK_QUEUE

Example
>SHOW /CLOCK_QUEUE
LIONEL SCHEDULED AT
ONEUP SCHEDULED AT
CALDOR SCHEDULED AT
TEWKSY SCHEDULED AT

29-0CT-82
29-0CT-82
29-0CT-82
30-0CT-82

17!41!31!51 RESCHEDULE INTERVAL 05 SECS
17!48!44!05
1s:oo:oo:oo RESCHEDULE INTERVAL 02 HOURS
10!00!00!00

This example shows the display from SHOW /CLOCK QUEUE.
Installed
tasks are placed in the clock queue through the scheduling
options of the RUN command. See Section 7.2.2.
The task LIONEL is scheduled to run at 17:41:31:51
minutes, seconds, ticks) and every 5 seconds thereafter.

(hours,

The task ONEUP is scheduled to run at 17:48:44:05.
The task CALDOR is scheduled to run at 18:00:00:00 and every
hours thereafter.

two

The task TEWKSY is scheduled to run at 10:00:00:00
day.

the

Notes
SHOW /CLOCK_QUEUE is the equivalent of the MCR CLQ command.
Installed tasks are placed
in the clock queue through
privileged form of the RUN command.
See Section 7.2.2.
7-60

the

RUNNING TASKS

This command has nothing to do with queues under the control of
the Queue Manager. Entries in Queue Manager queues are displayed
through SHOW QUEUE.
See the RSX-llM-PLUS Batch and Queue
Operations Manual.

:rr~ 11:2:.:6:F .:sa<>W' ::cbMfoio'N

/' :;~/'_:! .?' ;,X'·>~:; ·~:· '··~·:;_,:•i'·', ,~'> /

<.:.'

,·y.

· · ..,~·

·>'~;,

···. : · .

'">;i

·· .

;·~:rf,,

"»

.:S,a6~:· '~,~·J~:···;tl.:j,:~:~~:a·y~i· .·We . ·:'f'.ta.~~~. ·•.:"~~·· . ·r·e !:).i.d~fi.t .1¢onu11ons .."i'n,sta,;l'.t' ~.µ.·. ,• ih.; .·/to'~
,;~:i,.~::t;~rt,Ji / :;:;~~J~;~;'f:/ j~<;B::::' i:ci.~g ~·~~ g.~s •:•~:.;' t' ;t;h~:/ra' o.~be (it) ,f,: ·~:·t::t:;ab~·ecrl .·.ta~:~s .r(i .~p)l· ,,.~;n:~·
::?1;:9~\:l,,s/" :t>:f:"•~;.t?l~/ ~pmpiqn.,; <' ·· .r.t'Ji.~s"· .,<;:9irtf!}'a1Jl9:•· ,,fa~, . •· to. i:;· ::·R,p.X.+l IM~?LP;S;,' :~Yf>.t:eirl¢:: :<>,nl?,ft
;;";.~.·.··:·,.·/~i,,:"::I ,,'':/·.:.,:.·: ·,:l:,,··~,·..··,.:.·:•·1·,,;:1,::1
;'.;': ··;l::',:· .•.,:·J:'.:'/:"'.,·"'f.tJ. ,:, :
. . . '• .,
'Yol]i,. c•a:n' .~l"s.o. dis:pJa'y' ·,in.for;maif'idn: about· 'a

single'," commQn,
.:i:noltidin}:J »a 'Hst '<H, ta'sks 'att~ched'',.to. the, common~.'· '/
., ,

f }, .~"~ J~ ,'
0

i-'

<.>

~:: -'i f

"<-.

,, .; •

<i>

.,..

·~i,

,,;

.;- '

~ '~ :~ ~:

•

}

f~?'f~~;:t:/

.,....

.,~ ~

:;>,

;: .: "

" : ·~SHow,>cdMM:ONJ:'cbmm,~nri~meJ [,/qu~l·ff.ier{ ,

:.~r~s~·,/ :·:/: ,?.:.
·~:rgj.~m:ent

. . : :tf yqu .:a.a: ·'n:o;t riame .a;· :comm.on;· in,f:o·rmaJ:;Ion abou.t/,a11' cdmmb.ns' irl ::the
· Common. Block Oir.ect;ory
,ls qisplayed·.
>
'

,,, ,

.'·~

>·

·~

,·.

.,:

~'··.:,.~·,

> :<w

,,,

,.'/-

·~

;

,:·

.! «:

~=·' ':·

,·

'·'

• • ,.

·~

• •:·

·;

is· in· :the .fo lfowfog :·.format:

...The ~:,i splay
,.

._.,,-·

.,..

:i=
''

_?;)·,
~

~.:· :

'
'

<,: ,' <:;'.:" ,.

.,
,;.

'<"

;;

~·

/!"

, c<;:>~mo.nnam~ ,pcbaodr'' 'taskc9u{lt s.tatus'~i.t"s , ·

/fo~ £~j;/a;;~~'.a ~ ,·. ·~~oi-~ui~" i; :~;.,~!tie. :(n . ~p e, .ei;~~o. peP<;~@r.":i;

,·.:th~· , :acldre.sa:· .i" .ol". :;the, ,P;a:r, ti;t~bn ::cc)~:tri>·l »·a,:.i,o.ck: :' <·~cs'f, ," tas'.Jico. 4nt''. i's
J:h~ 'n,unib. er: ,:of iaS,k$ . ma.pp:e<t .t<i.· ,the",c.6n1ni<ln}., . . ?na;: ,:··$,tat.us~fts: . i.s . ,." . ~:
.ffs"( ..o.f''.· .common·· r.egi~n ·s'b:h:uei 'bits. that.:· a'dr :set}.· Her·e .i·s a ·1.ist
o.r:·',sta~us Bits anct''tneir,,meanlng's:
.· , >::
.:'· • ·'"
.···., ... ;
~,~''<:>

», '.;' ,,; /

.,,

;

:· '·

''!;-

:~ ;".".<! ,,

,'i>

." : · .' .: .
"' CAF
.:+C.H'.K>
CKP
'CKR· ..~

. COM

· . DEL.
'DRV.

FXD
LIO

LFR
'NSF
OUT
PER
PIC

RON

..,:

;,:

~' ~

:<-

. . . . .", k~cin.i~g :": . ,

. Che·C kpoi n t "a.n oc,a·ti1on' .fa i 1 ur e.
-~~oe.,··,qrrec·~pq·1n~;-a~b1~

· ,~ \.'. ~~ ~,

,'Checkpoint in . progress
f:!ie.ckpo int requ~sted
Library or common
Marked , for delete on· la.st d'etaC.h ·
Drlver ·commoti
Fixed in memory
Long I/O
Last load failed
Not shuffleable
Out of memory
Parity . error
Position independent
Read~only common

U'sually, the status bits will indicate that the common region
either fixed in memory (FXD) or out of memo~y {OUT).

7-61

RUNNING TASKS

SHOW CO'MM,ON (Cont.)
commonname
SpecJfies a
di splayed.

common

name

about , which

information. , is

Command Qualifier
/TASK
Specifies that you wish a list of tas,ks attached to a particular
common reg ion showing the number of times each task is ·mapped to '
the common (mapping count) •
Examples
>SHOW COMMON
BASIC2 050644

ItEPRES

0 SHlTUS !

DSMBUF
DSMSUP

FCSFSL
TT COM

056340
053630
064164
l.17210
034620

STATUS!

5 SH\TUS !

... STATUS~

i7 sTt~rns:
1. srr~rus~

COM
COM
COM
COM
COM

PIC

FXD COM

This example shows the display from the unadorned SHOW COMMON
command. Currently, six commons are installed in the system.
>SHO COMM:

DSMBUF
5 STATUS!

COM PfC

This example shows the display when a single common is named.
>SHO COM: DSMBUF
DSMBUF 0536:rn
DSM IO
DSMGAF:

DSi'il 61

TASK
~;

ST~nus:

COM p It.:

1
1

This example shows the display when a list of tasks is
for a single common.

Notes
SHOW COMMON is the equivalent of the MCR CBD command.

7-62

requested

CHAPTER 8
SYSTEM CONTROL

The commands in this chapter are used to control and display certain
system level functions.
The SHOW commands in this chapter are
nonprivileged, but all other commands in the chapter are privileged.
Other commands needed for system control may be found in other
chapters of this manual, in the RSX-llM/M-PLUS MCR Operations Manual,
and in the RSX-llM/M-PLUS System Management Guide.

8.1

SET AND SHOW

You can set
UFDs, and
display the
system, and

8.1.1

and display the time and date, the system and
the size of the dynamic storage region (pool).
logged-in users and the current use of memory
you can enable and disable logins to the system.

library
You can
on the

SET DAYTIME

SET [DAY]TIME sets the current date and time.

Format
SET [DAY] TIME [date]

[time]

Parameters
Either the time or the date, or both, can be specified in the
command.
They can be specified in either order.
If you do not
specify a time or a date, you will be prompted.
The date field and the time field must be separated by a space.
date
Specifies the date.
formats:

You can enter the

date

either

two

dd-mmm-yy

Where dd is the number of the day, mmm is the
first three characters of the name of the
month, and yy is the number of the year
(relative to 1900).

mn/dd/yy

Where mn is the number of the month, dd is the
number of the day, and yy is the number of the
year (relative to 1900).

Regardless of the format you choose, the date is displayed in the
first format.

8-1

SYSTEM CONTROL

SHOW [DAY]TIME
time
Specifies the time.
hh :mm [: ss]

Time is entered in the following format:

Where hh is the number of the hour in the
24-hour format and mm is the number of the
minute. ss defaults to 00.

Examples

>SET TIME
Time?

8t05

This example sets the time at 8:05 on the current day.

>SET DAY
Date?

16-JAN--66

This example sets the date at January 16, 1966.
is unchanged.

The time setting

>SET DAY
Date?

01/14/63 17:14

This example sets the date at January 14, 1963, and the time at
17:14:00.
The date will not be displayed in the format entered
but as 14-JAN-63.

>S E T DA YT I ME 0 b -- J U N-- 4 •l 0 4 : 0 0 : 0 0
>S E T T I ME 0 4 : 0 0 ! 0 0 Cl 6 -- .. l UN - 4 4
The examples are equivalent.
and the time at 04:00 hours.

Both set the date at June 6,

1944,

Notes
Regardless of the prompt, you can
either order.

enter

the

date

time

SHOW [DAY]TIME

8.1.2

SHOW [DAY]TIME displays the current time and date.
The
24-hour format and the date is formatted as dd-mmrn-yy.

Format
SHOW [DAY]TIME
SHOW TIME
SHOW DAY

Example

>SHOW TIME
04:00:22 06-JUN-44

8-2

SYSTEM CONTROL

SET SYSTEM
8.1.3

SET SYSTEM

SET SYSTEM establishes certain characteristics of the system.
privileged command.

It is a

Format
SET SYSTEM[/qualifier]

Command Qualifiers
/EXTENSION LIMIT:n
/[NO] LOGINS
/PACKETS:n
/POOL:top:max:total
/DIRECTORY: [g ,m]

Command Qualifiers
/EXTENSION_LIMIT:n
The /EXTENSION LIMIT qualifier establishes the maximum size to
which a task- can extend itself by means of the EXTEND TASK
directive. n can be entered in all the formats used in the SET
PARTITION command.
See Section 7.12.1.
See the RSX-llM/M-PLUS Task Builder Manual and the RSX-llM/M-PLUS
Executive Reference Manual for more information on the Extend
Task directive.
/[NO] LOGINS
/[NO]LOGINS enables or disables logins.
If you issue SET SYSTEM/NOLOGINS and then log out, you will have
to reboot the system to log in again unless there is another
privileged user logged in.
/PACKETS:n
The /PACKETS qualifier specifies the maximum number of I/O
packets to be retained in a separate queue for use by the QIO
directive.
Changing the number of retained packets
helps
optimize the servicing of QIO requests.
n can be from 0 through
15. The default is 5.

This value is a system-generation option on RSX-llM systems.
On RSX-llM-PLUS systems, the. value is usually set as
the st~r·tup procedure.

part

This command is equivalent to the SET /MAXPKT command in MCR
VMR.

and

SHOW SYSTEM/PACKETS displays this limit and also
packets currently available. See Section 8.1.4.

8-3

the

number

SYSTEM CONTROL

SET LIBRARY/DIRECTORY
/POOL:top
The /POOL qualifier increases the size of the system pool
(the
dynamic storage region) •
The
top argument
is the number of
32-word blocks (decimal).
The max argument is the maximum size
in decimal
words.
The
total
argument
is
the total size in
decimal words.
/DIRECTORY: [ g ,m]
/DIRECTORY establishes the identity of the system directory.
The
UFD you name must already exist.
This command does not create a
UFD.
/DIRECTORY is the default qualifier for SET SYSTEM.
See the discussion in Section 8.1.5 for information on the use of
this command on RSX-llM and RSX-llM-PLUS systems.

Examples

>SET SYSTFh
S~stem UFD?

[3,54J

>
>SET SYSTEM

L3r54J

These commands are equivalent.
They establish
directory as UFD [3i54] on pseudo device LB:=

the

system

>SET SYSTEM/EXTENS!ON_LJMIT!1200
This command sets the maximum size to which a
task can extend
itself through the Extend Task directive to 1200 (octal) 32-word
blocks (decimal) or 30K words.

8 .. 1. 4

SET LI.BkA.RI/Of.REC1'0.RY

The SET LIBRARY/DIRECTORY.
Rsx...:11M-:-J?LUS system.s ..

command

establishes

the

library

OFD

between

SET

This·· comma:nd" ·e'~tabli'she~· .th~·::id~ntfty' of .. the sy.stem • ':tibrary'

UFD

See. the di.scussion in Section

8.1.5

for·

the. · relati.on

LIBRARY/DIRECTORY: and SET SYSTEM/DIRECTORY~
Format

on ... an ·.:Rsx-IlM.:'.:.:P,LOS' . sy.s·t.~m; ..· ~he· .conmiand . does not c.teat~ Ji .
.dir.ecfo~y..
Th;e ,'dir.ector'y must exi$t .before,,, you·. issue the·
command..

8-4

SYSTEM CONTROL

SHOW SYSTEM
SYSTEM AND 'LI~RARY:; UFOs

8 .1. 5

On RSX-11.M systems, the system image file and all system tasks and
utilities are kept in the system directory on pseudo dev.ice LB:. You
can display the current setting for this directory with the SHOW
SYSTEM/DIRECTORY command.
Privileged users can change the directory
with the SET SYSTEM/DIRECTORY command.
When .you issue a RUN or I,NSTALL, co.mma,nd ·and precede the f ilespec (.that

is; the task image file name)
with a dollar sign' ($)'1 you are
instructing the syst~m that the task you wish to run or install is in
tnis dLtectory,:

b.fl.,, .!isx;~Eii.:

l ::sy~iem.~·17 ~Ji;e': ~is

:.i~ii$4~~?JH:l,ie? F~ila::)·

it:'1tf.:'J P:~:Yv(~e9.~r

!s'yst!=m: ta$, s .'· .·a:fe:, ,~ept:' .;in :·J:.he;'
. ·m·;·cti:riec:to#y}: orr,;ps·eudo; .iqevi.ce ·LB::;:;'
:roii. :dan:.tfis'pl}~;y: :.:t;ti'e.:·: o.,to.
e/··:;sliewl:; iS¥S'fE.M/9I~EQT(fgy.:"·:ci6mm:~f1«:i:x.
fp·~i'v'ileged;: .:.us'e;rs ·Jcan:L ::cha'nge;i.•·· the:'.1 :uF't) ..~:*th:.·:the~$ET.>,·s:Y$TEM)nrR;EC'!'b;R·¥ ·
:¢p#·~:~a·:.;: ::.:·~i:l.::'i1~~~~1:~.~1~ 9~~a::,~~~~~·em; . :·ea:~:~.:s:::::~~a;·:.:;t1H.·:i;~,t:i~s:'.·ar:~::iJ<eI?J:*.;fo.:::t:·iie
:1tbi::'ary ·UFE> .oh .pseude· dev,ice:, f.:B.: :. : Yo·h . c.c\r)r display the :cur:tent· ·setting;
fOi: : .t;h,is ·:··· d i~:ec.tor.,y :'.:with ,' '."bh~'." ,;SHGW'.' ·. ' 'LIBRARY/'O I ~ECTORY: ; ·comma.nd ~·
.:.pJr.i:V·~·ie9 ea· ;·;,~:sei;:'s:.~ ,, ~·ca.a§:-· ·~:h'a~ge::· · ;t:l)l:r :: a::·i:·tec~ry:: , · w.Lth : : the . :sE~·'

;'w±·tli ..·

,,~·IB~ARY/PI.REC'f(lRY:'.: cqinma"rid..

"·:.· .: ·· · · .

. . · , ' · ·:

'. ' .. ,: · · · ,

.., ";.

::~: ' :;· :· ; '\ :" ; '·: :: .: .~· :; ,: :" ." ,' .~'} i ,:.: ,': '::: ~ . " : ' ' ' ' .; " . .· . ' •. ' ;· . . ; :· ·• . ' " . .· .· ·. . •.·· ..·
.. '
•. ' ' ' ''
·wti¢n •·:you'• isstfe· ··a:'RUN.Olc:; :HfSTA~L: <:.ornm.~ha .·~nd ·f>redede ..the: fi.les.l?~c: ·" (th.e

t.ask, 'imag.e·· .fH~:name} .wft:h . a~.1::101tar sign.'($.):, you· are .instructing.the

. syste111· that.·th:e . task." Y:O•U; · wi'sh ·: 1:0 run .o:r. install/ :is ... in· ·one·. of
these·
·~.i,r~ct<':r:i:e~·: .~ · ;rfie . ::,;ay~·f:~m:· d;i:t~t!;,~o:r;~y ,'. ··,;is·. :·~:e:~·:rc;:h~a. f.~rst·::ana:.: :tJ;i,en · tpe',
l~~iar¥ direq~9ry~

8.1.6

SHOW SYSTEM

SHOW SYSTEM displays information about the current system.

Fermat
SHOW SYSTEM(/qualifier]

Command Qualifiers
/CLI
/DIRECTORY
/EXTENSION LIMIT
/PACKETS /POOL
/SECQ,NDA~Y-~J?OO(.

Cemmand Qualifiers
/CLI
SHOW SYSTEM/CL! displays information about each command line
interpreter
(CLI)
on the system. The information includes the
name of the CLI, the name of the task that implements the CLI,
the number of terminals set to the CLI, and several status flags
for the CLI.

8-5

SYSTEM CONTROL

SHOW SYSTEM {Cont.)
Here are the status flags:
ACT
DSB
PRV
RST

CL!
CL!
CL!
CL!

is
is
is
is

active.
disabled.
available to privileged users only.
restricted.

For more information about adding CLis to the system, see the
RSX-llM/M-PLUS MCR Operations Manual and the RSX-llM/M-PLUS
System Management Guide.
There is no SET SYSTEM/CL! command in DCL.
/DIRECTORY
SHOW SYSTEM/DIRECTORY displays the current system directory.
The
display specifies SYSUIC, but the system directory rarely has a
UIC associated with it;
it is a UFD.
SHOW . LI:BRARY1/0J;R$C'rQR¥
displays the current library dir:ectory. See Section 8.1.5 for
more information.
/EXTENSION_ LIMIT
The SHOW SYSTEM/EXTENSION LIMIT command displays the maximum size
to which a task can extend itself by means of the Extend Task
system directive. The size is displayed as an octal number of
32-word blocks (decimal).
/PACKETS
Normally, some number of 18-word I/O packets are set aside in
pool and retained
in a separate queue for use by the QIO
directive.
This number of packets (referred to as MAXPKT)
is
used to optimize the servicing of QIO requests.
The SHOW SYSTEM/PACKETS command displays the maximum number
the current number of available I/O packets in the format:

and

MAXPK'l'=m.: ~.

where m is the maximum number of and c is the current
available I/O packets.

number

/POOL
The SHOW SYSTEM/POOL command displays the current status of the
system dynamic pool as three numbers, flor:
lfb:
tps, where
flor is the first location available for user partitions, lfb is
the largest free block in decimal words, and tps is the total
pool space in decimal words.
The SHOW MEMORY command
(Section
more information about the pool.

8-6

8.1.9)

displays

considerably

SYSTEM CONTROL

SHOW LIBRARY
SHOW USERS
/SECONDARY_POOt
.'rhe SHOW SYSTEM/SECONDARY POOL command, on ~sx...;UM-PLUS . systems
displays information about secondary.pool. : The. display· ~s :.: i:h: .'the
following format·:, · ·
·
'

S,ECPOt=fr.ee.::size:P,6t: ·
where. free·· is. the ·amount· of···· -f·ree. :&~conq:ary, · p(jo1.:: .in 32.::.wot'.a
· plocks~. size is 'fhe'"si.:z.e of·secoridary:po!).~ 'in 32-word.,':blocks, ·-and·;
' 'pct 'is 'the pe,rcentag,e. "of free hl,ock,s ,in ,secqndary eool ' :
'

(

, >, ,, , . .

,.,,,,, •

'• u ' '· '

u.,m

;

.;'.

: :"

•',

;

'~'

,;.

.:;

;

SH.OW LIBRA,RY

8;.l.7

.The SHOW LIBRARY command displays the current .. library directory on'
RSX-llM~PLUS
systems. .. The display specifies· LIBUIC, but the., library
d:j_,rectory .rarely has a ,:UIC: assdcic:;tted .w.ith :it;: ; it/ is· a:: OFD~.
. . . , ..

8.1.8

SHOW USERS

SHOW USERS on RSX-llM systems displays the terminal number
UIC for all logged-in users.

and

SHOW USERS on RSX-llM-PLOS systems displays the terminal number, l()gin
UIC, , and :defaul~ UFD for, ail logged-in users;~ . I.~, ~e:source {\c~oll,·nt.!~9
;i $. supported . and ·i's'. running, ·SHOW. t}SE.RS . on RSX-illM-,PLUS al:so shows" the
date and .. time·· (,)f. login, the. numhe+ ·of :ta~ks acbive: on.· the terridnal.,:.
and the user na.me' of the .person Jogg~d, in..
·
·
··
.. ,
,,. ,h

Format
SHOW USERS

Examples

>SHOW USERS

no:
TT2!
TT5!

TT?:
TT16:
TT51:
TT54 t

HT2:

[3,54]
[7140]
(30lr3}0J
(200.1J

[7,42]
[7,26]
[303,5]
[7,43)

This example shows the SHOW USERS display for an RSX-llM system.
The first column identifies the terminal. The second column is
the login UIC for nonprivileged users and the current UIC for
nonprivileged users. HT2:
is a DECnet host terminal.

8-7

SYSTEM CONTROL

SHOW USERS (Cont.)

:.:lT2f. . E7.t41'.>J,· . .
../. TTS·~. . · · /,[ 30 i', :5'70':'.f ···

.i/r,i7,:1:· ·, :c.2'0<) •. t'J
·.ci./42J·...:
:n20:. ''.f2·00, ZOJ.

.. :.',,,:1'.Tl6)·.
..~T5i.,t,
,, , / ' ll.5 4 :

.,Tb2J·,·
C:,1' l.Q·] ; .., '

,;·:)-i ·i'2T "' • £.7(4/H'.

· · L7·, 4lJ.:·J
.. C~Ot; 310'J
' c2:00 ~ t·J ''

· {r,4':t:1 · · ....

'c7.;3n . ·.

: 1:7,·26~'.I

·.c361,5,.1·
,(7,,,43]

>Thts. ewample. sh~ws· tl}e 'SHOW' USE:i~·s' cl':isp.laf.
. .· '·RSx.:ilM-PLUS ''
·~Ys.tem .,witp.ouf ·.Resource ·Accounting· .active •.. T:he f.i rst column .
identifies. the. tertninal. The. second column .is the . default UfD.'.'
Column 3 is the log:i.n · urc·~ HT2·:.
a· DECnet ·hos't: terminal. · ·

·is

>SHOW· USERS
·TT7:
·TT10 !·

):'J, 40]

[7·, 40]

7·· N·OV;_82

1o:s7.

. A• GROUPE.

C3031SJ.

C), i'OOJ

'7·~N'JV·•82

lU 1()

TT14!

[7,25]
(7' 25.J
[1, 1J
C7150J
(3141362] (7, 14]

7--NOV-82 13!56
7-NOV-82 11 !06

()·,

WRITERS
FOX
B+ CAUHJELL

C7160J
[12'10]

[7,60]
[ 7'24 J

7-NOV-82 11:15

TT30t
TT32 !

(1,bJ
[303J2]
[303'10]
[301d1J

[7d3J
(303,2)
[303'10]
r7'11J

0
0
1

TT::\::\!

f7.th1

[7'16")

TT34 !
TT35!

[7,21]
t1124J
(301r370J 1:301,370]
[7,302]
[71302]
[303,14] [303, 14]
(303112]
C303r12J
[304,3251 o,:~25J
[30:~, 2~D
C3C•3,23J
(7,43]
[7,43]
[7,:LO:J
C7161J
[314t362J i:/,362J
(301'356J (3()1,356]
C:304,27J
[ 30'4 '27J
[30315]
(303,5]

TT15 !

TTHd
TT17:
TT20!
TT21 !
TT27:

TT36:

TT37:
TT41 !
TT42t
TT43 t

TT45 t
TT46t

TT47i

H50t
TT51!
VT3!

7-NOV•82 1(): 47
7-NOV-82 10t50
7-NOV-82 12:55

()

W+

B. Ai"1BER
F' + LTEBERWIRTH
D. Bf\OWN
B. MABRY
L. SWEENEY

7-NOV·-82 12:33
'7-NOV·-82 14!14

0
l

J. PAINTEF:

7-NOV--82 10t56
7-NOtJ-82 11t08
7-NOt...1-82 12!:36

0
()

J. KASSON
F. BAATZ

A+

7-NOV-82 10:55

S .. ADAMS

7-NO'J·-82 13!01
?-NOV-82 12t36

1
0
0
0
0
0

J. MORAN

7-NOV-82 10:56
7-N(}lJ-82

11~17

7 -- N0 V-· B ~'. 14:35
7-Nov~a2 10:5:3
./'"Ii....,
"7-NO-V ..-82 ".::·'
J. ·.J + V..:J
7·-NOtJ-82 1UO?
7:-NOV--82 10:59
7···NOV-132 15:04

...

£.

BODGE

(' . FOOTECOL.E
P. BEZEREDI

,.J • PETERSON

J. KAUFFMAN

....t.'E +•

F'OLL.Aet-:;
A T'1r,A)..(1.~·. ·j\ l.t

M.C.>1\MI ,,JI.JI~

,J •

THOMPSON

()

[I •

CMMAN

·-

T+ PAF:MENTEF:

'')

This example gives the SHOW USERS display for an RSX-HM-PLUS
system with Resource Accounting. .The first column identifies the
user's TI:, the second co1umn i~ the current .default UFD; the,
third· co1umn. i.s t.he :Login UIC 1 t:he fourth column gives the dat.e
and time of log i h, the fi.fth column is the number of · tasks
curient.ly active,. and. the . sixth column is the user.· name.
If
·Res·ource . ?\co\mt ing is. nqt acti v.e .or i:l}nning at. t:he tir,ne of login,
the · last. t.hree columns are not .displaye,d. .The user on TT16: in .. ·
the . example lo9ged in.. :when Res.qur:qe Accounting wa.~ not;. active.

8-8

SYSTEM CONTROL

SHOW MEMORY
8.1.9

SHOW MEMORY

SHOW MEMORY invokes the Resource Monitoring Display (RMD), a system
utility program. This program displays in a graphic manner the status
of much of the system. It is, in effect, a display of the contents of
the system pool (dynamic storage region).
The RMD program is useful for monitoring the general activity of the
system.
It is also useful viewing for a new user to see how the
operating system operates. However, you should understand that the
graphic display is approximate and cannot be used for critical
measurement.
Format

SHOW MEMORY
Example

>SHOW MEMORY
The· following example shows the SHOW MEMORY display for
The circled numbers are keyed to the explanation.

-----A. . --. .,.

RSX-llM.

RSX-11M V4.0 BL32
C) TASK= *IDLE*

G POOL=,1686. !3169. !55.

<QUASAR> 512K
8 FREE= SYO:l8470.
DB1!62322.

12-MAR-81 10:59:16
DB2:14542.
DB3!DMO
PARS

1686. !3168~ t55+

l . ~~::m

CEXPAR:C
TTf'AR :T

.·.·l·H:K·l.·· I.~·~~~· ·~.
OUT:
4

31K

C.
0.

<>!>J>

. R
E

S
t-!

~i~~ : ~ ~
LE. A
M. T
Q, •

:~ ! ~ :

1
F

F
C

C T
A 5

A
C

T
1

L
B

• . $
.·

<>>>>-->-->--->---->><->--> <----->----->

DRVPAR: D
LDRPAR: T

BASIC2:C
FCSRESfC

~~~~~~g~~~~~gg~~~~g~~g~~~~g~~~~g~g~g~~g~~g~gg~~~~~ l·~~!PAR;~
G} ERRSEQ
o.
ZK-288-81

The , fol,1.owing,. exam'p1e: . shows,,,' ::'th~· : :·sac)'~ ·M~MORY: · dis.p:lay . ·fo.r
RSX-llM-PLUS..
The circled nlimber·s are keyed· to the explanation,.
Some numbers appear on the 'RSX-:llM:-PLUS.~xample o.nly.

8-9

SYSTEM CONTROL

SHOW MEMORY (Cont.)

~~·------,.,,,..A..~·-------...,
RS.X-HM-f'LUS V2 BLiO
.·<CASTOR> .512K.' UP 000:00:49
6-J:iEC'.>-eu
0 .FREE.'=. · .. SYO: 16954. t!B1 :Ill'\fO
··
. .
'It~0:.8755 •. • .D.B2HlMQ
0 SECPOOL::::64 • :·256. :25°1. .
•.

Q TASK~ f'If'H1 .
O Pood=i7o~ :14B;4d?4·

.. .

170'+ :1404. :74.

•

1~:25#53 '

f'ARS.

o;4: ... :256. :·2'57.

'SY]$PM:D

Lt•Rf'AfU[t.
M It 'tr

·'{1N•· '}

RCilMTTPSZ' BPR RR' RR NNF

F LNNG £<

PCPf"ARUt·

f•r

··~· •.~!.~.:1. ·• · 7H ~~~ ~ ~ ~~ ! !U~ ~ ~~~ •~· ; ·~· .; •
.

i$ECPOL!P·
IIR~:D

GEN

m·

i· · . ·.: M 1
Gli 0$ Of'
LPL fi XP.
O·
.. '. <>'!.!--> ·. )))).!>>>:::~ :::+-<>~}->>->1 !·-!-->>J>->-:.>-->!===·!-:-+-

·.·.~!~~.~:.~.~~=~i. .~~~~..:~~~~~~~~+~~~~.=~~~~~·~=e~~~~.*.-~=~·=~~~~~=.·.=.·~·.~~~.··~. ~··I:.·.•
----;------------·-·-:.-.~--·--.----,-.-.--..-------"1----- --,.....-·-.---:-=~,-------~-~··

256•***288***U320*****352*1**U3814*****416t****44S*,****4~****.'.
->-.!l>-):""-><->+~---+

A I'c~R A
T N.MM ,T

L
0

. 'NV•
Inn .
,v
ti

T F
3 s ·1:n 1 '·~,
2 L j() '1

T
3
3

n
T'

1
F'
H
1

•
ZK-287-81

0
8

Operating system type, version number, and base level.
Six-character name that is a DECnet node name (if DEcnet is
running on your system)
or the system name that you
~PlP~tPrl in SYSGEN
(if DECnet is not running on your
system) •
Size in K words of the system memory.

F<>r: tRS;:l{·-11~-PLUS; sys'tems, time elapsed tn . units
~ur's, and' 'minutes' si'nde .the

of~

;daY;~:~

system: was last' :bc)oted.

Current date and time •
.. ,. ___

L'l01lll::

-.t:

V.L

.&...\...L.lll::

.L..--1-

L.Q;:)f\.

L\...-.L..

L.lJOL.

.;_
.L;:)

-··-...---.S..1 . . .,

\...U.L.L<::llL..L)'

-··--, .. .a..~--"""V.L I

<::"Jl.C\...UL..1.ll'::j

.:.f=

.1..L

.,.._,,...
...... ,..._
LIVLIC

.J...;;J

executing, *IDLE* (Executive executing the idle loop).
Number of free blocks on four Files-11 devices in your
system.
If a device is dismounted, RMD displays "DMO." If
a device is off line, RMD displays "OFL."

Pool (dynamic storage region)

information in the format:

POOL=X:Y:Z

Number of words in the largest free block in pool

Number of free words in pool

The second line records the worst case of pooi since you
invoked RMD.
This line is most useful if RMD has been
running on a slaved terminal since the system was last
booted.

8-10

SYSTEM CONTROL

SHOW MEMORY (Cont.)
on RSX~llM:...·p'LUS s'ystems'i ·'se:c.oridary·po'cil fnfo:rmation ib'
'forinat: ·

· ·.t{um.beF/Pf:.fre~· blo:~ks· .. :fl) ;:·sec.p.tia~~n::y .·popJ ..

ro~,.1 llwn~er :Of blo.Ck~ ;~t~eco~~a'rY ,'I!<>oix:

·..· .·· :pei:.¢e-llt~9~ ;~: ·seco11d~;,i_ ~~~ :~h~t :~/~r~k;

.. /:~he .. ~ecOna :1 f ne :·£~cortls .. th.e: ..·wo:r:~:~··::.CG\:~?: ...:of.·. ::.:$~¢of1iiar&£';/:·P5>~·J! .i
·.s:~~Q'<?·~· ,:y~tJ./~11v:~~ect ··RM{)~··· :irl;i:~s:: ·:~.£ n~ . J•'f;: ni(.')st;.·:·tis~~·fu·:v .::i:'~:· .:~r-tp.:::i:Ya.~:·.~
;bb·.:eo·..···eO:~. . e. . ·. .•dr.•
. ..~u•.
·-

4ID

\,,;,.

nni ng .; pn.· .a.,· sl ~;'z,~d-~ ·;~:~.·i:.~;i'.!1,~~:i
{ sfner./?t~~:· iii.~.ieefi .: W:~~/ ";~./~.·:. ~..·~t.//:
l~
-~: f ,; 5~
~
t

,.;

.,.

.f:

;; .

/;;

::>

··,

_.,

Partitions in the system using the format:
partitionname:type
type
F,dr Rsx:...1111 sys.terns T one of the fo·llowi ng:

T
S
D

.Task partition
Subpariition
System-cont·rolled (dynamic) partition
Command partition

·Far RSX~llM-'PLUS .s:ystems:~ . one .of

the following:.;·
~·

;

""!.,

·o.· ·.;",;system-·conBrcifiea>(dyfiam.i~}:.:f)ar.tTti:on;:
"· ;·~
~~.C'O Q<;t·a.~·y .: PP·°'··~; ;:Pi:tfr;t;~;t 10 n: '. : :' :·: ' . . . .
.• . . . .. ;
~

Number of tasks in memory and amount of memory they use and
number of active tasks swapped or checkpointed out of
memory and the amount of memory they would require.

4!)

Name of each task, common, or driver in memory and its
location in memory using the following symbols to designate
size, type (task, common, or driver), and other attributes:
Attribute

Symbol

[

]

Active task
Task not active but occupies memory
Named common
Unnamed common (displayed name is first
attached task)
Loaded driver using device mnemonic
Task not fixed in memory
Task fixed in memory

The hyphens and equal signs represent the amount of memory
that each task, driver, or common occupies. Where the
display shows only one delimiter and no hyphens or equal
signs, the open delimiter is in the same location as the
closing delimiter of the preceding task.

8-11

SYSTEM CONTROL

SHOW MEMORY (Cont.)
®

Partition size and location.
The beginning of
each
partition is marked with the same symbols as those listed
previously plus the following additions for both operating
systems:
E
P

Executive
Pool

The lines of asterisks are proportional representations of
the amount of memory occupied by each partition.
The
numbers are in lK-word
increments.
Each
numerical
character also represents the same amount of memory as an
asterisk.
~

System error count sequence recorded by the Error Logger
(always zero if Error Logger not present in your system).

Notes
RMD must be installed under the name ••• RMD for this
work.

command

RMD adjusts its display to your terminal model.
If you are at a
video terminal, the display changes as you watch it.
If you are
at a hard-copy terminal, a snapshot of the display as of the
moment you issued the command is printed on your terminal.
Often, RMD is set running on a slaved terminal near the
as part of the system boot procedure.

computer

Task locations and sizes displayed by RMD should be considered
approximate.
RMD is primarily designed
to provide a visual
display and system debugging tool.
It does not measure task size
or location accurately.
In general, RMD is designed to allow either an operator or user
to
view the current state of the operating system.
The
information is presented
in a graphic,
easily comprehensible
form.
There are a number of specific instances in which RMD can help to
locate certain system lockout problems or bugs in application
and/or system-level software:
•

Bugs and other situations that cause exhaustion of system
dynamic memory
(resulting in unexplained system hangs)
may be detected and more easily reproduced and diagnosed.

•

Task checkpointing and swapping can be monitored and,
in
systems with limited memory, deadlock conditions can
often be diagnosed more easily.

Free space on a
number of Files-11 devices may be
• monitored
in real
time,
which may help in situations
where on-line storage is
program is running wild.

8-12

premium

where

some

SYSTEM CONTROL

SHOW MEMORY (Cont.)
Other pages in the RMD display are invoked by the
SHOW
TASKS/DYNAMIC command (Section 7.12.3.3). Once you have started
the RMD display by either SHOW TASKS or SHOW MEMORY, you can move
from page to page without
issuing any more DCL commands.
In
fact, RMD is meant to enable you to watch the activity in memory,
on the active task list, and within a single task header and to
note the relation between these pages*
See the RSX-llM/M-PLUS
System Management Guide for a full explanation of all the
functions of RMD and--ror-descriptions of the commands used within
RMD to change from page to page.

8-13

CHAPTER 9
QUICK REFERENCE

This chapter lists all DCL commands in alphabetical order.
Each
command
entry
includes
cross-references
to the full command
description in this manual or to other RSX-llM/M-PLUS manuals.
Each
command entry also includes a general description of the functions of
the command, as well as the full command syntax, sometimes with brief
comments behind an exclamation point (!).
These command descriptions are intended for quick reference only.
If
you are not familiar with the functions of a particular command, you
should read the main text referenced in this chapter.
The comments
are in shorthand form and are meant to serve as reminders only.
Comments include examples of input, value ranges, and cautions.
Privileged commands and qualifiers are flagged as are commands
available"on',RSX_;llf:1,_;PLUS- "O:nly:.
A number of commands have two
qualifiers listed as ~ynonyms.
Other qualifiers perform no operation
by themselves and are listed
in the comments as "no-ops." These
synonyms and no-ops are usually included for compatibility with DCL on
VAX/VMS systems or for clarity and completeness. See the main text
for more information.
This chapter does not document the differences between DCL commands as
used interactively and DCL commands as used in RSX-llM-PLUS batch
processing.
Nor does it provide descriptions of the batch-exclusive
commands, which are not part of the DCL command set.
See the
RSX-llM/M-PLUS Batch and Queue Operations Manual for descriptions of
these commands-.~~Thrs- chapter also lists and summarizes the DCL
commands used in setting up the Queue Manager.
The RSX-llM/M-PLUS
System Management Guide includes full details on using these commands.
For your convenience, some frequently used commands have brief forms.
These
short
forms
are not necessarily compatible with other
implementations of DCL and are provided for the convenience of
RSX-llM/M-PLUS users.
They are:
A

ABORT

HELP

BROADCAST

HELP

COPY

LOGOUT

DIRECTORY

LINK

DEA

DEALLOCATE

MACRO

DEAS

DEASSIGN

EDIT

RUN

FORTRAN

SHOW

9-1

QUICK REFERENCE

Section 7.3

ABORT

ABORT forces an orderly end to a running task or to the action of a
specific command.
Nonprivileged users can abort any task running on
TI:,• . ']?r:i'•ii'l~g~..: .:us~'rs: ,'on . ~SX:-11M-:PL,US can . a,'}).orti;<=t.ny tas·k by \J,~·~~g:'.the
j:?;~RMl~.~~Jqu11:~J·fi,e.:r;,~·
· ·· · ·

ABORT[/COMMAND] [/qualifier[s]] commandname
ABORT/TASK[/qualifier]

taskname

Command Qualifiers
!Default

/COMMAND
/TASK

./TERt,fINAL;::ttnn:
/[NO]POSTMORTEM

Section 5.4

ALLOCATE

ALLOCATE declares a specified device to be a private device.
If you
omit the unit number and colon, the first available device of that
class is allocated.

ALLOCATE[/qualifier[s]] dd[nn:]

[logicalname]

!Logical names same as
!other device names:
!Two characters, octal
!unit number, and :.

Command Qualifier
/TERMINAL: ttnn:
I

/'flVPR•rlAuif"At-vnA

----·--·----.1.r-

!Privileged
!RP06; RK05; RLOl; and so on.

Section 4.4.3

APPEND

APPEND appends to an existing sequential file records from one or more
sequential files.

APPEND[/qualifier[s]]

infile[,s] outfile

Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mrnm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmrn-yy
/TODAY
/EXCLUDE:filespec

9-2

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

QUICK REFERENCE

Section 5.2

ASSIGN

ASSIGN associates a
logical name with a physical device,
pseudo
device,
or other logical device.
All references to the logical name
are resolved by the system to the associated physical device,
pseudo
device, or logical device.
See also other forms of the ASSIGN command
described in the following entries.

ASSIGN[/qualifier[s]] ddnn: logicalddnn:

!Logical names same as
!other device names:
!Two characters, octal
!unit number, and :.

Command Qualifiers
/LOCAL
/LOGIN
/GLOBAL
/SYSTEM
/TERMINAL:ttnn:

!Default
!Privileged
! Privileged
!Privileged; synonym for /GLOBAL.
!Privileged

ASSIGN/QUEUE
See the RSX-llM/M-PLUS System Management Guide.

ASSIGN/QUEUE establishes a path between a queue and a processor in the
Queue Manager subsystem.
Privileged.

ASSIGN/QUEUE queuename processorname

ASSIGN/REDIRECT

Section 5.2.l

ASSIGN/REDIRECT redirects output from one physical device to another.
You can also redirect output from a physical device to a pseudo device
or vice versa.
Privileged.

ASSIGN/REDIRECT oldddnn:

newddnn:

9-3

QUICK REFERENCE

Section 5.5.2

ASSIGN/TASK

ASSIGN/TASK reassigns an installed task's logical unit numbers
(LUNs)
from one physical device to another.
The reassignment overrides the
static LUN assignments in the task's disk image file.
You cannot
change the LUNs of an active task.
Privileged.

ASSIGN/TASK:taskname ddnn:

lun

BACKUP

Section 5.9

See also the RSX-llM/M-PLUS Utilities Manual.

BACKUP backs up and restores Files-11 volumes.
It transfers files
from a volume to a backup volume and retrieves files from the backup
volume. BACKUP works through the Backup and Restore Utility
(BRU).
You should read carefully the main text entries on BACKUP and BRU
before using. this command.

BACKUP[/qualifier[s]] sourceddnn:[filespec[s]] destinationddnn:
Command Qualifiers
Group 1:

Selective Backup and Restore

/AFTER:(dd-mmm-yy hh:mm)
/BEFORE: (dd-mmm-yy hh:mm)
/CREATED
/EXCLUDE
/IMAGE:arg
SAVE
RESTORE
/

!Use with /CREATED or
!with /MODIFIED.
!For multivolume disk operations.

/ .. •nnTOT'C'tJ""\

l"JVLI .L J.: .L J.:JLI

/NEW VERSION
/[NO]REPLACE
Group 2: Initialization
/ACCESSED:n
/BADBLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
/EXTENSION:n
/FILE PROTECTION:code
/HEADERS:n
/INDEX:arg
BEGINNING
MIDDLE
END
n

!n is default number of FCBs per
!volume.
!Default

!Default n=5.
!Default is protection of involume.
!Specifies location of INDEXF.SYS
!on volume; default is location of
!file on involume.
!At logical block n.

9-4

QUICK REFERENCE
/INITIALIZE
/MAXIMUM FILES:n
/SAVE_SET:name

!Default is name of volume being
!backed up.
!Default is number of mapping
!pointers on involume.

/WINDOWS:n
Group 3: Tape and Disk Control

/APPEND
/DENSITY:arg
800
1600
6250
/ERROR LIMIT:n
/LABELTTAPE:fileset-ID
/LENGTH:n
/REWIND

!May need /REWIND; see main text.

!Default density is 800 bpi.
!Default n=25.
!Usable length of output tape in
!decimal feet; default n = physical
!length of the output tape.
!Rewind first tape of tape set
!before executing the command line;
!may use with /APPEND.

Group 4: Verification

/COMPARE
/VERIFY
Group 5: Display

/LIST
/[NO]LOG

!/LOG goes to TI:; /NOLOG is default.

Group 6: Disk Processing

/DIRECTORY
/NOINITIALI ZE

!Can only be used with /NOINITIALIZE.

/LABEL:arg

!See also /LABEL:TAPE:volumelabel,
!Gp 3.

INPUT:volumelabel
[OUTPUT:]volumelabel

/MOUNTED
/[NO]PRESERVE

!/LABEL:OUTPUT is default; if the
!only volumelabel in command line
!is outvolume, /LABEL:volumelabel
!will do.
!/PRESERVE is default.

BASIC

Section 6.2.2

BASIC invokes an interpreter or compiler for the BASIC language.

BAS IC [/qualifier]

[@f ilespec]

!@filespec is BP2 only

Command Qualifiers

/Bll
/BP2
/USING:userbasic

! BASIC-11
!BASIC-PLUS-2; the default

9-5

QUICK REFERENCE

Section 3.6

BROADCAST

BROADCAST displays a specified message at one or more terminals.

BROADCAST ttnn: message
'SR9'AJ?C'AS''r' llSiername'' '~~ss,~ge''.,'
BROADCAST @indirectspec
BROADCAST[/qualifier] message

1RSJe...:fi,M.;_,p,LUSi0;n'1;yj' ,t)(f 'pr~pt'.«

Command Qualifiers
! Privileged

/ALL
/LOGGED_IN

! Privileged

Section 7.5

CANCEL

CANCEL does not
CANCEL eliminates entries from the clock queue.
affect a currently executing task, just the pending entries in the
clock queue.

CANCEL taskname

COBOL

COBOL invokes
compiler.

Section 6.2.4.1

the

COBOL-81

compiler.

COBOL-81

the

default

COBOL[/qualifier[s]J filespec
Command Qualifiers
/[NO]ANSI FORMAT
/[NO]CHECK:arg
[NO] BOUNDS
[NO] PERFORM
ALL
NONE
/CODE: [NO]CIS
/[NO]CROSS_REFERENCE
/[NO]DEBUG
/[NO]DIAGNOSTICS[:filespec]
/[NO]LIST[:filespec]
/NAMES:xx

!Source is in conventional format.
!Check ranges of subscripts,
!indexes, and nested perform
!statements at run time.
Use CIS in the object code produced.
Include cross-reference in listing
file.
Include Symbolic Debugger in task
image.
Create a diagnostic file.

Produce a listing file.
Use two characters you specify as
!PSECT kernel.

9-6

QUICK REFERENCE

/[NO]OBJECT[:filespec]
/[NO]OVERLAY_DESCRIPTION

Produce an object module.
Produce indirect command file and
Overlay Descriptor Language file.
/[NO]SHOW: [NO] MAP
Produce listfile and append two
offset maps.
/[NO]SKELETON
Produce a skeleton ODL file.
/[NO]SUBPROGRAM
Treat source file as a subprogram.
Store temporary work files.
/TEMPORARY:device
/[NO]TRUNCATE
!Perform truncation on values of
!comp data items.
/[NO]WARNINGS: [NO] INFORMATIONAL !Issue informational, warning, and
!fatal diagnostics.

Section 6 .. 2 .. 4 .. 2

COBOL/Cl!

COBOL/Cll invokes the PDP-11 COBOL compiler.

COBOL/Cll[/qualifier[s]] filespec

Command Qualifiers
/[NO]ANSI FORMAT
/[NO]CHECK

!Source in conventional format; A starts at 8.
!/NO means no bounds checking; /CHECK is
!default.
!Specifies PDP-11 COBOL compiler.
/Cll
/[NO]CM6
!/CM6 means COMPUTATIONAL-6.
/[NO)CROSS REFERENCE
!Includes cross-reference in listing file.
/LARGE SYMBOL TABLE[:n] !Allocate more symbol space; n=l-4; default n=l.
/[NO]LIST[:filespec]
!/NOLIST is default; see main text for
!filespec defaults.
/NAMES:xx
!Specify 2-character kernel for program section
!names.
/NEST:n
!Depth of nested PERFORMS; default=lO.
/[NO]OBJECT[:filespec] !/OBJECT is default; see main text
!for filespec defaults.
/[NO]OVERLAY
!Make all procedural program sections overlayable.
/[NO]POOL LITERALS
!See main text; PDP-11 COBOL documentation.
/[NO]READONLY
!Generate read-only program sections; default
!is /NOREADONLY or read-write.
/[NO] SHOW: {arg [ ,s])
!Specify additions to listing; a single argument
'needs no parentheses; multiple arguments must be
separated by commas and enclosed in
parentheses.
COPY LIST
/NOSHOW:COPY LIST means no source statements
from library-included in listing.
MAP
/SHOW:MAP means produce special map.
./SHOW:VERB LOCATION means list location for
VERB LOCATION
!each program verb.
!Produces skeleton ODL file; default is /SKL.
/[NO]SKELETON
/[NO]SUBPROGRAM
!Indicates subprogram.
/TEMPORARY:dev
!Assigns work files to a specified device.
/WARNINGS
!Warning and fatal diagnostics printed
!Only fatal diagnostics printed
/NOWARNINGS

9-7

QOICK REFERENCE

Section 7.4

CONTI NOE

CONTINUE resumes execution of a previously suspended task.

CONTINUE [/qualifier]

[taskname]

! Taskname defaults to TTnn

Command Qualifier
/TERMINAL: ttnn:

!Privileged;

CONVERT

RSX-llM-PLUS only.

Section 4.3.6

CONVERT invokes the RMSCNV utility, which moves records from one file
to another.
RMSCNV reads records from an input file and writes them
to an output file.
The action of RMSCNV depends on the organization
(sequential,
relative,
or
indexed)
of the two files and on the
qualifiers you include with the CONVERT command. See the main text
and the RMS-11 documentation supplied with your system for more
information.

CONVERT[/qualifier[s]]
Cn!!'m~na

infile outfile

Qualifiers

/[NO]APPEND
/BLOCK SIZE:n
/[NO]FIXED CONTROL
/[NO]IDENTIFICATION
/INDEXED
/KEY[:n]
/[NO]LOG FILE[:filespec]
/[NO]MASS INSERT
/MERGE
I [ N0] PAD [ : [ # ] a r g]
/RELATIVE
/[NO]REPLACE
/SEQUENTIAL
/[NO]TRUNCATE

!/APPEND conflicts with /REPLACE.
!Magtape block size:l8<=n<=8192; default=512.
!/NO is default.
!Prints RMS version number; /NO is default;
!no filespec required.
!Outfile is indexed; see main text.
!O<=n<=9; default=l.
!/NO is default; no filespec logs on TI:
'Both files must have same organization.
Pad infile records to outfile length; default
pad character is blank (040).
Outfile is relative.
/REPLACE conflicts with /APPEND.
Outfile is sequential.
/NO is default.

Section 4.3.4

COPY

COPY copies files.
Unless specified otherwise, COPY preserves the
file organization of the input file, that is, indexed files are copied
as indexed files, and so forth.
See also the CONVERT command.

COPY infile[s] outfile

!See main text for multiple file copies

9-8

QUICK REFERENCE

Command Qualifiers
/BLOCK_SIZE:n

/[NO]CONTIGUOUS
/OWN
/REPLACE
/[NO]SPAN BLOCKS
/DATE:dd-mmm-yy
/SINCE:dd-rnrnm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-rnrnm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Defines block size for outfile on
!magtape; n is octal unless terminated
!with decimal point; no effect on
!infile.
!Specifies contiguous outfile.
!Makes outfile UIC owner of copy.
See main text
Given day only
From given day through current day
From beginning through given day
From given day through given day
Today only
Filespec can include wildcards.

Section 6.2.5

CORAL

CORAL invokes the CORAL 66 compiler.

CORAL [/qualifier [s]]

filespec [ ,s]

Command Qualifiers
/[NO]CHECK
/CODE:arg
EIS
FIS
FPP
PIC
(EIS,PIC)
(FIS,PIC)
(FPP,PIC)
/[NO]EXTEND_SOURCE
/[NO]LIST[:filespec]
/[NO]MACHINE_CODE
/NAMES:x
/[NO]OBJECT[:filespec]
/[NO]OPTIMIZE[:LEVEL:n]
/READ ONLY [ :arg]
ALL
NONE
PURE DATA
/[NO]SHOW[: (arg[~s])]
ALL
[NO] EXPANSIONS
NONE
[NO] OVERRIDE
[NO] SOURCE
[NOjSTATISTICS
[NO] SYMBOLS

!Checks boundaries of subscripts and
!switches; default is /NOCHECK.
!Specifies choice of instruction set;
!default is /CODE:EIS~

!Processes more than 72 characters or
!not; default is /EXTEND SOURCE.
!Generates listing file or not;
!default is/NOLIST.
!Listing file includes generated machine
!code; default is /NOMACHINE CODE.
!Compiler-generated program-section
!names begin with x; default is S.
'Generate object module or not;
default is /OBJECT.
Optimize CORAL 66 source programs;
default is /OPTIMIZE.
Alter read-write or read-only attributes
of program sections; default is
/READ_ONLY:PURE_DATA.
!Include or exclude elements from
!listing file; default is /SHOW.
!Default is /SHOW:NOEXPANSIONS.
!Default
!Default
!Default
!Default

9-9

is
is
is
is

/SHOW:NOOVERRIDE.
/SHOW:SOURCE.
/SHOW:STATISTICS.
/SHOW:SYMBOLS.

QUICK REFERENCE
!Highlights non-IECCA keywords or not;
•default is /NOSTANDARD.
Retain or omit declarations and
statements; default is /TEST:O.
Prints source-file and line-number
information in run-time messages;
default is /NOTRACEBACK.
Specifies width of listing file; n
8
!through 132; default is /WIDTH:l32.

/[NO]STANDARD
/TEST [: n]
/[NO]TRACEBACK
/WIDTH:n

Section 4.2.1

CREATE

CREATE creates a sequential file in a directory on a file-structured
device.
After you issue the command, you can immediately enter text.
To end data entry and close the file,
type CTRL/Z.
See also
CREATE/DIRECTORY.

CREATE f ilespec

Section 4.2.2

CREATE/DIRECTORY

CREATE/DIRECTORY creates a User File Directory
(UFD)
on a Files-11
volume and enters its name in the volume's Master File Directory
(MFD) ~
Nonprivileged users can only create directories on mounted
volumes on their own private (allocated) devices.

CREATE/DIRECTORY[/qualifier)

[ddnn:]

[g ,m]

Command Qualifiers
/ALLOCATION: n
/

!Entries for n files.

/nonm~0mTn~·~n~o

,l;l.,V..LU""""'.L..LVL"f•V'"''-"''-

/LABEL:volumelabel

!Compare with volume label.

DEALLOCATE

DEALLOCATE counteracts ALLOCATE.
by others.

DEALLOCATE[/qualifier] ddnn:

Section 5.5

It frees a private device for access

!Volume must be dismounted.

Command Qualifier
/ALL
./DEVICE
/TERMINAL: ttnn:

!Frees all devices allocated by TI:;
!do not specify ddnn: •
!No-op
!Privileged; RSX-llM-PLUS orily.

9-10

QUICK REFERENCE

Section 5 .. 3

DEASSIGN

DEASSIGN deletes logical-device assignments.
DEASSIGN disassociates
logical names from physical device names, pseudo device names, or
logical device names created by ASSIGN. See also other forms of the
DEASSIGN command described in the following entries.

DEASSIGN[/qualifier[s]]

logicalddnn:

Command Qualifiers
!Combine with any other qualifier;
!No ddnn:
!Default
! Privileged
! Privileged
!Synonym for /GLOBAL.
!Default is TI:; oth·erwise privileged.

/ALL
/LOCAL
/LOGIN
/GLOBAL
/SYSTEM
/TERMINAL:ttnn:

DEASSIGN/QUEUE
See the RSX-llM/M-PLUS System Management Guide.

DEASSIGN/QUEUE counteracts ASSIGN/QUEUE.
It is used to eliminate the
path from a queue to a processor in the Queue Manager subsystem.
Privileged.

DEASSIGN/QUEUE queuename processorname

•

~- > •l

DEBUG. fotce·s ·a task on RSX':._·llM:-PLUS to . trap .to' g 'debugger .· qy setting
the T-bi t
in the task's Process·or Status Word.·. ··The task must have "
·been built using. the /DEBUG qualifier to · ·the· LINK. cpmmand or have
issued ~n Executive directive specifying a debugge~. .see main te~~.
Nonprivi1eged users can issue thi.s comma·na for any: nonp+ivileged task
runninq from their own terminals.
Privileged users can name a·ny task.,
but th~ command must be issued from the same terminal the task was run
from.

DEBUG [taskname]

!Default taskname is TTnn; RSX-llM-PLUS
!only.

9-11

QUICK REFERENCE

DELETE

Section 4.3.2

DELETE deletes specified versions of files and releases the storage
space tqe files occupy. See also other forms of the DELETE command
described in the following entries.

DELETE[/qualifier[s]]

Command Qualifiers
/[NO]LOG
/[NO]QUERY
/DATE:dd-rnrnm-yy
/SINCE:dd-rnrnm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-rnrnm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Lists deleted files on TI:
!Queries before deleting;
!/NO is default.
!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

DELETE/ENTRY
See the RSX-llM/M-PLUS Batch and Queue Operations Manuale

DELETE/ENTRY deletes QMG jobs by entry number.

DELETE/ENTRY:n[/qualifier]

!n is QMG entry number.

Command Qualifier
/FILE_POSITION:n

DELETE/JOB
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.

DELETE/JOB deletes QMG jobs by queuename and jobname.

DELETE/JOB[/qualifier] queuename [[g,rn]]jobname

Command Qualifier
/FILE_POSITION:n

9-12

QUICK REFERENCE

DELETE/processor type
See the RSX-llM/M-PLUS System Management Guide.

DELETE/PROCESSOR deletes print processors, output despoolers, or batch
processors from the Queue Manager subsystem by processor name or
device name.
This command also sets the device unspooled.

DELETE/processortype processorname
APPLICATIONS PROCESSOR
BATCH PROCESSOR
CARD READER
!INPUT is synonym.
!PRINTER is synonym.
DEVICE
!CARD READER is synonym.
INPUT
!DEVICE is synonym.
PRINTER
PROCESSOR

DELETE/QUEUE
See the RSX-llM/M-PLUS System Management Guide.

DELETE/QUEUE
Privileged.
subsystem by name.
See
from queues.

DELETE/QUEUE queuename/ERASE

deletes queues in the
Queue
Manager
DELETE/JOB and DELETE/ENTRY to delete jobs

!/ERASE is required.

Section 4.4.5

DIFFERENCES

DIFFERENCES compares two ASCII (text) files line by line to determine
if parallel records
(lines) are identical and produces a listing of
the differences between the files, if any.

DIFFERENCES inf ilel infile2

Command Qualifiers
/CHANGE_BAR [ : n]
/IGNORE: (arg[ ,s])
BLANK LINES
COMMENTS
FORM FEEDS
SPACING
TRAILING BLANKS
/LINES: n
/[NO]NUMBERS
/OUTPUT:filespec
/SLP[:audittrail]

!n is octal ASCII code of alternate
!bar. Default n=041 (!).
!Comments begin with ";".
!Group of tabs and blanks = 1 blank.
!n lines must be same for match.
!Line numbers in output file.
!Names output file; TI: is default.
!Output is SLP indirect command file.

9-13

QUICK REFERENCE

Section 4.3.1

DIRECTORY

DIRECTORY displays information on files in directories (UFOs).

DIRECTORY[/format-qual] [/destination-qual]

[other-qual [s]]

[filespec[s]]

Command Qualifiers
Format
!RMS-11 attributes

/ATTRIBUTES
/BRIEF
/FREE [ddnn:]

!Free blocks on volume; default is
! SY:.

/FULL
/SUMMARY

!Blocks used and allocated only.

Destination
/OUTPUT[:filespec]
/PRINTER

!Names output file. TI: is default.
!Output to LPO:

Other Qualifiers

!Not used with /FREE or /ATT

/DATE:dd-mrnm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

Section 5.7

DISMOUNT

DISMOUNT marks the volume mounted on the specified device as logically

off line and disconnected f rcm
DISMOUNT ddnn:

[label]

!If label specified, volume label is
!checked.

Command Qualifiers
/ALL
/PUBLIC
/SAVE

!Dismount all devices mounted by user.
!Privileged; dismounts all users from
!volume.
!Privileged; disk keeps spinning;
!privileged· tasks can access;
1asx-11M~PLUS .only~

/SYSTEM
/TERMINAL:ttnn:
/{NOJUNLOAD

!Synonym for /PUBLIC.
!Privileged; dismounts volumes mounted
!from another terminal.
!Affects DB:, DM:, and ou: devices;
!see main text; RSX-llM-PLUS only.

9-14

QUICK REFERENCE

Section 4.2.3.1

EDIT[/EDT]
See also the EDT Editor Manual.

EDIT or EDIT/EDT invokes EDT, the DEC Standard
default editor.

EDIT [/EDT] [/qualifier [s]]

EDT

Editor.

the

f ilespec

Command Qualifiers
/[NO]COMMAND[:filespec]
/[NO]JOURNAL[:filespec]
/[NO]OUTPUT[:filespec]
/[NO]READ ONLY
/[NO]RECOVER

!Default is /COMMAND:EDTINI.EDT.
!Default is /NOREAD ONLY.
!Default is /NORECOVER.

Section 4.2.3.2

EDIT/SLP
See also the RSX-llM/M-PLUS Utilities Manual.

EDIT/SLP invokes the Source
program-maintenance editor.

Language

Input

Program

(SLP) ,

EDIT/SLP[/qualifier[s]] filespec
Command Qualifiers
/[NO] AUDIT [: (arg [s]}]
POSITION:n
SIZE:n
/CHECKSUM [: n]
/[NO]LIST[:filespec]
/[NO]OUTPUT[:filespec]
/[NO]REPORT
/[NO]TAB
/[NO]TRUNCATE[:n]

!Default is /AUDIT:(POS:80:SIZ:8).
!n must be <=132.
!n must be <14.

!Report truncation of lines by audit
!trail.
!Right-justify with tabs or spaces;
!/NOTAB is default.
!/TRUNCATE deletes audit trails and
!trailing characters; optionally
!truncates text at specified
!horizontal position.

Section 4.2.3.3

EDIT/EDI and EDIT/editor

EDIT/EDI invokes EDI, the Line Text Editor.
user-specified editor (see list below).

EDIT[/qualifier]

[edit-input]

EDIT/editor

!Input accepted by editor
9-15

invokes

QUICK REFERENCE

Command Qualifier
!Line Text Editor.
!Unbundled KEO editor.
!VT52 version of unbundled KEO editor.
!Unsupported TECO function.
!Unsupported TECO function.
!Use with /KEO and /K52 (unbundled
! editors) .
!Use with KEO and K52.
!Unsupported Son of Stopgap.
!Unsupported Text Editor and
!Corrector.
!Unsupported user editor.

/EDI
/KEO
/K52
/MAKE
/MONG
/OUTPUT:filespec
/CREATE
/SOS
/TECO
/USING:yyy

FIX

Section 7.10

FIX causes an installed task or region to be loaded
memory.
Privileged.

FIX[/qualifier]

taskname

and

locked

into

!Name task or region.

Command Qualifiers
/READONLY_SEGMENT

!Read-only segment of
hnUlfluser taskf RSX-"llM;...PLUS only;

/REGION

!common region; RSX-llM-PLUS only.

FORTRAN

Section 6.2.3

FORTRAN invokes a FORTRAN compiler.

FORTRAN[/qualifier[s]J

filespec[s]

Command Qualifiers
/[NO]CHECK
/CODE:arg
EAE
EIS
FIS
THREADED
/CONTINUATIONS:n
/[NO] DLINES
/[NO]EXTEND SOURCE
/FOR
/F4P
/[NO]F77

!F4P and F77; default is /NOCHECK.
!FOR only; mutually exclusive options.
!Extended Arithmetic Element.
!Extended Instruction Set.
!Floating Instruction Set.
!F4P and
ID-lines
!FIV and
!Code is
!Code is
!Code is

F77; n=0-99 continuation lines.
compiled or not.
F77; accept more than 72 columns or not.
FORTRAN-IV; default.
FORTRAN-IV-PLUS.
FORTRAN-77; /NOF77=/F4 P.

/IDENTIFICATION

!Compiler and version.

/[NO]I4
/[NO]LINE NUMBERS
/[NO]LIST[:filespec]

!/NOI4 is default; I4 is 2-word variables.
!FORTRAN Internal Sequence Numbers.
!Default is /NOLIST.

9-16

QUICK REFERENCE

/[NO]MACHINE CODE
/[NO]MAP
/[NO]OBJECT[:filespec]
/SHAREABLE
/SOURCE
/[NOjSTANDARD:arg
ALL
NONE
SOURCE
SYNTAX
/[NO]TRACEBACK:arg
ALL
BLOCKS
LINES
NAMES
NONE
/USING:usercompiler
/[NO]VECTORS
/[NO] WARNINGS
/WORK_FILES:n

!/OBJECT is default.
!F4P and F77.
!ANSI standard extensions; default is
!/NOSTANDARD.

!F4P and F77.
!LINES is synonym.
!ALL is synonym.

!FOR only; default is vectored arrays.
!FOR only; default is warning diagnostics.
!F4P and F77; n is maximum for temporary files.

Section 3.5

HELP

Help displays information about your system.
Help files for MCR, DCL,
and most utilities are supplied with the system.
Your system may also
have help for an alternate CLI or local, group, or other special help.
See main text.

HELP[/qualifier[s]]

[parameterl ••• parameter9]

Command Qualifiers
/OUTPUT: f ilespec
/LOCAL
/GROUP
/CLI :cliname
/MCR
/DCL
/FILE:filespec
/filename

!Help text to file; default /OUTPUT:TI:.
!Help file is in default UFD; HELP % is same.
!Help file is in [g,l]; g is your group.
!For alternate CLis.
!MCR help; default for MCR terminals.
!DCL help; default for DCL terminals.
!Names file containing help text.
!LB: [1,2] filename.HLP

HOLD/ENTRY

See the RSX-llM/M-PLUS Batch and Queue Operations Manual.

HOLD/ENTRY holds a QMG job in its queue by entry number.

HOLD/ENTRY:n

!n is QMG entry number.

9-17

QUICK REFERENCE

HOLD/JOB
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.

'HOLD/JOB holds a QMG job in its queue by queuename and jobname.'

HOLD/JOB queuename [[g,m]]jobname

INITIALIZE

Section 5.8

INITIALIZE produces a volume in
Files-11
format.
See
also
INITIALIZE/UPDATE.
~ou'
must
moun:t.
the
~ol!ume:
/FQRE'l'GN,' on,
RSX~llM~PLQS.~. You can mount. the volume /FpREIGN on RSX-.11.M,· bi.lt •. it is
n'.ot r~g;ui:r;ed. See main text. See also other forms of 'the INITIALIZE
command described in the following entries.

INITIALIZE[/qualifier[s]] ddnn: volumelabel !Nonprivileged must
!allocate the device.

Command Qualifiers
/ACCESSED: n

!Number of UFOs accessed simultaneously.

/BAD BLOCKS:arg
AUTOMATIC
MANUAL
OVERRIDE
/DENSITY:arg
800
1600

!Default

6250

/EXTENSION:n
/FILE_PROTECTION: (code)
/HEADERS:n
/INDEX:arg
BEGINNING
MIDDLE
END
n

/MAXIMUM FILES:n
/OWNER: [g ,m]
/PROTECTION: (code)
/[NO]SHOW
/WINDOWS:n

!Extend full files by n blocks;
!default n~s.
!Default protection for files
!on volume.
!Locates index file on volume.
!Default for tapes and DECtapes.
!Default for disks.
!At logical block n.
!Default protection for volume.
!Display volume information on TI:;
!/NO is default.
!Mapping pointers to file windows;
!default n=7.

9-18

QUICK REFERENCE

INITIALIZE/PROCESSOR (Output)
See the RSX-llM/M-PLUS System Management Guide.

INITIALIZE/PROCESSOR creates, names, and starts an output despooler or
batch processor.
Privileged.
See next entry to initialize an input
spooler.

INITIALIZE/processortype processorname[/qualifier[s]]
Processor types:
APPLICATIONS PROCESSOR
BATCH PROCESSOR
DEVICE
PRINTER
PROCESSOR

Command Qualifiers
/FLAG PAGE:n
/FORMS:n
/[NO]SHAREABLE
/[NO]LOWERCASE
/[NO]UPPERCASE

!n can be 0-2; default n=l.
!n can be 0-255; default n=O.
!Default is NOSHAREABLE.
!Default is LOWERCASE.
!Default is NOUPPERCASE.

INITIALIZE/PROCESSOR (Input)
See the RSX-llM/M-PLUS System Management Guide.

INITIALIZE/processortype creates, names, and starts an input spooler
or
card-reader
processor.
Privileged.
See previous entry to
initialize an output despooler.

INITIALIZE/processortype processorname[/qualifier[s]]
CARD READER
!INPUT is synonym.
INPUT
!CARD READER is synonym.

Command Qualifiers
/BATCH QUEUE:gueuename
/CONSOLE:ddnn:
/PRINTER_QUEUE:queuename

9-19

QUICK REFERENCE
INITIALIZE/QUEUE
See the RSX-llM/M-PLUS System Management Guide.

INITIALIZE/QUEUE creates, names, and
Manager subsystem.

starts

queue

the

Queue

INITIALIZE/QUEUE queuename[/qualifier]

Command Qualifiers
/BATCH
/PRINT.ER
/NOWARNINGS

!Default

INITIALIZE/UPDATE

Section 5.8.1

INITIALIZE/UPDATE invokes the HOME utility to alter values in the
volume home block without affecting the other data on the volume.
INITIALIZE/UPDATE is only for disks and DECtapes in Files-11 format.
You must mount the· volume /FOREIGN.on RSX-llM-PLUS.
volume /FOREIGN on RSX-llM, but it is not required.

INITIALIZE/UPDATE[/qualifier[s]] ddnn:

You can mount the
See main text.

volumelabel

Command Qualifiers
/ACCESSED:n
/DENSITY:arg
800
1600
6250
/

/ T.l'rmT."l ... 'Trt T " • , . . -

J:.J\J.J:.L'IOJ.Vl'lo ll

/FILE PROTECTION:code
/OWNER: [ g ,m]
/MAXIMUM FILES:n
/PROTECTION:code
/[NO]SHOW
/LABEL:newvolumelabel
/WINDOWS:n

tr.t ... J...--...:1
~.DJl.l..CllU

.t: •• 11
.L.U.L.L

.c.:1-.L.J..LCO:.

i.... ....

U:f

i....1.--1... U.LV'-1'>.-=>e

!Default protection for files on volume.
!Maximum number of files on volume.
!Protection for volume.
!Changes volume label.
!Mapping pointers to file windows; default n=7.

INSTALL

Section 7.8

INSTALL includes a task in the System Task Directory, thus
known to the system. Privileged.
INSTALL[/qualifier[s]J

[$Jfilespec

9-20

making

QUICK REFERENCE

Command Qualifiers
/[NO] CHECKPOINT
/COMMAND:"taskcommand"
/EXTENSION: n
/MULTIUSER PARTITION:parname
/PARTITIONTparname
/[NO]POSTMORTEM
/PRIORITY:n
/READONLY COMMON
/[NO]SLAVE
/TASK NAME:taskname
/UIC:(g,m]

!n (octal) additional words of address
!space.
!Install read-only portion.
!0-250.
!Install common as read-only.
!/NOSLAVE is default.
!1-6 characters.

LIBRARY

Section 6.3

See also the RSX-llM/M-PLUS Utilities Manual.

LIBRARY creates and maintains user-written library files.
The command
has eight functions, each listed here as a separate command.
See main
text for more details on all functions and qualifiers.

LIBRARY[/operation] [/qualifier[s]]
LIBRARY @filespec

!Indirect command file specification.

LIBRARY/COMPRESS

Section 6.3.1

LIBRARY/COMPRESS physically deletes modules that have been logically
deleted
through
LIBRARY/DELETE.
You can rename the resulting
compressed library. You can also use this command to copy a library
and rename it.

LIBRARY/COMPRESS[: (arg[,s])]
GLOBAL:n
MODULES:n
BLOCKS:n

libspec [newlibspec]
!Entry-point table entries.
!Module-name table entries.
!Size in 256-word blocks.

LIBRARY/CREATE

Section 6.3.2

LIBRARY/CREATE creates a library and optionally inserts
modules into it.

one

LIBRARY/CREATE [ : (a r g [ , s ] ) ] [/qua l i f i er [ s ] ] libs pe c [ i n f i 1 es pe c [ s ] ]
GLOBAL:n
!Entry-point table entries.
MODULES:n
!Module-name table entries.
BLOCKS:n
!Size in 256-word blocks.
9-21

QUICK REFERENCE
Command Qualifiers
/[NO]GLOBALS
/MACRO
/OBJECT
/SELECTIVE SEARCH
/SQUEEZE /UNIVERSAL

!Include globals in entry-point table.
!Identifies macro library.
!Default; identifies object library.
!Object modules only.
!Identifies universal library.

LIBRARY/DELETE

LIBRARY/DELETE
LIBRARY/REMOVE
library.

Section 6.3.3

deletes object
modules
from
a
library.
See
for removing global symbols
{entry points) from a

LIBRARY/DELETE libspec module[,module[,s]

!Name as many as 15 modules

LIBRARY/EXTRACT

Section 6.3.4

LIBRARY/EXTRACT reads one or more modules from a library and writes
them to a specified output file.
You can extract as many as eight
modules with a single command.
If you extract more than one module,
the modules are concatenated in the output file.

LIBRARY/EXTRACT[/qualifier]

libspec module[,s]

Command Qualifier
/OUTPUT[:filespec]

!Default output file is TI:; name
!a file when extracting object
!modules.

Section 6.3.S

LIBRARY/INSERT

LIBRARY/INSERT inserts modules from one or more files into a library.

LIBRARY/INSERT libspec filespec[s]

!Name any number of files

Command Qualifiers
/[NO]GLOBALS
/SELECTIVE SEARCH
/SQUEEZE -

!Include globals in entry-point table.

9-22

QUICK REFERENCE

LIBRARY/LIST

Section 6 .. 3 .. 6

LIBRARY/LIST lists on your terminal or in an output file the names
all modules in a library.

LIBRARY/LIST[:filespec]

libspec

Command Qualifiers
/BRIEF
/FULL
/[NO]NAMES

!Names plus global entry points.

Section 6.3.7

LIBRARY/REMOVE

LIBRARY/REMOVE removes global symbols (entry points) from a
library.
See LIBRARY/DELETE for deleting object modules from a library.

LIBRARY/REMOVE libspec global[,global[,s]

!Name as many as 15 global symbols

LIBRARY/REPLACE

Section 6.3.8

LIBRARY/REPLACE replaces a module in a library with a
the same name and deletes the old module.

new

module

LIBRARY/REPLACE libspec filespec[s]
Command Qualifiers
/[NO]GLOBALS
/SELECTIVE SEARCH
/SQUEEZE -

!Include globals in entry-point table.

LINK

Section 6.4

LINK invokes the Task Builder, which links object modules and routines
from user and system libraries to form an executable task.

LINK[/qualifier[s]]

filespec[/qualifier[s]] [,filespec[s]]

9-23

QUICK REFERENCE
Command Qualifiers
/ANCILLARY PROCESSOR[:n]
/BASIC
/[NO]CHECKPOINT:arg
SYSTEM
TASK
/CODE: (arg[,s])

DAT'A :5p~~

EAE FPP
PIC
POSITION INDEPENDENT
/COMPATIBLE
/[NO]CROSS REFERENCE
/[NO]DEBUG[:filespec]
/[NO]EXECUTABLE:filespec
/ERROR LIMIT:n
,,''iifN.~J ~TEft;U/\J}<
/FAST
/FULL SEARCH
/[NO]ttEADER
/[NO]IO PAGE
/LONG /MAP [: f i lespec]
/[NO]MEMORY_MANAGEMENT[:n]
/OPTIONS[:filespec]
/OVERLAY DESCRIPTION
/POSTMORTEM
/[NO]PRIVILEGED[:n]
/[NO]RECEIVE
/[NO]RESIDBNT OVERLAYS
/SAVE
/SELECTIVE SEARCH
/[NO]SEGREGATE
/SEQUENTIAL
/SHAREABLE [: arg]
COMMON
LIBRARY
'l'ASJ(

/SLAVE
/SLOW
/SYMBOL TABLE[:filespec]
/[NO]SYSTEM LIBRARY DISPLAY
/[NO]TASK[:filespec]
/TKB
/TRACE
I [NO] WARNINGS
/WIDE

!Task is ACP; n is 0,4, or 5.
!Checkpoints to [O,O]CORIMG.SYS.
!Checkpoints to task image file.
! RSX-'1ilM.:.PI.uS" ,\tinl;~:.•
!Extended arithmetic element.
!Floating-point processor.
!Position-independent code.
!Synonym for PIC.

!Default is ODT.
!Names task file. Synonym for /TASK.
, !Stp,P !:,as~ b1;J,iJ~'I . atter n errors.
.. ! R$X':"1:i,.M.;.,1;\LQ'.S, ;;9nly< ••:
! Fast TKB.

!Long map
!Default is /MAP:TI:
!n for unmapped systems; see main
!text; default is /MEM; n is 28 (default) or 30.
!File contains options. Otherwise you will be prompted
!Default is /NOPRIVILEGED.
!Saves indirect file.
!/NOSEG is default.
!Multiuser
!Default; RSX41M-PLUS only

!Slow TKB.
!Output .STB file
!Default is /NOSYS.
!Names task image file; /EXECUTABLE
!is synonym; names 1-6 characters;
!/NOTASK means no task built.
!Default
!/NO suppresses diagnostic messages; /WARNINGS is
!default.
!Wide map

File Qualifiers
/[NO]CONCATENATE
/DEFAULT LIBRARY
/[NO]GLOBALS
/LIBRARY
/INCLUDE: (modulel[: ••• :modulen])
/OVERLAY DESCRIPTION
/SELECTIVE_SEARCH

!File to replace [l,l[SYSLIB.OLB
!Default is /GLOBALS; includes
!global symbols in map.
!File is object module library.
!File is object module library;
!include named modules in task image.
!File is .ODL; also a command qualifier.
!Also a command qualifier.

9-24

QUICK REFERENCE

Section 6.4.3

LINK/C81 or LINK/COBOL

LINK/C81 invokes the Task Builder and the COBOL BLDODL facility,
indicates that COBOL-81 object modules are being linked.

and

LINK/C81[/qualifier[s]] filespec[,s]
LINK/COBOL[/qualifier[s]] filespec[,s]
Command Qualifiers

/[NO]FMS
/OTS: [NO] RESIDENT
/[NO]RMS
/RMS: [NO] RESIDENT
/[NO]MAP
/[NO]DEBUG

!/FMS:NORESIDENT equivalent to /FMS.

Section 3 .1.1

protection

system

and

!HELLO is synonym.

LOGOUT

Section 3.1.2

LOGOUT counteracts LOGIN.
LOGOUT also aborts any nonprivileged tasks
running
from the terminal and also dismounts any volumes and
deallocates any private devices allocated from the terminal.
LOGOUT[/qualifier]

!LO is sufficient

Command Qualifier

/[NO]HOLD

!Holds remote line after logout;
!is default.

MCR

/NO

Section 1.2.4

MCR enters an MCR command from a DCL terminal without leaving DCL.
MCR mcrcommand

9-25

QUICK REFERENCE

Section 6.2.1

MACRO

MACRO invokes the MACR0-11 Relocatable Assembler, which assembles one
or more MACR0-11 source files into a single relocatable object module
suitable for processing by the Task Builder.

MACRO[/qualifier [s]]

filespec[/qualifier [s]] [ ,filespec[ ,s]]

Command Qualifiers
/[NO]CROSS REFERENCE
/DISABLE: (arg[ ,s])
ABSOLUTE
BINARY
CARD FORMAT
GLOBAL
LOCAL
LOWERCASE
REGISTER DEFINITIONS
TRUNCATION
/ENABLE: (arg [ ,s])
ABSOLUTE

!Default is /NOCROSS.
!Parentheses not required
!if single parameter; see
!main text for meaning of
!parameters.

!Parentheses not required
!if single parameter; see
!main text for meaning of
!parameters.

BINARY

CARD FORMAT
GLOBAL
LOCAL
LOWERCASE
REGISTER DEFINITIONS
TRUNCATION
/[NO]LIST[:filespec]
/[NO]OBJECT[:filespec]
I [ NO] SH OW [ : ( a r g [ , s ] ) ]
ALL
BINARY
CALLS
COMMENTS
CONDITIONALS
CONTENTS

!Default is /NOLIST.
!Default is /OBJECT.
!Parentheses not required
!if single parameter; see
!main text for meaning of
!parameters.
ALL is default.

COUNTF.R

DEFINITIONS
EXPANSIONS
EXTENSIONS
LISTING DIRECTIVES
OBJECT BINARY
SEQUENCE NUMBERS
SOURCE SYMBOLS
I [NO] WIDE
File Qualifiers
!File is macro library.
!Assemble file on pass 1 or 2.

/LIBRARY
/PASS:n

9-26

QUICK REFERENCE

MOUNT

Section 5.6

MOUNT declares a volume to be logically known to the system, on line,
and available for use.
Some qualifiers can be used with any MOUNT
command;
some
are
limited
to
mounting
disks
(and
other
random-addressable
devices)
and others are limited to mounting
magnetic tapes.

Format for Disks and Other Random-Addressable Devices
MOUNT[/qualifier[s]] ddnn:

volumelabel

Format for Magnetic Tapes
MOUNT [/qualifier [ s]] ddnn: [ ,ddnn: ••• ] f ileset-ID

Command Qualifiers for Both Disks and Tapes

/DE'F AU'J:;T': ig

' : !Sets defaults, ;f:or a i::;~o'unt;; see. mai-n . te'xt :~

SAVE

,· NOHN'LOAD
. UNLOAD~.• ,:

/FILE PROTECTION: (code)
/FOREIGN
/OVERRIDE: IDENTIFICATION
/PARAMETERS:"user parameters"
/PROCESSOR:arg
acpname
UNIQUE[:acpname]
/PROTECTION: (code)
/PUBLIC
/[NO]SHAREABLE
/[NO]SHOW
/SYSTEM
/[NO]WAIT
/[NO]WRITE

!Protection for files created during mount
!Privileged; no label needed.
!Quotes are required syntax.
!Privileged; name ACP for volume.
!Volume protection during mount
!Privileged; deallocates; sets public.
!Display volume information on TI:.
!Synonym for /PUBLIC.
!Default is /NOWAIT.

Command Qualifiers for Files-11 Devices
/ACCESSED:n
/EXTENSION: n
/OWNER: [ g ,m]
/UNLOCK
/WINDOW:n

!n is number of File Control Blocks.
!Extend full files by n blocks.
!Coordinate with file and volume protection
!Main use is with VFY.

Command Qualifiers for ANSI and Unlabeled Tapes
See main text for these qualifiers.
/BLOCK SIZE:n
/CARRIAGE CONTROL:arg
FORTRAN
LIST
NONE
/DENSITY:arg
800
1600
6250

9-27

QUICK REFERENCE
/[NO]HDR3
/[NO]LABEL
/OVERRIDE: (arg [ ,s])
ACCESSIBILITY
EXPIRATION DATE
SET IDENTIFICATION
/RECORD SIZE:n
/TRANSLATE:arg
EBCDIC
NONE
UTl
UT2
UT3
/VOLUME_IDENTIFICATION: (volume-ID[,volume-ID[,s]])

Section 4.4.2

PRINT queues files for printing on a line
queue jobs for other output devices.

printer.

can

also

PRINT[/qualifier[s]] filespec[/qualifier[s]] [,filespec[,s]]

Command Qualifiers
/AFTER:(dd-mmm-yy hh:mm)
/COPIES:n
/[NO]DELETE
/DEVICE:ddnn:
/[NO]FLAG PAGE
/FORMS:n
/[NO]HOLD
/JOB COUNT
/[NOJJOB PAGE
/LENGTH:n
/[NO]LOWERCASE
/NAME: jobname

!Override on filespec.
!Override on filespec.
!Flag page on each file; default is
!/NOFLAG PAGE.
!n can be 0-256; default n=O.
!Default is /NOHOLD; same effect as
!HOLD command.
!Flagpage on job; default /JOB_PAGE.
!Page length
!1-9 characters

.... .; ):f.;,,. ,,,.,,,...· '.¢,.; 1:0.,.:,...,,.,..

iiiTAl mo:A>.TC;l<''11D

,,(\~~:.,,."""'

/PAGE COUNT:n
/PRIORITY:n

!Limit pages in job.
!n is 1-150 nonprivileged; through 250
!privileged; default n=50.

:r ·:t:•••·v- J ~...·.;_.&:~,··~·~'*" ~·····~·

·~·~~~~-·-v~

/QUEUE:queuename
/[NO]RESTART
/[NO]UPPERCASE

File Qualifiers
/COPIES:n
/[NO]DELETE

./t;NPJ!t~A,~SFEJ~,

9-28

~~-~~~--·

QUICK REFERENCE

Section 4.3.3

PURGE

PURGE deletes all but the latest versions of files
storage space the deleted files occupy.
PURGE[/qualifier[s]]

releases

and

the

filespec[s]

Command Qualifiers
/KEEP:n
/[NO]LOG
/DATE:dd-mmm-yy
/SINCE :dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Lists files on TI: as deleted.
!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

RELEASE/ENTRY
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
RELEASE/ENTRY releases by entry number a print or batch job
been held in its queue.

RELEASE/ENTRY:n

that

has

batch

job

!n is QMG entry number.

RELEASE/JOB
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
RELEASE/JOB releases by queuename and jobname a
that has been held in its queue.

RELEASE/JOB queuename [[g,m]]jobname

REMOVE

Section 7.9

REMOVE counteracts INSTALL.
REMOVE takes
System Task Directory.
Privileged.
REMOVE[/qualifier]

task

name

out

taskname

Command Qualifier
/REGION

Takes name of region out
of Common Block Directory and
partition list; RSX-HM-PLUS only.
9-29

the

QUICK REFERENCE

Section 4.3.5

RENAME

RENAME changes the name, type, or version number of an existing file.

RENAME[/gualifier[s]]

oldfilespec newfilespec

!Watch wildcards and version numbers.

Command Qualifiers

/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

Section 3.7

REQUEST

REQUEST sends a message to the operator's console (CO:).
!Optional "quotes" around message

REQUEST message

RUN uninstalled task

Section 7.2.1

When used to run an uninstalled task (from a task image file), RUN is
a combination command, encompassing
INSTALL, RUN, and REMOVE.
See
main text.

RUN[/qualifier[s]]

[$]filespec

Command Qualifiers
/ [NO] CHECKPOINT
/COMMAND:"taskcommand"
/EXTENSION:n
/PARTITION:parname
/[NO]POSTMORTEM
/PRIORITY:n
/STATUS:arg
TASK
COMMAND
/TASK NAME:taskname
·/TIME:L H-i IT :·n ['u J

!See main text.
!n (octal} additional words of address
!space.
! Privileged
!Privileged

!l-6 characters

! Arg' 1's .M (minut'es)
.!b~default;

can also b~ S (seconds);

!RSX-llM-PLUS only. 3M is default.
/UIC: [g ,m]

! Privileged •

9-30

QUICK REFERENCE

Section 7.2.2

RUN installed task

taskname

Command Qualifiers

!All privileged except /STATUS

/DELAY:nu

!n is the number of units and u is the
!time unit: T,ticks; S,seconds;
!M,minutes; H,hours.

/INTERVAL: nu
/SCHEDULE:hh:mm:ss
/STATUS:arg
COMMAND
TASK

!Return status from RUN command; default.
!Return status from task being run;
!see main text on both these
!arguments.
!Synchronize on next T, s, M, or H.

/SYNCHRONIZE:u
/UIC:[g,m]

SET [DAY]TIME

Section 8.1.1

SET [DAY]TIME sets the system date and time.
SET [DAY] TIME: [dd-mmm-yy]

[hh :mm]

Privileged.

! Set at least one;

either order.

Section 4.5.l

SET DEFAULT

SET DEfAULT establishes your default device or UFD, or both.

SET DEFAULT[:ddnn:]

[[g,m]]

!Unadorned SET DEF returns
!nonprivileged user to login device
! and UFD.

SET DEVICE

Section 5.10.2

SET DEVICE establishes certain device attributes.
SET DEVICE:ddnn:/qualifier[s]

9-31

Privileged.

QUICK REFERENCE
Command Qualifiers

/[NO]LOWERCASE
/[NO]PUBLIC
/WIDTH:n

!n is number {decimal) of blocks in
! [0,0]CORIMG.SYS.
!Default is /NOLOWERCASE.
!Default is /NOPUBLIC.
!Nonprivileged for TI:.

SET GROUPFLAGS

Section 6.6.1

/[NO]CHECKPOINT_FILE[:n]

SET GROUPFLAGS creates and deletes group global event flags.
text.

See main

!Nonprivileged command for own group
!n is group number.

SET GROUPFLAGS:n[/qualifier]
Command Qualifiers

/CREATE
/DELETE

!Default

$ET LIBR,ARY/DI_R,ECTORY

SET LIBRARY/DIRECTORY establishes the RSX-llM-PLUS directory wh:er,';e' th.1=
system utilities and other r1()nprivile9ed sy~t~m tasks ~~,~;:Js~l?:!=i·

Privileged.
SET LIBRARY/DIRECTORY:tg,m]

!.Does not create a di:i:ectory.:·.L

SET [NO]PARTITION

Section 7.12.1

SET [NO]PARTITION creates or eliminates a partition.

Privileged.

SET [NO]PARTITION:parname/qualifier[s]

!Parname 1-6 characters

Command Qualifiers

/BASE:n

/COMMON

/DEVICE

/DJ:AGNOSTIC
/SIZE:n
/;[ NOJ SUBPART tt I ON: s 1Jbpa r riame.
/SYSTEM
/TASK

. !RSX..,.llM only
!Device common.
!RSX-HM-PLUS only.

l RSX-HM only.
!'RSX-llM

/TOP:value

9-32

only~

QUICK REFERENCE

SET PRIORITY

Section 7.12.8

SET PRIORITY alters the priority of an active task.

SET PRIORITY:n taskname

Privileged.

0 through 250

SET PROTECTION

Section 4.5.3

SET PROTECTION establishes the protection status of files.
SET PROTECTION:code[/qualifier[s]]
SET PROTECTION[/qualifier[s]]

filespec[s]

filespec[s] (code)

!default is

!The preferred syntax;
(SY:RWED,OW:RWED,GR:RWED,W:R).

Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

SET QUEUE/ENTRY
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
SET QUEUE/ENTRY modifies by entry number some attributes of print or
batch
jobs once they are in a queue.
See SET QUEUE/JOB to modify by
job name.
SET QUEUE/ENTRY:n[/qualifier]

!Only one attribute at a time

Command Qualifiers
/AFTER:(dd-mmm-yy hh:mm)
/COPIES:n
/[NO]DELETE
/FILE POSITION:n
/FORMS:n
/HOLD
/LENGTH:n
/[NO]LOWERCASE
/PAGE COUNT:n
/PRIORITY:n
/RELEASE
/[NO]RESTART
/[NO]UPPERCASE

!Same as HOLD/QUEUE

!n is 1-150 nonprivileged; through 250
!privileged; default n=50.
!Same as RELEASE/QUEUE

9-33

QUICK REFERENCE

SET QUEUE/JOB
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
SET QUEUE/JOB modifies by job name some attributes of print or batch
jobs once they are in a queue. See SET QUEUE/ENTRY to modify by entry
number.
SET QUEUE/JOB[/qualifier] queuename [[g,m]]jobname
!Only one attribute at a time
Command Qualifiers
/AFTER: (ddd-mmm-yy hh:mm)
/C.OPIES: n
/[NO]DELETE
/FILE POSITION:n
/FORMS:n
/HOLD
/LENGTH:n
/[NO]LOWERCASE
/PAGE COUNT:n
/PRIORITY: n
/RELEASE
/[NO]RESTART
/[NO]UPPERCASE

!Same as HOLD/QUEUE

!n is 1-150 nonprivileged; through 250
!privileged; default n=50.
!Same as RELEASE/QUEUE

SET SYSTEM

Section 8.1.3

SET SYSTEM establishes certain characteristics of the system.
privileged command.
SET SYSTEM/qualifier

It is a

!Qualifier required

Command Qualifiers
/DIRECTORY: [g ,m]
/EXTENSION_LIMIT:n
/[NO] LOGINS
/PACKETS:n
/POOL:top:max:total

!Sets UFO where system tasks are kept;
!does not create a directory.
!Sets maximum size a task can extend
!itself with the Extend Task
!directive.
!n = 0 through 15
!Increases size of pool; see main
!text.

9-34

QUICK REFERENCE

Section 3.8.1

SET TERMINAL

SET TERMINAL sets various attributes of your
users can set attributes for any terminal.

terminal.

Privileged

SET TERMINAL[:ttnn:]/qualifier[s]

Command Qualifiers
Group 1: Common Use
/DCL
/[NO]HOLD SCREEN
/[NO]LOWERCASE
/MCR
/[NO]PRIVILEGED
/SPEED: (transmit,receive)
/[NO]UPPERCASE
/WIDTH: n
/[NO]BROADCAST
/CLI :cliname

!Not for VTlOOs
!/NOLOWER same as /UPPER and is
!default.
! Privileged
!Remember to set hardware after this
!command.
!/NOUPPERCASE same as /LOWERCASE

Group 2: Terminal Setup
/[NO]AUTOBAUD
/ASR33
/ASR35
/CRFILL:n
/[NO]FORM FEED
/[NO]HARDCOPY
/KSR33
/KSR35
/LA12
/LA30P
/LA30S
/LA34
/LA36
/LA38
/LAlOO
/LA120
/LA180S
/LFFILL
/[NO]SCOPE
/[NO]TAB
/MODEL:arg
/PAGE LENGTH:n
/VT05/V'r50
/VT52
/VT55
/VT61
/VTlOO
/VTlOl
/VT102
/VT105
/VT125
/VT131
/VT132
/WIDTH: n

!n can be 0-7

9-35

QUICK REFERENCE
Group 3: Task Setup
/[NO]ECHO
/[NO]EIGHT BIT
/[NO]ESCAPE
/[NO]FULL DUPLEX
/[NO] INTERACTIVE
/[NO]LOCAL
/[NO]PASSALL
I [NO] .R~MOTE
,::/l~O:]~,l!lRiAL'.. ,' i•.

·'!/~·o·s'.~Ji;ni'.t' Js:<~e:f!l,~·1·~· •.
:l'~~x;.+;,l;'~M-:~'ltlf'~ .~·OJ1'~Y ··" \···· .:

/[NO]SLAVE
/[NO] TYPEAHEAD fi!iJ" '

·... 1.:~uinef,(e.a1} .C7r.9.lilll~n £, ·.i,:~,)~s~.,: i·r~~etti~

1.p;n·+·y«f d:'can'J>,e 0~2!5-S··«:' · ...:. ;"(/ .··.,, ·.:' ····

/[NO]WRAP

fl~.!! i

sttow ·AcCooN!r'.1 NG/qua'.iti 'ft~~~: ~.
~

; ~

t ·+ ~.;:

j :~

~ ·~

'~ ~

~ ~~ ';}

·-;· ;f ·~ t 7

~ ~~f~

+<~·

''\ :4

-~':-· ;~

eomm~bki· ~l;if]:~iAJrI •'. · :3\;
~ '.: ; J ~ :: ? 1 ~: '. J. ··~· ;~ ~~ L·' f
J "~"x::<

:~~.::\}::it

/I~FR~;frb,~ "!t;il ~ ;:;_~ . ~;·'.~;~: t l :~. ;_,. • ·:(\~.·i:
/'.Jm1~~~:rl~rt·~r:iz~l.~~·::!':~t~:J·Jl~,;:•·:·,,~

SHOW ASSIGNMENTS

Section 5.10.1

SHOW ASSIGNMENTS displays at your terminal your local and login
logical-device assignments.
Privileged users can display assignments
from other terminals and global assignments.
SHOW ASSIGNMENTS[/qualifier[s]]
Command Qualifiers
/GLOBAL
/LOCAL
/LOGIN
/SYSTEM
/TERMINAL: ttnn:

! Privileged
!Default
!Same as /LOCAL
!Synonym for /GLOBAL; privileged.
!Privileged.

9-36

QUICK REFERENCE

Section 7.12.9

SHOW CLOCK_QUEUE

SHOW CLOCK QUEUE displays information about tasks currently in the
clock queue.
This information consists of the task names, the next
time each task is to run, and each task's reschedule interval, if any.
SHOW CLOCK_QUEUE

"r:O,t~J?igy~· .'t~·~'i<s. '.~~t:a:i~:h'~a;. :Io
J.com:m6n~

', · · · · ·· · ·

· · ·

SHOW [DAY]TIME

Section 8 .1. 2

SHOW [DAY]TIME displays the system time and date setting.
SHOW [DAY]TIME

SHOW DEFAULT

Section 4.5.2

SHOW DEFAULT displays the current default device
terminal, along with your terminal number.

and

UFD

for

your

SHOW DEFAULT

SHOW DEVICES

Section 5.10.3

SHOW DEVICES displays information about the devices
system.
SHOW DEVICES[/qualifier]

included

!Two-character mnemonic only

9-37

the

QUICK REFERENCE
Command Qualifiers
/dd[nn:]
/[NO]PUBLIC
/WIDTH:ddnn:
/[NO]SYSTEM

!Synonym for /PUBLIC

SHOW GROUPFLAGS

Section 6.6.2

SHOW GROUPFLAGS displays the group global event flags currently in the
system.
SHOW GROUPFLAGS

SHOW MEMORY

Section 8.1.9

SHOW MEMORY invokes the Resource Monitoring Display (RMD),
display of the system's activities in memory.

dynamic

SHOW MEMORY

SHOW PARTITIONS

Section 7.12.2

SHOW PARTITIONS displays address and content information about the
partitions in the system.
You can display information about all
partitions or about a single partition.
SHOW PARTITIONS[:name]

9-38

QUICK REFERENCE

SHOW PROCESSOR
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
SHOW PROCESSOR displays information about the processors, batch
processors, printers, card readers, and other devices under control of
the Queue Manager. Batch processing is available on RSX-llM-PLUS
only.
SHOW processortype processorname
Processortypes:
CARD READER
DEVICE
INPUT
BATCH
PRINTER

!INPUT is synonym.
!All nonbatch output processors;
!synonym for PRINTER.
!CARD READER is synonym.
!All batch processors; RSX-llM-PLUS
!only.
!All nonbatch output processors;
!synonym for DEVICE.

PROCESSOR

SHOW QUEUE
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
SHOW QUEUE displays information about batch and print jobs in
Batch processing is available on RSX-llM-PLUS only.
SHOW QUEUE[/qualifier]

queues.

[queuename]

Command Qualifiers
/ALL
/BATCH
/BRIEF
/DEVICE
/ENTRY:n
/FILES
/FORMS:n
/FULL
/NAME:jobname
/OWNER_UIC: [ [g ,m]]
/PRINTER

!All entries in all queues
!All entries in all batch queues; RSX-llM-PLUS
!only.
!All nonbatch queues; synonym for /PRINTER.
!Lists files in each job; not as long
!as /FULL.
!Lists only jobs with that name; may
!Lists only jobs from that UIC;
!default UIC is login UIC.
!All nonbatch queues; synonym for
!/DEVICE.

9-39

QUICK REFERENCE

Section 8.1.6

SHOW SYSTEM

SHOW SYSTEM displays information about the current system.
SHOW SYSTEM[/qualifier]
Command Qualifiers
/CL!
/DIRECTORY
/EXTENSION LIMIT
/PACKETS -

!CLis on current system
!Default; displays current system UFO.
!Task extension limit
!Maximum I/O packets and number
?currently available.
!Displays pool statistics •

SHOW TASKS

~J.~%,:;~~i:J.:~ti&F¥!J~:d~'.l·Y·)·:~.·~

Section 7.12.3.1
7.12.3.2

SHOW TASKS displays information about active or installed tasks.
SHOW TASKS[:taskname]/qualifier[s]
Command Qualifiers
/ACTIVE [: ttnn:]
/INSTALLED
/LOGICAL_UNITS

!Static LUNs for installed task
!qualifier.

/BRIEF
/FULL
/ALL

SHOW TASKS/DYNAMIC

Section 7.12.3.3.1
7.12.3.3.2

SHOW TASKS/DYNAMIC invokes RMD to display on a video terminal
continuing changes in either a single task header or of all or part of
the Active Task List. On a hard-copy terminal, SHOW TASKS/DYNAMIC
provides a snapshot display. See main text for more information.

Format to display individual task information
SHOW TASK:taskname/DYNAMIC[/qualifier]
Command Qualifier
/RATE:n

!Rate in seconds for display change; default n=l.

9-40

QUICK REFERENCE
Format to display Active Task List
SHOW TASKS/ACTIVE/DYNAMIC[/qualifier[s]]

Command Qualifiers
/OWNER:ddnn:
ALL
/PRIORITY:n
/RATE:n

!Default is ALL.
!Highest priority to display; default n=250.
!Rate in seconds for display change; default n=l.

SHOW TERMINAL

Section 3.8.2

SHOW TERMINAL displays information
terminals on your system.
SHOW TERMINAL[:ttnn:] [/qualifier]

about

your

terminal

and

!Without qualifier, displays all
!attributes of the terminal;
!default ttnn:=TI:.

Command Qualifiers
/[NO]AUTOBAUD
/[NO]ASR33
/[NO]ASR35
/[NO]BROADCAST
/CLI :cliname
/[NO]CRFILL
/DCL
/[NO]ECHO
/[NO]EIGHT BIT
/[NO]ESCAPE
/[NO]FORM FEED
/[NO]FULL-DUPLEX
/[NO]HARDCOPY
/[NO]HOLD SCREEN
/HT
/[NO]INTERACTIVE
/[NO]KSR33
/[NO]KSR35
/[NO]LA12
/[NO]LA24
/[NO]LA30P
/[NO]LA30S
/[NO]LA34
/[NO]LA36
/[NO]LA38
I

.1r •.:1n1r

!DECnet host terminal

1\,1\n.

Ll'IVJ 1..IMJ.VV

/[NO]LA120
/[NO]LA180S
/[NO]LFFILL
/[NO]LOCAL
/LOGGED ON
/[NO]LOWERCASE

other

!NOLOWER same as /UPPER and is
!default.

/MCR
/MODEL
/PAGE LENGTH
/[NO]PASSALL

9-41

QUICK REFERENCE
/[NO]PRIVILEGE
/[NO]REMOTE
/[NO]SCOPE
/[NO]SERIAL
/[NO]SLAVE
/SPEED
/[NO]TAB
/TI:
/TT
/[NO]TYPE AHEAD
/[NO]UPPERCASE

!All real terminals
!/NO UPPERCASE same as /LOWERCASE.

:;/if~.:;:J· .f;t•i. :~·i#:.;iiS:tt~·;tfl:t.~f~~zX.,t l:~;·,;:~::':i~:f ,T.f'#;f~tV'Jt.~t\~~;;~~Ji!l·ih~~:iJ;;fJt'~~lJl}~rj·~.ti~'.r90.ti,~~
/[NO]VT05
/[NO]VT50
/[NO]VT52
/[NO]VT55
/[NO]VT61
/[NO]VTlOO
/[NO]VTlOl
/[NO]VT102
/[NO]VT105
/[NO]VT125
I [NO] VT13 l
I [NO] VT132
/WIDTH
/[NO]WRAP

Section 8.1.8

SHOW USERS

displays

all

currently

legged-in

t~rminuls,

inclyding

DECnet host terminals and virtual terminals, with the default UFD and
login UIC for each.
SHOW USERS

Section 4.4.4

SORT

SORT invokes the SORT-11 utility, if present.

See main text.

SORT[/KEY: (abm.n) [abm.n ••• ]] [/qualifier(s]]

outfile FORMAT: (arg) [/qual]

infile[/qual]

Command Qualifiers
/ALLOCATION: n
/BUCKET SIZE:n
/[NO]CONTIGUOUS
/DEVICE:ddnn:
/PROCESS:type
ADDRESS ROUT ING

INDEX
RECORD
TAG
/SIZE:n
/SPECIFICATION:filespec
/WORK_FILES:n

9-42

QUICK REFERENCE
File Qualifiers
/BLOCK_SIZE:n
/FORMAT: (format, [n])
F!XED:n
STREAM:n
UNKNOWN:n
VARIABLE:n
/INDEXED: n
/RELATIVE
/SEQUENTIAL

!Infile or outfile
!Required on infile; may appear on
!outfile; n is size in bytes.

! Inf ile
!Outfile
! Outf ile

START

Section 7.7

START resumes execution of a task stopped by a STOP$S directive.
START [/qualifier}

[taslrname]

!Taskname defaults to TTnn.

Command Qualifier
/TERMINAL: ttnn:

! Pr iv il eg ed

START/PROCESSOR
See the RSX-llM/M-PLUS System Management Guide.
START/PROCESSOR starts a processor, batch processor, output processor,
or card-reader processor. Privileged.
START/processortype processorname[/qualifier[s]]
Processortypes:
APPLICATIONS PROCESSOR
BATCH PROCESSOR.
CARD READER
DEVICE
INPUT
PRINTER
PROCESSOR

!INPUT is synonym.
!PRINTER is synonym.
!CARD READER is synonym.
!DEVICE is synonym.

Command Qualifiers
/FORMS:n

!Overrides value set on
! initialization.

/CONTINUE
/RESTART
/NEXT
/TOP OF FILE
/BACKSPACE:n
/FORWARDSPACE:n
/PAGE:n

. ! Default

/ALIGN

9-43

QUICK REFERENCE

START/QUEUE
See the RSX-llM/M-PLUS System Management Guide.
START/QUEUE starts a queue.

Privileged.

START/QUEUE queuename

START/QUEUE/MANAGER
See the RSX-llM/M-PLUS System Management Guide.
START/QUEUE/MANAGER starts the Queue Manager.

Privileged.

START/QUEUE/MANAGER

Section 7.7.1

START/UNBLOCK

START/UNBLOCK continues the execution of a
task blocked by the
STOP/BLOCK command.
Nonprivileged users can unblock any task running
from their own terminal.
Privileged users can unblock any task.
See
main text.
START/UNBLOCK[/qualifier]

[taskname]

STOP/ABORT
See the RSX-llM/M-PLUS Batch and Queue Operations Manual.
STOP/ABORT stops the current job
Privileged users can stop any job.
own jobs.

on a
line printer immediately.
Nonprivileged users can stop their

STOP/ABORT printer[:]

9-44

QUICK REFERENCE

Section 7.6

STOP/BLOCK

[ tasknarne]

~~,~~~/"

:~;:~~~'~;~~,i::~~;~lf1*~;:/'
STOP/PROCESSOR
See the RSX-llM/M-PLUS System Management Guide.
STOP/PROCESSOR stops a processor, batch
processor,
card-reader
processor, printer, or other output processor. Privileged.
STOP/processortype processorname[/qualifier[s]]
Processortypes:
APPLICATIONS PROCESSOR
BATCH PROCESSOR.
CARD READER !INPUT is synonym.
DEVICE !PRINTER is synonym.
INPUT !CARD READER is synonym5
PRINTER !DEVICE is synonym.
PROCESSOR
Command Qualifiers
/ABORT
/FILE END
/JOB END
/PAUSE

!See main text

STOP/QUEUE
See the RSX-llM/M-PLUS System Management Guide.
STOP/QUEUE stops queues.

Privileged.

STOP/QUEUE queuename

9-45

QUICK REFERENCE
STOP/QUEUE/MANAGER
See the RSX-llM/M-PLUS System Management Guide.
STOP/QUEUE/MANAGER stops the Queue Manager.
STOP/QUEUE/MANAGER

Privileged.

!Marks QMG for stop after current job.

Command Qualifier
/ABORT

!Stops QMG immediately.

/[NO]HOLD

TYPE

Section 4.4.1

TYPE prints selected files on your terminal.
TYPE [/qualifier[s]]filespec[s]
/DATE:dd-mmrn-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-rnmm-yy
/SINCE:dd-mmm-yy
/TODAY
/EXCLUDE:filespec

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

9-46

QUICK REFERENCE

UNFIX

Section 7.11

UNFIX frees a fixed task or region from memory.
UNFIX[/qualifier]

taskname

Privileged.

!Can be region name.

,~~~~;

;~(:/ii/! +c ; ,• /

...

Section 4.4.6

UNLOCK

UNLOCK unlocks locked files.
Locked files are files that have been
improperly closed.
They are identified by an L in the directory
listing.
UNLOCK [/qualifier[s]] filespec[s]

Command Qualifiers
/DATE:dd-mmm-yy
/SINCE:dd-mmm-yy
/THROUGH:dd-mmm-yy
/SINCE:dd-mmm-yy/THROUGH:dd-mrnrn-yy
/TODAY
/EXCLUDE:filespec

!Given day only
!From given day through current day
!From beginning through given day
!From given day through given day
!Today only
!Filespec can include wildcards.

9-47

APPENDIX A

COMMON ERROR MESSAGES

The following error messages are common to many DCL commands.
They
may appear on your terminal preceded by a 3-letter code identifying
the system component that detected the error. This can be DCL or the
first three letters of the command itself. This code appears here as
yyy.
Most of the error messages with the word "expected" in them reprint
the command on your terminal with a circumflex (A) pointing to the
error. Sometimes the circumflex points to the character just past the
last successfully parsed command element.
Many of the explanations refer to the Radix-50 character set.
The
Radix-50 characters are the uppercase alphabet, the numerals 0 through
9, the dollar sign($), and the period(.).
Many other error messages are included in the descriptions of the
commands that produce the errors. Many system tasks also issue error
messages. These messages are explained elsewhere in the documentation
set.
In particular, many I/O errors return error messages as code
numbers. These errors are explained in the system Mini-Reference and
are discussed further in the I/O documentation. The RSX-llM/M-PLUS
MCR Operations Manual and the RSX-llM/M-PLUS Utilities Manual also
contain explanations of many errors.
yyy -- Allocation failure - no contiguous space

Explanation: Not enough contiguous space
output volume for the file being copied.

available

the

User Action: Delete any files no longer required on the output
volume and retry the command. You may need to use the BACKUP
command or the DSC utility to compress the files on the output
disk.
' yyy

Allocation failure on output file
or

yyy

Allocation failure -- no space available

Explanation:

Not enough space is available on the output
for the file being copied.

User Action:

volume

Delete any files no longer required on the output
volume and retry the command. You may need to use the BACKUP
command or the DSC utility to compress the files on the output
disk.

A-1

COMMON ERROR MESSAGES
yyy -- A-Z expected

Explanation:

The

command

typed

included

nonalphabetic

character.

User Action:

Check command for proper syntax and reenter.

yyy -- A-Z and/or 0-9 expected

Explanation:

The command as

typed

included

nonalphanumeric

character.

User Action:

Check command for proper syntax and reenter.

yyy -- Bad error message

Explanation:

Some unusual condition has caused an error.

User Action:

Notify your operator or system manager and make
ready to send in a Software Performance Report (SPR) • Record the
command that caused the error and other information on activity
at your terminal at the time.
yyy -- Bad use of wild cards in destination file name

Explanation: A wildcard (*) was specified
where it is not permitted.
User Action:

Reenter the command with a
file specification for the output file.

for

output

file

complete

and

explicit

UFO

found

yyy -- Cannot find directory file

Explanation: The command
current volume.

specified

not

User Action:

Reenter the command after checking for the
UFO and correct volume.

the

correct

yyy -- Cannot find files

Explanation:

The file or files specified in the command are
in the designated directory.

not

User Action:

the

Check

the

file

specification

and

reenter

command line.
yyy -- Cannot rename from one device to another

Explanation:

The command

attempted

rename

file

across

devices.

User Action: Use the COPY command to
device to another and rename it.

move

the

file

from

one

yyy -- Cannot truncate this f iletype

Explanation: The command attempted to truncate a file that
cannot
be
truncated.
Only files containing fixed-length,
variable-length, or sequenced records can be truncated.
User Action:

Check to see if you have named the proper file
retry the command.

A-2

and

COMMON ERROR MESSAGES
yyy -- Close failure on input file
or
yyy -- Close failure on output file

Explanation:
closed.

A file named in the command could not
The file is locked by PIP.

properly

User Action:

Use UNLOCK to unlock the file.
Determine the cause
of the error and correct it if you can.
You may need to check
the validity of the file structure with the VFY utility.

yyy -- Command function not unique

Explanation: The command as typed did not
characters to identify some command function.
User Action:

include

sufficient

Retype command after checking proper syntax.

yyy -- Command line incomplete

Explanation:

The command as typed is not a complete command.

User Action:

Retype command after checking proper syntax.

yyy -- Command syntax error

Explanation:

The command did not conform to the syntax rules.

User Action:

Check command for proper syntax and reenter it.

yyy -- Conflicting qualifier

Explanation: The command as typed included
conflict with each other in their effect.
User Action:

qualifiers

that

Retype command after checking proper syntax.

yyy -- Contradictory qualifier

Explanation: The command as
typed
included
qualifiers, such as /DELETE and /NODELETE.
Oser Action:

contradictory

Check for proper syntax and reenter command.

yyy -- Contradictory qualifier in key specification

Explanation:

The command included a contradictory
the key definition argument to the /KEY qualifier.

User Action:

qualifier

Check command for proper syntax and reenter.

yyy -- Decimal number expected

Explanation:

The command included a number not in proper format.

User Action: Check command for proper syntax and reenter with
decimal point (.) terminating the number.

COMMON ERROR MESSAGES
yyy -- Device invalid or not specified
Explanation:
The command specified an invalid
device at all when a device name is required.

device

User Action:
Check the devices on the system with SHOW DEVICES.
Reenter command after checking for proper syntax. Determine the
cause of the error and correct it if you can.
If you cannot, see
your operator or system manager.
yyy -- Device not in system
Explanation:
The command specified a device that is not
current system.
User Action:
Check the devices on the system with SHOW
Reenter command after checking for proper syntax.

the

DEVICES.

yyy -- Device not mounted/allocated
Explanation:
The command specified a device that is not properly
mounted or allocated for the command to execute.
User Action: Check the status of the device with SHOW DEVICES.
Find the cause of the error and correct it if you can.
It is
likely that you will need to mount the volume on the device.
Nonprivileged users need the volume label to mount the volume.
yyy - Device not terminal
Explanation:
The command specified a device other than
a
terminal where a terminal device name is required.
TI:
is not
an acceptable terminal device name in all contexts.
user Action:
syntax.

Reenter

the

command

after

checking

for

proper

yyy -- Directory write protected
Explanation:
The command attempted to remove an entry from a
directory that is privileged or from a directory on a device that
is write-protected.
User Action:
Determine the cause of the error and correct it if
you can.
You may need to enable write access through the device
hardware or change the protection for the directory.
If you
cannot correct the error, see your system manager or operator.
yyy -- Error dispatching command.

DSW = 'n'

Explanation:
An error occurred that was not
by DCL or some invoked task.

explicitly

handled

User Action:
Look up the DSW error code in the Mini-Reference or
the RSX-llM/M-PLUS Executive Reference Manual.
Determine the
cause of the error and correct it if you can.
If you cannot, see
your system manager or operator.
yyy -- Explicit output file name required
Explanation:

The command requires an explicit output file name.

User Action:
Reenter the
without wildcards.

command

A-4

line

proper

syntax

and

COMMON ERROR MESSAGES
yyy -- Extraneous input
Explanation:
The command as
typed
included extraneous input.
The circumflex
(A)
points to the error or just past the last
successfully parsed command element.
User Action:

Reenter the command line in proper syntax.

yyy -- Failed to attach output device
or
yyy -- Failed to detach output device
Explanation:
An attempt to attach or detach a
record-oriented
output device, such as a terminal or line printer, failed.
This
error usually means the device is off-line or nonresident.
User Action: Determine the cause of the error and correct it
you can.
If you cannot, see your operator or system manager.

yyy -- Failed to create output UFD
Explanation:
The command failed
to create an entry in a
directory because the device was write-protected or because of a
privilege violation.
User Action:
Determine the cause of the error and correct it if
you can.
You may need to enable write access through the device
hardware or change the protection for
the directory.
If you
cannot correct the error, see your system manager or operator.
yyy -- Failed to delete file
or
yyy -- Failed to mark file for delete
Explanation:

The command attempted to delete a protected file.

User Action:
Check for the proper file specification and default
OFD and reenter
the command.
You may need privilege to delete
the file.
yyy -- Failed to enter new filename
Explanation:
The command specified a file that already exists in
the UFD, or the directory is protected.
Oser Action:

Check for proper syntax and reenter the command.

yyy -- Failed to find files

Explanation:

The command specified a file or

files

that

could

not be found as specified.
Oser Action:
the command.

Check for proper file

A-5

specifications

and

reenter

COMMON ERROR MESSAGES
yyy -- Failed to get time parameters
Explanation:

An internal system problem has occurred.

User Action: Retry the command. If the error recurs, see your
system manager and prepare to submit a Software Performance
Report. Record the command that caused the error and other
information on activity at your terminal at the time.
yyy -- Failed to read attributes
Explanation: The command specified a
corrupted or protected against access.

volume

that

either

User Action: You may be able to correct the error by making your
defaults the same as the device and UFD of the file you wish to
affect. You may need to check the validity of the volume with
the VFY utility.

yyy -- Failed to remove directory entry
Explanation: The command attempted to remove an entry
directory that was either protected against access
write-protected device.

from a
or on a

User Action: Determine the cause of the error and correct it if
you can. You may need to enable write access through the device
hardware or change the protection for the directory.
If you
cannot correct the error, see your system manager or operator.
yyy -- Failed to truncate file
Explanation: The command specified a volume that is corrupted or
is protected against access.
User Action: You may be able to correct the error by making your
defaults the same as the device and UFD of the file you wish to
affect. You may need to check the validity of the volume with
the VFY utility.
yyy -- Failed to write attributes
Explanation: The command specified a volume that is corrupted or
is protected against access.
User Action: You may be able to correct the error by making your
defaults the same as the device and UFD of the file you wish to
affect. You may need to check the validity of the volume with
the VFY utility.
yyy -- Fatal I/O error
Explanation: The command failed to execute because of some I/O
error.
This error can be caused by the unavailability of a
device or of pool space, or by a device error. The device may be
write-locked.
User Action: Determine the cause of the error and correct it
you can. If you cannot, see your operator or system manager.

A-6

COMMON ERROR MESSAGES
yyy -- File is lost

Explanation: PIP has removed a file from its UFO,
delete it, and failed to restore the directory entry.

failed

User Action:

check

Use the VFY utility to run the lost-file
recover the file name.

yyy -- Filename or filetype not specified

Explanation:

The command as typed did not clearly specify a file
name and file type where one or the other or both is required.
This error can be caused if you do not leave a space in front of
a file specification that is a parameter.

User Action:

Retype command after checking for proper syntax.

yyy -- File not locked

Explanation:

An UNLOCK command specified

file

that

not

locked.

User Action:

Check for the proper file specification and reenter

the command.
yyy -- File specification either invalid or not specified

Explanation:

The system could not read a file specification
included in the command. This error often results from a typing
mistake or typing the command in the wrong format.

User Action:

Check for proper syntax and reenter the command.

yyy -- File specification list not available for RMS-11

Explanation: A command to an RMS-11 utility included
one input file specification.
User Action:

than

Check for proper syntax and reenter command.

yyy -- File version number not specified

Explanation:

The command requires a file version

number

specified.

User Action:

Reenter command after checking for proper syntax.

yyy -- Function not unique

Explanation: The command as typed did
characters to identify some function.
User Action:

not

include

sufficient

Retype the command but include more characters.

yyy -- Get command line - Bad @ file name

Explanation:

The command specified an illegal

indirect

command

file.

User Action:

Check for proper file specification and reenter the

command.

A-7

COMMON ERROR MESSAGES
yyy -- Illegal command

Explanation:

The command, which is the first word on the command
line, is not part of DCL.

User Action:

Check command for proper syntax and
the command fails again, see your system manager.

reenter.

Explanation: The command named a device in an illegal format
contained some other syntax error.

yyy -- Illegal device

User

Action: Check command for proper syntax and reenter.
Device names are two alphabetical characters followed by an octal
number and a colon.

yyy -- Illegal f ilespec

Explanation:

The command required a file specification that

was

not present.

User Action:

Check command for proper syntax and reenter.
See
Section 4.1.2 for a complete description of a file specification.
Perhaps some other command element is being parsed as a filespec.
Use the prompting version.

yyy -- Illegal job name

Explanation:

A command to the Queue Manager named a
improper format.

job

User Action:

Check command for proper syntax and reenter.
Job
names include an optional UIC and as many as nine Radix-50
characters. ThP job nam~ is listed in the SHOW QUEUE display.

yyy -- Illegal or contradictory qualifier

Explanation: One or more
conflict, or are in error.
User Action:

qualifiers

the

command

are

Check command for proper syntax and reenter.

yyy -- Illegal processor name

Explanation: A command to the Queue Manager named a processor in
an improper format.
User

Action: Check command for proper syntax and reenter.
Processor names include as many as six Radix-50 characters.
Processor names are listed in the SHOW PROCESSOR display.

yyy -- Illegal protection code

Explanation:

The command
improper format.

specified

User Action:

protection

code

Check command for proper syntax and reenter.
Section 4.1.5 for more information on protection codes.

A-8

an
See

COMMON ERROR MESSAGES
yyy -- Illegal qualifier value
Explanation:
The command as typed included an improper
to a qualifier.

User Action: Check command for proper syntax
DCL, an argument is preceded by a colon {:).

and

argument

reenter.

yyy -- Illegal queue name
Explanation:
A command to the Queue Manager named a queue in
improper format.

User Action: Check command for proper syntax and reenter. Queue
names include as many as six Radix-50 characters.
Queue names
are listed in the SHOW QUEUE display.
yyy -- Illegal use of wildcard character
Explanation:
The command included a wildcard (* or %) in a file
specification in a way that would result in unpredictable or
inconsistent output.
User Action: Check command for proper syntax and
may not be able to use the wildcard.

reenter.

You

yyy -- Illegal task name
Explanation:
The command named a task using a task
illegal format.

name

Oser Action: Check command for proper syntax and reenter.
names include as many as six Radix-50 characters.

an
Task

yyy -- Input device must be a directory device
Explanation:
The command as typed specified a device that is not
a directory device, such as a line printer or magnetic tape.
Directory devices are those on which Files-11 volumes with
directories can be mounted.
User Action:

Correct syntax and reenter command.

yyy -- Input files have conflicting attributes
Explanation: Warning message.
The command operation
but the files named had'conflicting attributes.

completed,

User Action:
Use DIRECTORY/ATTRIBUTES to find the attributes of
all input and output files involved. Determine if the conflict
causes any difficulty.
yyy -- Invalid command function
Explanation:
The command as typed requested a function
not valid for that command.
User Action:

that

Check command for proper syntax and reenter it.

A-9

COMMON ERROR MESSAGES
yyy -- Invalid command parameter

Explanation:

The command as typed included a parameter that is
not valid.
In DCL, a parameter is either entered in response to
a prompt or preceded by a space.

Oser Action:

Check command for proper syntax and reenter.

yyy -- Invalid file specification list

Explanation:

The command included a list of file specifications
in an invalid format.
In general, file specifications in lists
should be separated by commas and, optionally, blanks.

User Action:

Retype command after checking proper syntax.

yyy -- Invalid file specification qualifier
a
file
Explanation: The command included a qualifier to
In DCL, a qualifier is
specification that was not valid.
preceded by a slash (/) •

User Action:

Check for proper syntax and retype the command.

yyy -- Invalid terminal specified

Explanation:

A command directed to a specific terminal named the
terminal in an improper format.

User Action:

Check the name of the terminal using SHOW USERS and
reenter the command with the proper format.

yyy -- Invalid time or date

Explanation: The comman~
both, incorrectly.
Oser Action:

~pecified

a clock or calendar field, or

Check for proper syntax and retype the command.

yyy -- Invalid UIC specified

Explanation: The command specified a O, a number including an 8
or 9, or a number greater than 377 (octal) for the group or
member number in a UIC or UFO.
Oser Action:

Retype command after checking for proper syntax.

yyy -- I/O error on input file
or
yyy -- I/O error on output file

Explanation:

One of the following conditions exists:

• The device is not on line.
• The device is not mounted.
• The hardware has failed.

• The output volume is full.
• The input file is corrupted •
A-10

COMMON ERROR MESSAGES
Oser Action:
Determine the cause of the error and correct it
you can.
If you cannot, see your operator or system manager.

yyy -- Key position size or number not specified
Explanation:
The command failed to include the size or number of
a key position in the key definition argument to the /KEY
qualifier.
Oser Action:

Check command for proper syntax and retype it.

yyy -- Key specification out of sequence
Explanation:
The command included improper
definition argument to the /KEY qualifier.
Oser Action:

syntax

the

key

Check command for proper syntax and reenter.

yyy -- Magnetic tape file label not specified
Explanation:
The command attempted to initialize a magnetic tape
without specifying the required volume label.

User Action:

Retype command after you have

checked

for

proper

syntax.
yyy -- More command parameters than permitted
Explanation:

The command as typed included too many parameters.

Oser Action:

Check command for proper syntax and reenter.

yyy -- No such file
Explanation:
The command requested operations
does not exist.

file

that

Oser Action: Make sure you have named the file properly.
Check
your defaults to be sure you are looking in the right UFO on the
right device.
You may have made a typing error.
If the desired
file is in fact not present, find out why it is not present and
proceed accordingly.
yyy -- Not a directory device
Explanation:
A directory-oriented command named
does not have directories, such a line printer.
User Action:
a UFO.
yyy

device

If you can, reenter the command without

that

specifying

Not logged in
P - .... 1 ___ ...... .: - - •
£1A.t:'.LQUQ~.LVUo

A command

wa~

entered

a terminal

that

not

logged in.
Oser Action:
Only LOGIN, HELLO and HELP execute on terminals
that are not logged in.
If you do not know how to log in, type
HELP.
If you know how to log in, do so and reenter the command.

A-11

COMMON ERROR MESSAGES
yyy

Numeral expected

yyy

Numeral required
Explanation: Command included nonnumeric
characters
position where numerals are required or expected.
User Action:

Check command for proper syntax and reenter.

yyy -- Octal number expected
Explanation:
The command included a number with an 8 or 9
an octal number was expected.
User Action:

where

Check command for proper syntax and reenter.

yyy -- Open failure on file
Explanation:
reason.

The system could not open a required file for

some

User Action: Check the UFD to be sure that the file is present,
not locked, and in the proper format.
If the file is locked, it
may be corrupted or contain bad data. Determine the cause of the
error and correct it if you can.
If you cannot, see your
operator or system manager.
yyy -- Output device must be a directory device
Explanation:
The command as typed specified a device that is not
a directory device, such as a line printer or magnetic tape.
Directory devices are those on which Files-11 volumes with
directories can be mounted.
Oser Action:

Correct syntax and reenter commanda

yyy -- Partition busy
Explanation: The partition into which a task was to be fixed was
occupied by a running task.
The requested task thus could not be
fixed.
User Action: Wait until the partition is no longer busy or
out why the partition is busy and proceed accordingly.

find

yyy -- Primary key not specified
Explanation:
A command affecting an indexed file failed to
include a primary key.
In many such commands, you cannot specify
any action on an alternate key without first
identifying the
primary key.
User Action:

Check for proper syntax and reenter command.

yyy -- Privilege violation
Explanation: The command was a privileged command
nonprivileged terminal.

issued

User Action:
None.
If you must have the function
find a privileged user to issue the command for you.

A-12

requested,

COMMON ERROR MESSAGES
yyy -- Qualifier inconsistent with compiler
Explanation:
A compiler command included a
qualifier
not
acceptable by that compiler, such as a FORTRAN/F4P command
including a /LINE_NUMBERS qualifier, which is for the FOR
compiler only.
User Action: Check the command for proper syntax and try it
again.
Remember that your command may be specifying a compiler
by default.
yyy -- Qualifier not available for this command format
Explanation:
The command included a qualifier that is invalid in
the current context of the command.
The context is usually
determined by some other qualifier in the command.
User Action:

Reenter command after checking for proper syntax.

yyy -- Qualifier not unique
Explanation: The command as typed did not include sufficient
characters to identify some qualifier.
In DCL, qualifiers are
preceded by a slash (/) •
User Action:

Retype the command, but include more characters.

yyy -- Qualifier value invalid here
Explanation: The commands as typed included an inappropriate
argument to a qualifier.
In DCL, an argument is usually preceded
by a colon (:) .
User Action:

Check command for proper syntax and reenter.

yyy -- Radix-50 expected
Explanation: The command included a non-Radix-50 character where
Radix-50 required.
User Action: Reenter the command using proper syntax.
The
Radix-50 characters are the uppercase alphabet, the numbers O
through 9, the dollar sign ($}, and the period (.).
yyy -- Repeated command parameter
Explanation: The command as typed included one parameter more
than once.
In DCL, a parameter is preceded by a blank or prompt.
User Action:

Retype command after checking for proper syntax.

yyy -- Repeated key specification
Explanation: The command as typed included the
same
key
specification more than once in the key definition argument to
the /KEY qualifier.
User Action:

Retype command after checking for proper syntax.

yyy -- Repeated keyword in key specification
Explanation: The command as typed included the same keyword more
than once in the key definition argument to the /KEY qualifier.
User Action:

Retype command after checking for proper syntax.

A-13

COMMON ERROR MESSAGES
yyy -- Repeated magnetic tape file label
Explanation:
than once.

The command included the required volume label more

User Action:
the command.

Check command syntax for

correctness

and

reenter

yyy -- Repeated qualifier
Explanation: The command specified the same qualifier more
once. In DCL, a qualifier is preceded by a slash (/).
User Action:
it is right.

than

Reenter command after checking the syntax to see if

yyy -- Required parameter not specified
Explanation: The command cannot
execute
without
parameters, such as a file specification or attribute.
parameter is preceded by a blank or prompt.
User Action: Retry the command, using the prompts.
for all required parameters.

required
In DCL, a

DCL

prompts

yyy -- Required qualifier not specified
Explanation: The command requires a qualifier that it does
include. In DCL, a qualifier is preceded by a slash (/).
User Action:

not

Check for proper syntax and reenter the command.

yyy -- Required qualifier value not specified
Explanation: A qualit1er to the command requires that you state
a numerical argument. In DCL, an argument is usually preceded by
a colon (:) •
User Action:

Retype command after checking for proper syntax.

yyy -- Required value not specified for position size or number
Explanation: The command failed to include a required
the key definition argument to the /INDEXED qualifier.
User Action:

value

Check command for proper syntax and reenter.

yyy -- Sorry, line too long
Explanation: DCL commands are translated for execution by MCR or
another system task or utility.
This error is caused by a
translated command line that the destination task cannot handle.
User Action: Check command syntax to see if you are specifying
elements that can be defaulted. Check to see if you can enter
the command twice with different qualifiers to accomplish in two
commands what you cannot accomplish in one. You may have to
enter the command in MCR format or the format of the task or
utility you are seeking to invoke. Check the translated command
line with SET DEBUG.

A-14

COMMON ERROR MESSAGES
yyy -- Sorry,

not supported in Indirect

Explanation:
An indirect command file
included an
illegal
element, as identified by the quoted part of the message.
User Action:

Check indirect command file for correctness=

yyy -- Sorry, low pool
Explanation:
The command
could
not
execute
because
of
insufficient space in the system pool (dynamic storage region) .

User Action:

The pool is the Executive's data base.
In general,
each task, including commands, uses a certain amount of pool.
If
the pool is full or badly fragmented, there may not be sufficient
space for
the command to execute.
Usually, pool problems clear
up spontaneously if you wait.
Retry the command after an interval.
If it still does not
execute,
see your operator or system manager.
You should not
attempt to execute any other task, not even an ABORT or LOGOUT,
when the pool is low.
These tasks too absorb pool.

yyy -- Sorry, task active
Explanation:
The command required some
taken on an active task.

action

that

cannot

User Action:
Determine the cause of the error and correct it
if
you can.
If you cannot, see your system manager or operator.
Check the task with the various SHOW TASK commands, or SHOW
MEMORY.
yyy -- Sorry, task not installed
Explanation:
installed.

The command attempted to invoke a task that was not

User Action:
Try running the task with a command in the RUN $
form.
Determine the cause of the error and correct it if you
can.
If you cannot, see your system manager or operator.
yyy -- Syntax error
Explanation:
The command
included some error
in typing
specification, such as a letter where a number should appear.
User Action:

Check for proper syntax and reenter command.

yyy -- Version must be explicit or

"*"

Explanation:
The command syntax requires that the version number
of the file must be specified explicitly or as a wildcard ( * ) .
User Action:
Reenter
correctly expressed.

the

command

with

the

version

number

yyy -- Wildcards not permitted
Explanation:
Command included a wildcard (* or %)
where it is not permitted.
User Action:

Check for proper syntax and reenter command.

A-15

context

COMMON ERROR MESSAGES

yyy -- Zero value not valid for key size or number

Explanation: The command included a zero
definition argument to the /KEY qualifier.
User Action:

value

the

Check command for proper syntax and reenter.

A-16

key

APPENDIX B
FUNCTIONS INITIATED BY DCL COMMANDS

Most DCL commands initiate functions that are actually performed by
MCR or by some other system task or utility. The following table
gives these relationships, with any necessary comments.

DCL Command

MCR Command,
Task, or Utility

ABORT

ALLOCATE

AL Locate

APPEND

PIP

ASSIGN

ASsigN

Assign logical name

ASSIGN/QUEUE

QMG

Assign queue to
processor

ASSIGN/REDIRECT

REDirect

Redirect device

ASSIGN/TASK

REAssign

Alter LUN assignments

BACKUP

BRU

BASIC

BAS, BP2

BROADCAST

BROadcast

CANCEL

CANcel

COBOL

COB

CONTINUE

RESume

CONVERT

RMS CNV

COPY

PIP

CORAL

COR

CREATE

PIP, FCS

CREATE/DIRECTORY

UFD

DEALLOCATE

DEAllocate

DEASSIGN

ASsigN

Comments

Deassign logical name

B-1

FUNCTIONS INITIATED BY DCL COMMANDS

DCL Command

MCR command,
Task, or Utility

DEASSIGN/QUEUE

QMG

Eliminate assignment of
queue to processor

DELETE

PIP

Delete files

DELETE/ENTRY

QMG

DELETE/JOB

QMG

DELETE/PROCESSOR

QMG

Delete despooler task

DELETE/QUEUE

QMG

Delete queue

DIFFERENCES

CMP

DIRECTORY

PIP
RMS DSP

DISMOUNT

DisMOunt

EDIT

EDT, EDI, KEO, SLP

FORTRAN

FOR, F4P, F77

FIX

HELP

HELlo

Comments

/ATTRIBUTES qualifier

As part of HELlo, HELP
can run on unlogged-on
.a..---!
- - , l..C.LUl.L UQJ.i:) e

HOLD/ENTRY

QMG

HOLD/JOB

QMG

INITIALIZE

INitvolume

Create Volume

INITIALIZE/PROCESSOR

QMG

Set up despooler task

INITIALIZE/QUEUE

QMG

INITIALIZE/UPDATE

Home

INSTALL

IN Stall

LIBRARY

LBR

LINK

TKB

HELlo

LOGOUT

BYE

MACRO

MAC

MCR

Alter volume's
home block

Task Builder. May be
more than one on
system. STK is Slow TKB.
FTB is Fast TKB.

B-2

FUNCTIONS INITIATED BY DCL COMMANDS

DCL Command

MCR Command,
Task, or Utility

MOUNT

MOUnt

QMG

PURGE

PIP

RELEASE/ENTRY

QMG

RELEASE/JOB

QMG

REMOVE

RE Move

RENAME

PIP

REQUEST

BROadcast

RUN

RUN INS

SET [DAY] TIME

TIMe

SET DEFAULT

SET /UIC

SET DEVICE

DEVice

SET GROUPFLAGS

FL Ag

SET LIBRARY/DIRECTORY

SET /LIBUIC

SET PARTITION

PAR, SET /MAIN,
SET /PAR, SET SUB

SET PRIORITY

ALTer

SET PROTECT ION

PIP

SET QUEUE

QMG

SET SYSTEM/DIRECTORY

SET /SYSUIC

SET SYSTEM/EXTENSION LIMIT

SET /MAXEXT

SET SYSTEM/NOLOGINS

SET /NOLOGON

SET SYSTEM/PACKETS

SET /MAX PKT

SET SYSTEM/POOL

SET /POOL

SET TERMINAL

SET /attribute

~~qw,. ;~~.O!l'N'.'11;1,'.~G,.,:";.:;;.i .'

Comments

SET for UFO
ASN for SY:

·~qq

SHOW ASSIGNMENTS

ASsigN

SHOW CLOCK_QUEUE

CLQ

SHOW COMMON

CBD

SHOW [DAY]TIME

TIM

SHOW DEFAULT

SET /UIC
ASsigN

Common Block Directory

B-3

SET for UFO
ASN for SY:

FUNCTIONS INITIATED BY DCL COMMANDS

DCL Command
SHOW DEVICES

MCR Command,
Task, or Utility

Comments

DEV
SET /PUB
SET /BUF

/PUBLIC qualifier
/WIDTH qualifier

SHOW GROUPFLAGS

FL Ag

SHOW MEMORY

RMD

SHOW PARTITIONS

PAR

SHOW PROCESSOR

QMG

SHOW QUEUE

QMG

SHOW SYSTEM/CL I

CL! /SHOW

SHOW SYSTEM/DIRECTORY

SET /SYSUIC

SHOW SYSTEM/EXTENSION LIMIT

SET /MAXEXT

,..TTnr..T

SET /POOL

onvn

SYSTEM/POOL

Resource Monitoring
Display

SHOW SYSTEM/SECONDARY POOL
-

SET /SECPOL

SHOW TASKS/ACTIVE

ACT

SHOW TASK:taskname/ACTIVE

ATL

SHOW TASKS/DYNAMIC

RMD

SHOW TASKS/INSTALLED

TAS

SHOW TASKS/INSTALLED/FULL

TAL

SHOW TASK:taskname/INSTALLED TAS
SHOW TERMINAL

DEV

SHOW TERMINAL/attribute

SET /attribute

SHOW USERS

DEV

SORT

SRT

START

UNS

START/PROCESSOR

QMG

START/QUEUE

QMG

START/QUEUE/MANAGER

QMG

START/UNBLOCK

UNBLOCK

STOP/ABORT

QMG

STOP/BLOCK

Block

SORT-11

B-4

FUNCTIONS INITIATED BY DCL COMMANDS

DCL Command

MCR Command,
Task, or Utility

STOP/PROCESSOR

QMG

STOP/QUEUE

QMG

STOP/QUEUE/MANAGER

QMG

TYPE

PIP

UNFIX

UNFix

UNLOCK

PIP

B-5

Comments

APPENDIX C
SUMMARY OF TECHNICAL CHANGES

This appendix lists all changes in DCL syntax from RSX-llM-PLUS Vl.O
to
RSX-llM-PLUS
V2.0,
and
from
RSX-llM/M-PLUS
V4.0/2.0 to
RSX-llM/M-PLUS V4.l/2.l.
Section C.l lists
all
commands
and
qualifiers that have changed syntax since Vl.O, Section C.2 lists all
syntax elements that have been added to DCL since Vl.O, and Section
C.3 lists all commands and syntax elements that have been added or
changed for V4.l/2.l.

C.l

CHANGED SYNTAX

This section lists all commands and qualifiers changed since
RSX-llM-PLUS.
Old

Vl.O

New
ABORT

ABORT
/[NO]DUMP

/[NO]POSTMORTEM
APPEND

APPEND
/INDEXED [/KEY:NUMBER:n)
/RELATIVE
/SEQUENTIAL

No support (use CONVERT)
No support (use CONVERT)
No support (use CONVERT)