Digital PDFs

AA-FD04A-TC

October 1985

616 pages

Original

120MB

Document:	RSX-11M-PLUS Command Language Manual Version 3.0
Order Number:	AA-FD04A-TC
Revision:	0
Pages:	616
Original Filename:

OCR Text

PREFACE

Convention
filespec

Meaning
A full file specification includes device, directory,
and version number, as in the
file name, file type,
following example:
DU1:[COTTONTAL]HIPPITY.HOP;2
Full file specifications are rarely needed. If you do
not give a version number, the highest numbered version
will be used.
If you do not give a directory, the
default directory 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 file specification with a DECnet
See Chapter 1, for more information.
node name.

red ink

All user input in examples is printed in red ink to
That is, what you
distinquish it from
system output.
type is shown in red.
A symbol with a 2- to 6-character abbreviation indicates
that you are to press the corresponding key on your
indicates that you are to
terminal. For example,
means that you are to
press the RETURN key, and
press the DELETE key.

{A I B}

A number of options between braces and separated by
vertical bars means that you are to choose one from the
options listed.
means that you are to press the key
The symbol
Thus,
marked CTRL while pressing another key.
indicates that you are to press the CTRL key and the Z
is echoed
on
in this
fashion.
key together
your terminal as ^Z. Not all control characters echo.
See Chapter 3 for more information.

See Chapter 1, for more information on DCL conventions.

HOW TO USE DCL
Arguments are preceded by a colon (:), or an equals sign
book documents only the colon.

(=).

This

Here is an example:
$ DIRECTORY/OUTPUT:UNCLE.DAT SOLO.*
In this case, the elements of the command line are as follows:
DIRECTORY is the command name.
OUTPUT, which is preceded by a slash (/), is a qualifier.
This qualifier indicates that you want the output from the
DIRECTORY command to go somewhere other than your terminal
screen, which is the default.
UNCLE.DAT, which is preceded by a colon (:), is the argument
to
the /OUTPUT qualifier. This argument is the name of the
file where you want the output from the command to go.
This
SOLO.*, which is preceded by a blank, is a parameter.
parameter is the name of the file(s) of which you are taking a
are
file
listing.
Most
DCL
parameters
directory
specifications, as is this one. The asterisk (*) indicates a
for
information on
See Section 4.4
wildcard file type.
wildcards.
Note that after you type in a command,
you must pass it to the
operating system by pressing either the RETURN key or the ESC key.
(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
See Section 1.3.13 for a discussion of command lines that
completed.)
are 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
(In some cases, an omission causes an
question mark (?) for help.
error message rather than a prompt.)

1.3.1

Prompting

The prompts teach you the form
supply required command elements.

of a

command

requesting that you

For example, the RENAME command works as follows:
$ RENAME
Old file name? BROWNS.STL
New file name? ORIOLES.BLT
The one-line format for RENAME is as follows:
$RENAME BROWNS.STL ORIOLES.BLT
The formats can be mixed. DCL prompts for whatever you leave out.
For example:
$RENAME BROWNS.STL
New file name?ORIOLES.BLT

1-8

HOW TO USE DCL
There are no defaults for prompts. You must supply a response to 'any
prompt.
If you do not wish to continue with the command, press
CTRL/Z.

1.3.2

Qualifiers

Qualifiers modify the action of the command
optional. Qualifiers always start with a slash

and

are

generally

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 name, as in this
example:
$TYPE/TODAY *.HLP
However, most command qualifiers can appear anywhere in the command
line.
They are also called "floating qualifiers." The following
examples illustrate how command qualifiers can float:
$TYPE *.DAT/TODAY
or
$TYPE
File(s)?*.DAT/TODAY
or
$TYPE
File(s)?/TODAY
File(s)?*.DAT
You can mix formats and get exactly the same results, as in the
following examples:
$TYPE/TODAY
File(s)?*.DAT/EXCLUDE:ILLYA.DAT;*
or
$TYPE/TODAY
File(s)?*.DAT/
Qualifier?EXCLUDE:ILLYA.DAT;*
or
$TYPE/TODAY
File(s)?/
Qualifier?EXCLUDE:ILLYA.DAT;*
File(s)?*.DAT
Note that you are prompted for a qualifier when a slash with no
qualifier attached appears on the command line. When you supply the
qualifier, do not type the slash again.
Almost all command qualifiers can float. In a few cases,
however, 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

1-9

HOW TO USE DCL
Other qualifiers to such commands can still
qualifier cannot float.
float, however, as in this example:
$ CREATE/DIRECTORY
Device and UFD? [JENA]/ALLOCATION:5
which is the same as the following example:
$ CREATE/DIRECTORY/ALLOCATION:5 [JENA]
Parameter qualifiers, sometimes called file specification qualifiers,
cannot float. Usually a parameter qualifier must be attached to a
file
specification,
because
most
DCL
parameters
are
file
specifications.
Many qualifiers can be negated by prefixing NO or -- (minus) to the
qualifier name. Thus, the command
$

DELETE/LOG *.TXT;*

deletes all files with the type .TXT and
deletions on your terminal, while the command
$

DELETE/NOLOG *.TXT;*

DELETE/-LOG *.TXT;*

prints

list

the

simply deletes all the files without printing a list. (This action is
in fact the default behavior, but the example is given to illustrate
the use of the negative form of qualifiers.)

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

need

help

on the

TYPE

command,

type

$ HELP TYPE
TYPE[/qualifier[s]] filespec [s]
/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 displays the contents of text files on your
terminal.
To obtain help on the above qualifiers, type the following:
$ HELP TYPE qualifier

1-10

the

HOW TO USE DCL
TYPE
The HELP text consists of the command syntax, showing that
accepts one or more file specifications and one or more qualifiers,
followed by a brief explanation.
You can also type a HELP command naming the qualifier to get more
information on that qualifier, as in this example:
$ HELPTYPE TODAY
TYPE/TODAY filespec[s]
The /TODAY qualifier specifies that you wish the TYPE
command to type only files created today.
If you want help while being prompted by the
following procedure:

TYPE

command,

use

the

$TYPE RET
File(s)??
TYPE[/qualifier[s]] filespec[s]
/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 displays the contents of text files on your
terminal.
To obtain help on the above qualifiers, type the following:
HELP TYPE qualifier
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 want 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 (?) followed
by the subtopic. For example, after getting help on SET, you can also
get help on a specific function of SET:
$ SET RET
Function? ?
The SET command establishes or changes the following:
DEFAULT
[DAY]TIME
HOST
LIBRARY
PROTECTION/DEFAULT

DEVICE
[NO]PARTITION
QUEUE

ERROR_ LOG
PRIORITY
SYSTEM

For information on the above commands, type HELP SET
commandname.

1-11

GROUPFLAGS
PROTECTION
TERMINAL

HOW TO USE DCL
To get help on a specific topic, enter a question mark followed by the
topic as follows:
Function? ? DEFAULT
SET DEFAULT

[ddnn:][directory]]

The SET DEFAULT command sets your default directory or device,
or both.
Function?
You can also get help by typing a question mark in response to the
dollar sign prompt ($).
If you should decide after reading the help text that you have chosen
the wrong command, enter a CTRL/Z in response to the prompt to end the
execution of the command. (A CTRL/Z pressed before entering the
command always cancels the command.)
From a DCL terminal, the command HELP provides information on DCL and
the command HELP/MCR
provides
information on MCR.
From an MCR
terminal, the command HELP provides information on MCR and the command
HELP/DCL provides information on DCL.
There may also be help files providing information on special aspects
of your
installation.
In addition, you can create local help files
for your own use. See Chapter 3 for more information on the
HELP
command and help files.

1.3.4

MCR and DCL Commands

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

DCL

DC L

If you are at a DCL terminal and want 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
If you want 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.

1.3.5 Abbreviations
the complete command
It is rarely
necessdry for you to type either
name or the complete qualifier name.
You only need to type the
characters needed to distinguish the command or qualifier from all
others.

1-12

HOW TO USE DCL
For example:
TYPE can be abbreviated T because it is the only command
beginninq with that character.
INITIALIZE can be abbreviated INI, but not IN.
INSTALL can be abbreviated INS, but not IN.
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 you can abbreviate various
commands.
For instance, the following command:
$SET TERMINAL/VT100
is the documented format for the command that sets a terminal as a
The same command to VAX/VMS DCL does the same thing. However,
VT100.
the RSX-11M-PLUS version of DCL permits you to type the following:
$ SET VT100
to achieve the same result. This second form does not work on VAX/VMS
systems.
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.7 for a discussion
of
compatibility between RSX-11M-PLUS DCL and other versions of DCL
used on other operating systems.
For your convenience, some frequently used commands have special brief
forms as follows:
Command

Brief Form

Command

Brief Form

ABORT
BROADCAST
COPY
DIRECTORY
REALLOCATE
REASSIGN
EDIT
FORTRAN

A
B
C
D
DEAL
DEAS
E
F

HELP
HELP
LOGOUT
LINK
MACRO
PRINT
RUN
SHOW
TYPE

H
?
LO
L
M
P
R
S
T

To save time and typing, use these brief forms to replace the command
names when you are entering commands.
NOTE
As new commands are added
abbreviations may change.

future

releases,

1.3.6 Numbers and Dates
You usually do not
DCL recognizes both octal and decimal numbers.
a
number
as
octal
or
decimal,
as DCL takes care of
have to identify
In rare cases, the command description directs you to add a
it.
decimal point to identify a decimal number.

1-13

HOW TO USE DCL
DCL recognizes dates in two forms:
dd-mmm-yy as in 21-JUN-85
or
mm/dd/yy as in 06/21/85
System displays are always in the first format.

1.3.7

Multiple Parameters

Some commands permit you to enter a list of parameters
instead of just
one.
If you are entering a list of parameters, each parameter must be
set off by commas. For example,
$

PRINT JANE.TXT

causes a single file to be printed, while
$ PRINT JANE.TXT, CHRIS.TXT, MULP.TXT
causes three files to be printed. You have
spaces on either side of the comma in lists.
If you end the list with a
parameters. For instance:

comma,

DCL

the

option of including

prompts

you

for

further

$ PRINT JANE.TXT, CHRIS.TXT,
File(s)? MULP.TXT
Some commands for program development accept a list of arguments to a
single qualifier or parameter. In such cases, the list of arguments
must be enclosed in parentheses, with the elements set off by commas.
For example:
$ LINK/CODE:(PIC,FPP) HIYA
If you need to enter only a single argument, you do not need the
parentheses.
For example:
$

1.3.8

LINK/CODE:PIC 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.
However, PRINT/FLAG PAGE will not work. You cannot include a space in
a command field.

1.3.9

Colon and Equal Sign

The command descriptions in this manual show arguments set off by a
colon (:), such as follows:
$

PRINT/COPIES:2 IZZY.TXT

1-14

HOW TO USE DCL
You can usually replace such colons with an equal sign (=), as in this
example:
$PRINT/COPIES=2 IZZY.TXT
replaced

equal

If you wish to include an exact string in a DCL command,
string in quotation marks. For instance, the message

put

the

Colons in device names, such as DU1:,
signs.

1.3.10

cannot be

Quoting Strings

$BROADCAST/ALL Rockand roll will never die
is broadcast as
From PRINCE::WRITERS (TT64) to ALL

11-MAY-85 13:55

ROCK AND ROLL WILL NEVER DIE
while
$BROADCAST/ALL "Rockand roll will never die"
is broadcast as
11-MAY-85 13:56

From PRINCE::WRITERS (TT64) to ALL

"Rock and roll will never die"
You need quotation marks when passing commands to tasks using the
/PARAMETERS qualifier to MOUNT or the /COMMAND qualifier to RUN or
INSTALL.

1.3.11

ANSI File Names

ANSI file names do not have the same format as Files-11 file names and
may contain characters that are illegal in Files-11. For instance,
the file name "MONEY&." is a legal ANSI file name, as is "CASH&.". To
use those file names in a command, simply enter them as shown in the
following example:
$ COPY
From?MM:"MONEY&."
To?MM1:"CASH&."
If you are copying a file from a tape to a Files-11 disk, you must use
only Radix-50 file specifications, such as the following:
$COPY
From?MM:"MONEY&."
To?DB:[200,1]RADIX50.TXT
The Radix-50 character set consists of the numbers 0 through 9, the
letters of the alphabet, the dollar sign ($), and the period (.).

1-15

HOW TO USE DCL
1.3.12

DECnet and DCL

Your system may include the optional DECnet networking software.
so, you'll need the following information.

DECnet is a DIGITAL product that enables two or more systems to "talk"
to each other. These systems are linked together physically to form a
network . The purpose of a network is to allow the users on different
systems to share information and resources. See the Introduction to
DECnet for more information about this product.
Each system in a network is called a node .
The system that you
originally log in to is your
local node . All other systems in a
network are called remote nodes.
Some DCL commands accept DECnet
node
specification.
They are the following:
APPEND
DIRECTORY

COPY
RENAME

CREATE
TYPE

names

part

file

DELETE

Several other DCL commands accept
node
names
in
the
file
specifications.
However, DECnet modifies the basic syntax of these
commands.
These commands are: PRINT, SUBMIT, SET PROTECTION, and SET
FILE.
Be sure to check the RSX DECnet Guide to User Utilities before
attempting to use these commands.
If the node you select is part of your network, you can simply add the
node name to the file specification in the appropriate DCL command.
Note that your terminal remains connected to your local node when you
issue these commands to a remote node.
In the following example, you issue a command to type on your terminal
the file ROMAN.TXT, which is located on remote node PRINCE and device
DB2:, in directory [PETER].
$ TYPE PRINCE::DB2:[PETER]ROMAN.TXT
All the usual rules about file and volume protection are maintained,
of course.
See Section 4.5.
If the remote node you specify has a different style of file
specification
from
RSX-11M-PLUS,
you
must
enclose the file
specification in quotation marks, as shown:
$TYPE NEMO::"DISK$USERDISK:[DALTON]DESPERADO READERS.DIS"
In addition to transmitting commands between nodes, DECnet also allows
you to connect your
terminal to a remote node. See the SET HOST
command, described in the following section.

1.3.12.1

SET HOST

After you have logged in to a system, you can use the SET HOST command
to connect your terminal to a different system.
Both your current system and the remote system must run DECnet
software.
In addition,
you need to have an account on the remote
system.
Otherwise, you will not be able to log in to the remote
system after you issue the SET HOST command.

1-16

HOW TO USE DCL
Format
SET HOST nodename
Parameters
nodename
Specifies the name of the remote system that you want to connect
your terminal to.
A node is one system within a network of systems. The system
that you originally log in to is called a local node; all other
systems in a network are called remote nodes.
Once you have connected to the remote node, that operating system
After you log in, use commands that the
responds with a prompt.
remote operating system accepts.
Type the LOGOUT command to log out of a remote node.
this command, you are located on your local node.

After

typing

You can only use SET HOST to connect to one remote node at a time.
For example,
suppose you want information located at two different
remote nodes, KING and JUNE. You cannot connect first to remote node
and then execute SET HOST again to connect to remote node JUNE.
KING,
You must first log out of KING, which relocates you on your local
node, then use SET HOST to connect to JUNE.
See the RSX DECnet Guide to User Utilities for a full
this command.

explanation

Example
$SET HOST TOOTSI
Connected to "TOOTSI", System type = RSX-11M-PLUS
RSX TIMESHARING
System ID:
$LOGIN
Account or Name:Erin
Password:

This SET HOST command connects your terminal to the remote node
The remote system identifies itself, then prompts you. You
TOOTSI.
log in to the remote system,
using the name and password of your
account on that system.

1.3.12.2

SHOW HOST

The SHOW HOST command displays the name of the processor to which your
The display also shows you the name
terminal currently is connected.
and version number of the operating system running on the processor.

1-17

HOW TO USE DCL
The SHOW HOST command is most useful after you have connected your
terminal to a remote system with the SET HOST command. However, SHOW
HOST works whether or not your system runs DECnet software.
Without
DECnet on your system, this command simply displays information about
your local operating system.
Format
SHOW HOST
Example
$

SHOW HOST

HOST=TOOTSI RSX-11M-PLUS V3.0 BL 24
This example indicates the display from SHOW HOST. The name of your
current processor
is TOOTSI,
which is running Version 3.0 of the
RSX-11M-PLUS operating system.

1.3.13

Command Line Continuation

Sometimes a command will not fit all on one line. In that case you
can continue the line by using a hyphen (-). When you end a command
line with a hyphen and a 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.

DCL commands are limited to 80 characters in all.
When you type a
continuation line, count the hyphen and the two times you press the
RETURN key as three of the 80 characters. Of course, each blank, as
well as each punctuation mark, counts as one character.
Here is an example of line continuation:
$ PRINT/COPIES:2/FLAG_PAGE/AFTER:(04-JUN-85) OZY.TXT,--> IZZY.TXT,FIZZY.TXT
The command is not entered until DCL encounters a line ending with a
RETURN that is not preceded by a hyphen. In the example, the first
RETURN does not enter the command. Only the second RETURN, with no
hyphen, enters the command. The RETURN can be on a line by itself.

1.3.14

Comments in Command Lines

You may want to include comments in command lines if you are keeping a
permanent record, such as a batch job or command file, or simply an
interactive session on a hardcopy terminal. You can include a comment
in a DCL command line by preceding it with an exclamation point (!).
If the comment ends the command line,
exclamation point, as in this example:
$ PRINT OZY.TXT

!Poem by Shelley

1-18

you

need

only

single

HOW TO USE DCL
If the comment is within the command line, you need two exclamation
points to set it off, as in this example:
IZZY.TXT

$PRINT!Parody of Shelley!

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.
Another example:
$PRINT/FORMS:2!Letter-quality printer! IZZY.TXT

1.3.15 SET DEBUG
The SET DEBUG command 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 want the DCL command to
execute after the translation is displayed. The default is the
/NOEXECUTE qualifier, meaning that the translation only is
displayed.
When the SET DEBUG/NOEXECUTE command is in effect,
you can only execute SET DEBUG commands or MCR commands using the
all other DCL commands are trapped and
DCL
command MCR;
translated.
You can issue SET NODEBUG to turn ff SET DEBUG.
You can also issue the SET DEBUG command with the /FULL qualifier
or the /EXECUTE qualifier or both.
/FULL
The /FULL qualifier indicates that you want the SET DEBUG command
(IFORM queue) used by DCL to
to display the logical symbols
translate the command as well as the translation itself. See the
RSX-11M/M-PLUS System Management Guide for information on how DCL
uses these logical symbols.

1-19

HOW TO USE DCL
Example
$ SET DEBUG
$ SHOW TIME
TIM
$ INITIALIZE/EXTENSION:200/PROTECTION:(SYS:RWED,OWN:RWED,GRO,WO)
Device? DR2
Label? HOTROD
INI DR2:HOTROD/EXT=200./PRO=[RWED,RWED „]
$ SET DEBUG/EXECUTE
$ SHO TIM
TIM
21:33:46 17-JUN-85
$ SET NODEBUG
In this example, the user first issued the SET DEBUG command.
Then,
the user typed SHOW TIME. DCL displayed TIM, which is the MCR command
that displays the date and time, but no date and time is displayed
because the /NOEXECUTE qualifier was in effect. Next, the user typed
an INITIALIZE command and DCL displayed the MCR translation of the
same command. Then, the user issued the SET DEBUG/EXECUTE command and
typed SHOW TIME again. This time, after displaying the MCR command
TIM,
DCL passed the command TIM to MCR and the date and time were
displayed.
Finally, the user issued the SET NODEBUG command to end
the session with the SET DEBUG command.
Notes
Use the SET DEBUG command to check on the MCR syntax of any DCL
command.
This
is particularly helpful when learning the brief forms
of commands.
The SET DEBUG command creates your own copy of DCL that remains
present while SET DEBUG is in effect.
Therefore, the SET DEBUG
command creates a load on the system. You should use this command
sparingly, particularly when the system is in heavy use.
You should not use the SET DEBUG command if your terminal is set to
serial mode.
Because DCL remains an active task while you are in this
mode (which is also an active task) and your terminal can process only
one task at a time, you may encounter unpredictable results when your
terminal tries to process two tasks at the same time.

1.3.16 Errors
You can correct typing errors or change the line completely by using
the DELETE key or CTRL/U, provided you have not terminated the line.
You can get rid of any DCL command by pressing a CTRL/Z, provided you
have not terminated the command.
If the system detects an error in the command line input, it returns
the appropriate error message at the issuing terminal.

1-20

HOW TO USE DCL
Here are some examples of incorrect commands and the error messages
they produce:
$PRIJT IZZY.TXT
DCL -Illegal command
$PRINT/PURPLE IZZY.TXT
PRINT -Illegal or contradictory qualifier
PRINT/PURPLE IZZY.TXT
$PRINT/COPIES:TWELVE IZZY.TXT
PRINT -- Numeral expected
PRINT/COPIES:TWELVE IZZY.TXT
In the first case, the error was detected by DCL, as indicated by the
first part of the error message. There is no DCL PRIJT command. The
entire command was rejected.
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 (^)
points to the error.
In the third case, the command and the qualifier were correct, but the
argument was in error.
The message explains
the error and the
circumflex points to the error.
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 or after the actual error. Typing mistakes
are by far the most common cause of errors. Retyping the command is
often all you need to do to eliminate 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 Chapter 10.

1.4

USING THE QUEUE MANAGER: PRINT AND BATCH JOBS

The RSX-11M-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 Chapter 4. The
description includes information on how to display and alter jobs in
the print queues.
In addition, the Queue manager provides a batch processing facility.
Batch jobs allow you to 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 as at night or on weekends.
All uses of the Queue Manager are described in a separate manual, the
RSX-11M/M-PLUS
Batch
and Queue Operations Manual . The manual
introduces and explains all the uses of the Queue Manager and the

1-21

THE SET AND SHOW COMMANDS
You use this command in the following manner:
$ SHOW TERMINAL
TT13:

[TEST1]
CLI
= DCL
LINES = 24.
LOWER
NOPRIV
ECHO
VFILL
CTRLC
AVO
SERIAL

07-MAY-859:05
HFILL
BUF
= 80.
TERM
= VT2xx
OWNER
NOHOLD
NOSLAVE
NOESC
HHT
NOFDX
WRAP
DEC
EDIT
ANSI

1
M. ANGEL
= 0
BRO
NOABAUD
= none
CRT
NOFORM
NOREMOTE
NORPA
NOEBC
TYPEAHEAD
NOREGIS NOSOFT
NOBLKMOD

The display is explained in full in Section 3.8.2. Here, briefly, are
the more significant fields:
Terminal number, login directory, date and time, and name
CLI
BUF
LINES
TERM
OWNER
BRO
NOPRIV
CTRLC

Current CLI setting
Buffer length, that is, the width in colum ns
Page length in lines
Terminal model
Tells whether terminal has been allocated
Terminal can receive broadcast messages
Terminal is not privileged
Terminal has Control/C
abort
enabled

The SET TERMINAL command permits you to set most of these attributes
for your terminal.
Privileged users can set the attributes of any
terminal.
Format
SET TERMINAL/attribute[/attribute[s]]
Note that you can set more than one attribute at a time.
such as the following:

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:
/UPPERCASE
/LOWERCASE
/DCL
/MCR
/SPEED:(transmit,receive)
/PAGE LENGTH:n /WIDTH
/HARD COPY
/[NO]BROADCAST /[NO]PRIVILEGE /SCOPE
/HOLD SCREEN /INQUIRE
/CLI=cliname /CONTROL=C
You can also set your terminal as a particular model:
/ASR33
/ASR35
/DTC01
/KSR33
/LA12
/LA30P
/LA30S
/LA34

See Section
attributes.

3.8.1

/LA36
/LA38
/LA50
/LA100
/LA120
/LA180S
/LN03
/RT02

/RT02C
/VT05
/VT50
/VT52
/VT55
/VT61
/VT100
/VT101

for

information

2-3

/VT102
/VT105
/VT125
/VT131
/VT132
/VT200_SERIES

the

meaning

of these

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 displays the terminal
number and default directory for each logged-in user.
On systems with Resource Accounting active, SHOW USERS also
the user's name and the number of currently active tasks.

displays

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 displays 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/0. When you
exit (for example,
by pressing 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 have an accessible on-off switch. This switch supplies
power
to the terminal, but it has no bearing on whether the terminal
is logged in. If you turn the power switch off, a logged-in terminal
remains logged in.
You can test whether a terminal is turned on and available by pressing
RETURN.
The RETURN key causes the dollar sign prompt ($) 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 directory.
If the terminal is already logged in, look at the prompt to determine
whether the terminal in set to DCL or MCR. If the terminal is set to
MCR, a right-angle-bracket prompt (>) is displayed on the terminal.
If the terminal is set to MCR, issue the following command line to
determine if there are any active tasks running on the terminal:
>ACT

3- 2

TERMINAL OPERATIONS
If the terminal is set to DCL, issue the following command for the
same information:
$SHOW TASKS/ACTIVE
This command informs 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, by typing the following:
$ LOGOUT
If your terminal is set to MCR, execute the following command to log
out:
MCR>BYE
Then, after you log out the terminal, log yourself in.
If the terminal is not logged in, you may log in.
You can log in
using either HELLO or LOGIN together with your User Identification
Code (or name) and your password. The system's HELLO program logs you
in if you have an account on the system and have used the proper
password.
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 MCR (or
the converse) with the following commands:
MCR>SET /DCL=TI:
or
$ SET TERMINAL/MCR
All RSX-11M-PLUS systems are multiuser protection systems. This means
that the system includes features, such as LOGIN and LOGOUT (Section
3.1.2) and ALLOCATE or MOUNT/NOSHAREABLE( Chapter 5), that enable many
users to use the system without interfering with each other's work.

3-3

TERMINAL OPERATIONS

LOGIN (Cont.)
Examples
$LOGIN
Account or name:KAFKA
Password:
RSX-11M-PLUS V3.0 BL24 Multiuser [3,54] System CASTOR
20-MAY-85 09:16 Logged on Terminal TT54:
Good Morning
May 20, 1985

System Manager

** System will be down tonight from 21:00 to 24:00 **
** BACKUPS TONIGHT **
Please purge your files!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
May 1, 1985

Operator

Magtape drive MSO: is back on line.

In this example, the user logs in with a name (KAFKA) ,
and
the
full
login text is automatically printed on the terminal. The full login
text is also printed if you log in with a UIC entered with a comma
[g,m]. See the next example.
The dollar sign prompt ($) signifies the completion of logging in.
$LOGIN 303/5
Password:
RSX-11M-PLUS V3.0 BL24 Multiuser [3,54] System CASTOR
20-MAY-85 09:16 Logged on Terminal TT54:
Good Morning
May 20, 1985
System Manager
** System will be down tonight from 21:00 to 24:00 **
** BACKUPS TONIGHT **
Please purge your files!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

3-5

TERMINAL OPERATIONS

LOGIN (Cont.)
This example shows the first login of the day for this user. The UIC
is entered with a slash (303/5). The printing of the system LOGIN.TXT
file in full is therefore suppressed. Only the first message (defined
as being a priority message by the system manager) is printed. The
This
priority message is printed only on the first login of the day.
ensures that users who habitually log in with the slash do not miss
anything.
See the next example.
$ LOGIN 303/5
Password:
RSX-11M-PLUS V3.0 BL24 Multiuser [3,54] System CASTOR
20-MAY-85 09:16 Logged on Terminal TT54:
Good Morning

This example shows a subsequent login on the same day by the same
user.
Note that no system messages are displayed.
$ LOGIN
Account or name: 301/370
Password:
RSX-11M-PLUS V3.0 BL24 Multiuser [3,54] System CASTOR
20-MAY-85 09:16 Logged on Terminal TT54:
Good Evening
$ @LOGIN.CMD
$ SET TERMINAL/INQUIRE
$ SET PROTECTION:(S:RWED,O:RWED,G:R,W:)/DEFAULT
$ ASSIGN RS: DU1:
$ @ <EOF>
This user has prepared a LOGIN.CMD file in his directory to set up the
terminal,
establish a default protection code, and make a logical
assignment. The operating system runs the LOGIN.CMD file each time
the user logs in.
The commands shown are issued by the indirect
command file LOGIN.CMD; the @ <EOF> marks the end of the command file.
See the Introduction to RSX-11M-PLUS and the RSX-11M/M-PLUS Indirect
Command Processor Manual for more information on indirect command
files.
Your system manager may have established your account so that you do
not receive login messages, regardless of how you log in. If this is
the case, none of the information that usually appears between the
Password:
prompt and your
LOGIN.CMD file prints on your terminal.
Therefore, you do not see the system identification or messages from
the system manager's LOGIN.TXT file,

3-6

TERMINAL OPERATIONS

LOGOUT
3.1.2

LOGOUT

LOGOUT logs the user off the system and makes the terminal available
to another user.
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 (including those
allocated by means of MOUNT/NOSHAREABLE).
Format
LO[GOUT] [/HOLD]
No prompts.
Command Qualifier
/[NO]HOLD
Used on remote or DECnet host terminals.
If you include the
qualifier,
the terminal
is logged out but the line is not
disconnected.
This means you can
log
back
in
without
reconnecting the line.
The default is /NOHOLD, meaning that when
you log out, the line is also disconnected.
Examples
$ LOGOUT
Connect time:
0 hrs 44 mins 0 secs
CPU time used: 0 hrs 12 mins 6 secs
Task total:
90
Have a good afternoon
08-JUL-85 16:58 TT10:
Logged off PRINCE
In this example, the user logs off an RSX-11M-PLUS system.
The
information on system use only prints on systems that have Resource
Accounting running. (PRINCE is a DECnet node name. DECnet is a
DIGITAL product that allows the users of different computer systems to
share information and resources.
A node is the name of one of these
systems.)
Your system manager may have set up your account so that you do not
receive system information when you log out.
In this case, the
operating system simply prints a dollar sign prompt ($) to indicate
that you have successfully logged out.

3-9

TERMINAL OPERATIONS

LOGOUT (Cont.)
$ LOGOUT
DMO -- TT10: Dismounted from DU1:
Connect time:
0 hrs 32 mins 0 secs
CPU time used: 0 hrs
0 mins 12 secs
Task total:
21
Have a good morning
08-JUL-85 11:17 TT10:
Logged off ROMPER
In this example, the user logs off with a volume mounted on device
DU1:.
The LOGOUT command dismounts the volume, as the message states.
If the device is allocated, the LOGOUT command deallocates it, but
does not issue a message.
$ LOGOUT
13:29:36

Task "TT10 " Terminated
Aborted via directive or CLI

Connect time:
0 hrs 23 mins 0 secs
CPU time used:
0 hrs 3 mins 6 secs
Task total:
36
Have a good afternoon
19-JUN-85 13:30 TT10:
Logged off MICRO
In this example, the user has a task running from the terminal at the
time the LOGOUT command is issued. The LOGOUT command causes the task
to be aborted.
Notes
LOGIN, or HELLO, counteracts LOGOUT.
You need type only LO to log out.
BYE is the same as LOGOUT.

3.1.3

ACNT, the Account File Maintenance Program

Account files on RSX-11M-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 (commonly DCL) and a default device with each user.
Privileged users have full access to the functions of ACNT, as
described
in
the
RSX-11M/M-PLUS
System
Management
Guide.
Nonprivileged users have no access to ACNT. They can change their
password
using the SET PASSWORD command (the next section). However,
to change other aspects of their account, nonprivileged users need to
see the system manager.
The RSX-11M/M-PLUS System Management Guide also has information on
Resource Accounting, a separate system program that keeps track of
system usage.
Resource Accounting is briefly described in Section
3.2.3.2.

3-10

TERMINAL OPERATIONS

SET PASSWORD
3.1.3.1

SET PASSWORD

SET PASSWORD changes your password.
Format
SET PASSWORD
Old password:
New password:
Verification:
Nothing that you type in response to these prompts is echoed. This is
shown in the examples by enclosing the password in angle brackets.
Your password is limited to 39 Radix-50 characters, including dollar
signs
($), periods
exclamation points (!) , quotation marks
and hyphens (-).
Example
$ SET PASSWORD
Old password: <KRYPTO>
New password: <COVERT>
Verification: <COVERT>

In this example, the user changes the password from KRYPTO to COVERT.
SET PASSWORD verifies that the new password is correct. If you type
the
in different responses to New password:
and Verification:,
password is not changed.
To preserve security, choose nonobvious passwords. You should not use
your name (or a close friend's), nor should you use the same password
on more than one system. The more characters there are in a password,
the harder it is to guess.
Notes
SET PASSWORD invokes a task called PSW, which is installed as ...PSW.
PSW puts the new password in the system account file.
Because passwords are encrypted on RSX-11M-PLUS,
the system manager
and other privileged users cannot access your password, however, they
can still change it by running ACNT.
If you are a nonprivileged user and do not remember your password, you
will have to have the system manager or a qualified privileged user
change your password by running ACNT.

3-11

TERMINAL OPERATIONS
When you log out,
Resource Accounting displays the time you were
logged in, the CPU time used, and the number of tasks used.
Users can also display current Resource
command SHOW ACCOUNTING/INFORMATION.

Accounting

data

with the

The data gathered by Resource Accounting makes possible the billing of
individual
users
for the system resources used, and measurement of
overall system usage.
For further information on Resource Accounting as well as command
descriptions, see the RSX-11M/M-PLUS System Management Guide.

3.2

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 (Section 3.2.7) 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, there
may be a noticeable lag between the input and the echo.
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
standard DIGITAL 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.2.1

RETURN and Command Line Length

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.
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/COPIES:2/FORM:1/DELETE IZZY.TXT, OZY.TXT, ->MADISON.AVE, FUZZY.TXT;12, GUNGA.DIN;2

3-13

TERMINAL OPERATIONS
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
The hyphen called for the
single line.
could be specified on a
execution of the
(->),
rather than
special continuation prompt
The carriage return without the preceding hyphen then called
command.
for execution of the full command. For more information on command
line continuation, see Chapter 1.

3.2.2

Line Terminators

You can terminate a command line with either the RETURN key or the key
and CTRL/C are also
variously labeled ESC, SEL, or ALTMODE. CTRL/Z
Each of these terminators has different effects.
line terminators.
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
the
implicit DCL prompt reappears, ready for
command
is processed,
another command.
For example:
$ SHOW TIME
09:59:21 13-JUN-85
You need
command.

not

wait

for

the

return

the

prompt

to enter another

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

does

not

$ SHOW TIME
10:05:38 13-JUN-85
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

included on
You should avoid the BACK SPACE key. This key is
terminals for compatibility with other systems but is not used in DCL.
The BACK SPACE key moves the cursor to the beginning of the current
line, 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
(The BACK SPACE key may be used
key to correct it, not BACK SPACE.
for special functions within tasks, as it is in EDT.)
on the
The DELETE key (labeled RUBOUT on some terminals and
VT200-series terminals) works in a slightly different fashion on video
and hardcopy terminals.

3-14

TERMINAL OPERATIONS
On hardcopy 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:
$RUN FEEBER

appears on a hardcopy terminal as:
$ RUN FEEBER\ RE\LE
But the operating system receives the command:
$ RUN FEEBLE
You can verify this by pressing a CTRL/R after the corrected line to
retype it properly, without the intervening deleted characters, thus:
$ RUN FEEBER\RE\LE
$ RUN 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:
$ RUN FEEBER

The sequence appears on a video screen in succession as follows:
$ RUN
$ RUN
$ RUN
$ RUN
$ RUN

FEEBER
FEEBE
FEEB
FEEBL
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.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-11M-PLUS" without
disengaging it, even though the numbers and the hyphens are lowercase.
The SHIFT keys set
by
CAPS
affected
characters.

your terminal to uppercase for the keys not
LOCK,
as
well as for
individual alphabetic

On most hardcopy terminals, CAPS LOCK sets all keys to uppercase.
Different terminal models vary widely in their treatment of CAPS LOCK
or the equivalent key. You should experiment on your terminal.

3.2.5

REPEAT

You
The REPEAT key on the LA36 repeats the action of any other key.
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

3-15

TERMINAL OPERATIONS
2.

If you try to type more than 80 characters on a line without
using a hyphen to continue the line, the system automatically
to the
cancels the command and indicates this by sending a ^U
for more information on line
terminal.
See
Chapter
1
continuation.

Finally, if there is no available pool space when you type in
to your terminal informing
a command, the system sends a ^U
you that your command has been canceled. 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 problem.

3.4.6

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 hardcopy 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:
$ THIMK\KM\NK
$ 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 often see a ^R and a second copy of your
command line.
Simply continue typing the command.

3.4.7

CTRL/X

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

3.4.8

SET TERMINAL command, for

CTRL/L

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

3-23

TERMINAL OPERATIONS

HELP (Cont.)
/FILE:filespec
If
Specifies any file where help text is located.
give
a
complete
file
specification, the
in
LB:[001,002]filename.HLP.
You must be logged
qualifier.

you do not
defaults are
to use this

/filename
with
Specifies
that
the
help
text
begins
LB:[001,002]filename.HLP.
When using this qualifier, you cannot
specify the device, directory, or extension, only the file name.
You must be logged in to use this qualifier.
Examples
$HELP
Help is available for the following DCL commands:
ABORT
BACKUP
CONTINUE
DEASSIGN
DIRECTORY
HELP
LINK
MOUNT
RENAME
SORT
UNLOCK

ALLOCATE
BASIC
CONVERT
DEBUG
DISMOUNT
HOLD
LOGIN
PRINT
REQUEST
START

ANALYZE
BROADCAST
COPY
DEFINE
EDIT
INITIALIZE
LOGOUT
PURGE
RUN
STOP

APPEND
CANCEL
CREATE
DELETE
FIX
INSTALL
MACRO
RELEASE
SET
TYPE

ASSIGN
COBOL
DEALLOCATE
DIFFERENCES
FORTRAN
LIBRARY
MCR
REMOVE
SHOW
UNFIX

type
HELP
commandname.
For information on a command,
Additional help on a particular qualifier is often available
by typing:
HELP commandname qualifier
You can also get any DCL help on DCL commands by typing a ?
in response to a prompt.
For information on utilities, system tasks, and other system
For the short forms of some
information, type HELP MORE.
commands, type HELP BRIEF.
For help on logging in, type HELP
LOGIN.
This example shows the initial display from HELP. The
without parameters or qualifiers.

3-27

user types HELP

TERMINAL OPERATIONS

HELP (Cont.)
$ TYPE
File(s) ?
TYPE [/qualifier[s]] filespec[s]
/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 displays the contents of text files on your
terminal.
File(s)?
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 thing
The SHOW command can be used to show something. The
following
things can be shown with this command:
ACCOUNTING
ASSIGNMENTS
CACHE
CLOCK-QUEUE
COMMON

[DAY]TIME
DEFAULT
DEVICES
ERROR LOG
GROUPFLAGS

LIBRARY
LOGICALS
MEMORY
PARTITIONS

PROCESSOR
PROTECTION
QUEUE
SYSTEM

TASKS
TERMINAL
UIC
USERS

Abbreviation: S
Function? ? TIME
SHOW DAYTIME
SHOW TIME
The SHOW TIME command displays the current time and date. The
time is in 24-hour 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.5.1

Help File Format: Writing a Help File

The HELP facility requires a specially formatted file or files called
help
iles.
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
special purpose.

for any help file:

3-28

local,

group,

CLI,

TERMINAL OPERATIONS

BROADCAST (Cont.)
@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
following formats:

also

use the

privileged qualifiers in the

ALL:message
LOGGED_IN:message
The indirect command file cannot include any Indirect directives
The destination
or labels,
only destinations and messages.
cannot be preceded by tabs or blanks.
Command Qualifiers
/ALL
Sends the same message to all powered terminals, excluding slaved
terminals.
This qualifier is privileged.
/LOGGED IN
Sends the same message
qualifier is privileged.

all

logged-in

terminals.

This

Examples
$ BROADCAST
To? TT20
Message? Meet me in the alley behind the barn.
The message is printed on TT20:
FROM: MICRO::SYSMGR (TT10:)
30-MAY-85 16:34
TT20:
MEET ME IN THE ALLEY BEHIND THE BARN.

TO:

Notice
As the message arrives,
the terminal's audio signal sounds.
that the message is printed in uppercase characters on the receiving
it is
If you enclose the message in quotation marks ("),
terminal.
printed exactly as you enter it, including the quotation marks.
$BROADCAST TT12: THIS IS A ONE-LINER.
This is the one-line form of the command.
$ BROADCAST/LOGGED_IN
Message? Everybody take the rest of the day off.

3-33

TERMINAL OPERATIONS

BROADCAST (Cont.)
The message is printed
privileged command.
$

all

logged-in

terminals.

This

BRO @DAILY

The file DAILY.CMD contains the following messages:
TT1:WHERE IS THE DITKO CONTRACT?
TT3:MEET ME FOR LUNCH AT 11:30.
TT7:THE QUICK BROWN FOX JUMPED OVER THE LAZY DOG.
TT5:GET BACK TO WORK.
TT4:I LOST MY GREEN EYESHADE. HAVE YOU SEEN IT?
Privileged
The messages are sent to the designated terminals.
can also include messages preceded by ALL: and LOGGED IN:.

users

Notes
B is the short form of BROADCAST.
Only terminals can receive messages.
If you want your message to include lowercase characters when printed,
enclose the message in quotation marks (").
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 an 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/O 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 want to receive broadcasts.
See Section 3.8.1.
This command invokes the MCR BRO task.
Error Messages
BRO---Command input error
Explanation:
line.

The BROADCAST task did not receive the command

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

Check for proper syntax and enter the command

3-34

TERMINAL OPERATIONS

REQUEST
3.7

REQUEST

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

message
message

Parameter
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.
The message
terminal.

time-stamped

and

indented

the

operator's

Example
$ REQUEST Charlie, the tape drive is down again.
The message appears on the operator's console in the following form:

13:30:45
13:32:45
13:32:47

13:36:22
14:36:42

The user at TT6:
observes a problem on the system and reports it to
the operator with REQUEST.
The message appears on the operator's
console, timestamped and indented so that it stands out from other
messages.

3-36

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
On systems that support separate instruction and data space, you
set the size of the typeahead buffer from 0 through 255. If
can
your terminal is set /SERIAL, you may want to increase the size
of the typeahead buffer so you can queue more commands.
On non-instruction and data systems,
buffer is fixed at 58 characters.

the size of the typeahead

/[NO]WRAP
Specifies that the terminal automatically
lines longer than its line width.

wrap

(or

not

wrap)

The /WRAP qualifier 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.
The
/NOWRAP qualifier
unlimited line length.

overrides

this

feature

and

permits

Examples
$SET
Function?TERMINAL
Attribute?INQUIRE
The command in this example causes the system to test the terminal
type and then set all appropriate attributes for that terminal type.
In most cases, you will not need to change any attributes of your
terminal after issuing this command.
$ SET TERMINAL/INQUIRE
This is the equivalent of the previous example. Include the command
in this form in your LOGIN.CMD file and your terminal attributes will
be set each time you log in.
$ 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 is the reprinting of
characters deleted by the DELETE key. This command sets a number of
defaults.
These are-shown in Table 3-2 in Section 3.8.2.
$SET TERM/SPEED:(110,300)
This example sets the issuing terminal to transmit at 110 baud and
The acceptable values for transmit and receive
receive at
300 baud.
rates are inherent in the design of the terminal and other hardware.
See the documentation provided with your terminal. After issuing this
command, you must reset the hardware to the same transmit and receive
You must issue the SET TERMINAL command first and then set the
rates.
terminal, using SET-UP, so that the terminal driver can communicate
with the terminal.

3-51

TERMINAL OPERATIONS

SET TERMINAL (Cont.)
$ SET TERMINAL/LA36/SPEED:(300,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 TERMINAL/SERIAL/TYPEAHEAD:150
$ MACRO/SHOW:ALL PETE, JOHN, ROGER, KEITH
$ LINK/TASK:WHO KEITH
$ RUN WHO
In this example, the user sets the terminal /SERIAL and increases the
size of the typeahead buffer.
The user then enters a MACRO command,
followed by a LINK command and a RUN command.
The commands are
separated by RETURNs.
The LINK command is not issued until the
assembly completes, and the RUN command is not issued 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 the SHOW TERMINAL command. See the next
section.

3-52

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
/VT05B
/VT52
/VT61
/VT101
/VT105
/VT131
/VT200_SERIES

/VT50
/VT55
/VT100
/VT102
/VT125
/VT132

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

about which you want to
display
is the terminal from which the command

A SHOW TERMINAL command, such as the following:
$ SHOW TERMINAL
or
$ SHOW TERMINAL:TT6:
displays all the attributes 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
TERMINAL attribute.
The meaning of each attribute is discussed
in its place under SET TERMINAL in Section 3.8.1.
In addition,
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 issue both a SHOW TERMINAL/BROADCAST command
and a SHOW TERMINAL/NOBROADCAST command.
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 following 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 following
command
$ SHOW TERMINAL/HARDCOPY
causes a display labeled NOCRT, meaning that the terminal is not
a video terminal.

3-54

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
The same display results from the following:
$SHOW TERMINAL/NOSCOPE
Table 3-2 shows the relationships between SHOW TERMINAL and its
displays,
and SET TERMINAL.
information on the
For
further
displays, see the examples.
/HT
/RT
/TI
/TT
/VT
These qualifiers display information about particular types of
terminals on the system.
/HT and /RT display 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 list of virtual terminals.
Virtual terminals are
used in batch jobs and may be used by some applications.
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

ADVANCED VIDEO

AVO

ADVANCED VIDEO

ANSI CRT

ANSI

ANSI CRT

AUTOBAUD

ABAUD=

AUTOBAUD

BLOCK MODE

BLKMOD

BLOCK MODE

BROADCAST

BRO

BROADCAST

CLI:cliname

CLI=

CLI:cliname

CONTROL=C

CTRLC

CONTROL=C

CRFILL

HFILL=

CRFILL

DEC CRT

DEC

DEC CRT

DCL

CLI=DCL

DCL

ECHO

EDIT MODE

EDIT

EDIT MODE

EIGHT BIT

EBC

EIGHT BIT
(continued on next page)

3-55

TERMINAL OPERATIONS

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

SHOW TERMINAL
Display

SET TERMINAL
Attribute

SOFT_CHARACTERS

SOFT

SPEED

SPEED=

SPEED

TAB

HHT

TAB

TTSYNC

TYPEAHEAD

UPPERCASE

NOLOWER

UPPERCASE

WIDTH

BUF=

WIDTH

WRAP

Examples
$ SHOW
Function? TERMINAL
TT10:
[DDALE]
CLI
= DCL
LINES = 24.
LOWER
NOPRIV
ECHO
NOVFILL
CTRLC
AVO
SERIAL
NOHSYNC

16-MAY-85 13:26 1 D. DALE
BUF = 80.
HFILL = 0
TERM = VT100
OWNER = none
NOHOLD NOSLAVE NOESC
CRT
HHT
NOFDX
WRAP
NORPA
ANSI
DEC
NOEDIT NOREGIS
NOPASTHRU
TTSYNC

SPEED= (9600:9600)
BRO
NOABAUD
NOFORM NOREMOTE
NOEBC
TYPEAHEAD
NOSOFT NOBLKMOD

This example displays all the attributes for the user's own terminal.
The command
is the equivalent of SHOW TERMINAL:TI: The attributes
include the terminal number, the default directory, the date and time,
the number of active tasks, the name, plus all the attributes that can
be set with SET TERMINAL. See Table 3-2 and the remaining examples.
$ SHOW TERMINAL:TT5:
B. DIDDLEY
TT5:
[007100] 16-JUN-8513:47 1
CLI
= DCL
BUF = 80.
HFILL = 0
OWNER = SELF
LINES = 24.
TERM = VT100
CRT
LOWER
NOPRIV
NOHOLD NOSLAVE NOESC
NORPA
ECHO
NOVFILL NOHHT
NOFDX
WRAP
ANSI
DEC
NOEDIT NOREGIS
CTRLC
AVO
TTSYNC
SERIAL
NOHSYNC NOPASTHRU

SPEED=(9600:9600)
BRO
NOABAUD
NOFORM NOREMOTE
NOEBC
TYPEAHEAD
NOSOFT NOBLKMOD

This example displays all the attributes for another terminal.
$SHO TERM/ESCAPE

This example shows that no terminal on the system
handle escape sequences.

3-57

is currently set to

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
$ SHO TERMINAL/LA36/DCL
DCL=TT5
LA36=CO0:
LA36=TT0:
LA36=TT4:
This example displays all the terminals on the system set as LA36s and
all terminals on the system set to DCL. Note that the 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.
$ SHO TERM/SPEED
SPEED=TT10:9600:9600
This example displays the speed settings for the terminal from which
the command was issued.
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
ASR33=TT2:
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
NOCRT=TT7:

$ SHO TERM/NOHARDCOPY
CRT=TT2:

$ SHO TERM/SCOPE
CRT=TT1:

$ SHO TERM/NOSCOPE
NOCRT=TT7:
CRT means cathode ray tube, another name for a video screen or scope.
$ SHO TERM/CRFILL
HFILL=TT10:0
This example returns the /CRFILL value for the terminal from which
was issued.

3-58

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
$SHO TERM/LFFILL
VFFILL=TT4:

This example shows which terminal has its /LFFILL attribute enabled.
$ SHO TERM/FORMFEED
FORMFEED=TT3:

$ SHO TERM/NOFORMFEED
NOFORMFEED=TT5:
This example shows which terminals have their FORMFEED attribute
enabled (or not).
$ SHO TERM/TAB
HHT=TT1:

$ SHO TERM/NOTAB
NOHHT=TT7:
This example shows which terminals have their TAB attribute enabled.
HHT means Horizontal Hardware Tabs.
$ 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 SHOW
TERMINAL command, giving the name of the other terminal.)
$ SHO TERM/ECHO
ECHO=TT1:

$ SHO TERM/NOECHO
NOECHO=TT1:
$ SHO TERM/ESCAPE
ESCSEQ=TT10:
$ SHO TERM/NOESCAPE
NOESCSEQ=TT1:

ESCSEQ means ESCape SEQuences.

3-59

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
$ SHO TERM/FULL_DUPLEX
FDX=TT2:
$ SHO TERM/NOFULL_DUPLEX
NOFDX=TT1:

FDX means full-duplex.
$ SHO TERM/PASSALL
RPA=TT1:

$ SHOW TERM/INTERACTIVE
NORPA=TT3:

$ SHO TERM/NOPASSALL
NORPA=TT3:

$ SHO TERM/NOINTERACTIVE
RPA=TT1:

RPA means Read-Pass-All.
$ SHO TERM/REMOTE
REMOTE=TT1:
$ SHO TERM/LOCAL
NOREMOTE=TT2:

$ SHO TERM/NOLOCAL
REMOTE=TT1:

3-60

TERMINAL OPERATIONS

SHOW TERMINAL (Cont.)
$ SHO TERM/NOREMOTE
NOREMOTE=TT2:

This attribute has no relationship to 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 no relationship to DECnet host terminals either.
The LOCAL/REMOTE switch on a terminal sets a terminal as a typewriter
or terminal, respectively.
$ SHO TERM/SLAVE
SLAVE=TT5:
$ SHO TERM/NOSLAVE
NOSLAVE=TT1:

$ SHO TERM/TYPEAHEAD
TYPEAHEAD=TT1:

$ SHO TERM/NOTYPEAHEAD
NOTYPEAHEAD=TT7:
$ SHO TERM/WRAP
WRAP=TT1:

$ SHO TERM/NOWRAP
NOWRAP=TT4:
$ SHO TERM/NOEIGHT_BIT
NOEBC=TT1:

$ SHO TERM/EIGHT_BIT
EBC=TT6:
EBC means Eight-Bit Characters.

3-61

HANDLING FILES
directory.
If you want to print the highest numbered version of this
file (version 3) on your terminal, all of the following forms of the
TYPEcommand produce the same desired result:
$ TYPE TEXT.TXT
$ TYPE TEXT.TXT;3
$ TYPE TEXT.TXT;0
$ TYPE [200,20]TEXT.TXT;3
$ TYPE [MUSTARD]TEXT.TXT;3
$ TYPE DU0:TEXT.TXT
$ TYPE DU0:[200,20]TEXT.TXT
$ TYPE DU0:[MUSTARD]TEXT.TXT
$ TYPE SY:TEXT.TXT
$ TYPE SY:[200,20]TEXT.TXT;3
$ TYPE SY:[MUSTARD]TEXT.TXT;3
$ TYPE SY:[MUSTARD]TEXT.TXT;0
In most cases, you will use the first form, but if you want 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 is always assumed to be 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.

.BAT

File containing
convention.

.BLD

Indirect command file used to create
build system tasks. System default.

.B2S

BASIC-PLUS-2 source program. System default.

.CBL

COBOL source program. System default.

.CMD

Indirect command file. System default.

.COR

Source Language Input Program
(SLP) file
correct a source file. System convention.

.DAT

File containing
default.

.DIR

File is either Master File
Directory. System default.

.DMP

Dump file created by File Dump Utility. System default

.FTN

FORTRAN-77 source program. System default.

.LOG

Log of batch processing session. System default.

.LST

Listing file. System default.

.MAC

MACRO-11 source program. System default.

batch

data,

processing

opposed

commands.

System

files needed to

Directory

used

code.
or

System

User

File

(continued on next page)

4-5

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

Use

.MAP

Task Builder map file. System default.

.MLB

Macro library. System default.

.OBJ

Object module output from assembler or compiler. System
default.

.ODL

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

.OLB

Object module library. System default.

.PAT

Correction file used by assembler
object file. Must be specified.

.PMD

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

.POB

Patched object module input for PAT utility; must be
specified.
See the RSX-11M/M-PLUS Utlities Manual for
more information on file types .PAT and .POB.

.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 Chapter 6, and the RSX-11M/M-PLUS and
Micro/RSX Task Builder Manual for more information.

.SYS

Bootable system image. System default.

.TMP

Temporary file. System convention.

.TSK

Task image file. System default.

.TXT

Text file. System convention.

.ULB

Universal library. System default.

create

patched

4.4 WILDCARDS IN FILE SPECIFICATIONS
In addition to the regular defaults for the current device, the
current directory, 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 file specification except the device name.
Simple wildcarding uses the asterisk (*) to replace all or any fields
in the file specification, except the device name.
For instance, the following command:
$ DIRECTORY [*]
lists
name.

all

files

on the default volume,

4-6

regardless of

the directory

HANDLING FILES
The following command:
$ DIRECTORY [100,*]
lists all files in any numbered directories that have a group number
of 100.
The following command:
$ DIRECTORY [*]TEXT.TXT
lists the most recent versions of all files on the default volume
named TEXT.TXT, regardless of the directory name.
Likewise, the asterisk (*) in place of the version number means "all
versions."
The following command:
$ DIRECTORY WOM.BAT;*
lists all versions of the file WOM.BAT on the default volume and in
the default directory.
The asterisk (*) can also be used to replace an entire file name or
file type in much the same way.
The following command:
$ 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 directory.
The following command:
$ DIRECTORY COMMON.*
lists the most recent versions of all files with the name COMMON
any type on the default volume and in the default directory.

and

of
The examples thus far have demonstrated the simplest form
wildcarding,
using the asterisk (*) to replace an entire field in a
Simple wildcarding works with all the commands in
file specification.
this chapter.
The PRINT command accepts simple wildcarding, as does
the SUBMIT command for batch processing.
PURGE,
COPY, RENAME,
For the following commands, DIRECTORY, DELETE,
TYPE, APPEND, UNLOCK, and SET PROTECTION, a more elaborate form of
wildcarding is available.
In these commands, within file names and
file types,
the asterisk (*) can be used in a more complex manner.
The asterisk actually means "match zero or more characters in this
position."
Therefore, the following 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 directory.

4-7

HANDLING FILES
The following command:
$DIRECTORY *L*.TXT
TXT whose
lists the most recent versions of all files with the type
names include an L on the default volume and in the default directory.
The same substitutions can also be used in file types, so that the
following command:
$ 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
directory.
Note that you can use more than one wildcard in file names and file
types.
The following 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 same commands permit the percent sign (%)
to be used
as a wildcard, but only within file names and file types. The percent
sign means "match exactly one character in this position."
For instance, the following command:
$ DIRECTORY %.TXT
lists all files with the type TXT and a single-character file name on
the default volume in the default directory.
The following command:
$ DIRECTORY NOV%%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 directory.
The wildcards can be combined in a single file specification.
The following 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
directory.
policies
of
directory
Wildcarding, combined
with
systematic
file names,
and file types, can add considerable
assignments,
flexibility and convenience to your use of the system.

4-8

HANDLING FILES
The four kinds of file access that you can grant to the user
categories are as follows:
READ

The user, or the user's tasks, may read, copy, print, or
type the file.

WRITE

The user, or the user's tasks, may add new data to the
it.
You can't edit a file without
file by writing to
WRITE access, nor can you use the COPY command to write a
file to a directory where you have no WRITE access. If
the file is a task image file, WRITE access means you may
run it.
If you deny WRITE access to a class of users,
they can't run the task.

EXTEND

The user, or the user's tasks, may change the amount of
disk space allocated to the file. In practice, EXTEND
access is always specified along with WRITE access.

DELETE

The user, or the user's tasks, may delete the file.
can't delete a file without DELETE access.

You

system's
default
Ordinarily,
the operating system assigns the
protection code to files.
In a protection code, the four types of
The default
file access are designated by their first letters.
protection is as follows:
SYSTEM: RWED,OWNER:RWED,GROUP:RWED,WORLD:R
Note that under this default protection scheme, any user can read your
files because the WORLD category has READ access. Furthermore,
everyone in the GROUP category and all privileged users have full
READ, WRITE,
EXTEND,
and DELETE access. They can all delete your
files.
If you have files that you particularly want to protect against
if want to limit the access people have to your files,
deletion,
or
use the SET PROTECTION or SET PROTECTION/DEFAULT commands, described
in Sections 4.11.6 and 4.11.7. Be aware, though, that there is no way
to protect your files from privileged users, because they can change
the protection code for any file.
You can display the protection for any file with the SHOW PROTECTION
The DIRECTORY/FULL command also displays file protection, in
command.
the following form:
[RWED, RWED, RWED, R]
In the DIRECTORY display, the groups are not given, but are in the
same order as before, SYSTEM, OWNER, GROUP, WORLD. That is, in the
previous example, WORLD has READ privileges.
A number of DCL commands include qualifiers that help you use file
The most important is the /OWN qualifier to the COPY
protection.
command. If you don't specify otherwise, when you copy one of your
files to send it to someone else, you are the owner of the copy, even
if it isn't in your directory.
Assume you have UIC [303,5] and you
are placing a copy of a file you own in a directory called [MOONDOG],
which is owned by UIC [200,2]. You are using the following command:
$ COPY RAMP.TXT [MOONDOG]RAMP.TXT

4-11

HANDLING FILES
The file RAMP.TXT is in both directories, but its owner in both cases
is
[303,5].
The owner of [MOONDOG] has only WORLD READ access to
their copy of RAMP.TXT, as seen in this directory listing, where the
file owner is the first item on the second line of each file listing:
$ DIRECTORY/FULL RAMP.TXT, [MOONDOG]RAMP.TXT
Directory DU0:[OTHER]
3-JUN-85 15:49
RAMP.TXT;52
(7516,5)
[303,5] [RWED,RWED,RWED,R]

2./2.

23-APR-85 13:12

(14343,6)
2./2.
[RWED, RWED, RWED, R]

3-JUN-85 15:48

Total of 2./2. blocks in 1. file
Directory DU0:[MOONDOG]
3-JUN-85 15:49
RAMP.TXT;l
[303,5]

Total of 2./2. blocks in 1. file
Grand total of 4./4. blocks in 2. files in 2. directories
The /OWN qualifier to the COPY command specifies that the recipient of
the copy is the owner,
not the sender.
The following commands
illustrate this:
$ COPY/OWN RAMP.TXT [MOONDOG]RAMP.TXT
$ DIRECTORY/FULL RAMP.TXT, [MOONDOG]RAMP.TXT
Directory DU0:[OTHER]
3-JUN-85 15:50
RAMP.TXT;52
(7516,5)
[303,5] [RWED,RWED,RWED,RI

2./2.

23-APR-85 13:12

2./2.

3-JUN-85 15:49

Total of 2./2. blocks in 1. file
Directory DU0:[MOONDOG]
3-JUN-85 15:50
RAMP.TXT;2
(14343,6)
[200,2] [RWED,RWED,RWED,R]
Total of 2./2. blocks in 1. file
Grand total of 4./4. blocks in 2. files in 2. directories
You do not need the /OWN qualifier if you are copying a file from
somewhere else.
Generally, when you create a file, you own it. When
you copy a file to some other place, you are creating the file, so you
must override your default ownership with the /OWN qualifier.

4-12

HANDLING FILES
4.6.2 Directory Protection
Because a directory is a file, it has a protection code like that of 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.
The default access for directory and file protection is the protection
code the disk was mounted with. The default for mount protection is
the protection code the volume was
initialized with.
See the
discussion of CREATE/DIRECTORY in Section 4.7.2 and also Chapter 5 for
more information.
The CREATE/DIRECTORY command includes a /PROTECTION qualifier that
provides a means of overriding the default system protection. This
qualifier sets the protection for the directory file itself, not for
files in the directory.
The following example shows how to set protection on a new directory
so that no one else can even list your files:
$ CREATE/DIRECTORY/PROTECTION:(SYSTEM:,OWNER:RWED,GROUP:,WORLD:)
Device and UFD?DU1:[RAGBAG]

This example creates a directory called [RAGBAG] on the volume mounted
on device DU1:. The protection code is the protection code applied to
the actual directory file DU1:[000000]RAGBAG.DIR. The protection code
specifies that the owner (the person issuing the command) has full
access to the directory and the files in it, and that SYSTEM, GROUP,
These three groups may not list the
and WORLD have no access.
directory (no READ privilege), nor can they create files in the
directory (no WRITE and EXTEND privilege), or delete the directory (no
DELETE privilege).
That is, only the owner can do anything with the
directory.
If the directory [RAGBAG] already exists, you can limit access by
resetting the protection of the directory file with the following
command:
$ SET PROTECTION:(SYSTEM:,OWNER:RWED,GROUP:,WORLD:) [000000]RAGBAG.DIR

Remember that this command does nothing to the protection of the
files within the directory. If a sophisticated user knows
individual
the file ID numbers of your files, they're still accessible. Remember
also that although you can protect your files against SYSTEM access by
privileged users, a privileged user can still issue a SET PROTECTION
command and change the protection to SYSTEM:RWED, whereupon the
privileged user has complete access.
You can display the protection of a directory file in the same way as
any other file. The following command displays the protection for the
directory created in the previous example:
$ DIRECTORY/FULL DU1:[000000]RAGBAG.DIR

4.6.3 Volume Protection
A disk with files in RSX-11M-RLUS format on it is called a Files-11
volume.
Volume protection works in much the same way as file
protection except it affects the entire volume.

4-13

HANDLING FILES

CREATE
4.7 CREATING DIRECTORIES AND SEQUENTIAL FILES
The CREATE command without a qualifier enables you to create a
sequential file
directory at your terminal. The CREATE/DIRECTORY
command permits a user to create a directory.

4.7.1 CREATE
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 filespec
Parameter
filespec
Specifies the name of the file to be created.
As soon as the command is entered, the cursor (or print head)
The file is open for input. Any text you
moves down a line.
type goes into the file.
When you have finished entering text, press a CTRL/Z to close the
file.
If you want to create an empty sequential file, simply enter the
CTRL/Z first.
See the examples.
Examples
$ CREATE
File? COPY.CMD
;Command file to move files from Bob S.'s directory to mine
. ENABLE SUBSTITUTION
.LOOP:
. ASKS FI What file
COPY DB2:[303,26] 'FI' 'FI'
. GOTO LOOP

4-15

HANDLING FILES

CREATE (Cont.)
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
file specification, 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) has
been entered.
$ CREATE JOE.TXT
Joe called at 4:30 on Monday. He'll be back from
Switzerland on Thursday, but he won't be in the
office until Friday afternoon .
In this example, the user used CREATE to take notes on a phone call.
$ CREATE CHURCHYLA.FEM
In this example,
later use.

the user used

CREATE to

create an

empty

file for

Notes
The function of CREATE differs slightly in batch jobs.
See the
RSX-11M/M-PLUS Batch and Queue Operations Manual for more 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
creates a file with the version number you give.

the file,

the system

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

HANDLING FILES

CREATE/DIRECTORY (Cont.)
Command Qualifiers
/ALLOCATION:n
Specifies the number of directory entries (file names) for which
space is to be initially allocated. The value n is rounded up to
the next multiple of 32.
The default is /ALLOCATION:32.
/LABEL:volumelabel
Specifies that the volume label that you supply be compared with
the label on the volume. If the names match, a directory can be
allocated.
If they do not match, the command is rejected.
If you do
checked.

not

specify

this qualifier, the volume label is not

/NOWARNINGS
Suppresses error messages resulting from the command.
/OWNER_UIC: [uic]
Specifies the User Identification Code (UIC) of the directory's
owner. A UIC establishes the protection status of the directory.
See Section 4.6.2 for more information.
The default is for the directory to be owned by you.
You can
specify any UIC as the owner. However, a nonprivileged user
cannot always create files in a directory that is owned by a UIC
different from his own.
/PROTECTION:(code)
Specifies the protection code for the directory file, not for
files in the directory.
Because 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.
The default is the protection code the disk was mounted with.
The default for mount protection is the protection code at
initialization.
The default system protection code is as follows:
/PROTECTION:(SYSTEM:RWED,OWNER:RWED,GROUP:RWED, WORLD:R)
See also Section
protection.

4.6

for

Examples
$ CREATE/DIRECTORY
Device and UFD? DU2:[REGIS]

4-18

information

on file

and volume

HANDLING FILES

CREATE/DIRECTORY (Cont.)
This example creates directory [REGIS] on the volume mounted on device
DU2:.
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 DU2:[REGIS]
This example is identical to the previous one.
$ CREATE/DIRECTORY
Device and UFD? [KIZZY]
This example creates directory [KIZZY] on the default device.
$ CREATE/DIRECTORY
Device and UFD? DY2:
This example creates a directory on the volume mounted on DY2:
the same group and member number as the default directory.

with

$ CREATE/DIRECTORY/PROTECTION:(S:RWED,O:R,G:R,W:R)
Device and UFD?DU0:[MOUSE]
This example creates directory [MOUSE] on the volume mounted on device
DU0:. The protection code is the protection code applied to the
actual file containing the directory, DU0:[000000]MOUSE.DIR. The code
in this example permits privileged users to perform all 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.6.

4-19

HANDLING FILES

DELETE/DIRECTORY
4.7.3

DELETE/DIRECTORY

DELETE/DIRECTORY deletes a directory on a Files-11 volume and removes
the directory from the volume's Master File Directory (MFD).
Privileged users can delete directories on volumes mounted on any
device.
Nonprivileged users can delete directories only on volumes
mounted on their own private (allocated) devices.
Format
DELETE/DIRECTORY
Directory?
[ddnn:] [directory]
DELETE/DIRECTORY [ddnn:][directory]
Parameters
[ddnn:] [directory]
You must specify at least the directory parameter. If you do not
specify the device, the default volume is used for the parameter.
ddnn:
Specifies the device on which the volume you want to delete the
directory is mounted. This parameter defaults to SYO:.
The volume must be a mounted, Files-11 volume.
[directory]
Specifies the name of the
parameter must be specified.

directory you

want

to delete. This

The brackets are required syntax.
Examples
$ DELETE/DIRECTORY
Directory? DU1:[TSTSYS]
This example deletes directory [TSTSYS] on the volume mounted on
device DU1:.
Nonprivileged users can delete directories only on
volumes mounted on a device they have allocated. Privileged users can
delete directories on volumes mounted on any device.
$ DELETE/DIRECTORY DU1:[TSTSYS]
This example is identical to the previous one.
$ DELETE/DIRECTORY [EXTRAI]
This example deletes directory [EXTRAI] on the default device.

4-20

HANDLING FILES

EDIT/EDT (Cont.)
specified a name for the journal file other than infile.JOU, you
must include the /JOURNAL qualifier with the appropriate file
specification.
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
[EOB]
This example shows the EDIT command in its simplest form.
HORNBLOW.TXT is created during the editing session.

The

file

$ 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 file as input and edits it
to create a new file.
$ EDIT/COMMAND:FORMAT RAMBLE.RNO
Input file does not exist
[EOB]
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 the next example.
$ EDIT/COMMAND:FORMAT/RECOVER 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
running,
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 example. All the editing
commands and text entered during the session have been recorded in the
file RAMBLE.JOU,
which is also read back in by EDT. The result is
that the entire editing session is repeated up to within a few
keystrokes of the crash.
If you want 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 the recovery or your previous editing session.

4-24

HANDLING FILES

EDIT/SLP (Cont.)
Examples
$ EDIT/EDI CHILI.MAC;2
[00066 LINES READ IN]
[PAGE 1]

This example invokes EDI and names an existing input file.
$EDIT/SOS HARRY.MAC;5
Edit:DB0:[7,7]HARRY.MAC:5
This example invokes SOS for a file that already exists.
$ EDIT/SOSLONNNY.MAC
Input: DB0:[7,7]LONNNY.MAC;1
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
editor does all the checking.

parameter

is performed by DCL.

The

The unsupported editors SOS and TECO are found on many RSX-11M-PLUS
systems.
Commands to access these editors are included only for the
convenience of users. No support is implied.

4.8 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
You should not keep files that you do not need.
important resource.

4-30

HANDLING FILES

DIRECTORY (Cont.)
/TODAY
Specifies that you want the DIRECTORY command to list only files
created on the same day the command is being issued.
/EXCLUDE:filespec
Specifies that you want the DIRECTORY command not to list certain
files.
The filespec argument to /EXCLUDE can contain either a
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or *.*;2) if you want to exclude multiple
files.
However,
the version number must be given, either
explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
/REWIND
Causes the tape to rewind before starting the operation.
qualifier is for magnetic tapes only.
Examples
$ DIRECTORY
Directory DU0:[DOCDAD]
1-JUN-85 14:16
A.A;1
ANIML.BAS;1
AZ.CMD;5
BYE.CMD;1
CLEAN.CMD;1
DUN.CMD;4
EDT.CMD;22
LOX.CMD;1
LOGIN.CMD;6
TI.CMD;4

1.
6.
1.
1.
1.
1.
1.
1.
1.
1.

F.TSK;1
G.TSK;1
PONG.TSK;2
BUZZ.TXT;2
IZZY.TXT;1
JIVE.TXT;1

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

25-SEP-8412:29
24-MAR-8517:59
02-APR-8513:03
25-SEP-8412:29
10-JAN-8508:29
23-JAN-8508:05
07-NOV-8415:56
27-APR-8510:21
06-APR-8515:56
30-APR-8508:36

C
C
C

25-SEP-8412:30
25-SEP-8412:30
25-SEP-8412:31
12-MAR-8509:13
06-MAR-8514:33
16-NOV-8413:23

Total of 2906./3043. blocks in 160. files
This example shows a directory listing in the standard format.

4-34

This

HANDLING FILES

DIRECTORY (Cont.)
The device and directory are named at the head of the listing, along
the time.
All files in the directory are listed
with the date and
The files
because the user did not supply any file specifications.
in column three are contiguous files, in this case,
shown with a C
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.9.4 for information on the
UNLOCK command.
$ DIRECTORY/SUMMARY
Storage used/allocated for Directory DU0:[DOCDAD]
1-JUN-85 14:15
Total of 2892./3033. blocks in 160. files
This example displays the output produced by the /SUMMARY qualifier.
If the user had supplied one or more file specifications in the
command, the summary would cover the blocks used and allocated for the
specified files only.
$ DIRECTORY/FREE
DU0: has 12077. blocks free, 9523. blocks used out of 21600.
Largest contiguous space = 10610. blocks
3702. file headers are free, 298. headers used out of 4000.
This example displays information about the default device.
$ DIRECTORY/FREE LB0:
DUO: has 12077. blocks free, 9523. blocks used out of 21600.
Largest contiguous space = 10610. blocks
3702. file headers are free, 298. headers used out of 4000.
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
Directory DU1:[DOCDAD]
1-MAY-85 14:17
TI.CMD;4

30-APR-85 08:36

Total of 1./5. blocks in 1. file
This example displays information on the most recent version of the
See the next example.
file named.

4-35

HANDLING FILES

DIRECTORY (Cont.)
$ DIR TI.CMD;*
Directory DU1:[DOCDAD]
1-MAY-85 14:17
TI.CMD;4
TI.CMD;3
TI.CMD;2
TI.CMD;1

1.
1.
1.
1.

30-APR-85
27-APR-85
27-APR-85
27-APR-85

08:36
16:32
16:29
16:28

Total of 4./20. 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.CMD
Directory DU0:[DOCDAD]
1-MAY-85 14:17
TI.CMD;4
08:36
[303,5]

(300,56)
[RWED,RWED,RWED,R]

1./5.

30-APR-85

03-MAY-85 09:58(2.)

Total of 1./5. 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, and the second is the sequence number of
the file. The UIC is the UIC of the owner, the protection status of
the file, and the final column on the second row is the last revision
date and revision level. The revision date is the date the file was
last manipulated without a
new version being created (for example,
appending one file onto another). See the notes at the end of this
section.
Protection status is listed in the order of system, owner, group,
world.
See Section 4.6 for an explanation of protection status and
how it can be altered.
$ DIRECTORY/BRIEF *.CMD
Directory DU1:[DOCDAD]
ADV.CMD;2
AZ.CMD; 5
BYE.CMD;1
CLEAN.CMD;1
DAY.CMD;1
DTC.CMD;1
DUN.CMD;4
EDT.CMD;22
LOX.CMD;1
VTK.CMD;1
TI.CMD;4

4-36

HANDLING FILES

DIRECTORY (Cont.)
This example displays brief information on the most recent version of
all files of the type .CMD in the default directory.
$ DIRECTORY/TODAY
Directory DU2:[DONNAX]
5-JUN-85 13:44
Day of 5-JUN-85
2051CH4.MEM;1
NEWINSDC3.TXT;7
2051CH4.MEM;2
FUT.MAI;1
NEWINSDC3.TXT;6
NEWINSDC3.TXT;10
NEWINSDC4.TXT;3
FRK.CMD;6
NEWINSDC4.TXT;4
LOG.LOG;1

339.
10.
320.
1.
9.
10.
7.
1.
11.
0.

05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85

Total of 708./736

blocks in 11. files

10:11
10:05
10:12
13:05
09:55
10:39
11:46
13:43
13:43
13:43

In this example, the user asked for a directory of all files created
the same day the command was issued. Note that the directory listing
includes the date. See the next example.
$ DIRECTORY/TODAY/EXCLUDE:*.TXT;*
Directory DU2:[OLDTIM]
5-JUN-85 13:45
*.TXT;* excluded
Day of 5-JUN-85
2051CH4.MEM;1
339.
320.
2051CH4.MEM;2
FUT.MAI;1
1.
FRK.CMD;6
1.
LOG.LOG;1
2.

05-JUN-85
05-JUN-85
05-JUN-85
05-JUN-85
05-JUn-85

10:11
10:12
13:05
13:43
13:43

Total of 672./693. blocks in 6. files
In this example, the user listed all files created the day the command
Note that
file type.
issued but excluded all files with the .TXT
was
has a wildcard version number.
the filespec argument to /EXCLUDE
Observe also that the exclusion is noted in the heading of the
directory listing.
$ DIRECTORY/ATTRIBUTES YACHT.SEQ
SEQUENTIAL
FILE ORGANIZATION:
SY:[303,5]YACHT.SEQ;1
REVISED: 15-JUN-1985 08:19 (5)
CREATED; 25-MAY-1985 12:32
[RWED,RWED,RWED,R]
FILE PROTECTION:
VARIABLE
RECORD FORMAT:
CARRIAGE RETURN
RECORD ATTRIBUTES:
FILE ATTRIBUTES:
EXTEND QUANTITY =0
ALLOCATION=10

4-37

HANDLING FILES

DIRECTORY (Cont.)
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.
$ DIR *.TSK, [ELBODGO]*.TXT
Directory DU1:[LAWRENCEP]
20-MAY-85 09:39
CLOCK.TSK;3
F.TSK;l
G.TSK;1
TICTAC.TSK;4
TREK.TSK;1

8.
4.
4.
19.
54.

C
C
C
C
C

15-APR-85
25-MAR-85
25-MAR-85
01-APR-85
25-MAR-85

08:55
12:30
12:30
12:07
12:31

Total of 89./89. blocks in 5.
Directory DU1:[ELBODGO]
20-MAY-85 09:39

files

FRONT.TXT;1
EDITNEWS.TXT;12
OZY.TXT;3
TEXT.TXT;1
NEW.TXT;l
AWARE.TXT;2
IZZY.TXT;10

16-MAY-85 11:23
11-MAY-85 10:50
11-MAY-85 10:50
11-MAY-85 10:50
27-APR-85 14:36
27-APR-85 13:48
12-MAY-85 13:42

3.
25.
2.
151.
0.
2.
2.

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 directory of [LAWRENCEP]
requested directory information files in two directories. The default
directory is applied to the first files named,. the *.TSK files; these
are listed
first in the display. The second set of files displayed,
the *.TXT files, are from directory [ELBODGO], which was explicitly
specified in the command. Note the locked file. Compare this example
with the next one.
$ DIR [ELBODGO]*.TXT, *.TSK
Directory DU1:[ELBODGO]
20-MAY-85 09:40
FRONT.TXT;1
EDITNEWS.TXT;12
OZY.TXT;3
TEXT.TXT;1
NEW.TXT;1
AWARE.TXT;2
IZZY.TXT;10
ADVENT.TSK;1
DUNGEON.TSK;2
PONG.TSK;2
YCLOCK.TSK;6
STAR.TSK;2
TICTAC.TSK;5
VTCHS.TSK;12
XCLOCK.TSK;6
LIFE.TSK.10

3.
25.
2.
151.
0.
2.
2.
151.
242.
12.
9.
102.
19.
26.
9.
4.

C
C
C
C

16-MAY-85 11:23
11-MAY-85 10:50
11-MAY-85 10:50
11-MAY-85 10:50
27-APR-85 14:36
27-APR-85 13:48
12-MAY-85 13:42
13-MAY-85 14:12
11-MAY-85 09:08
13-MAY-85 14:13
08-APR-85 12:17

C
C

13-APR=85 09:07
01-APR-85 11:31

C
C
C

06-MAY-85 15:39
03-MAY-85 16:48
03-APR-85 13:28

Total of 758./780. blocks in 16. files
4-38

HANDLING FILES

DELETE (Cont.)
Examples
$ DELETE
File(s)? *.DAT;
This example deletes all versions of all files of the type .DAT.
$ DELETE FILE.FIL;1, ;3, .TXT;5
This example deletes versions 1 and 3 of FILE.FIL, and version 5 of
Note that no file name or type is specified for version 3,
FILE.TXT.
and no name for .TXT;5. This form requires user confidence.
$ DELETE/QUERY
File(s)?*.TMP;*
Delete file DU1:[KATHYED]OGRE.TMP
Delete file DU1:[KATHYED]TROLL.TMP;1
Delete file DU1:[KATHYED]ORC.TMP;1
Delete file DU1:[KATHYED]ELF.TMP;1
Delete file DU1:[KATHYED]HOBBIT.TMP;1
Delete file DU1:[KATHYED]SNIPE.TMP;1

[Y/N/G/Q]? Y
[Y/N/G/Q]? Y
[Y/N/G/Q]? Y
[Y/N/G/Q]? N
[Y/N/G/Q]? N
[Y/N/G/Q]? G

The following files have been deleted:
DU1:[KATHYED]SNIPE.TMP;1
DU1:[KATHYED]SNOPE.TMP;2
In this example, the user specified all files having the type TMP in
Three files were deleted at the user's choice,
the DELETE command.
and two were retained. The user then directed that all remaining
which
files with the type TMP be deleted. There were two more files,
were deleted and listed.
$ DELETE *.DOC
DU0:[ANNEDIT]WITCH.DOC;2
Delete file
DU0:[ANNEDIT]DRY.DOC;4
Delete file
Delete file
DU0:[ANNEDIT]PAYCHECK.DOC;1
Delete file
DU0:[ANNEDIT]LOADING.DOC;3
DU0:[ANNEDIT]LOADING.DOC;4
Delete file
Delete file
DU0:[ANNEDIT]LOADING.DOC;5
Delete file
DU0:[ANNEDIT]LOADING.DOC;6

[Y/N/G/Q]? Y
[Y/N/G/Q]? N
[Y/N/G/Q]? Y
[Y/N/G/Q]? Y
[Y/N/G/Q]? Y
[Y/N/G/Q]? Y
[Y/N/G/Q]? N

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.
$ DELETE/LOG *.LST;*
The following files have been deleted:
DU1:[JIMPAR]RANGER.LST;1
DU1:[JIMPAR]TONTO.LST;1
DUl:[JIMPAR]REID.LST;1
DU1:[JIMPAR]SILVER.LST;1
DU1:[JIMPAR]SCOUT.LST;1
DUl:[JIMPAR]HORNET.LST;1
DU1:[JIMPAR]KATO.LST;1
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.

4-42

HANDLING FILES

PURGE (Cont.)
If more than one file specification is given with the /KEEP
qualifier, all but the latest n versions of all files listed are
deleted.
/DATE:dd-mmm-yy
Specifies that you want the PURGE command to affect only files
created on the date given.
/SINCE:dd-mmm-yy
Specifies that you want the PURGE command to affect only files
created on or since the date given.
/THROUGH:dd-mmm-yy
Specifies that you want the PURGE command to affect only files
created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want the PURGE command to affect only files
created within that range.
/TODAY
Specifies that you want the PURGE command to affect only files
created on the same day the command is being issued.
/EXCLUDE:filespec
Specifies that' you do not want the PURGE command to not affect
certain files.
The filespec argument to /EXCLUDE can contain
either a single file specification (for example, TEST.DAT;2) or
wildcards in all but one of the file specification fields (for
example, *.DAT;*, TEST.*;*, or *.*;2), if you want to exclude
However,
the version number must be given,
multiple files.
either explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
Examples
$ PURGE
File(s)? TEMPER.TSK
In this
deleted.

example,

all

versions

4-45

TEMPER.TSK

but

the

latest

are

HANDLING FILES

PURGE (Cont.)
$ DIRECTORY ASDIC.TM1:*, ELPASO.TEX;*
Directory DU1:[BRUCEW]
20-JUN-85 13:44
ASDIC.TM1;1
ASDIC.TM1;2
ASDIC.TM1;3
ASDIC.TM1;4
ASDIC.TM1;5
ELPASO.TEX;1
ELPASO.TEX;2
ELPASO.TEX;3
ELPASO.TEX;5
ELPASO.TEX;6

1.
1.
1.
0.
1.
1.
1.
1.
1.
1.

20-JUN-85 13:41
20-JUN-85 13:41
20-JUN-85 13:41
20-JUN-85 13:41
20-JUN-85 13:42
20-JUN-85 13:42
20-JUN-85 13:42
20-JUN-85 13:42
20-JUN-85 13:43
20-JUN-85 13:43

Total of 9./45. blocks in 10. files
$ PURGE/LOG/KEEP:3 ASDIC.TM1
The following files have been deleted:
DUO:[GLENN]ASDIC.TM1:1
DUO: [GLENN] ASDIC.TM1;2
$ PURGE/LOG/KEEP:3 ELPASO.TEX
The following files have been deleted:
DU0:[GLENN]ELPASO.TEX;1
DU0:[GLENN]ELPASO.TEX;2
DU0:[GLENN]ELPASO.TEX;3
$ DIRECTORY ASDIC.TM1;*, ELPASO.TEX;*
Directory DU0:[GLENN]
20-JUN-85 13:46
ASDIC.TM1;3
ASDIC.TM1;4
ASDIC.TM1;5
ELPASO.TEX;5
ELPASO.TEX;6

1.
0.
1.
1.
1.

20-JUN-85 13:41
20-JUN-85 13:41
20-JUN-85 13:42
20-JUN-85 13:43
20-JUN-85 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.TM1 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.TM1 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.
Because there was
none, the PURGE command task exited, its work done.
Notes
You can purge any file to which you have DELETE access.

4-46

HANDLING FILES

COPY (Cont.)
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want the COPY command to affect only files
created within that range.
/TODAY
Specifies that you want the COPY command to affect only files
created on the same day the command is being issued.
/EXCLUDE:filespec
Specifies that you want the COPY command not to affect certain
files.
The filespec argument to /EXCLUDE can contain either a
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or * . * ;2), if you want to exclude multiple
files.
However,
the version number must be given, either
explicitly or with a wildcard (*).
Examples
$ COPY
From? [KILIKI]TSKBLD.CMD
To? TSKBLD.CMD
This example copies TSKBLD.CMD from [KILIKI] to the current directory
and device.
The file is still owned by the source UIC.
$ COPY *.BAS DUl:
This example copies all files with the file type BAS from the current
device and directory to the same directory on the volume mounted on
device DU1:.
$ COPY/OWN TSKBLD.CMD

[MONGO]BLDFIL.CMD

This example copies TSKBLD.CMD from the current directory and device
to [MONGO], assigns ownership to the destination UIC, and also changes
the file's name to BLDFIL.CMD.
$ COPY/CONTIGUOUS LITTER.DAT *.*
This example creates a new version of the file LITTER.DAT.
version is contiguous.

The

new

$ COPY OLD1.FIL,OLD2.FIL
To? NEW.ONE
This example copies two previously existing files into one new file.

4-50

HANDLING FILES

COPY (Cont.)
$ COPY CHARLA.DMP TT4:
This is a
This example prints a copy of CHARLA.DMP on TT4:.
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 same contents as
FLY.TXT, both on the current device and directory.
Notes
C is the short form of copy.
COPY does not affect file organization. If you want to change file
organization, use the CONVERT command, Section 4.8.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 directories with the same
Thus, you can copy from many places that you cannot
group number.
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
single file as you copy it.

the name,

4-51

type, and version

number of a

HANDLING FILES

RENAME (Cont.)
/SINCE:dd-mmm-yy
Specifies that you want the RENAME command to affect only files
created on or since the date given.
/THROUGH:dd-mmm-yy
Specifies that you want the RENAME command to affect only files
created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want the RENAME command to affect only files
created within that range.
/TODAY
Specifies that you want the RENAME command to affect only files
created on the same day the command is being issued.
/EXCLUDE:filespec
Specifies that you want the RENAME command not to affect certain
files.
The filespec argument to /EXCLUDE can contain either a
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or *.*;2), if you want to exclude multiple
either
files.
However,
the version number must be given,
explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
Examples
$ RENAME
Old file name? INTRO.TXT
New file name? APPENDIX.TXT
In this example,
APPENDIX.TXT;1.

the

most

recent

version

of INTRO.TXT becomes

$ RENAME IZZY.TXT;4 FIZZY.*
In this example, IZZY.TXT;4 becomes FIZZY.TXT;1. Other
IZZY.TXT are not affected.

versions

$ RENAME AMA.DOC;4 *.*;11
In this example, AMA.DOC;4 becomes AMA.DOC;11.
$ RENAME MAIN.TSK;* EXTRA.TSK
The
In this example, all files named MAIN.TSK are renamed EXTRA.TSK.
version numbers remain the same, regardless of sequence and order of
file creation.
$ RENAME MAIN.TSK;* SUB.*
4-53

HANDLING FILES

RENAME (Cont.)
In this example, all versions of MAIN.TSK are renamed SUB.TSK.
Versions are in the order of creation, with numbers unchanged.
$ REN EXHAUST.*;* REFRESH.*
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
yourself.

also

tricky.

4-54

Experiment

before

committing

HANDLING FILES

CONVERT (Cont.)
/[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.BAR
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.
$ 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:1 SAND.BAR MAX.BAR
RMSCNV reads
the
indexed input file SAND BAR,
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

4-60

HANDLING FILES

CONVERT (Cont.)
file
RMSCNV reads fixed-length records from the indexed input
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 SIZE:1024/APPEND/KEY:9 BRER.BAR
Output file? MM3:BRER.BCK
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
more
information.
RMS and FCS sequential files are compatible. Sequential files created
by FCS can be input files for CONVERT, and sequential files created by
CONVERT can be read by FCS.

4.9

OTHER FILE-RELATED COMMANDS

The commands in this section perform varied actions on your files.
These commands are as follows:
TYPE

Displays files on your terminal

Prints files on the system line printer

APPEND

Alters the contents of certain files

DIFFERENCE

Displays the differences between two files

UNLOCK

Unlocks locked files

4-61

HANDLING FILES

TYPE (Cont.)
/THROUGH:dd-mmm-yy
Specifies that you want the TYPE command to affect only files
created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want the TYPE
created within that range.

command to

affect only

files

/TODAY
Specifies that you want the TYPE command to affect
created on the same day the command is being issued.

only files

/EXCLUDE:filespec
Specifies that you want the TYPE command not to affect certain
can contain either a
files. The filespec argument to /EXCLUDE
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or *.*;2) if you want to exclude multiple
either
files.
However,
the version number must be given,
explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
/SHARED
Specifies that you want other users to be able to access the file
while you are typing it.
Examples
$ TYPE
File(s)? LOGIN.CMD
. ENABLE QUIET
.IF <CLI$ EQ "MCR" SET /DCL=TI:
SET TERMINAL/INQUIRE
ASSIGN DB1: SY0:
@AZ
This example prints the file LOGIN.CMD from the
directory on your terminal.

current

device and

current

device

$ TYP [DALE]LOGI N. CMD
TYPE LOGIN.TXT
SET TERMINAL/INQUIRE
This example prints the file LOGIN.CMD from
directory [DALE] on your terminal.

4-63

the

and

HANDLING FILES

TYPE (Cont.)
$ TYPE [*] *.FIL;*
This is the beginning of a file named ARTHUR.FIL.
It goes 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 and is called Z.FIL.
And some more.

At last, we reach the beginning of a file named FILLIE.FIL.
Again, some more text and then
The last two lines of FILLIE.FIL.
$
ZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
This example prints on your terminal all versions of all files having
the type .FIL
located on the current device.
Notes
In general, RSX-11M-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 display any file using TYPE, but normally only ASCII text
files are readable.

4-64

HANDLING FILES

APPEND (Cont.)
/SINCE:dd-mmm-yy
Specifies that you want the APPEND command to affect only files
created on or since the date given.
/THROUGH:dd-mmm-yy
Specifies that you want the APPEND command to affect only files
created on or before the date given.
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want the APPEND command to affect only files
created within that range.
/TODAY
Specifies that you want the APPEND command to affect only files
created on the same day the command is being used.
/EXCLUDE:filespec
Specifies that you want the APPEND command not to affect certain
files.
The filespec argument to /EXCLUDE can contain either a
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or * . *;2), if you want to exclude multiple
files.
However,
the version number must be given, either
explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
/REWIND
Causes the tape to rewind before starting the operation.
qualifier is for magnetic tapes only.

This

/SHARED
Specifies that you want others to be
while your append operation is underway.

able

access the file

Examples
$ APPEND
File(s)? BIRD.DOG;*
To? JOKER.TXT
This example appends copies of all versions of BIRD.DOG in order to
the end of the most recent version of JOKER.TXT.
$ APPEND *.LST LIST.FIL
This example appends copies of most
the type .LST to LIST.FIL. Appended
are listed in the directory.

4-66

recent versions of all files of
files appear in the order they

HANDLING FILES

DIFFERENCES (Cont.)
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:[303,5]TOM.MAC;1)
2
.IDENT "01"
4
.MCALL ALUN$C, QIOW$C, EXST$C
6
STRING:
.ASCII
"This is a simple MACRO-11 program."

DB2:[303,5]TOM.MAC;2)
2
.IDENT "02"
4
.MCALL ALUN$C, QIOW$C, EXST$S
6
STRING:
.ASCII
"This is a simple MACRO-11 program."
1 differences found
TI:/-BL/-FF/-CB=TOM.MAC;1,TOM.MAC;2
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 the following:
/IGNORE:(BLANK_LINES,FORM_FEEDS)
to reproduce the defaults of CMP, the File Compare utility, which the
DIFFERENCES command invokes.
The listing of differences between the two files starts with the IDENT
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 is
command line equivalent to the DIFFERENCES command.
$ DIFFERENCES TOM.MAC;1 TOM.MAC;2
1)
2
3
4
5
2)
2
3
4
5

DB2:[303,5]TOM.MAC;1
.IDENT "01"
.MCALL ALUN$C, QIOW$C, EXST$C
DB2:[303,5]TOM.MAC;2
.IDENT "02"
.MCALL

ALUN$C, QIOW$C, EXST$S

1 differences found
TI:/BL/FF/-CB=TOM.MAC;1,TOM.MAC;2

4-71

the CMP

HANDLING FILES

DIFFERENCES (Cont.)
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:(BLANK_LINES,FORM_FEEDS) TOM.MAC;1 TOM.MAC;2
1
.TITLE WRITE PRINT A PREDEFINED MESSAGE ON THE USER TERMINAL
2 !
.IDENT
"02"
.MCALL ALUN$C, QIOW$C, EXST$S
4 !
6 !
STRING: .ASCII
"This is a simple MACRO-11 program."
7
LENGTH =
.-STRING
; CALCULATE THE STRING LENGTH
8
.EVEN
10
START: ALUN$C 1,TI,0
; ASSIGN THE LUN TO USE THE TERMINAL
11
QIOW$C IO.WVB,1,1,,,, <STRING,LENGTH,40>
; PRINT THE STRING
12
13
EXST$C EX$SUC
; SUCCESSFUL EXIT IN ALL CASES
START
; SETUP THE STARTING ADDRESS
15
END
1 differences found
TI:/-BL/-FF/CB/VB::041=TOM.MAC;1,TOM.MAC;2

The
This example shows the effect of the
/CHANGE BAR qualifier.
second file is printed on the terminal with exclamation points next to
the numbers of the changed lines.
$ DIFFERENCES/IGNORE:(BLANK LINES) TOM.MAC;1 TOM.MAC;3

1)
2
4

DB2:[303,5]TOM.MAC;1
.IDENT "01"
.MCALL ALUN$C, QIOW$C, EXST$C

2)
2
4

DB2:[303,5]TOM.MAC;3
.IDENT "03"
.MCALL ALUN$C, QIOW$C, EXST$C

1 differences found
TI:/-BL/FF/-CB=TOM.MAC;1,TOM.MAC;3

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 IDENT 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)
2
3

DB2:[303,5]TOM.MAC;l
.IDENT "01"

2)
2
3

DB2:[303,5]TOM.MAC;3
.IDENT
"03"

1)
7

DB2:[303,5]TOM.MAC;1
LENGTH =
.-STRING

2)
7
8

DB2:[303,5]TOM.MAC;3
LENGTH

.-STRING

4-72

; CALCULATE THE STRING LENGTH

HANDLING FILES

UNLOCK (Cont.)
/EXCLUDE:filespec
Specifies that you want the UNLOCK command not to affect certain
The filespec argument to /EXCLUDE can contain either a
files.
single file specification (for example, TEST.DAT;2) or wildcards
in all but one of the file specification fields (for example,
*.DAT;*, TEST.*;*, or *.*;2), if you want to exclude multiple
either
files.
However, the
version number must be given,
explicitly or with a wildcard (*).
/NOWARNINGS
Suppresses error messages resulting from the command.
Example
$ Directory TOPEKA.KAN
Directory DU0:[PBEZ]
5-JUL-85 13:13
ELIOT.MAN;3

32.

25-JUN-85

12:29

Total of 32./40. blocks in 1. files
$ UNLOCK TOPEKA.KAN
$ DIRECTORY TOPEKA.KAN
Directory DU0:[PBEZ]
13:14
5-JUL-85
TOPEKA.KAN;3

32.

25-JUN-85

12:29

Total of 32./40. blocks in 1. 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
issues the UNLOCK command, the file is no
listing.
After
the user
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.10 PRINT AND QUEUE MANAGER COMMANDS
The following section describes the PRINT command as well as all the
nonprivileged Queue Manager commands.

4-75

HANDLING FILES

PRINT (Cont. )
/[NO]DELETE
Overrides the /[NO]DELETE command qualifier when
particular file specification.

to a

attached

/[NO]TRANSFER
Overrides the /[NO]TRANSFER command qualifier when attached to a
particular file specification.
Examples
$ PRINT
File(s)? PASHA.CMD
PRI -- Job 305, name "PASHA

", submitted to queue "PRINT "

This example prints the most recent version of PASHA.CMD from the
default device and directory on the line printer. The Queue Manager
returns a message confirming that the job has been submitted and given
an entry number. You can use this entry number in QMG commands. See
the next section.
$ PRINT/COPIES:20
File(s) ?PASHA.CMD
PRI -- Job 706, name "PASHA

", submitted to queue "PRINT "

They
This example prints 20 copies of PASHA.CMD.
end-to-end with no flag page except at the beginning.

are

printed

$ PRI/COP:20/FLAG_PAGE PASHA.CMD
", submitted to queue "PRINT "
PRI -- Job 321, name "PASHA
This example prints 20 copies of PASHA.CMD, each with a flag page.
$ PRIN/COPIES:2 DAVID.TXT, DAN.TXT
PRI -- Job 18, name "DAVID
", submitted to queue "PRINT "
This example prints two copies of DAVID.TXT followed by two copies of
It does not print two sets of one copy of each file. If you
DAN.TXT.
want to print sets of files, see the next example.
$ PRINT/JOB COUNT:2 DAVID.TXT,DAN.TXT
", submitted to queue "PRINT "
NAME "DAVID
PRI -- JOB 311,
This example prints a set consisting of a copy of DAVID.TXT followed
and then prints another set of DAVID.TXT
by a copy of DAN.TXT,
followed by DAN.TXT.
$ PRI/FLAG PASHA.CMD,RAJAH.CMD,SHEIK.CMD
", submitted to queue "PRINT "
PRI -- Job 999, name "PASHA
This example prints
page.

one copy

of each

file,

each with its own flag

$ PRI/NAME:ARABY/FLAG PASHA.CMD, RAJAH.CMD, SHEIK.CMD
", submitted to queue "PRINT
PRI -- Job 805, NAME "ARABY

This example prints one copy of each file, 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.

4-83

HANDLING FILES

PRINT (Cont.)
$ PRINT/LENGTH:60 GLADRAG.MAC
PRI -- Job 22, name "GLADRAG

", submitted to queue "PRINT "

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.
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.COR, RIFF.COR, RAB.COR/COP:19, PROXOR
PRI -- Job 77, name "MOB
", submitted to queue "PRINT "
This example prints 20 copies each of MOB.COR, and RIFF.COR, 19 copies
of RAB.COR, and then 20 copies of PROXOR.
$ PRI/DELETE LASER.TST, PHASER.TST, RAZOR.TST/NODELE
PRI -- Job 406, name "LASER
", submitted to queue "PRINT "
This example prints the three files and deletes the first two from the
current directory.
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-84 13:13) CONST.CON
PRI -- Job 809, name "CONST
", submitted to queue "PRINT
This example blocks the job in its queue until the specified date and
time.
The file
itself remains in its directory. Deleting the file
from its directory does not take it out of the queue, but does prevent
it from being printed.
$ PRI/AFTER:(17:00) GUNGA.DIN
PRI -- Job 765, name "GUNGA

", submitted to queue "PRINT

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 percent wildcard (%).
The
asterisk wildcard
(*)
can only be used to substitute for a complete
part of the file specification and not for part of a file name or file
type as some commands do.
PRINT is to print jobs as SUBMIT is to batch jobs. The PRINT command
defines QMG print jobs.

4-84

HANDLING FILES

DELETE (Cont.)
Examples
$ DELETE/ENTRY:301
This command deletes the job from the queue by referencing the job's
unique entry number (in this example, job number 301). Jobs may share
the same job name but never the same job entry number.
When you
delete a job by its entry number, you are deleting that particular job
with greater confidence. It is possible to delete the wrong job when
a
job is
referenced by its job name. Deleting a job by its unique
entry number protects you from such mistakes.
$ DELETE/JOB LP0 ANGEL
This command deletes the job ANGEL by first referencing
queue, LP0, and then deleting the job ANGEL from LP0.

the

job's

$ DELETE/ENTRY:301/FILE_POSITION:2
This example deletes only the second file appearing in job 301.
You
may only refer to the file you want to delete by the file's position
in the print job (the numbered order in which you entered the file
specification).
You cannot specify the file you want to delete by
referring to its file specification.
Notes
Associating a particular file specification with the numbered order in
which
it was entered into a queue can be accomplished by entering a
SHOW QUEUE command, and examining the output on your terminal.
You
Using the /ENTRY:nnn qualifier to delete a job saves keystrokes.
are also deleting a job with greater confidence. Remember, a job may
share a job name but never a job entry number. If, for example, you
decided
to delete a job by referring to the job name, and you have
several jobs sharing the job name, you would succeed in deleting only
the first occurrence of the job and not necessarily the job that you
wanted to delete.
DELETE/QUEUE works on all categories of jobs in any queue.
You can
delete ACTIVE jobs, WAITING jobs, TIME-BLOCKED jobs, or HELD jobs.
There can be more than one job with the same name from the same UIC.
The DELETE/QUEUE command will delete the first job of a given name in
the queue.

4-87

HANDLING FILES

SHOW QUEUE (Cont.)
/ENTRY:nnn
Limits information to a particular
job's unique entry number.

job entry

referenced by the

/FORMS[:n]
Limits information to jobs that are to be printed on a specified
form.
If n is omitted, the display shows all jobs that are other
than Form 0.
/NAME:jobname
Limits information to jobs with the specified jobname.
/OWNER UIC:uic
Limits information to jobs owned by the specified UIC.
/PRINT
Limits information to print queues. This qualifier produces the
same information as the /DEVICE qualifier.
/BATCH
Limits information to batch queues.
Examples
The following examples show the three different output displays (FULL,
FILE, BRIEF):
$SHOW QUEUE/FULL
** PRINT QUEUES **
PRINT => LP0 (LP1)
[7,25] ANGEL
ENTRY:22
FORM:0
ACTIVE ON LP0
PRI:50 LENTO PAGE:0 NORESTART FLAG:JOB NOLOWER COP:1
> 1 DU0:[GREGG]ANGEL.LST;1
COP:1
NODELETE
[7,40] ANITA
ENTRY:24
FORM:0
PRI:50 LEN:0 PAGE:0 NORESTART FLAG:JOB NOLOWER COP:1
1 DU0:[LAKE]ANITA.MEM;120
COP:1
NODELETE
LP0
=> LP0
LP1
=> (LP1)
** BATCH QUEUES **
BATCH => BAP0
[7,40] MJRA
ENTRY:23
ACTIVE ON BAP0
PRI:50 NORESTART LOG PRINT:PRINT
> 1 DU0:[7,40]MJRA.BAT;1
NODELETE
This display shows all information about the queues and jobs in
queues.
In this example, the Queue PRINT can send jobs to LP0 or LP1.
LP1 has been stopped by the System Manager and is therefore not
eligible to accept jobs.
( This is indicated by the processor name
enclosed in parentheses.)

4-89

HANDLING FILES

SHOW QUEUE (Cont.)
There are two files to be printed in the Queue PRINT:
[7,25]ANGEL.LST,
printed on LP0

entry

[7,40]ANITA.MEM,
printed

entry number 24,

The batch job [7,40] MJRA,
processor BAP0.

number 22,

entry

which is

currently being

which

waiting

number 23,

running

batch

The attributes of the job are indicated in the display, and the files
The angle bracket (>)
that make up each job are also listed.
indicates which file of a job is currently being processed.
$ SHOW QUEUE
** PRINT QUEUES **
PRINT => LP0 (LP1)
[7,25] ANGEL
ENTRY:22
> 1 DU0:[GREGG]ANGEL.LST;1
[7,40] ANITA
ENTRY:24
1 DU0:[LAKE]ANITA.MEM;120
LP0
=>
=>LP0
LP0
LP1
=> (LP1)
** BATCH QUEUES **
BATCH =>BAP0
[7,40] MJRA
ENTRY:23
> 1 DU0:[7,40]MJRA.BAT;1

ACTIVE ON LP0

ACTIVE ON BAP0

This display, the default format, shows the queues in the same state.
It does not show the attributes of the job. It only shows the form
number of the job and the attributes of the files if other than the
default values were specified.
$ SHOW QUEUE/BRIEF
** PRINT QUEUES **
PRINT => LP0 (LP1)
[7,25] ANGEL
ENTRY:22
ENTRY:24
[7,40] ANITA
LPO
=> LP0
LP1
=> (LP1)
** BATCH QUEUES **
BATCH => BAP0
ENTRY:23
[7,40]MJRA

ACTIVE ON LP0

ACTIVE ON BAP0

This display only shows the names, entry numbers, and status of the
Also, if a form other than Form 0 is specified
jobs
in the queues.
for a print job, the form will appear in the display.

4-90

HANDLING FILES

SHOW PROCESSOR
4.10.2.3

SHOW PROCESSOR

the
initialized
displays
information
about
SHOW
PROCESSOR
characteristics of spooled devices and batch processors, printers, and
other output devices under the control of the Queue Manager.
Format
SHOW PROCESSOR [processorname]
Displays
information about all processors.
processors and spooled input devices.

This

includes

batch

SHOW PROCESSOR/BATCH
Shows all batch processors.
SHOW PROCESSOR/PRINT or SHOW PROCESSOR/DEVICE
Shows all print processors.
Example
$ SHOW PROCESSOR
Information about print processors, batch
input devices is displayed at your terminal:
** SPOOLED DEVICES **
<= PRINT LP0
LP0
LOWER
FORM:0
FLAG:2
CURRENT JOB:
[CRAZED]FUP
LP1
(STOPPED) <= LP1
FORM:1
FLAG:1
NOLOWER
** BATCH PROCESSORS **
BAP0
<= BATCH

processors,

and

spooled

ENTRY:59

This example shows all information about spooled devices and batch
In this example, spooled device LP0 can receive jobs from
processors.
queues PRINT and LP0.
Spooled device LP1 has been stopped by the System Manager
therefore not eligible for receiving jobs for printing.

and

The batch processor, BAP0, can only receive jobs from the Queue BATCH.
There is no other batch processor.
LPO is currently printing job [CRAZED]FUP, entry number 59.

4-91

HANDLING FILES

SET QUEUE (Cont.)
File Qualifiers
/COPIES:n
Changes the number of copies of a file you want to have printed
within a single printing of a print job.
/[NO]DELETE
Changes the delete status of a single file contained in a print
job.
/FILE POSITION:n
Changes the operation of /COPIES:n or /[NO]DELETE as they apply
to
a
file contained in a job in queue. The number n refers to
the file position in the job. Use SHOW QUEUE to determine its
position.
Example
$ PRINT/JOBCOUNT:2 JILL.TXT,JOHN.TXT/COPIES:3
The SHOW QUEUE/FULL command output might look like this:
** PRINT QUEUES **
PRINT => (LP0)
[303,5]
JILL
PRI:50 LEN:0

ENTRY:696
FORM:0
PAGE:0 NORESTART FLAG:JOB NOLOWER COP:2
1 DUO:[DICK]JILL.TXT;1
COP:1

NODELETE
2 DU0:[DICK]JOHN.TXT;l
LP0
LP1

COP: 3

NODELETE

=> LP0
=> LP1

To print two copies of the file JOHN.TXT instead of the three copies
specified in the initial print command, you would enter the following
SET QUEUE command:
$ SET QUEUE/ENTRY:696/FILE_POSITION:2/CO:2
The SHOW QUEUE/FULL command output on your terminal would look like
this:
** PRINT QUEUES **
PRINT => (LP0)
[ 303,5] JILL ENTRY:696 FORM:0
PRI:50 LEN:O PAGE:O NORESTART
1 DU0:[DICK]JILL.TXT;1
2 DUO:[DICK]JOHN.TXT;1
LP0
=> LP0
LP1
=> LP1

FLAG:JOB
COP:1
COP : 2

NOLOWER COP:2
NODELETE
NODELETE

Note that the file in position 2, JOHN.TXT, will now have two copies
instead of three printed.

4-94

HANDLING FILES

STOP/ABORT
4.10.2.5

STOP/ABORT Command

The STOP/ABORT command stops the current job on
a
line printer
immediately.
Privileged users can stop any job. Nonprivileged users
can stop their own jobs.
Format
STOP/ABORT

printer

Parameter
printer
Specifies the line printer whose active job you want to stop.
Example
$ STOP/ABORT LP0
This command stops the currently active job on LPO:
This
deleted from the queue and the next available job is queued.

job

Notes
As soon as the active job is deleted, the Queue Manager passes the
eligible job to the processor. The processor has not been aborted or
killed, only the active job on that processor.

4-96

HANDLING FILES

RELEASE
4.10.2.7

RELEASE

RELEASE unblocks a job that has been held in queue.
Format
RELEASE/JOB queuename jobname
RELEASE/ENTRY:nnn
Examples
$ PRINT/HOLD/NAME:MARY MUSE.TXT
The SHOW QUEUE/FULL command output might look like this:
** PRINT QUEUES **
PRINT => LP0
[303,5]
MARY
ENTRY:698
FORM:0
HELD
PRI:50 LEN:0
PAGE:0 NORESTART FLAG:JOB
COP:1
> 1 DU0:[AMUSED]MUSE.TXT;1
COP:1
LP0
=> LP0
LP1
=> LP1
To unblock MUSE.TXT, you would
commands on your terminal:

type one

of the

NOLOWER
NODELETE

following RELEASE

$ RELEASE/ENTRY:698
$ RELEASE/JOB PRINT MARY
The SHOW QUEUE/FULL command output would look like this:
** PRINT QUEUES **
PRINT => LP0
[303,5]
MARY
ENTRY:698
FORM:0
PRI:50 LEN:0
PAGE:0 NORESTART
COP:1
> 1 DU0:[AMUSED]MUSE.TXT;1
LP0
=> LP0
LP1
=> LP1

ACTIVE ON LP0
FLAG:JOB NOLOWER
COP:1

NODELETE

Notes
The HELD status of the job in the previous example was first changed
to WAITING, and then, because there were no jobs in queue, became
ACTIVE.

4.11

SET AND SHOW

You can type SET commands to establish your default device, directory,
and User Identification Code, and SHOW commands to display what these
defaults are. You can change the protection code for any existing
file in your directory with the SET PROTECTION command. In addition,

4-98

HANDLING FILES

SET DEFAULT (Cont.)
Command Qualifier
/[NO]NAMED_DIRECTORY
named
or
numbered
Allows SET DEFAULT to accept
either
directories.
The
format
for a named directory is [directory],
the
where directory is one to nine of the following characters:
26 letters A through Z, and the numbers 0 through 9. Examples of
named directories include [MAG] and [1POTATO2].
The format for a numbered directory is [g,m], where g and m are
octal numbers
from 1
through
377.
Examples of numbered
directories are [100,2] and [202,10].
If you issue SET DEFAULT/NONAMED DIRECTORY, you can only specify
numbered directories in the SET DEFAULT command. Operating with
/NONAMED DIRECTORY is offered for users of other systems in the
RSX-11 family who need to maintain compatibility. This qualifier
is the default.
When you specify /NONAMED DIRECTORY, SET DEFAULT functions as it
previously did on older versions of RSX. In the old style, the
following happened:
You can no longer set your default to a named directory.
However, you can still use named directories in commands.
You refer to directories in the SET DEFAULT command using the
numbered format [g,m].
The SET DEFAULT command now changes the UIC, as well as the
default directory and device, of privileged users. In this
case, the UIC and the directory name are identical numbers.
The SET DEFAULT command with no arguments now returns the
nonprivileged user to
the login defaults and returns the
privileged user to the login device, but does not change the
default directory.
Examples
$ SET DEFAULT DU1:[MASKELYNE]
This example sets DU1: as the default device and [MASKELYNE] as the
default directory.
All subsequent commands default to this device and
directory unless you explicitly state otherwise.
$ SET DEF DU1:
$ ASSIGN DU1: SY0:
The two commands in this example are equivalent. In each case, the
When you set the default device, SET
default device becomes DU1:.
DEFAULT actually assigns SY0 (or SY0: for systems without extended
logical name support) as a logical name for the device you want. SY0
(or SY0:) is the logical name that represents your default device.

4-101

HANDLING FILES

SET DEFAULT (Cont.)
$ SHOW ASSIGNMENTS
SYS$LOGIN = DU1:[TASK]

(Login, Final, TT2: )

$ SET DEFAULT DU2:[IMAGE]
$ SHOW DEFAULT
DU2:[IMAGE]
Named
TT2:
Protection UIC:
[302,5]
$ SET DEFAULT SYS$LOGIN
$ SHOW DEFAULT
DU1:[TASK]
Named
Protection UIC: [302,5]

TT2:

This example shows the use of both explicit device and directory
specifications (DU2:[IMAGE])
and logical names (SYS$LOGIN, which is
assigned to DU1:[TASK]) in the SET DEFAULT command line.
$ SHOW DEFAULT
DU0:[DONVAN]
Named
TT2:
Protection UIC:
[303,1]
$ SET DEFAULT/NONAMED DIRECTORY
$ SHOW DEFAULT
DU0:[303,1]
Nonamed
TT2:
Protection UIC:
[303,1]
$ SET DEFAULT [TINA]
SET -- Illegal directory
$ SET DEFAULT/NAMED_DIRECTORY [100,100]
$ SHOW DEFAULT go
DU0:[100,100]
Named
TT2:
Protection UIC:
[303,1]
$ SET DEFAULT/NONAMED DIRECTORY
$ SHOW DEFAULT FRET
DU0:[303,1]
Nonamed
TT2:
Protection UIC:
[303,1]
$ SET DEFAULT/NAMED DIRECTORY [DONVAN]
$ SHOW DEFAULT
DU0:[DONVAN]
Named
TT2:
Protection UIC:
[303,1]
This example shows the behavior of SET DEFAULT/NONAMED_DIRECTORY. You
log
in and issue a SHOW DEFAULT command. Your default directory is
[DONVAN].
You issue SET DEFAULT/NONAMED_DIRECTORY. You then type another SHOW
DEFAULT command.
The default directory appears as [303,1]. This is a
directory name that is based on your User Identification Code (UIC).
Note that
[303,1]
is an actual directory only if it had been
previously created.
Any time that you change your terminal's default
from /NAMED DIRECTORY to /NONAMED_DIRECTORY, the name of your default
directory is the
same as your UIC.

4-102

HANDLING FILES

SHOW DEFAULT
4.11.2

SHOW DEFAULT

SHOW DEFAULT displays the current default device and directory for
your
terminal.
It also shows whether you are operating with
/NAMED DIRECTORY or /NONAMED DIRECTORY as your default, and your User
Identification Code (UIC).
Format
SHOW DEFAULT
Example
$ SHOW DEFAULT
DU1: [HUSKY]
Named
TT6:
Protection UIC: [15,20]
This example shows the display from SHOW DEFAULT, giving the default
device, DU1:, and directory, [HUSKY], for your terminal, TT6:.
Named
indicates that your default is /NAMED_DIRECTORY---that is, you can
specify
either
a
named
or
numbered directory in all file
specifications and commands.
Your User Identification Code
( UIC)
identifies you to the operating system and controls your ability to
access files.

4-104

HANDLING FILES

SET FILE (Cont.)
Examples
$ DIRECTORY/FULL HAI.FAI
DIRECTORY DU1: [HWANG]
16-JUN-85 11:02
HAI.FAI;1
( 10,10)
0./55.
16-JUN-85 11:02
[222,314][RWED,RWED,RWED,R]
Total of 0./55. blocks in 1. files
$ SET FILE/END OF FILE: (BLOCK:56,BYTE:0)
In this example, the user has just aborted a task that writes data in
the file HAI.FAI.
On checking the directory for HAI.FAI with the
/FULL qualifier, the user finds that while 55 blocks are allocated,
none have been used. The file may contain nothing. It may contain
irrelevant information, or it may contain useful data. In any case,
the end-of-file pointer can be moved out to just past the last block
allocated to check. The user issues the SET FILE/END OF FILE command
and specifies byte 0 of the first unused block (55 + 1) as the end of
file.
This makes it possible to examine the contents of the 55
allocated blocks.
$ SET FILE/ENTER:DUO:[MKTG]LANE.TXT ODIN.TXT
In this example, the user caused the file ODIN.TXT to appear in the
[MKTG] directory under the name LANE.TXT.
There is still only one
copy of the file, and only a small amount of extra disk space is used.
$ SET FILE/REMOVE

[MKTG]LANE.TXT

In this example, the user decided that the directory [MKTG] no longer
needed access to LANE.TXT and removed the entry from the directory.
$ DIRECTORY/SUMMARY
Total of 146./155. blocks in 5. files
$ SET FILE/TRUNCATE *.*;*
$ DIRECTORY/SUMMARY
Total of 146./146. blocks in 5. files
In this example, the user uses the DIRECTORY/SUMMARY command to
determine that there are nine unused blocks in the directory. Because
blocks allocated cannot be used, the user issues the SET FILE/TRUNCATE
command with wildcards, specifying that all files in the directory are
to be truncated.
Now there are no unused blocks in the directory.
This saves disk space.

4-107

HANDLING FILES

SET UIC (Cont.)
Examples
$ DIRECTORY/FULL [000000]GIDEON.DIR
Directory DU0:[000000]
12-JUN-85 14:12
GIDEON.DIR;1
(576,5040)
[200,1] [RWED, RWED, RWED, R]

l./1.

C 12-JUN-85 07:28

Total of l./l. blocks in 1. file
$ SET UIC
UIC? [200,1]
$ SET DEFAULT [GIDEON]
Assume that, as a privileged user, you want to create or alter files
in [GIDEON], another directory located on your current device. A full
listing of the directory file itself, located in [000000]GIDEON.DIR,
that the UIC of the directory's owner is [200,1]. You then
shows
issue the SET UIC command to change your current UIC to that of the
Finally, you type the SET DEFAULT command to move
directory's owner.
to the other directory.
Notes
As a privileged user, you can manipulate the files of another
directory in any way. Note that you only need to issue the SET UIC
command if you intend to create or alter files (WRITE) in another
when you are working with the files of another
directory.
However,
directory, it is good practice to always use this command.
If you change your UIC to that of a non-privileged account, you can
change back to a privileged account by issuing the SET UIC command
again.
You can type either the SET UIC or the SET DEFAULT command first; the
sequence does not matter.
When a terminal's default is /NONAMED DIRECTORY, SET UIC changes both
the UIC and the directory of a privileged user. For a privileged
user, therefore, SET UIC functions exactly like SET DEFAULT.

4-109

HANDLING FILES

SHOW UIC
4.11.5

SHOW UIC

SHOW UIC displays your User Identification Code (UIC).
Your UIC
is
unique and identifies you to the operating system. In addition, your
UIC determines whether you are a privileged or nonprivileged user.
Each file and directory has a UIC associated with it, which identifies
the owner.
Each file and directory also has a protection code. The
way in which your UIC relates to both the UIC and protection code of a
file or directory controls your ability to access that file or
directory.
See Section 4.6 for a description of protection.
Nonprivileged users always have the same UIC, but privileged users can
change their UIC with the SET UIC command.
Format
SHOW UIC
Example
$ SHOW UIC
Protection UIC: [303,17]
This example shows the display from SHOW UIC. The first number is the
group number,
and the second is the member number. Group and member
numbers are octal and range from 1 through 377.
Generally, all users working on a particular project have the same
group number. Each user account, however, has a unique member number.
Group numbers indicate privilege status.
The UICs of privileged
accounts have group numbers of 10 or less. The user issuing this SHOW
UIC command, therefore, is nonprivileged.

4-110

HANDLING FILES

SET PROTECTION (Cont.)
/SINCE:dd-mmm-yy/THROUGH:dd-mmm-yy
Specifies that you want
created within that range.

set the

protection only on files

/TODAY
Specifies that you want to set the protection only on files
created on the same day the command is being issued.
/EXCLUDE:filespec
Specifies that you want the SET PROTECTION command not to affect
certain files.
The filespec argument to /EXCLUDE can contain
either a single file specification (for example, TEST.DAT;2) or
wildcards in all but one of the file specification fields (for
example, *.DAT;*, TEST.*;*, or *.*;2), if you want to exclude
However,
the version number must be given,
multiple files.
either explicitly or with a wildcard (*).
Examples
$ SET
FUNCTION?PROTECTION
CODE? (SYSTEM:RWED,OWNER:RWED,GROUP,WORLD)
File(s)? SANTONE.TEX
$ SHOW PROTECTION SANTONE.TEX
System:RWED, Owner:RWED, Group:No Access, World:No Access
This example changes the protection of file SANTONE.TEX so that
the owner have full access to the file and all
privileged users and
The SHOW PROTECTION command
others have no access to the file.
the
protection
of
file.
Issuing
the SHOW PROTECTION command
displays
is a good way of checking that you have changed the file's protection
code correctly.
$ 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
privileged users can change the protection status of any file.
users,
Thus, you can prevent privileged users from inadvertently accessing
your files, but you cannot prevent them from deliberately changing the
files' protection status and doing as they want.
If you deny READ access to a task image file, the task cannot run.
code
Other commands accepting a protection
INITIALIZE/UPDATE, MOUNT, and CREATE/DIRECTORY.

4-113

include

INITIALIZE,

HANDLING FILES

SET PROTECTION/DEFAULT (Cont.)
Examples
$ SET PROTECTION/DEFAULT
CODE?(SYSTEM: R,OWNER:RWED,GROUP:R,WORLD)
This example establishes your default file protection.
Because you
are issuing this command for the first time in the terminal session,
you specify all four user categories. The code limits users in the
SYSTEM and GROUP categories to READ access. You retain the standard
volume default protection for the OWNER category of READ, WRITE,
EXTEND, and DELETE.
You deny all file access to the WORLD category by
omitting the colon and access code after the category name.
$ SET PROTECTION:(GROUP) /DEFAULT
Assume that you type this command later in the same terminal session
that you executed the command in the first example. Here you change
your default protection for the GROUP category, denying these users
any access to your files. Your default protection for the other three
user categories remains unchanged.
Note that you only needed to
specify the user category for which you wanted to change the file
access.
$ SET PROTECTION/NODEFAULT
This command removes your personal default file protection. The files
that you create after issuing this command receive the volume default
protection.
Notes
If you place SET PROTECTION/DEFAULT in your LOGIN.CMD file, you must
specify all four user categories.
The system manager can use the Account File Maintenance Program (ACNT)
to establish a default file protection for your account. This method
has
the same effect as placing SET PROTECTION/DEFAULT in your
LOGIN.CMD file:
both methods establish your default file protection
for each terminal session. Note, however, that you can modify your
default
file protection
for any portion of a terminal session by
typing the SET PROTECTION/[NO]DEFAULT command.
If both SET PROTECTION/DEFAULT and
ACNT set your default file
protection, then the protection indicated in SET PROTECTION/DEFAULT is
your default.
SET PROTECTION/NODEFAULT removes your personal default protection,
regardless of whether SET PROTECTION/DEFAULT or ACNT established it.
Error Messages
Illegal user default protection code
Explanation:
issuing SET
session.

You did not specify all four user categories when
PROTECTION/DEFAULT the first time during a terminal

User Action:
Reenter the command line, specifying all four user
categories in the protection code.

4-116

HANDLING FILES

SHOW PROTECTION
4.11.8

SHOW PROTECTION

SHOW PROTECTION displays your personal default file protection code.
Your default file protection can be established in two ways:
either
by issuing the SET PROTECTION/DEFAULT command, or by using the Account
File Maintenance Program (ACNT) to enter a protection code for your
account.
See the description of SET PROTECTION/DEFAULT in Section
4.11.7.
If you do not set your own default
PROTECTION issues the following message:

file

protection,

then

SHOW

No user default protection specified.
Format
SHOW PROTECTION
Example
$ SHOW PROTECTION
System:RWED, Owner:RWED, Group:R, World:No Access
This example shows the display from SHOW PROTECTION, indicating
that your default file protection grants full access to the
SYSTEM and OWNER categories, READ access to the GROUP category,
and no access to the WORLD category.

4-118

HANDLING DEVICES AND VOLUMES
3.

Private devices cannot be accessed by anyone but the owner,
that is, the person who allocated the device. Devices can be
or by
made private with the ALLOCATE command (Section 5.7),
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.

5.1.4

Unowned devices are those that have not been allocated,
mounted,
or set public. RSX-11M-PLUS permits no access to
unowned volumes.

Preparing a Scratch Disk for Use

A scratch disk is a blank disk or a disk which contains data of no
use.
The prime example of a scratch disk is one that has never been
used.
You must use a combination of several system utilities and DCL
commands to prepare the scratch disk as a Files-11 volume. This
section summarizes the process.
1.

Allocate an appropriate device and place the disk on the
drive,
using the DCL ALLOCATE command. Make sure the device
is write-enabled.

After physically placing the disk on the drive, spin it up
and mount it using the /FOREIGN qualifier. This permits the
system to bypass the file system when accessing the disk.

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 questions about formatting a
disk, see your system manager.
If formatting is necessary, you can use the Disk Volume
Formatter
Utility (FMT).
(The RSX-11M/M-PLUS Utilities
Manual provides full instruction on this utility) To gain
access to FMT from DCL, enter the following command:
$ RUN $FMT
FMT>
Now you can enter FMT commands.

Once the disk is ready, you must identify the bad blocks on
the disk. These are blocks that are physically unusable for
some purpose.
This information is usually written on disks
when they are manufactured, but you can supplement this
information with the ANALYZE/MEDIA command.

Once you have identified the bad blocks, the disk driver and
the disk controller have full use of the disk. Next, 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.

5-11

HANDLING DEVICES AND VOLUMES
your default disk and directory, or the logical name DIARY to a file
in which you keep a log of your daily activities. You can also use
logical names in file specifications to keep your programs and command
procedures independent of physical file specifications.

Logical Name Tables

5.2.1

The system maintains logical name and equivalence name pairs
logical name tables:

four

Task logical name table---Contains logical name entries that
are created for an individual task using the Create Logical
(CLOG$) directive. These entries remain in the table for
only as long as the task is running. When either the task
has completed
execution or
the
Delete Logical (DLOG$)
directive has been issued, the logical names are removed from
the table. (See the RSX-11M/M-PLUS and Micro/RSX Executive
Reference Manual
for more information on the CLOG$ and the
DLOG$ directives )

User logical name table---Contains logical name entries that
are local to a particular user. By default, the DEFINE and
ASSIGN commands and login assignments place a logical name in
the user logical name table.

Group logical name table---Contains logical name entries that
are qualified by a
group number. These entries can be
accessed only by tasks that execute with the same group
number
in their user Identification Codes (UIC) as the user
that assigned the logical name.
You must use the /GROUP
qualifier to make an entry in the group logical name table.

System logical name table---Contains entries that can be
accessed by any task in the system. You must use the /SYSTEM
or /GLOBAL qualifier to make an entry in the system logical
name table.

You must be privileged
logical name tables.

5.2.1.1

place

entries

the

group

and

system

Displaying Logical Name Table Entries

The SHOW LOGICALS (or SHOW ASSIGNMENTS)
entries in the logical name tables.

command

displays

current

To display the contents of the user logical name table, enter the SHOW
LOGICALS command, without any qualifiers or parameters as follows:
$ SHOW LOGICALS
This command produces a display of the current logical names in the
user logical name table and their equivalence.

5-15

HANDLING DEVICES AND VOLUMES
To delete a logical name, use the DEASSIGN command.
Generally,
to
delete a
logical name created by the DEFINE command, you should put
quotation marks (") on both sides of the logical name in the DEASSIGN
command line.
For example, to delete the logical name TASK: (created
by the DEFINE command), use the following command line:
$ DEASSIGN "TASK:"
You do not need need the quotation marks to delete any logical names
created by the ASSIGN command.

5.2.3 Logical Name Translation
For logical names created using the ASSIGN command, if the system
finds a logical name, it substitutes the equivalence name for the
logical name in the file specification. This is called logical name
translation.
When the system translates logical names, it
searches the task, user,
group,
and system tables (in that order), and uses the first match it
finds.
If you are ever in doubt about the equivalence name assigned to a
logical name,
use either the SHOW LOGICALS or the SHOW ASSIGNMENTS
command.

5.2.3.1

Iterative Translation

When the system translates logical names in file specifications, the
logical name translation can be iterative. This means that after the
system translates a logical name in a file specification, it repeats
the process of
translating
the file specification.
For example,
consider the following logical name table entries made with the ASSIGN
commands:
$ ASSIGN LB:[3,54] RANDOM
$ ASSIGN RANDOM:VMR.TSK TASK
The first ASSIGN command equates the logical name RANDOM to the device
and directory specification LB: [3,54].
The
second ASSIGN command
equates the
logical
name
TASK
to
the
equivalence
string
RANDOM:VMR.TSK.
In subsequent commands, or in programs you execute,
you can refer to the logical name TASK. For example:
$ RUN TASK
When the system translates the logical name TASK, it finds the
equivalence
string RANDOM:VMR.TSK.
The system then checks to see if
the portion to the left of the colon (if there is a colon) in the
equivalence name is a logical name; if it is a logical name (as RANDOM
is in this example), the system translates that logical name also.
When the logical name translation is complete, the translated device
and file specification is LB:[3,54]VMR.TSK.
NOTE
The system limits logical name translation to 10
levels.
If you define more than 10 levels or create a
circular definition, an error occurs when the logical
name is used.

5-17

HANDLING DEVICES AND VOLUMES
You can control the translation of logical names by using the /FINAL
For example, you
qualifier on either the ASSIGN or DEFINE commands.
assign three levels of logical names in the following manner:
$ ASSIGN DB0:[TSTSYS] TESTS:
$ ASSIGN/FINAL TESTS: LAST:
$ ASSIGN LAST: DISK:
Without the /FINAL qualifier on the second assignment, the logical
name DISK:
would eventually be translated into the equivalence name
DBO:[TSTSYS].
Because you applied the /FINAL qualifier to the second
assignment, the translation stops at the equivalence name TESTS:. The
If for
task is less hardware dependent when you use this qualifier.
some reason,
DB0:
is no
longer available for use, you can assign
TESTS:
to point to another disk drive (when the task is not running)
without having to change the task itself. However, at some point, you
( or the task) have to refer to the logical name TESTS: (for example,
spawning another
task,
issuing a ACHN$ directive) in order for the
translation from DISK: to DBO:[TSTSYS] to work. For more information
on the ACHN$ directive, see the RSX-11M/M-PLUS and Micro/RSX Executive
Reference Manual .

5-18

HANDLING DEVICES AND VOLUMES

ANALYZE/MEDIA (Cont.)
/[NO]EXERCISE[=(n,m)]
Specifies the double word data pattern that ANALYZE/MEDIA uses to
locate bad blocks. The parameter (n,m) represents the two 16-bit
octal numbers used as the double word data pattern.
You can
specify a decimal number by placing a period after the number.
If you specify /NOEXERCISE, ANALYZE/MEDIA uses the blocks found
in the bad block descriptor without testing them.
/OVERRIDE
Ignores the last-track information on a last-track device and
creates a bad block descriptor file on the last good block before
the last track.
/RETRY
Specifies that the I/0 driver retry operations on bad blocks it
finds before flagging them as bad.
/SHOW
Specifies that ANALYZE/MEDIA list bad blocks as it encounters
them.
The /SHOW qualifier does not list the bad blocks you enter
manually using the /BAD qualifier.
Examples
$ ANALYZE/MEDIA
Device? DU1:
In this example, ANALYZE/MEDIA analyzes the media found in DUl:
and
adds the bad blocks it encounters to the bad block descriptor file on
the media. It does not display the bad block information on your
terminal.
$ ANALYZE/MEDIA/BADBLOCKS DU1:
BAD> LBN(S)= 300
BAD> LBN(S)= 1002
BAD> LBN(S)=
BAD -- DU1: Total bad blocks = 2.
In this example, ANALYZE/MEDIA prompts you for bad block information
to add to the bad block descriptor file of DU1:. After you enter all
the bad blocks, enter CTRL/Z to end the manual entry of bad blocks.
ANALYZE/MEDIA then analyzes the entire volume and displays a message
telling you the total number of bad blocks it finds, including those
you entered manually. In this case, the only bad blocks on the media
were those you entered. If you enter RET instead of CTRL/Z when you
finish entering bad block information, the command displays a list of
the bad blocks you entered.

5-20

HANDLING DEVICES AND VOLUMES

ANALYZE/MEDIA (Cont.)
$ ANALYZE/MEDIA/BADBLOCKS/SHOWDUl:
BAD>LBN(S) = 3
BAD>LBN(S) = 347
BAD>LBN(S) =
BAD -- DUl: Bad block found - LBN = 102.
110.
In this example, ANALYZE/MEDIA found two bad blocks in addition to
those
you specified with the /BADBLOCKS qualifier.
The /SHOW
qualifier causes the command to display the additional bad blocks, but
it does not display the blocks you entered.
Notes
If your system includes error logging, the device you specify may have
an error limit set.
In this case, error logging displays the
following message if the media reaches that limit:
ERRLOG -- **Warning: Device ddnn: reached Hard limit (n.)
However, the ANALYZE/MEDIA command does not terminate at this point.
It is an informational message only.
Error Messages
The ANALYZE/MEDIA command can display the following message:
ANALYZE---Illegal analyze function
Explanation:
You specified
ANALYZE/MEDIA command.
User Action:

incorrect

syntax

for

the

Check the syntax and retry the command.

In addition you may receive the following messages from BAD, the
utility run by ANALYZE/MEDIA.
BAD ---ddnn:

Allocation Failure

Explanation: Bad failed to allocate the block number
sequence
you entered.
The
I/0 failed for a reason other than that the
block number was already allocated to another file. This message
applies to the /ALLOCATE switch only.
User Action:
maintenance.
BAD---ddnn:

Either the volume is bad or the drive requires
Try another volume in the same drive.

Bad block file not found

Explanation:
The bad block descriptor file could not be read
when you used the /BADBLOCKS/NOEXERCISE qualifier.
User Action:
You must use the device without updating the bad
block file, or reformat the device and destroy all data.

5-21

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)

Command Qualifiers
/GLOBAL
/SYSTEM
Specifies that the assignment is to be a system table assignment.
/SYSTEM and /GLOBAL are synonyms and are privileged qualifiers.
System assignments apply to all tasks running in the system.
/LOCAL
Specifies that the assignment is to be a local assignment.
is the default qualifier, so you do not need to specify it.

This

Commands and tasks initiated from your terminal can access
devices or
files through the logical names assigned to them.
Note that no automatic deassignment occurs if you dismount a
device after assigning a logical name to it.
You can define your own set of local assignments for your
terminal.
These local
logical names exist only
for your
terminal.
/LOGIN
Specifies that the assignment is to be
is a privileged qualifier.

a login assignment.

This

5-27

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)
$ ASSIGN LB0: RR2:
This example assigns the logical name RR2: to the pseudo device LBO:.
This logical name exists for your terminal only.
$ ASSIGN/TERMINAL:TT4: DY1: LN1:
This example assigns the logical name LN1:
to the physical device
DY1:
for
all
commands and tasks initiated from TT4:. This command
must be issued from a privileged terminal. Also, the terminal TT4:
must be logged in before the assignment can be made.
$ ASSIGN/GLOBAL DL1: XX1:
This example assigns the logical name XX1:
to the physical device
DL1:.
All users and tasks on the system can refer to XX1:
when they
initiate commands and tasks. This command must be issued from a
privileged terminal.
DL1:
can also be used to reference DL1:.
Notes
The order of precedence in logical names, from highest to lowest, is:
task,
local,
login, group,
and global.
This means that, if the
logical device SY0: has a global assignment of DB1:
but a local
assignment of DR0:, the operating system interprets SY0: to be DR0:
for your terminal.
ASSIGN is counteracted by DEASSIGN.
You can display current assignments with either the SHOW ASSIGNMENTS.
You can assign SY0: with SET DEFAULT, described in Chapter 4.
ASSIGN/REDIRECT is a separate command, described in 5.4.3.
ASSIGN/TASK is a separate command.
ASSIGN/QUEUE is a separate command, described in the
Batch and Queue Operations Manual .

RSX-11M/M-PLUS

ASS---Device not in system
Explanation:
The specified equivalence device name does not
exist in the system.
User Action:
Reenter the command line specifying
is recognized by the system.

device

that

ASS---Device not terminal
Explanation:
You did not specify a terminal when you issued the
ASSIGN/TERMINAL command.
User Action:

Reenter the command line specifying a terminal.

5-28

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)
You can define your own set of local assignments' for your
terminal.
These local logical names exist only for your
terminal.
/LOGIN
Specifies that the assignment is to be a login assignment.
is a privileged qualifier.

This

Login assignments are usually established through ACNT, the
Account File Maintenance Program.
However,
the ASSIGN/LOGIN
command does not alter the account file.
These logical names
exist
for your account, and are available to you regardless of
the terminal on which you log in.
When a user issues a LOGIN command to log in to the system, the
system automatically assigns the logical name SYS$LOGIN to the
user's default device and directory, which is the device and
directory that contains the user's files.
/TERMINAL:ttnn:
Specifies that the requested local assignment be applied to
another terminal.
Only a privileged user may make assignments to
other terminals. Note that the target terminal. must be logged in
before the assignment can be made.
/FINAL
/TRANSLATION_ATTRIBUTES=TERMINAL
Specifies that the equivalence name string should
not
be
translated
iteratively;
that is,
the logical name translation
should terminate with the current equivalence string.
See
Section 5.2.3.1 for more information on the iterative translation
of logical names. The /TRANSLATION_ATTRIBUTES=TERMINAL qualifier
is a synonym for /FINAL, included for VAX/VMS compatibility.
Examples
$ ASSIGN
Logical name equivalent? DU1:
Logical name? TP1
This example assigns the logical name TP1 to the physical device DU1:.
The user may now issue commands referring to device TP1 (in any
command that accepts a device specification) and DU1:
will be
substituted for it.
$ ASSIGN LB0: RR2:
This example assigns the logical name RR2 to the pseudo device LBO:.
This logical name exists for your terminal only.
$ ASSIGN/GROUP:303 DU0:[1,1]SYSLIB.OLB;3 SYS$LIB
This example assigns the logical name SYS$LIB to file SYSLIB.OLB;3,
which is located on device DU0: in directory [1,1]. This logical
name exists for users whose User Identification Code (UIC) group
number is 303.

5-31

HANDLING DEVICES AND VOLUMES

ASSIGN (Cont.)
$ ASSIGN/TERMINAL:TT4: DU2:[TEST] A:
$ SHOW ASSIGNMENTS/TERMINAL:TT4:
A = DU2:[TEST] (Local, TT4:)
This example assigns the logical name A to the directory [TEST], which
is located on device DU2: for all commands and tasks initiated from
TT4:. The user then issues a SHOW ASSIGNMENTS to display the logical
name.
These commands must be issued from a privileged terminal.
Also, the terminal TT4: must be logged in before the assignment can
be made.
$ ASSIGN/GLOBAL DL1: XX1:
This example assigns the logical name XX1 to the physical device DL1:.
All users and
tasks on the system can refer to XX1: when they
initiate commands and tasks.
This command must be issued from a
privileged
terminal.
The string DL1: can also be used to reference
the physical device DL1:.
$ ASSIGN DU1 DQ
$ SHOW ASSIGNMENTS
DQ = DU1: (Local, TT:)
This example assigns the logical name DQ to the physical device DU1:.
Although the user did not terminate the equivalence name (DU1) with a
colon, DCL recognizes that the equivalence name resembles the other
ASSIGN command device format (ddnnn:, as descibed in Section 5.4.1).
Because the ASSIGN command line is in this format, DCL automatically
terminates the equivalence name string with a colon, as shown when the
user issued the SHOW ASSIGNMENTS command.
$ ASSIGN DB0: [TSTSYS] TESTS

$ ASSIGN/FINAL TESTS LAST:
$ ASSIGNLAST FIRST
This example shows three assignments. First, the user assigns logical
name TESTS to the equivalent name DBO:[TSTSYS]. Second, the user then
assigns the logical name LAST to the equivalent name TEST5 with the
/FINAL qualifier.
Third, the user assigns the logical name FIRST to
the equivalent name LAST.
When a task (for example) refers to the
logical name FIRST,
the
translation is carried only as far as the
equivalent name TESTS and then stops.
For more information on the
iterative translations of logical names, see Section 5.2.3.1.

5-32

HANDLING DEVICES AND VOLUMES

ASSIGN/REDIRECT
5.4.3

ASSIGN/REDIRECT

ASSIGN/REDIRECT redirects output from one physical device to another.
You can also redirect a physical device to a pseudo device, or the
reverse.
Use this privileged command when you have another device
that can take the place of a currently unavailable device.
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 requests for oldddnn:
are to be redirected.
Example
$ ASSIGN/REDIRECT DU0: DU3:
$ SHOW DEVICES TYPE DU:
DU0:
DU3:
LOADED
DU1:
LOADED
DU2:
LOADED
DU3:
LOADED
$ ASSIGN/REDIRECT
FROM? DU0:
TO? DU0:
$ SHOW DEV DU:
DUO:
DU1:
DU2:
DU3:

LOADED
LOADED
LOADED
LOADED

This example shows the process of redirection.
Following the first
ASSIGN/REDIRECT, any output for DUO: is sent to DU3:, as indicated by
the first SHOW DEVICES display. Later, when DU0: is again available,
the user issues ASSIGN/REDIRECT again to redirect DU0: to DU0:.

5-34

HANDLING DEVICES AND VOLUMES

DEASSIGN (Cont.)
Examples
$

DEASSIGN TP0:

If the system does not have extended logical name support, this
example deletes the local assignment of the logical device name TPO:
to a device.
If the system has extended logical name support, this example deletes
the local assignment of logical name TPO to a device. DEASSIGN
ignores the terminating colon.
$ DEASSIGN/ALL
This example deletes all local logical name assignments.
$ DEAS/LOCAL/ALL
This example is the equivalent of the previous example. /LOCAL is the
default qualifier.
$ DEAS/LOCAL/ALL/TERMINAL:TT4:
This example deletes all local assignments for terminal TT4:.
command must be issued from a privileged terminal.

This

$ DEASSIGN
This example deletes the logical name XY: (created with the DEFINE
command).
This example is valid only if your system supports extended
logical names.
Notes
DEASSIGN counteracts ASSIGN and DEFINE.
You must
command.

type

least

the

first four characters of the DEASSIGN

Login assignments are normally established through ACNT, the Account
File Maintenance Program.
You can display assignments with either the SHOW ASSIGNMENTS or SHOW
LOGICALS command.
All local assignments are deassigned when you either log out or log
DISMOUNT does not delete logical name assignments.
DEASSIGN/QUEUE is a separate command. See the RSX-11M-PLUS Batch
Queue Operations Manual for more details.

5-39

and

HANDLING DEVICES AND VOLUMES

DEFINE (Cont.)
Examples
$ DEFINE
Logical name? "TOM'S TEST"
Equivalent name string? " BLEW UP"
$ SHOW LOGICALS
TOM'S TEST = BLEW UP (local, TT0:)
This example defines the logical name TOM'S TEST to the equivalent
string BLEW UP.
The user issued a SHOW LOGICALS command to verify
that the assignment had been made. DEFINE removes the quotation marks
from the logical name.
$

DEFINE "TOM'S TEST"

"BLEW UP"

This example is the same as the previous one.
DEF---Device not terminal
Explanation: You did not specify a terminal when you issued the
DEFINE/TERMINAL command.
User Action:

Reenter the command line specifying a terminal.

DEF---Function requires logical name support.
Explanation:
support.

Your system does not support extended logical name

User Action:

None.

DEF---Octal group number expected
Explanation:
You did not specify an octal group number value
when you issued the DEFINE/GROUP command.
User Action:
the command.

Check the group number that you want and reenter

DEF---Terminal not logged in
Explanation: The terminal you
definition for is not logged in.

attempted

make

logical

User Action: Log in the terminal you want to make the definition
for and reenter the command line.

5-44

HANDLING DEVICES AND VOLUMES

ALLOCATE (Cont.)
Examples
$ ALLOCATE DU
ALL -- DU0: Now allocated
This example allocates the first available DU drive (RD51 or RX02).
The message gives the name of the device allocated. This is an
example of a generic allocation.
$ ALLOCATE
Device? DU1:
This example allocates the specified device.
confirmed by the return of the prompt.

The

allocation is

$ ALL DU1:
ALL -- Device allocated to other user
This example shows an allocation that failed because the device named
was not available.
$ ALL DL1: TP0:
ALL -- DL1: Now allocated
This example allocates the specified device and assigns it the logical
name TP0:.
$ ALLOCATE/TYPE:RD51 DU
ALL -- DU1: Now allocated
This example shows the use of the /TYPE qualifier. The user may want
to allocate the first available RD51 but to ignore any other devices
using' the DU driver. This is also a generic allocation.
Notes
When you
device.

allocate

device,

no other

user

can gain access to the

REALLOCATE counteracts ALLOCATE.
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-11M-PLUS batch jobs.
See the
RSX-11M/M-PLUS Batch and Queue Operations Manual for information on
private devices in batch jobs.

5-46

HANDLING DEVICES AND VOLUMES

DEALLOCATE
5.8 DEALLOCATE
DEALLOCATE counteracts ALLOCATE. It frees a private device for access
by other users.
Format
DEALLOCATE[/qualifier]
Device?
ddnn:
DEALLOCATE[/qualifier] ddnn:
Command Qualifiers
/ALL
/DEVICE
/TERMINAL:ttnn:
Parameter
ddnn:
Specifies the device to be deallocated.
Command Qualifiers
/ALL
Frees all devices allocated from the terminal being used. If you
use this qualifier, you cannot specify a device name.
/DEVICE
This qualifier is non-operational.
/TERMINAL:ttnn:
Enables a privileged user to deallocate devices allocated from
another terminal.
Example
$ DEALLOCATE
Device? DU0:
This example deallocates the device DUO: previously allocated by the
user.
Notes
Nonprivileged users can deallocate only those devices that they have
previously allocated.
Privileged users can deallocate any private
device.
DEAL is the short form of DEALLOCATE,

5-48

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
/TRANSLATE:arg
EBCDIC
NONE
UT1
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.
UT1, UT2, or UT3 specifies user-supplied translation
tables that have been previously linked into the MTAACP.
See the
RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference Manual for
further information on character translation.
/VOLUME_IDENTIFICATION: (volumeID[,volumeID[,s]])
Specifies Volume Identifiers. If you want 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.9.1 for more information, including examples of this
qualifier in use.
Examples
$ MOUNT
Device? DL1:
Volume ID? HOTROD
This example mounts the volume labeled HOTROD on device DL1:. If you
are doing nothing more than mounting a volume to read from or write
to, 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.
$ MOUNT/DENSITY:1600 (MM0:MM1:MM2:) "W*MB*T",FOOBAR,FOO
This example mounts a 3-volume ANSI magneic tape set on devices MMO:,
MM1:,
and MM2:.
The volume labels are W*MB*T, FOOBAR, and FOO. The
first label
is included within quotation marks to
allow
the
specification of the asterisk (*).
Note that the comma between
"W*MB*T" and FOOBAR is outside the quotation marks.

5-60

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
$ MOUNT/PROCESSOR:MRXACP/FOREIGN/PARAMETERS:"MUMBLFRAZ"
Device? DR0:
Volume label? HARPO
This example mounts the volume labeled HARPO on device DRO:.
The
volume's file
structure
is controlled by a non-DIGITAL ACP named
MRXACP; therefore, 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.
$ MOUNT/NOLABEL/BLOCK:2048/RECORD:64/CARR:FORTRAN->/TRANSL:EBCDIC MS1:
This example mounts an unlabeled magnetic tape on device MS1:,
specifying a block size of 2048 characters and a record size of 64
characters.
The volume includes FORTRAN carriage control, so that is
specified as well.
The volume's records are written in EBCDIC
The
characters, so the user included the /TRANSLATE qualifier.
characters will be translated to ASCII for handling by the operating
system and then translated back to EBCDIC for writing to the tape
volume.
$ MOUNT/WAIT DL1: WHIZZER
In this example, the user wants an operator to place the medium
containing the proper volume in place on DL1:. The command may appear,
in a batch job, indirect command file, or interactive mount, perhaps
from a user on a remote terminal. The following message appears on
CO:, the operator's console:
Please mount volume WHIZZER on DL1:

CO:
Type

UNS (DCL START) when ready
or
RES (DCL CONTINUE) to reject request.
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. The batch processor attempts 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
Naturally, you must place the
other magnetic medium on a drive.
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. However, mounting enables
the system software to access the medium, either to read or write
data, or to establish a file structure for the volume.
Mounting
device.

device

resets

the

error counts and QIOs to zero for that

5-61

HANDLING DEVICES AND VOLUMES

MOUNT (Cont.)
If you want to use a File Set ID other than the Volume ID of the first
in the set, you can do so on the
first mount of a newly
reel
initialized tape, as shown in the examples.
Each site using magnetic tapes extensively will have policies on File
Set IDs and Volume IDs.
See your system manager or supervisor for
information on how File Set IDs and Volume IDs are used at your site.
The following examples establish the relationship between File Set IDs
and Volume IDs.
The following command:
$ MOUNT MS0: FOO
mounts a tape set (consisting of a single physical reel) whose File
Set ID is F00 and whose Volume ID is FOO. The reel FOO must be loaded
on device MS0: at the time of the mount.
The following command:
$ MOUNT MS0: DRAG/VOLUME IDENTIFICATION:(FOO,BAR,MORE)
mounts a tape set (whose File Set ID is DRAG) and that consists of
three physical reels with Volume IDs of F00, BAR, and MORE. The reel
but the other
with the Volume ID F00 must be loaded on device MS0:,
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 F00)
does not take place until the first record is written to the tape.
The following command:
$ MOUNT/OVERRIDE:SET_IDENTIFICATIONMS0: (FOO,BAR,MORE)
mounts a tape set (whose File Set ID is immaterial) that consists of
three physical reels with Volume IDs of F00, BAR, and MORE. The reel
F00 must be loaded on device MSO:, but the other two reels are not
loaded at the time of the mount.
The following command:
$ MOUNT MS0: FOO/VOLUME_ID:(A312,A387,B231)
mounts a tape set (whose File Set ID is F00) that consists of three
physical reels with Volume IDs A312, A387, and B231. The reel A312
must be loaded on device MSO:, but the other two reels are not loaded
a t the time o f the mount.
The following command:
$ MOUNT (MS0:,MS1:,MS2:) (FOO,BAR,MORE)
mounts a tape set (whose File Set ID is F00) that consists of three
physical reels with Volume IDs F00, BAR, and MORE. At the time of the
mount, the reel F00 must be loaded on device MSO:, the reel BAR must
be loaded on device MSl:, and the reel MORE must be loaded on device
MS2:.

5-63

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont.)
/SAVE
Specifies that the disk is to remain spinning in the drive and
can be accessed for read or write by privileged tasks.
This is a privileged qualifier that applies to DB:, DM:, and DU:
devices only.
The most common use of /SAVE is when saving or backing up the
system disk. If
you simply want to leave the disk spinning, use
the /NOUNLOAD qualifier.
Remember, these values can also be set
with the /DEFAULT qualifier to MOUNT. See Section 5.9.
/TERMINAL:ttnn:
Allows a privileged user to dismount a volume mounted from
another terminal.
/[NO]UNLOAD
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 only
if you are a privileged user. If you are a nonprivileged user
and you try to dismount the unit or specify /UNLOAD in the
command
line, you will get a warning message that the volume
cannot be spun down.
The /NOUNLOAD qualifier specifies that the disk is to remain
spinning after the dismount.
This is the default for foreign
mounted volumes. The /NOUNLOAD qualifier is useful when the
volume is to be immediately remounted. For magnetic tapes, this
qualifier rewinds the tape to the first file position. Remember,
these values can also be set with the /DEFAULT qualifier to
MOUNT.
The /UNLOAD and /NOUNLOAD qualifiers apply to DB:, DM:, and DU:
disk drives and magnetic tape drives only.
Examples
$ DISMOUNT
Device? DL0:
DIS -- TT3: Dismounted from DL0: *** Final Dismount Initiated ***
This example dismounts a volume on device DL0:. No other user had the
volume mounted when the DISMOUNT command was issued.
$ DISMOUNT DUl: HOTROD
DIS -- TT4: Dismounted from DU1:
specified
This example dismounts a volume on device DU1:.
The user
the label
HOTROD to be sure the correct volume was mounted on the
device.
The volume was mounted shareable and because another user
also has
it mounted, the informational message does not include the
notification of final dismount.

5-69

HANDLING DEVICES AND VOLUMES

DISMOUNT (Cont.)
$ LOGOUT
DMO -- TT1: Dismounted from DU0: *** Final dismount ***
Have a good morning
22-APR-85 TT1: Logged off
The
This example dismounts a volume as part of the LOGOUT procedure.
user had the volume mounted on the device and had not dismounted it
before logging out. LOGOUT dismounted the volume.
If the device was
This is the equivalent of
allocated,
LOGOUT also deallocated it.
DISMOUNT/ALL.
$ DISMOUNT/ALL
DMO -- TT1:
Dismounted from DU0:
DMO -- TT1:
Dismounted from DU1: *** Final dismount ***
Dismounted from MS1: *** Final dismount ***
DMO -- TT1:
This example dismounts all volumes mounted from the terminal at which
the DISMOUNT was issued. See next example.
$ DISMOUNT/ALL
Dismounted from DUO:
DMO -- TT1:
Dismounted from DU1: *** Final dismount ***
DMO -- TT1:
DMO -- TT1:
Dismounted from MS1: *** Final dismount ***
$ MOUNT DY1: CRUCIAL
This example dismounts all volumes mounted from the terminal at which
The message reminds the user that a volume
the DISMOUNT was issued.
was mounted on DU1:. Because this volume was necessary for a running
task, the user immediately issued a new MOUNT command using the volume
As long as the task did not attempt to open a file and
label CRUCIAL.
its last file between the time of the message and the
did not close
All
time of the new MOUNT, the DISMOUNT has no effect on the task.
files that the task had open remain open.
$ DISMOUNT/PUBLIC DL0:
DMO -- TT2: Dismounted from DL0:
DMO -- TT1: Dismounted from DL0:
DMO -- TT3: Dismounted from DL0:
DMO -- TT5: Dismounted from DL0:
In this example, a privileged
mounted the volume on DLO:.

user

***Final dismount ***
dismounted

all

users

who had

Notes
DISMOUNT counteracts MOUNT.
DISMOUNT/ALL dismounts
LOGOUT issues a DISMOUNT/ALL automatically.
terminal,
whether
mounted explicitly
the
all volumes mounted from
through a MOUNT command or implicitly through a task that spawns a
MOUNT command.
You cannot include comments in a DISMOUNT command line.
terminal
indicate only that the
The messages from the AC P to your
volume is marked for dismount. The actual completion of the dismount
is noted on the operator's console.

5-70

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
These values are the same as the following DCL qualifiers:
Display

DCL Equivalent

Label
/Bad
/Cha
/Ext.
/FPro.
/Indx.
/Inf.
/Lru.
/Mxf.
/Pro.
/UIC.
/Win

Label
/BAD BLOCKS
/EXTENSION
/FILE PROTECTION
/INDEX
/HEADERS
/ACCESSED
/MAXIMUM_FILES,
/PROTECTION
/OWNER
/WINDOWS

/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 for n is
7.
This value can be altered
INITIALIZE/UPDATE command.

on an

existing

volume

with

the

Examples
$ INITIALIZE
Device? DU0:
Volume ID? HONOLULU
This example initializes a volume with the volume label HONOLULU on
device DUO:.
See the next example.
$ ALLOCATE DU0:
$ MOUNT/FOREIGN DU0:
$ INITIAIZE DU0: HONOLULU
$ DISMOUNT DU0:
$ MOUNT DU0: 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 has already been written on the medium.)
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
Finally, the volume is mounted conventionally using
then dismounted.
the volume label HONOLULU.

5-81

HANDLING DEVICES AND VOLUMES

INITIALIZE (Cont.)
$ INIT/INDEX:END/PROTECTION:(SYSTEM:RWED,OWNER:,GROUP:,-> WORLD:) DU1: MIRACLE
This example initializes a volume named MIRACLE on a medium mounted on
device DU1:.
The index
file is
placed at the end of the volume.
Files on the volume are accessible to the system and privileged users
only.
The user used the continuation character (-) to make room for
the command on a narrow terminal.
Notes
All users must
initialized.

allocate

the

device

on which

the volume

is to

On RSX-11M-PLUS, you must use MOUNT/FOREIGN before INITIALIZE.
Error Messages
INI---Allocation for sys 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
qualifier.
/INDEX:

with

command

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
The specified block or blocks exceeded the physical
Explanation:
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 writing out the volume

User Action: Reenter the command. If it still does not work,
see your system manager.

5-82

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
/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:
$ BACKUP/EXCLUDE DB0:[306,6]*.* DU0:
This command
[306,6].

transfers

all

files

except those in the directory

/IMAGE:arg
SAVE
RESTORE
Specifies that you want to use more
during a backup or restore operation.

than

one

diskette or disk

You must use the /IMAGE:SAVE qualifier when you create a backup
set that spans more than one disk or diskette. For example, if
you are backing up a large disk to several small disks, you must
use this qualifier.
You must use the /IMAGE:RESTORE qualifier when you are restoring
a backup set that spans multiple disks or diskettes. For
example, if you are restoring a backup set to a large disk, and
your backup set spans six smaller disks, you must use this
qualifier when you restore the backup set to the large disk.
NOTE
You cannot use the /IMAGE qualifier when backing
up or restoring from one disk or diskette to
another disk or diskette. For one-to-one backup
and
restore operations,
use the /INITIALIZE
qualifier.
/NEW_VERSION
Specifies that a new version of the file be created in the event
of conflicts during restore operations or 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, a time, or both.

before

after

the

The required date/time argument can be in several formats.
You
must specify a date, a time, or both. If you do not specify a
date or time, the default is your system's current date and time.
Here are some examples

5-94

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)

5.12.3

Examples

The following are examples of various BACKUP operations.
Examples
$ BACKUP/LABEL:INPUT:RANDOM/SAVE_SET:19APR85
From? DU0:
To: DU1:
BAC - Starting disk 1 on DU1:
BAC - End of disk 1 on DU1:
BAC - Completed
This example transfers all files on the diskette labeled RANDOM to the
diskette on DU2:.
The backup set name 19APR85 identifies the data
written on the output disk.
$ BACKUP/LIST MS0:
VOL1
VOL1
VOL1

18JUL84
BACKUP2
19JUL84

INPUT1 18-APR-85
INPUT2 19-APR-85
RANDOM 19-APR-85

This example shows a directory of tape volume.
It displays the tape
volume number (VOL1), the names of three volumes, and the names of the
three backup sets contained on the tape.
$ BACKUP/SAVE_SET:19APR85/LIST DU1:
VOL1 19APR85 RANDOM 19-APR-85 23
[303,13]
27DECE.LST;1
ASTCRSH.MAC;2
APNDXC.TXT;1
X.MAC;1
X.OBJ;1
X.TSK;1
X.MAP;1
[306,6]
27DECE.CDA;1
RSX11M.STB;3

BAC - Completed on DU1:
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 previous example).
$ BACKUP/REWIND/SAVE_SET/:18APR85/NOINITIALIZE MS0: DU0:
This example rewinds the tape on drive MS0:,
then locates the backup
set with the name 18APR85 (there may be more than one backup set on a
tape) and transfers all files in the backup set to DU0:. The
/NOINITIALIZE qualifier instructs BACKUP not to initialize DU0:.

5-101

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
$ BACKUP/REVISED:AFTER:(14-MAY-85 17:00)/VERIFY DU0: MS0:
This example backs up all files on the fixed disk that were revised
After all the files have been
after 5:00 P.M. on May 14, 1985.
copied onto the tape, BACKUP verifies the tape. If files on the tape
do not verify, BACKUP returns an error message.
$BACKUP/INI/IMAGE:SAV/VER/MOU DU0: DU1:
BAC - Mount disk 1 on DU1: . Press "RETURN" when done
BAC - Starting disk 1 on DU1:
BAC - End of disk 1 on DU1:
BAC - Starting verify pass disk 1 on DU1:
BAC - End of disk 1 on DU1:
BAC - Mount disk 2 on DUl: . Press "RETURN" when done
BAC - Starting disk 2 on DUl:
BAC - End of disk 2 on DU1:
BAC - Starting verify pass disk 2 on DU1:
BAC - End of disk 2 on DU1:
BAC - Mount disk 3 on DU1: . Press "RETURN" when done
BAC - Starting disk 3 on DU1:
BAC - End of disk 3 on DU1:
BAC - Starting verify pass disk 3 on DU1:
BAC - End of disk 3 on DU1:
BAC - Mount disk 4 on DU1: . Press "RETURN" when done
BAC - Starting disk 4 on DU1:
BAC - End of disk 4 on DU1:
BAC - Starting verify pass disk 4 on DUl:
BAC - End of disk 4 on DU 1:
BAC - Completed
This example shows a back up of the fixed disk to several diskettes.
You must use the SAVE option with the /IMAGE qualifier when doing a
multiple diskette backup operation.

5-102

HANDLING DEVICES AND VOLUMES

BACKUP (Cont.)
$ BACKUP/INI/IMAGE:RES/VER DUl: DU0:
BAC - Mount disk 1 on DUl: . Press "RETURN" when done
BAC - Starting disk 1 on DU1:
BAC - End of disk 1 on DU1:
BAC - Mount disk 2 on DUl: . Press "RETURN" when done
BAC - Starting disk 2 on DU1:
BAC - End o f disk 2 on DU 1:
BAC - Mount disk 3 on DU1: . Press "RETURN" when done
BAC - Starting disk 3 on DU1:
BAC - End of disk 3 on DU1:
BAC - Mount disk 4 on DU1: . Press "RETURN" when done
BAC - Starting disk 4 on DU1:
BAC - End of disk 4 on DU1:
BAC - Mount disk 5 on DU1: . Press "RETURN" when done
BAC - Starting disk 5 on DU1:
BAC - End of disk 5 on DU1:
BAC - Completed
This example shows a diskette restore operation to the fixed disk.
You must specify the RESTORE option on the command line with the
/IMAGE qualifier when restoring several diskettes to the fixed disk.

5.12.4 Messages
There are instances when you may receive informational, warning, or
error messages.
Informational messages do not require a response.
They give you information such as whether the operation is complete or
whether another disk is being verified. Warning messages are usually
There are also fatal
not fatal, but may represent a severe error.
messages which terminate the operation.
This section contains a listing of the BACKUP error messages you may
receive, with a description of the problem and the action you should
take.
Note that if you cannot find an error message in this section
That section describes and suggests
(5.12.4), check Section 5.12.4.1.
action for error messages (preceded by the mnemonic BRU instead of
BAC) you may receive from the BRU utility.

5-103

HANDLING DEVICES AND VOLUMES

SHOW ASSIGNMENTS
SHOW LOGICALS (Cont.)
/GROUP[:g]
Displays the group logical assignments for users with
specified User Identification Code (UIC) group number, g.

the

Nonprivileged users can see the group logical assignments of
their own group.
In this case, you can either specify /GROUP
without an argument or use your own group number as the argument.
Only privileged users can see the logical assignments of other
groups.
This qualifier
logical names.

is valid

only if

your

system

supports

extended

/LOCAL
Specifies that local and login logical assignments for your
terminal
are to be displayed on your terminal.
This is the
default.
/LOGIN
Specifies that local and login logical assignments for your
terminal are to be displayed on your terminal. This is a
privileged qualifier.
/TERMINAL:ttnn:
Specifies that local and login logical assignments for terminal
ttnn: are to be displayed on your terminal.
This is a
privileged qualifier.
You can also use this qualifier with
logical assignments for terminal ttnn:.

/ALL to

see all of the

Examples
$ SHOW
Function? ASSIGNMENTS
LP0:
LOCAL
DU1:
TP0:
TT1:
LOCAL
DY1:
LOGIN
SY0:

TI - TT1:
TI - TT1:
TI - TT1:

This example (only for systems without extended logical name support)
shows the display of your local and login logical assignments. The
logical name (terminated by a colon) is displayed first, followed by
Finally, the type of assignment and your terminal
the device name.
number are given.
You can use these logical names in place of device specifications.
Output to LP0: will actually go to DU1:. Output to TP0: will go to
TT1:, which is TI:. In addition, the user has the login assignment of
SYO:
to DY1:.
This means that DY1: is the default device for this
user.

5-130

HANDLING DEVICES AND VOLUMES

SHOW ASSIGNMENTS
SHOW LOGICALS (Cont.)
$ SHOW
Function? ASSIGNMENTS
LP0 = DU1: (Local, TT:)
INFILE = DU0:[DANIEL]ADDRESS.TXT (Local, TT:)
@@PE&& WISS = STRANGE string (Login, TT:)
SYS$LOGIN = DU0: [SAMUAL] (Login, Final, TT:)
This example shows the display of your local and login logical
assignments.
The logical name is displayed first, followed by the
equivalence name.
Finally,'the type of assignment and your terminal
number are given.
You can use these logical
names in place of device and file
specifications.
References to LPO will actually go to DU1:. The file
ADDRESS.TXT, which is located on device DU0: in directory [DANIEL],
is an input file for a task that specifies the logical name INFILE.
In addition, the string "STRANGE string" is the translation of the
logical
name
"@@PE&& WISS".
Finally, the user has given the login
assignment of SYS$LOGIN to DU0:[SAMUAL].
This means that DU0:[SAMUAL]
is the default device and directory for this user.
$

SHOW ASSIGNMENTS/LOCAL

This example is the equivalent of the previous example.
$ SHOW ASSIGNMENTS/ALL
WK = LB: (Global, Final)
TEXT = DU0:[SYSTST]LOGIN.TXT (Local, TT:)
SYS$LOGIN = DU: (QUERY] (Login, Final, TT:)
This example displays all the logical assignments (local, login,
global, and
system)
for your
terminal.
The system has given the
global logical name WK to the pseudo device, LB:
and the login
logical name SYS$LOGIN to the directory, DUO:[QUERY].
The user has
given the local
logical
name TEXT to
the file
specification,
DUO: [SYSTST] LOGIN.TXT.
$ SHOW ASSIGNMENTS/TERMINAL:TT3:
MP0 = SY0: (Local, TT3: )
This example, which requires a privileged terminal and a terminal
(TT3:)
that is logged in, displays the
logical assignments for
terminal TT3:.
This user has given the local logical name MP0 to the
pseudo device, SY0:.
$ SHOW ASSIGNMENTS/GLOBAL
WK = LB: (Global, Final)
IN0 = SY0: (Global, Final)
EX0 = SY0: (Global, Final)
This example, which requires a privileged terminal, displays all
global logical names.

5-131

HANDLING DEVICES AND VOLUMES

SET DEVICE (Cont.)
/[NO]LOWERCASE
The /LOWERCASE attribute sets a terminal or line printer so that
lowercase characters are not converted to uppercase for printing.
attribute sets a terminal or line printer so
The /NOLOWERCASE
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
This
The /PUBLIC attribute sets the device as a public device.
command also mounts the device. Public devices are accessible to
all users.
The /NOPUBLIC attribute removes the public status of a device.
This is the default setting.
/[NO]SYSTEM is a synonym included for VAX/VMS compatibility.
Chapter 4, contains a discussion of public and private devices.
/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 15 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 their terminals using
either the SET DEVICE/WIDTH:n command or the SET TERMINAL/WIDTH:n
command.
Examples
$ SET
Function? DEVICE
Device? LP10
Attribute? WIDTH:80
This example sets the I/0 buffer size
characters on the line printer LP0:.

5-133

(line

length)

80 (decimal)

HANDLING DEVICES AND VOLUMES

SET DEVICE (Cont.)
$ SET DEVICE:LP0:/LOWERCASE
This example sets LP0: 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 DEVICE:DL3:/CHECKPOINT_FILE:256
This example creates a checkpoint file of 256 (decimal) blocks on DL3:.
Note
SHOW DEVICES displays the attributes set by SET DEVICE.
Error Messages

SET---Feature not supported
Explanation:
The command specified an optional feature that was
not incorporated into the system at system generation.
User Action: See your system manager.

SET---Pseudo device error
Explanation:

Command attempted to set a pseudo device public.

A pseudo device cannot be set public.
User Action:
command using the physical device name.

Retype

the

SET---Write check not supported
Explanation: Command attempted to enable write-checking on a
device that does not support it.
User Action:

Write-checking is not supported on magnetic tapes

or RL01s .

5-134

HANDLING DEVICES AND VOLUMES

SHOW DEVICES (Cont.)
UNLOADED
Indicates that a loadable device driver is currently not loaded.
SPOOLED
Indicates
Manager.

that

device

under

the

control

of the Queue

WCHK=
NOWCHK=
Indicates a device with write-checking enabled or not enabled.
Examples
$ SHOW DEVICES
PUBLIC MOUNTED LOADED TYPE=RP06
DB0:
PUBLIC MOUNTED LOADED TYPE=RP06
DB1:
DB2:
PUBLIC LOADED TYPE=RP04
TT3: - PRIVATE MOUNTED LOADED TYPE=RM03
DR0:
PUBLIC MOUNTED LOADED TYPE=RM05
DR1:
PUBLIC MOUNTED LOADED TYPE=RM80
DU0:
LP0:
DB0: SPOOLED LOADED
DB0: SPOOLED LOADED
LP1:
TTO:
CO0:
TT0:
LOADED
TT1:
[7,40] [1,1] - LOGGED ON LOADED
TT2:
[7,40] [14,10] - LOGGED ON LOADED
TT3:
[303,5] [303,5] - LOGGED ON LOADED

TT66:
TT67:
NLO:
VTO:
VT1:
VT2:
VT4:
TI0:
CL0:
SP0:
LB0:
SY0:

LOADED
LOADED
LOADED
LOADED
LOADED
[1,1]
[303,5]

[1,1] - LOGGED ON LOADED
[303,5] - LOGGED ON LOADED

TT0:
DB0:
DB0:
DB0:

All devices and
This example shows the display from SHOW DEVICES.
For terminals, the current directory is
pseudo devices are included.
shown. The only information shown for pseudo devices is the name and
Privileged users also see
the device to which they are redirected.
volume labels.

5-137

HANDLING DEVICES AND VOLUMES

SHOW DEVICES (Cont.)
$ SHOW DEVICES DU:
DU0:
PUBLIC MOUNTED LOADED LABEL=MICRORSX TYPE=RD51
DUl:
PUBLIC MOUNTED LOADED TYPE=RD51
DU2:
PUBLIC LOADED TYPE=RX50
OFFLINE LOADED TYPE=unknown
DU3:
This example displays information about all devices of the type DU:.
The mnemonic (DUnn:) identifies the device controller and the model
name (RD51) indicates the physical device type.
$ SHOW DEVICES/PUBLIC
PUB=DU0:
PUB=DU1:
PUB=DU2:
PUB=LP0:
Public
This example displays information about all public devices.
devices are accessible to all users. They may be mounted by any users
to assure continued access to the volume mounted on the device.
$ SHOW DEVICE: LP0:/WIDTH
BUF=LP0:00132.
$ SHOW DEVICE:TT11:/WIDTH
BUF=TT11:00080.
This example displays the line lengths of a line printer and a
by the size of the I/O
is determined
terminal.
The line length
buffer, which is established through SET DEVICE:ddnn:WIDTH.

5-138

LINK AND LIBRARY COMMANDS
6.3.1

Object Files as Input to the Task Builder

The assembler or compiler processes the source code that you have
The assembler produces an
written and produces the object file.
object file from assembly language source code. The compiler produces
an object file from high-level language source code. An object file
contains nondisplayable binary code. The object file must be named
and must be a discrete part of the necessary code needed to create an
executable task.
The object file is then called a module (an object
module).
A task may contain one or more modules, each of which
contains a separate logical part of the task.
Separate modules are
used for the following reasons:
Separate modules may be written by different persons.
Separate modules may contain discrete logical parts of a task.
For example, a task that does calculations may have an add
module, a subtract module, a multiple module, and so forth.
The same module may be used by different tasks though included
at separate times for those tasks; therefore, it need be coded
only once. For example, many tasks can do addition and use
the same add module if the module and tasks are designed
properly.
A task divided into logically discrete parts makes the task
easier to understand and debug.
A module may contain coded routines, each of which is usable
by several
tasks.
A module coded in this way is called a
library.
Section 6.3.2 discusses libraries.
See also the
discussion of the LIBRARY command in Section
6.6.
The Task Builder accepts one or more object module files from a disk
and creates a task from them.
When you use the LINK command, described in a later section, you can
specify one or more object files as input to the Task Builder. Object
files have an .OBJ
file type.
The following example will begin to
familiarize you with the required form of the LINK command when you
use object files as input to the Task Builder:
$ LINK/TASK MODULE1.OBJ,MODULE2.OBJ,MODULE3.OBJ
This LINK command shows three object modules as input to the Task
Builder.
The Task Builder combines them to create one task named
You would run this task by issuing the command RUN
MODULE1.TSK.
You need not specify .OBJ as a file type in the LINK command
MODULE1.
file
because the Task Builder assumes that an input file has an .OBJ
However, the file must actually have this file type.
type.

6.3.2

Library Files as Input to the Task Builder

A library file is another kind of object file and it has an OLB file
type.
However, a library file is coded with a special purpose in
mind. What the library file contains is coded routines that may be
commonly used by your task and other tasks. Your task would then call
the routines in the library file when they are needed.
This saves a
lot of time and effort because, in many applications for specific
business sites, many routines are useful for a wide range of programs.
These routines may include, for example, specific kinds of calculating
routines such as addition or multiplication, or certain kinds of
graphic charts.
The DCL LIBRARY command is used for maintaining
libraries (see Section 6.6).

6-4

LINK AND LIBRARY COMMANDS
The LINK command has two ways of specifying a library file in the
command line.
The first is shown next as an example. The two ways
are more fully described in a later section. Here is a LINK command
that uses an entire library module:
$ LINK/TASK TASKMOD.OBJ,LIBMOD.OLB/LIBRARY
The first
This LINK command creates a task from two input files.
input file
is TASKMOD, which is an ordinary object file. The second
input file is LIBMOD, which is a library file. In this example, the
The LIBMOD.OLB
TASKMOD file refers to and uses the LIBMOD library.
file has a special /LIBRARY qualifier on it.
The qualifier denotes
that LIBMOD
is
a library.
With this command, the routines in the
library that the task references become part of the task.
The .OLB file type used in the previous LINK command is understood to
be present because of the /LIBRARY qualifier; therefore, the default
file type for a library used in this way is .OLB. That is,
the
.OLB
file type need not be specified in the LINK command line, but the file
must actually have those file types.

6.3.3

Overlay Description Files as Input to the Task Builder

The overlay description file is a special file unlike the object files
that
have
been
previously
discussed.
It
contains special
mathematical-like language that contains the names of object files and
file
libraries
in an algebraic relationship.
This file has the .ODL
type.
It is best to mention here that this chapter does not describe
overlays at all; nor does it describe overlaid tasks in great detail.
and
complete
Overlays are an advanced
topic for programmers,
in the RSX-11M/M-PLUS and Micro/RSX Task
information
is available
However, a simplified description of an overlaid task
Builder Manual .
follows:
An overlaid task is one in which parts of the task are not always
together
in memory.
Some parts of the task may be on the disk and
some in memory at different times during task execution. When a part
of the task that is on disk is called into memory, it may be read into
memory over another part of the task already in memory.
This action
and
interaction between disk and memory and parts of tasks can get
That is the reason for the overlay description file.
quite complex.
The overlay description file (.ODL file) describes the relationship
between the parts of the
task and libraries in such a way that
everything works correctly at the right time during task execution.
that needs to be specified when you build an overlaid
The only file
task is the overlay description file. The overlay description file
contains all the necessary logical relationships and module names for

6-5

LINK AND LIBRARY COMMANDS
the task to build correctly. Therefore, you may see a
that looks like one of the following:

LINK

command

$ LINK/TASK INPUTFILE.ODL/OVERLAY_DESCRIPTION
or
$ LINK/TASK/OVERLAY_DESCRIPTION INPUTFILE
These two LINK commands specify that a task is to be built using a
single
input file that describes an arrangement of overlays for the
If you use the /OVERLAY_ DESCRIPTION qualifier, the Task Builder
task.
assumes the .ODL file type. No other files need to be mentioned as
input files because all the other files are designated in the .ODL
file.
The /OVERLAY DESCRIPTION qualifier can be in either part of the
LINK command; that is, to the left of the blank space as a command
qualifier,
or appended to the input file as an input file qualifier.
The /OVERLAY DESCRIPTION qualifier specifies that the single input
file describes how the task is to be built and overlaid. The .ODL
file type is understood to be the default file type if you specify
/OVERLAY_DESCRIPTION.
Therefore, you need not specify .ODL in the
command line in this case, even though the file must actually have
that file type.

6.3.4

Command Files as Input to the Task Builder

The command file is another special file unlike all the other Task
Builder
input files. The command file contains Task Builder commands
in a special language and syntax only usable by the Task Builder.
This file contains all the commands needed
to build a task. Because
the Task Builder is large and complex, the command file may contain
many commands, qualifiers, and options not mentioned in this simple
Task Builder and LINK command description. However, you need not know
how to create a Task Builder command file at this time. The only
knowledge you require at this point is how to use the LINK command to
The following example
build a task by using a command file.
illustrates this:
$ LINK @BUILDFIL.CMD
Command files have a CMD file type. The file type need not be used
in the LINK command because CMD is understood to be the default file
type. However, the file must actually have a CMD file type. The at
sign (@) designates that the system is to process the command file and
send the commands that it contains to the Task Builder.

6.4

THE TASK BUILDER FUNCTIONS

After you have coded a program in a programming language and then
file
compiled it, the result is an object file; this file has an .OBJ
However,
a
large
program
can
be
coded
and
compiled
in
one
or
type.
more discrete sections or parts called modules. When this is done,
all the modules should have a unique name. Every programming language
has a statement in it that you can use to name the module. Also, all
For example,
the modules will probably have defined unique symbols.
these symbols may be labels of routines in the code. The work that

6-6

LINK AND LIBRARY COMMANDS
remains is the job of the Task Builder. Simply explained, the Task
Builder does the following:
1.

Puts the modules in a single unit called a task (with a
file type) that has a logical order of code.

TSK

Arranges the addresses of the combined modules in sequential
order.

Assigns addresses to symbols and makes any global symbols
known to the entire task. Not all symbols are global ones;
some may need to be known only to a single module.

6.4.1 Creating a Task
The Task Builder uses files that have the .OBJ
file type to create a
task.
The resulting task has a TSK file type. The .OBJ
files are
files that have binary coded information arranged in certain ways.
These files are not printable or readable on a terminal. If you were
able to see one, it would be a very long string of binary numbers like
these:
0110001101011000111000101011101000101000001ll
An object file cannot be executed by
a computer system.
The Task
Builder takes one or more object files and arranges them into a single
unit of binary code called a task. The Task Builder also affixes to
the task certain structures that are used by the RSX-11M-PLUS system
code.
The LINK command, discussed in the next section, is the command you
use to
invoke the Task Builder and create a task from one or more
object modules.
However, for now, the following is an example LINK
command line that creates one task from three modules:
$ LINK/TASK:MYCODE MODULE1,MODULE2,MODULE3
Here, the LINK command line causes the Task Builder to create a single
task called MYCODE from three modules.
The modules are separately
coded and were named differently. However, the entire program could
have been coded as a single module and the single object module would
have only one name.

6.4.2 Arranging Addresses
Every unique module that you code has addresses ranging from 0 through
the highest address in the module. In other words, the beginning of
the code in each module starts at 0 and ends at the highest address.
If a task is to be constructed out of several modules,
each module
will have different information at the same numeric address.
The
program cannot work this way. Therefore, when combining the modules,
the Task Builder assigns new addresses to all the module statements.
This assignment results in a single task that has a single address of
0 at the beginning. The addresses are then sequential from that point
through the end of the task. Figure 6-1 shows the relationships among
addresses for a 3-module task.

6-7

LINK AND LIBRARY COMMANDS

LINK
6.5

THE LINK COMMAND

The LINK command invokes the Task Builder, a system utility that
builds the tasks, 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
Thus, you can use qualifiers to the LINK
included
in
the defaults.
command to perform the following functions:
Create TKB output files in addition to the task image file
Identify certain kinds of unusual tasks
Use hardware options that may not be present on all systems
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 specify in the LINK command line and, therefore, pass to
the Task Builder, an object file (default file type .OBJ) produced by
the MACRO-11
Relocatable Assembler or one of the high-level language
The Task Builder then produces a runnable task image. The
compilers.
following command invokes the Task Builder:
$ LINK
File(s)?SAMPLE
The
This command produces a single output file called SAMPLE.TSK.
sign
prompt
($)
tells
you
that
the
task
build
return of the dollar
completed successfully.
If, in addition to the task image file, you 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.
The Task Builder spools SAMPLE.MAP to the line printer and puts
SAMPLE.MAP in your directory.
The following command also requests that a map file be created:
$ LINK SAMPLE.OBJ/MAP
The Task
This produces two output files, SAMPLE.TSK and SAMPLE.MAP.
SAMPLE.MAP in your directory, but does not spool it to
Builder puts
the line printer.

6-10

LINK AND LIBRARY COMMANDS

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 following command:
$ LINK MOE, CURLY, LARRY
produces a task image file named MOE.TSK. That is, LINK uses the name
of the first
input
file,
MOE, as the name of the task unless you
change the name of the task. Use the /TASK qualifier to change the
name of the task image file. For instance, the following command:
$ LINK/TASK:SHEMP MOE, CURLY, LARRY
produces a task image file named SHEMP.TSK.
command:

Or,

use

the

following

$ LINK MOE, CURLY/TASK, LARRY
$
to produce a task image file named CURLY.TSK.
Note, however, that the following LINK command:
$ LINK/MAP MOE, CURLY/TASK, LARRY
produces a task image file named CURLY.TSK and a map file named
MOE.MAP because MOE is the first input file. If you use the following
form:
$ LINK/MAP:SAM MOE,CURLY,LARRY
the map file is named SAM instead of MOE.
If, in addition, you want the task build to abort after the Task
Builder finds three errors, issue a command such as this:
$ LINK/MAP/ERROR_LIMIT:3 SPARKY
As before, this produces two output files:
the task image named
SPARKY.TSK,
and
the map named SPARKY.MAP.
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. If you specify the /OPTION
qualifier
in your LINK command, LINK prompts you for further input.
For example
$ LINK/MAP/OPTIONS BIGJON
Option? UNITS=7
Option?

6-11

LINK AND LIBRARY COMMANDS

LINK (Cont.)
The UNITS option specifies the number of I/0 units for the task.
There are more than two dozen options you can specify. They are
listed in Table 6-1.
If you want to specify options, there are two ways of doing so.
You
must first
include the /OPTION qualifier in your LINK command. You
will be prompted Option? Then, you can do the following:
1.

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.

Specify options in a separate file.
When prompted by
Option?,
simply name that file with a preceeding at sign (@)
and then press RETURN.

Specify options in a seperate file and name that file as an
argument to the /OPTIONS qualifier. Note, however, that you
will not be prompted for options.

Here are three examples.
$LINK/MAP/OPTIONS BIGJON
Option? UNITS=7
Option? ASG=SY0:6:7
Option?
or
$ LINK/MAP/OPTIONSBIGJON
Option? @SPARKY.CMD
Option?
$
or
$ LINK/MAP/OPTIONS:@SPARKY.CMDBIGJON
The LINK command and its qualifiers are all DCL commands,
and the
The Task Builder, however, does not recognize
format
is DCL format.
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 checks it for correct DCL
format.

DCL translates the command line into correct TKB format.

DCL places the TKB-format command in a TKB indirect command
the Task
file and passes the
indirect
command file to
Builder.

6-12

LINK AND LIBRARY COMMANDS

LINK (Cont.)
4.

The Task Builder builds the task as directed and creates all
requested output files.

The Task Builder returns control to DCL and DCL deletes the
TKB indirect command file.

If you are building standard tasks by using the defaults and by
following
the examples given in the command description (Section
6.5.2), this process will serve you well.
However, you will have to refer to the RSX-11M/M-PLUS and Micro/RSX
Task Builder Manual for information on how the Task Builder responds
to your LINK command. The Task Builder manual explains all the output
files produced by TKB and how TKB interprets your LINK command. It
explains all the options, defines all the terms used in the TKB
environment,
and elucidates the capabilities of this complex and
flexible software tool.
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.
Because TKB format and DCL format are different, understanding how the
LINK command works with the Task Builder commands 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.TMP. This file
is also useful if you want to repeat a particular task build. See the
discussion of the /SAVE qualifier in Section 6.5.1.
The following description should help you switch from DCL format to
TKB 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 Task Builder can
produce up to three kinds of output
files.
See the following
examples:
The following DCL command:
$ LINK SAMPLE.OBJ
produces the following command in TKB format in the TKB indirect
command file:
TKB>SAMPLE.TSK=SAMPLE.OBJ
In this first example, the Task Builder takes SAMPLE.OBJ as its input
file and produces one 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 (=).

6-13

LINK AND LIBRARY COMMANDS

LINK (Cont.)
The following DCL command:
$ LINK/MAP SAMPLE.OBJ
produces the following command in TKB format:
TKB>SAMPLE.TSK,SAMPLE.MAP=SAMPLE.OBJ
In this second example, the Task Builder takes SAMPLE.OBJ as its input
SAMPLE.TSK and SAMPLE.MAP.
The
file and produces two output files:
map file takes the second position in the list of TKB output files to
the left of the equal sign.
The following 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 this third example, the Task Builder takes SAMPLE.OBJ as its input
file and produces three output files: SAMPLE.TSK, SAMPLE.MAP, and
The output file type STB is called a symbol definition
SAMPLE.STB.
file and
it takes the third position in the list of TKB output files
to the left of the equal sign.
In TKB format, you can alter the output file by adding switches
(consisting of a slash and two letters)
to each output
file
specification.
For example, the following DCL command:
$ LINK/CODE:FIS SAMPLE.OBJ
produces the following command in TKB format:
TKB>SAMPLE.TSK/FP=SAMPLE.OBJ
In this case, the Task Builder builds a task that uses the Floating
Point Processor, which is optional hardware.
Qualifiers can also be used on map files. The following

DCL command:

$ LINK/CROSS REFERENCE SAMPLE.OBJ
produces the following command in TKB format:
TKB>SAMPLE.TSK,SAMPLE.MAP/-SP/CR=SAMPLE.OBJ
In this case, the Task Builder map includes a listing of symbol
cross-references in the program. DCL does not require you to use the
/MAP qualifier if you use another qualifier (such as /CROSS -REFERENCE)
that implies that you want a map file.
follows,
that
In the description of the LINK command
qualifier is identified with its equivalent in TKB format.

6-14

each

DCL

LINK AND LIBRARY COMMANDS

LINK (Cont.)
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
following form:
$ LINK @SHEMPBLD
and duplicate the task build that originally produced the command
file.
syntax with
This file is also useful for comparing LINK command
TKB syntax because it includes the full translation of the LINK
command into TKB format.
/[NO]SEGREGATE
Causes the Task Builder to order program sections alphabetically
by name within access code (RO followed by RW). If you also
specify the /SEQUENTIAL qualifier, TKB orders program sections in
their input order by access code.
TKB interleaves RO
The /NOSEGREGATE qualifier is the default.
When
combined
with
the /SEQUENTIAL
program
sections.
and RW
qualifier, the /NOSEGREGATE qualifier results in a task with
in input order with its RW and RO
program sections allocated
and
/NOSEQUENTIAL
If you use
the
sections
interleaved.
qualifiers
together,
which
is
the
default
for
both,
/NOSEGREGATE
alphabetically with RW and RO
TKB orders program sections
sections interleaved.
In
TKB format,
specification.

use

the

.TSK

/[-]SG switch on the

file

/SEQUENTIAL
Directs Task Builder to construct a task image from program
in the order in which they appear. Generally, the Task
sections
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
allocation of program
build
tasks that rely on alphabetical
sections, such as FORTRAN I/O handling modules and FCS modules
See also the /SEGREGATE qualifier discussion.
from SYSLIB.
In TKB format,
specification.

apply

/SQ

the

/SHAREABLE[:arg]
TASK
COMMON
LIBRARY

6-25

switch

the

.TSK

file

LINK AND LIBRARY COMMANDS

LINK (Cont.)
Table 6-1 (Cont.)
Task Builder Options
Description and
Language Key

Format and Defaults

Alterations
Declare series of patch
values; patches I-space
in I- and D-space
tasks (M)

ABSPAT=seg-name:address:val-1 . . .
(up to 8)
No default

Declares series of patch
values; patches D-space
of I- and D-space tasks

DSPPAT=seg-name: address:val-1 .
(up to 8)
No default

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

No default

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-name:vector-length
No default

Include specified symbols
in .STB file (M,H)

GLBINC=symbol-name,symbol-name,...,symbol-name
No default

. .

GBLXCL=sym1:sym2:...:symn

Examples
$ LINK
File(s)? WRAY
This example task builds the object file WRAY.OBJ into the task image
file WRAY.TSK.
For the LINK command to work properly, WRAY.OBJ must
be an object file. Because 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 dollar sign
completion of the task build.

prompt

($)

$ LINK WRAY
This example is equivalent to the previous one.

6-34

indicates

successful

LINK AND LIBRARY COMMANDS

LINK (Cont.)
$ LINK/MAP WRAY
This example is similar to the previous two except that a Task Builder
When the task build is completed, the map
map is also requested.
WRAY.MAP is spooled to the line printer,
and also appears
in your
directory.
$ LINK/MAP:NEWLINK WRAY
This example is similar to the previous one, except that a file
specification is provided with the /MAP qualifier. When the task
your
build is completed, the map file NEWLINK.MAP appears in
directory.
If you want a copy of this file, issue a PRINT command.
$ LINK WRAY/MAP
In
This example illustrates another way of using the /MAP qualifier.
this case, when the Task Builder exits, a file called WRAY.MAP appears
If you
in your directory, but is not spooled to the line printer.
want a copy of this file, issue a PRINT command.
$ LINK/DEBUG WRAY
This example builds the task WRAY.TSK including ODT.
$ LINK/OPTIONS WRAY
Option? UNITS=8
Option?ASG=TT0:7:8
Option?
The
This example illustrates the use of the /OPTIONS qualifier.
command sequence builds the task with eight logical units (LUNs), with
LUNs 7 and 8 assigned to TTO:. (See the discussion in Section 6.1.1.)
The entire LINK command is entered by the final RETURN in response to
the Option? prompt.
$ LINK/OPTIONS/NOMEMORYMANWRAY
Option? PAR=KROBAR:50000:40000
Option?
This example builds the task to run on an unmapped system in the
KROBAR, which has a base address of 50000 and a size
partition named
of 40000.
$ LINK/CHECKPOINT:SYSTEM WRAY
$ LINK/CHECKPOINT WRAY
The commands in this example are equivalent.
checkpointable to the system checkpoint file.

6-35

The

task

built

LINK AND LIBRARY COMMANDS

LINK (Cont.)
$ 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, 3TRACK
Option?TASK=SHACK
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
WRAY, 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
Language.
Only one file can be specified with this
Description
called
qualifier.
The files that
form the overlaid task are
automatically.
$ LINK @WRAYBLD
This example specifies the indirect command file WRAYBLD.CMD as input
file must be written in Task Builder
to the Task Builder.
This
format, not DCL format. This file can be the ATLNK.TMP file renamed.
See the discussion for the /SAVED qualifier.

6-36

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
Parameters
1ibspec
The
Specifies the name of the library file to be compressed.
default type
is
.OLB, specifying an object module library. If
you
want to compress a macro library (standard file type .MLB),
library
(standard file type .ULB),
you must
or
a
universal
specify the file type explicitly.
newlibspec
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 parameter is optional.
this command.
Arguments
If you are specifying more than one argument, the arguments must be
separated by commas.
If you are
enclosed
in parentheses and
specifying only one argument, the parentheses are not necessary.
GLOBALS:n
Specifies the number of global symbols (entry point table
The default value for n is the number of
entries)
to allocate.
global symbols allocated in the old library. The maximum value
for
n
is 4096.
The value of n is always forced to 0 for macro
and universal libraries.
MODULES:n
Specifies the number of entries to allocate in the module name
table.
The default value is the number of entries in the old
The maximum number of module names is 4096.
library.
BLOCKS:n
Specifies the size of the library in 256-word blocks.
default size is the size of the old library.

The

Example
$ LIBRARY/COMPRESS LB: [001001]SYSLIB.OLB
This example compresses the system object module library.

Note
This command is equivalent to the LBR /CO switch applied to a library
file.
If you like, you can use LIBRARY/LIST before and after compressing a
library to see the effects of the compress operation.

6-41

LINKAND LIBRARY COMMANDS

LIBRARY (Cont.)
Example
$ LIBRARY
Operation? CREATE: (GLOBALS:128,MODULES:64)
Library? 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 then
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 on the
output file.
Expanding
Tables should be allocated to maximum anticipated size.
table allocations requires using LIBRARY/COMPRESS to copy the entire
file.
If
the qualifiers /SELECTIVE_SEARCH and /SQUEEZE are
LIBRARY/CREATE, you must specify an input file or files.

used

with

The /SQUEEZE qualifier causes all text to the right of the rightmost
to be deleted. This convention permits you to preserve any
semicolon
to its right.
meaningful semicolon by adding another semicolon
Examples of meaningful semicolons include using the ASCII value of the
semicolon in code, or a semicolon marking a comment you want to
line of code moves the ASCII value of the
preserve.
The following
semicolon to register 1:
MOVB #';,R1
However, the code emerges after the /SQUEEZE as the following:
MOVB

To preserve the meaningful semicolon, use the following form:
MOVB

#';,R1 ;THIS DUMMY COMMENT SAVES THE CODE

which emerges after the /SQUEEZE as the following:
MOVB

#';,R1

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 the following:
;NEXT 5 LINES ARE CRUCIAL
Keep this convention in mind whenever you are using the /SQUEEZE
qualifier.

6-44

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)

6.6.3 LIBRARY/DELETE
modules
from
any
library.
See
the
LIBRARY/DELETE deletes
LIBRARY/REMOVE qualifier discussion for information on removing global
symbols (entry points) from a library.
Format
LIBRARY/DELETE libspec module[,s]
Parameter
libspec
Specifies the
deleted.

name of the

library

from

which modules

are

to be

module[,s]
Specifies the modules that are to deleted. You can specify as
many as 15 names of modules to be deleted, separated by commas.
If you do not specify the module list, you will be prompted for
it.
Example
$ LIBRARY/DELETE
Library? BUMPERS
Module(s)? BUGGY, BABY, RUBBER
Modules deleted:
BUGGY
BABY
RUBBER
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 applied to the
output file.
When you delete an entry from a library, the entry is not physically
removed, but is marked for deletion.
This means that although the
module is no longer accessible,
the file space it occupied is not
available.
To clear this space, use the LIBRARY/COMPRESS operation,
Section 6.6.1.

6-45

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
Command Qualifier
/OUTPUT
Specifies the file to which the extracted modules or macros are
If you specify the /OUTPUT qualifier without a
to be written.
file specification, 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 file specification. You can reply
TI:
to have the output printed on your terminal.
Examples
$ LIBR/EXTRACT/OUTPUT:MATH LB0:[001001]SYSLIB ARITH
library
This example extracts the module named ARITH from the
The module is placed in the
system object library.
SYSLIB.OLB,
the
default directory as a file named MATH.OBJ.
$ LIBR/EXTRACT/OUT:TI: LBO:[001001]RSXMAC.SML STOP$S
.MACRO STOP$S ERR
.MCALL DIR$
MOV
(PC)+, -(SP)
.BYTE
131.,1
DIR$
,ERR
STOP$S
.ENDM
This example extracts the macro named
library and spools it tothe terminal.

STOP$S

from

the

system macro

Note
This command is the equivalent of the
library file as the input file.
LIBRARY/EXTRACT has no effect
are extracted.

6.6.5

LBR /EX

on the library

switch applied

from which

the

to the

modules

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

6-47

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
Macros that have been squeezed not only take up less room in the
macro library file but also take up less memory.
See the Notes to Section 6.2.2 for important information on the
/SQUEEZE qualifier.
This command is the equivalent of the LBR /SZ switch applied to
the output file.
Example
$ LIBRARY/INSERT
Library? LB0:[001001]SYSLIB
Module(s)? USERSUB
This example inserts object modules from the file USERSUB.OBJ into the
system object module library, LB0:[001001]SYSLB.OLB.
Notes
This command is the equivalent of the LBR /IN command.
Note that a single input file can contain more than one object module
or macro.
If you are inserting macros into a macro library,
LIBRARY/INSERT
inserts only the .MACRO and .ENDM lines and what appears between 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
Use
the
have taken
place.
operations past that point will
LIBRARY/LIST qualifier to check which modules have been inserted and
which have not.

6-49

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
Examples
$ LIBRARY/LIST LB0:[001001]SYSLIB
Directory of file SYSLIB.OLB;1002
Object module library created by: LBR V06.00
Last insert occurred 25-MAY-85 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
ALERR
ALSCT
ALTPRI
ANSPAD
ARITH

This example shows the default display from LIBRARY/LIST.
Only the
module names appear. The information appears on your terminal.
$ LIBRARY/LIST/FULL LB0:[001001]SYSLIB
Directory of file SYSLIB.OLB;1002
Object module library created by: LBR V06.00
Last insert occurred 25-MAY-85 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
ALERR
Ident:00
Size:00073 Inserted:22-MAY-85
ALSCT

Size:00134

Inserted: 22-MAY-85

Ident:00

ALTPRI

Size:00081

Inserted:22-MAY-85 Ident:00

ANSPAD

Size:00068

Inserted:25-MAY-85 Ident:20.0P6

ARITH

Size:00088 Inserted:22-MAY-85 Ident:03.03

This example shows the display from LIBRARY/LIS/FULL, which includes
full module descriptions. This information appears on your terminal.

6-51

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
$ LIBRARY/LIST/NAMES LB0:[001001]SYSLIB
Directory of file SYSLIB.OLB;1002
Object module library created by: LBR V06.00
Last insert occurred 25-MAY-85 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:ALTPRI
ALT PR I
** Module:ANSPAD
..ANSP
** Module:ARITH
$DIV

$MUL

This example shows the display from LIBRARY/LIST/NAMES, which lists
entry points for each module.

6-52

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
$ LIBRARY/LIST/FULL/NAMES LB0:[001001]SYSLIB
Directory of file SYSLIB.OLB;1002
Object module library created by: LBR V06.00
Last insert occurred 25-MAY-85 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

Size:00073

Inserted:22-MAY-85 Ident:00

$ALERR
** Module:ALSCT

Size:00134 Inserted:22-MAY-85 Ident:00

ALSCT
** Module:ALTPRI

Size:00081

Inserted: 22-MAY-85

Ident:00

Size:00068

Inserted: 25-MAY-85 Ident:20:0P6

ALTPRI
** Module:ANSPAD
..ANSP
** Module:ARITH

Size:00088 Inserted:22-MAY-85 Ident:03.03

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
DU2: [LAYLA] TT26:
$ LIBRARY/LIST:FRED.LIS LB0:[001001]SYSLIB
LBR -- *FATAL*-Open failure on file FRED.LIS
In this example, the user intended to create a list of the modules in
SYSLIB in the default directory on the default device. The error
This is
message indicates that the listing file cannot be opened.
because
LIBRARY attempted to place FRED.LIS on LB0: in [001001],
where the user did not have file creation privileges.
See the next
example.

6-53

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
$ SHOW DEFAULT
DU2: [LAYLA]
TT26:
$ LIBRARY/LIST:DU2:[LAYLA]FRED.LIS LB0:[001001]SYSLIB
In this example, the user explicitly stated the device and directory
for the listing file and the command succeeded.
Note
This command is the equivalent of applying the LBR /LI, /FU,
switches to the listing file.

/LE

Note that there are four possible listing formats with this command.
( See Command Qualifiers.)

6.6.7

LIBRARY/REMOVE

LIBRARY/REMOVE removes global symbols from a library.
See the
LIBRARY/DELETE qualifier discussion 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 want to remove
global symbols.
global[,s]
Specifies the global symbols you want to remove from the library.
You can specify as many as 15 global symbols.
Example
$ LIBRARY/REMOVE DOUBLE TINKER,EVERS,CHANCE
Entry points deleted:
TINKER
EVERS
CHANCE
This example deletes the globals TINKER, EVERS, and
library DOUBLE.OLB.

6-54

CHANCE

from

the

LINK AND LIBRARY COMMANDS

LIBRARY (Cont.)
Command Qualifiers
/[NO]GLOBALS
Specifies whether (or not) entry points for the specified modules
are to be included in the entry point table. The default is the
/GLOBALS qualifier.
/SELECTIVE SEARCH
Sets the selective search attribute bit in the module header of
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.
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.6.2 for more
information on the /SQUEEZE qualifier.
Example
$ LIBR/REPLACE LB0:[1,1]SYSLIB 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
There must be enough space in the library's tables for both the
modules being replaced and their replacements, because the new modules
are entered before the old modules are deleted.
The old modules are logically deleted only, that is, all references to
those modules are removed, but not the module itself. You must use
LIBRARY/COMPRESS to eliminate the modules and free the space they
occupy.

6-56

LINK AND LIBRARY COMMANDS

SET GROUPFLAGS (Cont.)
Example
$ SHOW GROUPFLAGS
7
0
000000
200
0
000000
$ SET GROUPFLAG
Flag? 303
$ SHOW GROUPFLAG
7.
0
200
0
303
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 is 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-64

LINK AND LIBRARY COMMANDS

SHOW GROUPFLAGS
6.7.2

SHOW GROUPFLAGS

SHOW GROUPFLAGS displays the group global event flags currently in the
system.
Format
SHOW GROUPFLAGS
Example
$ SHOW GROUPFLAGS
7
1
000000 000000
200
1
000000 000000
201
1
000000 000000
303
1
000000 000000
333
1
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 flags 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 the previous section.

6-65

RUNNING TASKS
Blocked

Unable to compete for CPU time because a needed resource
is not available, a synchronization factor is present,
or because the STOP/BLOCK command is in effect (Section
7.6)

You can display the list of active tasks with SHOW TASKS/ACTIVE.
Section 7.14.3.1.

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. These tasks
can then be 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-11M/M-PLUS and Micro/RSX Task Builder Manual for more
information on how tasks are built, installed, and run in partitions.

7.1.1

Task Naming

Tasks are installed under names that are 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. This section describes a number of ways tasks
acquire their installed names.
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 the examples in this section are assumed to have been
issued from terminal TT10:.
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 TT10:
$ SHOW TIME
results in a task named SHOT10 in the STD while the task is executing.
Likewise, the following
VT4:

batch command,

issued

from

virtual terminal

$ SHOW TIME
results in a task named SHOV4 in the STD while the task is executing.

7-2

RUNNING TASKS
The following command, passed through DECnet by host terminal number
6:
SHOW TIME
results in a task name SHOH6 while the task is executing.
terminal is a DECnet virtual terminal.)

(A host

For tasks that are installed and run explicitly, task names can be
established through the LINK command, the INSTALL command, and the RUN
For example, if you begin with a source file named ROBOT.MAC
command.
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 following privileged command:
$ INSTALL ROBOT.TSK
you will find the task name ROBOT in the STD.
If you issue the following command:
$ RUN ROBOT.TSK
you will find the task name TT10 in the STD while the task is
The installation is through the install-run-remove form of
executing.
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 want the task image file you are creating to be installed. If you
thus specify the installed name of ROBOT1.TSK to be EANDO when you
build the task, the following privileged command:
$ INSTALL ROBOT1.TSK
results in the task name EANDO in the STD.
If, however, you issue the following command:
$ RUN ROBOT1.TSK
you will again find the task name TT10 in the STD while the task is
executing, despite the specification of EANDO at task-build time.
The following command:
$ RUN/TASK NAME:EANDO ROBOT1.TSK
results in the task name EANDO in the STD while the task is executing.
The RUN command defaults to a task name that is based on the terminal
must use the
designation (without the colon).
Therefore, you
/TASK NAME qualifier if you want to use the RUN command to initiate
execution of more than one task at a time from the same terminal.
This is because all task names in the STD are unique; that is, you
cannot have two tasks named TT10 installed at the same time. ( See the
examples in Section 7.2.1).
Finally, most DCL commands work by

7-3

RUNNING TASKS
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 LINT10.
In fact,
the RUN
results in the brief existence of a task named RUNT10.

command itself

If you are running a utility, using a command in the following form:
$ MCR PIP
your task will have a name in the form PIP10.
See Section 7.2 for information on including the dollar sign ($) in a
RUN command.
On RSX-11M-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
task name.
The following discussion describes the problem and its
solution.
Remember that terminal numbers are octal. The first 64 terminals on
an RSX-11M-PLUS system are numbered 1 through 77 (octal). The system
supports as many as 256(decimal) terminals. Terminals 65 through 256
are numbered
100 through 377(octal).
Tasks
initiated from these
terminals cannot be named directly after these terminals because their
numbers,
if used explicitly, are too large for task names (which are
limited to six characters). 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 names is employed. See the following example.
Assume your terminal is TT107:. The following command:
$ RUN ROBOT
initiates a task named TTA7. The letter A stands for the first two
digits of the unit number of the terminal, 10 in this case. To
minimize the confusion resulting from this convention, the display
from SHOW TASKS/ACTIVE includes the name of the initiating terminal in
parentheses next to the name of the active task. The SHOW task itself
will be named SHOTA7.
The numbering system replaces the first two digits of the unit number
with a
single letter.
Here
is
a
full list of the possible task
numbers and the equivalent terminal unit numbers:
Task Number
0-77
AO-A7
BO-B7
CO-C7
DO-D7
EO-E7
FO-F7
GO-G7
HO-H7
10-17

Terminal Unit Number
0-77
100-107
110-117
120-127
130-137
140-147
150-157
160-167
170-177
200-207
(continued on next page)

7-4

RUNNING TASKS
Task Number

Terminal Unit Number
210-217
220-227
230-237
240-247
250-257
260-267
270-277
300-307
310-317
320-327
330-337
340-347
350-357
360-367
370-377

J0-J7
K0-K7
L0-L7
M0-M7
N0-N7
O0-O7
P0-P7
Q0-Q7
R0-R7
S0-S7
T0-T7
U0-U7
V0-V7
W0-W7
X0-X7

Only uninstalled tasks initiated with the RUN command have task names
preceded by VT, TT, or HT (or RT).
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 (or R) (for physical, virtual,
or DECnet host terminal) plus the unit number.

7.2

INTRODUCTION TO THE RUN COMMAND

RUN initiates the execution of a task. This command can be used in
four ways:
1.

To install, run, and remove upon execution a task from a task
in a user's directory. This is the most
image
file stored
common use of the command.

To install,
task
image
directory.

To
run immediately
privileged user.

To run at some future time, or according to a schedule, a
task previously installed by a privileged user.

These functions
paragraphs.

are

run,
file

and remove after execution a task from a
stored in the system directory, or library
a

introduced

task

previously installed

detail

the

following

The first and most common use of RUN is to initiate execution of tasks
contained in task image files. The following command:
$ RUN PUPPET.TSK
directs the operating system to look in the default directory on the
default device for a task image file named PUPPET.TSK. When the file
is found, the image is read into 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 file specification,
this procedure is followed. The following command:
$ RUN DU0:MUPPET

7-5

RUNNING TASKS
directs the operating system to do the following:
1.

Look in the default
named MUPPET.TSK.

directory on

device DU0:

for

Install and run the task image.

Remove the task image when it has completed execution.

file

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 the system and library directories. The dollar
sign ($) in a file specification indicates that you want to use this
form of RUN.
Using this convention relieves you of the necessity of
knowing exactly where on the system various system tasks are stored.
Simply include the dollar sign ($) in your RUN command and the system
takes over. If you receive the following 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 directories, perhaps to conserve disk space.
In this case, see your system manager.
In general, you can use the dollar sign ($) to run most system tasks
and utilities.
These usually have 3-letter names like PIP or TKB, but
See
the RMS=11 utilities have 6-letter names like RMSDSP or RMSCNV.
the RMS-11 documentation for more information on RMS-11 tasks and
utilities.
(Your system manager may also have added other task image
files
supplied
by
DIGITAL to these directories for your
not
convenience.)
Copies of many or all privileged system tasks are placed in the system
directory on pseudo device LB:. The directory is usually [1,54], but
it can be some other number. You can display the identity of this
You can list the
directory with the command SHOW SYSTEM/DIRECTORY.
In addition,
contents of the directory with a DIRECTORY command.
copies of many or all nonprivileged system tasks are placed in the
library directory on pseudo device LB:.
The directory is usually
[3,54], but it too can be some other number. You can display the
identity of this directory with the command SHOW LIBRARY/DIRECTORY.
You can also list the contents of the directory with a DIRECTORY
command.
The system responds to the dollar sign ($) in a file specification as
The command:
follows.
$ RUN $TKB
directs the operating system to do the following:
1.

Look for a file called TKB.TSK.

Install and run the task image.

Remove the task image when it has completed execution.

7-6

RUNNING TASKS
Because the Task Builder is a privileged task, it will be found in the
system directory.
The system installs, runs, and removes TKB just
like any other task.
If the command had
following command

named

nonprivileged

task,

such

the

$ RUN $QIX
the system would still have started by searching the system directory,
but,
failing to find QIX.TSK there, would have gone on to the library
directory to search for QIX.TSK there.
NOTE
Privileged users can also use the dollar sign ($) with
the
INSTALL command.
See Section 7.8 for more
information.
The third use of RUN is to execute immediately a previously installed
task.
The
task must have been installed by a prvileged user. The
following command:
$ RUN TURTLE
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 is not
installed by the system (because it is already installed) nor is it
removed when it has completed its execution. The task runs under the
name TURTLE, not TT10.
If the system does not find an installed task of the same name you
give, the command defaults to the install-run-remove form and looks in
the default directory on the
default device for a file named
TURTLE.TSK.
The system then installs, runs, and removes the task, as
described earlier.
Finally, privileged users can use RUN to schedule the execution of a
task in several forms. Scheduling options include the following:
Run the installed task after so many hours, minutes, seconds,
or ticks.
Run the installed task at an absolute time of day.
Run the installed task in synchronization with the beginning
of the next interval, that is, the next hour, minute, second,
or tick.
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-7

RUNNING TASKS
/COMMAND:"taskcommand"
Passes a command to the task you are running. The command must
be inside the quotation marks (") and not more than 40 characters
long.
For example, the following command:
$ RUN/COMMAND:"/LI" MAMBO
runs MAMBO and then passes the /LI switch to it.
/EXTENSION:n
Specifies that n additional decimal words of address space be
allocated to a task.
/[NO]IO_PAGE
Specifies that a privileged task can overmap the I/0 page.
If
you specify /IO_PAGE, RUN assumes that the task will overmap the
I/O page and,
if the task is larger than 8K words,
issues a
warning message.
If you specify /NOIO_PAGE, RUN assumes that the
task does not need to use the I/O page;
no warning message is
issued.
The default is /IO_PAGE.
/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 RUN
command, the task will run in the default partition GEN.
/[NO]POSTMORTEM
Specifies whether or not a Postmortem Dump is to be generated if
the task terminates unexpectedly.
The default is determined when the task is built.
If not
the LINK command defaults to /NOPOSTMORTEM. For more
specified,
information on Postmortem Dumps see the RSX-11M/M-PLUS and
Micro/RSX Task Builder Manual .
/PRIORITY:n
This
is a
Specifies at what priority the task is to run.
The default is established when the task
privileged qualifier.
This qualifier
is used to override the
is built (linked).
d efault.
The default priority for the Task Builder, INSTALL, and RUN is
If a
task has been built or installed at another
50(decimal).
users can run
it at that priority.
priority, nonprivileged
nonprivileged users are limited to running tasks at
Otherwise,
the default priority.
Priorities range from 1 through 250 (decimal) .
/READ_PARTITION:pname
into a
task
Installs the read-only portion of a multiuser
specified partition (pname). If the specified partition does not
exist, the read-only segment is installed in the same partition
as the task.

7-9

RUNNING TASKS
Examples
$ RUN
TASK? ROBOT
This example installs, runs, and removes
of
(upon
completion
execution)
the task contained in the task image file named ROBOT.TSK
from the default directory on the default device, assuming there is no
installed task named ROBOT.
$ RUN ROBOT
$ RUN ROBOT.TSK
The two commands in this example are the equivalent of the command in
the previous example, assuming there is no installed task named ROBOT.
If there is, only the second form, with file type specified, will run
the task from the directory.
The following examples illustrate the task-naming convention.
These
examples assume that a SET TERMINAL/NOSERIAL command has been issued
to allow more than one task to run at a time. See Chapter 3.
The terminal number in parentheses indicates the terminal from which
the tasks are being run.
$ RUN ROBOT
$ SHOW TASK/ACTIVE
MCR...
SHOTA7
TTA7

(TT107:)
(TT107:)
(TT107:)

This example illustrates the task-naming convention as applied from a
terminal with a unit number greater than 77(octal), in this case,
TT107:.
Notice the name given to SHOW task.
In the following example, the terminal number is less than 77 (octal).
$ RUN/TASK_NAME:CAPEK ROBOT
$ SHOW TASKS/ACTIVE
MCR...
(TT10:)
SHOT10
(TT10:)
CAPEK
(TT10:)
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...
(TT10:)
SHOT10
(TT10:)
TT10
(TT10:)
$ RUN ASIMOV
RUN -- Task name already in use
$ RUN/TAS_NAME:BINDERASIMOV
$ SHOW TASKS/ACTIVE
MCR...
(TT10:)
SHOT10:
(TT10:)
TT10
(TT10:)
BINDER
(TT10:)
This example shows how you can run two tasks simultaneously using the
RUN command and the /TASK NAME qualifier.

7-11

RUNNING TASKS
/SCHEDULE:hh:mm:ss
Specifies that the task be run at a particular time of day. This
is a privileged qualifier.
/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 batch jobs or
in indirect command files 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.
This qualifier can be only specified separately or with the
/UIC:[g,m] qualifier.
/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.
The argument u is one of the following time units:
T
S
M
H
See the
units.

Ticks
Seconds
Minutes
Hours

/DELAY

qualifier

for

detailed

description

of 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
seconds after the command is entered.

the

installed

task

PINBAL

$ RUN/INTERVAL:20M WIZARD
This example initiates execution of the installed task
immediately, and every 20 minutes thereafter.

WIZARD

$ RUN/DELAY:10M/INTERVAL:1H TOMMY
This example initiates execution of the installed task TOMMY after 10
minutes, and every hour thereafter.

7-14

RUNNING TASKS
$ RUN/SCHEDULE:12:00:00 NOON
This example initiates execution of the installed task NOON at the
If you entered the
next 12:00:00 after the command is entered.
If you
command before noon today, NOON would run at noon today.
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/SYNCHRONIZE:H/INTERVAL:1H BELTOL
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
First,
the job installs the task HIFI from the
user batch job.
library directory, then the task is processed. If the user had not
the RUN command would have
included the /STATUS:TASK qualifier,
returned a status of success, the batch processor would have executed
and then, the EOJ would have aborted the task that had just
the EOJ,
With the qualifier,
the EOJ is not executed until
started running.
after the task has exited. See the 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
the job installs the task CAVIAR. When
a user batch job.
First,
FISHEGGS.LST and
processed, this task writes two listing files:
After these files have been written and closed, the
SHADROE.LST.
batch job prints them both. With the /STATUS:TASK qualifier on the
the batch processor waits for the installed task CAVIAR
RUN command,
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 (Cont.)
/[NO]POSTMORTEM
Specifies that a Postmortem Dump be taken (or not taken) of the
task before it is aborted. See the RSX-11M/M-PLUS and Micro/RSX
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
The default for
you
install it (including install-run-remove).
this qualifier is determined by previous specification of the
/DUMP qualifier.
If no /POSTMORTEM qualifier has been specified,
the default is /NOPOSTMORTEM.
/TASK
Specifies that you want to abort a task by name.
/TERMINAL:ttnn:
Specifies that a task from some terminal other than your own be
This is a privileged qualifier.
aborted.
Examples
$ ABO RUN
11:11:11 Task "TT10" terminated
Aborted via directive or CLI
This example aborts a task initiated with the RUN command
your terminal.
See the next example.

running

$ RUN TREK
ORDERS: STAR DATE = 2000
YOU MUST DESTROY THE KLINGON INVASION FORCES OF 29 BATTLE
YOU HAVE 40 SOLAR YEARS TO COMPLETE YOUR MISSION.
CRUISERS.
READY?
DCL>ABORT RUN
12:11:09 Task "TT10" terminated
Aborted via directive or CLI
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 monitor level,
issued the ABORT command. DCL prompted for the command to
and then,
be aborted, and then, RUN was specified. The task was aborted and
If your RSX-11M-PLUS system
removed,
and the message displayed.
would
have
been
issuing CTRL/C alone
supports CTRL/C ABORT,
See Chapter 3, for more information.
sufficient.
$ ABORT/TASK MACT3
Nonprivileged users can
This example aborts the task named MACT3.
Privileged users can
their own terminals.
abort tasks running on
abort tasks by name running on any terminal. See the next example.

7-18

RUNNING TASKS

ABORT (Cont.)
$ DIRECTORY *.RNO
Directory DU2:[303,5]
20-MAY-85 16:28
ALTCLI.RNO;3
213.
27-APR-85 16:52
ANNI.RNO;6
3.
30-MAR-85 09:30
APRCOM. RNO; 4
9.
15-APR-85 10:35
BEST.RNO;5
40.
28-APR-85 15:50
CATCH.RNO;4
7.
22-APR-85 09:39
CHAP11SMG.RNO;13
49.
13-MAY-85 16:36
CHAP12SMG.RNO;51
223.
08-APR-85 13:15
CHARSET.RNO;5
6.
15-MAY-85 11:57
DCL>ABORT DIRECTORY
16:29:45 Task "DIRT6" terminated
Aborted via directive or CLI
In this example, the user issued a DIRECTORY command and soon saw that
the file being checked for was present.
Rather than wait for the
directory listing to complete, the user typed CTRL/C, and then,
entered the ABORT command in response to the explicit DCL prompt. The
ABORT command defaulted to ABORT/COMMAND.
If your, system supports
CTRL/C ABORT, the CTRL/C alone would have been sufficient.
$ 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.
$ ABORT/DUMP RUN
14:41:11 Task "TT10" terminated
Aborted via directive or CLI
R0=000000
R1=100077
R2=135600
R3=000000
R4=000000
R5=000000
SP=012540
PS=170017
In this example, the user requested a Postmortem Dump.
The contents
of the task's registers at the time of the abort are listed on the
terminal along with notification of the dump. The dump file will be
printed on the system's line printer.

7-19

RUNNING TASKS

CONTINUE
7.4

CONTINUE

CONTINUE resumes execution of a previously suspended task.
Nonprivileged users can continue tasks initiated from their own
terminals.
Privileged users can continue any suspended task.
Format
CONTINUE [/TERMINAL:ttnn:] taskname]
Command Qualifier
/TERMINAL:ddnn:
Parameter
If you do not supply a parameter,
the task running at your
terminal initiated by the RUN command is continued.
Tasks are suspended through the execution of a SPND$S directive
A RSUM$ directive is another way of continuing
within
the task.
a suspended task.
taskname
Specifies the suspended task you want to continue. If you do not
specify a task name,
the default is a task named after the
terminal.
Command Qualifier
/TERMINAL:ttnn:
Allows you to continue a suspended task running on some other
This is a privileged qualifier.
terminal.
Example
$ RUN YOYO

"Message from Yoyo: Yoyo is suspended"
$ SHOW TASK/ACTIVE TT10
PRI - 50.
DPRI - 50.
00677100-00701600
TT10
070530 GEN
STATUS:
-CHK SPN -PMD REM MCR
TI - TT10: IOC - 0. EFLG 000001 000000 PS 170000 PC 001254
BEGS 0-6 001372 000037 000012 140311 001254
$ CONTINUE
"Message from Yoyo: Not suspended. Climbing string"
In this example, the user ran a task that issues a message and then
Not all suspended tasks issue such messages, but you
suspends itself.
The user
can identify a suspended task through SHOW TASKS/ACTIVE.
issued SHOW TASKS/ACTIVE and named the task. Included in the listing
7-21

RUNNING TASKS

CANCEL
7.5

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 executing task, but only the
pending entries in the clock queue.
Format
CANCEL
Task?

taskname

CANCEL

taskname

Parameter
taskname
Specifies the name of the installed task whose clock-queue
entries you want to eliminate.
Example
$ RUN/DELAY:5M ARDVRK
$ SHOW CLOCK__QUEUE
ARDVRK Scheduled at 17-MAY-85 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.
First, the user verified that ARDVRK was in the clock queue (as the
the user issued the CANCEL command to eliminate
only entry).
Then,
the scheduled run of ARDVRK. Finally, 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.14.5 for information on SHOW CLOCK QUEUE.

7-23

RUNNING TASKS

STOP/BLOCK
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:ttnn:
Parameter
taskname
Names the task to be blocked. If you do not name a task, the
initiated with the RUN command and named after the terminal
task
is blocked.
Command Qualifier
/TERMINAL:ttnn:
Specifies that a task running from the named terminal is to be
This is a privileged qualifier.
blocked.
Example
$ RUN ADVENT
$ SHO TASK/ACTIVE
MCR...
SHOTS
TT5
$ STOP/BLOCK
$ SHOW TASK:TT5/FULL
073464 00541000-005436 PRI - 50. DPRI - 50.
TT5
100604
GEN
BLK -CHK WFR -PMD REM MCR
STATUS:
TI - TT5: IOC - 0. BIO - 0. EFLG - 000001 000000 PS - 170000
PC - 002206 REGS 0-6 001637 040066 040060 140311 163500 000000 001252
$ START/UNBLOCK
$ SHOW TASK:TT5/FULL
TT5
100604
GEN
073464 00541000-005436 PRI - 50. DPRI - 50.
-CHK WFR -PMD REM MCR
STATUS:
TI - TT5: IOC - 1. BIO - 0. EFLG - 000001 000000 PS - 170000
PC - 002206 REGS 0-6 006173 042066 040060 140311 163500 000000 001260
In this example, first, the user on terminal TT5: ran a task with the
RUN command, giving the task the name TT5 by default. Then, the user
/FULL
issued the
STOP/BLOCK command, without naming the task. The

7-24

RUNNING TASKS

INSTALL (Cont.)
Command Qualifiers
/[NO]CHECKPOINT
The
Specifies whether or not the task is to be checkpointable.
This qualifier overrides the
default is set at link time.
link-time checkpointability specification.
/COMMAND:"taskcommand"
The command
Passes a command to the task you are installing.
must be
inside the quotation marks
(") and not more than 40
characters long. For example, the following command:
$ INSTALL/COMMAND:" /LI" SAMBA
installs SAMBA and then passes the /LI switch to it.
/EXTENSION:n
Specifies that n(decimal) additional words of address space are
to be allocated to a task.
/[NO]INTERPRETER
Specifies that the task being installed is a command line
You must install a CLI using the /INTERPRETER
interpreter (CLI).
qualifier before you can set a terminal to that CLI (SET
TERMINAL/CLI:cliname)
or work with the CLI by means of the CLI
command.
The default is the /NOINTERPRETER qualifier.
/MULTIUSER_PARTITION:parname
Specifies the partition into which the read-only portion of a
multiuser task is to be installed.
/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.
/[NO]POSTMORTEM
Specifies whether or not a Postmortem Dump (PMD) is to be
generated if the task aborts because of a synchronous system trap
This
( SST) error condition. The default is set at link time.
the link-time specification.
See the
qualifier
overrides
RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for further
information.
/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
The argument n can range from 0 through 250 (decimal).
link time.

7-29

RUNNING TASKS

INSTALL (Cont.)
/[NO] WRITEBACK
Specifies whether or not a read/write common is to be written
back
to
the original task image file on a checkpoint or remove
operation. Taking the default
(/NOWRITEBACK) means that the
read/write common is to be checkpointed to the system checkpoint
file.
Examples
$ INSTALL FATE
This example looks for a task image file named FATE.TSK on the default
device and in the default directory, and then, installs it as FATE in
the STD, assuming no other name was specified at link time.
$ INSTALL $LATE
This example looks in the system directory (by convention, [1,54]) and
in the library directory (by convention, [3,54]) for a task image file
named LATE.TSK, and then, 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
default device and in the default directory, and then, installs it as
BUCKIN in the STD, assuming no other name was specified at link time.
Task names are limited to six Radix-50 characters.
$ INSTALL/TASK:DOOR GATE
This example looks on the default device in the default directory for
a task image file named GATE.TSK, and then, 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 in a
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 then, 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.

7-32

RUNNING TASKS

REMOVE
7.9

REMOVE

REMOVE takes a task name out of the System Task Directory.
is no longer installed.

The

task

REMOVE/REGION takes the name of a region out of the Common Block
Directory and the partition list. This is a privileged command.
Format
REMOVE[/qualifier]
Task?
taskname
REMOVE [/qualifier] taskname
Command Qualifier
/REGION
/TRANSLATION ROUTINE:n
Parameter
taskname
Specifies the name of the task you want to remove.
If you want to remove a region, specify the /REGION qualifier and
the name of the region.
Command Qualifier
/REGION
Specifies that you want to remove a region from the Common Block
Directory.
/TRANSLATION_ROUTINE:n
Removes the ancillary control driver (ACD) specified by the
argument n.
If you assigned a logical name for the ACD when you
This
installed it, the name is deleted when you remove the ACD.
qualifier is privileged.
Examples
$ REMOVE WONTON
This example removes the task named WONTON from the System Task
Directory.
It is no longer installed.
$ REMOVE/ REGION DONJON
This example removes
Block Directory.

the common

region

7-39

named

DONJON

from

the

Common

RUNNING TASKS

FIX
FIX

7.10

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
/READONLY SEGMENT
/REGION
Parameter
taskname
Specifies the installed task or region you want to fix in memory.
Command Qualifiers
If you
memory.

not

specify

qualifier,

installed task is fixed in

/READONLY_SEGMENT
Allows you to fix in memory the read-only segment of a multiuser
task.
/REGION
Allows you to fix in memory a common region.
Example
$ FIX ACNT
$ SHOW TASK/INSTALLED/FULL ACNT
ACNT
061724 GEN 100630 02264100-02342000
STATUS:
-EXE -CHK -PMD PRV FXD
IOC - 0 EFLG - 000000 000000
TI - NONE

PRI-50. DPRI-50.

$ UNFIX ACNT
$ SHO TAS INS FU ACNT
0047000-00554700
ACNT
061724 GEN 035370
STATUS:
-EXE -CHK -PMD PRV
IOC - 0. EFLG - 000000 000000
TI -NONE

7-41

PRI-50. DPRI-50.

RUNNING TASKS

ASSIGN/TASK
7.12

ASSIGN/TASK

ASSIGN/TASK reassigns an installed task's logical unit numbers (LUNs)
from one physical device to another. The reassignment overrides the
a
static LUN
assignments in the task's disk image file.
This
is
privileged command.
Format
ASSIGN/TASK
Task?
taskname
Device?

ddnn:

Logical Unit?

lun

ASSIGN/TASK:taskname ddnn:

lun

Parameters
taskname
Identifies the installed task whose LUN you want to reassign.
ddnn:
Specifies the new device to which you want the LUN reassigned.
This can be a physical device, pseudo device, or logical device
name.
lun
Specifies which LUN you want to reassign to the new device.
Examples
$ ASSIGN/TASK:NIKNAK
Device? DUl:
Logical unit? 5
This example overrides the assignment of LUN 5 established at link
time and reassigns LUN 5 to DU1:.
$ ASSIGN/TASK:PADWAK TT1:

This example overrides the assignment of LUN 4 established at link
time and reassigns LUN 4 to TT1:.
$ ASSIGN/TASK:GIVBON AZ1: 3
This example overrides the assignment of LUN 3 established at link
time and reassigns LUN 3 to logical device name AZ1:.

7-44

RUNNING TASKS

DEBUG
7.13

DEBUG

DEBUG forces a task to trap to a debugger by setting the T-bit in the
The task must have been built using the
task's Processor Status Word.
/DEBUG qualifier to the LINK command or it must have been issued the
SVDB$ Executive directive (Specify SST Vector Table for Debugging
Aid)
DIGITAL offers two debuggers for use with this command:
1.

ODT-11, the On-Line Debugging Tool

RSX-11M-PLUS FORTRAN-77 DEBUG

for
See the RSX-11M/M-PLUS and Micro/RSX Debugging Reference Manual
more information on ODT and the documentation accompanying the
more
for
RSX-11M-PLUS FORTRAN-77 product (available separately)
information on FORTRAN-77 DEBUG.
Nonprivileged users can issue this command for any nonprivileged task
Privileged users can name any task, but
running
from their terminal.
the command must be issued from the same terminal the task was run
from.
Format
DEBUG [taskname]
Parameter
taskname
Specifies the name of the task you want to trap. If you do not
specify a taskname, the default is a task named after the
terminal from which the command was issued, such as TT5:.
Example
$ RUN JOE
$ SHOW TASKS/ACTIVE
MCR...
(TT5:)
SHOT5
(TT5:)
(TT5:)
TT5

$ DEBUG
TE:002452
issued
The user
In this example, the task was built including ODT.
the task named after the
the DEBUG command, which defaulted to
terminal. The display from ODT gives the T-bit exception code and the
address following the location in error and issues its prompt. The
user can then proceed with debugging.

7-46

RUNNING TASKS

SET PARTITION (Cont.)
/DIAGNOSTIC
Specifies a diagnostic partition. Diagnostic partitions are used
for
diagnostic
functions
on multiprocessor systems.
The
specified partition is created without
checking the top of
memory.
/SYSTEM
Specifies a system partition. 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.
Examples
$ SET PARTITION: TOMPAR/SYSTEM
Base? 002010
Size? 1000
$ SHOW PARTITION: TOMPAR
PAR=TOMPAR: 002010:1000: 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.
Because this is the default, the user need not
have specified the /SYSTEM qualifier in the command.
$ SET NOPARTITION
Partition name? TOMPAR
$ SHOW PARTITION: TOMPAR
SET -- Partition not in system
This example eliminates the partition TOMPAR.
Notes
Partitions are one of the key elements in tuning larger
systems and making the best use of available memory.

RSX-11M/M-PLUS

You can specify the partition you want 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.
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 can display the name, size, address, and type of one or more
partitions with the SHOW PARTITIONS command (Section 7.14.2). You can
display the allocation of partitions in memory graphically with the
SHOW MEMORY command (Section 8.3).

7-50

RUNNING TASKS

SHOW PARTITIONS (Cont.)
RO COM

Read-only common partition

RW COM

Read-write common partition

DEVICE

Partition that is a common mapped to the I/0 page

SEC POOL Partition that is a secondary pool
contentname
Indicates one of the following:
[taskname]

An inactive resident task

An active task

(dd:)

A specific device driver

+xxxx+

The name of the first installed task that is
associated with an unnamed common, usually the
read-only segment of a multiuser task

!yyyy!

The name of the common

Examples
$ SHOW PARTITIONS
SYSPAR 035720 00201000 00010000 MAIN
036330 00201000 00010000 TASK

<MCR...>

DRVPAR

035610 00224000 00140000 MAIN
035324 00224000 00002600 DRIVER (DB:)
035260 00227600 00001300 DRIVER (DK:)

LDRPAR

035544 00364000 00003000 MAIN
033774 00364000 00003000 TASK

SECPOL
GEN

035434 00427000
035370 00477000
117210 00477000
041324 00523000
.062124 00545100

<...LDR>

00050000 SEC POOL
04701000 MAIN
00024000 RW COM !FCSFSL!
00004400 TASK < POOL >
>
00012600 TASK < LPP0

046340 00763300 00006100 TASK < TT35 >

7-53

RUNNING TASKS

SHOW PARTITIONS (Cont.)
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 1000(octal) bytes. See next
example.
$ SHOW PARTITION: SYSPAR
PAR=SYSPAR:002010:000100: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 one hundred 64-byte blocks.
Notes
SHOW PARTITIONS unadorned is the equivalent of the MCR PAR command.
SHOW PARTITIONS with a partition name is the equivalent of the MCR SET
/PAR=parname command.

7-54

RUNNINGTASKS

SHOW TASKS (Cont.)
Examples
$ SHOW TASKS/ACTIVE
MCR.. .
(TT5:)
SHOT5
(TT5:)
This example shows the brief display from SHOW TASKS/ACTIVE.
In this
case, the tasks are MCR..., the central command dispatcher, and SHOT5,
the SHOW task itself.
The terminal from which the task is running is also displayed.
$ SHOW TASKS/ACTIVE/ALL
LDR... (CO0:)
RMDEMO (TT0:)
SHOH2
(HT2:)
NETACP (CO0:)
MCR... (TT13:)
SHOT5
(TT5:)
DCLT5
(TT5:)
DB0FCP (CO0:)

EDTT2
EDTT3

(TT2:)
(TT3:)

This example shows the brief display from SHOW TASKS/ACTIVE/ALL.
The terminal from which the task is running is also displayed.
Full Format
SHOW TASKS/ACTIVE/FULL [taskname]
SHOW TASKS[: taskname] /ACTIVE/FULL
Parameter
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
This format includes detailed information on the state
command.
system.
The format of the
of one or all tasks active on 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 rlval r2val r3val r4val r5val r6val

7-56

RUNNING TASKS

SHOW TASKS (Cont.)
NOTE
These status flags are displayed by several forms of
They give information on what
the SHOW TASK command.
is happening within the task and between the task and
identify certain kinds of
the
system.
They also
tasks.
Names prefixed by a minus (-) indicate the
Thus, -CHK means the
complement of the condition.
task is noncheckpointable. You must understand how
the system runs tasks to understand the meanings of
all these flags. See the RSX-11M/M-PLUS and Micro/RSX
Task Builder Manual , the RSX-11M/M-PLUS and Micro/ RSX
and the RSX-11M/M-PLUS
Executive Reference Manual ,
Analyzer
Reference Manual for more
Crash
Dump
information
The CDA manual has a full explanation of
the contents of the TCB.
Examples
$ SHOW TAS/ACT/FULL TT7
TV 066734 GEN 064244 01676500-02062100 PRI - 50. DPRI
50.
STATUS: -CHK WFR -PMD REM MCR
TI - TT7: IOC - 1. EFLG - 000000 040000 PS-70004 PC-072132
BEGS 0-6 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
The task
is not
in the default partition GEN at a priority of 50.
state. No
PMD will be
checkpointable.
It is
in a "wait-for"
The task is to be removed on exit (meaning it was
generated.
and it was
form of RUN),
installed with the install-run-remove
activated by MCR.
(Many tasks requested from DCL are actually
activated by MCR.)
$ SHO TAS/ACT/FUL
...LDR 034210 LDRPAR 033774 00364000-00367000 PRI - 248. DPRI - 248.
STATUS: STP - PMD PRV NSD FXD
TI - COO: IOC - 0. EFLG - 000001 000000 PS - 170000 PC - 120526
BEGS 0-6 000162 024207 177777 066640 066610 066314 120250
046640 01367700-01415100 PRI - 225. DPRI - 225.
RMDEMO 046320 GEN
STATUS:
-CHK WFR -PMD PRV MCR
TI - TT62: IOC - 0. 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 - 0. EFLG - 000001 040000 PS - 170000 PC - 124412
REGS 0-6 000000 120556 000400 120512 000100 120572, 120442
037344 00624700-00634700 PRI - 160. DPRI - 160.
DCL... 115530 GEN
STP -PMD PRV CLI NSD CAL
STATUS:
TI - TT10: IOC - 0. EFLG - 100001 040000 PS - 170000 PC - 124470
REGS 0-6 025550 025550 000000 120426 123530 000000 120362
066610 02221700-02261700 PRI - 160. DPRI - 160.
SHOT10 066314 GEN
STATUS:
-PMD REM PRV
TI - TT10: IOC - 0. EFLG - 000001 040000 PS - 170017 PC - 121202
REGS 0-6 000000 131574 050712 000000 000000 000000 001216

7-59

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 at that of SHOW TASKS/ACTIVE/FULL.
See Section 7.14.3.1 for a description of the display.
Examples
$ SHOW TASKS/INSTALLED
LDR...
12.15
LDRPAR
TKTN
04.7
TKNPAR
RMDEMO V1.03
GEN
MTAACP 0013
GEN
F11MSG V0010
GEN
NETACP V02.00 GEN
EVP...
V01.00 GEN
...MCR 1.1
GEN
SHOT5
1.1
GEN
...MOU
2502
GEN
...DCL 00
GEN
MCR... 2.02
SYSPAR

248.
248.
200.
200.
200.
200.
199.
160.
160.
160.
160.
160.

00002500 LB0:-00163310 FIXED
00010000 LB0:-00171022
00026700 LB0:-00171022
00013600 EM0:-00000315
00025500 LB0:-00167207
00025500 DB0:-00644640
00013100 DB0:-00644640 CHECKPOINTED
00020300 LB0:-00162467
00020300 LB0:-00162467
00037700 LB0:-00222416
00035600 DB0:-00212612
00010000 LB0:-00162443

This example shows the
brief format of the display from SHOW
TASKS/INSTALLED. The task LDR... ( the loader ) is fixed in memory.
The task EVP... is checkpointed. The final entry shown, MCR..., is
the system command dispatcher.
See next example.
$ SHOW/TASK:MCR.../INSTALLED/FULL
MCR... 110160 SYSPAR 11454 00202700-00212700 PRI - 160. DPRI - 160
STATUS: STP -PMD PRV MCR CLI NSD CAL
TI - TT5: IOC - 0. BIO - 0. EFLG - 000001 040000 PS - 170000
PC - 122436 BEGS 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-62

RUNNING TASKS

SHOW TASKS (Cont.)
Notes
The brief format of SHOW TASKS/INSTALLED is the MCR TAS command.
full format of SHOW TASKS/INSTALLED is the MCR TAL command.

The

The /DYNAMIC qualifier enables you to watch the full format display in
real time as it is updated. See Section 7.14.3.5.

7.14.3.3

SHOW TASKS/INSTALLED/DEVICE -

The SHOW TASKS/INSTALLED/DEVICE command displays the names and status
of all tasks installed from a specified device.
Format
SHOW TASKS/INSTALLED/DEVICE:ddnn:
Example
$ SHOW TASKS/INSTALLED/DEVICE:DR0:
DR00F1 M0323 SYSPAR 149. 00055700 LB0:-00475656 FIXED
F11ACP M0323 GEN
149. 00044000 LB0:-00315566
DB01F1 M0323 GEN
149. 00044000 LB0:-00315566
DB07F1 M0323 SYSPAR 149. 00044000 LB0:-00315566 FIXED
ERRLOG V1.01 GEN
148. 00042200 LB0:-00335276
PMD... 04.0
GEN
140. 00015200 LB0:-00503535
140. 00055100 LB0:-00505331
HRC... 02
GEN
GEN
130. 00016300 LB0:-00504250
SYSLOG 1.02
100. 00035400 LB00:-00502750
...INS 06
GEN
This display contains the following from left to right:
Task name
Task version identification
Partition name
Task priority
Task size
Load device identification
Logical block number on the load device
Task memory state
On a processor with less than 124K words of memory, the task size
field (fifth column) contains 6-digit rather than 8-digit numbers.
CHECKPOINTED
the task
is fixed
in memory.
FIXED indicates that
indicates
that the task has been swapped out of memory to make room
for a higher priority task.

7-63

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
RMD.
The first
from one page to the other without leaving
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, where the named task will
still be displayed.
/RATE:n
Allows you to set the rate at which the RMD display screen is to
be replotted on the first display. The argument n is the number
You
of seconds between replots. The default value for n is 1.
can change the rate by pressing ESC and entering a new rate. The
If you
rate setting returns to 1 as soon as you change pages.
want a slower rate, you must reset the rate each time you change
the page.
Use this qualifier to slow down the display.
Task headers can change more often than once per second, but once
per second
is the most rapid rate that can be specified in a
command.
Example
$ SHOW TASK:CORT5/DYNAMIC
The screen is cleared and the following display appears:
14-MAY-85

RSX-11M-PLUS V3.0 BL24 512K
18:53:11
Task: CORT5
Own:
TT5:
000356000

Partition:
I/0 = 0.

GEN STATUS:
-CHK -PMD REM PRV CLI
DPri:
160 Pri: 160 Spri: 155 Len:

RO = 022120 R1 = 000764 R2 = 002230 R3 = 000764 R4 = 024626
R5 = 022136
Eflg =
PC = 005330 PS = 170000 SP = 022224
$DSW -- 0.
0000001 040000
LUN File
--- ---1. SY0:
2. DB0:[3,33]DEEP.DAT
3. SY0:
4. SY0:
5. TI0:
6. CL0:
7. DB0:

LUN File
--- ----

7-65

RUNNING TASKS

SHOW TASKS (Cont.)
Command Qualifiers
/OWNER:arg
ddnn:
ALL
Specifies the terminal or other device from which the tasks
displayed are being run. You can name any device, pseudo device,
The
logical device name, or terminal number for this argument.
which displays tasks owned by all
default argument is ALL,
devices on the system.
You can change the owner displayed by pressing the ESC key 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 is

Use this
screen.

it fits on one

qualifier to

shorten the

display so that

You can change this value by pressing the ESC key and entering a
new priority.
/RATE:n
Allows you to set the rate at which the RMD display screen is to
The argument n is the number
be replotted on the first display.
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 want a
must reset the rate each time you change the
rate,
you
slower
page.
Use this qualifier to slow down the display.
The Active Task List may change more often than once per second,
but once per second is the most rapid rate available.
Examples
$ SHOW TASKS/ACTIVE/DYNAMIC

7-67

RUNNING TASKS

SHOW TASKS (Cont.)
The screen is cleared and the following display appears:
RSX-11M-PLUS V3.0 BL24

14-MAY-85 19:08:55

512K

Name Length
TI
LDR... 00002500 CD0
RMDEMO 00026700 TT0
SHOHO
00026700 HT0
NETACP 00025500 CO0
EVP... 00014200 CO0
DCLT5 00035600 TT5
DBOFCP 00044000 CO0

Pri
248.
225.
225.
200.
199.
160.
149.

I/0 Status flags
0. -CHK FXD STP -PMD PRV NSD
0. -CHK WFR -PMD PRV MCR
0. -CHK -PMD PRV MCR
0. STP ACP -PMD PRV NSD
0. STP -PMD PRV
0. -CHK STP REM PRV CLI
0. -CHK STP ACP -PMD PRV NSD

LP0
TT5

70.
50.

0. STP PRV SLV
1. -CHK WFR -PMD REM MCR

00014100 CO0
00002600 TT5

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.
Because the current owner is ALL, the
remainder of the display is the Active Task List 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-PLUS V3.0 BL24
Name
SHOTS

Length
TI
00026700 TT5

14-MAY-85 14:57:55

512K
Pri

I/O Status flags
0.
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.14.3.7 SHOW TASKS/LOGICAL UNITS SHOW TASK:taskname/LOGICAL UNITS displays the static logical unit
number assignments (LUNs) for an installed task.
Format
SHOW TASKS:taskname/LOGICAL UNITS

7-68

RUNNING TASKS

SHOW TASKS (Cont.)
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.
The
display consists
of
a list of physical devices and
The display does not show
corresponding static LUN assignments.
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.
Examples
$ SHOW TASK: TEWKSY/LOGICAL UNITS
DB1:
1.
DB1:
2.
DB1:
3.
DB1:
4.
TI0:
5.
CL0:
6.
This example shows the display.
SHO -- Task not in system
This example shows the error message received when you attempt to show
a task installed through the install-run-remove form of
the
LUNs of
RUN.
Notes
You can display information about a terminal's
with SHOW ASSIGNMENTS.
(See Chapter 5.)

logical

assignments

You can display information about the LUNs of a task installed with
form of the RUN command with the SHOW
the
install-run-remove
TASKS/DYNAMICcommand. (See Section 7.14.3.3.)
For more information on logical units, see Chapter 5.
RSX-11M/M-PLUS and Micro/RSX Task Builder Manual .

See

also

the

SHOW TASK/LOGICAL UNITS is the equivalent of the MCR LUN command.
Tasks can dynamically alter their LUN assignments through the ALUN$
Executive directive.

7-69

RUNNING TASKS

SET PRIORITY
7.14.4 SET PRIORITY
SET PRIORITY alters the
privileged command.

priority

of an

active

task.

This is a

Format
SET PRIORITY
Priority?
pnum
Task?
taskname
SET PRIORITY:n taskname
Parameters
pnum
Specifies the new priority you want to assign to the task.
Priority numbers are
in the range of from 1 through 250. The
argument 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 want to
alter.
Example
$ SHOW TASK:TT7/FULL/ACTIVE
TT7 066734 GEN 064244 01676500-02062100 PRI - 50. DPRI - 50.
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
TASK? TT7
PRIORITY? 199
SET -- syntax error
$ SET PRIORITY TT7 199.
TT7 066734 GEN 064244 01676500-02062100 PRI - 199. DPRI - 199.
$ SHOW TASK ACT FULL TV
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
TT7 066734 GEN 064244 01676500-02062100 PRI - 149. DPRI - 149.
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

7-71

RUNNING TASKS

SHOW CLOCK_QUEUE
7.14.5 SHOW CLOCK_QUEUE
SHOW CLOCK_QUEUE displays information about tasks currently in the
the task names, the next
information consists of
clock queue.
The
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 29-MAY-85 17:41:31:51 RESCHEDULE INTERVAL 05 SECS
ONEUP SCHEDULED AT 29-MAY-85 17:48:44:05
CALDOR SCHEDULED AT 29-MAY-85 18:00:00:00 RESCHEDULE INTERVAL 02 HOURS
TEWKSY SCHEDULED AT 30-MAY-85 10:00:00:00
Installed tasks are
This example shows the display from SHOW CLOCK/QUEUE.
queue
through
the
scheduling
options
of the RUN command.
placed
in the clock
See Section 7.2.2.
The task LIONEL is scheduled to run at 17:41:31:51 (hours, minutes, seconds,
ticks) and every 5 seconds thereafter.
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 2 hours thereafter.
The task TEWKSY is scheduled to run at 10:00:00:00 on the next day.

Notes
SHOW CLOCK_QUEUE is the equivalent of the MCR CLQ command.
Installed tasks are placed in the clock queue through the privileged
form of the RUN command. See Section 7.2.2.
This command has nothing to do with queues under the control of the
Entries in Queue Manager queues are displayed through
Queue Manager.
the SHOW QUEUE command.

7-73

RUNNING TASKS

SHOW COMMON (Cont.)
Command Qualifier
/TASK
Specifies that you want a list of tasks attached to a particular
common region showing the number of times each task is mapped to
the common (mapping count).
Examples
$ SHOW COMMON
BASIC2 050644 0
DEPRES 056340 0
DSMBUF 053630 5
DSMSUP 064164 2
FCSFSL 117210 17
TTCOM 034620 1

STATUS: COM
STATUS:
COM
STATUS: COM PIC
STATUS:
COM
STATUS: COM
STATUS:
FXD COM

This example shows the display from the unadorned SHOW COMMON command.
Currently, six commons are installed in the system.
$ SHOW COMM: DSMBUF
DSMBUF 053630 5 STATUS: COM PIC
This example shows the display when a single common is named.
$ SHO COM:DSMBUF/TASK
DSMBUF 053630 5 STATUS: COM PIC
DSMIO
3
DSMGAR 1
DSMT61 1
This example shows the display when a list of tasks is requested for a
single common.
Notes
SHOW COMMON is the equivalent of the MCR CBD command.

7-75

SYSTEM CONTROL

SET [DAY]TIME
8.1.1

SET [DAY]TIME

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. You can enter the date in either of two
formats
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).

mm/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.
time
Specifies the time. Time is entered in the following format:
hh:mm[:ss]

where hh is the number of the hour in the
24-hour format and mm is the number of the
minute. The parameter ss defaults to 00.

Examples
$ SET TIME
Time? 8:05
This example sets the time at 8:05 on the current day.
$ SET DAY
Date? 16-JUN-85
This example
unchanged.

sets

the

date

at June

8-2

16, 1985.

The time setting is

SYSTEM CONTROL

SET [DAY]TIME (Cont.)
$ SET DAY
Date? 06/14/85 17:14
This example sets the date at June 14, 1985, and the time at 17:14:00.
The date will not be displayed in the format entered but as 14-JUN-85.
$ SET DAYTIME 06-JUN-85 04:00:00
$ SET TIME 04:00:00 06-JUN-85
The examples are equivalent.
the time at 04:00 hours.

Both set the date at June 6,

1985,

and

either

Notes
Regardless of the prompt, you can enter the date
order.

8-3

time

SYSTEM CONTROL

SHOW [DAY]TIME
8.1.2

SHOW [DAY]TIME

SHOW [DAY]TIME displays the current time and date.
The
24-hour format and the date is formatted as dd-mmm-yy.

time

Format
SHOW [DAY]TIME
SHOW TIME
SHOW DAY
Example
$SHOW TIME
04:00:22 06-JUN-85
This example shows the date as June 6, 1985 and the time as 4:00:22.

8-4

SYSTEM CONTROL

SET SYSTEM (Cont.)
Examples
$ SET SYSTEM
System UFD? [3,54]
$ SET SYSTEM [3,54]
These commands are equivalent.
They establish the system directory as
UFD [3,54] on pseudo device LB:.
$ SET SYSTEM/EXTENSION_LIMIT:1200
This command sets the maximum size to which a task can extend itself
32-word
directive
to
1200(octal)
through
the
Extend
Task
blocks(decimal) or 30K words.

SYSTEM CONTROL

SHOW LIBRARY
8.2.2 SHOW LIBRARY
The SHOW LIBRARY command displays the current library directory on
The display specifies LIBUIC, but the library
RSX-11M-PLUS systems.
directory rarely has a UIC associated with it; it is a directory.
Format
SHOW LIBRARY
Example
$ SHOW LIBRARY
LIBUIC= [3,54]
This example shows the system library directoy as [3,54].

8-12

SYSTEM CONTROL

SHOW USERS
8.3 SHOW USERS
SHOW USERS displays the terminal number, login UIC, and default
If
Resource Accounting is
directory
for all logged-in users.
supported and is running, SHOW USERS also shows the date and time of
login,
the number of tasks active on the terminal, and the user name
of the person logged in.
Format
SHOW USERS
Examples
$ SHOW USERS
TT2:
TT5:
TT7:
TT16:
TT20:
TT51:
TT54:
HT2:

[7,40]
[301,370]
[200,1]
[7,42]
[200,20]
[1,2]
[1,10]
[7,43]

[7,40]
[301,370]
[200,1]
[7,42]
[7,37]
[7,26]
[303,5]
[7,43]

This example shows the SHOW USERS display for an RSX-11M-PLUS system
The first column identifies the
without Resource Accounting active.
Column three
terminal.
The second column is the default directory.
is the login UIC. HT2: is a DECnet host terminal.
$ SHOW USERS
TT7:
[7,40]
TT10:
[303,5]
TT14
[7,25]
TT15:
[1,1]
TT16:
(314,362]
TT17:
[UYAK]
TT20:
[12,10]
TT21:
[1,6]
TT27:
[303,2]
TT30:
[FRINI]
TT32:
[VEISS]
TT33:
[7;16]
TT34:
[1,24]
TT35:
[KNOCKS]
TT36:
[7,302]
TT37:
[GAZLE]
TT41:
[303,12]
[304,325]
TT42:
TT43:
[303,23]
TT45:
[7,43]
VT3:
[ANGLE]

[7,40]
[7,100]
[7,25]
[7,50]
[7,14]
[7,60]
[7,24]
[7,13]
[303,2]
[303,10]
[7,11]
[7,16]
[7,21]
[301,370]
[7,302]
[303,14]
[303,12]
[7,325]
[303,23]
[7,43]
[303,5]

7-MAY-8510:57
7-MAY-8511:10
7-MAY-8513:56
7-MAY-85 11:06

0
2
0
0

J. ANGEL
W.WRITERS
D. DUCK
G. VOSKA

7-MAY-85 11:15
7-MAY-85 10:47
7-MAY-85 10:50
7-MAY-85 12:55
7-MAY-85 12:33
7-MAY-85 14:14
7-MAY-85 10:56
7-MAY-85 11:08
7-MAY-85 12:36
7-MAY-85 10:55
7-MAY-85 13:01
7-MAY-85 12:36
7-MAY-85 10:56
7-MAY-85 11:17
7-MAY-85 14:35
7-MAY-85 15:04

0
0
1
0
0
1
0
0
1
0
1
0
0
0
0
2

P. STROM
D.UYAK
P. KROBAR
C.FUTILE
J. FRINI
P. VEISS
S. THOMS
N. EPPS
D. KNOCKS
S. ADAMS
J. GAZLE
J. ALNESE
P. BEZ
L. KROGAN
J. MAN
M. ANGLE

8-13

SYSTEM CONTROL

SHOW MEMORY
8.4

SHOW MEMORY

The SHOW MEMORY commnd 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
for a new user to see how the
system.
It
is also useful viewing
operating system operates.
However, you should understand that the
graphic display is approximate and cannot be used for
critical
measurement.
Format
SHOW MEMORY
Example
The following example shows the SHOW MEMORY display for
The circled numbers are keyed to the explanation.
$ SHOW MEMORY

8-15

RSX-11M-PLUS.