Digital PDFs

AA-FD12A-TC

July 1985

568 pages

Original

30MB

Document:	RSX-11M/M-PLUS System Management Guide System Management Guide
Order Number:	AA-FD12A-TC
Revision:	0
Pages:	568
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_plus/RSX11Mplus_V3.0_Jul85/AA-FD12A-TC_RSX-11M-PLUS_V3.0_System_Management_Guide_Jul85.pdf

OCR Text

RSX-11 M/M-PLUS
System Management Guide
Order No. AA-FD12A- Te

RSX-11 M Version 4.2
RSX-11 M-PLUS Version 3.0

digital lequipment corporation · maynard, massachusetts

First Printing, October 1979
Revised, November 1981
Revised, March 1982
Updated, April 1983
Revised, July 1985
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
Copyright @ 1979, 1981, 1982, 1983, 1985
by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DIBOL
EduSystem
lAS
MASSBUS
MicroPDP-ll
Micro/RSTS
Micro/RSX
PDP

DEC
DEC/CMS
DEC/MMS
DEC net
DECsystem-lO
DECSYSTEM-20
DECUS
DECwriter

PDT
RSTS
RSX
UNIBUS
VAX
VMS
VT

~D~DD~D

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

800-258-1710

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

603-884-6660

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

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

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, OntariO K2K 2A6
Attn: Direct Order Desk

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary or
approved distributor

'Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)

Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Northboro, Massachusetts 01532

ZK2573

CONTENTS

Page

xiii

Preface

CHAPTER 1

INTRODUCTION

CHAPTER 2

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)

2.1
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.3
CHAPTER 3

INVOKING ACNT
• • • • • • • •
ACNT OPTIONS • •
• • • • •
Creating the Account File
Adding Account Entries • •
Examining Account Entries
Modifying Account Entries • • • • • • • •
Listing Account Entries • • • •
Deleting Account Entries •
• •••
Sorting Account Entries
••••
Exiting from ACNT
ERROR MESSAGES • • • • • • •

• • 2-2
• • 2-2
• 2-3
· 2-3
• • 2-5
• 2-7
2-8
• 2-9
2-10
2-11
2-11

THE CONSOLE LOGGER

3.1
THE CONSOLE OUTPUT DEVICE (CO:)
• • 3-1
3.1.1
CO: as a Pseudo Device • • • •
••••
• 3-1
CO: with the Console Logger Active • •
• • • 3-1
3.1.2
INSTALLING COT ••• AND LOADING CODRV
• • 3-2
3.2
3.3
COMMUNICATING WITH THE CONSOLE LOGGER • • • •
3-2
User Communication with the Console Logger
• 3-2
3.3.1
Task Communication with the Console Logger • • • 3-2
3.3.2
Writing to CO: • • • • • • • • •
• • • • • 3-2
3.3.2.1
Reading from CO: • • • • • • • . • • • • • • . 3-3
3.3.2.2
Attaching and Detaching CO:
••••••
3-3
3.3.2.3
3.4
CONSOLE LOGGING COMMAND DESCRIPTIONS • • • • • . • 3-3
Displaying the Current Console Terminal and Log
3.4.1
File Assignments • • • • • • • •
• 3-4
Starting Console Logging • • • •
• 3-4
3.4.2
3.4.3
Stopping Console Logging • • • •
• 3-4
Disabling the Console Terminal • .
3-5
3.4.4
Reassigning the Console Terminal • •
• 3-5
3.4.5
Disabling the Log File • • . •
• • • • • • • 3-5
3.4.6
3.4.7
Reassigning the Log File • • . .
• • 3-5
Using Multiple Console Logging Commands
3-6
3.4.8
MONITORING THE STATUS OF CO: . . • • •
• • 3-6
3.5
3.6
REDIRECTING CO:
•••••.•••••.
• • 3-7
3.7
READING THE LOG FILE • • • • • • • . • • •
• 3-8
SAMPLE CONSOLE LOGGING TERMINAL SESSION
• • 3-8
3.8
3.9
ERROR MESSAGES .
• • • • . • • . • • • • • 3-11
CHAPTER 4

THE I/O EXERCISER (lOX)

4.1
INTRODUCTION . • . • • • • • • • • • • • • • •
Running an I/O Exercise . • • • • • • • • • • .
4.1.1
How lOX Exercises Different Types of Devices • •
4.1.2
How lOX Exercises Disks • • • • • • • • • • •
4.1.2.1
4.1.2.2
How lOX Exercises Magnetic Tapes and Cassettes
iii

4-1
4-1
4-2
4-2
4-2

CONTENTS
4.1.2.3
4.1.2.4
4.1.2.5

How lOX Exercises Terminals . . • • • •
4-3
How lOX Exercises DECtapes • . • • • . • • • • 4-3
Non-Fi1e-Structured and File-Structured
Volumes • . • • • • • • • • • • • •
• • 4-3
4.1.3
The Four Categor ies of lOX Commands • . . .
4-3
4.2
INSTALLING AND INVOKING lOX
• • • • 4-4
4.2.1
Installing lOX • . • . • • • • • • •
. • • • 4-4
4.2.2
Invoking lOX • • • • • • • • • • .
• 4-5
4.2.2.1
Invoking an Installed Version of lOX .
. • 4-5
Invoking lOX When It Is Not Installed
• 4-5
4.2.2.2
4.3
USING INDIRECT COMMAND FILES WITH lOX
• 4-6
4.4
SETTING UP A TEST CONFIGURATION
4-6
4.5
SELECTING DEVICES FOR EXERCISING •
4-7
The FILES11 Command
• • 4-7
4.5.1
4.5.2
The SELECT Command •
.••.
.•••
4- 8
4.5.3
The VERIFY Command • .
4-8
4.6
EXERCISE PARAMETERS
. • • • .
. • • • . 4-8
General Exercise Parameters • • • • • .
• • 4-8
4.6.1
4.6.2
Device-Dependent Exercise Parameters •
. • • 4-8
Parameter Commands for Files-11 Disks
4.6.2.1
with FILES11 • . • • •
•.••
• 4-8
Parameter Commands for NFS Volumes or
4.6.2.2
Terminals with SELECT
•••.
• • 4-9
Parameter
Commands
for
NFS Volumes
4.6.2.3
with VERIFY.
. • • • • • • 4-9
SETTING PARAMETERS FOR EXERCISING FILES-11
4.7
VOLUMES
• • • •.
• . • • • . • . • • •
4-10
4-12
SETTING PARAMETERS FOR EXERCISING NFS VOLUMES
4.8
4.8.1
Exercising a Magnetic Tape with the SELECT
4-12
Comma nd
• . • . • • • • • • • • . • • • •
4.8.2
Exercising with the VERIFY Command
. • • • 4-15
4-18
4.9
lOX OPERATING MODES
•••.
4.9.1
Command Mode • . •
4-18
4-18
4.9.2
Execution Mode • •
4.9.3
Interactive Mode.
4-19
4.10
lOX OUTPUT. • . . .
• . • • • 4-20
4.10.1
Activity Reports
.•••
4-20
4.10.1.1
The Format of Activity Reports.
4-20
4.10.1.2
The Content of Activity Reports
4-20
4.10.2
Error Reports
..•..
4-21
4.10.2.1
Data Compare Error Reports.
4-21
4.10.2.2
I/O Error Reports
.••••
4-22
4.11
THE TASK-BUILD FILE • . • • .
4-22
4.12
COMMAND DESCRIPTIONS •
4-22
ABORT
4-24
BADBLOCKS
4-25
BUFFERSIZE • •
4-27
COMPAREDATA
4-28
4-29
CONFIGURE
4-31
CTRL/C • . •
CONTROL C • • . •
4-32
DENSITY4-33
DESELECT . •
4-35
ERRORLIMIT • . . . • • • •
4-36
EXECUTE • • . .
4-37
EX IT • •
4-38
FILES11
4-39
HELP • .
4-40
INTERLEAVE
4-41
4-42
LOGFILE
LOOPBACK • .
4-43
4-44
PARAMETERLIST
PATTERN
4-48
4-49
PRINTSUMMARY •
PROCEED • • • .
4-50
4-51
RANDOM . • • .
iv

CONTENTS

4.13
4.13.1
4.13.2
CHAPTER 5
5.1
5.2
5.3
5.4
5.4.1
5.4.2
5.4.3
5.5
5.5.1
5.5.2
5.5.3
5.5.4
5.5.4.1
5.5.4.2
5.6
5.7
5.8
5.9
CHAPTER 6
6.1
6.1.1
6.1.2
6.2
6.2.1
6.2.1.1
6.2.1.2
6.2.2
6.3
6.4
6.4.1
6.4.1.1
6.4.1.2
6.4.2
6.5
6.5.1
6.5.2
6.6

RANGE
RECORDS
REPORTERRORS
RESTART
RETRIES
• • • •
RUNTIME
SELECT
Spy
START
SUMMARYTIME
TEMPORARYFILE
VERIFY • • •
VOLUMECHECK
WAIT • • • • •
WRITECHECK •
ERROR MESSAGES •
Error Messages With Device Specifications • •
Error Messages without Device Specifications •

4-52
4-53
4-54
4-55
4-56
4-57
4-58
4-60
4-61
4-62
4-63
4-64
4-65
4-66
4-67
4-68
4-68
4-74

THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)
BAD BLOCK REPLACEMENT FUNCTIONS
• •
RECOVERY TECHNIQUES
• • • • • • •
INSTALLING RCT • • • • • •
• • •
DISK CONFIGURATION OF MSCP DISKS •
••• • • •
Log i ca 1 Blocks (LBNs)
• • • • • •
Replacement Blocks (RBNs)
• • • • •
Revector Control Tables
• •
BAD BLOCK HANDLING ON MSCP DISKS •
••• • • •
Bad Block Detection •
• • • • • . • • •
Bad Block Notification • • • • •
• •
Bad Block Replacement
• . • • • • • • • •
Bad Block Revectoring
••••••
Primary RBNs •
• •
Secondary RBNs • • •
• • • • ••
•
COMPLETING PARTIAL BAD BLOCK REPLACEMENTS
• • • •
PREVENTING LOSS OF WRITE-BACK CACHE DATA •
•
RCT AND OTHER RSXllM AND RSX-llM-PLUS UTILITIES •
RCT AND THE ERROR LOGGER • • • • • • • • • • • • •

5-1
5-1
5-2
5-2
5- 2
5-2
5-2
5-3
5-3
5-3
5-3
5-4
5-4
5-4
5-4
5-5
5-5
5-5

RESOURCE MONITORING DISPLAY (RMD)
INTRODUCTION • • • •
•
Display Pages
• •
Setup Pages
• • • •
INSTALLING AND INVOKING RMD
• •
Using RMD at Individual Terminals • • • • • · •
Installing RMD at Individual Terminals
• •
Invoking RMD at Individual Terminals
• • •
Running RMD on a Slaved Terminal •
• •
THE HELP DISPLAY • • • • • • • • •
• • • • • •
•
THE MEMORY DISPLAY • • • . • • • .
Altering the Memory Display from the Setup Page
The FREE Command • • • • • • •
The RATE Command • • • • • • •
• • • •
Altering the Memory Display from the MCR Command
Line • • • • • • • • • • • • • •
• •••
THE ACTIVE TASK DISPLAY • • • • •
• • • •
Altering the Active Task Display from the Setup
Page • •
••••• • • • • • • • • • • • • •
Altering the Active Task Display from the MCR
Command Line • • • . •
• • • • • •
THE TASK HEADER DISPLAY • • • • • • • • • • • . •

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

6-4
6-7
6-7
6-7
6-7
6-8
6-8
6-9
6-9

CONTENTS
6.6.1
6.6.2
6.7
6.7.1
6.7.1.1
6.7.1.2
6.7.2
6.7.2.1
6.7.2.2
6.7.3
6.7.3.1
6.7.3.2
6.7.4
6.7.4.1

Altering the Task Header Display from the Setup
Page . . . • . • • • • • • • • • • . • . • • . 6-10
Altering the Task Header Display from the MCR
Command Line • . • • • . • • • .
. • • • 6-11
DISPLAYS AVAILABLE ONLY ON RSX-llM-PLUS
6-11
The I/O Counts Display • • • . . . • •
6-11
Altering the I/O Counts Display from the
Setup Page • • • • • • • • • . • • .
6-12
Altering the I/O Counts Display from the MCR
Command Line • • • . • . • • •
6-12
The System Statistics Display . • • • •
6-13
Altering the System Statistics Display from
the Setup Page . • • • • • • . • • • •
6-14
Altering the System Statistics Display from
the MCR Command Line • . •
••••
6-14
The General Statistics About a Cache Region
Display •
• • • • • • • • • • . • • • 6-14
Altering the RMD C Display from the Setup
Page • • • •
• • • • • . . . • • . • • • 6-15
Altering the RMD C Display from the MCR
Command Line
.•.•••.•••.•
6-16
The Detailed Statistics About a Cache Region
Display
. . . . • . . . • • . • • • 6-16
Altering the RMD D Display from the Setup
Page .

6.7.4.2
6.8
6.9
CHAPTER 7

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

6-17

Altering the RMD D Display from the MCR
Command Line
••••••..••.•••
MODIFYING THE TASK-BUILD COMMAND FILE
ERROR MESSAGES . • • • . . • • •

6-18
6-18
6-18

SETTING UP AND RUNNING THE QUEUE MANAGER

• • • • • • 7- 2
INTRODUCTION AND REVIEW . • • • .
7.1
7.2
QUEUE MANAGER COMMAND DESCRIPTIONS •
7-14
7-14
INITIALIZE/ (QUE /CR/SP) • • • • •
7.2.1
7.2.1.1
INITIALIZE/QUEUE (QUE /CR) • •
7-14
7-16
IN ITI AL I ZE/PROCESSOR (QUE /SP) . . • .
7.2.1.2
7.2.2
DELETE/ (QUE /DEL) • • . • • •
7-22
7-22
DELETE/QUEUE (QUE /DEL:Q)
7.2.2.1
7-22
7.2.2.2
DELETE/PROCESSOR (QUE /UNSP)
. • • • 7-25
ASSIGN/QUEUE (QUE /AS:)
7.2.3
7.2.4
DEASSIGN/QUEUE (QUE /DEA)
. • • •
7-25
STOP/ (QUE /STO) • • . . • • • .
• • • • • 7-26
7.2.5
STOP/QUEUE (QUE /STO:QUE)
7-26
7.2.5.1
7-26
STOP/QUEUE/MANAGER (/STO:QMG)
•••.
7.2.5.2
7-27
STOP/PROCESSOR (QUE /STO)
7.2.5.3
7-28
STOP/ABORT (QUE /KIL)
•••••
7.2.5.4
7-29
START/ (QUE /STA)
••••••.•
7.2.6
. • • • 7-29
START/QUEUE (QUE /STA) • • • . •
7.2.6.1
7-29
START/QUEUE/MANAGER (QUE /STA:QMG)
7.2.6.2
7-32
START/PROCESSOR (QUE /STA) • • . • •
7.2.6.3

CHAPTER 8
8.1
8.2
8.3
8.4
8.5
8.6
8.6.1
8.6.2

THE SHUTUP PROGRAM
PREREQUISITES TO RUNNING SHUTUP . • • •
..•
INVOKING SHUTUP
• • . .
SHUTUP INPUT • •
.•• • • • • • .
SHUT UP OUTPUT
• • • .
• • • •
THE SHUTUP.CMD FILE
• • • ••
RSX-llM SYSTEM SHUTDOWN . • • •
..•.
•
RSX-llM System Shutdown Procedure • • • • • • •
Example of an RSX-llM System Shutdown . • • • .

8-1
8-1
8-2
8-2
8-3
8-4
8-4
8-5

CONTENTS
8.7
8.7.1
8.7.2
CHAPTER 9
9.1
9.1.1
9.1.2
9.2
9.2.1
9.2.2
9.3
9.3.1
9.3.2
9.3.3
9.4
9.4.1
9.4.2
CHAPTE:R 10
10.1
10.2
10.2.1
10.2.2
10.2.3
10.3
10.3.1
10.3.2
10.4
10.5

10.6
CHAPTER 11
11.1
11.1.1
11.1.2
11.1.3
11.2

RSX-llM-PLUS SYSTEM SHUTDOWN • • • • • • • •
• 8-6
RSX-llM-PLUS Sy~tem Shutdown Procedure • •
8-6
Example of an RSX-llM-PLUS System Shutdown • • • 8-7
TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER
SYSTEMS
INTRODUCTION
Connecting Two Computers • • • • • • •
Location of DTE and MFT
ESTABLISHING TERMINAL EMULATION
• • • •
DCL Command Syntax • • • •
Examples
•.•.••••
PERFORMING FILE OPERATIONS •
• •
MCR Command Syntax
DCL Command Syntax •
• • • •
Examples
• • •
MESSAGES
DTE MESSAGES
MFT MESSAGES

•
• • • • •
•
• • • • •
•
• • •
• • • • •
•
• •
• • • • •
·

9-1
9-1
9-3
9-3
9-4
9-5
9- 5
9-5
9-7
9-8
9-8
9-8
9-10

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
INTRODUCTION TO VMR
. • • •
STARTING VMR • • • •
• • • • •
•• • •
Method 1: Running VMR
• • • • • •
• •••
Method 2: Installing and Running VMR from LB:
Method 3: Running VMR While Specifying an
Indirect Command File • • • • • • • • • • • •
VMR COMMAND SYNTAX • • • • • . • • • •
VMR Command Format • • • • • • • • • • •
Including Comments in VMR Commands • • . . • •
VMR FILE SPECIFICATIONS
• • • •
VMR COMMAND DESCRIPTIONS
ALTER • • • •
ASSIGN • • • • • • • • • •
• • • •.
CANCEL • • • •
••••
• • •
CONFIGURATION • • • • • • • • •
•• • • •
DEVICES
• • • •
• •
FIX-IN-MEMORY
• • • • •
INSTALL
• •
LOAD • • • • • •
• • • • • • •
LOGICAL UNIT NUMBERS •
• •
PARTITION DEFINITIONS
• • • •
REASSIGN
• • • •
REDIRECT •
• • • • •
• • .
REMOVE •
• • • • • •
RUN
• • • • • • • • • • • •
SAVE • • •
••••••••••
• •
SET
• • • • •
• •
TASKLIST •
• • • •
• •
TIME •
. • • • • • • • •
•
UNFIX
• • • • • • • • • • • • • •
UNLOAD
• • • • • • • •
•
VMR ERROR MESSAGES .
• • •

10-1
10-1
10-2
10-3
10-3
10-4
10-4
10-5
10-5
10-7
10-8
10-9
10-11
10-12
10-16
10-18
10-21
10-33
10-35
10-36
10-38
10-39
10-40
10-42
10-47
10-50
10-88
10-90
10-92
10-93
10-94

COMMAND LINE INTERPRETERS

...... .

· · · · CLI
- The Traditional RSX-llM/M-PLUS
DIGITAL Command Language
··· ..·.
- DECnet Remote Terminal Facility

INITIAL
MCR
DCL RMT
WRITING

CONCEPTS

AN APPLICATION CLI
vii

·.···...·.

11-1
11-2
11-2
11-2
11-2

CONTENTS
11.2.1
11.2.2
11.2.3
11.2.4
11.2.5
11.2.5.1
11.2.6
11.2.7
11.2.8
11.3
11.3.1
11.3.2
CHAPTER 12

Executive Directives for CLls
. . • • . 11-3
11-3
Basic Interaction with the Operating System
Task Names for CL I s . • • •
11-4
11-5
MCR Control Commands • • •
System Messages to CLls
•••.
11-5
CLI Message Descriptions • •
11-5
Prompts that Affect CLls .
.•••
11-7
11-8
System Handling of Continuation Lines
Interaction with Serial Command Processing
11-8
(RSX-IIM-PLUS only)
••••..
SAMPLE CLI • •
• • • • .
• 11-10
MACRO-ll CLI
• 11-11
FORTRAN CLI
• 11-16
THE DCL TASK

12.1
INTRODUCTION •
12.2
INSTALLING AND BUILDING DCL
12.2.1
Conventional Installation of DCL as a CLI
Alternative Ways to Use DCL
12.2.2
12.2.2.1
Run DCL as a Task
• • • • • .
12.2.2.2
Install as •.. DCL
12.2.2.3
Install as •.• CA.
• ••.••••
The MCR Command
. • • •
12.2.3
12.2.4
DCL SET Commands from MCR
. . • • •
Allowing Unrecognized Commands to Fall Through
12.2.5
to MCR . . . . • •
••••••••••••
Flying Installs
. • • • • • • • • • • .
12.2.6
12.2.7
Task Building DCL • • . • • •
. • ••
Summary of First Task Build
12.2.7.1
12.2.7.2
Summary of Second Task Build.
12.2.8
How the DCL Task Works • • . • . • • • • •
12.2.8.1
Interpreting DCL Commands . • . •
Constructing DCL Command Tables
••••
12.2.8.2
12.3
DCL COMMAND TABLES • • • . .
MODIFYING DCL COMMAND TABLES • • . • • •
12.4
12.4.1
Adding Commands • • • .
12.4.1.1
The PT/TT File • • • . • • • . • • • • •
12.4.1.2
The MCT Entry • • • • • • •
The Overlay Entry
. • . • . • • • • .
12.4.1.3
12.4.1.4
Incorporating the PT/TT and MCT
. . • • . .
Deleting Commands
• . • • • . . •••••
12.4.2
Modifying Commands • . • . • • • . . • . • • .
12.4.3
A GENERAL DESCRIPTION OF A METALANGUAGE
•
12.5
THE MACRO METALANGUAGE . •
.
12.6
INTERPRETING DCL COMMAND TABLES
•
12.7
Parser Processing
. • • •
.
12.7.1
Translator Processing
• • • .
•
12.7.2
Parser/Translator Handling of Nonliterals • •
12.7.3
Parser/Translator Handling of Literals . • • •
12.7.4
Summary of Parser/Translator Functions .
12.7.5
Examples . • • • • • • • • • •
•
12.7.6
MAPPING DCL TO MCR • • . . • .
. . • • .
12.8
THE INTERMEDIATE FORM (IFORM)
•
12.9
ATTRIBUTES OF SYNTAX ELEMENTS
•
12.10
12.10.1
AND
• • • • •
·
BC and BS
12.10.2
•
12.10.3
BCT and BST . • • • • •
•
12.10.4
CBM, CCBM • • • .
·
12.10.5
COP, OCOP
12.10.6
DIR
• • • • •
ERR
• •
12.10.7
• . • • . • ••
12.10.8
HLP
. • • • .
•
MAP, DMAP
• • ••
••••
•
12.10.9
12.10.10 NO •
• • • • . • • .
viii

12-1
12-1
12-2
12-2
12-3
12-3
12-3
12-3
12-3
12 - 4
12-4
12-4
12-4
12-5
12-5
12-5
12-6
12-7
12-8
12-8
12-9
12-9
12-10
12-12
12-13
12-13
12-13
12-16
12-18
12-19
12-19
12-19
12-20
12-20
12-21
12-21
12-24
12-26
12-27
12-27
12-28
12-29
12-30
12-31
12-31
12-32
12-32
12-36

CONTENTS
12.10.11 OPT, OPTR
• • • 12-36
12.10.12 PRO
12-37
12.10.13 QUA
• 12-38
12.10.14 TST
• • • • • • • 12-39
12.11
PREDEFINED SYNTAX ELEMENTS •
· 12-40
12.11.1
Basic Data Types • • • • • • • •
• 12-40
12.11.2
Common Command Elements • • • •
12-42
Special Parser Elements • • • • • • • •
12.11.3
12-43
12.11.4
Special Translator Elements
• • • •
• 12-45
12.11.5
Program Control Elements
• • 12-46
Example from DCL Command Tables
• • • • • • • 12-47
12.11.6
CHAPTER 13

POOL MONITORING SUPPORT

13.1
HOW YOU GET POOL MONITORING SUPPORT
13-1
13-1
13.2
THE EXECUTIVE POOL MONITOR CODE
13.2.1
Pool Events Affecting the Executive
13-1
High Pool Event • • • • • • • • • • •
13-2
13.2.1.1
13.2.1.2
Low Pool Event • • • • • • • • • •
13-2
Pool Monitoring Interface
••••
13-2
13.2.1.3
13.2.2
Pool Conditions
• • • • 13-2
13.3
THE POOL MONITOR TASK • • • • •
• • • • • • 13-3
13.3.1
Conditions Affecting PMT • • • • • •
13-3
13.3.1.1
Pool
Level and
Fragment
Size Are
Satisfactory • • • •
13-4
Low Pool Condition
13.3.1.2
13-4
High Pool Condition
13.3.1.3
13-4
Largest Pool Fragment Is Too Small •
13.3.1.4
13-4
13.3.1.5
Largest Pool Fragment Becomes Larger •
13-5
13-5
PMT Default Actions for a High Pool State
13.3.2
13.3.3
PMT Default Actions for a Low Pool State • • • 13-5
PMT Output to Terminals During Low Pool State 13-6
13.3.3.1
13.3.3.2
PMT Output to the Console Terminal During
Low Pool State • • • • • • • • • • • • • • • 13-6
13.3.4
PMT Default Actions for Extreme Fragmentation
13-6
13.3.4.1
Abortable Tasks
• • • • • • • • • • 13-7
13.3.4.2
PMT Messages • • • •
• • • • • • • • • • 13-8
13.3.4.3
Annotated Example of PMT Output for Extreme
Fragmentation
••••
13-9
13.3.5
PMT Task-Build Options • • • • • •
13-10
13.3.5.1
Controlling PMT Timing •
• • • • • 13-10
13.3.5.2
Controlling PMT Action . • • • •
• 13-11
Controlling Pool Use •
13.3.5.3
. • • • 13-11
13.3.6
Aborting PMT • • • • • • •
13-11
13.4
THE SET /PLCTL COMMAND • •
• • ••
• • • 13-12
Low and High Pool Limits • . . . . . . . . . . 13-12
13.4.1
Pool Fragment Size • • • •
13.4.2
• • 13-13
Base Priority for Nonprivileged Tasks
13.4.3
• • • • 13-13
CHAPTER 14
14.1
14.1.1
14.1.2
14.2
14.2.1
14.3
14.3.1
14.3.2

THE SHUFFLER
EXECUTIVE AND MEMORY USAGE • • • •
System-Controlled Partitions •
Partition Fragmentation • • • • • • • •
SHUFFLER PERFORMANCE • • • •
•••••
Monitoring The Shuffler • • • •
THE SHUFFLER ALGORITHMS
••••
The First Pass Algorithm • • • • •
Second Pass Algorithm
•••.

14-1
14-3
14-4
14-4
14-6
14-6
14-7
14-8

CONTENTS
CHAPTER 15

RSX-11M-PLUS SYSTEM RECONFIGURATION

15.1
15.1.1
15.1.2
15.1.3
15.2
15.2.1
15.3
15.4

THE RECONFIGURATION SERVICES • • . . • • . •
15-1
Reconfiguration Components (CON,RD:,HRC)*
15-1
Device States • • • • • • • • • • • . • • • • 15-2
Placing Devices Logically On Line and Off Line 15-3
INITIATING THE RECONFIGURATION SERVICES • • • • 15-4
Invoking CON . • • • • • • • •
• • • • 15-4
CON COMMAND SUMMARY
• • • .
15-5
CON COMMAND DESCRIPTIONS • .
••••
15-7
BUILD
• • •.
• • • • • 15-7
CLEAR . • • •
• • ••
••••
15-8
DISPLAY
• . • •
15-9
ESTATUS
• . • .
• 15-12
HELP • .
• • • •
. • • • • • 15-14
IDENT • . • . • • • • • • • •
• 15-15
LINK • • •
. • ••
• • . • • • 15-16
LIST. . .
• 15-17
OFFLINE • • • •
. • • .
• . • . • 15-19
OFFLINE MEMORY •
• • • • •
15-21
ONLINE . • • • •
• • • .
. 15-22
ONLINE MEMORY . • • • • • • • . • • • .
15-24
SET
• 15-25
SWITCH
. . • • • 15-27
UNLINK . • • . • • • • • • • •
• 15-25
15.5
SYSTEM FAULTS
• . • • •
• 15-28
15.5.1
Hardware Faults
• • • •
• • • • • 15-2B
15.5.1.1
Media Failures
• • 15-28
15.5.1.2
Transient Failures •
• • • •
• 15-28
Intermittent Failures
• 15-30
15.5.1.3
15.5.1.4
Soft Errors
. • • . •
• 15-30
15.5.1.5
Hard Errors • • • • • •
• • 15-30
15.5.2
Recoverable and Nonrecoverable Errors
• 15-30
15.6
FAULT ISOLATION • • • • . .
.•••
• 15-31
15.7
SYSTEM RECOVERY
• • • • ..
.•.•
• 15-31
Device Unit and Controller Failures • • • • • 15-32
15.7.1
15.7.2
Processor Failures • • • • . • . . • •
. • 15-32
MK11 Memory Box Failures • • • • • .
• 15-33
15.7.3
15.8
STAND-ALONE MAINTENANCE FOR MULTIPROCESSOR
SYSTEMS
. • • • • • • •
. • • .
• 15-34
15.9
ERROR MESSAGES • • • • • • . • • .
• 15-37
15.9.1
CON Error Messages •
• 15-37
15.9.2
HRC Error Messages . •
• 15-39

CHAPTER 16
16.1
16.1.1
16.2
16.2.1
16.2.2
16.2.3
16.2.4
16.3
CHAPTER 17
17.1
17.2
17.2.1
17.2.2
17.2.3
17.3
17.3.1

RSX-11M-PLUS I/O QUEUE OPTIMIZATION
INITIATING OPTIMIZATION • • • • • •
Displaying Optimization Status . •
SELECTING THE TYPE OF OPTIMIZATION • •
Adjusting the Fairness Count Limit •
Nearest Cylinder Method
Elevator Method
Cylinder Scan Method
ERROR MESSAGES • • • • •

16-1
16-2
16-3
16-3
16-4
16-4
16-4
16-4

RSX-11M-PLUS RESOURCE ACCOUNTING
INTRODUCTION
• • . •
CONTROL COMMANDS • • • • •
START/ACCOUNTING Command •
SET ACCOUNTING Command • •
STOP/ACCOUNTING Command
. • .•
SHOW COMMANDS • • • • • .
SHOW ACCOUNTING/INFORMATION Command
x

17-1
17-5
17-5
17-8
• 17-10
• 17-11
• • 17-11

• • •

CONTENTS
17.3.2
17.4
17.4.1
17.5
17.5.1
17.5.2
17.5.3
17.6
17.6.1
17.6.2
17.6.3
17.7
17.7.1
17.7.2
17.8
CHAPTER 18
18.1
18.2
18.2.1
18.2.2
18.2.3
18.2.4
18.2.5
18.3
18.3.1
18.3.2
18.3.3
18.4
CHAPTER 19
19.1
19.2
19.2.1
19.3
19.3.1
19.3.2
19.4
19.4.1
19.4.2
19.4.3
19.4.4
19.5
19.5.1
19.5.2
19.5.3
19.5.4
19.5.5
APPENDIX A
A.l
A.2
A.3
A.4

SHOW ACCOUNTING/TRANSACTION_FILE Command
•
WRITING AN ACCOUNTING REPORT PROGRAM USING
DATATRIEVE-ll • • • • • • • • • • • • • • •
SHOW ACCOUNTING/DATATRIEVE Command • • • • • •
USER TASK INTERFACE FOR CREATING TRANSACTIONS •
Calling $QTRAN • • • • • • • • • • • • • • • •
Calling $QTRNl • • • • • • • • • • • • •
Calling $QTRN2 • • • • • • • • • • • •
••
ACCOUNT BLOCKS • • • • • • • • • • • • •
•
Account and Transaction Block Diagrams.
•
Account and Transaction Block Offset
Definitions • • • • • • • • •
• •••
Account Block Li nkages • • • •
••
SYSTEM RESOURCES USED • • • •
•
Executive Space Requirements •
•••••
Secondary Pool Usage • • •
• • • •
RESOURCE ACCOUNTING MESSAGES •
••

17-12
17-16
17-17
17-17
17-17
17-18
17-19
17-20
17-22
17-32
17-38
17-39
17-39
17-39
17-40

RSX-llM-PLUS SHADOW RECORDING
PREPARING YOUR SYSTEM FOR SHADOW RECORDING •
CONTROLLING SHADOW RECORDING
••••••••
START Command
• • • • • • • •
STOP Command • • • • • • •
ABORT Command • • • •
CONTINUE Command •
DISPLAY Command
• • • • • • •
BAD BLOCK HANDLING • • • • •
• • • • •
Errors on the Primary Disk •
. ••
Errors on the Secondary Disk • • • • • • • • •
Errors on the Primary and Secondary Disk • • •
SHADOW RECORDING MESSAGES • • • • •
• • •

18-2
18-4
18-5
18-6
18-7
18-8
18-9
18-10
18-10
18-10
18-11
18-11

DISK DATA CACHING ON RSX-llM-PLUS AND MICRO/RSX
SYSTEMS
DATA CACHE FEATURES
• • • • • • • • •
DATA CACHE MANAGER (DCM) • • • • • • •
PERMANENT DCM IN A SYSTEM CONFIGURED USING VMR
THE DATA CACHE REGION • • • • • •
CREATION AND DELETION • • • •
FORMAT • • • • • • • • • • • • • • • •
DCL COMMANDS USED WITH DISK DATA CACHING
MOUNT Command
•• • •
• • • •
SHOW CACHE Command •
• • • • • •
SHOW DEVICE Command
• • • •
••• ••
SET DEVICE Command • •
• • • • • •
MCR COMMANDS USED WITH DISK DATA CACHING
••
MOUNT Command
• • • •
• • • • • •
RMD C Command
• • • • •
• •
RMD D Command
• • • • • • • • • •
• • •
DEV Command
• • • • • •
SET Command • • • •
• • • •

19-1
19-3
19-3
19-3
19-4
19-4
19-6
19-6
19-8
19-9
19-9
19-10
19-10
19-12
19-14
19-15
19-16

SERIAL DESPOOLER TASK
RECEIVE QUEUE OPERATION
TEXT REQUIREMENTS
TASK-BUILD INFORMATION
PRT ERROR MESSAGES • • •

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

A-l
A-l
A-l
A-2

CONTENTS
APPENDIX B

RSX-IIM/M-PLUS UFD CONVENTIONS

B.1
B.2
B.3
B.4

GROUP NUMBER •
B-1
MEMBER NUMBER
• . • • • • • B-2
EXAMPLE SYSTEM USER FILE DIRECTORIES • • • • • • • B-3
B-4
SYSTEM FILE-NAMING CONVENTIONS • . • . • • • •

3-1
4-1
4-2

Sample Console Logging Terminal Session
Exercising an RL02 with the FILESll Command
Exercising a Magnetic Tape with the SELECT
Command • • • • • • • • • • • • . • •
Exercising an NFS RK07 with the VERIFY Command .
Log File Output for Example 4-3
•••• ••
PARAMETERLIST Display Shown in Four Parts
PMT Output for Extreme Fragmentation
•••.
Code That Calls $QTRAN • •
•
Code That Calls $QTRNI • • . • • • • • • • • • •
Code that Calls $QTRN2 •
. ••

EXAMPLES

4-3
4-4
4-5
13-1
17-1
17-2
17-3

· 3-8
4-10
4-13
4-16
4-17
4-44
13-9
17-18
17-19
17-19

FIGURES
6-1
6-2
9-1
9-1
15-1
17-1
17-2
19-1
19-2
19-3
19-4
A-1

RSX-I1M Memory Display • • • • • • • • • •
• • 6-4
• • • •
RSX-11M-PLUS Memory Display
· • 6-5
Terminal Emulation with an On-Site System
9-2
Terminal Emulation with a Remote System . • • • • 9-2
Sample Configuration for Increasing System
Throughput • . • • • • • • • • • •
• • 15-19
Privileged Task Interface Overview.
• 17-21
Account Block Linkages. • • •
• • • • • • • 17-38
Format of Data Cache Region
• • • • •
19-5
Forma t of Pool Header Area •
• • • ••
19- 5
RMD C Page Display • . • • • • • • •
• 19-12
RMD D Page Display • • • • •
. 19-14
PRT Send Data Buffer Format
• . • •
• • • A-2

TABLES
3-1
4-1
4-2
4-3
10-1
10-2
12-1
15-1
15-2
B-1
B-2
B-3
B-4
B-5

Summary of Console Logging Commands • • • .
Four Categories of lOX Commands
• • • •
Parameter Commands by Device Type for SELECT
Parameter Commands by Device Type for SELECT
Command
. • • • •
. •
Functional List of VMR commands
SET Keywords • • .
DCL Command Tables
CON Command Summary
• • • .
Exit Status Values for CON ESTATUS .
• •
Group Number Identification
Member Number Identification • • •
MCR User File Directories (UFDs)
System UFDS
System File Types
••.••••

xii

•

· 3-3
• 4-4
4-9

4-58
• 10-2
· 10-51
12-8
15-5
• 15-12
• • • B-1
• . • B-2
· B-3
• B-3
• B-5
.

PREFACE

MANUAL OBJECTIVES
The RSX-IIM/M-PLUS System Management Guide documents system programs
and
procedures
that
test,
monitor,
maintain, and customize
RSX-IIM/M-PLUS operating systems after system generation.

INTENDED AUDIENCE
This manual is intended for system managers, operators, and system
programmers who perform system management functions.
The manual is
not intended for general users or applications programmers.

STRUCTURE OF THIS MANUAL
The RSX-IIM/M-PLUS System Management Guide consists of 19 chapters and
two appendixes as follows:
Chapter 1 summarizes each program and procedure described in
2 through 19.

Chapters

Chapter 2 describes how you use the Account File Maintenance Program
(ACNT)
to create and maintain accounts on multiuser protection
systems.
Chaptel~

3 describes how you use the Console Logger to control
I/O to
the console output device
(CO):
and record system messages at a
terminal and/or in a log file.

Chaptelr 4 describes how you use the I/O Exerciser (lOX) to detect and
diagnose I/O problems on the disk, terminal, and tape units in your
system's hardware configuration.
5 describes how the Bad Block Replacement Control Task
(RCT)
performs bad block handling and recovery on Mass Storage Control
Protocol (MSCP) devices such as the RA80.

Chaptel~

Chapte:r 6 describes how you use the Resource Monitoring Display
(RMD)
to display information about the active tasks in your operating system
and the availability of system resources.
Chapter 7 describes how to set up the
multistream line-printer spooling.

Queue

Manager

for

convenient

For RSX-IIM-PLUSsystems only, this chapter describes how you set up
batch processors that enable youto.direct a command sequence to the
operating system at a predetermined time of day_

xiii

PREFACE
Chapter 8 describes how you use the SHUTUP Program to
system in an orderly fashion.

shut

down

the

Chapter 9 describes how you use the Data Terminal Emulator
(DTE)
to
log
in from a local Micro/RSX system to an external computer system
and conduct an interactive session.
Chapter 10 describes how you use the Virtual Monitor
(VMR) to alter a system image file on disk.

Console

Routine

Chapter 11 describes command line interpreter tasks, including how
write them and how to use new Executive directives in them.

Chapter 12 describes how to task build and install the DCL task with
various options.
It also describes the Macro Meta language, which is
a set of macros that describes the mapping from DCL syntax
to MCR
syntax.
With this language, you can alter or add commands to extend
DCL.
Chapter 13 describes the Pool Monitoring Support that controls the use
of the system's dynamic storage region (pool).
Chapter 14 describes the Shuffler, which
is
memory space in system-controlled partitions.

task

that

compacts

Chapter 15 desQribes how you use the RSX-IIM-PLUS reconfiguration
services
(CON andHRC) to reconfigure system resources to isolate the
system from the effects of faulty hardware elements.
Chapter 16 describes RSX-IIM-PLUS I/O Queue Optimization, which
improves the throughput of the disk subsystems used in your system.
Chapter 17 describes RSX-IIM-PLUS Resource Accounting, which creates a
transaction file of system usage information.
Chapter 18 describes RSX-I1M-PLUS Shadow Recording, which allows your
system to back up all information being written to a Files-ll disk.
Chapter 19 describes RSX-IIM-PLUS and Micro/RSX Disk Data Caching, a
feature that enhances I/O operations by reducing the number of
physical I/O requests performed during a disk operation.
Appendix A describes the Serial Despooler, which is superseded by
Queue Manager to handle line-printer spooling for most systems.
Appendix B describes the set of User File Directory
observed by the operating system for files on disk.
naming conventions is also included.

the

(UFD)
conventions
A section of file

ASSOCIATED MANUALS
Before you
read this manual, you should be familiar with the
RSX-llM/M-PLUS MCR Operations Manual,
the RSX-IIM/M-PLUS utilities
Manual, and, for-ofGITAL Command Language users, the RSX-IIM Command
Language Manual or RSX-IlM-PLUS Command Language Manual.
Although you
do not need to read the RSX-IIM System Generation and Installation
Guide or
the RSX-IIM-PLUS System GeneratIon and I~allatlon GUIde
oerore reading this manual, system generation logically precedes your
use of the programs and procedures documented in this manual.

xiv

PREFACE
CONVENTIONS USED IN THIS MANUAL
Convention

Meaning
Designates user
input.
Responses
programs are designated in black ink.

blue ink

from

Designates RSX-IIM-PLUS multiprocessor system
information.
A horizontal ellipsis indicates that the
command line element immediately preceding
the ellipsis can be repeated one or more
times.
A vertical ellipsis indicates that part of a
command sequence or program output continues
but is not relevant to the discussion of the
example.

lowercase

In a command line,
lowercase words
and
letters indicate that you substitute a value.
Usually, the lowercase word describes the
value to be substituted.

UPPERCASE

Command elements other than those shown in
lowercase for which you substitute a value
are always uppercase.
Within descriptions,
these command elements are never truncated.
In examples, they may be truncated according
to the rules of the particular program.

A reverse number is a white number printed in
a black circle. These numbers key a part of
an example to the text that explains that
part of the example.
The reverse number
appears both in
the
example
and
the
explanation.

[optional]

Square brackets indicate
item is optional.

that

shading

Shaded portions of
operating system.

describe

text

the

enclosed
only

one

Gray shading indicates that the text applies
only
to
RSX-llM-PLUS operating systems.
Shading is not used in chapters that describe
programs that are unique to RSX-llM-PLUS.
Redshading.indfcatesthatthe text
only to RSX-IIM operating systems.

applies

Portions of text that are not shaded describe
both
operating
systems,
except in the
RSX-IIM-PLUS-only chapters.
The symbol g~
indicates that you press a
key while simultaneously pressing and holding
down the CTRL key;
for example, CTRL/C,
CTRL/O.

SUMMARY OF TECHNICAL CHANGES

The programs and procedures described in this manual have all been
enhanced to
include new software features.
The following lists
descriptions of new software and the enhancements to previously
existing software for RSX-llM Version 4.2 and RSX-lIM-PLUS Version
3.0.

Account File Maintenance Program (ACNT)
On RSX-IIM-PLUS systems, passwords are now automatically encrypted
when they are created. Passwords can now be up to 39 characters long.

I/O Exerciser

(lOX)

Support for exercising terminals has been added. This is accomplished
by using the LOOPBACK parameter to the SELECT command.

Resource Monitoring Display (RMD)
Two new displays about cache regions have been added: the RMO C page,
which displays general statistics about a cache region; and the RMO 0
page, which displays detailed statistics about a cached device.

SHUTUP Program
Messages now include a "reason for
systems.

shutdown"

field

RSX-IIM-PLUS

Virtual Monitor Console Routine (VMR)
The VMR chapter includes the following changes:
•

New Introduction.

•

New Table of Commands.

•

Revised section describing how, to start VMR.

•

Additional information about the FIX-IN-MEMORY command which
describes
fixing
tasks on RSX-IIS systems with memory
management (PLAS) support. Also, information has been added
which describes fixing tasks on RSX-IIM and RSX-llS systems
above 124K-words.

xvi

SUMMARY OF TECHNICAL CHANGES

•

Information has been added to the NOTES section of the INSTALL
command which describes (on RSX-llM and RSX-llM-PLUS systems)
what happens to changes made in a common when a common is
removed and then reinstalled. New information has also been
added which describes restrictions for using the INSTALL
command to install device commons that were created with the
SET/PAR command.
New INSTALL command examples have been added.

•

A NOTE has been added to the LOAD command indicating that you
can load drivers above the l24K-word limit on RSX-llM systems.

•

More information and new restrictions have been added to the
REDIRECT command, which describes redirecting I/O requests
from one physical device to another.

•

New NOTES have been added to the REMOVE command describing (on
RSX-llM and RSX-llM-PLUS systems) what happens to changes made
in a common when a common is removed and then reinstalled.
Also, another new NOTE has been added which indicates (on
RSX-llM-PLUS systems) that a region cannot be removed if there
are tasks installed in the system that reference that region.

•

The description of the RUN command has been totally revised.
New RUN command examples have been added.

•

The SAVE command supports the following new devices:
DU:
MU:
Also, a NOTE to the SAVE command has
saving a system on paper tape.

•

information

about

New SET command examples have been added.

New VMB: Keywords
The following VMR commands have new keywords:
ASSIGN

/SYS '1' EM

(RSX-llM-PLUS
systems
Defines,
displays or
system-wide
logical
assignments.

only. )
deletes
device

INSTALL
(RSX-llM-PLUS
systems
only.)
Specifies
where a read/write
common will be checkpointed to.
(RSX-llM-PLUS
systems
only.)
Informs the system that the task
will
use
the
fast-mapping
feature of the Executive.

/FMAP

xvii

SUMMARY OF TECHNICAL CHANGES
SET

/AVO

(Full-duplex
terminal
driver
only.)
Informs the system that
the
specified
VT100-series
terminal has the advanced video
option.

/BLKMOD

(Full-duplex
terminal
driver
only.) Enables local editing and
block-mode transmission for the
specified terminal.

/DEC

(Full-duplex
terminal
driver
only.)
Indicates
that
the
specified terminal is upwardly
compatible with the VT100-series
of terminals.

/EDIT

(Full-duplex
terminal
driver
only.)
Informs the system that
the
specified
terminal
can
perform
ANSI-defined advanced
editing functions.

/HSYNC

(Full-duplex
terminal
driver
only.)Enables
host-terminal
synchronization, which controls
the typeahead buffer to prevent
it from overflowing.

/PARITY

Enables parity
checking.

/PASTHRU

(Full-duplex
terminal
driver
only.)
Instructs the system to
ignore the original function of
special characters typed at the
specified
terminal
and
to
instead pass them to a program
in their binary form.

/PRINTER_PORT

terminal
driver
(Full-duplex
only. )
Informs the system that
the specified terminal has a
printer port.

/REGIS

(Full-duplex
terminal
driver
only.)
Informs the system that
the specified terminal supports
the ReGIS graphics set.

/SOFT[=ttnn:]

terminal
driver
(Full-duplex
only. )
Informs the system that
terminal
can
the
specified
accept
software-defined
character sets.

/TTSYNC

(Full-duplex
terminal
driver
only. )
Enables
the terminal
synchronization option for the
specified terminal.

xviii

generation

and

SUMMARY OF TECHNICAL CHANGES
Modified VMR Keywords
The following VMR command keywords have new information:

INSTALL
JCLI
Indicates that the
Interpreter (CLI).

task

being

installed

Command

Line

/XHR
Use the jXHR keyword whenins.tall i n9 tasks with external headers.
SET
/BUF
The buffer size for a terminal must be greater than or
14(decimal).

-equal

/POOLSIZE
If you do not specify a value (on RSX-llM-PLUS systems), VMR also
displays the lowest physical address at which a partition can
start (32-word blocks) •

/REMOTE
The terminal has a line to the following additional multiplexers:
DHUll
DHVll
DLVll
DZQll
DZVll
You can specify several different answer speeds for the following
variable-speed multiplexers:
DHUll
DHVll
DZQII
DZVll
You cannot specify
multiplexer.

answer

speed

for

DLll

DLVll

/SPEED
You can specify additional speeds for the following multiplexers:
DHll
DHUll
DHVll
DZll
DZVll
DZQll
If you have a DZIl, DZQll, or DZVll multiplexer, the receive and
transmit speeds must be the same because these multiplexers do
not support split speeds.

xix

SUMMARY OF TECHNICAL CHANGES
/TERM
The SET/TERM command supports the following
types:
DTCOI
LN03
PC3XX

LA50
LA2l0
VT2XX

additional

terminal

LQP02
LQP03

New VMR Error Messages
VMR has new error messages that pertain to bus switches,
regions, LOAD/CTB keyword, fast mapping, and pool space.

shared

Disk Data Caching
RSx-IIM-PLOS and Micro/RSX now include support for disk data caching.
Disk data caching enhances I/O operation by reducing the number of
physical I/O requests performed during a disk operation.

CHAPTER 1
INTRODUCTION

This C'hapter summarizes the functions of the programs and procedures
documented in the chapters of this manual. Each chapter is summarized
in the order in which it is presented in the manual.

Chapter 2 - Account File Maintenance Program (ACNT)
The Account File Maintenance Program (ACNT) allows a privileged user
to create and maintain an account file on multiuser protection
systems. Each account entry consists of information such as an
account number
(the user's UIC) and password, the default device
(SY:), the user's first and last name, and the default command
language interpreter
(CLI). ACNT allows a privileged user to create
an account file, add and delete accounts, modify accounts, list the
accounts, examine an individual account, and sort the account entries.
The chapter describes, with examples, how to use each ACNT function.

Chapter 3 - Console Logger
The Console Logger consists of a driver (CODRV) and a task
(COT ••• )
that handle r/o to the console output device
(CO:) and record
time-stamped system messages on a terminal and/or in a log file.
You
use MCR SET commands from a privileged terminal to start and stop
console logging, disable the log file or the console terminal, and
reassign the log file and console terminal.
You select Console Logger
support during SYSGEN.
The chapter documents the console logging commands and presents an
extensive terminal session with explanations of the commands used in
the session.

Chapter 4 - I/O Exerciser (lOX)
The r/o Exerciser (rOX) detects and diagnoses r/o problems on the
disk,
tape,
and
terminal
units
in
your system's hardware
configuration.
rox exercises Files-II disks, non-file-structured
disks, magnetic tapes, DECtapes, and cassettes.
rox performs three
kinds of exercises. The rox Command Lan~uage enables you to specify
and control the exercise for the units In your system. You choose an
exercise appropriate to a unit and set exercise parameters that
determine how the unit is exercised.
The chapter documents each lOX command in alphabetical order and
provides examples that explain how t~ set parameters for the three
kinds of rox exercises.
1-1

INTRODUCTION
Chapter 5 - Bad Block Replacement Control Task (RCT)
The Bad Block Replacement Control Task
(RCT)
handles bad block
replacement and recovery on Mass Storage Control Protocol (MSCP) disks
such as the RA80.
Bad block handling on MSCP disks consists of four
stages:
detecting, notifying, replacing, and revectoring.
The disk
controller (UDA50) detects bad blocks and notifies the driver (DUDRV).
The driver activates RCT.
RCT performs the bad block replacement
functions that enable the controller to revector (redirect)
I/O from
the bad block to the replacement block.
RCT also performs replacement and recovery on MSCP disks that went off
line during bad block replacement or before the contents of a
write-back cache were copied to the disk.
The chapter describes bad block
techniques.

replacement

functions

and

recovery

Chapter 6 - Resource Monitoring Display (RMO)
The Resource Monitoring Display (RMO) provides information about the
active tasks
in your operating system and the availabilit~ of system
resources.
This information includes the active tasks, thelr location
in memory,
the amount of memory they occupy, and the available pool
space. RMO generates dynamic displays on CRTs and "snapshot" displays
on hardcopy terminals.
There are three displays:
memory, active task,
and task header.
There is also a help page that tells you how to switch display pages.
Each display page has a setup page from which you can alter the
contents of the associated display page.
You can access any RMD
display and alter the contents of the display from the MCR command
line.
On RSX-llM-PLUS systems, a system statistics
count display are also available.

display

and

error

log

The chapter contains an example and explanation of the memory display.

Chapter 7 - Setting Up and Running the Queue Manager (QMG)
The Queue Manager (QMG) has the primary function of controlling the
system's line printers and the print jobs that are passed to them.
Users can specify the number of copies they want printed, the time the
job is to be released for printing, whether the file is to be deleted
after printing, and which printer they want to use.
Users can display
all information about the QMG queues and can alter the characteristics
of jobs in queues.
Some installations may have user-written output
processors that pass jobs to devices other than line printers.
The
nonprivileged functions of QMG are documented in the RSX-IIM/M-PLUS
Batch and Queue Operations Manual.
This chapter documents the privileged system management functions of
QMG.
Systems can have as many as 16 output queues (including the
default PRINT queue) and 16 output processors.
Print processors can
be initialized to print a specified number of flag pages before each
print job, to accept or reject print jobs specifying that lowercase
printing is required, and to handle many kinds of printed forms.

1-2

INTRODUCTION
On RS.X .... IlH ...PtUS systems, QMG also
.supports
bateh
processingRSx .... IlM ....PLUS systems can have as many as 16 batch queues and 16 batch
processors.
The chapter includes an illustrated explanation
Queue ~(anager.

for

setting

the

Chapter 8 - The SHUTUP Program
The SHUTUP program allows a privileged user to shut down the system in
an orderly fashion.
SHUTUP prompts for the number of minutes to wait
before shutdown, the number of minutes between shutdown messages,
and
the number of minutes to wait before disabling logins. Before halting
the system, SHUTUP performs cleanup functions such as logging out all
logged·-in
terminals,
submitting
the user-written command file
LB: [1,2]SHUTUP.CMD to Indirect for execution,
stopping the Queue
Managel:, Console Logger, and Error Logger (if present), deallocating
checkpoint space, and dismounting mounted devices.
The chapter provides an example and explanation of SHUTUP output.

Chapte]~ 9 -

Terminal Emulation and File Operations with Other Systems

A local Micro/RSX terminal can log in to and conduct an interactive
session with an external compufer system. This session is established
using the Data Terminal Emulator (DTE). The external system can be an
RSX-llM or RSX-llM-PLUS system, a Professional Personal Computer, or
another Micro/RSX system. Once a local Micro/RSX terminal is logged
in to an external system, the external system becomes the host system.
The host system views Micro/RSX as remote.
During an interactive
session, files can be transferred between the host system and
Micro/RSX. Files are transferred using the Micro/RSX File Transfer
Utility.
The chapter describes how to perform terminal emulation and file
operations between a Micro/RSX system and an external system, with
examplE~s •

Chaptelt: 10 - Virtual Moni tor Console Routine (VMR)
The Vi:rtual Monitor Console Routine (VMR) is a task that contains a
subset of the Monitor Console Routine (MCR) commands. You use VMR to
make the same changes to the system image file on disk that you would
make to the running system with MCR.
Some of these changes are
setting the size of pool, creating partitions,
loading drivers, and
installing tasks.
The advantage of using VMR is that you can almost
completely configure a system image file before you bootstrap it.
The chc:ipter presents each of the VMR commands in alphabetical order.

Chapter 11 - Command Language Interpreters
A command line interpreter, or CLI,
is a
task that
services
unsolicited commands meant for the operating system or an appl~cation.
These commands are not prompted for by any task nor are they glven to
a task by a read operation on a terminal. A CLI is also an efficient

1-3

INTRODUCTION
means of interfacing an application command processor to any number of
terminals, because no read QIO or character AST processing is
involved.
This chapter introduces the concepts of CLls on
systems.
The chapter includes enough information
programmer to write application-specific CLls.

RSX-IIM/M-PLUS
to allow the

Chapter 12 - The DCL Task
The DIGITAL Command Language
(DCL)
is a general purpose command
language syntax implemented on several DIGITAL operating systems.
This chapter explains the ways in which DCL can be installed on your
system and documents the means by which the DCL task parses and
translates commands.
In addition, this chapter documents the Macro
Meta Language, a set of MACRO-II macros used to define DCL. An
experienced programmer can add commands to DCL or remove them, or
alter DCL by changing parts of DCL, such as altering defaults or
eliminating qualifiers.

Chapter 13 - Pool Monitoring Support
Pool monitoring support controls the use of the system's dynamic
storage region
(pool). This support monitors pool levels, restricts
use of pool, and notifies you when pool is near depletion.
This
support consists of two parts:
the RSX-IIM/M-PLUS Executive pool
monitor code and the privileged Pool Monitor Task (PMT).
The chapter describes how to get pool monitoring support, the
conditions that affect PMT, PMT defaults, and how to abort PMT. There
is also an annotated example of PMT output for extreme fragmentation.

Chapter 14 - Shuffler Support
The Shuffler (SHF)
is a privileged task that compacts space in
system-controlled partitions when a memory allocation failure occurs.
The Shuffler operates only within system-controlled partitions.
The chapter describes Shuffler structure, Shuffler interaction with
the operating system, ways to monitor the Shuffler, and Shuffler
algorithms for the operating system.

Chapter 15 - RSX-I1M-PLUS Reconfiguration Services
The reconfiguration services consist of two tasks (CON and HRC) and a
driver
(RD:).
With these services, you can alter or display
information about various system resources such as devices and memory.
The main purpose of the reconfiguration services is to allow you to
isolate faulty hardware so that it does not affect the system
adversely.
The chapter describes the functions of CON, RD:, and aRC.
The
reconfiguration commands are described, with examples of how to use
each one. The chapter also gives procedures for recovering from
various hardware errors.

1-4

INTRODUCTION
Ch~p.ter: ····.·l.,·.....SX...llM-PLUS

flo Queue .Optiaization

I/oqueu;eoptimlzatlon is used to improve the throughput of the disk
supsystems . used in your RSX-IlM-PJ;.USsystem. This is done by making
th~>most . >effectiveuse of the listofllorequests1nthequeue for . a
particular disk device. Three metbodsof optimization are provided:
Nearest:. Cylinder, Elevator., and Cylinder Scan.•
The chapter descr ibes each of the three methods ofopt.imization and
how to choose the one that is best for your system. There is also a
list of error lDessages given by the SET /OPTcommand.

Chapter· 17· -RSX-IIM-PLUS·Resoarce.Accounting
provides a .transaction file of system u.sage
information.
Information is gathered on each user ina system and on
total system utilization.
This information can be used to bill
individual .. users for the. resources used and for measuring overall
sy_temperformance. Byanaly.zing.the data in the transaction file,
you can determine such thIngs as who . used the system, for how long,
how much CPU time they used, and a number of other statistics.
For
system utilization, you can find out the number of users, number of
109ins, how much input/output was done, and other system usage
information. The information in the transaction file can be displayed
or you can write a program to access the file and analyze the data.
Re~oureeAcoou.nting

The chapter describes how Res·ource Accounting works
example of a transaction file output.

and

contains

Cbapter 18 - RSX-IlM-PLOS Shadow Reoo.rding

Shadow Recording allows your system to back up all information as it
is being written to a Files-ll disk. It does so by creating two
identical disks called a "shadowed pair.'tMore than one pair of disks
may be shadowed, but Shadowed disk pairs cannot overlap. The first
disk of the pa.ir, the primary disk, is the original disk that exists
whether 01' not Shadow Recording is active. You can make any disk on
your system, including the system disk, the primary diskofa shadowed
pair.
The cnapterdescribes Shadow Recording, how to prepare your system for
it, and how to control it. The Shadow.Recording commands and error
messages are described in detail ..

Chapter 19 - aSX-llM .... PLUSand. Micro/RBX Disk Data Caching

Disk datacaohing isa feature on RSX-IlM-PLUS and Micro/RSX systems
that enhances I/O operations by reduoingthenumberof physical I/O
requests performed during a disk operation.
In addition to monitoring all I/O operations performed on disk
devices, disk data caching deoreases the number of physical I/O
operations taking place on "cached" disk drives by using a cache
partition in memory.
Copies of disk data are placed in the cache
partition, making the data available for memorl'-to-memory transfers
instead of disk-to-memory transfers during an I/O request.
The chapter describes all of the disk data oaching features.
disable, override, mOdify,·and monitor disk data caching.

1-5

You

can

INTRODUCTION
Appendix A - Serial Despooler (PRT)
The Serial Despooler Task (PRT ••• ) provides a means of eliminating
contention for
the system line printer.
Rather than waiting for the
line printer to become available, the task directs the output intended
for the line printer to a disk file.
This appendix briefly describes the Serial
documents Task Builder information for it.

Despooler

Task

and

Appendix B - RSX-llM/M-PLUS UFO CONVENTIONS
The RSX-llM and RSX-llM-PLUS operating systems observe a set of User
File Directory (UFO) conventions for files on disk.
These conventions
provide a uniform and consistent method of locating, allocating, and
maintaining a file on disk.
This appendix describes group and member numbers and their use
in
identifying the contents of system UFOs.
A section on file-naming
conventions is also included.

1-6

CHAPTER 2
THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)

RSX-llM and RSX-llM-PLUS each provide an Account File Maintenance
Program (ACNT)
for creating and maintaining an account file on a
multiu.ser system. The account file contains entries for all User
Identification Codes (UICs) authorized within the multiuser protection
systerrl. One UIC can have several users, each user having his or her
password.
When you try to log in, the system checks the HELLO or
LOGIN command parameters against the account file to determine whether
or not. the user should have access to the system.

With Version 3.0 of RBX-IIM-PLUS, passwords
are
automatically
encrypted when a new account is created.
Once a password is
encrypted, the password cannot be seen. Therefore, if you forget your
pafSsword, you must get a privileged user to enter the ACNT program to
obtain a new password.
NOTE
Please be aware that no new user-written encryption
routines
will
be
supported after Version 3.0.
However, encryption routines written prior to Version
3.0 will continue to be supported.
If you. wish to change your password, you must use the SET PASSWORD
comman.d to do so. You have to know your old password if you want to
use the SET PASSWORD command.
If you do not remember your old
password,
then a privileged user can run ACNT and obtain a new
password for you.
Each account in the account file contains the
following information:
.'

UIC (the account number)

Password

•

User's default system device

•

User's default file protection

First name

Last name

User's Command Line
multi-CLI support

Date and time of the user's most recent login

The number of times that the user has logged in to the system

Interpreter

2-1

(CLI)

the

system

has

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)

2.1

•

Whether the user's terminal is to be slaved after login

•

On RSX-llM-PLUS systems, a session identifier

•

On RSX-llM-PLUS systems, the user account number

INVOKING ACNT

Invoke ACNT, from a privileged terminal, as follows:

ACNT identifies itself and displays a list of options after
the RUN corrunand.

you

type

A nonprivileged user can use ACNT only to modify the account entry for
his or her password.
(See the RSX-llM/M-PLUS MCR Operations Manual).
On RSX-llM-PLUS systems, a nonprivileged user cannot use ACNT to
modify the account entry for his or her password.
If a nonprivileged
user attempts to run the ACNT program, ACNT will print the following
message:
Can not b e
Use

2.2

SET PASSWORD

run f Y' () III
to chanSe

non .. p r i IJ i 1 e g E' (j
password

t E' T' tTl ina 1

~OUT'

ACNT OPTIONS

ACNT is an interactive
following options:

program

that

allows

privileged

•

(A) Add accounts to the file

•

(E) Examine individual account entries in the file

•

(M) Modify individual account entries in the file

•

(L) List account entries in the file

•

(D) Delete account entries from the file

•

(S) Sort the account entries in the file

•

(CTRL/Z) Exit from ACNT

users

the

ACNT prompts you for an option. Enter one of the letters indicated in
the parentheses above.
The program responds by requesting further
input or by displaying information for the option you selected.
The
remainder of this chapter discusses the ACNT options and includes
examples of each.

2-2

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
2.2.1

Creating the Account File

The Crleate option lets you create the account file.
Create the
accoun-t file immediately after generating your system to allow normal
use of the system. The Create option allocates the account file
(LB:[O,O]RSXll.SYS)
and sets the file protection so that only
privil1eged users and privileged task-s can access the account file.
You may copy and optionally extend the account file using the
Periph1eral Interchange Program (PIP) (see the RSX-llM/M-PLUS Utilities
Manual).
The new copy will have the default file protection,
therefore,
immediately run ACNT.
ACNT will detect the incorrect
protection codes and restore proper protection.
The following example shows how to create the account file on RSX-llM
systems.
After you invoke ACNT, it responds with a list of options
and a prompt, as follows:

Options are: A - ADD, C - CREATE FILE, D - DELETE, E - EXAMINE,
I... -- L.IST? M -- r~ODIF,(, S - SORT, CTFn/z - EXIT
Ent.er- option!
C ~
F 1"1 t i~: l' III a ;-: i lTl 1..1 IfI n UITI b e r

Cl f

~ C C l11J II t s:

:3 5.

Enter a decimal number (n.) to specify the maximum number of account
entries to be listed in the file.
The system then creates an account
file (LB:[O,O]RSXll.SYS) large enough to contain 35 accounts.
When the Create operation is complete, press the ESCAPE key to request
a list of options. Then you can add accounts to the account file.

2.2.2

Adding Account Entries

The Add option lets you add accounts
prompts you for the following:
•

UIC (the account number).

•

Password.

•

User's default system device.

•

User's default file protection.

•

First name.

•

Last name.

the

account

file.

ACNT

User's CLI.
If your system does not have multi-CLI support,
• ACNT
does not prompt you for the user's CLI (MCR is the
default).
•

Whether the user's terminal is to be slaved after login.

•

On RSX-llM-PLUS systems, a ses<sion ident.ifier.

•

On RSX-IIM-PLUS systems, a user account number ..

ACNT maintains the file in ascending order by UIC.

2-3

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
The prompts for the password, first name, and last name specify the
maximum number of characters that ACNT accepts. Passwords can be up
to 39 characters long, but be aware that systems using DECnet can only
use a-character passwords.
The legal characters for user names and
passwords are as follows:
•

A through Z, upper- and lowercase

•

0 through 9

•

. (period)

•

$ (dollar sign)

•

(apostrophe)

(hyphen)

(exclamation point)

The default system device prompt requests a device name and unit
number (optional if 0). ACNT accepts logical, physical, and pseudo
device names. The acceptance of logical and pseudo device names lets
you move the user disk to another drive without having to change the
default device in the account file. When specifying the device name,
do not include a colon (:).
RSX-llM-PLUS systems include two additional prompts:
one is for a
session i4entifier and the other is for the user account number. The
session identifier and user account number are optionally used by the
Resource Accounting Program (see Chapter 17). The session identifier
is also used by the HELLO pro9ram (see the RSX-lIM/M-PLUS MCR
Operations Manual).
--The following example shows how to add entries to the account file
RSX-1IM systems:

Options are: A - ADD, C - CREATE FILE, D - DELETE, E - EXAMINE,
L - LIST, M - MODIFY, B - SORT, CTRL/Z - EXIT
Enter I:lf-t'ion:A tMfJ
El"ltef' a('~C(3IJnt or <ESC> for options ( N,N ): 5, :t.S tMfJ
F',l$SSWO f'd

lJt~ifault

(

-(::.:39 chars t

S~:lstelTl

F:i. rst nam~

f:ttEt'.?C3

device ( {IDU ): DB

chars. ): JANE ~
Last I'laltle ( <::::14 chaT'S. ): BARRETT ~
D€~ t' a u 1 t f i 1 ~ P 1'1) tee t i 0 f'i ( ( SY ,OW, GR , W01
Enter U!l.er CLI (defi~t.llt::::MCR): [leL (fl[ij
(

<:::1=~

Slave l~f:~rlllin(!tl'f r(Y/NJ]:
UFD DB1:[COOS,015]]

): RWED, RWE[I , RWF.: D , R

ffi)

In this example, ACNT creates an account in the account file for Jane
Barrett.
Jane's password is A1B2C3 and her default system device is
DBO:. Her default file protection is read, write, extend, and delete
access for system, owner, and group: the world has read-only access.
(This is also the system default protection.) Jane's CLI is DCL, and
her terminal is not slaved after login.
ACNT remains in Add mode until you press the ESCAPE key to
list of options.

2-4

request

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)

The followingexamp~eshows how to add an account to
syst.em.
RSX~11M-PLUS

RSX-IIM-PLUS

AceouMt File Haintenan~e Pro~r.~

At!cOtJnt Uti 1 it~ opt.ionsa re:

Add
Delete

Add .n account to file

EH ami ns

Del~te a~ ac~ount file ent~~
E>~a", ine e>~ i st i nSl.acco~~nt

Li$t

Li.t

Ma~ifv

Sort

file
account file
So rt aCCCHJt",t. file
.cca~nt

~odifY

CTRL/Z
Te~min~t. utllit~ session
Enter .·opt:i. C;'r'i: He
Erlter aC\~olJnt (~.rou,. 'lllE~mber); 10,1 () .811
De~f.cltJl. ts~'S t,E"!. device ( DftU ) t [1l}O
p~$sw(i)l~d( ~9ch~T's.orftwer >l BASEl< I TPL 8ll
First name (1:2 charstor feWer): Kathleen fIij
t ..ii~<::.\, rUliril.ti'.<i4t:!ha'r'5..0 rftlwer) l ;ifearl ~
Dl~tralJ.lt ~\leprotection . .•• <t: SYtOW, GR, WOl·): •. tRWE'D, RWF.tf, R·, Rl fIij
['c!ffcHJ l·ti dl rector~. $t~'irl~U: e.trcHJP,membe r] or [rlJ1Jme 1) l KATHLEEN
Se~s$ion ident(3 ~h~l"tS. (u~feweJ' >! KLH 8ll
Ac~cot,Jr·(~numb(~J'(4·.·disrt.$orfewer ):23 mJ

Er'ttf.I'f'l~SerCLI(tjefaH..Ilt~!DCL)!
(II)
StavEl . .• t.ermi n~l~ .(Y/Nl: .... N,.
Disi.iable lo~ inll 0 SOtJt me1ts aste $, , t ¥ IN J; tt(lI)

In this example , ACNT erea:t,ed an a.Ccount for Kathy Bean..
Kathy' s
t._~EK.ITPL, . Which is encryp~ed byACN'f~hentbeaccountis
cr~ated.Herdefault . fileprot.ect.ion
1.8
read, write, extend i and
delete access for system and owner, and. read only. access· for group and
world. Her defaultdireotory st.ring(which must be .9 . characters or
fewer) . is KATHLEEN, .. and her default system device is DUO:. Her
session.·. ident;i.fieris •.·KLM,·. he!raccountnuniber is 23, her CLI is. DeL
(b~caus.. she ...s.J;>e~ifiedthedefault), and her·· ter;minal is not slaved •
L09.tnand logout<messagesare·notdisabled.
pa~sWQr4

After her account has been created, and the system has finished
prbmpting for all the neces.saryinfo:tm.ation, the system returns the
following message:

Examining Account Entries

2.2.3

The Examine option displays two lines of detailed information for each
account in the account file on RSX-llM systems. The first line
contains, from left to right, the following information:
•

UIC

•

Password

•

First name

•

Last name

•

User's default system device

2-5

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
The second line contains the following information:
•

Date of the last login.

•

Time of the last login.

•

Number of times the user has logged in to the system.

•

User's CLI.
If your system does not have
ACNT displays the default CLI (MCR).

•

Whether the user's terminal is to be slaved after login.

multi-CLI

"'I1~;,o'
. d.li;.pla~j..~~Im&t£Qll.:for
a~
,"It·, .. :::;
:
.!::;,.,
.
."." .... '. :.:<:.: . :'... "
.. ': :.\
.'::::"
;'.
"'
~"

;:::··i~>

.~,:.:.

~::'5::" ~

::~

:~ ..

!;.;:'.:~:r.~:,:,

':~'

support,

account

~ ~~

j ;,~

DI(';:~~::~a~~t~i~ ~: ~~~~ltTt·" IE

i~rJ~/lp~i:~r.~t.N~·~ .·):.~l
fEij~

'~O'()1' \t~ct
/'

'. .;. . .: ,"

.. ;/

. :',

:eQt.t·"~'~it

. " .,."'" .,

,',' :',:

. 'i

.,' .. :.

".~

,bcJhbji~.'ti 4cQo~nt.il ••_in~. 'l'be first line
)~, '.~ .'
I'd O')O'} , fil',t name, last name, and
f)11+!"...Set)nd l1fte lfI,iS1plays t"e date of
·~· • ~.·~ni :tim:eL.:azbj,:a' last. ~ogin:(lS*OS: 5S ), the
g'e<I,~·n.. .pll~· hij';:, CLI
(·DeL),· and the
Q~' hlstltmit1al:( Nl',~

ACNT remains in Examine mode until you press the ESCAPE key to request
a list of options.

The following example shows hoW to d.isplay information for an
on an RSX-lIM-PLUS l!iIyste:

account

RSX-l1t1··PlllS Accountf' i Ie Maintenance Pros ram

ACC01Jntutil.i ti\,d . options a re t
Add

Addar!iSccount tot' i 1 e

Delate

Del~t~an

EX.3It.ine

E::·a~mirle

Li~t
Kodif~

li.t account fila
MDdifw account file
lor~ account file
Terminate titilits 5eslion

Sort

C1RL/Z
En tt~ r

('J'.}t 1. on:

Ent.e"

,~ceUj.Jnt

.~eountfile

ent~w

aHt'!>tinaac'~(.)t.;mt

E . 1f(D

(tf'CHf}tt,·lllF.Hf.ber): 1()~10
25~AUG-BS 08:30:02 RSX-11M-PLUS Multiuser A~caunt File List
Ownt~~l' ;;:; (010010J
Lo<ifindefaul
t::: ttlJOO t (KATHY)

In;Sln~

tlefCL I

Be:t~N

"":
l::

tieL

Pa.e 1

Frlame = KATHY
f'as$wOl'd:::: (FNCRYPTEtI)
Sassi on J. [I :::: 1<t..H AccolJnt
:.:: 23

TDtBllo~ins :::: 2
Lsstlasin ~ 24~AUG-85 12:46:?2
ChaT' act. l' i s t, i c s ;:;:. NO S 1is \I r.~ D11~ 'fd irs t. r i n'it .Ih:~fProt.ction :::: (R.W'ElhRWf.lhR, to

In this example, Kathy Bean·saccount is examined. The first line of
the display li$ts her UIC (010;010) and her login defaults (her
default system deviceisDtJO: and her default directory string is

2-6

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
[KAT~~]).
The next line of the display lists her last name, first
name, and, in the password field, (ENCRYPTED) is displayed. If any of
the passwords in any accounts that are being examined are encrypted,
the password field will display (ENCRYPTED) instead of the password
itself. The third line displays Kathy's CLI (DCL) , her session
identifier (KLM), and her account number (23). Next, her total number
of 109ins and last login are displayed. The fifth line of the display
shows Kathy's terminal characteristics (her terminal is set to
noslave) and her default directory string is left blank, because it is
also her login default, which is shown in the first line of the
displalY. The last line of the display shows Kathy's default file
protection.

After examining an account, or a group of accounts, ACNT
with t.he following message:
K:e~

2.2.4

<RETURN> t(J

c(JntinlJi-:'~'

prompts

you

CTRI..IZ for ACNT options menu:

Modifying Account Entries

The Modify option allows you to change the password, default system
deviCE!, default file protection, first name, and last name for an
account, and the slave/no-slave status of a terminal. You can change
the Cr.I of an account if your system includes the multi-CLI option.
In an RSX-llM-PLUS system, the Modify option also allows you to change
the sE!ssion identifier and the account number.
After you specify the account to be modified, the program displays an
account entry and asks for verification. Type either Y (Yes) or N
(No) t.O indicate that the correct account was or was not specified.
If you specify N, ACNT searches the file for another entry with the
same trIC. When you enter a Y, ACNT prompts for the entry details.
Press the ESCAPE key if you do not want to change an item.
The following example shows how to modify account
RSX-llM system:

information

Options are! A - Ann, c - CRFATF FILEt n - DELETE, E - EXAMINE,
L -

l .. t81',

11 -

MODtFY, S -

SORT,

CTR!...!! -. E:Xlr

Enter cn-:.tilJnt M tRrn
Ent,.€H .;sCCCHH'lt (:>r <ESC> for options ( N,N >: 5,l2 ':@)
[[0051012JJ BARB
BARBARA
SPENCER
03/05/81
15:00:11
00006 MeR
N
Thi~:;

f.l~ntl'~

r.(Y/Nl1~

Type <ESC> to leave

DBO:

entr~

unchansed

({:::::39 r.:h~:rs.): BE:S tRrn
D f.d~ a IJ 1 t. ~:; .~ sd', e m d e vic e ( 11 nu ): @
Fil'st namE:' \. <:·:1.2 ('hal'S. ): @
L3st I"\Bllle ( <>:::14 ch(;~r!:; + ) : @

Pc;ss~wt:}r'd

Entf:tT'

USfH'

CI... I

(df!fi:HJlt::::MCR):

nla ... (.;~ t,er-minal? [(YiN]]:

DeL (fl@

In this example, Barbara Spencer's account is modified. Her password
(BARB) is changed to BES, and her CLI (MCR) is changed to DCL. ACNT
remain.s in Modify mode until you press the ESCAPE key to request a
list olf options.

2-7

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
The following example shows how to modify account
RSX-IIM-PLUS system:

information

R8X-llM-PLUS Account File Maintenance ProSram
Account
Add

options are!
Add an account to file
Delet~
Delete an account file entr~
Examine
Examine existin. account
List
list account file
Modif~
Modif~ account file
Surt
Sort account file
CTRL/Z
Terminate utilitw session
Ent.er option: M (flrn
Enter account (~rouP' member)! 10,1.0 ~
OI.Jrtf:>\· :.:: [010010]
losindefaults :::: nUOO:rKATHYJ
Fname :::: KATHY
Password:::: (ENCRYPT~D)
L.nalTl~ ::: BEAN
Session ID :::: KlH A~count
:::: 23
II Ed'CL J '::: neL.
Te>tallogins :::: 2
Lastlo~in ~ 24-AUG-85 12:4~:22
f~ ~'l i:l r" act e r i s t i. c s :::: NOS 1 ~~ y e
rl e f d irs t, r- i f' 9 _.
DefProtection = ERWED,RWED,R,RJ
Thi-:; ~ntT'~1 ? [[YIN]]: Y ~
THPe <ESC> to l~ave entry unchdn~ed
Utilit~

F'as-,;;w(H'd (39 chaT'S. or- ft,lwer-):
D (-~\ of au]. t ':; ':/ S t, ::~ rtl d \:~ '.) :i. C P. ( n1) U ):

@
@

First nalIll'-! (1.2 char'::). 1.)1' f€·)wer )t @
La,:.t name (14 chaT'-i). O'f' fewer): @9
Ded'i:nJ) L f 11~" F'Y-() t.~':C:4;._:i. on ([ Sy, O~h GR, W() J >; @
Default d:i.T'f'~Ct.()T>~ st.ring KATHI..t::EN
New dire~tor~ h~s been cT'Psted
Ent-f.~r' I.I;;>I:·~Y' Cl..I (d(-?fat.Jlt~:nC' . ):
~) 1. ~~ veto c r' III .i n Iii 1 '? [[ YIN J J:
1'1 :i {::- a h 1. e 1 () !:.! i n /1 0 <30 u t nl (~ s S -is ~ e s '?

~3 I.:! 'c, ~;-. _i 0 n
FI C r: n l..I f'I t

®ID

r. Y / N :I! @
.i. d ,~> 1"1 t i r .l f.~ T' (3 c h c; r !:!.. () T' fewer): KKK
III I J'il b Ii~> T' (4 rl i '.:.t i t. S r.J T' few e I' ) : @

In this example, Kathy Bean's account is modified.
Her default
directory string is changed to KATHLEEN, and her session identifier is
changed to KKK.
When she changed her default directory string, the system printed
message:

the

After ACNT has prompted you for changes to all the account fields,
prompts you with the following message:

1< (~ .! <" P F T 1..1 P ! J :>

2.2.5

t Cl

C () n t

:i. It IJ P ,

C T f;: I. I?

'1" D T'

A CN T

Cl p t

:i. 0 n S

III P n I) :

Listing Account Entries

The List option either displays on the user's terminal or spools to
the line printer all account entries in the account file or a
specified group of entries. If you specify the line printer, ACNT
creates
the
file
ACCNT.DMP.
This file contains the account
information you specified. ACNT prints the file if the spooler is
installed in your system. If the spooler is not installed, you may
print ACCNT.DMP after you exit from ACNT.

2-8

THE ACCOUNT PILE MAINTENANCE PROGRAM (ACNT)
'!'he following example
RSX-IIM-PLUS system:

shows

how

list

account

RSX-llM-PLUS Account File Maintenance

entries

Pro~ram

Account Utilit~ options are:
Add
Add an account tp file
Delete
Delete an account file entrw
Examine
Examine existin~ account
List
List ~ccount file
Hodifw
Modifw account file
Sort
Sort account file
CTRL/Z
Ter~inate utility session
Ent,e r Of< t. ion: L (B@
Onl~ the old ilNFNCRYPTFD twpe passwords can be printed
Pl"il"lt. pas'SW(J rds (def au 1 t no) l' LY IN]: ~
All 6(::(::ounts (def<iitIJlt rm)1 (YIN): ~
Lis·t, eso Terminal(defaIJlt.) or File(ACCOUNT.tlMP) LT/FJ:
~
If any of the passwords are encrypted, the password field will display
(ENCRYPTED) instead of displaying the password itself.
After all the accounts you have
returns the following prompt:
Ke,,:~

specified

have

<RET URN> t.o cord.. i nlJEH CTRL/Z fQ r ACNT

been

OF't ions

listed,

ACNT

menu:

On RSX-llM systems, this option lists accounts in the same manner.
However, RSX-llM systems do not support password encryption. When the
list ()peration is complete, ACNT displays its options and prompts for
a choice.

2.2.6

Deleting Account Entries

The DE!lete option eliminates individual accounts from the file. After
you specify the account to be deleted, ACNT displays the account entry
and requests a Y (Yes) or N (No) response for verification.
If the
response is N, ACNT searches for another account with the sarne UIC.
If thE~ response is Y, ACNT asks if you want to delete the account's
UFD Clnd other files. Another Y response deletes these files.
If you
enter N in response to the deletion query, the account's files and UFD
are left intact.
The following example shows how to delete accounts
file on an RSX-1lM system:

from

the

account

Options are: A - ADD, C - CREATF FILE, n - DFlETF, f - EXAMINE,
L - LIST, M - MODIFY, S - SORT, CTRL/Z - ~XIT
Enter opt.ion: D ~
E: n t e~ l' ace 0 I.m tor <: E' SC:> f 0 t' 0 p t ion s. ( N, N ): 5, j:1 ~
[[005,012]] MLK
MAUREEN
KACZKA
DB1:
08/06/85
08:46:51
00004 nel
N
T h :i. s e rd~ I' ~ 'l' C[ YIN 11: y ~
Delete llFII <.~nd files? [(YIN)]: Y ~
PIP DB1:[(005,Ol~]J*.*;*/DE
>PIP DB1:[[O,OJJ005012.DIR;*/DE
In this example, ACNT deletes Maureen Kaczka's UFD and files.

2-9

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
The following example shows how to delete accounts
file on an RSX-IIM-PLUS system.

RSX-llM-PlUS Account File Maintenance

from

the

account

Pro~ram

Account U~ilitw options are:
Add
Add an account to file
Delete
Delete an account file entr~
E:·{anline
Examine existin. account
List
list account fjle
MOI."H f"~:f
Modify account file
~)() r t
Sort account file
CTRL,I Z
Te t' fJI ina t e~ 1..1 til i t ~ s e s s ion
Enter c)ptionZ D ~
E n ~ e I' a c to: () U n t
Own~r

(~~i T' () UP,

III (7.\ mbeT' )!

lnam€' : ;

HE~IN

D~1fCLI

:::: Del..

1. 0 , 1 0

L.osindefaults :::: DUOO:rKATHYJ
Fn~me = KATHY
Pa~sword:::: (ENCRYPTED)
Session ID :::: KlH A~count
= 23
la5tl"~in = 24-AUG-85 12:46:22
DefdirstrinS

[0100101

Characteristics = NOSlavp
DefPrutection :::: [RW~D,RWED,R,RJ
T h .i. '::; e rd, l' Y '? r.: YIN J t Y (@)
De1.f?tlO:\ IJFD and i":i.lf~~)? [VitO: y ~
Accuunt entry has been deleted

In this example, ACNT deletes Kathy Bean·s account and files.

2.2.7

Sorting Account Entries

The Sort option sorts the account entries in ascending order by UIC.
The following example shows how to sort the account file on an RSX-IIM
system:

Options are! A - ADD, C - CREATE FILE, D - DFLETF, F - EXAMINE,
L - LIST, M - MOnlFY, S - SORTy CTRl/Z - EXIT
Ent(~~" cption! S (@)
When the sort operation is complete, ACNT displays all its options and
prompts for a choice.
The following example
RSX-I1M-PLUS systems:

shows

how

sort

the

account

file

RSX-l1M-PLUS Account File Maintenance ProSr8ID
AccDunt

Ut,ill.t·~.)

Add
Delete
E >~ ,~1l1 i f". (.?
List-.
M(Jdi. f'::~

Sort
CTPI./Z
En t e l' UP t :i. 0 1"1 !

Clr--tiorts aI'f.':

Arid ~n ~ccount to file
Delete an account fjle entr~
J~ ;< i-! 11'1 i rl &~ f".£' }( i s t, i n g ace i) 1.1 n t
list account file
Modi. '1"'", acci",1I.mt file
Sort d2CQUnt fjl~
T f~ r- HI i f", <:l t ~:' u t. i :I. i t ~ S I"! <5 S ion

S ~

After the sort operation is complete, ACNT
message and then redisplays the ACNT menu:
Accnunl

ril~

is now sorted by Ule

2-10

returns

the

following

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
2.2.8

Exiting from ACNT

The Exi.t option allows you to exit from the ACNT program.
followi.ng example shows how to exit from ACNT on RSX-llM systems:

The

Options are! A - ADD, C - CREATE FILE, n - DFlETE, E - EXAMINE,
L - LIST, M - MODIFY, S - SORT, CTRL/Z - EXIT
Ent(2('

t:ipti.()nt

(CTRL/zl

When yc.u exit .from ACNT, ACNT displays the following message
terminal:

your

OP'ER("TtON COMPI.ETE

The following example shows how to
systems:

exit

from

ACNT

RSX-llM-PLUS

R5X-l1M-PLUS Account File Mpintenance Prosram
Account Utility options are!

Add an account tu file
Delpte an Bccount file entrw
E >: a I'tI i nee >~ i s t 'i. n SaG C0 1..1 n t
LL~t dccount file
Modify account file
Sort account file
T~rffiinat~ utiljt~ session

Add
n~\1.ete

E~{atnine

1..1 <.;;t
Mot.:h f~:·!
S()y''l,

CTr~L'/Z

Enter

option!

©TRL/zl

When ycm exit from ACNT, ACNT returns the following message:
A C' (;:' 0 I..i n t

2.3

f i 1. t;~ nl Cl d i. fie a t ion i r; co IJI P 1 e t e

ERROR MESSAGES

The ACNT program returns the following error messages:
ACNT -- Account already exists
Explanation: You attempted to add an account with a UIC and
password that already exists in the account file.
ACNT -- Account file already exists
Explanation: You attempted to create an account
already exists.

file

that

ACNT -- Account file error
Explanation: The program detected
processing the account file.

I/O

error

while

ACNT -- Account file full
Explanation: The account file is full; you cannot add
further accounts. See the description of the Create option
for details on how to enlarge the account file.
ACNT -- Cannot find account
Explanation: You attempted to delete, examine, or modify an
account that does not exist.

2-11

THE ACCOUNT FILE MAINTENANCE PROGRAM (ACNT)
ACNT -- Invalid default device name
Explanation: The default system device specified is
directory device.
ACNT -- Warning

not

** Device does not exist on current system.

a
OK?

[y IN] :

Explanation: The specified default device is not in the
system.
If you enter Y, ACNT retains the device name as a
logical device name. ACNT prompts again for the device name
if you enter N.
ACNT

Invalid option
Explanation: In response to the Enter option: prompt, you
did not specify A,
C,
D,
E,
L, M, S, or CTRL/Z, which
represent valid ACNT options.

ACNT -- Listing file error
Explanation: When you use the List option, ACNT opens the
file SY:[current uic]ACCNT.DMP. This message indicates that
ACNT cannot open the file; for example, the device is full
or it does not contain a UFD for the current UIC.
If the
device is full, delete some files.
Create a new UFD if
there is no UFD for the current UIC.
ACNT -- Syntax or command input error
Explanation: You typed an
correct data.
ACNT

-- Workfile - dyne

memo

invalid

character.

Enter

the

exhausted

Install
Explanation: There is insufficient dynamic memory.
the task in a larger partition, or install it with a larger
increment.
ACNT

-- Workfile - virtual storage exceeded
Explanation:

The workfile exceeds virtual memory.

2-12

CHAPTER 3
THE CONSOLE LOGGER

The Console Logger consists of a driver (CODRV) and a task (COT ... )
which together control I/O to the console output device (CO:) and
record time-stamped system messages on a terminal, in a log file,
or
both.
You
select
support for console logging during system
generat:ion.
For RSX-IIM systems, console
systems.

3.1

logging

available

only

mapped

THE CONSOLE OUTPUT DEVICE (CO:)

Your system has a console output device (CO:) and a console terminal.
When t:he Console Logger is active, I/O to CO: is controlled by the
consolE~ output task (COT ... ) and the console driver (CODRV).
When the
Console Logger is not active, CO: is a pseudo device, and I/O to CO:
is cont:rolled by the terminal driver.
In both cases, output to CO:
can bE~ forwarded to a terminal that you assign as the console
terminal.

3.1.1

CO:

as a Pseudo Device

As men1:ioned in the previous section, CO: is a pseudo device when the
ConsolE~
Logger is not active. You can redirect CO: to any terminal
on your system using the MCR REDIRECT command.
The terminal driver
controls all I/O to CO: that is redirected to the console terminal.

3.1.2

CO:

with the Console Logger Active

When the Console Logger is active, the console driver (CODRV) and the
console output task (COT ... ) control all I/O to CO:. You use a
console logging command to assign the console terminal (see Section
3.4.5) rather than redirecting CO:
by means of the MCR REDIRECT
command.
There are two advantages to using the console logger to control I/O to
CO: . ~['hese are as follows:
I..

Console logging allows you to record messages sent to CO:
in
a log file. You can record messages on the console terminal,
in the log file, or both. This flexibility enables you to
inspect the log file at any time and to free a terminal when
you do not need an on-line display of console logging.

3-1

THE CONSOLE LOGGER
2.

The console logger time-stamps messages to co: that have not
been time-stamped by the task issuing the message in the
following form:
hh:mm:ss hours, minutes, and seconds.
Also, prior to outputting the first message after a change of
date, the Console Logger outputs the current time and date.

3.2

INSTALLING COT ••. AND LOADING CODRV

If you select console logging at system generation time, SYSGEN
installs the console output task (COT ... ) and loads the console driver
(CODRV) by including the appropriate commands in SYSVMR.CMD. You only
need to install COT ... and load CODRV if one of the following
conditions exists:

3.3

You have removed one or both of
console logging.

them

and

want

You have altered SYSVMR.CMD to eliminate them.

restore

COMMUNICATING WITH THE CONSOLE LOGGER

You can use MCR commands to communicate with the Console Logger.
Tasks use the CODRV driver to communicate with the Console Logger.

3.3.1

User Communication with the Console Logger

COT ... is a privileged task. From a privileged terminal, you issue
console logging commands to start and stop console logging, assign the
console terminal, and specify the console log file.
Table 3-1
summarizes the console logging commands. There are no DCL equivalents
for the console logging commands. Section 3.4 discusses each console
logging command in detail.
These commands are processed by the
COT ... task.

3.3.2

Task Communication with the Console Logger

Tasks communicate with the console driver (CODRV) by issuing OIOs.
CODRV handles OIOs to CO:
for reading, writing, attaching, and
detaching. All other I/O functions to CO: are passed to the terminal
driver as if they were issued directly to the console terminal.

3.3.2.1 Writing to CO: - Tasks can issue OIOs to print system
messages on the console terminal or write system messages in the
console log file.
For example, HELLO issues a 010 to print a message
to the console terminal each time a user logs in to the system.
Messages to CO: may begin with a CTRL/G to ensure that COT ... sends
the message to the most recently assigned console terminal, even if
you have disabled the console terminal by specifying the NOCOTERM
option (discussed in Section 3.4.4).

3-2

THE CONSOLE LOGGER
The buffer in COT ... accepts messages not longer than 256(10) bytes.
Note ·that using the MCR SET /BUFFERSIZE command to set the buffersize
of device co: does not affect this restriction.)
Table 3-1
Summary of Console Logging Commands
MCR Command

Meaning

SET /COLOG

Displays the current
console terminal and
logfile assignments

SET /COLOG=ON

Starts console logging

SET /COLOG=OFF

Stops console logging

SET /COLOG/NOC[OTERM]

Disables the console
terminal

SET /COLOG/COT[ERM][=TTnn:]

Enables the console
terminal or changes the
console terminal assignment

SET /COLOG/NOLOGFILE

Disables the logfile

SET /COLOG/LOG[FILE][=[filespec]]

Enables the console logfile
or changes the logfile
assignment

3.3.2 • .2 Reading from CO: - Tasks can issue OIOs to read input from
the console terminal.
For example, an operator can use the console
terminal to respond to prompts by a system task that require user
input.
COT ... does not record messages in the log file that are read
from the console terminal.

3.3.2.3 Attaching and Detaching CO: - Tasks may attach to CO::
however, the attach is a NOP. Though tasks may attach or detach CO:
they are not allowed exclusive access to Co:.

3.4

CONSOLE LOGGING COMMAND DESCRIPTIONS

You use console logging commands to perform the following functions:
•

Display the current console terminal and log file assignments

•

Start and stop console logging

•

Change the console terminal and log file assignments

•

Disable the console terminal or the log file

3-3

THE CONSOLE LOGGER
The general format of console logging commands in MCR is as follows:
>SET /COLOG[[MCRoption]] ...
where:
SET

The MCR SET command

COLOG

Console logging keyword

MCRoption

One of the console logging functions.
these options to three letters.

3.4.1

Displaying the
Assignments

Current

Console

Terminal

You can truncate

and

Log

File

To display the current console terminal and log file assignments, type
the following:
::- ~~; F T / C ill.. Cl G

Use this option to determine if the Console Logger is active.
When
the Console Logger is active, COT ... displays the current console
terminal and/or log file assignments. For example:
::- '::) E T / COL () G

COT -_ ....
COI'"I~.C)] p

LG:,~;file

TTOOO:
DBOOO:[[1,4]]CONSOLE.LOO;1

If the Console Logger is not active, the display option indicates
following:

the

COT ---

3.4.2

Con<.:,ol(7~

None

L.o<-:tfi l.f~

NDI"I~~

Starting Console Logging

The following command line starts console logging:
>~;FT

/COLO(1::::()N

When you start console logging, COT ... retains the current console
terminal assignment.
If you have just bootstrapped the system,
COT ... assigns CO: to TTO:. The default location and name of the log
file is LB:[1,4]CONSOLE.LOG. COT ... always creates a new version of
the default log file when you start console logging.

3.4.3

Stopping Console Logging

The following command line stops console logging:
>SET /COL.OG:=:OFF

When you stop console logging, the current console terminal assignment
is retained.
Use the MCR DEV command to display the current console
terminal. Section 3.5 discusses how you can use the MCR DEV command
to monitor how CO: is redirected.

3-4

THE CONSOLE LOGGER
NOTE
Do not abort COT ....
pool fragmentation.

3.4.4

Aborting COT ...

causes

severe

Disabling the Console Terminal

To dis.able the console terminal, type the following command:
}8[T ICOLOG/NOC[[OTfRMJJ
This command line enables you to maintain a
log file of system
messages without using a terminal as the console terminal.
This is
especi,ally useful if your system does not have many terminals or if
you cannot spare a terminal to dedicate to receiving system messages.
When you do this, messages starting with a bell still corne out on the
consolI;:! terminal (i. e ., Device not ready).
To completely disable CO:
(that .is, to stop these messages) assign CO:
to NL:.
Once you have disabled the console terminal with the NOCOTERM
the following command:

option,

}SET ICOLOG/COTERM
restorl3s the most recent console terminal assignment.

3.4.5

Reassigning the Console Terminal

The following command line reassigns the console terminal:
~S[T

ICOLOG/COT[[[RMJJ[[=TTnn:JJ

where ~rrnn:
is the newly assigned console terminal.
When you
bootstrap your system,
the default console terminal assignment is
TTO:. When you start console logging, the default console terminal
assigrunent is the current console terminal.

3.4.6

Disabling the Log File

To disable the log file, type the following command line:

:> :3 E T / C () LOG I N() 1_ 0 HF I L E
This command line enables you to continue recording system messages
time-s1:amped by COT... at the console terminal without recording the
messages in a log file.

3.4.7

Reassigning the Log File

The following command line reassigns the log file:
>8ET ICOLOG/LOG[[FIlE][=(filespec]]]
where "filespec" is any legal file specification as described in the
RSX-ll~1/M-PLUS
Utilities Manual.
The default file specification is
LB:[1,4]CONSOLE.LOG.
3-5

THE CONSOLE LOGGER
To change only part of the file specification for the log file,
type
only that part of the file specification after the equal sign that you
want to change from the default. For example, if LB:
is ORO:
and
you want to make the log file DBO:[301,55]CONSOLE.LOG, type the
following:

>SET ICOLOG/LOGFILE=DBO:r301,55J
If you want to make the log file TESTLOG.LOG in
LB:, type the following:

the

default

UIC

>SFT ICOLOG/LOGFILE=TESTLOG
In all cases, COT fills in the missing parts of the file specification
with parts from the default file specification, LB:[1,4]CONSOLE.LOG,
and creates a new version of the log file.
To create a new version of the current log file, type the following:

:> nF T / C iJ L. iJ fj / ,_ nGF I l.. E :.:
If you have disabled the log file with the NOLOGFILE option, this
command line restores the most recent log file assignment. Although a
new version Gf the log file is created, the rest of the file
specification does not change.
To change the log file back to the default, type the fOllowing:
>8[T

/COLOG/L.OGFILE

This command line creates and opens a new version of the
file.

3.4.8

default

log

Using Multiple Console Logging Commands

You can enter multiple console logging commands in a command line.
The following command line:
starts console logging, assigns the
console terminal to TTI7:, and opens a log file named TESTLOG.TST in
the default UFO on LB:

>S[T !COLOG=ON/COTFRM=TT17!/LOGFIL[=TFSTLOG.TST
The following command line disables the console terminal and
the log file to the default:

restores

>8ET /COLOG/NOCOTFRM/LOGFTLE

3.5

MONITORING THE STATUS OF CO:

To use the MCR OEV command to determine the status of CO:,
console logger is active, enter the following:

while

the

>Drv CO:
The system responds as follows:

coo:

LOADED

This response means that the console driver (CODRV) is loaded and that
COT .. , handles system messages to CO:.

3-6

THE CONSOLE LOGGER
Use the console logging display option to display the console terminal
assignment as follows:

>8ET /COLOG
If you. have disabled console logging, use the MCR
detenm:ine the terminal assigned as CO: as follows:

>DEV

coo:

DEV

command

pseudo

device

co:
lTnn:

where nn is
redirected.

the

terminal

which

the

CO:

Before COT .•. exits,
it redirects CO:
to the current
console
terminal.
If there is no console terminal (because you disabled it
with the NOCOTERM option) when you stopped console logging, then CO:
is redirected to the last terminal COT ... assigned as the console
terminal. In this case, the terminal driver handles messages directed
to CO: and redirects them to TTnn:.
If you have disabled the console terminal with the NOCOTERM option but
continue to record system messages to co:
in a log file, then use the
MCR DEV command to determine the status of co:

>DEV

coo:

co:
LOADED

This response means that the console driver is loaded and that
COT •.. handles all messages directed to CO:; however, system messages
are not directed to a terminal. Use the display option to verify that
CO:
is not assigned to a terminal.

3.6

REDIRECTING CO:

Use the MCR REDIRECT command to redirect co: to a terminal, only when
the console logger is not active.
If you try to redirect co: while
the console logger is active, you will receive the following error
message:
)RED

Device not redirectable

For example, if the Console Logger is active, the console terminal is
assigned to TT2:, and you stop console logging, COT ... redirects CO:
to TT2: before exiting. Use the MCR DEV command to verify that CO:
is redirected to TT2:. To assign the console terminal to TTO:, use
the MCR REDIRECT command as follows:

>RED lTO:=CO:
If you then start console logging again, COT ... will assign
the console terminal.
NOTE
Do not redirect co: to co:.

3-7

TTO:

THE CONSOLE LOGGER
3.7

READING THE LOG FILE

Because the current log file is open for writing if LOGFILE is
enabled,
you can read it only by using PIP with the Shared Read (/SR)
switch. For example, if the log file is ORO: [1,4]CONSOLE.LOG, and you
type the following:

)PIP TI:=DRO:C[1,4JJCONSOLE.lOG
PIP responds as follows:
PIP -- Open failure on input file
DRO:C1,4JCONSOLE.LOG;1
Accessed for write

To read the log file, type the following:
>P T. P T I : ;::: DR 0: I: [ 1 ,41"] CON S £) I. E • LnG I S F:

A sample log file follows:
:ll.l:43~:17l logout IJser
16:43:35 Lo~in user
16:45:07 LoSin user
16:46:21
DMO: -16:46:32 L.ogin user
16:47:22 Login user
16:47:38
L.PO: --

***

1 I.> ~ 4 '7 : 4 ~~ L Cl ',~ ClI, I t

I.J <';; e r

[1,4J
ALPHA
BRAVO

TT~j3:

[7,3:34J TT53:
[7,4;:>] TT13:

dismount complete

DECNET
CHARLIE
t"; C\ t

r ~~ ,~ d ':1

(1.,4] TT53:

16:47:58 L.osout user [7,~!'73] TT:??!
16:4B!Ol I .. osil': user ALPHA
16:49:40 login user DECNET

3.8

[240,240J TT30:
[7,373] TT22:

[7,334] TT53:
[240,240] HTO:

SAMPLE CONSOLE LOGGING TERMINAL SESSION

Following is an annotated example which shows a console logging
terminal session illustrating how you use all the commands described
in the Sections 3.4 through 3.7.
Example 3-1

Sample Console Logging Terminal Session

(This example assumes that LB: is assigned to DBO:.)

>~3ET /CfJL.ClG
C Cl T ---C(jn~::,o:! e
j"!one
I...u::';f::' 'I.e
NCln('~

DE . . ' CO!
COO:

TTO:

>SET

/COI_nG:"~ON

)D[l}

CO!

COO: LOADED
>f.jET

/COL.OG

COT -- ....
Con~:>C) J f:~

~::

TlOOO:

= DBOOO:[[1,4J]CONSOLF.lOG;1
/ CnI" 0 G/ C f) T F R 1'1 ~:: T 1 :'.'i 1 !

Lo~file
:>~) E T

>S[1 /COLOG/LOGFILE=DR:[[301,55JJTFST

o
o
(continued on next page)

3-8

THE CONSOLE LOGGER
l~xample

3-1 (Cont.)

Sample Console Logging Terminal Session

>SET ICOI..OG

COT ---Console =: TTOSt:
::: DROOO:[[301,5SJJTEST.LOG;j

Lo~file

>SET /COLOG/NOCOT

ICCiLOG
COT -- . .
>~)ET

:: None
Losfile = DROOO:[[301,5SJJTEST.LOG;1

Con~'.()l(·

>DI::I.) CO:

COO:: t. OADED

>SE T /COI ... OG/ r: 11 TF R INClLDG

>SET ICDLClG
COT -- . .
CDn~>()l(~ :: TT051:
LO~3file

":: None:

/COI . OG/COTF:J;:r1::::TT 1."?: /LOG:::
>SET ICOLOG
>~3ET

cor -- . .

Cnn~;>ule

:=:

TT017:

Logfile :: DROOO:[[301,5SJJTEST.t.OG;2
>SET /CClI . OG==CiFF
>SET /COLOG

cor --'"

Con<;;(1 J e :;:: None
:::: NClne

L.o~~f:i.l(:?

>DE!) CO:
TTl"?:
>F:EV TT':Sl: C":CD:
>DEI,' CO:

coo:

coo: TT51.:

>SET /COI..OG:"ON/I.OG"=OB1: [[}, 301. J:I
>SET ICOI...OG

COT -"
Console :: TT051:
LD~-:H':i.le :: DBOOl.:[[7,301J]CONSOLF.LOG;:I.
>SFT /COLOG/CClT=TTO:/LDG

>SET !COtDG
COT .......
Con~::.CJ] e

::: TTOOO:

l...oSfile ::: DBOOO:[[1,4J]CONSOLE.t.OG;2
>F'I F' T T : 0:1..8: r.: [1.,4 rl CONSOLF.. LOG
PIP -- Open failure on input fiJe

DBO:[[l,4]lCONSOI..E.I...OG;3 --. ACI.::e~;s~~d for write
>PTP TI: :::I..B: [[ l., 4] ]CONSOL F. LOG/SF::
:1.6:43:1.9 1...()~:.Wl.lt U5€'!T' [[1,41] TT53:
[[/,,334JJ TT~;3:
16:43:35 l...oSin user ALPHA
16:45:07
16:46:21
16:46:32
16:47:22
16:47:38

16:47:49
l.6:4/':~)8

16:48:01
16:4'1:40
>~;FT

I...o~in

user BRAVO

[[/,,4)]]

LoSin
user CHARLIF
IF'O! -- not reBds
l..o~J()ut I..ISf:~T· [ [ j ,4:1::1 TT~:;3:
I...()<.~~out 1..If:;eT' [["7,:'373]] TT22!
l..o~in
user ALPHA
[[/',334]J TT53:
I..u<.:.lin 1..1 <;:,f.n' OFCNET
[[240,240]] HTO:

***

leCiL DG/N(1COTEPM.lNOl. OG

COT -- Not

lo~~ing

on a terminal or to a

>DEl) CD:
COO:

TT13:

*** DMO:user
-- dismount complete
Login
DFCNET
[[240,240]] TT30:

TTO:

3-9

ftl~,

COT

exitin~

THE CONSOLE LOGGER

the current console terminal (none) and log file
o Displays
(none) assignments,
indicating that the Console Logger is
not active.
Illustrates the MCR DEV command that shows how CO:
is
redirected.
CO:
is redirected to TTO:, which means that
the Console Logger is not active and that the terminal
driver redirects co: to TTO:.
Starts console logging.
Shows that the Console Logger is active because CODRV is
loaded.
The display option shows that COT ... redirects co:
to TTO: and that DBO:[1,4]CONSOLE.LOG;1 is the log file.
These are both the defaults when you bootstrap your system.

o
o

Shows how you assign the console terminal to TT51:.
Shows how you assign the log file to DR:[301,55]TEST.LOG.
COT ...
fills in the missing parts of the file specification
with parts from the default file specification.
In this
case, COT ... supplies the file type.
Displays the current console terminal (TT51:) and log file
(DR:[301,55]TEST.LOG;1) assignments resulting from command
lines 5 and 6.
Disables the console terminal and retains the current log
file
(DR:[301,55]TEST.LOG;1).
The display option confirms
this.
Shows that when you disable the console terminal with the
NOCOTERM option, the console logger is still active (CODRV
is loaded), but CO: is not redirected to any terminal.
Illustrates the multiple commands that restore the most
recent console terminal assignment (TT5l:) and disable the
log file.
The display option confirms this.
Illustrates the mUltiple commands that assign the console
terminal to TT17:
and restore the most recent log file.
The display option confirms these assignments. The version
number of the log file is incremented.
Stops console logging. The display option confirms that the
console logger is not active. co: is redirected to TT17:,
which was the last console terminal assignment before
COT ... exited.

Redirects co: to TT5l: with the MCR REDIRECT
confirms this with the MCR DEV command.

command

and

Illustrates mUltiple commands on a command line.
Starts
console logging, retaining the current console terminal
assignment (TT5l:) redirected with the MCR REDIRECT command
in
step
13,
and
opening
a
log
file
DB001:[7,30l]CONSOLE.LOG;1.
The display option confirms
these assignments.
~

Illustrates multiple commands on a command line.
Assigns
the console terminal to TTO: and restores the default log
file. The display option confirms these assignments.
The
version number of the log file is incremented.

3-10

THE CONSOLE LaaGER

3.9

Illustrates what happens when you try to read
file without the Shared Read switch (/SR).

Shows how to read an open log file using the Shared Read
switch.
Each message in the log file begins with a time
s1tamp.

Disables the
console
terminal
and
the
log
file.
COT ••. exits because no console logging is in progress.
COT .•. displays a message informing you that it is exiting.
~~e
MCR DEV command shows that co: is redirected to TTO:,
the console terminal assignment before COT ... exited.

open

log

ERROR MESSAGES

COT -- LUN assignment to console terminal failed
Explanation: You specified an incorrect terminal number
console terminal.

the

User Action: Use the COTERM option to assign the
terminal to a terminal in your hardware configuration.

console

COT -- Illegal console terminal
Explanation: You tried to assign a device that is off line or is
not a 1:erminal to CO:.
OnR$X-1IM... PI..US systems, the device may be illegal because it
a.spooledtemninal.

User Action: Use the COTERM option to assign a terminal in
hardware configuration to CO:

your

COT -- Console driver not loaded, COT exiting
Explancition:

The console driver, CODRV, is not loaded.

User Action:

Load the console driver and start console logging.

COT -- Maximum consecutive write errors, disabling logfile
ExplanCltion: An error occurred on five
consecutive
write
operations to the log file.
COT ..• closes the log file and
disablE~s logging to the log file.
User Ac:tion: Determine the problem that caused the write
and correct it. Then restart COT ...

errors

COT -- Not logging on a terminal or to a file, COT exiting
ExplanCltion: You have disabled the console terminal with
NOCOTERM option and the log file with the NOLOGFILE option.

the

User Action: If you did not intend to stop console logging,
start it again specifying either a log file, console terminal, or
both.

3-11

THE CONSOLE LOGGER
COT -- Unable to redirect CO:

to a terminal - CO:

is offline, COT exiting

Explanation: CO: is off line. There is a problem with the most
recent console terminal assignment. It may be off line or not a
terminal.
On RSX-llM-PLtJS systems;
terminal was assigned.

,the

problem

may

t.ha<t

User Action: Start COT ... and specify a legal console
with the COTERM option. Then, stop console logging.

spooled
terminal

COT -- Syntax error
Explanation:
command.

You made an error in

entering

console

User Action: Check the command description in Section
enter the command correctly.

logging
3.4,

and

COT -- Will attempt console LUN assignment to TTnn:
Explanation: This error message may occur when you stop console
logging.
If COT ... cannot redirect the console terminal to the
terminal currently assigned as the console terminal, it tries to
redirect CO:
to the previous console terminal assignment. If
that fails, it tries TTO:. If that fails, it generates the error
message:
SCOT -- LUN assignment to console terminal failed
User Action: Start console logging again, specifying
console terminal. Then stop console logging.

legal

COT -- Illegal command - Console logging has not been turned on
Explanation: You issued
starting console logging.
User Action:

console

logging

command

before

Start console logging and issue the command.

COT -- Logfile x error
filespec -- QIO Error Code -nn.
Explanation: An I/O error occurred while COT ... was performing
an operation on the log file. The function being performed, x,
is WRITE, OPEN, or CLOSE. The filespec is any legal filespec
designated for the log file. The error code, -nn., is an I/O
error code.
User Action: Look up the I/O Error Code in the RSX-IIM/M-PLUS
and Micro/RSX I/O Operations Reference Manual and take the
appropriate action.

3-12

CHAPTER 4
THE I/O EXERCISER (lOX)

The I/O Exerciser (lOX) detects and diagnoses I/O problems on the
disk,
terminal, and tape units in your hardware configuration. Using
the IOX Command Language, you can execute, control, and monitor I/O
exercises on device units that you specify for exercising.
This chapter has a narrative part and a reference part. The narrative
part presents the information you need to run the I/O Exerciser in the
order you need that information. The reference part describes each
command in the lOX Command Language.

4.1

INTRODUCTION

This section serves the following functions:
•

Provides an overview of the steps· involved in running
exercise

I/O

•

Describes how the I/O Exerciser exercises different
devices

types

•

Distinguishes between file-structured and
volumes

•

Categorizes the lOX commands by function

4.1.1

non-file-structured

Running an I/O Exercise

BeforE! you run an I/O exercise, you need to consider the following:
•

Kinds of devices to exercise
disks, terminals, and DECtapes)

(magnetic

tapes,

cassettes,

•

Kind of exercises to run for each device (lOX has three
of exercises)

•

Exercise parameters to set for each exercise (such as whether
or not to test random blocks on disks, how many records to
test on magnetic tapes, and how long to run the exercise)

kinds

The st:eps involved in running an I/O exercise include your making
decisions about these three aspects of testing. Using the lOX Command
Language, you implement these decisions and run an exercise.

4-1

THE I/O EXERCISER (lOX)
To run an I/O exercise, you must take the following basic steps:
1.

Invoke lOX.

Determine which devices you want to test and include them
your "test configuration.

Determine the kind of exercise to run on each
test configuration.

Set exercise parameters to affect how lOX tests the units you
want to exercise.

Begin the exercise and possibly
change steps 2, 3, and 4.

interrupt

Monitor the activity and error
during an exercise.

reports

Exit lOX or repeat this process beginning at step 2, 3, 4, or
5, as appropriate.

4.1.2

unit

the

that

exercise
lOX

your

generates

How lOX Exercises Different Types of Devices

lOX performs exercising on disks,
magnetic
tapes,
cassettes,
terminals, and DECtapes.
You can use lOX to perform an exercise
operation on any mounted volume disk, magnetic tape unit, or terminal
in your hardware configuration that has not been allocated to another
user.
By default, lOX can ~xercise 28 units simultaneously. You can
edit the task build command file (see Section 4.ll) to enable lOX to
test as many as 250 units simultaneously.
In general, I/O exercises consist of four steps:
1.

Writing bytes of data (made up of a specific data pattern) to
a mounted volume

Reading the data just written

Checking that the data read matches the data written

Reporting mismatches of data

lOX repeats this process until the exercise has completed.

4.1.2.1 How lOX Exercises Disks - lOX writes a buffer of data to a
disk and then reads that data from the disk. You can also set
exercise parameters that determine the following:
•

The data pattern to be written

•

The range of blocks to be tested

•

Whether to test blocks sequentially or randomly

4.1.2.2 How lOX Exercises Magnetic Tapes and Cassettes - lOX uses the
same algorithm to exercise magnetic tapes and cassettes. lOX rewinds
the tape, writes one record, space reverses one record, and then reads
the record that was just written. This procedure is repeated until
the number of records that you specified for testing are read. At the
4-2

THE I/O EXERCISER (lOX)
end of the exercise, lOX writes two tape marks and rewinds the tape.
rf you are testing more than one unit, rox continues testing on those
uni ts 'while the tape is rewinding.
You can also set exercise
parameters that determine the fOllowing:
•

The data pattern to be written

•

The size of the data buffer

•

The number of records to be exercised

4.1.2.3 How lOX Exercises Terminals - rox exercises terminals by
continuously writing out a portion of the ASCII character set to a
terminal that is not logged-in.
If LOOPBACK NO (the default) is
specified, this is all that happens.
If LOOPBACK is specified, lOX
will read the characters back after writing them, compare the two sets
of characters, and report on the comparison between the two sets.
(LOOPBACK mode requires that a loopback connector be connected in
place of the terminal to direct the characters written back to lOX.
lOX depends on the presence of a typeahead buffer to store the
characters between writing and reading them. See Section 4.4 for
further information on the LOOPBACK parameter.)

4.1.2.4 How lOX Exercises DECtapes - lOX exercises DECtapes
by
writing forward/reading forward, then writing reverse/reading reverse
until the end of the tape is reached.
lOX exercises DECtapes using a
data buffer of two blocks (1024(decimal) bytes). You can set a test
parameter only to determine the data pattern that lOX writes to the
DECtape.

4.1.2.5 Non-File-Structured and File-Structured Volumes - lOX exercises devices on two kinds of volumes: non-file-structured (NFS) and
file-structured (Files-II). The meanings of these terms may differ
slightly from other manuals within the RSX-IIM/M-PLUS set. In the
context of the I/O Exerciser, they are defined as follows: all tapes
and terminals are NFS volumes.
(Throughout this chapter, the term
"NFS" describes devices and the testing of devices that contain
non-file-structured volumes.) Disks can be either NFS or Files-II
volumes. Files-II volumes are only those disks that have been
initialized with the MCR INITIALIZE command and therefore have a home
block and a Files-II structure.

4.1.3

The Four Categories of rox Commands

The rox Command Language has four categories of commands:
1.

Function Commands - Select devices for testing, deselect
devices from testing, and initiate tasks to run in parallel
with rox.

Control Commands - Start and stop lOX processing, switch lOX
modes of operation, and exit from rox to the operating system
monitor.

Display Commands - Display current default parameters, get
help text for lOX commands, and display status and activity
reports during an r/o exercise.

4-3

THE I/O EXERCISER (lOX)
4.

Parameter Commands - Set default parameters that
lOX tests the devices you select for testing.

affect

how

Table 4-1 lists the lOX commands under their appropriate categories.
Table 4-1
Four Categories of lOX Commands
Function

Control

Display

Parameter

DESELECT
EXECUTE
FILESII
SELECT
VERIFY

ABORT
CTRL/C
EXIT
PROCEED
RESTART
START

BADBLOCKSI
CONFIGURE 1
DENSITY 1
HELP
PARAMETERLIST
PATTERN 1
PRINTSUMMARY
RANGEl
Spy

BADBLOCKSI
BUFFERSIZE
COMPAREDATA
CONFIGURE 1
CONTROL C
DENSITy-l
ERRORLIMIT
INTERLEAVE
LOGFILE
LOOPBACK
PATTERN 1
RANDOM
RANGEl
RECORDS
REPORTERRORS
RETRIES
RUNTIME
SUMMARYTIME
TEMPORARYFILE
VOLUMECHECK
WAIT
WRITECHECK

1. These commands have two forms: one that displays the
current default for the parameter and one that sets the
current default for the parameter.

4.2

INSTALLING AND INVOKING lOX

lOX is task built as a nonprivileged, checkpointable task that runs at
a priority of 50 in the GEN partition. You can run lOX by entering
the RUN command from either MCR or DCL or by installing and invoking
lOX.

4.2.1

Installing lOX

Install lOX from a privileged terminal with the
command.

MCR

DCL

INSTALL

For RSX-IlM systems that do not support the Extend Task Directive (see
the RSX-IIM/M-PLUS ~ Micro/RSX Executive Reference Manual), install
lOX with an increment large enough to accommodate all buffers.
Assuming all initial lOX defaults, allocate 600(decimal) words per
unit to be tested simultaneously. For example, to test three devices
simultaneously, install lOX as follows:

)INS $IOX/INC=1800.

4-4

THE I/O EXERCISER (lOX)
For RSX-IlM systems that support the Extend
lOX without an increment.
.

4.2.2

Task

Directive,

install

Invoking lOX

You can invoke lOX from any terminal.
On RSX-IIM single user systems, mount all disks that you want to
exercise as file-structured disks. If you have a multiuser system,
first allocate all units that you want to exercise. Then mount only
those disks that you want to exercise as file-structured disks.
On RSX-IIM-PLUS systems, allocate and mount all units that you want to
exercise. Mount non-file-structured volumes using the /FOREIGN switch
for the MOUNT corrunand.

4.2.2.1 Invoking an Installed Version of lOX - If lOX
invoke it with the following corrunand:

installed,

>IOX
lOX>
lOX responds by prompting you with the name of the task that you
assigned to lOX when you installed it.
If you did not specify a task
name when you installed lOX, its task name is ... 10X. After receiving
the prompt, you can enter lOX corrunands.

4.2.2.2 Invoking lOX When It Is Not Installed - If lOX is not
installed,
invoke it by entering the RUN corrunand from either MCR or
DCL.
In this case, lOX uses your terminal number to name the task and
prompts you using this task name. For example, if from TTIO: you
type the following:
>F~UN

$IOX

When you receive the following prompt, you can enter lOX commands:

T'flO>
For RSX-llM systems, if your system does not support the Extend Task
Directive, then run the I/O Exerciser with an increment large enough
to acc·ommodate all buffers.
Assuming all initial lOX defaults,
allocate 600 (decimal) words per device to be tested simultaneously_
For example, to test four devices simultaneously, invoke lOX as
follows:
)RUN $IOX/INC=2400.
When you invoke an uninstalled version of lOX on RSX-lIM systems that
support the Extend Task Directive, you do not need to run the task
with an increment.
When you invoke an uninstalled version of lOX on RSX-IIM-PLUS systems,
you do not need to run.the task with an' increment.

4-5

THE I/O EXERCISER (lOX)
4.3

USING INDIRECT COMMAND FILES WITH lOX

You can use indirect command files as input to lOX.
lOX accepts one
level of indirect command files.
You can use indirect command files
to set up your test configuration, choose devices for testing,
set
exercise parameters, and start and exit the exercise. You cannot
interrupt an I/O exercise to enter lOX commands from an indirect
command file.
The default file type is "CMD."
For example, use an editor to create a file
contains the following lOX command sequence:

named

TEST.CMD

that

CONFIGURE DB2:

Adds DB2: to the test configuration

FILESII DB2:

Chooses DB2: for an exercise that preserves
the contents and structure of the disk

RUNTIME 10

Sets an exercise parameter that runs
for 10 minutes

START

Starts the exercise

EXIT

Exits from lOX to the operating system
monitor when the exercise completes

After you invoke lOX, type the following:

lOX exercises DB2:
(preserving its contents and structure)
minutes and then exits to the operating system monitor.

4.4

for

SETTING UP A TEST CONFIGURATION

Before you can exercise a unit, you must first include it in your test
configuration.
When you include a unit in your test configuration,
lOX adds the unit to its list of units available for exercising and
creates an empty data structure for the unit. lOX includes in the
default test configuration one of each device type supported by
DIGITAL as unit "0".
To add units to the test configuration, you use the CONFIGURE command.
The syntax for this command is as follows:
CONFIGURE [ddnn:[=type]] ....
where:
dd

The device mnemonic

The device number

type

The device type, either DISK, TERM, or TAPE

You can add any unit to the test configuration and assign
device name to it by using the MCR ASN (ASSIGN) command.

4-6

logical

THE I/O EXERCISER (lOX)
The CONFIGURE command with no
configuration. For example:

arguments

displays

the

current

test

IC!X>CClNFIGURE
Djoo~oks:

fit 0

OBO

Dl"!O

DFO

fll<O

DXO

DYO

FMO

SYO

MF 0

MMOM S ()

DMO

DPO

I"IF:O

[ISO

nuo

Tapf::'~:' :

CT ()

fIT 0

MTOM 1.I 0

T f:~ r R. i. r. a 1. ~i :
lTO

To add OKl:

and MMl:

IOX~CONFIGURf

to your configuration, type tOAle following:

DK1:

MM1:

This command line adds OKl: to the configuration as a disk unit
(because OKO:
is already configured as a disk) and MMl: to the
configuration as a tape unit (because MMO: is already configured as a
magnetic tape).
Section 4.12 describes the CONFIGURE command in
detail.
To add TT12:

to your configuration, type:

ID'xo:>CONFIGUr:F:: TTl2!

This command line adds TT12: to the configuration as a terminal unit
(because TTO:
is already configured as a terminal.) If you want to
exercise your terminal using LOOPBACK mode, the following terminal
characteristics must be set BEFORE installing the LOOPBACK connector:
SLAVE, PASSTHRU, NOECHO, LOWERCASE, and NOWRAP. The line must also be
logged out.
For Loopback mode, lOX relies on the typeahead buffer to store the
characters it writes before reading them. For this reason, lOX limits
the number of characters it writes to the size of the typeahead
buffer, and does not operate if typeahead is disabled.

4.5

SELECTING DEVICES FOR EXERCISING

After configuring all the units you want to exercise, you select units
for exercising.
When you select a unit, lOX fills in the data
structure created when you configured the unit. This data structure
contains all the information lOX needs to exercise the specified unit.
You select units for exercising with the FILESll, SELECT, and VERIFY
commands.
These commands require device and unit specifications
within their command lines.

4.5.1

The FILESll Command

The FILESll command selects a disk unit with a mounted Files-II volume
for an I/O exercise.
Exercising with FILESll does not affect the
contents of the disk being tested.

4-7

THE I/O EXERCISER (lOX)
4.5.2

The SELECT Command

The SELECT command selects a unit with an NFS volume for an I/O
exercise.
Invoking the exercising function by using the SELECT
The
command will destroy the contents of the volume being exercised.
SELECT command is also used to select a terminal for exercising.

4.5.3

The VERIFY Command

VERIFY command selects a disk unit with a mounted NFS volume for
an I/O exercise. VERIFY does not write on the volume being exercised.
Exercising with VERIFY does not affect the contents of the volume
being exercised because VERIFY only reads from the volume.
~rhe

4.6

EXERCISE PARAMETERS

You set parameters that determine how lOX exercises units.
These
exercise parameters determine aspects of testing such as how long an
exercise is to run, how many records are tested on magnetic tapes,
what range of blocks are tested on disks, and whether output is
directed to your terminal or to a log file. There are two kinds of
exercise parameters: general and device dependent.

4.6.1

General Exercise Parameters

The following commands set general exercise parameters and, therefore,
affect all lOX testing:
CONFIGURE
CONTROL C
LOGFILEPATTERN
REPORTERRORS
RUNTIME
SUMMARYTIME

4.6.2

Device-Dependent Exercise Parameters

You use the commands listed in this section to set default parameters
for the units that you select for exercising. You can include these
commands within the FILESll, SELECT, and VERIFY command lines to
override the default parameter for the specified unit.

4.6.2.1 Parameter Commands for Files-II Disks with FILESII - The
following commands affect the exercising of disks that you select with
the FILESll command:
COMPARE DATA
ERRORLIMIT
INTERLEAVE
RANDOM
TEMPORARYFILE

4-8

THE I/O EXERCISER (lOX)
You can use these commands to set the default parameters before you
use the FILESll command to select a unit. You can also use these
commands within the FILESll command line to override the default
paramet:ers for the unit being selected.

4.6.2.2 Parameter Commands for NFS Volumes or Terminals with SELECT The following commands affect the exercl.sl.ng of NFS volumes or
terminals that you select with the SELECT command:
Bl~DBLOCKS

BUFFERSIZE
COMPARE DATA
DENSITY
ERRORLIMIT
INTERLEAVE
LOOPBACK

RANDOM
RANGE
RECORDS
RETRIES
VOLUME CHECK
WRITECHECK

You USE~ these commands in conjunction with the SELECT command to set
defau11: parameters for exercising a terminal or a unit with an NFS
volume" You can use all but BADBLOCKS within the SELECT command line
to override the current default settings for the device being
selectE~d .
Table 4-2 lists the
devices.

parameters

for

exercising

different

types

Table 4-2
Parameter Commands by Device Type for SELECT
NFS Disks

Cassettes

DECtapes

Magnetic
Tapes

BADBLOCKSI

BUFFERSIZE
COM PARE DATA
ERRORLIMIT
RECORDS

COMPAREDATA
ERRORLIMIT

BUFFERSIZE
ERRORLIMIT
DENSITY
RECORDS
RETRIES

BUFF]~RSIZE

COMP1\REDATA
ERROltLIMIT
INTERLEAVE
RANDOM
RANGg
RETRIES
VOLUlo1ECHECK
WRI T]~CHECK

Terminals

BUFFERSIZE
COMPA~EDATA

ERRORLIMIT
LOOP BACK

1. Ca.nnot be used within SELECT command line.

4.6.2.:3 Parameter
Commands
for
NFS Volumes with VERIFY - The
following commands affect the exercising of NFS disks that you select
with the VERIFY command:
BJ\DBLOCKS
BUFFERSIZE
ERRORLIMIT
INTERLEAVE
RJ!WDOM
RJ!\NGE
Rl~TRIES

4-9

THE I/O EXERCISER (lOX)
You use these commands with the VERIFY command to set default
parameters for testing a unit with an NFS disk.
You can use all but
BADBLOCKS within the VERIFY command line.

4.7

SETTING PARAMETERS FOR EXERCISING FILES-II VOLUMES

This section shows you how to use lOX to exercise an RL02 with
Files-II structure. Example 4-1 uses the following lOX commands:

PARAMETERLIST
Displays current default parameters, lOX buffer space statistics,
and device-dependent parameters for devices you have selected for
testing.
RUNTIME
Sets the length of time
(in minutes)
unit(s} you have selected for testing.

that

lOX

exercises

the

FILESll
Selects a disk with a mounted Files-II volume for an I/O exercise
that preserves the contents and structure of the disk.
TEMPORARYFILE
Sets the size of the temporary file that
Files-II disks with the FILESll command.

lOX

uses

for

testing

START
Starts exercising units that you have selected for testing.
Example 4-1

n L I.

Exercising an RL02 with the FILESll Command

DL \) ~

:> !'1 n1.: :u 1.J) ~

I .• C I.J ~. L

';. I Cl :~.

I !jx>PI~r'tlhFTFPI. J f,.T

BUFFERSI!E= 1024.

COMPAHFDATA=

I:: I~: r·: DF: I... I MIl ;;:; 1. () •
i N T F F: L. F f~II.1 E :c;: 4 +
i:' I~i T T F I~: N:o o.
!~ E COP D S C~:
1. 0 :) 4 •
r;: 1...1 NT 111 F ;;" 5.
'3 Ut·, MAHYT I /Vi E :;;: 1.

YFS

CnNTROL .. C":: y[~)
LOGF:r I. F:::: Nfi
LOOPBAC:I';;;::; NO
~~:r~INnnM::::

YFS

RFPORTFRRORS= YES
F:FTF(JES:::: YF~;
I) OI .. 1...1MF r:: HF r: l{ :::: YEn

(..triJl;;;· YFS
WF: I TFCHFCI{:::: NO

:I. [I X"> Ui\~ l I ~'j F ::~
J DX::: F I I . r-:: ~J 1. 1. ni . O!
OX:> r' (~ PAM F l F f::

l E 1'1 F ::: 8 0 0

(continued on next page)

4-10

THE I/O EXERCISER (lOX)

Example 4-1 (Cont.)
Dev i CE~

Mode

DL.O:

F1l

BlJffer~;L~E'

Exercising an RL02 with the FILESll Command

Filesize/Records/Rangp

~512 •

Gl)

800 +

BUFFFRSIlF~

1024.

f~f)MPAREDATA::::

EF~F~DF;:LJ"'iIT::~

to.

CONTF~OL _.. C:::

IN·rF.F~I.EA\jE·:::

LOGFTI..[;::: NO
I..OOPF:ACr:.:::: NO

P(:lTTEPN·:::

P8r8meters

}

-----------

COM

RFT

RAN

ERR~lO,

YES
YFS

1~:ECi)RDS"~

1. 024.
I:,I.JNTIME:::: 3 ~
SU~'iMM';:YTIME:::: 1.

1~I~Nnnt1:~: YES
F: FP () P TFf;:ROF:B::: Y F S

TEMPOR~RYFJLE=SOO.

'vIOL Ul"FCHFCK::~ 'YFS

I:::FTF:H::S:::: YES

Wi-iTT:::: YEB
lAlf;: :r T F r. H F C1< :::: N n

1 () X >3 T (:, F: T

The command sequence in Example 4-1 does the following:

Allocates drive DLO:.

Mounts the disk with label "LOUIE

Invokes an installed version of lOX with default task
•.. lOX.

Displays the initial default parameters with PARAMETERLIST.

Changes the default RUNTIME to 3 minutes.

Selects DLO: for FILESll testing with a temporary file size
of 800 blocks.

Note the difference between
PARAMETERLIST command before
selected DLO:.

in DLO:.

defaults
the
and after you

displayed
by
changed RUNTIME

Only the RUNTIME default has changed.

The default for TEMPORARYFILE has not changed.

name,

the
and

After you selected DLO:
for testing, PARAMETERLIST contains
an
extra
line
at
the beginning that displays all
device-dependent parameters' for the selected device.
Each
selected device has its own display line. There are five
fields of parameters.

«D

Field four shows that the temporary file size used for
FILESll testing for DLO: is 800(decimal) blocks instead of
the 500(decimal) block initial default.
During FILESll
testing, this field refers only to temporary file size.
The START command begins FILESll testing on DLO:
for a
RUNTIME of 3 minutes and uses a temporary file size of
800(decimal} blocks.

4-11

THE I/O EXERCISER (lOX)
4.8

SETTING PARAMETERS FOR EXERCISING NFS VOLUMES

This section shows examples for the command sequences that test a
magnetic tape volume using the SELECT command and an NFS disk using
the VERIFY command. Both examples are explained in detail.

4.8.1

Exercising a Magnetic Tape with the SELECT Command

The command sequence in Example 4-2 tests a magnetic tape by using a
buffer of 8K bytes (which contains the data pattern 052652) to
transfer data.
Example 4-2 illustrates the following commands:
PARAMETERLIST
Displays current default parameters, lOX buffer space statistics,
and device-dependent parameters for devices you have selected for
testing.
PATTERN
Sets the pattern that lOX writes and reads during an exercise.
BUFFERSIZE
Sets the amount of data that lOX transfers for every read or
write request when testing NFS disks, magnetic tapes, and
cassettes.
DENSITY
Sets the density and characteristic word of the specified
magnetic tape or displays the current density and characteristic
word for the specified magnetic tape unit.
SELECT
Selects a unit with a mounted NFS scratch volume
exercise that destroys the contents of the volume

for

I/O

RETRIES
Determines (for magnetic tapes and NFS disks) whether an I/O
driver repeats an I/O operation after the driver receives errors
during the operation.
ERRORLIMIT
Sets the maximum number of errors that lOX tolerates
interval reports before terminating testing on a device.

between

RECORDS
Specifies the number of records to be exercised on magnetic tapes
and cassettes.
START
Starts exercising units that you have selected for testing.

4-12

THE I/O EXERCISER (lOX)
EXIT
Terminates lOX processing and'exits from lOX.
Example 4-2

Exercising a Magnetic Tape with the SELECT Command

>ALL Mi"10!
)i"IOtl MI"iO!

>IOX
IOX)PARAMFTERlIST
BUFFERSI7F~

t024.

LF;:F-:OF~L.Jt·1JT:::;

j O.

c n11 P A F: i=:~ nAT A :~: YES
CONTROl. .... C:::: YFS
1.. nr·iF II .. Fe:: NO
lOOPB(.lCK::: NO

Ii'll FRl..EAl,.iF:::: 4.
0+
I~FCOI;:n 8::;: :I. ()24.
F'!...INTIi"iF::: ~:i+
P(~TTFRi'-l':::

RANDnt1::" YES
RFPORTFRRORS= YES
~:FTF:IFS::-~ YES
I...)Ol UMFCHFCK::: YFS
vJ (o~ I T :~ YF '::l
ltIF.:1 TFCHFCK::' NO

Bl.JriMAF:YTH~F:.:

TEMPORARYFJLE= 500.

B 1..1 f' 'f j..:, T'

,:, ,., a C II

I.i <~ -'3 .,,~ I;~ .::

:-;; ~:J <.T'

O. : 1. <;:0 :~: 4 + : l 9 ~:~ -4 • : 1 •

Iox>pr,TTFF;:N 1.:?
IOX>nUFFFF: 01.92
I OX >0 F :i'l f:~ 1'111 () !

r".~.-I.1
r"l ,"> Y' ;:> I" +. ... Y' <::••,.~.• j ("
1.1.-)
n),..() 4 (1)...() 4 ('J
.... J.-r ~ ,....~ 1)
}
Dp n ~;j. :i. t t·I::· :1. ,I:, ;) 0 'R I:' T.
w. T' rl::;:
..
I. ,'_.
.• ~
IDX)SFI.. FCT i'1MG: ~ RFTHTEf.~::::Nn nFt··.!f~JTY:::·B()O FF-:ROF<"::j 00 f;:FC:::;JOOOO
I nX:> p f.\ :~: I~I f';
.,.

.. ,

'.'

'1'
.•

•

Device

Mode

Buffersize

Fi]esize/RecQrd5/R~n~e

hMO:

NFS

B192.

~~oooo

BUFFFF:SI?F:·,·:

fit <'12.

Parampters
COM FRF:=10. Cli)

COriF'f:IF:FDAT,;:::: YFS

:to.
I I) I::: I~ I... E (':II) r-: :;:: 4 ~

Fr~f;:OF;:LJMIT::::

CiJl···ITF~n!.

... c;:;; YFS

nf3 F :r. I.. E,,: N [)
I. nnF' P. A C i< ::: N 0
!.

P tl T T F F: N::: 1. ::.! •
RECORtS= 1024.
RUNTIME= 5.
S UM,'1tIF:Y T:r MF·;:: l..
TEMPORARYFILE~

•

A
.:I'

RANnnM~ YES
REPORTFRRORS= YFS
h F: r I~ 1: ~:S;::: YES

500.

VOLUMFCHFCK= YFS
l,JA I T;::

YE~::l

t~Fi~ITFCHFCI<:;::

lOX.> Ii F ~l E IT '( "j I'~ 0 ~
Densjt~~

J D >' ::. ~:) T '~I F: T
:I ~j).
h j'''\ 0:

800 BPi

Ch3racteristic Word= 000000 (octal)

Ci)
to a d h 'I. C' c k,

1 1:; (d e c i III a 1)

J!, 0

.: 0 C' t a J ;.

I (] X
S I.' I'll IY: d Y' '.:~ D f (::! ::.: ~:.> r c :i. <:; e I' ;;~ (: t i v 'i. t '..I ~~ t ;~ (; .- ..1 I.J L - 8 5 l 6 : ~:) 0 : 4 0
T I 1-1 F -- - P I..i \",: :I. 1\1 :i. n •
F J a f" s I-':! d; J It! .i. n •
F: P ITI a i n :i n :::t: 4 ITI:i n •
~'i M0: -- -- :;-, 10 ~ R / W r :.~ (~ 1.1 i:~ ':; t·; t () 'I.., ;;1 1. 'i. n <~~ ~ :~ O.
T' I"! ,:~ () T' ('\'-5 W i. t. h 1. \,:1 T' ,.. q T' ~;;
~STiS

executed:

I d 'I. P -- :I. j) c, ,.'

~46.

t. (:~ T' i::! t. i (J n s t :) -4 4 •

(continued on next page)

4-13

THE I/O EXERCISER (lOX)
Example 4-2 (Cont.)
lOX
lOX

Exercising a Magnetic Tape with the SELECT Command

MMO: bad block, 486 (decim3l) 746 (octal)
MMO: b~d block, 551 (rlecim~l) 1047 (oct~l)

S 1..!lTIITI a r ~ () f f? :.~ E' f' C' :i ~:; e r' act i v i t. ~ a t ~1 0 -- J UI.. - 8 5 1 f:, : 5 4 : 5 0
Tlt-'iF --- R1.ln: 1 111in.
F.:laps~~d:::; min.
F:t::~ITI~i.nin<:.I: Ol1li.n.
MM0: ... - ? 1 7. R / W T' e CH.I e sl-:; t. ('\ t. a l:i. n ~~ ~) 1 i'. r Po rOT' d s w:i t h 2 p r· r () r s

I 0 )(

I d 1 f:1 .- J Cl Cl p :i. -t, ~:. rat :i () II~':
C r.: '.! r~ II I... ATE:O

~~ 2:1. •

r T t'l F - _..

F\' un:

E 1. a F' '::. ~~ d:

MHO:

1,121. R/W reQuests

f.·~:-~f.·:·CI.lt.f~rl:

,:,)ST! <:;

Idle-loop

fli 'i. n •

T D T (.\ L S :
:5

ITI :i. n •

tota]in~

R~matn'i.n~:

:t, 121.

T'E'CClf'(b

0 min.
w:i th 3 e T' T'Of'S

1, tS8b.

il~ratlons:

1,670.

I OX>FX I T

The command sequence in Example 4-2 does the following:

tt Allocates drive MMO:, mounts the magnetic tape, and

invokes

an installed version of lOX.

On RSXllM;"';PLUS systems, you mount the tape with the /FOREIGN
switch.
~

Displays the initial defaults.

Selects pattern number 12 to be written to the tape.

Changes the default
8l92(decimal) (8K).

1024(decimal)

Displays the default density and characteristic word on
magnetic tape mounted in drive MMO:.

the

BUFFERSIZE

from

G» Selects MMO:

for NFS testing with SELECT, overriding the
defaults for RETRIES, ERRORLIMIT and RECORDS, and sets the
tape density at 800(decimal).

Checks the parameters with PARAMETERLIST and DENSITY.

Changes the BUFFERSIZE default.

Changes the PATTERN default.

Displays the device display line for MMO:.

Shows the current BUFFERSIZE of MMO:.

Shows that the number or records to be tested is 20000.

Starts NFS testing with SELECT on MMO:.

The remainder of Example 4-2 shows interval reports,
error reports,
and
accumulated totals generated at your terminal during this
exercise. These reports are discussed fully in Section 4.10.
When
the exercise has finished, you exit to the operating system monitor
unless you want to do more testing.

4-14

THE I/O EXERCISER (lOX)
4.8.2

Exercising with the VERIFY Command

The command sequence in Example 4-3 performs oscillating seeks between
blocks 1 and 1000 to align disk heads.
It reads only 4 bytes per data
transfer, which is the minimum. No error or summary reporting is
required. The exercise runs until you abort it.
Example 4-3 illustrates the following commands:
PARAMETERLIST
Displays current default parameters, lOX buffer space statistics,
and device-dependent parameters for devices you have selected for
testing.
VERIFY
Selects a mounted disk for an NFS exercise that reads buffers of
data without writing on the disk, performing data comparisons, or
destroying the contents of the disk.
RANGE
Slets the minimum and maximum block numbers for NFS testing on the
specified disk.
BUFFERSIZE
Sets the amount of data that lOX transfers for every read or
write request when testing NFS disks, magnetic tapes,
and
cassettes.
RANDOM
Directs lOX to select either random or sequential blocks for disk
tl~sting .
INTERL]~AVE

Sets the number of blocks to be skipped before lOX writes the
next buffer of data for disk testing (applies only to sequential
tE~sting which you determine with the RANDOM command).
ERRORLIMIT
SE~ts the maximum number of
errors that lOX tolerates
interval reports before terminating testing on a device.

between

REPORTgRRORS
Enables or disables error reports.
SUMMARYTIME
Determines how
rE~ports .

often

(in

minutes)

lOX

will

output

interval

RUNTIME:
SE!tS the length of time {in minutes}
unites} you have selected for testing.

4-15

that

lOX

exercises

the

THE I/O EXERCISER (lOX)
LOGFILE
Determines whether lOX directs activity and error reports to your
terminal or to a log file.
START
Starts exercising units that you have selected for testing.
CTRL/C
With CONTROL C enabled, allows you to enter lOX commands while an
exercise is in progress.
ABORT
Terminates execution of an I/O exercise.
Example 4-3

>,"'LI.

>i'1DU

DMO:
DMO:

Exercising an NFS RK07 with the VERIFY Command
}

>IOX
IOX>PAR
BUFFERSIIF= 1024.
[f~ R 0 R LIM IT::: 1. 0 •
INTERLEAVE.::: 4.
F't-\TTERN= O.

r:Ot'lP?lRFDATA"" YES
CONTt,:OI. .... C:::: YFS
I..flGF II..F::::

LOOPBACK::: NO
F:ANDOM=: YES
REPORTFRRORS= YES
RFTr-':IFS:=: YES
'JOLUMECHE'CK= YFS

1024.
5.
S l.J MMAr-': YT I 11 E ;::; 1.
I~ECORDS~-::

I~IJNTIME::::

TEMPORARYFILE:::: 500.

WAIT;;; YES
WF;: I TECHECK= NO
Buffer

<:;pace

1.J'~.;ac!e:::;

~3~~r;O.:l924.:1924.:1.

lOX:> V E F: J F Y DM0: F: A NGF ;.;: :I. : :I 000 B U F ::= 4 t\ A Nft = N I NT F R ;::; 9 9 9 ERR::: 50000 . .
IOX>RFPORTERRORS NO
I I]X>SIJMM(.lf~Y 0
I Cl X:> Rl.J Nl I 11 F (,

IOX>LOCl Y
lOX> F'Ah:

Device

Mode

[tMO:

VFY

Buffersize

1..

BUFFERSI1F= 1024.
INTF.:RI...EAVE,;;; 4.
PATTERN::: O.
r-':ECOfmS= 1.024.

RFPf)RTERI~ORS;::;

TEMPORARYFILF= 500.

space

'Jsa~e::::

3290.:191?:19l2.:1.

IOX:>ST
IOX>'~C

:r: OX>ABOfn

} 0

4-16

Parameters
RFT

VOLUMFCHE'CK::: YES
WAIT::-" YES
WFU TECHF'CK= NO

!3LJMMARYTIME'::: O.

Buffer

--> 1.,000.
COMPARFDATA~ YES
CONTROI.._.C:=: YES
I..OGFILE::= YES
LOOPBACI,:::: NO
RANDOM= YES

ERRORLIMIT:=: 10.

I~:UNTIME=:

Fi]esize/Rpcords/Ran~e

INT=999.

ERR:::50000.

THE I/O EXERCISER (lOX)

The comma.nd sequence in Example 4-3 does the following:

t»

Allocates drive DMO:, mounts the RK07 for NFS
invokes lOX.

testing,

On RSXllM-PLUS
switch.

with

the

/FOREIGN

testing

with

VERIFY,

systems,

mount

disks

Displays the initial default parameter.

Selects DMO:
for read-only NFS
overriding the following defaults:

and

RANGE -- blocks 1 through 1000

BUFFERSIZE -- minimum, four bytes

RANDOM block testing turned off and INTERLEAVE
999 so that lOX tests only blocks 1 and 1000

ERRORLIMIT set impossibly high (50000.) so that lOX will
not deselect DMO:
no matter how many errors are
encountered during the exercise

set

Turns off REPORTERRORS so that no error reports
are
generated.
Turns SUMMARYTIME off so that no interval
reports will be generated. Sets RUNTIME to zero so that lOX
runs the exercise until you abort it. Sets LOGFILE YES to
direct all output to the log file, IOX.LOG, instead of to
the terminal.

Shows that the RUNTIME, SUMMARYTIME, and LOGFILE defaults
have been reset and that DMO: is being tested with VERIFY,
using a buffersize of 4., over a range of 1000.
blocks,
with RETRIES enabled, INTERLEAVE set at 999, and ERRORLIMIT
set at 50000.

Shows how to start the exercise using the START command and
enter Interactive Mode with CTRL/C so you can enter the
ABORT command to abort the exercise.

Example 4-4 shows the contents of the log file for Example 4-3.
Example 4-4
lOX -- 20-JUL-85 18:24:12

Dtl0 :

4 ;.

BLlFFFF:f.n7F:c" :1.074.
[: I~~ l;~ f) r.;: I... I M T T ::: 1 C, ,.
IN"I"Fr;;LFt-. '.)"-::::: 4 >
PATTEI;:N.;;: o.
l:;:ECDRDS:~:
.1.0:>4.
/;:UNT I ME:": o.
BUM~'Ar\YTH1[::::

TEMF'OR("\F~YF1:I .. F::::

~~;OO;.

Log File Output for Example 4-3

******** EXFRCrSFR STARTFD ********
1..... > lrOOO.

RET INT=999. FRR=50000.

C() MF' I~l F: F nt-. T A:: Y F S
CONTI~:nl. ... c·:" YES
I... 0 GF T L F :::: '( F S
I.OOPHAr,!,;::" NO
ptINlIOr·1:::: YFS
RFPOr.~TF:RI;:ORS:~: NO
(?FTF;:JrS:::: YFS
\.' nI. U /Vi F CHF CK ::-~ Y E ~:)
~J {I

IT:::: YF S

l4r~TTFr:HFCI<:·::

(continued on next page)

4-17

THE I/O EXERCISER (lOX)
Example 4-4 (Cont.)

Log File Output for Example 4-3

[OX .... -Fl..:'lPsed: :.~ ITlin.
TIMF --_.. 1~:lln: ] Illin.
J;~ (~~ HI ;:j "i. 1"1 i. n . ~:
b ~ ~ :3 :3 Itl i. n •
DMO: -- 3,075. R/W reGuests tota]in~ 3,075. hlncks w:ith no errors
(i E T . c,

t·:·: ;; t·:·, C 1.1 t

1 1'1 .I e' - .I ("I i) F"

(..: Ii:

1 t. (:.. r' d

:'1' () f3 1. ,.

t. :i () I"l <::.:

::,

9 f-: ;:> •

T D T

(.-i

T J h F -... F: 1.l1'I! 0 HI :i. n •
F 'I. ;:,: F" ,:; e d! 3 rfl i n +
F.: t·:·~ rtl ;;,: ·i. t'l 'j. n .: ~: .,,> ~.i ~:i :3 :3 iii :i. n •
:0 r~ 0 : A -- -- ::~, 0"7 (,. f;: ,I I,J r (~ (1 1..1 P ~~:. t. s t . (\ to' d:l in:.:! 3, 0 '7 t . .; h J n C' Ie .,::. w j t h n () e r T' Cl r '"o'
t, B'r .. ';, e ;':. f: c: I I to' !;.~ d: :3, 0 H ::2 .;

I CI X -- --

.~~ (0 .- . J 1J I .. -- ::~ ~)

1. f3 : .::.~ "7 : :?) :I.

***- *:t. :1: *' F :x: F c; 1: '1 F P H F.: TF II *- *** ***
r~:

;+:

(.:1

:.+::

The log file output terminates when you abort the Exerciser. The log
file begins with the time and date that the exercise began and the
current default parameters as displayed by the PARAMETERLIST command.

4.9

lOX OPERATING MODES

lOX operates in three modes:
Command, Execution, and Interactive.
This section discusses the functions of these modes, how you enter and
exit each mode, and what lOX commands are valid in each mode.

4.9.1

Command Mode

lOX is in Command Mode after you have invoked it and have received the
first lOX prompt.
(Section 4.2 discusses lOX prompts.) In Command
Mode, no devices are being exercised, and tasks initiated by the
EXECUTE command are queued but not active (see Section 4.12 for a
complete description of the EXECUTE command.) You usually
set
parameters, select devices for testing, and initiate tasks to be
executed in Command Mode.
When you press the RETURN key, you receive an lOX prompt.
press CTRL/C, you exit to MCR for one command line.

4.9.2

When

you

Execution Mode

When you begin an I/O exercise by entering the START command, lOX
exits Command Mode and enters Execution Mode. Once you have entered
Execution Mode, exercises begin on selected devices, tasks initiated
with the EXECUTE command begin executing, the lOX clock is turned on,
and activity and error reporting begin.
You set the CONTROL C parameter in Command Mode to allow or disallow
you to enter lOX commands while an exercise is in progress. CONTROL C
YES is the initial default setting.

4-18

THE I/O EXERCISER (lOX)
If you have set CONTROL C NO, then CTRL/C in Execution Mode gives
control to MCR and you receive the MCR prompt (» every time you press
the RE~rURN key and "MCR> " every time you press CTRL/C until the
exercise has terminated. With CTRL/C disabled, you cannot interrupt
the eXE~rcise, however, you can terminate it with the MCR ABORT
command.
If you have set CONTROL C YES, lOX does not accept any input from your
terminal except CTRL/C~ If you try to enter anything but CTRL/C, you
receive an error message for each key you press:
lOX --

On]~

Allowed

When you press CTRL/C, you receive the lOX prompt instead of the
prompt and lOX exits Execution Mode and enters Interactive Mode.

4.9.3

MCR

Interactive Mode

You have access to Interactive Mode only if CONTROL C is enabled.
When you press CTRL/C in Execution Mode, lOX exits Execution Mode and
enters Interactive Mode. In Interactive Mode, the RETURN key and
CTRL/C have the same functions that they have in Command Mode.
In Interactive Mode, the exercise and tasks initiated by the EXECUTE
command are running. Activity reports and error/reports directed to
your tE~rminal are suspended if you have set LOGFILE=NO. I f you have
set LOGFILE=YES, activity and error reports continue as in Execution
Mode.
All lOX commands except the following are valid in Interactive Mode:
BUFFERSIZE
P}~TTERN

RUNTIME
Sr.I~ART

RE:START
If you enter these commands, lOX prints the error message:
I n:<

"- "-

C () 01 11, Fi n d va}."i. (Ion 1. '::~i" I"'

C () III man d

111 (] d e

You can use the BUFFERSIZE command within the SELECT and VERIFY
command lines to override the current defaults for the device being
selecte!d, but the BUFFERSIZE command cannot be used by itself to reset
the default.
Althougrh you cannot use the PATTERN command to choose a different
pattern to be written to the volumes being tested, you can use PATTERN
with no argument to display all the patterns.
The following commands are valid only in Interactive Mode:
ABORT
PRINTSUMMARY
PROCEED
Spy
Al thoug:h you can use PRINTSUMMARY and Spy in Command Mode without
generat.ing
an error message, these commands display meaningful
informa.tion only when you use them in Interactive Mode.
When you use the ABORT command, lOX exits Interactive Mode and enters
Command Mode.
The ABORT command with no qualifiers terminates all

4-19

THE I/O EXERCISER (lOX)
exercising and all tasks initiated by the EXECUTE command. This form
of ABORT is valid only in Interactive Mode because in Command Mode
there can be no exercise or active tasks to abort.
The PROCEED command exits Interactive Mode and enters Execution Mode
unless no activity remains when you issue PROCEED, in which case lOX
aborts the exercise.

4.10

lOX OUTPUT

lOX generates two types of output:
activity reports and error
reports.
Activity reports summarize lOX processing information, such
as how long an exercise will run and how many ASTs have been executed.
There are two kinds of error reports: data compare error reports,
that show where lOX finds errors on the volume being tested, and I/O
error reports, that indicate failed QIOs from a driver. You use the
LOGFILE command (see detail in Section 4.12) to direct activity and
error reports to your terminal or to a log file.

4.10.1

Activity Reports

There are three types of activity reports:
1.

Accumulated Totals - An activity report at the end of an lOX
exercise that reports the activity for the entire exercise

Interval Reports - An activity report that summarizes lOX
activity in the time intervals set by the SUMMARYTIME command

Summary Reports - A report of activity between the last
Interval Report and the time you enter the PRINTSUMMARY
command to request a summary report.

Section 4.12 discusses the SUMMARYTIME and
detail.

PRINTSUMMARY

commands

4.10.1.1 The Format of Activity Reports - The formats of activity
Interval and
reports are indentical except for the first line.
For
summary reports begin with the time and date of the report.
example:

The accumulated totals report does not give the time or
report and begins:
(.1

C C 1.1 1'1 IJ 1..

TED

date

the

iiJTf.11..S

4.10.1.2 The Content of Activity Reports - The content of
all
activity reports is identical. The following is an interval report of
an exercise that tests SYO:.
lOX -- Summars of exerciser

~ctivit~

at 31-DFC-85 11:18:29

TIME -- Run: 1 min.
Elapsed: 2 min.
Remajnjn~: 3 min.
S YO: -- -- 1., 874. F: / W T' (~WH~ <;) t s t.. f) t a 1. in C.l 1, 874. b 1. 0 C k 5 wit h no
t"STs P;<f.'cuted: :t, 87~j.
Idle-loop iterations! 1,803.

4-20

Po r T' f) r s

THE I/O EXERCISER (lOX)
The ac1tivi ty report contains the following information:
•

Timing information
- Time between reports as set in the SUMMARYTIME command
- Time that the exercise has been in progress to
minute

the

nearest

- Time remaining to the nearest
will finish

the

exercise

acti vi ty

minute

before

• Unit information for each unit being tested
- Number of I/O requests to the unit
- Number of blocks exercised for disks and tapes

- Number of bytes exercised for terminals
- Number of error encounters on the unit
•

Number of ASTs executed

•

Number of iterations through the idle loop

You uSle the following commands
reports:

control

the

output

LOGFILE
PRINTSUMMARY
Spy
SUMMARYTIME
Section 4.12 discusses each of these commands in detail.

4.10.2

Error Reports

You uSle the REPORTERRORS command to enable or disable error reports.
Section 4.12 discusses the REPORTERRORS command in detail. There are
two kinds of error reports: data compare error reports and I/O error
reports.

4.10.2.1 Data Compare Error Reports - A data compare error means that
the driver returned a success I/O code to lOX but that the data
written to the volume and the data read from the volume did not match.
The following is an error report generated by a data compare error:
lOX

DR1: data compare error at block 33,937 (decimal) 102221 (octal)
Good Data: 005767
Bad Data: 155555 •
0
Word Position: 0 (decimal) 0 (octal) ~
Buffer contained 255. additional errors

Identifies the device on which lOX encountered an error. It
reports the starting block (in both decimal and octal) in
which the error was found.

•

Shows the "good data that lOX wrote to the volume and the
"bad data
that lOX read from the volume. Only the first
error encountered in the test buffer is reported.
II

4-21

THE I/O EXERCISER (lOX)

Shows the position of the first word in the test buffer that
generated a mismatch during the current operation. Only the
first error encountered in the test buffer is reported.

Shows how many other errors were found in the test buffer.

4.10.2.2 I/O Error Reports - There are 12 I/O errors.
If a QIO
fails, the driver returns an I/O failure code to lOX. lOX generates a
specific I/O error report as a result of the following I/O errors:
I/O Code

Description

IE.ABO
IE.BBE
IE.DAO
IE. DNR
IE.EOT
IE.FHE
IE.OFL
IE.PRI
IE.VER
IE.WCK
IE.WLK
N/A

Operation aborted
Bad block
Data overrun
Device not ready
End-of-tape detected
Fatal hardware error
Device off-line
Privilege violation
Unrecoverable error
Write check error
Write-lock error
Unexpected error

These error codes are shown in the RSXIIM/M-PLUS I/O Drivers Reference
Manual.
Section 4.13 of this chapter presents the format and content
of the 12 error messages that lOX generates because of these error
codes.

4.11

THE TASK-BUILD FILE

You can change the initial defaults for lOX parameters as well as
other defaults of the IOX.TSK by editing the lOX task-build file,
IOXBLD.BLD.
On RSX-llM systems, this file is located on your system disk
[1,24J for mapped systems and (1,20J for unmapped systems.

UFO

On RSX-11M-PLUS systems, this fi1eis located on your system
UFO [1,24J.

disk

4.12

COMMAND DESCRIPTIONS

This section provides complete descriptions of the commands in the lOX
Command Language. Each command description includes the following:
•

Kind of command by category:
and Control.

•

All command formats.

•

Qualifier descriptions.

Function,

Display,

Parameter,

mode restrictions.
(Where no mode restrictions are
• Operating
placed on a command, it is valid in Command Mode and
Interactive Mode.)

4-22

THE I/O EXERCISER (lOX)

•

Kinds of devices and testing to which the command applies.

•

Initial defaults, if applicable.

The conwands are presented alphabetically.
Commands may be issued in all uppercase, all lowercase, or part upper
and part lowercase. You can abbreviate commands using any combination
of characters that appear unique to the lOX Command Language.
All con~ands are represented by unabbreviated uppercase letters.
All
lowercase words in the presentations of command syntax indicate that
you substitute alphanumeric characters for the word.
All nunlerical qualifiers are decimal.
Bracke1:s [ ] indicate optional elements in the command line.

4-23

THE I/O EXERCISER (lOX)

ABORT
A[BORT] [/ALL]
[taskname]
The ABORT command is an lOX control command. You cannot use the ABORT
command to abort a task that has attached your terminal, such as PIP.
'There are three forms of ABORT:
ABORT

Terminates the execution of an I/O exercise and
tasks initiated by the EXECUTE command. This form
of ABORT is valid only in Interactive
Mode
(testing in progress) because in Command Mode (no
testing in progress) there can be no running
exercise or active tasks to abort.

ABORT/ALL

In Interactive Mode, this form of ABORT terminates
the execution of all tasks initiated by the
EXECUTE command and removes the tasks from the
list of tasks to be executed.
In Command Mode,
this form of ABORT removes all tasks from the list
of tasks to be executed.

ABORT taskname

In Interactive Mode, this form of ABORT terminates
the execution of a task initiated by the EXECUTE
command and removes the task from the list of
tasks to be executed.
In Command Mode, this form
of ABORT removes the task from the list of tasks
to be executed.

4-24

THE I/O EXERCISER (lOX)

BADBLOCKS
BA[DBLOCKS] ddnn:

[blocknumbers]

You can use BADBLOCKS as a device-dependent parameter command or as a
display command. Note that the BADBLOCKS command applies only to NFS
disk tE~sting.
To use the
BADBLOCKS requires a device specification "dduu:".
BADBLOCKS command, the disk that you specify must already be selected
for NFS operations.
BADBLOCKS as a Parameter Command
With the BADBLOCKS Parameter Command, you can omit the bad blocks on
your disk from lOX testing. BADBLOCKS does not find bad blocks on
your disk; it allows you to enter those blocks that the BAD utility
has reported to be bad into an lOX bad blocks list for the disk. When
you eXE~rcise the disk with SELECT or VERIFY, the blocks that you
entered in the list will not be exercised.
lOX omits only those
blocks that you listed as block numbers in the BADBLOCKS command line;
blocks marked as bad by the BAD utility but not entered into the bad
blocks list with the BADBLOCKS command are treated as good blocks by
lOX.
Once you have made entries in the bad blocks list for a disk, the
block numbers that you entered remain on the list until you deselect
the disk.
There are two formats for entering bad blocks into the bad blocks
list. One format is illustrated in the following two examples:
Bl\DBLOCKS DM1: 3
This command line (which uses DM1:
the bad blocks list for DM1:.
BADBLOCKS DM1:

as an example) enters block

3,4,5,11,12,13,99,151

In this second example, the command line enters blocks 3,
12, 13, 99, and 151 into the bad blocks list for DMl:.

11,

The second format has the following form:

where:
beg

Beginning block number.

num

Number of sequential blocks.

For example:
BADBLOCKS DMl:

3:3,10:4,100:50

This command line enters blocks 3 through 5, 10 through 13, and 100
through 149 into the bad blocks list for DMl:. You can use this
format for the length of a single command line.

4-25

THE I/O EXERCISER (lOX)

BADBLOCKS (Cont.)
You can use the two formats together on the same
example:
BADBLOCKS DM1:

command

line.

For

3:3,10:4,99,100:50,151

This command line enters blocks 3 through 5, 10 through
through 149, and 151 into the bad blocks list for DMl:.

13,

99,

100

Command.

For

BADBLOCKS as a Display Command
BADBLOCKS with no block numbers specified is a Display
example:
BADBLOCKS DM1:
This command line displays the bad blocks list for DMl:.
BADBLOCKS DMl:

If you type:

3:5,10:4,99,100:50,151

lOX would display:
000003:005
000010:004
000099:051
000151:001
lOX displays the bad blocks list using a variation of the second
format.
It strings consecutive blocks together even if you did not
enter them using the second format. For example, in the command line,
you entered:
99,100:50 ....
However, when lOX displays the bad blocks list, it does not separate
these because blocks 99 and 100 are consecutive blocks.
It does not
display two lines: one for block 99 and one for blocks 100 through
149.
Instead,
it displays (line three) the bad blocks list in one
line as if you had entered 51 blocks (99:51) beginning with block 99
in the bad blocks list.

4-26

THE I/O EXERCISER (lOX)

BUFFERSIZE
BU[FFERSIZE] buffersize
BUFFERSIZE is a device-dependent parameter
command.
You
use
BUFFERSIZE to determine the amount of data that lOX transfers for
every read/write operation request when exercising
NFS
disks,
terminals, magnetic tapes, and cassettes. lOX stores the specified
size in bytes and rounds this number up to the next 4-byte boundary.
When you use the random data pattern (PATTERN 0), BUFFERSIZE should
never exceed 3400(decimal) bytes, or lOX generates unpredictable data
compare errors.
Although read/write buffers are used for FILESII disk testing and for
NFS testing with DECtapes, the buffersize for these devices is fixed.
A SI2(decimal)-byte buffer is used for all FILESII testing.
A
1024(decimal)-byte buffer is used for all DECtape testing.
The BUFFERSIZE command is valid only when used by itself in Command
Mode.
In addition, it is valid only if units are not currently
selected; that is, you must set your default buffer size before you
select any units for testing. However, you can use the BUFFERSIZE
command in the SELECT and VERIFY command lines to override the default
buffer size for the selected device as long as you set the buffer size
smaller than the default.
The initial default is 1024(decimal) bytes.
The default buffersize
for terminals is the size of the typeahead buffer, if typeahead is
enabled. Otherwise, the default is 96(decimal) bytes.

4-27

THE I/O EXERCISER (lOX)

COMPAREDATA
COM[PAREDATA] Y[ES]/N[O]

COMPAREDATA is a device-dependent parameter command
SELECT that applies to the testing of devices.

for

FILESll

and

COMPAREDATA enables or disables the checking of the data pattern.
COMPAREDATA YES enables data pattern checking; COMPAREDATA NO disables
data pattern checking. When you direct lOX to compare data patterns,
it compares the data that it writes to the unit with the data it reads
from the unit. If the data read does not match the data written, lOX
prints a data compare error report. Section 4.10.2.1 discusses data
compare error reports in detail.
You can use COMPAREDATA within the command lines of FILESll and SELECT
to override the current COMPAREDATA setting for the device being
tested.
The initial default is COMPAREDATA YES.

4-28

THE I/O EXERCISER (lOX)

CONFIGURE
CONF[IC;URE] [dduu: [=type]] ••••
CONFIGURE is a general parameter command and a display command.
You
use CONFIGURE as a parameter command to add devices to your test
configuration and as a display command to display the current
configuration.
lOX configures by default one of each supported device type as unit
"0".
Allowable device types are either DISK, TERM, or TAPE. You can
add any device to the test configuration to which you can assign a
logical device name by using the MCR ASN command. When you configure
a device, lOX adds the device to its list of devices available for
testin9 and creates an empty data structure for the device.
If a dE~vice is not already included in the test configuration, you
must configure it before you can select it for testing. lOX does not
unconfigure devices at the end of an exercise. Once you have included
a device in the test configuration, only RESTART will unconfigure it.
CONFIGURE with no qualifiers displays the current test configuration.
To find\ out if a device is already configured, type the following:

lOX responds as follows:
Disks:
DBO DDO
DXO DYO

DFO
EMO

DKO
SYO

DLO

DMO

DPO

Tapes:
DTO

MFO

MMO

MSO

MTO

MUO

C~~O

DRO

DSO

DUO

TE~rrninals :
T~~O

To add devices to the test configuration, type the following:
IClX>CDt.tFICHlF:F DI<l:

flP1:

fiR?:

XX:

YY!

MM:=;:

~'tQl

:c-::TAPE

This command line configures devices DKl:, DBl:, DB2:, XXO:, and YYO:
as disk units. It configures devices MM5: and MOl: as tape units.
You must separate unit specifications with spaces or tabs.
Use thE~ display form of CONFIGURE to check that
been added to your configuration as follows:

these

lOX >CONF
Disks:
DBO DBI
DRO DSO

DB2
DUO

DDO
DXO

DFO
DYO

DKO
EMO

DKI
SYO

DLO
XXO

DMO
YYO

Tapes:
DTO

MFO

MMO

MM5

MOl

MSO

MTO

MUO

c~ro

TE~rminals :
T~rO

4-29

DPO

devices

have

THE I/O EXERCISER (lOX)

CONFIGURE (Cont.)
If you do not specify a device type when you configure a
device type defaults are as follows:
1.

device,

the

If one unit of a device type has already been configured as a
disk and you add a unit with the same device specification,
lOX also configures that unit as a disk.
For example,
because
DKO:
and DBO:
in the previous example are
configured as disks in the default configuration,
lOX
configures DKl:,
DBl:,
and DB2:
as disks.
By the same
logic, lOX configures MM5: as a tape because MMO: has been
configured as a tape unit by default.

lOX maintains consistency in configuring device
units.
Therefore, you cannot configure DKl:,
DBl:, or DB2: as
tapes. The same holds true for MM5: -- you cannot configure
it as a disk.
In both cases, lOX generates the following
error message:
I f) >:

Ii (:\1.11. I :

':; :.., ::~ I ~ :i. f :i. i·~ I j

d ;':! V :i. c (~.~ t ':: P E- 'i. <;i :i. n c Cl f'I <;; i. ';; t (.:? n t

For devices with mnemonics that have not been previously
configured,
the default is disk. Hence, in the following
example, lOX configures both XX: and YY: as disks, and MOl:
as a tape.
IO)(>CONF

01<1:

f1f::I!

flH:?:

XX!

YY!

11W~:

MQ1!::.cTAPE

lOX responds by displaying the following messages:
I DX
I OX

lXO

··

YYO +

i. i'~ I:·~

-1:, \::~ F·' (0

'j i? 'y' :i c ~:'

'.".) (.:~ \,.1

I:, \:! ~'J f:!

4-30

not
nnt

<:; ~'., I,:' c· "i- f

i. t·~ d --

:::. F' P (' j f :i pd

rl~~f;:~1 I

1 +, 'i n'~ to

df-''fau ] t j n:~

nrSI-<

n T SK

THE I/O EXERCISER (lOX)

CTRL/C
CTRL/C is a control command. In Command Mode and Interactive Mode,
CTRL/C generates an MCR prompt "MCR>" allowing you to enter one MCR
command line. The function of CTRL/C in Execution Mode depends on
whether CONTROL C has been set YES or NO. If you have set CONTROL C
NO, then CTRL/C generates the MCR prompt "MCR>" as it does in Command
and Interactive Modes.
If you have set CONTROL C YES, then CTRL/C
exits lOX from Execution Mode and enters Interactive Mode.
CTRL/C exits to MCR by default in Command and Interactive Modes.
In
Execution Mode, CTRL/C exits Execution Mode and enters Interactive
Mode by default.
Section 4.9 describes the three lOX operation modes in detail.

4-31

THE I/O EXERCISER (lOX)

CONTROL_C
CONT[ROL_C] Y[ES]/N[O]
CONTROL C is a general parameter command. You use CONTROL C to enable
or disable the use of CTRL/C to interrupt an I/O exercise.Command Mode
CTRL/C gives control to MCR for one command line. The
parameter has no affect on CTRL/C in Command Mode.

CONTROL C

Execution Mode
If you have set CONTROL C NO, then CTRL/C gives control to MCR
and you receive the -MCR prompt ">" every time you press the
RETURN key and "MCR>" every time you press CTRL/C until the
exercise has terminated.
With CTRL/C disabled, you cannot
interrupt the exercise to enter IOX commands. However, you can
terminate it with the MCR ABORT command and issue other MCR
commands while an exercise is in progress.
If you have set CONTROL C YES, IOX will not accept any input from
your terminal except -CTRL/C.
If you try to enter anything but
CTRL/C, you receive the following error message for each key you
press:

When you press CTRL/C, you receive the IOX prompt instead of the
MCR prompt and IOX exits Execution Mode and enters Interactive
Mode.
Interactive Mode
You have access to Interactive Mode only if CONTROL C is enabled.
In Interactive Mode, you can enter most IOX commands. The RETURN
key and CTRL/C have the same functions in Interactive Mode that
they have in Command Mode.
Section 4.9 describes the three IOX operation modes in detail.
The initial default is CONTROL C YES.

4-32

THE I/O EXERCISER (lOX)

DENSITY
DEN[SI1~]

dduu:

[n]

is a device-dependent parameter command and a display command.
The DENSITY command applies only to magnetic tape testing and requires
a magnetic tape device specification for "dduu:".

DENSIT1~

You use DENSITY as a device-dependent parameter command with an
argument "n" to set the density and characteristic word of a magnetic
tape.
(The device characteristic word is defined in the RSX-IIM-PLUS
Guide to Writing an I/O Driver.) You issue the DENSITY command before
you select the tape for NFS testing with SELECT. You can alsq set the
tape density for a magnetic tape unit by using the DENSITY command
within the SELECT command line.
You se1: all tape densities in bits per inch (bpi) using decimal values
for "n". The following tape densities are legal:
HIi':

MM:

MS:

MT:

MU:

1600
6250

800
1600

1600

200
556
800

1600
6250

You use DENSITY as a display command without an argument
nil to
display the current density of the specified magnetic tape unit.
For
examplE~ :
II

IOX>DENSITY MM:
Density= 1600 BPI Characteristic Word= 004004 (octal)

This command line displays the current density and characteristic word
for MMO:. To change the tape density to 800, you type the following:

IOX>DENSITY MM: 800
The DENSITY command is the only way you can find out what the current
DENSIT~{
setting is on a magnetic tape (because DENSITY is not
displayed by the PARAMETERLIST command).
To display the new tape density and characteristic word for MMO:,
type the following:
Iox>nFNE~:rTY

you

l"iM!

Densit~=

800 BPI Characteristic Word= 000000 (octal)

enter the density in
For tapes other than MT, MM, MS, MU, and MF,
decimal.
However,
lOX displays the density in octal as the
charact.eristic word.
For example:

IDX>DENS MQ!
Denslts= 1111 BPI

IOX::-nENS ,10: 800
IDX>DENS MQ:
Densits= 11?? BPI

Characteristic Word= 004004 (octal)
Characteristic W0rd= 001440 (octal)

4-33

THE I/O EXERCISER (lOX)

DENSITY (Cont.)
This command sequence indicates the following:
•

lOX does not know the density of the tape designated
The characteristic word is the default.

MQ:.

you set the density of MQ:
to 800 bpi (decimal) and
• When
display the current density and characteristic word, the
density appears in the characteristic word (octal).
Except for MT: devices, the initial default density for magnetic tape
devices is 1600 bpi. The initial default for MT: devices is 800 bpi.

4-34

THE I/O EXERCISER (lOX)

DESELECT
DES [EL1~CT] ddnn:
DESELECT is an lOX function command. You use DESELECT to "deselect"
devices that you have selected for testing with SELECT, VERIFY, or
FILESI1. DESELECT requires device (dd) and unit (nn) specifications.
If you issue the DESELECT command in Interactive Mode (while testing
of thE~ specified device is in progress), testing on the device
terminates and the device is removed from the list of devices to be
tested.. If you issue the command in Command Mode (while no testing is
in pro9ress), then DESELECT removes the device from the list of
devices to be tested.
For devices that you have selected for NFS testing, DESELECT does
following:
•

Terminates I/O operations (if they are in progress)

•

Deletes the badblocks list associated with the
only)

•

Deallocates all buffer space associated with the device

•

Detaches lOX from the device

device

For devices that you have selected for FILESII testing, DESELECT
the following:
•

Terminates I/O operations (if they are in progress)

•

Closes and deletes the temporary file

•

Deallocates all buffer space associated with the device

The DgSELECT command
configuration.

does

not

remove

4-35

device

from

the

(disks

does

test

THE I/O EXERCISER (lOX)

ERRORLIMIT
ER[RORLIMIT] n
ERRORLIMIT is a device-dependent parameter command that sets the
rnaximum number of errors that lOX will tolerate between interval
reports, before deselecting a device.
You use the SUMMARYTIME command to determine how often lOX generates
interval reports.
If you request interval reports every 2 minutes
(SUMMARYTIME 2) and set ERRORLIMIT at 10 errors, lOX will allow not
more than 10 errors on a device in a 2-minute interval before
deselecting the device from testing.
You can also use the ERRORLIMIT command within the FILESll, SELECT,
and VERIFY command lines to override the default error limit for the
device being selected for testing.
The initial default is 10 errors.

4-36

THE I/O EXERCISER (lOX)

EXECUTE
EXE[CU,]~E]

taskname commandstring

EXECUTg is a function command. You use EXECUTE to direct a command
line t~o the operating system for execution. The task you want to run
must bE! installed. For the EXECUTE command to operate, your system
must support task spawning. The rules for using the SPWN$ directive
and ent~ering command lines apply to the arguments for taskname and
commandstring in the EXECUTE command line (see the RSX-llM/M-PLUS and
Micro/RSX Executive Reference Manual).
When you use the EXECUTE command in Interactive Mode (testing in
progress}, the task you have initiated with EXECUTE runs immediately.
When you use the EXECUTE command in Command Mode (no testing in
progress}, lOX queues the task for execution.
The task begins
executing when you start an exercise with the START command.
Tasks you initiate with EXECUTE run in parallel with I/O exercises.
For example, you use the EXECUTE command to run the BAD utility to
list at~ your terminal the bad blocks on an NFS disk.
You can then
enter this information in the lOX badblocks list so that lOX will not
try to perform I/O operations on the blocks that are bad.
To run the BAD utility on NFS disk DLO:, type the following:
IO)(>FXF:

•., • Bt,f.i :H:nl .. O!/LI

In this case, you must include the pound sign (i), as shown in the
command line.
For tasks such as BAD, whose command line processing
requires a leading space, lOX converts the pound sign to a space.
A
task such as PIP does not require a leading space in its command line.
For thE!Se tasks, you do not need to include the pound sign in the
command line.
You can also use the EXECUTE command to run a task to do system
testin9 while lOX is doing I/O testing.
For example, if you have
written a CPU exerciser task and installed the task as ... QWK, you can
run this task in parallel with the I/O Exerciser by entering the
following command line:
IDX . ·E:<FClITE ••• OWI<
10:" :··::;Tf.:II'T

ICF'U·~:1144

where /CPU=ll44 is the command line to be passed to task ... QWK.
To remove a task from the list of tasks to be executed and terminate
execution of the task (if the task is in progress), you use the ABORT
command.

4-37

THE I/O EXERCISER (lOX)

EXIT
EXI[T]
EXIT is a control command. You use the EXIT command to terminate
processing and exit from lOX to the operating system monitor.

4-38

lOX

THE I/O EXERCISER (lOX)

FILES11
F[ilesll] dduu:

[command=qualifier] •••

FILESll is a function command. You use FILESII to select a Files-II
disk for an I/O exercise. Testing a disk with FILESII protects the
contents and structure of the disk, because lOX writes into a
temporary file that lOX removes from the disk at the end of the test.
You must first configure the disk if it is not already in the test
configuration before you can select it for testing.
When you select a disk using FILESll, you can override the default
paramet;ers by using the following device-dependent parameter commands
in the FILESll command line:
COMPAREDATA
ERRORLIMIT
INTERLEAVE
RPI.NDOM
TEMPORARYFILE
The following example uses some of these parameter commands:
IU\···FJLFBll. n:flO!

Cni'iF'ARFnATA:~"YFS

F~ANDOM:::NO

TFMPOF:AF:YFII..F:::.f:.OO

This command line selects DBa:
for I/O exercising.
lOX compares data
read ~vith data written, sequentially accesses the blocks in the file,
and opE~ns a GOO-block temporary file.
Example 4-1 in Section 4.7
illustrates and describes how you test an RL02 with FILESll.
Once you have selected a device, the default parameters become fixed
for that device. You cannot reset them without first deselecting the
device .
When you issue the FILESll command in Interactive Mode (while an
exercise is in progress),
lOX begins testing the specified device
immedia.tely. When you issue the FILESll command in Command Mode
(while no exercise is in progress), lOX includes the specified device
in its list of devices to exercise but does not begin the exercise
until you start the exercise with the START conunand.
If no commands are specified within the FILESll command line, the
device is exercised with the default parameters currently in effect.
Commands can only be separated by spaces or tabs.

4-39

THE I/O EXERCISER (lOX)

HELP
H[ELP]
HELP is a display command.
commands at your terminal.

You type HELP to display a summary of

4-40

rox

THE I/O EXERCISER (lOX)

INTERLEAVE
I[NTERl.EAVE] number
INTERLE:AVE is a parameter command that sets a device-dependent
paramet.er for disk testing. The INTERLEAVE command sets the number of
blocks to be skipped before lOX .writes the next buffer of data.
The
INTERLE:AVE factor applies only to sequential testing: that is, if you
have set RANDOM NO.
If you have set RANDOM YES, lOX tests blocks on
the di.sk randomly and ignores the INTERLEAVE factor.
The initial
defaul t. for RANDOM is RANDOM YES.
You can use the INTERLEAVE command within the FILESll, SELECT, and
VERIFY command lines to override the current default for the disk
being selected.
The ini.tial default is four blocks.

4-41

THE I/O EXERCISER (lOX)

LOGFILE
L[OGFILE] Y[ES]/N[O]
LOGFILE is a general parameter command. You use the LOGFILE command
1:0
direct activity and error reports either to your terminal or to a
log file in your default disk area.
Section 4.10 discusses the
content and format of activity and error reports in detail.
LOGFILE NO directs activity and error reports to your terminal.
LOGFILE YES directs activity and error reports to the log file.
Summary reports, which lOX generates when you issue the PRINTSUMMARY
command, are displayed at your terminal regardless of how you have set
LOGFILE.
lOX does not open a new log file each time you run an exercise with
LOGFILE enabled.
Instead, it creates the file when you first run an
t~xercise, and then appends to the created file.
The file is in your
area and is named as follows:
yyyyyy.LOG
where yyyyyy is the name of the task currently running lOX on your
terminal
(lOX, another task name, or the name of your terminal, for
example TTlO).
In addition to activity and error reports, lOX inserts
date and time information into the log file:
•

When the exercise began,
PARAMETERLIST command

•

When the exercise ended

•

When a log file was started

•

When log file entries were terminated

•

When an exercise was aborted

For example, all exercises begin
following:
I n X -_.- ? 0 ._.. .1 UL .- 8 ~'5

1. 1. : 1. ~:.:i i. ? 4

followed

with

the

event

line

the

following

output

the

such

the

** **:f. * F X C "[ ::;:; F P T AF: T F n *:t: * :t. ***
:.+: $

f:'I~:

:*"

and end with an event line such as:
I Cl X -- -- :? 0 -- ,J U!. -- f.l ~::i

1:1::? 0 ! 3 4

**:+: *****

The initial default is LOGFILE NO.

4-42

~.:.:< F F~ C J S F P T FFnU NAT F fI

*1: **:+: ***

THE I/O EXERCISER (lOX)

LOOPBACK
L[OOPBJ~CK]

Y[ES]/N[O]

LOOPBACK is a parameter command that is used only for exercising
terminals.
The LOOPBACK command causes rox to read back ASCII
characters it has written to a logged-out terminal. To use LOOPBACK,
you must have installed a loopback connector on the terminal line and
the terminal line must have typeahead enabled.
Before using LOOPBACK, certain terminal characteristics must be set.
These characteristics are SLAVE, PASSTHRU, NOECHO, LOWERCASE, and
NOWRAP.
They must be set BEFORE the loopback connector is installed.
TypeahE~ad must also be enabled.
Since typeahead is required, LOOPBACK
is available only on systems with the full-duplex terminal driver.
LOOPBACK is useful for testing a terminal line and interface, since
charact:ers must be written by the interface to the line, reversed by
the loopback connector, sent back up the line, received by the
interface, and read successfully for lOX not to report an error.
LOOPBACK NO is designed to test a terminal by displaying a portion of
the ASCII character set.
LOOPBACK NO is the default.

4-43

THE I/O EXERCISER (lOX)

PARAMETERLIST
PAR[AMETERLIST]
PARAMETERLIST is a display command.
PARAMETERLIST displays
two kinds of information.
For example:

least

lOX >- F' r~ I~ (. rvi r::: Tr::: 1:; '., I S T
BUFFERSI7F= 1024.

E h: Ri) F.: L r r'i T T =:: :1, 0 •
J r~ T F RL F i~ V E ::: 4.
P(:,TTFI:::N:": O.

f::l::C~~lf~D3::::
10::>4.
r';:UNTI riF:::· ~:j.
:~UiVjMAF: YT T MF:~: 1.
T EMF' nP (.1 H y' F II" E ::: t::j 0 0 •

CClMPAF<FI'tATA::: YF~~
C n N T R fJ L ., C··:: 'y E :::i
I. OGFII..f':= NO
1.. f)OPBf.:ICI<:::: NO
F:t,NnnM::: YFB

RFF'ORTFRRORS= YES

RFTFo,:JFS:::: YFB
',,.Ii) I.. "MFC HEr; K ::: Y E ~::;

YFS
\;JF:T T'FCHFCK=:: NO

l'Jf~,IT::::

Buffer space usage= 3290.:1924.:1924.:1.

o The current default parameters
~

lOX buffer space statistics

At most, PARAMETERLIST displays four kinds of information:
•

Current execution default parameters

•

lOX buffer space statistics

lOX may also list the:
•

List of tasks initiated by the EXECUTE command

•

Devices selected for testing with FILESll, SELECT, and VERIFY

Example 4-5 describes the information in the four parts of the
PARAMETERLIST
display
that correspond to these four kinds of
information.
Example 4-5
I 0 ~<:, ;",( \- C I.J T F
1 U :<
lOX

PARAMETERLIST Display Shown in Four Parts

•• v P (I '0 t Y.11 , '::' ! / L. I

F I IF;::; 1 1 S Y!
F I !:: r; T r1i1 ()!

T F MF (I f;:
I,: F r: fJ f~: T.l
IC;< I) F 1< : r· y £1 :'.j 0.; i·: 1:\ 1\1 f1 F
I Ci )( :: I~' f~: (I t'll?: T F I~ I, T\:;r

f·: Y F J 1 F :~: tl 0 0

F P F;: 0 F;: tIM I f .::: I.::j 0
::: -~ ~"j 0 H' JF F F PST '7 !~ .. '7 n 0 F: F T P '[ F S :::. 1,1 ! )
() 0 ! 1 i) i) () I'~,~ f~1 j\1 nn tVj ::: N n J H 'f F PI. F t,l) Fe :.:::

CD
CD
f)

(continued on next page)

4-44

THE I/O EXERCISER (lOX)

PARAMETERLIST (Cont.)
Example 4-5 (Cont.)

PARAMETERLIST

D~splay

Shown in Four Parts
Par2-lTIeters

Fi]esi7e/Records/R~nSe

DMO:

2 0 O.

I..'FY
BEL.
Fll

r1MO:

C~UF.UFn

~512 •

800.

•

I:; F' ;:1 C ,",~

CDMPf.IF:Fnf.ITA·::: YFS
i~f'}NTRnL .C:· YE~::'
LUG F J I F :c:: N n
! .nOPF:ACK:::: NO
p,:,NnOI'1:::: YFS
RFpnRTFRRnRS~

~5.

SUM!'1fIPYT I MF':; j .
TFMpnl~:f~Ir.:YF,[I .. F=:: ~.:.iOO.

Bur f f.' r

1 i fI~?

ttl.. 0 : ll ... I

BUFFFf;:S I ZF::: 1024.
FF:I\OF:I .. TMTT·:" 1.'),
:I: N l t ri' i F t~ '..I F :::: 4 +
P(.:,TTFF:tJ :::: o.
F'ECOF'.n~~:=: 1,0::>4.
r;:Ul···!Tli"IF~~:

RFT INT=8. ERR=lO.
r,nrl F.1\R=-ctO.
COM RFT RnN FRR"50.

1., 0 0 0 •
:~50 •

COlTlrll;:~nr.1

••• BAD

-- :>

?OO.

'I I:; ;,; <:.i ,,,~ :::

PFTF~IFS:=:

YES

YFS

1)()LU1"iFCHFr::I{··:: YFS
~.J?IIT=: YFS
[.J PIT F c: HF CI< ":: Nn

:':i ~~ j B. ! 1. 0 ? 0 • ! 1.~) 8 ~~ • : .:~ •

•

Current defaults at the time you entered the PARAMETERLIST
command.
None of the defaults have been changed by the
command sequence in the example.
These are the initial
default parameters.
You can alter the default for these
parameters. See the description for the appropriate command
in this section.
lOX buffer space statistics.
is the following:

The form of

these

statistics

totalmemory:freeblock:freebytes:fragments
totalmemory
Size of lOX buffer space in bytes.
freeblock
Size of the largest free block of lOX buffer
bytes.

space

freebytes
Total amount of free
space.

bytes

available

lOX

buffer

fragments
Number of memory fragments in lOX buffer space.
In the examples, these statistics have changed to reflect
the buffer allocations for the three devices that you
selected for testing.
4-45

o
e

THE I/O EXERCISER (lOX)

PARAMETERLIST (Cont.)
C)

Selected devices and their device-dependent parameters.
These parameters correspond to the default parameters unless
you have overridden the defaults in the command line that
you used to select the devices.

This part of the display has five fields that are labeled by function.
They are as follows:
device
Device mnemonic of the selected device.
mode
Testing mode selected, either
(SEL), or FILESll (Fll).

VERIFY

(VFY) ,

SELECT

buffersize
Buffer size used for reading data from the device and
writing data to the device. You can alter the buffer
size for magnetic tapes, NFS disks, and cassettes.
Files-ll disks have a fixed buffer size of 512(decimal)
bytes.
DECtapes have a
fixed
buffer
size
of
1024(decimal) bytes.
filesize/records/range
One of the following:
•

Temporary file size in
with FILESll

blocks

for

disks

selected

•

Number of records to test for magnetic tapes
cassettes selected with the SELECT command

and

•

Range of blocks to be tested on NFS disks that
selected with the SELECT or VERIFY command

you

parameter
Device dependent parameters. These either specify a value,
such as INT=S. or ERR=lO.
(INTERLEAVE S or ERRORLIMIT 10),
or their presence indicates that you have set a YES/NO
parameter to YES.
For example, in (4) RAN means that you
set RANDOM YES; and, in (6), the absence of RAN means that
you set RANDOM NO.
See Section 4.6 for a list of what
parameters apply to what devices and modes of testing.

This display line corresponds to the command line
next.

This is the command line that you used to select SY:
for
FILESll testing, overriding the TEMPORARYFILE and ERRORLIMIT
defaults. lOX tests SY: as a Files-ll device, using the
following parameters:
•

A 512-byte data buffer (fixed)

•

A TEMPORARYFILE size of SOO blocks

4-46

discussed

THE I/O EXERCISER (lOX)

PARAMETERLIST (Cont.)
•

COMPAREDATA enabled (by default)

•

RETRIES enabled (by default)

•

RANDOM YES (by default)

•

An error limit of 50 errors

The display line corresponding to the command line discussed
next.

The command line you used to select DMO: with VERIFY.
lOX
tests DMO:, using the VERIFY mode with the following
parameters:
•

The default buffer size of 1024(decimal) bytes

•

The range of blocks 200 through 1000

•

RETRIES enabled (by default)

•

RANDOM disabled

•

The INTERLEAVE factor set to 8

•

The default error limit of 10
command

The list of tasks initiated by the
EXECUTE
corresponding to the command line discussed next.
This part of the display has the following fields:

•

Task Installed -- taskname ( ... BAD)

•

Status Execution -- status (QUEUED,
WARNING, ERROR, SEVERE ERROR)

•

Command Line -- line passed to the task

ACTIVE,

SUCCESS,

The command line you used to execute the BAD utility.

In Command Mode, you can use CTRL/O
PARAMETERLIST.
In Interactive Mode,
output.

4-47

to suppress the output of
CTRL/O has no affect on the

THE I/O EXERCISER (lOX)

PATTERN
PAT[TERN] [patternnumber]
PATTERN is a general parameter command as well as a display command.
You use PATTERN as a parameter command (with an argument) to set the
pattern that lOX writes and reads during I/O testing.
The PATTERN
display command (with no argument) displays all 13 patterns and shows
the pattern that is the current default with an asterisk (*).
The following example illustrates the default
PATTERN as a display command:

IDX>F'ATTFPN

Random Data

1
2
3
4
5
6

000000,000000
177777,177777
125252,052525
165555,133333
163126,163126
055555,155555
022222,122222
1:1:1:1.:1:1,111111
007417,007417
021.042,0:11042
104210,104210
052652,052652

7
G

9
:1.0

11
12

pattern

when

you

use

To change the default pattern from
which is pattern 3, you type:

random

data

"125252,052525",

IOX>PATTERN :3
Using the display form of PATTERN now shows that the asterisk
from pattern 0 to pattern 3 after you changed the default:

moved

TOX>f'?iTTFF:N

Ranciom (lata

000000,000000
177777,177777
125252,052525
165555,133333
163126,163126

2
3

4
5
6
7
8
9
10
11
12

055555,1~5555
~

022222,122222
111111,111111
007417,007417
021042,021042
104210,104210
O~?652,052652

The form of the PATTERN command that changes the
valid only in Command Mode.

pattern

default

Pattern 0 is random data from pure portions of the I/O Exerciser
itself.
When you use the random data pattern, the buffer size should
never exceed 3400(decimal) bytes or lOX will generate unpredictable
data compare errors.
The initial default pattern is random data, pattern O.

4-48

THE I/O EXERCISER (lOX)

PRINTSUMMARY
PRI[NTSUMMARY]

PRINTSUMMARY is a display command that is valid
Mode.

only

Interactive

lOX outputs activity reports and error reports.
Activity reports
summarize lOX processing information, such as how long an exercise
will run and how many ASTs have been executed. There are three kinds
of act:ivity reports:
accumulated totals, interval reports, and
summary reports.
(For a complete description of these three kinds of
activity reports, see Section 4.10.)
Summary reports and interval reports have the same content and format.
However, lOX generates interval reports at the time intervals that you
have set with the SUMMARYTIME command. lOX generates summary reports
when you enter the PRINTSUMMARY command in Interactive Mode. A
summary report summarizes lOX activity between the last interval
report and the time you enter the PRINTSUMMARY command. lOX displays
summary reports at your terminal even if LOGFILE is enabled.

4-49

THE I/O EXERCISER (lOX)

PROCEED
PRO[CEED]

PROCEED is a control command that you use only in Interactive Mode.
(Section 4.9 describes the three lOX operating modes in detail.) When
you enter the PROCEED command, lOX exits Interactive Mode, enters
Execution Mode, and checks for lOX activity.
If no exercises are in
progress and no tasks initiated by lOX are executing, then lOX
terminates the exercise.
If there is activity,
lOX resumes display of activity and error
reports to your terminal if you have set LOGFILE NO.
(With LOGFILE
disabled, lOX suspends activity and error reports to your terminal in
Interactive Mode.
With LOGFILE enabled,
lOX continues recording
activity and error reports in the log file.)
Use the PROCEED command only if you want lOX to terminate an exercise
as soon as activity terminates, or if you want lOX to resume display
of activity and error reports at your terminal with LOGFILE disabled.

4-50

THE I/O EXERCISER (lOX)

RANDOM
RAND[OM] Y[ES]/N[O]
RANDOM is a device-dependent parameter command that applies to disk
testingr.
The RANDOM command directs lOX to select either random or
sequential blocks for disk testing.
RANDOM YES directs lOX to use its random number
the blocks on the selected disk for exercising.
to sequentially test blocks on the disk.

generator to choose
RANDOM NO directs lOX

If you set RANDOM NO, lOX skips the number of blocks
the INT'ERLEAVE command before testing the next block.

specified with
For example:

r i:) \. .> 1 N T F P I. F (\ ') F 8
J ("I/..'> I~: t1 (..1nnI'i ND
In this example, lOX tests every eighth block on the
block 0,7, IS, .
.).

disk

(that

is,

You can use the RANDOM command within the FILESll, SELECT, and VERIFY
lines to override the current default parameter, when
command
selecting blocks for testing.
The initial default is RANDOM YES.

4-51

THE I/O EXERCISER (lOX)

RANGE
RANG[E] dduu:

[minimum:maximum]

RANGE is a device-dependent parameter command and a display command.
The RANGE command applies only to disks that you have selected for NFS
testing with SELECT or VERIFY.
RANGE, as a parameter command, sets the minimum and maximum block
numbers for NFS testing on the specified disk unit. For example:
J ,! ::. ' .' F: f:l ;.: f i F

nI ():

3 0 0 ! :=; 0 (.

rox tests blocks in the range 300 through 500 on DLO.
This form of
the RANGE command can be used in the SELECT or VERIFY command lines to
specify the range of blocks to be tested.
RANGE, as a display command, displays the current range of blocks to
be tested on the specified disk unit. The device must have been
selected for testing.
For example:
I C' )( ." P (.\ I ~ i~ E T! I .. 0 !

o. .. :- 2 0 , 4? 0 •

This is the default for RL02 devices.
After you issue the RANGE
command in the previous example, you can use the RANGE command to
display the current range of blocks to be tested as follows:
:I Clx.>r.;;t.IN(~~ 01 .. 0 t
300. --> ~.:jOO +

This form of the RANGE command cannot be used
VERIFY command lines.

within

the

SELECT

The default range for all disks that have been selected is zero to the
maximum block number on the disk minus sixty (0:maximum-60).

4-52

THE I/O EXERCISER (lOX)

RECORDS
REC[ORDS] recordcount
RECORDS is a device-dependent parameter command that applies
testing
of magnetic tapes and cassettes with SELECT.
specifies a record count, which is the number of records
magnetic tape or cassette to be exercised.
For example:

to the
RECORDS
on the

IOX>RECOf\:DS 200

This command line directs lOX to exercise 200 records on all magnetic
tapes and cassettes.
RECORDS 0 directs lOX to test the records on
magnetic tapes and cassettes until it detects the end of the tape, at
which time lOX displays an end of tape message and deselects the tape
unit.
You can use RECORDS in the SELECT command line to override the default
recordcount for the magnetic tape or cassette being selected.
The initial default is 1024(decimal) records.

4-53

THE I/O EXERCISER (lOX)

REPORTERRORS
REP[ORTERRORS] Y[ES]/N[O]
REPORTERRORS is a general parameter command that you use to enable
(REPORTERRORS YES) or disable (REPORTERRORS NO) lOX error reports.
There are two kinds of error reports: data compare error reports and
I/O error reports.
If a success code is returned from the device driver (meaning that a
QIO succeeded), but the data that lOX wrote does not match the data
that lOX read, then a data compare error has occurred.
Section
4.10.2.1 illustrates and describes data compare error reports.

r/o error codes are returned from the device drivers (meaning that a
QIO failed).
These error codes generate one of 12 error messages
discussed in Sections 4.10 and 4.13.
rox directs error reports to your terminal,
restrictions:

but

with

the

following

•

Error reports never interrupt activity reports.

•

If LOGFILE is enabled, lOX enters error reports in
file instead of displaying them at your terminal.

the

•

In Interactive Mode, lOX
reports.

suppresses

The initial default is REPORTERRORS YES.

4-54

the

printing

log
error

THE I/O EXERCISER (lOX)

RESTART
RES [TART]
RESTAR'I' is a control command. The RESTART command is valid only in
Command Mode.
When you restart the r/o Exerciser, you effectively
reinvoke rox without exiting to the operating system monitor.
The RESTART command performs the following functions:
•

Deselects devices that are selected for testing

•

Resets all parameters to their initial defaults

•

Removes all tasks queued for execution by the EXECUTE
from the list of tasks to be executed

command

•

Unconfigures all
configuration

default

devices

that

4-55

you

added

the

THE I/O EXERCISER (lOX)

RETRIES
RET[RIES] Y[ES]/N[O]
RETRIES is a device-dependent parameter command that applies to the
testing of magnetic tapes and NFS disks. RETRIES YES directs a device
driver to use its standard recovery t~chniques to attempt to recover
from an error.
RETRIES NO inhibits an I/O driver from using its
standard recovery techniques when it encounters an error.
You can use the RETRIES command within the SELECT and VERIFY command
lines to override the current default for the device being selected.
The initial default is RETRIES YES.

4-56

THE I/O EXERCISER (lOX)

RUNTIME
RUN[TI~[E]

minutes

RUNTIME: is a general parameter command. Note that RUNTIME
only in. Command Mode, when no exercising is in progress.

valid

You use the RUNTIME command to·specify how many minutes you want lOX
to test the devices(s) that you have selected for testing. If you
specify RUNTIME 0, lOX continues testing the selected devices until
you abort the exercise with either the lOX ABORT command or the MCR
ABORT command.
The initial default is 5 minutes.

4-57

THE I/O EXERCISER (lOX)

SELECT
SE[LECT] dduu:

[command=qualifier] •••.

SELECT is a function command. The SELECT command selects a device
with an NFS volume mounted for an I/O exercise that destroys the
contents and structure of the volume. Before using SELECT, you must
first configure the device if it is not in the test configuration.
When you use the SELECT command to select a device to be tested as an
NFS volume, you can override the current default parameters by using
the commands in Table 4-3 within the SELECT command line.
Table 4-3
Parameter Commands by Device Type for the SELECT Command
NFS Disks

Cassettes

BUFFERSIZE BUFFERSIZE
COMPAREDATA COMPAREDATA
ERRORLIMIT ERRORLIMIT
INTERLEAVE RECORDS
RANDOM
RANGE
RETRIES
VOLUMECHECK
WRITECHECK

DECtapes

Magnetic
Tapes

Terminals

COMPAREDATA
ERRORLIMIT

BUFFERSIZE
ERRORLIMIT
DENSITY
RECORDS
RETRIES

BUFFERSIZE
COM PARE DATA
ERRORLIMIT
LOOPBACK

'rhe following command line illustrates some of these commands:
HL<>~)FI.

01. 0:

PANG=100!4000 RFT::::YFf; PANTI::::N(l

TNT:::8

fll.JF=2000

'rhis command line does the following:
•

Selects DLO:

for I/O exercising

•

Tests only blocks 100 through 4000

•

Allows the driver to retry I/O
errors

•

Accesses the blocks on the volume sequentially
eighth block

•

Uses a data buffer of 2000 bytes for data transfer

operations

encounters

testing

every

Once you have selected a device, the default parameters become fixed
for that device.
You cannot reset them without first "deselecting"
the device.
When you issue the SELECT command in Interactive Mode (while an
lOX begins testing the specified device
exercise is in progress),
immediately. When you issue the SELECT command in Command Mode (while
no exercise is in progress), lOX includes the specified device in its
list of devices to exercise but does not begin the exercise until you
start the exercise with the START command.

4-58

THE I/O EXERCISER (lOX)

SELECT (Cont.)
If no further parameter commands are specified within the SELECT
command line, the device is exercised with the parameters currently in
effect.. Note that commands can be separated only by spaces or tabs.
ExamplE~ 4-2 in Section 4.8.1 illustrates and describes how you test
magnetic tape unit with the SELECT command.

4-59

THE I/O EXERCISER (lOX)

Spy
Spry] [dduu:]

Spy is a display command. You use the Spy command only in Interactive
Mode (exercising in progress) to display status information on
device(s) being tested.
If you do not specify an argument with Spy, you will receive a display
of status information on all devices being tested. When specified
with a device and unit specification, Spy displays status information
only for the specified device. For example:

>spy DBO:
lOX outputs the following:

DBO:

-- TYP[=Fl1

:r /O"-=AST

'JHN::::305 +

c~,.,pupd

This output indicates the following:
•

Device being exercised (DBO:)

•

Type of testing being performed on the device:
SELECT (SEL), VERIFY (VFY)

•

Virtual block number being tested (305(decimal) in
example), or, for NFS volumes, the logical block number

•

I/O request status:

•

Type of I/O function being performed:

FILESII (FII),

AST queued, in progress, or idle
READ or WRITE

Spy always outputs to your terminal, even if LOGFILE is enabled.

4-60

this

THE I/O EXERCISER (lOX)

START
ST[ART]
START is a control command and is valid only in Command Mode.
When
you us~~ the START command, lOX exits Command Mode and enters Execution
Mode. Section 4.9 discusses the three lOX operating modes in detail.
After you have set your test configuration and selected the devices
you want to test, use the START command to begin exercising the
selected units. START also turns on the lOX clock, begins activity
and error reporting (if you enabled error reporting with REPORTERRORS
YES), and begins executing tasks queued by the EXECUTE command.

4-61

THE I/O EXERCISER (lOX)

SUMMARYTIME
SU[MMARYTIME] minutes
SUMMARYTlME is a general parameter command that you use to specify how
often (in minutes)
lOX outputs interval reports.
(See Section 4.10
for a complete discussion of interval reports).
You can suppress
interval reports by setting SUMMARYTlME to o.
The initial default is 1 minute.

4-62

THE I/O EXERCISER (lOX)

TEMPORARYFILE
T[EMPORARYFILE] filesize
TEMPORARYFILE is a device-dependent parameter command that applies to
the testing of Files-II disks with the FILESII command. The FILESII
command. protects the contents of the disk by writing them to a
temporary file, which lOX deletes at the end of the exercise. You
specify the file size in blocks.
You can use the TEMPORARYFILE command in the FILESII command
override the current default for the disk being selected.
The initial default is 500 blocks.

4-63

line

THE I/O EXERCISER (lOX)

VERIFY
VE[RIFY] dduu:

[command=qualifier] ••••

VERIFY is a function command you use to select a mounted NFS disk for
an exercise.
VERIFY reads buffers of data without: writing on the
disk, performing data comparisons, or destroying the contents of the
disk.
VERIFY accepts the
within its command
device being tested:

following device-dependent parameter commands
line to override the default parameters for the

BUFFERSIZE
ERRORLIMIT
INTERLEAVE
RANDOM
RANGE
RETRIES
The following example illustrates how you use the ERRORLIMIT and RANGE
commands within the VERIFY command line to override the current
defaults for testing DMO:
I nX :> V F.I~' T F y'

(I ,Ii () !

!~ (.:1 N

r; F 1. (, () I::, Z~r, 0 0 0

r,. R nF.: I. T h TT 1. Co 0 ()
c:

This command line selects DMO:
for read only testing of blocks 1000
through 3000 (inclusive) with a maximum of 1000 errors before lOX
deselects the disk.
Once you have selected a device, the default parameters for that
device are fixed. You cannot reset them without first deselecting the
device.
When you use the VERIFY command in Interactive Mode (while an exercise
is in progress), lOX begins testing the specified device immediately.
When you issue the VERIFY command in Command Mode (while no exercise
is in progress),
lOX includes the specified device in its list of
devices to exercise but does not begin the exercise until you start
the exercise with the START command.
If no further parameter commands are specified within the VERIFY
command line,
the disk is exercised with the parameters currently in
effect. Commands can only be separated by spaces or tabs.
Example 4-3 in Section 4.8.2 illustrates and explains how you test
NFS disk with VERIFY.

4-64

THE I/O EXERCISER (lOX)

VOLUMECHECK
VO[LUMECHECK] Y[ES]/N[O]

VOLUMECHECK is a device-dependent parameter command that applies to
NFS disk testing with SELECT.
VOLUME CHECK enables or disables
checking of disks mounted as NFS volumes for a home block and a
Files-II structure.
If VOLUMECHECK is enabled (VOLUMECHECK YES), lOX
will not allow you to use the SELECT command to select a volume with a
Files-II structure.
With VOLUMECHECK disabled (VOLUMECHECK NO), lOX
will allow you to use the SELECT command to select the disk without
warning you that the test will destroy the contents of the disk. You
should use VOLUMECHECK YES unless you are intentionally writing over a
Files-II disk.
You can use the VOLUMECHECK command within the SELECT command line
override the current default values for the disk being selected.
The initial default is VOLUMECHECK YES.

4-65

THE I/O EXERCISER (lOX)

WAIT
WA[IT] Y[ES]/N[O]
WAIT is a general parameter command you use to determine whether or
not lOX waits for an event flag while an exercise is in progress. The
WAIT command has no effect on tasks initiated with the EXECUTE
command.
WAIT YES requires lOX to wait for an event flag to signal that an I/O
operation has completed.
During this time, the Executive may be able
to execute another task.
If you set WAIT NO, lOX executes an idle loop during I/O operations.
Setting WAIT NO can monopolize system resources.
Therefore, you
should not set WAIT NO unless you intentionally want to monopolize
system resources.
The initial default is WAIT YES.

4-66

THE I/O EXERCISER (lOX)

WRITECHECK
WR[ITECFlECK] Y[ES]/N[O]
is a device-dependent parameter command that applies only
to test:ing NFS disks with SELECT. You use the WRITECHECK command to
determine whether or not I/O drivers perform write checks to NFS
disks.

WRITECHE~CK

If WRITECHECK is enabled, lOX writes data to the disks by issuing an
IO.WLC (write logical block with check) to the driver instead of
IO.WLB (write
logical
block).
The
disk
controller
reads,
word-by--word, a copy of the data from the data buffer, while
simultaneously reading the same data from the disk.
The disk
controller compares the two copies of the data.
If the copies do not
match, a.nd if RETRIES is enabled, the driver repeats the original
write operation and performs another write check.
This process
continuE~s until the WRITECHECK function succeeds or
the retry count
for thE~ driver is exceeded.
If RETRIES is disabled or if RETRIES is
enabled but the retry count for the driver is exceeded, the driver
issues the "hard" error message, IE.WCK, and lOX generates an error
message .
You can use the WRITECHECK command within the SELECT command
overridE~ the current default for the device being selected.
The ini 1:ial default is WRITECHECK NO.

4-67

line

THE I/O EXERCISER (lOX)
4.13

ERROR MESSAGES

lOX generates two types of error messages: error messages with device
specifications and error messages without device specifications. lOX
displays device specifications as appropriate.
The format for an error message with
follows:
taskname -- ddnn:

device

specification

message

taskname
In

Name of the lOX task that is currently running.
messages that follow, taskname is always lOX.

the

error

ddnn
Device specification text of the message.
message
Information specific to this message.
The format for an error message without a device specification
follows:

taskname--message
where taskname and message are the same as
format.

defined

the

All error messages use the letter "x" to indicate that lOX sUbstitutes
the appropriate command, task name, or value for "x" within the
message.

4.13.1

Error Messages with Device Specifications

The error messages are presented in alphabetical order
letter following the device specification.
lOX -- dduu:

the

first

lOX

(bad

block

bad block, xxx (decimal) xxx (octal)

Explanation:
error) .

IE.BBE

error

code

returned

User Action: Use the BADBLOCKS command (only for NFS
enter the block number into the bad blocks list.
lOX -- dduu:

disks)

block number out of range

Explanation: You used the BADBLOCKS command to enter a block
number in the bad blocks list that is outside the range of blocks
that you specified with the RANGE command.

4-68

THE I/O EXERCISER (lOX)
lOX -- TTuu:

buffer size being reduced to typeahead buffer size

E)C:planation: The buffer size specified or used
la.rger than the size of the typeahead buffer.

default

User Action: None. lOX will reduce the buffer size to equal the
size of the typeahead buffer.
lOX -- dduu:

buffer size is greater than default

Explanation: The buffer size that you specified in the SELECT or
VERIFY command line is greater than the current default set with
the BUFFERSIZE command by itself.
User Action: Either raise the default buffer
size
(using
BUFFERSIZE by itself) or lower the buffer size override for the
device (using BUFFERSIZE within the SELECT or VERIFY command
line).
lOX -- dduu: data compare error at block xxx (decimal) xxx (octal)
Good data: xxxxx bad data: xxxxx
Word position: xxx (decimal) xxx (octal)
Buffer contained xx. additional errors
Explanation: lOX found an error when comparing the data read
with the data written. This error message shows the first block
number in which the error occurred during the transfer, the good
and bad data, the word position of the first error found in the
buffer, and the number of additional errors found in the buffer.
Section 4.10.2.1 discusses data compare error reports in detail.
User Action: None. If the error persists, enter the block in
the bad blocks list by using the BADBLOCKS command (for NFS disks
only) .
lOX -- dduu:

data overrun at block xxx (decimal) xxx (octal)

Explanation: IE.DAO error code returned to lOX (data overrun).
The record size given was greater than the record size read.
This error occurs on tape devices only.
USler Action:
lOX -- dduu:

None.

device type not specified - defaulting to 'DISK'

Explanation: This message tells you that you are adding a device
to your test configuration with the CONFIGURE command and that
lOX is configuring that device as a disk by default.
USler Action:
lOX -- dduu:

None.

did not respond - unit now deselected

Explanation: The unit did not respond to the lOX command within
1 minute. The device may have been accidentally put off line or
a -tape drive may have lost its column vacuum.
USler Action:

Check the device.

4-69

THE I/O EXERCISER (lOX)
lOX -- TTuu:

does not support the LOOPBACK command

Explanation: LOOPBACK cannot be used with the selected terminal
line.
This is because of insufficient support in the terminal
driver (LOOPBACK is supported only with the full-duplex terminal
driver) or because typeahead is disabled.
User Action:
typeahead.
lOX -- dduu:

For full-duplex

driver

systems,

enable

does not support the x command

Explanation: The x command
specification, dduu:.
User Action:
lOX -- dduu:

terminal

incompatible

with

the

device

None.

duplicate block number

Explanation: The block number you entered with the BADBLOCKS
command is already in the bad blocks list for the device.
User Action:
lOX -- dduu:

None.

end of tape detected - unit now deselected

Explanation: IO.EOT error code returned to lOX (end-of-tape
detected).
lOX attempted to write a record past the end-qf-tape
marker.
User Action:
lOX -- dduu:

This is an informational message only.

error threshold exceeded - unit now deselected

Explanation: The number of
command has been exceeded.
User Action:
IOX -- dduu:

errors

set

with

the

ERRORLIMIT

None.

error while reading horne block

Explanation: When VOLUMECHECK is enabled, this message occurs if
lOX detects an error while attempting to read the horne block of a
Files-II device.
User Action: The disk you selected may be defective. If you are
testing a scratch disk, select the disk again with VOLUMECHECK
NO.
lOX -- dduu:

failed to attach

Explanation:

lOX could not attach the unit.

User Action: The device may be mounted or attached by someone
else. Make sure you have allocated and mounted the device.
For RSXIIM-PLUS systems, mount devices with the /FOREIGN switch.

4-70

THE I/O EXERCISER (lOX)
lOX -- dduu:

failed to detach

Explanation: An error occurred while lOX was
detach a unit that it had.previously attached.
User Action:
lOX -- dduu:

None.

attempting

This is a possible operating system problem.

failed to open temporary file

Explanation: lOX could not find enough free blocks on the disk
to open a temporary file as large as the one you specified with
the TEMPORARYFILE command.
User Action: Specify a smaller temporary file size either by
resetting the default with the TEMPORARYFILE command or by using
TEMPORARYFILE within the FILESII command line to override the
default TEMPORARYFILE size for each device.
If you are using the default (500 blocks) when lOX generates this
message, you need to make room on the disk.
lOX -- dduu:

fatal hardware error - unit now deselected

Explanation:
error) .

IE.FHE error code returned to lOX

User Action:

Check the hardware.

lOX -- dduu:

hardware

illegal density

Ex:planation: The density that you specified
command, for the magnetic tape is illegal.
User Action: Reenter the command, using a
Se!ction 4.12.
lOX -- dduu:

(fatal

with

legal

the

DENSITY

density.

illegal range

ElI:planation: The range of blocks which you specified on
de!vice to be tested with the RANGE command is out of bounds.
USler Action: Use RANGE with no qualifier to check the
range on the device; then specify a range within bounds.
lOX -- dduu:

See

the

default

invalid block number

ElI:planation: The block number that you entered
wi th
the
BADBLOCKS command was not a valid block number for the device.
U~ser

Action:

lOX -- dduu:

None.

I/O is unsatisfied at timeout - function:

xxxx

Explanation: When lOX finishes processing, it waits 5 seconds
f()r I/O to stop. If a long tape has not finished rewinding, this
mE~ssage may occur.
The function that timed out is xxxx.
Uner Action:

None.

4-71

THE I/O EXERCISER (lOX)
lOX -- dduu:

I/O request aborted - unit now deselected

Explanation:
aborted) .

IE.ABO

User Action:

None.

lOX -- dduu:

error

code

returned

(operation

lOX

is already configured

Explanation: You tried to configure with the CONFIGURE command a
unit that is already in the test configuration.
User Action: Use the CONFIGURE command as a display
check which devices are configured.
lOX -- dduu:

You tried to select a unit that

has

already
to

User Action: Use
the
PARAMETERLIST
command
information on all units that are selected.
is logged in

A user is logged in on the terminal selected.

User Action:

Select a terminal line that is not in use.

is not configured

Explanation: You issued
configured devices.
User Action:
lOX -- dduu:

been

display

Explanation:

lOX -- dduu:

is already selected

Explanation:
selected.

lOX -- TTuu:

command

that

valid

only

for

Use the CONFIGURE command to configure the device.

is not mounted or allocated for NFS operations

Explanation: You have selected a device for testing with SELECT
or VERIFY that is not properly allocated and mounted for NFS
testing.
User Action:

Allocate and mount the device.

For RBXlIM ... PLUS systems, mount
switch.
lOX -- dduu:

devices

with

the

/FOREIGN

is not ready - unit now deselected

Explanation:
ready) .

IE.DNR error

code

User Action:

Select the device again.

4-72

returned

lOX

(device

not

THE I/O EXERCISER (lOX)
lOX -- dduu:

is not selected

Explanation: You issued a device-dependent parameter command
(BADBLOCKS or RANGE) that is valid only after you have selected
the device.
User Action:
lOX -- dduu:

Select the device; then reenter the command.

is offline

Explanation: IE.OFL error code returned to lOX (device off
line).
The device was taken off line while testing was in
progress, or you tried to select a device that was off line.
If
tE~sting was in progress on the device when it was taken off line,
lOX appends
unit now deselected" to the error message.
II

User Action:
lOX -- dduu:

Ensure that the device is on line.

is write locked - unit now deselected

E~{planation:

error).

IE. WLK error code returned
The device is write-locked.

lOX

(write-lock

Uf;er Action: Check the device write-lock/write-enable switch and
the MCR write-lock status.
lOX -- dduu:

LUN assignment failure

E~!tplanation:
This probably means that the device, ddnn:, is not
physically present in your system.
It may also mean that you
have exceeded the number of devices that lOX can support.
The
d~~fault is 28 devices; the maximum number of devices is 246.

Ulser Action: I f the device is not physically present in your
system then take no action.
If you have exceeded the number of
d~~vices that lOX can support, then edit the Task Builder
command
file, IOXBLD.CMD (see Section 4.11), to allow lOX to support more
d~~vices •
lOX -- dduu:

privilege violation - unit now deselected

E:l[planation: IE.PRI error code returned to lOX
(privilege
violation) .
The device was not allocated or it was mounted by
someone else.
Ul:;er Action:
lOX -- dduu:

Check the ownership of the device.

specified device type is inconsistent

E:lCplanation: You tried to configure device "dduu as a tape when
a "dd" device had already been configured as a disk. The same
holds true if "dd" had already been configured as a tape and you
tried to configure another "dd" device as a disk.
II

U:ser Action: Use the CONFIGURE command as a display command to
check on the devices in your test configuration. Configure the
unit using a different device mnemonic.

4-73

THE I/O EXERCISER (lOX)
lOX -- dduu:

unexpected error #xx

Explanation: lOX received an I/O error code that
process. The error code is xx (octal).
User Action:
lOX -- dduu:

could

not

None.

unexpected request to queue I/O - request aborted

Explanation: lOX received an AST from
deselected the device.
User Action:
lOX -- dduu:

device

after

had

Check the device.

unrecoverable error at block xxx (decimal) xxx (octal)

Explanation: IE.VER error code returned to lOX (unrecoverable
error). This code indicates an unrecoverable error.
User Action:
lOX -- dduu:

Check the device and media.

VOLUMECHECK failure.

Unit contains a home block

Explanation: The unit is file-structured because the device
contains a home block. This error message is generated by select
if you try to select a Files-II volume while VOLUMECHECK is
enabled.
User Action: lOX destroys information on devices that you select
for exercising with the SELECT command.
If you want to destroy
the contents of the disk, disable VOLUMECHECK (VOLUMECHECK NO)
and select the device again.
lOX -- dduu:

write check error at block xxx (decimal) xxx (octal)

Explanation: IE.WCK error code returned to lOX (write
error). The write check operation failed at block xxx.
User Action:

4.13.2

check

None.

Error Messages Without Device Specifications

These error messages are presented in alphabetical order by the
letter following the lOX task name.

first

lOX -- Indirect command file syntax error
Explanation:

There is an error in the indirect command file.

User Action:

Check the indirect command file.

lOX -- Indirect command file nesting level exceeded
Explanation: lOX accepts indirect command files
level of nesting.

with

only

one

User Action: Rewrite the indirect command file so that
not have more than one level of nesting.

does

4-74

THE I/O EXERCISER (lOX)
lOX -- Aborting due to user command
E:xplanation:

You aborted lOX by using the MCR ABORT command.

User Action:

Reinvoke lOX if you want to continue testing.

lOX -- EXECUTE command is not supported
E:xplanation: You attempted to use the EXECUTE
system that does not support task spawning.
U:ser Action: Do another SYSGEN if you
command to properly test your I/O devices.

command

require

the

EXECUTE

tried

lOX -- Command input I/O error
Explanation: lOX detected an error when it
command that you typed at the terminal.
User Action:

read

the

Reenter the command.

lOX - Command valid only in Command Mode
E.xplanation: You tried to enter a command that cannot be entered
while an I/O exercise is in progress.
User Action: Either abort the exercise and enter the command
wait until the exercise has finished to enter the command.

lOX -- Command valid only in Interactive Mode
Explanation: You tried to enter a command that cannot be entered
unless lOX is running.
User Action:

Type START; then reenter the command.

lOX -- Command not unique
Explanation: The command abbreviation that you entered
distinguish it from another command.
User Action:

did

not

Reenter the command by using a longer abbreviation.

lOX -- Failed to close log file.

F.ERR=-x

Explanation: lOX could not close the log file in your directory.
The FCS error returned was "-x".
User Action: Look up the I/O error code returned to lOX by FCS
in the RSX-llM/M-PLUS and Micro/RSX I/O Operations Reference
~anual and take the appropriate action.
lOX -- Failed to open indirect command file
Explanation: The FCS GCML routine failed to
command file.

open

the

indirect

User Action: Check to see that the file exists and that
specified the file correctly; then resubmit the file to lOX.
4-75

you

THE I/O EXERCISER (lOX)
lOX -- Failed to open log file.

F.ERR=-x

Explanation: lOX could not open the log
returned was "-x".

file.

User Action: The disk may be write protected
enough blocks.
lOX -- Failed to open existing log file.

The

FCS

error

may

not

have

F.ERR=-x

Explanation: lOX could not open a log file that already
in your directory. The FCS error returned was "-x".

exists

User Action: Look up the I/O error code returned to lOX by FCS
in the RSX-IIM/M-PLUS and Micro/RSX I/O Operations Reference
Manual and take the appropriate action.
lOX -- Failed to truncate/close log file.

F.ERR=-x

Explanation: lOX could not truncate or close the log file.
FCS error returned was "-x".

The

User Action: Look up the I/O error code returned to lOX by FCS
in the RSX-IIM/M-PLUS and Micro/RSX I/O Operations Reference
Manual and take the appropriate action.
lOX -- Fatal file system error.

F.ERR= xxx PC+2= xxx

Explanation: lOX exited because an error occurred while rox was
trying to issue a read or write. F.ERR is the octal error code
in the File Descriptor Block indicating the kind of file error.
PC+2 is the octal location of the failure in the lOX code.
User Action: Look up the I/O error code returned to lOX by FCS
in the RSX-IIM/M-PLUS and Micro/RSX I/O Operations Reference
Manual and take the appropriate action.
lOX -- Fatal system error.

DSW= xxx PC+2= xxx

Explanation: lOX immediately exits because a directive that lOX
issued failed.
DSW is the Directive Status word in octal. PC+2
is the octal location of the failure in the lOX code.
User Action: Look up the I/O error code returned to lOX by FCS
in the RSX-IIM/M-PLUS and Micro/RSX Executive Reference Manual
and take the appropriate action.
IOX -- Invalid pattern number
Explanation: You tried to set a data pattern using a pattern
number greater than 12. The valid arguments for PATTERN are 0
through 12.
User Action:

Enter a valid pattern number.

4-76

THE I/O EXERCISER (lOX)
lOX -- Invalid task name
Explanation: The task name that you specified with the EXECUTE
command is invalid.
The task name is either incorrect or the
task does not exist.
User Action:
task exists.

Reenter the task name correctly or determine if the

lOX -- No activity remains - aborting
Ex.planation: In Execution Mode, lOX determines whether or not
any exercises are in progress or any tasks are executing at one
minute intervals. If lOX finds no activity,
it aborts the
ex.ercise and generates this informational message.
In Interactive Mode, lOX determines whether or not any exercises
are in progress or any tasks are executing only when you enter
the PROCEED command. If there is no activity when you enter
PROCEED,
lOX aborts the exercise and issues this informational
me!ssage.
Us,er Action:

None.

lOX -- No activity to start
ElIi:planation: When you issued the START command, no devices were
se!lected for testing and no tasks were initiated for execution.
Us;er Action: Select devices that you want to test, and use
EXECUTE command to initiate tasks that you want to execute.

the

lOX -- No buffer space available
EJI:planation: lOX does not have adequate
accommodate all the devices you selected.

buffer

space

Us:er Action: Either deselect some devices from
rednstall or reinvoke lOX with a greater increment.

testing

lOX -- No such command - type H for help
El:planation:

You entered a command that lOX did not recognize.

Us:er Action: Type H (abbreviation for the HELP
di.splays a summary all lOX commands.

command) ,

which

lOX -- No tasks to abort
ElI:planation: You tried to abort tasks using the ABORT
when no tasks had been initiated by the EXECUTE command.
Uf:ler Action:

None.

4-77

command

THE I/O EXERCISER (lOX)
lOX -- Only CTRL/C allowed
Explanation: You set CONTROL C YES to enable you to enter lOX
commands while exercises are in progress. Therefore, lOX only
accepts CTRL/C in Execution Mode.
User Action: Enter CTRL/C to exit Execution Mode, then lOX is in
Interactive Mode and you can enter commands.
lOX -- Syntax error
Explanation: The command
syntax error.

line

that

you

entered

contained

User Action: If necessary, check the syntax of the command
that you entered. See Section 4.12 or type H (for HELP).

line

lOX -- Task never executed
Explanation: The task that you tried to abort is not on the list
of tasks initiated by the EXECUTE command.
User Action: Use the PARAMETERLIST command to check the list
tasks to be executed.

lOX -- Task "xxxxxx" is currently active
Explanation: You tried to execute a task
active. The name of the task is "xxxxxx".
User Action:
lOX -- Task

that

was

already

None.

"XXXXXX"

is completed.

Status= nnnnnnn

Explanation: The task has completed execution. The name of the
task is "xxxxxx".
There are four task statuses represented by
"nnnnnnn": SUCCESS, WARNING, ERROR, and SEVERE ERROR.
User Action:

None.

lOX -- Task "xxxxxx" is not installed
Explanation: Task "xxxxxx" is not
initiated using the EXECUTE command.
User Action:
lOX -- Task

installed

and

cannot

Install the task from a privileged terminal.

"XXXXXX"

is unable to execute

Explanation:

Task "xxxxxx" could not execute.

User Action:

Try to execute the task again.

4-78

THE I/O EXERCISER (lOX)
lOX -- Units are selected - command ignored
Explanation: The BUFFERSIZE command is valid only
are selected for testing.

units

User Action: You can use the BUFFERSIZE command within the
SELECT and VERIFY command lines to override the default for each
device. However, if you require a larger buffer size for all
devices, use the DESELECT command to deselect all units; then
reissue the BUFFERSIZE command.

4-79

CHAPTER 5
THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)

The Bad

Block Replacement Control Task (RCT) handles bad block
and recovery on Mass Storage Control Protocol (MSCP) disks
such as; the RASO.
Bad block handling on MSCP disks consists of four
stages:

replacE~ment

Detecting

Notifying

Replacing

Revectoring

The dis;k controller (UDA50) handles the detection of bad blocks and
notification of the driver (DUDRV).
The driver activates RCT. RCT
performs all the bad block replacement functions that enable the
controller to revector (redirect)
I/O from the bad block to the
replacement block.
RCT also performs replacement and recovery on MSCP disks that went off
line during bad block replacement or before the contents of a
write-back cache were copied to the disk.

5.1

B}~

BLOCK REPLACEMENT FUNCTIONS

RCT performs the following bad block replacement functions:

5.2

•

Stores data from the bad block

•

Allocates a replacement block

•

Updates data structures on the disk

•

Initializes the replacement block

RECOVERY TECHNIQUES

RCT ChE!cks MSCP disks that have just corne on line for two conditions:
incomplete bad block replacement, and write-back cache corruption.
If
RCT de1:ermines that bad block replacement was partially completed when
the disk went off line, RCT completes the bad block replacement
process. If RCT determines that the write-back cache was not copied
to thE! disk before the disk went off line, RCT software write-locks
the disk so that the contents of the write-back cache are preserved.

5-1

THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)
5.3

INSTALLING RCT

If you select a DU: device in SYSGEN, RCT...
and DUDRV are both
built.
RCT...
is installed and DUDRV is loaded in S~SVMR.CMD. You
load or install and load RCT ... and DUDRV only if:
•

You have removed RCT ...

and/or unloaded DUDRV.

•

You have edited SYSVMR.CMD to exclude one or both.

If you manually install RCT ... and load DUDRV, you must first install
RCT....
Otherwise, you receive a message at the console terminal,
indicating that the Replacement 'Control Task is not installed.
To install RCT, use the following command line:
:> I N ~,

5.4

r: T / T A S I< :::: F~' CT. ; .,

DISK CONFIGURATION OF MSCP DISKS

Three address spaces on MSCP disks are relevant to RCT:
•

Logical blocks (LBNs)

•

Replacement blocks (RBNs)

•

Revector control tables

5.4.1

Logical Blocks (LBNs)

Logical blocks (LBNs) are accessible to user tasks for transferring
data between the disk and the operating system. When the controller
encounters a bad LBN and notifies DUDRV, DUDRV activates RCT to
replace the LBN.

5.4.2

Replacement Blocks (RBNs)

Replacement blocks (RBNs) are blocks reserved throughout the disk that
RCT allocates as substitutes for bad LBNs. RBNs cannot be directly
accessed by user tasks during normal data transfers.

5.4.3

Revector Control Tables

The rev ector control tables are accessible only by RCT (by way of
DUDRV) and the device controller. Each table entry corresponds to an
RBN according to its location in the table. An entry contains the LBN
being replaced and a code describing the status of the RBN. There are
five status codes:
•

ALLOCATED - The RBN is currently being used.

•

UNALLOCATED - The RBN is not being used.

•

UNUSABLE - The RBN cannot be used.

5-2

THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)
•

PRIMARY - The first RBN read when a bad block is replaced.

•

SECONDARY - The RBN read after the primary blocks are read.

For a g'iven LBN, a primary RBN is in a predetermined location, such as
the last sector of the same track as the LBN. For that LBN, all other
RBNs are secondary.
Sector 0 of the rev ector control tables stores information in a flag
word that enables RCT to determine if recovery techniques are required
when a disk is brought on line.

5 .5

BA.D BLOCK HANDLING ON MSCP DISKS

Bad block handling on MSCP disks consists of four stages:
•

Detection performed by the device controller, UDA50

•

Notification performed by the
driver, DUDRV

•

Replacement performed by RCT

•

Revectoring performed dynamically by the device controller

5.5.1

controller

that

notifies

the

Bad Block Detection

The UDA50 controller may detect a bad
request from the driver.

5.5.2

LBN

while

processing

I/O

Bad Block Notification

When the UDA50 controller detects a bad
listing the bad LBN in an end packet.
in pool and activates RCT.

LBN,
it notifies DUDRV by
DUDRV stores this information

DUDRV provides RCT with the information necessary to perform bad block
replacement:
•

LBN

•

I/O packet address

•

Unit Control Block (UCB) address

5.5.3

lBad Block Replacement

RCT performs the following steps in bad block replacement:
1.

Emulates an ATTACH to the disk, inhibiting all I/O other than
I/O necessary for bad block replacement.

Reads the data from the bad LBN into a
space.

5-3

buffer

its

data

THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)
3.

Determines which RBN on
predetermined algorithm.

the' disk

use

applying

Issues OIOs to DUDRV that update the revector control
(discussed in Section 5.4.3).

Updates the header and data of the bad LBN by issuing an
IO.RPL
to DUDRV.
This I/O function code directs the
controller to indicate in the header of the LBN that the LBN
has been replaced either by a primary or secondary RBN and
writes 128 copies of the address of the RBN in the data field
of the LBN.

Initializes the RBN by writing the data read from the LBN
back to the bad LBN. Because the bad LBN has been replaced
by the RBN, the data is written transparently to the RBN by
the controller.

tables

If an RBN is bad, RCT treats it as a bad LBN.
RCT finds
another RBN,
updates the revector control tables, marks the
old RBN as unusable, and initializes the new RBN by writing
the stored data back to the bad LBN.
7.

5.5.4

RCT detaches the unit, and normal I/O to the disk resumes.

Bad Block Revectoring

Revectoring is performed dynamically by the device controller.
When
the controller first accesses an LBN that has been replaced by RCT,
the controller revectors (redirects) the I/O to the RBN that RCT
designated as the replacement for the LBN. Thereafter, I/O to the bad
LBN is revectored transparently to the RBN without DUDRV activating
RCT.

5.5.4.1 Primary RBNs - When the controller detects a bad LBN whose
header indicates that it has been replaced by a primary RBN, the
controller directly accesses the RBN.

5.5.4.2 Secondary RBNs - When the controller detects a bad LBN whose
header indicates that it has been replaced by a secondary RBN, the
controller must look up the address of the RBN before it can access
the RBN. The controller finds the address of the secondary RBN in one
of two ways:

5.6

Checking the data field of the bad LBN,
128 copies of the RBN

which

contains

the

Checking the rev ector control tables for the entry containing
the bad LBN

COMPLETING PARTIAL BAD BLOCK REPLACEMENTS

When a disk unit is brought on line, RCT checks that no bad block
replacement was in progress when the disk went off line by checking
the flag word in sector 0 of the revector control table.
If
replacement needs to be completed, RCT completes the bad block
replacement.

5-4

THE BAD BLOCK REPLACEMENT CONTROL TASK (RCT)
5.7

PREVENTING LOSS OF WRITE-BACK CACHE DATA

RCT prevents loss of write-back cache data.
A disk with the write-back-cache-in-use flag set will be write-locked
each time it is brought on line. To write-enable such a disk, use the
/WRITE qualifier with the MCR MOUNT command each time you mount the
disk. RCT checks the write-back-cache-in-use flag word in sector 0 of
the revector control tables, software write-locks the disk if the flag
is set, and writes the following TKTN message to the console output
device (CO:):
ddnn: -- Write back caching data lost.
where ddnn:

Unit write locked

is the disk that RCT has write locked.
NOTE

Because RSX-llM and RSX-llM-PLUS operating systems do
not
support disks with write-back caching, this
function is extremely rare.
RCT performs this function only under the following circumstances:

5.8

A disk with a write-back cache failed to copy the data from
the write-back cache to the disk before going off line, while
on another operating system (that
supports
write-back
caching), and was then moved to an RSX-llM or RSX-llM-PLUS
operating system.

The revector control tables have been altered such
write-back-cache-in-use flag is set.

that

the

ReT AND OTHER RSXIIM AND RSX-IIM-PLUS UTILITIES

Utilities such as BAD, BRU, and INI treat
MSCP
devices
as
non-last-track devices.
RCT does not replace the BAD utility. You
must run BAD on MSCP devices to create a bad block descriptor file
before you initialize the disk. You can use BAD to find bad blocks
and list them in a bad block descriptor file. However, the bad block
descriptor file will not contain any information about blocks detected
by the device controller and replaced by RCT.

5.9

ReT AND THE ERROR LOGGER

DUDRV notifies the Error Logger with an error log packet whenever an
error has been detected that requires bad block replacement. RCT also
generat:es an error log packet indicating that a bad LBN has been
successfully (or unsuccessfully) replaced by an RBN. RCT logs the
packet under the name of the task that issued the QIO resulting in the
detection of the bad block by the controller.

5-5

CHAPTER 6
RESOURCE MONITORING DISPLAY (RHD)

The Resource Monitoring Display .(RMD) is a privileged task that
displays information about the resources in your system.
This
information includes the active tasks, their location in memory, the
amount of memory they occupy, and the available pool space. On video
terminaLls such as VT52s, VT100-series, VT200-series, and Professional
series
terminals,
RMD provides dynamic displays.
On hardcopy
terminals such as LA180s, RMD provides "snapshot" displays.
RMD
alters the display format according to terminal type without your
having to set switches or rebuild the task.

6.1

INTRODUCTION

RMD consists of "pages". A page consists of 24 lines, which, on CRT
termina.ls, is one screen. The program contains two kinds of pages:
display pages and setup pages.

6.1.1

Display Pages

There are four display
RSX-lltJl-PLUS systems:

pages

•

Memory (M)

•

Active Task List (A)

•

Task Header (T)

•

Help (H)

available

There are four additional display pages that.
RSX ....IlN-PLUS ~nd Micro/RSX systems.:

both

are

available

•

I/O Counts (I)

•

System Statistics (S)

•

General Statistics about a Cache Region (c)

•

DetailedStat.istics about a cached Device (D)

RSX-IIM

only

and

You pre!ss the terminal keys indicated in parentheses to switch display
pages.

6-1

RESOURCE MONITORING DISPLAY (RHD)
6.1.2

Setup Pages

There are five setup pages. Each setup page is associated with a
display page.
(The Help Display Page has no associated setup page.)
You access a setup page from a display page by pressing the ESCAPE key
on your terminal. The setup page documents and prompts you for setup
commands, which alter the content of the information displayed on the
associated display page.

6.2

INSTALLING AND INVOKING RHD

Individual users can invoke RMD at their terminals. For large systems
that support many terminals, you may want to run RMD continuously on a
slaved terminal near the computer. You use different procedures to
install and invoke RMD for use by individual users and to run RMD on a
slaved terminal.

6.2.1

Using RHD at Individual Terminals

On RSX-llM systems, RMD is available if you
generation.

selected

RMD

system

On RSX-l1 M-PLUS, RHD is always available.

6.2.1.1 Installing RHD at Individual Terminals - You must install RMD
in order for non-privileged users to use it. Privileged users can
simply use the MCR RUN command to run $RMD. To install RMD, use the
MCR INSTALL command at a privileged terminal:

6.2.1.2 Invoking RHD at Individual Terminals - From any terminal, you
invoke an installed copy of RMD from MCR as follows:
:> F' d fI

[F' d ~? f::I ] [' , ~:; ~::! t I, I P (' 0 ITI m<:~ n d '" ~I

•

where:
page
One of the display page abbreviations (M, A, T, or H).
(There
are also I, S, C, and D pages for RSX-IIM-PLUS users.) The
default page is the Memory Display (M).
setupcommands
A valid setup command for the display page that you have
selected.
The setup commands are the same as those available to
you from the setup page associated with the display page you
specified.
The default setup commands are discussed in Sections
6.4 through 6.6, which describe the content of each display page
and how you use setup commands to alter display parameters.
From a privileged terminal only, you can invoke an uninstalled copy of
RMD using the MCR RUN command. However, MCR command line parsing is
available only if RHD is installed.

6-2

RESOURCE MONITORING DISPLAY (RMD)
6.2.2

Running RMD on a Slaved Terminal

To run RMD on a slaved terminal and also allow users to invoke RMD at
their own terminals, RMD must be installed twice using different task
image files and different task names.
OnRSX-llM syst..ms, if you selectedRMD a,t .,yst.emgeneration, you will
find. RHD.TSK (wbicbhas been task built at syst._g~n1eratloriwith task
name .... RHD) in SYSUIC on your syst.em disk.
On RSX-1IM.... PLUS systems, you will find RMD.TSK (which has been task
built at system generation with task name ••• RMD) In SYSUIC on your
system disk.
RMD.TSK is the copy of RMD that the system installs for individual
users to invoke. LUNs 1 and 2 in this task image have been assigned
to TI: so that a user at any terminal can invoke RMD.
To run RMD on a slaved terminal, do the following:
1.

From a privileged terminal, make a copy of RMD.TSK in SYSUIC
on your system disk named RMDEMO.TSK.
If your SYSUIC is
[l,54J and your system disk is DRO:, use the following
command sequence:
>~~FT

IflFF::::[ 1., 54J

>t)SN DRO:~::SY:
>PTP RMDFMO.TSK=RMD.TSK
2. From a privileged terminal or from a command file to be executed
at a privileged terminal, install RMDEMO using the following command
sequence:

>INS RMDEMO/TASK=RMDfMO
)RFA RMDEMO 1 ttnn:
>REA RMDFMO 2 ttnn:
)8[T ISLAVF=ttnn:
:: F:UN Ri'1f1F riO

where ttnn:

is the terminal at which you want to run RMDEMO.

This command sequence installs RMD with task name RMDEMO,
reassigns LUNs 1 and 2 to the terminal you want to slave to
the task, slaves the terminal; and invokes the task.
Because the REASSIGN command alters the task image on disk,
you must use two task images rather than simply installing
RMD twice with different task names.

6.3

THE HELP DISPLAY

The Help Display documents how you switch display pages.
display pages by pressing a terminal key as follows:

You

switch

Explanation
~l
p~

'1'

1:
S
C

Accesses the Memory Display
Accesses the Active Task Display
Accesses the Task Header Display
Accesses the I/O Counts Display
Accesses the System Statistics Display
Accesses the General Statistics about a Cache Region
Accesses the Detailed Statistics about a Cached Device

6-3

RESOURCE MONITORING DISPLAY (RHD)
The Help Display also documents how to exit from RMD and use the
ESCAPE key to access setup pages from their associated display pages.
(Because there is nothing to alter on the Help Display, no setup page
is available from the Help Display.)
The Memory, Active Task, and Task Header Displays use the entire
screen. Therefore, you receive no prompts or documentation on display
pages. To find out how to access a setup page from a display page or
how to switch display pages, press the H key (for Help) to access the
Help Display.

6.4

THE MEMORY DISPLAY

The Memory Display graphically represents the entire system memory,
including the approximate size and locations of partitions and active
tasks. The display also shows pool statistics, the name of the task
that is currently executing, and other information about the status of
your operating system. You access the Memory Display from another
display page by pressing the M key (for Memory). To access the Memory
Display from the MCR command line, you type the following:
'> F: r·i (I M

If you invoke RMD without specifying a display page:

RMD defaults to the Memory Display.
Figures 6-1 and 6-2 show "snapshots" of the Memory Display for RSX-IIM
and RSX-IIM-PLUS respectively.
The reverse numbers in each figure
(white numbers in black circles) match the reverse numbers in the
explanations that follow the two figures. Where a display field is
the same for both RSX-IIM and RSX-IIM-PLUS, it is designated by the
same reverse number in Figures 6-1 and 6-2. The matching explanation,
however, appears only once .

•

,....--_ _ _ _ _
A _ _ _-

....
"

RSX-llM V4.2 Bl37
*IDlE*

(SYDNEY>

CD TASK:::;

G POOl=5770. : 5980. : 15.
5770.:5980.:15.

IN:
9
68K
OUr:

512K

~FREE:::;

EET DD P • F £I OlC
XXT Bl M • 1 B MPO
CC: :: T • 1 F GOT
00
R A C ••
MM
M C P ••
12
£I P
••

•
B
R
U

SYO:37189.
DBO:DMO

•

23-APR-85 14:37:43
DB1: 114469.
DB2:143206.
PARS
EXCOM1:C
EXCOM2:C
TTPAR : T
SYSPAR:T
TKNPAR:T
I'RVPAR:D
LDRPAR:T
BASIC2:C
GEN
:D

> (->->-»»------->
~~:.~~~;~~~~~i.~~~~~~~~~~~:~~~~~~~::~~~~~~:~~~~~~~:::~~~~~::~!~~~~t
! !=»)

.--------------------.~----------------.-----------.--.-.---- .... --C-.--.-- ( CI)

RMSRES:C

256*****288*****320*****352*****384*****416*****448*****480*****'

e ERRSEG
8.
ZK-4182-85

Figure 6-1

RSX-I1M Memory Display

6-4

RESOURCE MONITORING DISPLAY (RMD)

•

• ••

,....
- _ _ _ _ _ _A ....._ - - . .
....

RSX·-UM-PLUS V:3.0
HIS/(= *IDL.E:*

BL21B* (CASTOR)
• FREE::::

•

15361\ UP 000:03:20 23-APR-9S 14:40:44
9Y0t16919.
Il91:D"0
PARS
DBO:OFL
DB2:0FL
. . F'Om.,==172B. :2456. :67.
• SECF'ODL::::3378 + : 4096. : 92%
1728. ::~456. :67.
3:~79. : 4096. : 92%
CPUF'AR
SYSPAR
SECPOL
, :rN: D
FFt1RR. EHLRTBRE:.R • NN P ES [I. FAA H S}
. 29 r I\T
ECIMMM.DAPMTAMVM • TT 0 DE A.ATT A E
GEN
••.•.. 211 R. 'fe. •
XS1GI)H. TIOD3F'SCS ••• 0 -rN P.L •• l. 0
..
OUT 1 NO
DRA.EAPTR TI1R.L E EX L H. RS$RT
•
{ o
1 M
IEe.MeI2E 6 E.B D F'P • 2. EE$06
•
OK "
VSP.OPP5e 1 S.B T HT. • SA$ 2 ••
•

rr}

l=tJ!

++!+»>+>!»»!)!--+!I=='>->!!++»<><>

~:::~~~:~~~~~~~~~~~~~!~~~~~~!~~~~~~~~~~~~~~!~~~~~~~~~~~~~~~~~~~~l

.."......__._ ••._._____...... _ .•.._•• _"_. __"_.. _~_._ ._.____ - ____._. __ ,_, ._-_._---____._0._____ -------- ( I)

768*****864*****960*****1056****1152****1249****1344****1440****'

<~i
()

I-

ZK-4183-85

Figure 6-2

RSX-llM-PLUS Memory Display

Operating system type, version number, and base level.

•

Six-character name that is a DECnet node name (if DECnet is
running on your system) or the system name that you selected in
SYSGEN (if DECnet is not running on your system).

•

Size in K words of the system memory.

e
o

For RSX-lIM-PLUS systems, time elapsed in units of days,
and minutes, since the system was last bootstrapped.

hours,

Current date and time.

Na.me of the task that is currently executing or,
if
executing, *IDLE* (Executive executing the idle loop).

Number of free blocks on the first four Files-ll devices in your
system.
If a device is dismounted, RMD displays:
"DMO".
If a
d~~vice is off line, RMD displays:
"OFL" .
Magnetic tapes can
also be displayed, but only if previously selected from the I
SE~tup page.

Pool (dynamic storage region) information in the format:

none

POOL=X:Y:Z
where:
X

Number of words in the largest free block in pool

Number of free words in pool

Number of fragments in the pool free list

~le second line records the worst case of pool since you
invoked
ID1D.
This line is most useful if RMD has been running on a
slaved terminal since the system was last booted.

6-5

RESOURCE MONITORING DISPLAY (RMD)

On RSX-llM-PLUS systems,
following format:

secondary

pool

information

the

SECPOOL==A:B:C'
where:
A

Numbe.r of free blocks in secondary pool

Total number of blocks in secondary pool

Percentage of secondary pool that is free

The second line records the worst case of secondary pool since
you invoked RMD.
This line is most useful if RHD has been
running on a slaved terminal since the system
was
last
bootstrapped.

Partitions in the system using the followin9 format:
partitionnarne:type
where:
type
Por RSX-llM systems (Fi9ure 6-1), one of the following:
T
S
D
C

TC!l$kpartit,ion
SubpC!lrtition
System.... controlled (dynamic) partition
Commonpartition

For RSX-llM-PLUS systems (Figure 6-2), one of the followin9:
D
P

System-controlled (dynamic) partition
Secondary pool partition

Number of tasks in memory and amount of memory they use, and
number of active tasks swapped or checkpointed out of memory and
the amount of memory they would require.

Name of each task, cornmon, or driver in memory and its location
in memory using the following symbols to designate size, type
(task, cornmon, or driver), and other attributes:
Symbol
<

[

]

Attribute
Active task
Task not active, yet occupies memory
Named cornmon
Unnamed common (displayed name is first
task)
Loaded driver using device mnemonic
Task not fixed in memory
Task fixed in memory

attached

The hyphens and equal signs represent the approximate amount of
memory that each task, driver, or cornmon occupies. Where the
display shows only one delimiter and no hyphens or equal signs,
the open delimiter is in the same location as the closing
delimiter of the preceding task.

6-6

RESOURCE MONITORING DISPLAY (RHD)

Partition size and location. The beginning of each partition is
marked with the same symbols as those listed previously plus the
following additions for both operating systems:
E
P

Executive
Pool

The lines of asterisks are approxi~ate representations of the
amount of memory occupied by each partition. The numbers are in
lK word increments. Each numerical character also represents the
same amount of memory as an asterisk. RMD always divides the
system memory into groups of eight units.

System error count sequence recorded by the Error Logger
zero if Error Logger not present in your system).

6.4.1

(always

Altering the Memory Display from the Setup Page

To altE~r the Memory Display, you press the ESCAPE key, which accesses
the setup page for the Memory Display. The setup page documents and
prompts you for commands which you use to alter the Memory Display.
You can enter mUltiple commands after each prompt by using commas as
separat~ors.
The setup commands available for altering the Memory
Display are as follows:
•

FREEx=ddnn:, where x is a number from 0 to 3 and ddnn:
device name and number

•

RATE=s, where s is the replot rate in seconds

You can truncate these commands to their shortest unique forms.
These
setup parameters stay in effect until you alter them, even if you
switch to another display page and back to the Memory Display.

6.4.1.1 The FREE Command - You use this command to determine the four
Files-II devices for which you want the Memory Display to show the
available free blocks. This information is (7) in both Figures 6-1
and 6-·2.
The default is your system disk (SY:) and the next three
Files-II devices in your configuration.

6.4.1.2: The RATE Command - You use this command to determine how
often RMD replots the Memory Display if you are running RMD on a CRT.
The default replot rate is once per second.

6.4.2

Altering the Memory Display from the MCR Command Line

You can enter the FREE and RATE commands as part of the MeR command
line.
(The general format of the MeR command line is discussed in
Section 6.2.1.2.) For example, when you enter the MeR command line
~·RMD

M,FRFE3=DMO:,RATE=3

RMD displays the number of free blocks on DMO: instead of the fourth
Files-II device in your configuration and replots the display every 3
seconds instead of every second.

6-7

RESOURCE MONITORING DISPLAY (RMD)
To change the second and third Files-II devices to
respectively, use the following MCR command line:

DBl:

and

DB2:

'These setup parameters stay in effect until you alter them by using
setup commands from the setup page. Even if you switch to another
display page and back to the Memory Display, RMD does not restore the
default setup parameters.
Other display pages allow you to select devices as well.
These
devices are common across all pages. Therefore, if you select Fl=DMO:
for the M page, and then switch to the I page, DMO: will be the first
displayed device, not SY:
(which would be the default).

6.5

THE ACTIVE TASK DISPLAY

The Active Task Display shows you the active tasks in the system. You
access this display from another display page by pressing the A key
(for Active Task). To access this display from the MCR command line,
you type the following:

This display has six fields:
1.

Name of the task

Length of the task in octal bytes

Terminal that issued the task

Running priority of the task

Outstanding I/O count

Status flags

The status flags use the same mnemonics as the MCR ATL command.
See
the RSX-llM/M-PLUS MCR Operations Manual for the definitions of the
status flags.

6.5.1

Altering the Active Task Display from the Setup Page

To alter the Active Task Display, you press the ESCAPE key, which
displays the setup page for the Active Task Display. The setup page
documents and prompts you for commands that you use to alter the
Active Task Display.
You can enter mUltiple commands after each
prompt by using commas as separators. The setup commands available
for altering the Active Task Display are as follows:
•

OWNER=ttnn: - Where ttnn:
task.

is the

terminal

that

issued

the

The OWNER command allows RMD to display only those tasks that
have been issued by a particular terminal. The default is
ALL, which displays tasks issued from all terminals.

6-8

RESOURCE MONITORING DISPLAY (RMD)
•

PRIORITY=p - Where p is a task's running priority.
The active task list may be too long to fit on one screen.
You use the PRIORITY command to determine the highest priority
tasks that you want to see. The default is 250, the highest
possible priority.

•

RATE=s where s is the replot rate in seconds.
The RATE command allows you to determine how often RMD replots
the Active Task Display, if you are ,running RMD on a CRT. The
default replot rate is once per second.

•

TASK=taskname - Where taskname is the name of the
header you want to display.

task

whose

The TASK command allows you to look at a specific task header.
This command is an exception because it is the only setup
command that switches display pages. There is no default for
the TASK command.
The Task Header Display is discussed in
Section 6.6.
You can truncate these commands to their shortest unique forms. These
setup parameters stay in effect until you alter them, even if you
switch to another display page and back to the Active Task Display.

6.5.2

Altering the Active Task Display from the MCR Command Line

You can enter the same setup commands discussed in the previous
section as part of the MCR command line. For example, when you enter
the MCR command line:

RMD displays the Active Task Display using 200 as
priority and replots the display every 3 seconds.
To display
following:

only

those

tasks

issued

your

the

maximum

terminal,

type

task
the

>P 1'10 i;? f)1.LINFR;,:; T I :

6.6

THE TASK HEADER DISPLAY

The Task Header Display shows you the task header of the task you
specify.
You access this display from another display page by
pressing the T key (for Task Header).
If no task is currently
specified, RMD shows you the setup page first so that you can specify
the task whose task header you want RMD to display.
To access the Task Header Display from the MCR command line, you
the following:

type

:rMD T,TASK=taskname

where taskname is the name of the task whose header you
display.

6-9

want

RMD

RESOURCE MONITORING DISPLAY (RMD)
If you invoke RMD from the MCR command
name of a task:

line

without

specifying

the

RMD displays the setup page first so that you can specify the name
-the task whose header you want RMD to display.

'rhe Task Header Display shows you the following information about
specified task:

the

}RMD T

•

Name of the task

•

Name of the partition in which the task runs

•

Status flags, which have the same mnemonics as in
Task display

•

Owner of the task by terminal number

•

Outstanding I/O count

•

Default priority

•

Running priority

•

Swapping priority

•

Length in decimal words

•

Contents of the six general purpose registers,
counter, and the Processor Status Word

•

Contents of the Directive Status Word ($DSW)

•

Local event flags

•

Logical unit number (LUN) assignments to a maximum of 26 LUNs

the

Active

the

program

When RMD displays file names in the list of LUN assignments, the file
name is the name of the file when it was created.
If the file has
been renamed, the RMD display will not reflect the current file name.

6.6.1

Altering the Task Header Display from the Setup Page

To alter the Task Header Display, you press the ESCAPE key, which
displays the setup page for the Task Header Display. The setup page
documents and prompts you for commands that alter the Task Header
Display.
You can enter mUltiple commands after each prompt by using
commas as separators.
The setup commands available for altering the
Task Header Display are as follows:
•

RATE=s - Where s is the replot rate in seconds.
The RATE command allows you to determine how often RMD replots
the Task Header Display if you are running RMD on a CRT. The
default replot rate is once per second.

•

TASK=taskname - Where taskname is the name of the
header you want to display.

6-10

task

whose

RESOURCE MONITORING DISPLAY (RMD)
The TASK command changes the task header to be displayed.
There is no default. The TASK command has the same function
as the TASK command on the Active Task Display, except that
here it does not switch display pages.
You can truncate these commands to their shortest unique forms. These
setup parameters remain in effect until you alter them, even if you
switch to another display page and back to the Task Header Display.

6.6.2

Altering the Task Header Display from the MCR Command Line

Both the RATE and TASK commands are available to you from the MCR
command line. If you invoke RMD using the following command line:

>RMD T,RATE=2,TASK= ••• FDT
RMD displays the Task Header Display for EDT,
replotting the page
every 2 seconds. You must give the full task name.
In this case the
tasknarne is " ... EDT", not "EDT".
If you do not specify a task name in the MCR command line:

>H11D T f RATE::::?,
RMD first displays the setup page so that you can select a task whose
header you want RMD to display. The replot rate will be set to 2
seconds: .

6.7

DISPLAYS AVAILABLE ONLY ON RSX-IIM-PLOS

Four di.splays are available only on RSX-llM-PLUS systems:
the I/O
Counts Display, the System Statistics Display, the General statistics
about a Cache Region Display, and the Detailed Statistics for a Cached
Device Display. These displays are invoked by the commands RMD I, RHD
S, RHD C and RMD D, respectively_

6.7.1

The I/O Counts Display

The I/O Counts display shows you I/O and error logging counts for up
to six error logging devices. Sy default, the first six error logging
disk devices in your hardware configuration are displayed. You access
this display from another display by pressing the I key (for I/O). To
access this display from the MCR command line, you type the following:
>RMfJ I

The I/O Counts Display has 10 fields for each device:
1.

Device name of the displayed device

Total number of I/O requests to the device

Number of I/O requests issued
second

Average number of I/O
second

requests

6-11

the

device

issued

the

last

device

per

RESOURCE MONITORING DISPLAY (RMD)
5.

Average number Qf cylinders crossed per
the last second

I/O

request

Averagenul'ilber Of cylinder$ crossed per I/O request

Number of words transferred during the last second

Averagenum'ber of words transferred per second

Count and lifnit of soft I/O errors

10.

Count and limit of hard I/O errors

during

The I/O Counts display works only on video. terminals.

6. 7 .. 1.1 . Al tering.the 1/0 Counts Display from.. the Setup Page - To
alter the I/O Counts Distlay,'You press the ESCAPE key, .which displays
the setup page . fo~ tne' 1/0 Counts Display. The setup page .•. . lists the
available commands you can use to alter the I/O Counts Display, and
prompts you fora>comman.. You can enter multiple commands after each
prompt by using conunas as separators. The setup commands available
for altering the1/0Couots Display are a.s follows:
•

DIVICEx=ddnn: -Where x is a number from 0 to 6 and ddnn:
an error' 1099in9.·. devi.ce.

The DEVICE command allows you to select which error 10g9ing
devices, are to be displayed. The device specified must be an
error 1099.in9 deVice. you may select magnetic tape devices
from the setup.page.fQr magnetic tape devices, fields 5 and
iare suppressed. If you do not Use the DEVICE'comma.nd to
sp,cify .ad.vic~ordevice:s, the first six error logging disk
de'f'ices in yOllX' hardware configuration are displayed by
default •.... See ~hea$X""'llMIM-PLt1S Irror Loggins Manual fora
list of the error 109ging devices.

•

RATE=s ...... Where·. s is tbereplot rate in seconds ..
Tb.. RA'l'E'dommand, allows. you to determine how often RHD replots

the I/O . . Counts Display, if you are running RMt) on a video
di,play terminal.. The default replot rate is once per second.
You can truncate these commands: to their shorte$t unique forms. These
setup par,mete.rssit,ay '., irieffect .untilyou alter them, even if you
switohto anot1'lex; • di$plal' page and then return to the I/O Counts
Di.play.

6.7.1.2 Alteringth. 110 Counts Display from the Melt Command LineYou 'can entertbeDIVICB and !\ATE commands as part of theMCR command
line .. Forexample,.Whe~· you enter the following command line, RMD
displays 1..10countimformationfor DB3: and replots the display every
2 seconds:

The information . for '. DR3:.. is displayed in the. positi.on . that would
normally . display .. info~ation for the third error logging device in
your hardware configurat.ion.

6-12

RESOURCE MONITORING DISPLAY (RMD)

6-13

RESOURCE MONITORING DISPLAY (RMD)
19.

Average number of running CPU ticks per second

20.

Total number of zero CPU intervals

21.

Number of zero CPU intervals during the last second

22.

Average number of zero CPU intervals per second

23.

Total number of task checkpoints

24.

Number of task checkpoints during the last second

25.

Average number of task checkpoints per second

6.7.2.1 Altering the System Statistics Display from the setup PageYou can alter the replot rate on the System Statistics Display by
pressing the ESCAPE key, which displays the setup page for the System
Statistics Display.
The setup page lists the command format for
altering the replot rate, and prompts you for a command. The command
for altering the replot rate of the System Statistics Display is as
follows:
RATE=s, Where s is the replot rate in seconds.
You can truncate this command to the single letter R.
This setup
parameter stays in effect until you alter it, even if you switch to
another display page and then return to the System Statistics Display.
The default replot rate is once per second.

Altering the System Statistics Display from the MeR Command
Line - You can enter the RATE command as part of the MCR
command line. For example, when you enter the following MCR command
line, RHO replots the System Statistics Display once every 2 seconds:
6.7.2.2

>r~:Mn

S, RATE=-2

This setup parameter stays in effect until you alter it by using the
RATE=s command from the setup page. Even if you switch to another
display page and then return to the System Statistics Display, RHO
does not restore the default replot rate.

6.7.3

The General Statistics About a Cache Region Display

The General Statistics about a Cache Region display (RHO C display)
shows
you general statistics about a particular cache region.
(However, you must have previously established disk data caching
through the MOUNT or SET command to use this display. For more
information on disk data caching, see Chapter 19 of this manual.) You
access this display from another display by pressing the C key (for
Cache Region). To access this display from the MCR command line, you
type the following:

>RMD C

6-14

RESOURCE MONITORING DISPLAY (RMD)
The RMD CDisplay has 14 fields for each region:
1.

Name of the cache region.

Region size in octal of the cache region in 32 word memory
bloCKS, followed in parentheses by the decimal number of disk
blocks available in the cache extent area.

Device name.

Total count of all reads issued to that device"
These
include VIRTUAL, READAHEAD, DIRECTORY, LOGICAL, and OVERLAY
read requests.

Read hit rate (percentage o~
satisfied by the cache).

read

requests

that

were

Read fail rate (percentage of all read
not be satisfied by the cache).

requests

that

could

Read load rate (percentage of all read requests that resulted
in data being loaded into the cache) for the cache region.

Total writes (count of all write requests issued to the
device, including VIRTUAL, DIRECTORY, and LOGICAL writes).

Write hit rate (percentage of all write requests that
updating of blOCKS already loaded in the cache).

10.

Write fail rate (percentage of all write requests that could
not be directed to the cache because of an extent overlap).

11.

Write defer rate (percentage of all write requests that
deferred) •

12.

Total I/O operations (total of all read and write
for the device.

operations

13.

Cache Used (percentage of cache extent storage area
the device).

used

14.

Totals for the cache region.

all

caused

were

6.7,,3.1. Altering the RHD C Display from the Setup Page - To alter the
Displal', you press the ESCAPE key, which displays the setup page for
the General Statistics about a Cached Region Display. The setup page
lists the available commands you can use to alter the Display, and
prompts you for a connnand. You can enter multiple connnands after each
prompt by using commas as separators. The setup commands available
for alt.ering this display are:
•

REGION=name specifies the region to be displayed.
This command allows you to select the cache
displayed. The default region is CACHE ..

•

RATE=s,

region

Where s is the refresh rate in seconds.

This command allOWS you to determine how often RMD replots the
General Statistics about a Cache Region Display, if you are
running RMD on a video display terminal. The default refresh
rate is once per second.

6-15

RESOURCE MONITORING DISPLAY (RMD)
You can truncate these commands to their shortest unique forms.
(For
this display page, the shortest unique form is RA for RATE, and RE for
REGION.) These setup parameters stay in effect until you alter them,
even if you switch to another display page and then return to the RMO
C Display.

6.7.3.2 Altering the RHD C Display from the MCR Command Line - You
can enter the REGION and RATE commands as part of the MCR command
line. For example, when you enter the following command line, RMO
displays general statistics for the region named CACHE and replots the
display every 2 seconds:

)RMD C,REGJON=CACHE,RATF=2
The information displayed is
refreshed every two seconds.

for

the

region

named

CACHE

and

These setup parameters stay in effect until you alter them by using
setup commands from the setup page. Even if you switch to another
display page, and then return to the RHD C Display,RMD does not
restore the default parameters.

6.7.4

The Detailed Statistics About a Cache Region Display

The Detailed "Statistics about a Cache Region display (RMO 0 display)
shows you detailed statistics about a particular cache region.
(However, you must have previously established disk data caching
through the MOUNT or SET command to use this display_ For more
information on disk data caching, see Chapter 19 of this manual.) You
access this display from another display by pressing the 0 key (for
Detailed Statistics.) To access this display from the MCR command
line, you type the following:
>I:;:MO D

The RMO D Display has 15 fields for each cached device:
1.

Region Name

Region Size (in octal, measured in 32 word memory blocks.)

Cache Status field (whether the cache is ACTIVE and/or
ENABLED) •
ACTIVE means the device is being cached through
the region: ENABLED means that the device will automatically
be cached when it is mounted (even if the MOUNT command does
not explicitly request that the device be cached).

Requests Being Cached field (types of cache I/O operations
enabled for the device).
The types can be VIRTUAL (VIR),
READAHEAD (RDH), DIRECTORY (OIR), LOGICAL (LOG), and OVERLAY
(OVR) •

Reads section (number of read requests issued for each of the
I/O types listed in the display, as well as the total of all
read requests).

Read Hit Rate, Read Load Rate, Read Overlap Rate, and the
Extent Too Big rate for each type of request. Each of these
rates is computed as a percentage of the total number of read
operations for the particular type of request.

6-16

RESOURCE MONITORING DISPLAY (RMD)
7.

Maximum Extent Size for each of < the .I/O.typeslo

8..

Writes section sho'WstbenumherQf write requ.sts isSued for
each of the .110 types . .·a.ndthe total.ofallwt:it,e·· ~equests •
NotethatREADABEAD an<l OVERLAY write requests d.onot exist,
so . these fields ··areblank·.

Write Hit RateandWr:ite Overlap Rat.e for each type of I/O
request.
Each of these· rates·· is computed.· as· a percentage· .• of
the total number of write operations o.fa particular type.

10.

Total.amount.ofeachtypeofI/O,asw-ellas the totalamount
of all Iio~

11.

The last four listit.ems show rates that. ate not accumulated
by I/O type.
All cache I/O requests require t.hat an I/O
packet be allocated from primary· pool.

12.

Primary Pool Allocat.ion Failure Rate
(how
oft.en
the
allocat.ion cannot be done) as a percentage of the total
number of I/Os issued for that device.

13.

Cache Pool Allocation. Failure Rate is similar to the failure
ratefpr primary· pool allocation, ·except.tha~.· .• allocatiQnfrOm
the cache pool ispnly required on read operations. Tnerate
is therefore computed as a percentage·of the total number of
read operations.

14.

Read Load Failure Rate is the percentage of all
attempts that failed because of an I/O er~or.

15.

Deferred Write Rate is·th$ rat.e that write operations were
able to be deferred. This is computed as a pe~cent.age of the
total number of write operations.

cache

load

6.7. 4.1 Altering the·1OO) o Display from the Setup . Page'" TO ·alter the
Dis'play, you press the ESCAI?Ekey, which displays the setup page for
the Detailed Statistics About A Cached Region Displa.y. The setup page
lists the available commands you can use to alter the Display 1 and
prompts you for a command. You can enter multiple< commands after each
prompt by using commas as separat.ors. The setup commands available
for al t.ering this display are;
•

DEVICE1=ddnn: - specifies the device to be displayed ..
This command allows you to select the device to be displayed.
The ·defaultdevice isSY:. Note thatyou>canonly display one
device.

•

RATE=s, Where s is the refresh rate in seconds.
This command allows you to (letermine hoW'o·ften;aMD replots the
Detailed Statistics about a Cache Region Display, if you are
running RMD on a video display terminal. The default refresh
rate· is onCe per second ..

You can truncate these commands to their shortest unique forms. These
setup parameters stay in effect until you alter them, even if you
switch to another display page and then returntotheRMD DDisplay.

6-17

RESOURCE MONITORING DISPLAY (RMD)
6.7.4.2 Altering the RHD D Display from the MeR Command Line - You
can enter the DEVICE and RATE commands as part of the MeR command
line. For example, when you enter the following command line, RMD
displays detailed statistics for DR3: and replots the display every 2
secQnds:

The information for DR3:

is displayed.

These setup parameters stay in effect until you alter them by using
setup commands from the setup page. Even if you switch to another
display page, and then return to this display, RHD does not restore
the default parameters.

6.S

MODIFYING THE TASK-BUILD COMMAND FILE

You can modify the task-build command file to change the defaults
RMD.
On RSX-llM systems, this file is LB:[l,24]RMDBLD.CMD
systems and LB:[l,20]RMDBLD.CMD for unmapped systems.

for

mapped

On RSX-llM-PLUS systems, this file is LB:[l,24]RHDBLD.CMD.

6.9

ERROR MESSAGES

RMD generates the following error messages:
RMD - Allocated screen buffer too small for this device
Explanation: RMD requires more internal memory
requested display on the type of terminal
running RMD.
User Action: Rebuild RMD
modifying the task-build
6.S.

with a
command

to display the
on which you are

larger screen
buffer
by
file as discussed in Section

RMD - Illegal command - xxxxx
Explanation: You entered an illegal command xxxxx either on the
MCR command line or in response to the COMMAND> prompt on a setup
page.
User Action:
chapter.

Enter the correct command

documented

this

RMD - Page does not exist
Explanation: You requested a display page from the
line that does not exist.

MCR

command

User Action: Enter the command line again specifying
display mnemonic.

correct

6-lS

RESOURCE MONITORING DISPLAY (RMD)
RMD - Segment 'xxxxxx' not found
EJcplanation: The module xxxxxx was not found in the task
for RMD. This denotes an error in how RMD was task built.
Uuer Action:
modules.
RMD -

~rerminal

image

Check that RMD has been built with all the required

type not defined

EJcplanation: The operating system and RMD do not recognize
tE~rminal type.

your

User Action: Check your terminal type using the MCR command
SgT /TERM=TI:.
If this setting is incorrect, use the MCR SET
command to correct your terminal type setting. If the setting is
correct, move to a different type of terminal.
RMD -

~~erminal

type not set

Elcplanation: You did not build RMD to display the requested
display page on the type of terminal to which your terminal is
set.
User Action: Determine your terminal type setting using the
MeR SET /TERM=TI:
command.
If this setting is incorrect, use
the MCR SET command to correct your terminal type setting.
If
the setting is correct, move to a different type of terminal.
RMD -

']~erminal

type not yet supported

El~planation:

RMD does not recognize your terminal type.

U~ler Action:
Determine your terminal type setting using the
MeR SET /TERM=TI:
command.
If this setting is incorrect, use
the MCR SET command to correct your terminal type setting.
If
the
terminal
type is correct, you can write a terminal
characteristics module for the terminal similar to the one in
[l4,lOJV52CHA.MAC.
Then, assemble the module, include the new
module in the ODL file and rebuild RMD.

6-19

CHAPTER·7
SETTING UP AND RUNNING THE QUEUE MANAGER

This chapter is directed to the system manager or operator who will be
settin9 up and running the Queue Manager and batch processors on an
RSX-ll~1 or RSX-IIM-PLUS system.
Except where noted, all commands in
this chapter are privileged.
Most RSX-IIM/M-PLUS systems will include the Queue
convenience of multistream line printer spooling.

Manager

for

the

The QueueManageronRSX-lIM-PLUS also suppor't;s t,r(lnsparent. spooling:
and batch processing..
You can have the Qu(;!tueMa.llager wi t.h()utbatch
processing, but you cannot have batCh processing without the Queue
Marl!ager ...
In UFD [1,2] on the system disk
(LB:),
you will find the file
STARTUP.CMD.
This file includes commands for setting up the Queue
Manager on a standard configuration. This sets up the QMG subsystem
on a baseline system with one print processor, (and, on RSX-IIM-PLUS
systems, one batch processor .. ) The information in the present chapter
will help you alter STARTUP.CMD to set up a Queue Manager tailored to
your installation.
This chapter consists of a narrative introduction and review of the
process of setting up the Queue Managerfilndbatoh proce,sors} and
detailE~d descriptions of all commands to the Queue Manager.
The

qUE~ue

management subsystem consists of three major components on
(RSX-IIM... PLUS systems have a fourth .major component.) The
componE~nts are as follows:
RSX-ll~1.

A command line interpreter (OMGeLI) that processes both print
requests and queue access commands as described in the
RSX-IIM/M-PLUS ~ and Queue Operations Manual.
QMGCLI
communicates w1th the Queue Manager by sending data packets
to it.

The Queue Manager (OMG)
that controls the queueing and
dequeueing of print jobs. QMG communicates with QMGCLI and
the despooler tasks to process print jobs.

7-1

SETTING UP AND RUNNING THE QUEUE MANAGER
On RSX-IIM-PLUS systems only, QMG also controls
batch
processing.
The RSX-IIM-PLUS QMGCLI accepts batch requests
as well as print requests. The RSX-IIM-PLUS QMG controls the
queueing and dequeueing of batch jobs. The RSX-IIM-PLUS QMG
also includes a batch processor prototype task, BPR.
This
task creates a virtual terminal that passes commands to the
batch processor and to a system CLI, either MCR or DCL, or a
user-written CLI.
(Note that QMGCLI is not a CLI in this
sense.) The BPR task can be installed as many as 16 times
with task names in the form BAPnnn, where nnn represents one
to three Radix-50 characters.

7.1

The despool prototype task (LPP) that attaches a device and
despools print jobs to it. An LPP must be installed for each
device to be used as a spool device with the task name ddn,
where dd is the generic device name and n is the unit number.
A despool device is a device under the control of QMG.

On RSX-llM-PLUS only, the source files in SYO:[121,10] make
up the print processor task.. You can use this as a model if
you wish to write output despoolers for your applications.

INTRODUCTION AND REVIEW

The following narrative explains how to bring QMG
Both MCR and DCL commands are included.

into

your

system.

This can be done interactively, but in most cases you will include it
in an indirect command file invoked as part of the system's STARTUP
procedures.
NOTE
OnRSX-IlM-PLUS systems with DeL as a CLI, the DeL
form of these conunands can be used on both MeR and DeL
terminals.
This
is
for
compatibility
wi th
RSX-llM-PLUS Version 1,,0 ..
Each of the following steps includes a block diagram of the Queue
Manager, processors, and devices as they exist at that point in the
procedure. Those parts of the subsystem brought into being by that
step are shown in red.

7-2

SETTING UP AND RUNNING THE QUEUE MANAGER
1.,

Install the Queue Manager.
privileged utility tasks.

will

found

with

the

DCL>INSTAlL/CHFCKPOJNT $OMG
MeR> I NSTAI"I... $QMG/CKF'=YES

[Jj3

QUEUE
MANAGER

LPO:
unspooled

stopped

PRINT$
.PRINT

> SUBMIT

PRINT
ZK-154-81

7-3

SETTING UP AND RUNNING THE QUEUE MANAGER
2.

Start QMG.
The command starts the Queue Manager
and
initializes the default queues PRINT and BATCH. It creates
the queue file on LBO:
if the file is not there.
The
command also clears all assignments previously recorded. If
the queue file was intact, all queues will still contain
their jobs, but the jobs are not assigned to processors.
(Processors will have to be reinitialized, but queues will
not. )
DeL >STAF:T IQUFIJF IMAN(-IGFF:
MCI~:>11IJF

.ISlA: PMD

lli3

QUEUE
MANAGER

LPG:

unspooled

--- -- --

-----=...,~
Queue
PRINT

Queue

BATCH

PRINT$
.PRINT

Queue file

SUBMIT
ZK·155·81

7-4

SETTING UP AND RUNNING THE QUEUE MANAGER

3..

The default print queue PRINT was initialized in the previous
step, but you must initialize at least one more queue named
for each line printer. This queue will serve the many system
tasks that conventionally send output to LP: by directing
this output to QMG.
This is known as a device-specific
queue. PRINT is a general queue.
A device-specific queue must be initialized before the
associated device ~s initialized (spooled). For LPO:, the
device-specific queue is named LPO.

DCl>INITIALI7F/QUFUF lPO/PRJNT
MCR>OIJF: I .. PO: 1r.1;;:: P

QUEUE
MANAGER
unspooled

Queue
PRINT

Queue
BATCH

Queue

LPO

PRINT$
PRINT

FCS

Queue file

>SUllMIT

I
ZK-156-81

Initialization names, creates, and starts a queue.
You will need this extra queue even if your system has only
one printing device.
You can initialize as many as 14
additional print queues for a total of 16. One must be the
default queue PRINT. The remaining 15 can be device-specific
or general queues. There must be a device-specific queue for
every
spooled (initialized) output device.
Queues for
application processors are print queues.

7-5

SETTING UP AND RUNNING THE QUEUE MANAGER

Next, you must install a print processor for each physical
printing device that will be set spooled (by means of
INITIALIZE).
This processor "owns"
the
printer;
the
processor name must be derived from the printer name. For
example, LPG:
is
owned
by
LPG.
LPP.TSK
installs
automatically as LPO.
The print processors will be found
with the privileged utility tasks.
DCL.>INSTAI.I.
t1CH> 1: t·/S

$1 F'P

$I .. F'F'

[[3

QUEUE
MANAGER

LPO:

unspooled

Queue
BATCH

Queue
PRINT

Queue

LPO

PRINT$
.PRINT

FCS

Queue file

> SUBMIT
ZK-157-81

If you have additional output devices, use the
/TASK
qualifier to install their print processors under the proper
names. You can initialize as many as 15 print processors.
Applications processors are considered print processors for
this count.
DCL>lN:~··:At L/TASI<:I F'1

MC I~: .> T. N:.;

<.\",\. F'F'

$ I .. F' F' / T ASK :::: L P :I.

7-6

SETTING UP AND RUNNING THE QUEUE MANAGER
5.

You must initialize your print processors,
setting whatever
attributes you wish. Any initialization of a print processor
sets the associated output device spooled.

DCl>INJTIAL.IZF/PRINTFR lPO/FL.AG_PAGF:2/FORM:O/LOWFRCASF
MCR>(~UE

I .. PO: ISP IFL: 2/FO: O/I .. OW

QUEUE
MANAGER

LPO
LPO:
spooled

Queue
BATCH

Queue
PRINT

Queue

LPO

PRINT$
.PRINT

FCS

Queue file

ZK-1S8-81

The command assigns the queue LPO to despooler LPO.
The
queue must exist before you initialize the processor LPO.

7-7

SETTING UP AND RUNNING THE QUEUE MANAGER
6.

Next, you must install the interface between the Queue
Manager and other system tasks.
This interface is handled by
$QMGPRT.TSK.
It must be installed as PRT....
It will be
found with the nonprivileged utility tasks.

DCl>JNSTALL./TASK:PRT ••• SOMGPRT
MCR>INS SQMGPRT/TASK=PRT.++

QUEUE
MANAGER

LPO

LPO:
spooled

---~
Queue
BATCH

Queue
PRINT

Queue
LPO

PRT ...

PRINT$
.PRINT

FCS

Queue file

SUBMIT
ZK·159·81

7-8

SETTING UP AND RUNNING THE QUEUE MANAGER

Next, you must assign queues to print processors. Assignment
establishes the path between queue and print processor. The
Queue Manager can send jobs only to assigned processors.

DCL>ASSIGN/QUFUF
t·1cr~:>OIJF:.

PRJNT LPO

I..PO:/AS:PRINT

QUEUE
MANAGER

LPO
LPO:
spooled

---,
Queue

Queue

BATCH

PRINT$
.PRINT

PRT ...

Queue

FCS

LPO
Queue file

SUBMIT
ZK-160-81

When you complete this step, two queues are now
the same processor (because queue LPO was
processor LPO at initialization).

assigned
assigned

to
to

You can assign a queue to more than one processor and you can
a.ssign more than one queue to a processor.
If you initialize a queue, but do not assign it, jobs sent to
that queue will not be processed until the queue is assigned.
This completes the installation process for the RSX-llM
The remaining steps apply to RSX-IIM-PLUS only.

7-9

QMG.

SETTING UP AND RUNNING THE QUEUE MANAGER

You must nc>w in,tallt.l\e ba.'t;cll;. proce~sor.

This. tasK will

foun4witb.(tbe~rivilegea\1ti.~ity.t~,k$.

nCl>TNSTAtL, •. aPR

PRINT$
.PRINT

FCS

a2R.TSK inst.all.,autom"tically as SAPO.
Y<lu canl.n$tall·asma~yas:l~batch
have names in tbe form BAPn.·

7-10

processors.

They

must

SETTING UP AND RUNNING THE QUEUE MANAGER

7-11

SETTING UP AND RUNNING THE QUEUE MANAGER
10.

The
default
queue
BATCH
was
initialized
by
START/aUEUE/MANAGER, but you may initialize as many as 15
additional batch queues with names of as many as six
alphanumeric characters in any form.

DCL)JNT/G POGO/BATCH
Me F:::· {~IJI£ Pt100: leR :9

SAPO

QUEUE
MANAGER

LPO
LPO:
spooled

-~
Queue

Queue
PRINT

BATCH

Ooeue
POGO

Queue

LPO

PRT..•

PR1NT$
.PRINT

FCS

Queue tile

SUBMIT
ZK-l63.al

Note that batch processors do not need device-specific queues
because no devices are associated with them.

7-12

SETTING UP AND RUNNING THE QUEUE MANAGER

11 ;.'inal1Yt .you.-mustas.ignl>atch queue$t6·~t~11·.ptPee$so;f's.
llCl:)ASS 16N/.D. i<.ATCHBAF'O

2K·tsa~1

If you i.nitialize a: qUEilue but. 40 not assign it to a
processor, jobs can be queued, but they will not be processed
until tbe-queue.is assigned.

7-13

SETTING UP AND RUNNING THE QUEUE MANAGER
7.2

QUEUE MANAGER COMMAND DESCRIPTIONS

The operations of QMG are controlled through a number of DeL and MCR
commands. The functions invoked are identical, but the command syntax
is different. Use whichever command syntax you are accustomed to. In
this
manual, both forms of the syntax appear in the command
descriptions; the DeL commands and command elements are to the left
and the MCR to the right.
In the section titles, MCR commands or
command elements appear in parentheses. In the examples, commands are
identified explicitly by the DCL> and MCR> prompts.
The processors, devices, and device-specific queues all have names
derived from the name of the spooled device. Thus, if LPl: is the
spooled device, the processor that "owns" it is called LPI and the
device-specific queue is also called LPI. The colon (:) portion of
the device name can be omitted from references in DCL commands to
processors, devices, and queues. The colon portion must be included
in references in MCR commands to processors, devices, and queues. You
can include the colon portion in any DCL command, but it is required
only in MCR commands. Furthermore, in MCR commands, all queue names
must be terminated by a colon, whether they are derived from device
names or not. Thus, if you wish to refer to a queue named XPRESS in
an MCR command, you must refer to that queue as XPRESS:.
The general format of DeL QMG commands is as follows:
DCL>DCLcornrnand/QMGqualifier[s] parameter[s][/qualifier[sJ]
The general format of MCR QMG commands is as follows:
MCR>QUE ddnn:

/function[:option[s]][/sw[s]]

Command descriptions are given in the order they are used in the
narrative, except that any counteracting commands are described just
after the setup commands they counteract.

7.2.1

INITIALIZE/ (QUE /CR/SP)

These commands create, name, and start a queue or processor.
When you initialize an output processor, you are setting
its
corresponding device spooled. A spooled device can be accessed by the
Queue Manager. The processor or task must be installed.

7.2.1.1 INITIALIZE/QUEUE (QUE /CR) - INITIALIZE/QUEUE creates, names,
and starts a queue.
Formats
DCL>INITIALIZE/QUEUE queuename/qualifier
DCL Parameter Qualifiers
/BATCH
/PRINT
MCR>QUE ddnn:/CR:typ
MCR Queue Types
PRINT
BATCH
7-14

SETTING UP AND RUNNING THE QUEUE MANAGER
Paramet.er
queuename
This specifies the name of the queue to be initialized.
Queue names BATCH and PRINT are reserved, because the BATCH and
PRINT queues are initialized by the START/QUEUE/MANAGER (QUE
/STA:QMG) command.

The queue named BATCS is initialized on RSX-llM systems,
not used, and!s not accessible or displayed.

'but

You must initialize a queue for every output device to which the
Queue
Manager
is to send print jobs.
These are called
d~~vice-specific
queues.
Otherwise,
any
six
alphanumeric
characters make an acceptable queue name for a general queue. If
you have no processor LP1, LPl is then a general queue name.
D~~vice-specific

queues must be initialized before the

associated

processor.
Parameter Oualifiers
This qualifier can be either /BATCS·or /PRINT.
The qualifier
tells the Queue Manager what kind of queue is being initialized.
Queues for applications processors are print queues.
~1e

default qualifier is /PRINT. For the sake of clarity, you
should always include the qualifier when initializing a queue.

Examples
DCI.. >ASSIGN/QUFUF

xpr~FSS

lPO:

MC F: :> CHI F.: I.. PO: I AS: X P RF.: S S

This example creates, names, and starts a print queue named
XPRESS.
The queue can now accept print jobs, but it must be
assigned to an output processor before jobs can be taken from the
queue.
DCL>INITIAl 17F/C~UElIF XPRFSS/PRINT
ricr~:>out:::

XPRF.:SS:/CR:PRT.NT

This command assigns the queue
example to a print processor.

initialized

the

DCI. >INITIAL 17F/CHIEllE l PO/PRINT
[tCL>T.NITIALIZt:::/PRtNTF.R I..PO:
MCR>(HIF l. PO: /CF:
MCI;;:>[~UF.:

LF'O: ISP

This example creates, names, and starts a print queue named LPO.
~1is
is a device-specific queue whose name is derived from the
name of an output device. This queue must be initialized before
the output device despooler can be initialized. After both the
queue and output device despooler are initialized, the queue can
ac:cept print jobs and the named printer is set spooled.

7-15

SETTING UP AND RUNNING THE QUEUE MANAGER
Notes
No more than 16 print queues (including queues
processors) can be initialized.

for

applications

On RSX-llM-PLUS, no more than 16 batch queues can be initialized.
These counts include the default PRINT and BATCH queues.

7.2.1.2 INITIALIZE/PROCESSOR (QUE /SP) - This command creates, names,
and
starts an output despooler or batch processor.
When you
initialize an output despooler, this task "owns" a hardware device.
This is setting the device spooled; a spooled device can be accessed
by the Queue Manager.
Formats
DCL>INITIALIZE/processortype

processorname/[/qualifier]

MCR>QUE processorname:/SP[/sw[s]]
DeL Processor Types

MeR Function

/PROCESSOR
/PRINTER
/DEVICE
/BATCH PROCESSOR
/APPLICATIONS_PROCESSOR

/Sp
/Sp
/BA
/SP/EX

DeL Qualifiers

MCR Switches

/FLAG PAGE:n
/LOWERCASE
/UPPERCASE
/FORMS:n
/SHAREABLE

/FL:n
/LOW
/NOLO
/FO:n
/SHR

/sp

Processor Types
/PROCESSOR
/PRINTER
/DEVICE

(/SP)
(/SP)
(/SP)

The DeL processor types fall into three groups.
One group
consists of /PROCESSOR, /PRINTER, and /DEVICE. These three are
synonyms. The effect of each is the same.
The synonyms are
provided to assure unambiguous commands and documentation. Use
/PRINTER for line printers and /DEVICE for other output devices.
If you use one of these three synonyms, a device-specific queue
must exist before the output despooler task can be initialized.
See Notes.
The MCR /SP switch performs the same function.
There are no
synonyms in the MCR form of this command. A device-specific
queue must exist before the output despooler task can be
initialized. See Notes.

This is the second DeL processor type. Use this
(or option) when initializing a batch processor.

7-16

processor

type

SETTING UP AND RUNNING THE QUEUE MANAGER
/APPLICATIONS_PROCESSOR (/SP/EX)
'1'his is the third DeL processor type. Use this processor type
when the destination of the output is not a physical device, but
rather some software application.
Use /APPLICATIONS PROCESSOR
~ilien you are
initializing a user-written output despooler for
which the physical device is not currently in the system.
This
makes it possible for the Queue Manager to despool output to an
a.pplications task, to a network, or to some other instance of
down-line loading.
In MCR format, you must combine the /SP and /EX options.
When you use this command in either form, the Queue Manager does
not
check for the existence of a physical device before
initializing the processor.
Parameter
processorname
Remember, the names of the device, processor, and queue are the
same, and interchangeable.
MCR users must include the colon
( : ) but DeL users can omit it.
You must initialize device-specific queues before you
the print processor with the same number.

initialize

If initializing a batch processor, its name must be in
BAPn.

the

form

DeL Qu,alifiers and MCR Functions
These qualifiers and functions
print processors only.

have

meaning

for

initializing

With the exception of setting the number of flag pages, these
qualifiers have no effect on the printed output of the printer
hieing initialized. Rather, these qualifiers define the kind of
print jobs the processor can accept.
Different kinds of print jobs are established
command that places them in the queue.

the

/FLAG_PAGE:n (/FL:n)
This qualifier specifies how many flag pages are to precede jobs
and files printed by this processor. The default is
and the
value of n must be 0, 1, or 2.

If the processor is being initialized to
you may want to set this qualifier to 0.

special

forms,

If you wish, you can change the value set here with the /FLAG
qualifier to the START/ command (/FL switch to /STA option).
/LOWERCASE (/LOW)
If you initialize a printer as lowercase, that printer will
accept print jobs with lowercase or uppercase specified in the
PRINT command. Normally, you should not use this qualifier
unless the hardware involved has both the uppercase and lowercase
character sets.

7-17

SETTING UP AND RUNNING THE QUEUE MANAGER

/UPPERCASE (/NOLO)
If you initialize a printer as uppercase, that printer will not
accept print jobs with lowercase specified in the PRINT command.
Normally, you should not use this qualifier unless the hardware
involved does not have the lowercase character set. This is the
default.
/FORMS:n (/FO:n)
The value for n can range from 0 through 255.
These numbers are to be specified by your users
commands.

The default is
in

their

You should determine which forms will be used on your system and
assign
each
a
number.
You should then edit the file
LB:[1,24]LPPBLD.CMD to set up the forms table for the print
processor to correspond to the numbers you have assigned to the
forms. Then, you must build the processor.
If the right forms are not in an available printer,
their jobs
will wait until the printer stops, the proper forms are put in
place, and the printer is restarted with a new value for /FORMS
(/FO) .
Forms differ by their length and width.
in the forms table.

Both values can

set

Setting width is simply a matter of determining how many columns
are needed to fill in the form.
There are no standard widths for
forms, but 80 and 132 are the most common.
Setting length requires you to determine whether your forms are
of a standard length.
IIStandard length is any form length that
can be set on your printing hardware.
If the hardware can handle
the form by setting a response to a form-feed character, then it
is a standard length form,
and the form feed is a IIreal,1I
(hardware) form feed.
ll

If the form length cannot be set on the hardware, then it is a
nonstandard length.
In this case, the form feed must be replaced
by an appropriate number of line feeds.
This is called a
"simulated," (software) form feed.
The following table shows the forms
requirements
for
a
hypothetical installation.
The form names describe different
uses for these special forms, but the names have no significance
otherwise.
Form

Assigned n

Width

Length

Accordion
Paychecks
Invoices
Stationery
Moon Diary
Star Log

0
1
2
3
4
5

132
40
80
80
22
112

66
10
66
66
43
113

Standard?
Y
Y
Y
Y
N
N

The forms table can be changed at LB:[1,24]LPPBLD.CMD.
procedure is explained in the comments in this file.

7-18

This

SETTING UP AND RUNNING THE QUEUE MANAGER
As shipped, FORMS:O is 66 lines long by 132 columns with real
form feeds. FORMS:l is 1 line long by 132 columns with simulated
form feeds; FORMS:2 is 2 lines "long by 132 columns with simulated
form feeds; and so on through FORMS:66 which is 66 lines long by
132 columns with simulated form feeds.
The rema~n~ng FORMS:n
entries are set to 1 line long by 132 columns with simulated form
feeds.
Thus, if you specify /FORMS:43, when the
printer
encounters a form feed,-it will count the number of lines on the
page and subtract that number from 43.
The printer will then
reel off a number of line feeds equal to the difference. You may
find this arrangement satisfactory if your installation rarely
uses forms other than standard line-printer paper, but if you
have more than one standard form, you will probably want to make
the changes in the forms table entries.
/ SHARE,PLBLE

( / SHR )

This qualifier establishes the processor as shareable.
This
means the physical device is not "owned" by a processor if it is
not printing a job. Normally, the output processor attaches the
device when it is initialized and no other job can access the
device until it is detached.
If you initialize the processor as shareable, the device is
a·ttached at the beginning of the QMG print job and detached at
the end of the job, leaving the device free for other uses.
()~~~ ..~'.~M-'~LtS ,+~y~uinitial.ize .. ~. ..."I>~Q~El.• $(>:t' as
tr!!lnsp~~ent $pqQ:11ngtQ t.l1at:.·a.ev.:l.ce··.• wil1· . ·not:work~

shareable,

Di.:1. >]"I'.!IT,[(.\1 ]IF/Pf.:OCFSSOf\ LF'O!

LPO: is set spooled.
M,anager.

Jobs can be passed to it

from

the

You must initialize a device-specific queue named LPO before
can initialize the processor for device LPO:.

Queue
you

DCI. ::TNTTJI:'.jL I7F/PfnNTFF: l F'l !/FLf'-l(1. F'~IGF:2
MCP>QIH-:: I..P1.:/SP/FI...:2

This command initializes a print processor to control LP1:
and
specifies that jobs run on this printer will be preceded by two
flag pages. Jobs specifying flag pages in the PRINT command will
h,:lve two flag pages at the head of the job.
DCI.>JNITIAI..I'ZF/PHINTFR 1..F'1/NOI..OWFR
M(F:>(~UI::

1.F'1.: lSi=' /NOL.OW

This command initializes a print processor to control
states
that the printer will only accept jobs
uppercase in the PRINT command.

7-19

LP1:
and
specifying

SETTING UP AND RUNNING THE QUEUE MANAGER

DCL:>INI/BATCH_PROCESSOR BAPO
HCR)GUE BAPOt/BA
This oomma.nd creates, ncunes, a.nd starts batch processor SAPO,
an RSX-IIM-PLUSsyst.em.

DCI. >INI/PRO I. PO/FI ~IG:?/FORMS:O/I,·OWFR
MeR:> CHJ r::: I... F' 0 : / S F' I F I.. : ~ I F 0 : 0 I I... 0 W

This command creates, names, and starts print processor LPG. The
printer has the lower-case character set. Jobs will have two
flag pages when printed.
Notes
No more than 16 batch processors on an RSX-l1 M-PLUS system, or 16
print processors (including applications processors) can be
initialized.
If you are initializing an output despooler that attaches a
physical device,
the system checks for the existence of the
device and of its device-specific queue before the command is
executed. Therefore, the following procedure must be followed.
1.

The device must be part of the current system.

You must initialize a device-specific queue for the device
before you initialize an output despooler of the same type
and number.
When you initialize an output processor, it is named and
started and has its device-specific queue assigned to it.

For each print processor, there must be a print queue, called
the device-specific queue, with a corresponding name. The
printer named LPG: is owned by the output despooler named
LPG.
There must also be a device-specific queue named LPG.
The processor cannot be named until the device-specific queue
has
been
initialized.
This
queue will be assigned
automatically to the processor whose name it shares, but the
device-specific
queue
can
be deassigned and assigned
elsewhere after initialization.
This procedure does not apply
to
initializing
batch
processors or applications processors. Neither a physical
device nor a device-specific queue is needed to initialize a
batch processor or applications processor.
There can also be print queues whose names do not correspond
to output devices. These are called general queues.

The lowercase/uppercase attributes have no effect on the nature
of the printer's output. They do not cause jobs to be printed
all uppercase. These qualifiers set up a "mask" that must be
matched by the attributes of print jobs before they can be sent
to the printer. A printer without the lowercase character set
can be initialized lowercase and it will' accept print jobs with
lowercase specified in the PRINT command. This might be done if
a printer with the lowercase character set was temporarily
unavailable.
As a general rule, however, you should only
initialize printers with the characteristics they actually have
to avoid confusion.

7-2G

SETTING UP AND RUNNING 'THE QUEUE MANAGER
(~~e line printer driver
does, however, affect the printer's
output, through lowercase-to-uppercase translation.
See the
di.scussion of SET /LOWER in the RSX-llM/M-PLUS MCR Operations
Ma,nual, or the discussion of SET DEVICE fLOWER in the RSX-llM
Cc~d Language Manual
or the RSX-llM-PLUS Command Language
Ma.nual.)

7.2.2

DELETE/ (QUE /DEL)

You can. delete queues or processors.

7.2.2.1
name.

DELETE/QUEUE (QUE /DEL:Q) - DELETE/QUEUE

deletes

queues

Formats
DCL>DELETE/QUEUE

queuename/ERASE

MCR>QUE queuename:/DEL:Q
Parameter
queuename/ERASE (/DEL:Q)
This specifies the name of a queue to be deleted.
Only a
privileged user can delete a queue using this parameter. The
default queues BATCH and PRINT cannot be deleted.
When
If the queue has jobs in it, it will be marked for delete.
the last job leaves the queue, the queue itself is deleted. No
new jobs can be entered.
You cannot delete device-specific queues until after you have
deleted the processor with the same number.
See next section.
Examples
:0 CI. :> Ii F I. F T F / 0 UF UF t"l ('1 N I~ / F t\ A SF.

MCR>OtJE r1fJNt,: /flEL.: (]

This privileged command deletes the queue named MONA if it is
empty.
If the queue has entries, it is marked for delete, and
will be deleted as soon as the last job is removed from the
queue. Note the colon in the queue name in the MCR example.

7.2.2.2 DELETE/PROCESSOR (QUE /UNSP) - DELETE/PROCESSOR deletes print
processors, output despoolers, or batch processors by name. The
command also sets the device unspooled.
Formats
DCL>DELETE/processortype

processorname

MCR>QUE processorname:/UNSP

7-21

SETTING UP AND RUNNING THE QUEUE MANAGER
DCL Processor Types

MCR Functions

/PROCESSOR
/PRINTER
/DEVICE
/BATCH PROCESSOR
/APPLICATIONS_PROCESSOR

/UNSP
/UNSP
/UNSP
/UNBA
/UNSP

Parameter
processorname
For physical devices, the name of the processor is identical with
the name of the physical device.
Thus, the device LPI:
is
controlled by processor LPI:. DCL commands do not require that
you include the colon (:), but you must include the colon in all
MCR commands.
Batch processors have names in the form BAPnnn, where nnn is
to three Radix-50 characters.

one

Applications processors have names of six Radix-50 characters.
Processor Types
/PROCESSOR (/UNSP)
/PRINTER
/DEVICE
The DCL processor types fall into three groups.
One group
consists of /PROCESSOR, /PRINTER, and /DEVICE. These three are
synonyms. The effect of each is the same.
The synonyms are
provided to assure unambiguous commands and documentation. Use
/PRINTER for line printers and /DEVICE for other output devices.
If you use one of these three synonyms, the device-specific queue
cannot be deleted until after the output despooler task is
deleted.
These distinctions do not apply in MCR.
/BATCH_PROCESSOR C/UNBA)

This is the second DeL processOr type.
when deleting a batch processor.

Use this

processor

type

/APPLICATIONS_PROCESSOR (/UNSP)
This is the third DCL processor type. Use this processor type
when the destination of the output is not a physical device, but
rather some software application.
Use /APPLICATIONS PROCESSOR
when you are deleting a user-written output despooler. Examples

Ii C F: :> ~) I j F l .. F' ',) ~ / U N ~~ f'

This example deletes processor LPO, the
LPO: .
DCL>DELETE/BATCH_PROCESSOR BAP2
MCR>QUE BAP2:/UNBA

7-22

owner

line

printer

SETTING UP AND RUNNING THE QUEUE MANAGER

Tbe command$. are .equivalent., they delet.e t.he bat.ch proce.ssor
namedBAP2, on an RSX-llM-PLUSsyst.em. Not.e the colon in the MCR
command.
DCl>DElFTE/PROCESSOR lPO

DCI... >DEI.E TE /QI JEUF I.. PO/ERASE
("iCF<>nUF I.. PO: /UNSP
MeR:> Q I.J r: f.•• F' 0 : / n E J... : n

This example shows the
device-specific queue.

order

you

must

delete

Notes
DELETE/PROCESSOR (/UNSP) counteracts INITIALIZE/PROCESSOR (/SP).
For maximum clarity, operators using DCL should use the specific
qualifiers
/PRINTER
and
/DEVICE rather than the synonym
/PROCESSOR when deleting output despoolers.

7.2.3

ASSIGN/QUEUE (QUE /AS:)

ASSIGN/QUEUE
processor.

(QUE

/AS:)

establishes

path

from

queue

Formats.
DCL>ASSIGN/QUEUE queuename processorname
MCR>QUE processorname:/AS:queuename
Paramet~er

queuename
This specifies the queue that is to be assigned to the processor.
processorname
This specifies
assigned.

the

processor

which

the

queue

When assigning queues to output devices, use the the device
in the form ddnn:.

be
name

Notes
This command can be used to redirect output from one processor to
another.
Other uses include grouping related processors, such as plotters,
under a single queue.

7.2.4

DEASSIGN/QUEUE (QUE /DEA)

DEASSIGN/QUEUE (QUE /DEA) counteracts ASSIGN/QUEUE (/AS).
to eliminate the path from a queue to a processor.

7-23

It is

used

SETTING UP AND RUNNING THE QUEUE MANAGER
Formats
DCL>DEASSIGN/QUEUE queuename processorname
MCR>QUE processorname:/DEA:queuename
Parameters
queuename
This specifies the queue
processor.

that

deassigned

from

the

processorname
This specifies the processor
deassigned.

from

which

queue

When deassigning queues from output devices, use the device
in the form ddnn:.

7.2.5

name

STOP/ (QUE /STO)

STOP/ (/STO)
processor.

7.2.5.1

used

stop

queues,

the

Queue

Manager,

STOP/QUEUE (QUE /STO:QUE) - STOP/QUEUE stops queues.

Formats
DCL>STOP/QUEUE queuename
MCR>QUE queuename:/STO:QUE
Parameter
queuename
This specifies the queue to be stopped. Following the command,
no jobs will be taken from the queue, but jobs can still be added
to the queue.
If a job is active at the time this command is issued, the job
will be allowed to complete processing but no further jobs will
be dequeued.
Note the colon (:) in the MCR form of the command.

7.2.5.2 STOP/QUEUE/MANAGER (/STO:QMG) - STOP/QUEUE/MANAGER (/STO:QMG)
stops the Queue Manager and deletes all processors, whether batch
processors or output despoolers.
Formats
DCL>STOP/QUEUE/MANAGER[/ABORT]
MCR>QUE /STO:QMG[:AB]

7-24

SETTING UP AND RUNNING THE QUEUE MANAGER
Notes
If you issue this command without the /ABORT (:AB) qualifier, QMG
is marked for stop. As ~oon as all currently active jobs on all
processors are done, QMG will stop. No more jobs can be entered
in the queue.
See also example in Section 7.2.6.2.
If you include the /ABORT (:AB) qualifier, all active
he!ld immediately and QMG exits without further delay.

7.2.5.3: STOP/PROCESSOR (QUE
processor.

/STO) - STOP/PROCESSOR

jobs

(/STO)

are

stops

Formats:
DCL>STOP/processortype

processorname[/qualifier]

MCR>QUE processorname:/STO[:opt]
DCL Processor Types

MCR Functions

/PROCESSOR
/PRINTER
/DEVICE
/APPLICATIONS PROCESSOR
/BATCH_PROCESSOR
DCL Parameter Qualifiers

/STO
/STO
/STO
/STO
/STO
MCR Options

/PAUSE
/JOB END
/FILE END
/ABORT

<no equivalent>
:EOJ
:EOF
:AB

Paramet.er
processorname
wrlen stopping print processors, use the device name in
ddnn: .

the

form

This command has no effect on the status of jobs in queues,
no jobs will be dequeued while the processor is stopped.

but

Processor Types
/PROCESSOR (/STO)
/PRINTE:R
/DEVICE:
The DCL processor types are synonyms. The effect of each is the
same. These synonyms are provided to assure unambiguous commands
and documentation. Use /PRINTER for line printers,
/DEVICE for
ot.her output devices and /BATCH PROCESSOR for batch processors.
MeR users use /STO across the board.
/BATCH_wPROCESSOR (/ STO )
Use this processor type when stopping a batch processor.

7-25

SETTING UP AND RUNNING THE QUEUE MANAGER
/APPLICATIONS_PROCESSOR (/STO)
Use this processor type when the destination of the output is not
a physical device, but rather some software application. Use
/APPLICATIONS PROCESSOR when you are stopping a user-written
output despooler.
Oualifiers
Only one qualifier is permitted. The choice of qualifier here
affects the restarting of jobs when the processor is started
again.
/PAUSE <no equivalent>
This is the default; it causes the processor to stop at the end
of the current line.
There is no MCR qualifier;
/STO is
sufficient.
/JOB_END (:EOJ)
This qualifier causes the processor to stop at end of the current
job.
/FILE_END (:EOF)
This qualifier causes the processor to stop at end of the current
file.
/ ABORT (:AB)
This qualifier causes the processor
current job is held in its queue.

stop

immediately.

The

Notes
This command is counteracted by START/PROCESSOR (/STA).
You
cannot issue START/PROCESSOR (/STA) until the processor actually
stops.

7.2.5.4 STOP/ABORT (QUE /KIL) - STOP/ABORT (/KIL) deletes the active
job on a given processor.
Privileged users can delete any job;
nonprivileged users can delete their own jobs. You do not need to
know the queue name or job name to delete the job, only the name of
the processor.
Formats
DCL>STOP/ABORT processorname
MCR>QUE processorname:/KIL
processorname
This specifies the processor whose active job you wish to delete.
Note that the MCR command format requires a colon (:) after the
processor name.
You can stop jobs running on any processor under the
QMG, including RSX-llM-PLUS batch processors.

7-26

control

SETTING UP AND RUNNING THE QUEUE MANAGER
ExamplE!s
DCI. >:::\TClP li~\H(1PT
1:- r D 1:: t~· <:; cl C) r "j'
I .. P 0

This example shows how to stop a print job on LPO: The currently
active job is deleted from the queue and the next eligible job is
queued.
Notes
Use this command to quickly stop a processor,
printer printing nothing but form feeds.

such

line

As; soon as the active job is deleted, QMG passes the next
eligible job to the processor.
The processor has not been
aborted or killed, only the active job on that processor.
You can also delete the active job
wi.th this command.

7.2.6

card-reader

processor

START/ (QUE /STA)

START/ (QUE /STA) is used to start a queue, the Queue Manager,
processor. START/ (QUE /STA) counteracts STOP/ (/STO).

7.2.6.1
queue.

START/QUEUE (QUE

/STA) - START/QUEUE

(QUE

/STA)

starts

Formats;
DCL>START/QUEUE queuename
MCR>QUE queuename:/STA
Paramet~er

queuename
This specifies the queue to be started.
queue that has been stopped.
Note
format.

This command starts a
the colon (:) in the MCR

7.2.6.2 START/QUEUE/MANAGER (QUE /STA:QMG) - START/QUEUE/MANAGER (QUE
/STA:QMG) starts the Queue Manager, initializes the default queues
PRINT and BATCH, and creates the queue file LBO:[I,7]QUEUE.SYS if it
does not exist.
The command also clears all queue assignments.
If
the qUE!Ue file was intact, all queues will still contain their jobs,
but will not be assigned to processors.
Formats;
DCL> START/QUEUE/MANAGER
MCR>QUE /STA:QMG

7-27

SETTING UP AND RUNNING THE QUEUE MANAGER
Examples

Starts Queue Manager. Initializes the default queues PRINT
BATCH,
if
they are not already initialized.
Clears
assignments of queues to processors.

and
all

Any jobs that were active at the time the Queue Manager was
stopped will be held when the Queue Manager is started again.
All other jobs retain the status they had when QMG was stopped.
All processors must be reinitialized.
The default queue BATCH is initialized on RSX-IIM sy'stems as well
as RSX-IlM-PLUS, but it is neither accessible nor displayed.
UC I, :" ~:; T n F' I Q 1JF ! J F / t1 A N:'\ r; E F:

I,Cf:::uUF

/STO: OMG

With this command, the
processors are deleted.

Queue

Manager

stopped,

and

all

nt:: I , '> (:; T (.1 !~: T / Ci I.J F I !=: / MAN A f3 E F:
J

i'i I,:: r: :' I] UF ./ S T A : n1"1 G

This command clears all assignments of queues to processors.
DC I.> II-I TTl AI .. I?F IPF~ T N,"FF: I.. PO
I I CI. ::. J 1'-11 T I A I. TZ F ,/ P F: I N T F F:: I. P:l.
PCl.> 1: N TTl f~l.. 1: ZF.:/BATCH .. F'I~08E:SSOR BAF'O
nCL:> I NIT I At.. I IF IBATCH".PROCe::SSOF: FlAP 1
Del .. :> I~l H E I iJ N;' U I, JF I ,I F F' P 1 NT!, P (0
( let :> 1"-1 ;:) ~~ J GN ;' DU F I IF!.' t\ :r N T I.. P 1
DCL>A8~3,[GN/QIJF.:I.JI:: BATr;H SAPO
Del. >ASS:r CiN/tHIFUF BATCH SAP 1.
MC I~: .':' I) I J I"
Ii C >- 1.I r

r, n

I _PO! I S P

L F' 1 ~ I ::~:, ~:.
Me P::: (.! 11 E. F.: POt / B I~

f'1Cfn QUE HAP 1. : IBA
,"j CF: >- i~ U F I, PC' : / A ::3 : F' I~: TNT
He i;: >- ('/ U F I. P~, : .I A ! P t\ I NT
I"d:I\}IHJE BA.PO: lAS: BATCH
MCf\~>OUF

BAF':I.: /I~S: BATCH

These cowmands recreate the network of queues and
that RSX-lIM systems have no batch processors.

processors.

Note

the

nc I.. ::- I~: F ,.. F:: I~l :3 F.: / J f] B F' Ii: I N T B () B ()
i'iCP>GI!F f'f~INT: BOBD/t,FI..

This command releases a held job that
system crashed.

7-28

was

active

the

time

SETTING UP AND RUNNING THE QUEUE MANAGER
7.2.6.3 START/PROCESSOR (QUE /STA) - START/PROCESSOR
starts a batch processor or output despooler.

(QUE

/STA)

Formats:
processorname

DCL>START/processortype

[/qualifier[s]]

MCR>QUE processorname:/STA[:opt[s]]
DeL Processor Types

DCL Qualifiers

/PROCESSOR
/PRINTER
/DEVICE
/BA'1'CH···PROCESSOR
/APPLICATIONS_PROCESSOR

/FORMS:n
- /FLAG: n
/CONTINUE
/RESTART
/NEXT JOB
/TOP OF FILE
/BACKSPACE:n
/FORWARDSPACE:n
/AT PAGE:n

/ALIGN
MeR Options
/E'O:n
/E'L :n
<no equivalent>
:NE
: RES
:PA:O
:BA:n
:E'W:n
:PA:n
/AL
Paramet~er

processorname
ddnn:
This specifies the processor to be started.
When starting a
st~opped output processor, use the device name in the form ddnn:.
Processor Types
/PROCESSOR
/PRINTE:R
/DEVICE:
ISA!l'CHPROCESSOR
/APPLICATIONS_PROCESSOR
These are DCL synonyms. The effect of each is the same.
These
synonyms
are
provided to assure unambiguous commands and
documentation. Use /PRINTER for line printers, /DEVICE for other
output
devices,
/BA!l'CBPROCESSOR for batch processors, and
/APPLICATIONS PROCESSOR for applications processors.
In MCR
format, use the /STA option.
Qualifiers
Some qualifiers have meaning for starting either batch or print
processors, and some have meaning for print processors only.
See
descriptive text.

7-29

SETTING UP AND RUNNING THE QUEUE MANAGER

This field is restricted. You can include either /FORMS:
(/FO:)
or /FLAG:
(/FL:) or both, or you can include anyone of the
remaining qualifiers, if permitted.
/FORMS:
(/FO:)
processors only.

and

/FLAG:

(/FL:)

have

meaning

for

/FORMS:n (/FO:n)
This overrides the forms value set when the processor was
initializpd. The value n can be any number from 0 through 256.
/FLAG:n (/FL:n)
This overrides
initialized.

the

flag

value

set

when

the

processor

was

When the processor starts again, the Queue Manager sends the next
job that matches the attributes of the processor.
/CONTINUE
This specifies that the processor carryon from wherever it was
stopped. This is the default. MCR format requires no switch.
/RESTART (: RES)
This specifies that interrupted jobs be restarted from the
beginning of the file that was being processed when the processor
was stopped. This qualifier affects only jobs that were ACTIVE
at the time the processor stopped.
This qualifier may conflict with the desires of your users who
have specified /NORESTART in their PRINT or SUBMIT commands.
This qualifier causes such jobs to be restarted at the start of
the file being processed when the processor was stopped. You
should check the queue display for such jobs before using this
qualifier.
The /CONTINUE (default) qualifier will not affect
such jobs.
The action of this qualifier further depends on the qualifier to
the STOP/ (/STO) command that stopped the processor in the first
place.
If the qualifier was /PAUSE (the default for /STO), then any jobs
active at that time will be restarted at their beginning.
If the qualifier was /FILE END (:EOF), then any jobs active at
that time will be restarted at their beginning, unless the active
file was the last one in the job.
If the qualifier was /ABORT (:AB) (or if the system crashed), the
current active job was held in its queue,
so the restart
qualifier will have no effect.
Likewise, if the qualifier was /JOB END, (:EOJ) there will have
been no current job, so the restart qualifier will have no
effect.
/NEXT_JOB (:NE)
This specifies that the processor start at the beginning
next job.

7-30

the

SETTING UP AND RUNNING THE QUEUE MANAGER

This specifies that the processor start at the top of the current
file in the current job.
The qualifiers /CONTINUE (the default for /STA), /RESTART (/RES),
/NEXT JOB (/NE), and /TOP OF FILE (PA:O) are appropriate for both
print-and batch processors. /BACKSPACE:n (:BA:n)
This specifies that the processor
current job.

start

pages

back

the

forward

the

This specifies that the processor start at specified page in
job that was active when the processor was stopped.

the

/FORWARDSPACE:n (:FW:n)
This specifies that the processor start n pages
current job.
/PAGE:n (:PA:n)

These page-related qualifiers have meaning for print processors
only.
They will have no effect unless the user specified a page
length qualifier in the PRINT command.
/ALIGN (:AL)
This informs the print processor that the paper in the line
printer is currently at the top of a form.
It is used when you
have stopped the print processor to change forms.
The print
processor maintains a count of how many lines it has gone down on
a form. The /ALIGN (/AL) qualifier clears that count for new
forms.
Examples
DC \,,::- ::::; T A I~T / PR 1 NTEF: I.F' 0
i~ '.": f(

:> n~.I F 1 PO; /~) T A

This example starts print processor LPO:.
from the point at which it was stopped.

Printing

continues

It CI... :> ~;; T AF: l .I F' R I NT F R L. P 0 .I F I.. AG : 2
,viCR:>QUI7' l. PO: /STA/FL: 2

This example starts print processor LPO:. The processor will put
tw'O flag pages at the head of the job and at the head of each
file if the user specifies flag pages in a PRINT command.
ItCI.>START /BATCH .."F'ROCESSOR SAPO

MCR)QUE BAPO:/STA
This example starts batch processor BAPO.
Batch
co,ntinuesfrom the point at which it was stopped.

7-31

processing

SETTING UP AND RUNNING THE QUEUE MANAGER

DCL)START/BATCH 8APO/CONTtNUE
MCR)QUF

~APO:/STA

The two examples are equivalent.
[lC 1.. ::- '3 T (~r~: T I F'R 1. NTF r~:

I .. F' 1. IRF. ST ART

MC FC: n UF I. F' 1 : / S T A ! F\ [" S

This example starts print processor LPl:. The job active at
time the processor was stopped is restarted.

the

Notes
You should choose with care between the /RESTART (:RES) and
/CONTINUE (MCR default) operations. A restart may conflict with
the desires of users with print or batch jobs active at the time
a processor is stopped.
Users can specify /NORESTART (/-RES) in their PRINT
or SUBMIT
commands.
If a print or batch job with this attribute is active
when the processor is stopped, and you start the processor with
the /RESTART (:RES) qualifier, you will be restarting the jobs at
the top of the file that was being processed when the processor
was stopped, which the user did not want to happen. The
/CONTINUE (MCR default) qualifier will continue such jobs as the
user expected.
If you are restarting a processor to handle special forms, you
will probably want to set the /FLAGS (:FL) attribute to 0 to
avoid having a banner page printed on your special forms.

7-32

CHAPTER 8
THE SHUTUP PROGRAM

SHUTUP is the system program that enables orderly shutdown of an
RSX-ll~[ or RSX-IIM-PLUS system.
SHUTUP sends warning messages, aborts
nonprivileged tasks, and dismounts devices on the system.

8.1

PB~REOUISITES

TO RUNNING SHUTUP

To shut. down a system
installed:

using

SHUTUP,

the

following

tasks

•

INDIRECT, the MCR Indirect Command Processor

•

ACS, if dynamic checkpoint space is established

•

BYE, if multiuser protection support is included

•

DMO, if there are any mounted devices

•

ELI, if error logging is active

•

ACC, in an
Accounting

RSX-IIM-PLUS

system

that

includes

must

Resource

If LB:[1,2]SHUTUP.CMD is present, you may want it to install ACS, BYE,
DMO, ELI, and ACC. See Section 8.5.

8.2

INVOKING SHUTUP

Invoke SHUTUP from a privileged terminal as follows:
>I~;UN

$SHUTIJP ~

On RSX-IIM
invoked:

systems,

SHUTUP

displays

the

following

message

when

On RSX-IlM-PLUS systems, SHUTUP displays the
invoked:

following

message

when

R8X-l1M SHUT DOWN PROGRAM

RSX-1.1 M-PLUS SHUT fH1WN PROGRAM

8-1

THE SHUTUP PROGRAM
8.3

SHUTUP INPUT

SHUTUP prompts for the number of minutes as follows:
1.

Number of minutes to wait before the system is shut down

Number of minutes between warning messages

Number of minutes before disabling logins

If you specify less than 4 minutes to wait before shutdown, SHUTUP
does not ask the last 2 questions.
Instead, SHUTUP sets the interval
between messages to 1 minute and disables log ins immediately.
The number of minutes between messages must be greater than zero and
less than the number of minutes before shutdown minus three. If you
specify either value incorrectly, SHUTUP rejects your answer and
reprompts.
The following is an example of SHUTUP prompts and
RSX-llM system:

user

If you are using an RSX-llM-PLUS or Micro/RSX system, SHUTUP asks
additional question, which is shown in the following example:

En'ter llIinlJtes to wait b~fore shut. c~nwn: 1 ~ ~
Ent~" mi.rtutp.s batwa~n IIIf?SS;~~"i~~i: 3 ~
Enter mil"ll.lte4E, to wait beforE' r.Li.sCtbljrlg l(\~:ins:

Errte r

ud nutf?S t,C wa i t, beftJ re shut riot..trI:

1. 5

input

~':j ~

Entel' I\'d nutes bet.ween messaSf?s: :3 (B[D
Ent(:~I' mirll.Jt,l!:'s t.tJ w~sit b*:'t'nT'f? di<;'3bl:i.n~ lo~i.ns: 5 ~
r~e,:sst')n for shutdnwr. «CR> fOT' rlorre): FIFLD SFRVJCF PM. ~

After receiving your input, SHUTUP asks for confirmation as follows:

oK to',; h 1.1 t d I'" n ?
f)

[ YIN] :

SHUTUP terminates without taking any action if your response to the
question is N.
If your response is Y, SHUTUP sends warning messages
to terminals. Section 8.4 explains the messages.

8.4

SHUTUP OUTPUT

SHUTUP sends warning messages to terminals. If the system does not
support multiuser protection, SHUTUP sends warning messages to all
terminals. If the system does support multiuser protection, SHUTUP
sends warning messages only to logged-in terminals. On multiuser
systems, a terminal set to NOBROADCAST receives the warning messages
only during the last five minutes before shutdown.
SHUTUP sends the following warning messages:
F' :I. ~:' a ~; p
;:, ~'l u l. d () w n :

f i I"t :i. ~,:. h 1..1 f", :1::'=i min IJ l p ',;;
F .i. r.:·!·1 d S Po r v 'j. I,:' ~ P M

h p '1" Cl r p

~::. hut c'\ n w n

-- --

1",1 AI. Nl.I T F~ e ,~ ~; 0 n

-- -

Wi; I NII T

Three minutes later, SHUTUP sends another message:
P 1 to.' ,;1 ~:; p

fin i ~:. h

1..1 F,

1? ll'I:i n IJ t Eo she for P

8-2

'3 h '.I t (:\ 0 W n

f Cl r

THE SauTUP PROGRAM
The messages include a 6-character name that is a DECnet node name (if
DECnet is active) or the system name that was selected during system
generat:ion (if DECnet is not active).
In the previous messages,
WALNUT is the 6-character name.
SHUTUP continues to issue the warning messages at the interval
specified.
When three minutes remain before system shutdown, SHUTUP
changes; the interval between messages to one minute.
If ~he system supports multiuser protection and the specified delay
before disabling log ins has expired (measured from the time SHUTUP is
started), SHUTUP displays the following message on the invoking
terminall:
All

furth~r

lastns ar@ rlisAbled

After SHUTUP logs out all terminals, aborts all nonprivileged tasks,
and dismounts all devices, it displays the following message on the
invoking terminal:
SHUTUP

oPf:'r';~t:i.Qn

CClIIIP] ptp

SHUTUP then halts the processor.
At this: point, you can either bootstrap another system or resume
operati.on of the current system by pressing the continue switch on the
CPU console. After you press the CONT·switch (continue), logins are
enabled and the following message appears on the invoking terminal:

To cont.inue operation of the current system, you
devices. and follow normal system startup procedures.

8.5

must

mount

the

THE SHUTUP.CMD FILE

The indirect command file LB: [1,-2]SHUTUP.CMD is for user-specific
functions.
SHUTUP submits the file,
if present, to the Indirect
Command Processor for execution. The SHUTUP task-build file specifies
the amount of time (the time-out interval) that SHUTUP.CMD has to
execute. The default time-out interval is 120 seconds or 170{octal).
It is possible to change the time-out interval for SHUTUP.CMD in the
task-build file.
On unmapped RSX-I1M systems, the task-build file is [1,20)SHUBLD.CMD.
On mapped RSX-11M systems, the file is [1,24]SHUBLD.CMD.
For RSX-11M-PLUS systems, the task-build file is [1,24]SHUBLD.CMD.
If the timeout interval expires and SHUTUP.CMD is not finished, SHUTUP
asks if you want to wait for SHUTUP.CMD to finish. For example:
Command (AT.) Timeout - Continue waiting? [yIN]:
If you enter N, SHUTUP continues without waiting any longer.
If you
enter Y, SHUTUP waits an additional 30 seconds. SHUTUP continues
without waiting any longer if SHUTUP.CMD has not finished at the end
of the 30 seconds.

8-3

THE SHUTUP PROGRAM
You may want SHUTUP.CMD to install ACS, BYE, DMO, ELI, and ACC (these
tasks must be installed to enable SHUTUP to execute properly). If you
have an RSX-llM-PLUS system, SHUTUP.TSK will install ACS and ELI.
If
DECnet is installed on your system, you may use SHUTUP.CMD to shut
down the network.
The following is an example of a SHUTUP.CMD file:

;THTS SHUTUP.CMTt FIt F INSTAI..I. S FI. I
;ANf.I ACS IF THF.Y ARE NOT INSTAI.L.EDy
;AND AI.SO ACTIVATFS A COMMAND FJlF TO
; SHUT DOWN THE NETWORK T. F THF. NETWf)I~K
;If, ACTltJF.

;

.ENABLE SUBSTITUTION
.IFNINS ••• Fl.I INS $ELI
.IFNINS ••• ACS INS SACS

.IFNACT

NETACP

.GOrn 20

ml..B![1,?]NFTSTOf'

8.6

RSX-IIM SYSTEM SHUTDOWN

The following sections describe the shutdown procedure for RSX-llM
systems.
An annotated example of a system shutdown supplements the
description.

8.6.1

RSX-IlM System Shutdown Procedure

When the delay before system shutdown
following functions:

expires,

SHUTUP

(multiuser

performs

Logs out logged-in terminals
only)

Stops the Console Logger (if active)

Redirects the console terminal to the TI:

Submits the indirect command file LB:[1,2]SHUTUP.CMD (if
present), to the Indirect Command Processor for execution

Stops the Queue Manager (if active)

Stops the Error Log Task (ERRLOG) (if active)

Deallocates checkpoint space and dismounts devices

Halts the processor

At this point, you can either bootstrap
operation of the current system.

8-4

another

protection

the

systems

of SHUTUP

system

resume

THE SHUTUP PROGRAM

8.6.2

BZalaple of an ltSX-IIM Sya't:em Shutdown

The following is an example of an RSX-IIM system shutdown:

>RUN $S~HUTUf'
PROGRAM

)R8X-I1M SHUT DOWN

Enter mi nfJte~; towai t befo T'e shtJtr:town: 1. 0 fB§D
Enter ndnlJtes between messa!fest 3 (Ii)
Ent.el' mitHjt~s to wait before l:Hsablin!..t l09ins: 5 ~
OK t.o snlJtdowr,' r YINJ t y (!!§)
14-rtEC-8S 16:35 F'lease firlish

IJP,

to mint..ltes before- shlJtdowft

CASHFW

14-IIEC··SS 1.6:38 Please finish

IjP,

mt nutes befo re shtJtdowrt

CASHEW

wd flutes beforE' shutdown

CASHFW

All -flJT'ther

lo~Hns

are (.Ii sabled

14-flEC-8S 16:40 f'le~~e finish
14-t)EC-85 1./':42

PIE~lSse

fini<sh up, :5

14-DEC-85 16!43 Pl.ease finish
14-l)EC-·e~

I~IP ,

lJP,

16:44 Ple'ilfil.e finish up, t

14-DEC-85 16145

S~stpm

SET ICOLOG::;;OFF

•

is now

til i nljt*~s

tHti'ft)re

fil.hljtdr.Jwn

CASHEW

lTd rtutes

befoT'p. snu'l:.dc\wn

r.ASHFW

minlJt.e

befnre ~hl.ltrlown

CASHEW

6huttjn~

down -- CASHFW

@LEn ClI'2,JSHUTtJP.
>lN8 $F.:LI

>!NS tACS
'>@

<f:OF>

(~LJE ISlO t GMG

ELI

•

INOLL1fl •

16:46:01 ERRLOG -- £rror LosSin. stopped
ACS DrcO: IBLKS::::O.

•

ACB -- Checkpoint fils
DMO tlBOI l[lE'V -

hOW

inactive

OMO -- 8M.tam disk heins dismounted
DMO -- SYST~M dismounted from D80:
Final di.matJnt initiated
16:47:10
DBO: -- Dismount complete

***

from D90:

***

~MQ neOt/nEVe
DMO

--Warnin~

- Tasks

in5~811.d

***

fJMO -- SYST~11 r.ti ~smoIJnt-ed f rrHIt TJSO:
Fini.~ 1 rJ i ~mount, i.rd ti ~t.~d
16:47:20
DSO: -- Dismount complete

'**

8-5

THE SHUTUP PROGRAM
To shut down the system in this example, SHUTUP performs as follows:

Stops the Console Logger.

Invokes the indirect command file LB:[l,2]SHUTUP.CMD.
SHUTUP.CMD installs ELI and ACS.
The
@<EOF>
indicates the end of the command file SHUTUP.CMD.

message

Stops the Queue Manager.

Runs the task ELI to terminate the Error Log Task (ERRLOG).

Deallocates checkpoint files on DBO:.

Dismounts the disks on DBO:

Displays a message when SHUTUP has finished executing.

8.7

and 050:.

RSX-IIM-PLUS SYSTEM SHUTDOWN

The following sections
describe
the
shutdown
procedure
for
RSX-llM-PLUS systems.
An annotated example of a system shutdown
supplements the description.

8.7.1

RSX-llM-PLUS System Shutdown Procedure

When the delay before system shutdown
following functions:

expires,

SHUTUP

performs

the

Stops the Console Logger (if active)

Redirects the console terminal to the TI:

Submits the indirect command file LB:[1,2]SHUTUP.CMD
present) to the Indirect Command Processor for execution

Logs off logged-in terminals
only)

Stops the Queue Manager (if active)

Stops Resource Accounting, if Resource Accounting is active

Stops the Error Log Task (ERRLOG) (if active)

Checkpoints all read/write commons

Deallocates checkpoint space and dismounts devices

10.

Halts the processor

(multiuser

At this point, you can either bootstrap
operation of the current system.

8-6

another

of SHUTUP

protection

system

(if

systems

resume

THE SHUTUP PROGRAM

8. 7.2' BZu.pleol.u ·B.SX-llM"'PLUS _yet_Shutdown

The following.ls.An example of an RSX....1 1M-PLtJS system shut<lown:
>RUN$SHUTUP

Enter minut.es to waitbeforf1 shutdown: 10.(Ijj

Entef'mJt'lut~$betweerl .m.ssag.~l5
Erd.f?J'. minut·~~ .t4) ..·.·w-lltbefore dis"bl in~. If;)l?lins: ~'.(Ijj

Reason'rot'shutdown ('(CR> for none) t FIELD SFRVICf F'M
OK tu 1Shutdown,?CYINltY!D
OS-NOlJ-951ld34 Please finish UP., 10 lJlinutes lip-fO're
Reason forshlJ.tdownt FIELtt$ERVltEPM

~hfJt,dowft

-- ALMClN[I

05;...NOV .... S5 16: 39 . . . p 1 f?~~;eftni.sh tJ~' 5
lid nutes before shutdoWfl -- At MONn
Reasori ft)T's.j·HJtdown·;FIELD SERVtCE PM
()5"Nov-a516i41Pl~a$e
ReS$l)f) 1':'0!'

fini.sh.up,3

s.hl.d~d(Jwn:F' lEt..t.SERV teE

ltlirlui.es liEltot'a sht;:.ltdowt'l

16 t 42 F·lei:l~.e f i nishup, 2
m:i rtutes ttp.f<:lT"e
foY' shwi~dowrdFltLrJ SERVICe: PM

O~'5-NOV-85

Re;!t~i)ol"l

O'o-NOV-8S 16: 43F'leasEi' 'finish I,JFt,l.

RfHI Si) 0 for
O'5-NOtJ-8~

1;1'\IJt,f,~(,}wntF' tELO

Al.MOND

F'M

Ittirlui.ec

~hut,dt1wfl

AI. MONfI

before 5hut.dc\wn -- ALMOND

SERVICE F'M

16! 44$~s te1tt i $rHJW sh~,.t,ti n~ down -- ALMClND

Re;g ?orl~f f) r' shfJttil)wn t F lEt, n SF:RV I Ce: PM

ilLS: Eli' 2 JSHlJ Ttl F'

>1M$ tELl

>INS tACS
>@ <F.:OF:>

GlUE IST.O: QHG •
S:TOF'/ACCOtlNTING 'SHUTUF'

ELI lNOtOae
16:50:20: E'RfH,OG -·"Frror L.C)shH.n~ st.t:)pped

AC SfiB 7: I Btl< 5:= O.

•

ACS --

file now inactive

Ch.ckpoin~

:OMCI nrf7t IflFV/t OCK::::V

•

DMD -- Syst.m disk bein. dismounted

***

IlMO -- 8YSTF.M rH, SIlIOI,tl"l't.~1j t'rom tlf.f7:
F:i;n~l 1) l,<!H1H1tJnt.
11.. :47:19
Inl7~ ...;"; !t:i!!H'iQlJnt c'omf-lete

***

8-7

t rd, t i.atf.~d

***

THE SHUTUP PROGRAM
To shut down the system in this example, SHUTUP performs as follows:

Invokes the indirect command file LB:[l,2]SHUTUP.CMD.
SHUTUP.CMD installs ELI and ACS.
The
@<EOF>
indicates the end of the command file SHUTUP.CMD.

message

Stops the Queue Manager.

Stops Resource Accounting.

Runs the task ELI to terminate the Error Log Task (ERRLOG).

Deallocates checkpoint files on DB7:.

Dismounts the disk on DB7:.
The Virtual option, /LOCK-V, is privileged. When you specify
the Virtual option, the DISMOUNT command does not clear
volume as valid and does not spin down the disk.
(Refer to
the RSX-llM/M-PLUS MeR Operations Manual for additional
information II)
--

Displays a message when SHUTUP has finished executing

8-8

CHAPTER" 9
T'ERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS

9.1

INTRODUCTION

A local Micro/RSX terminal can log in to and conduct an interactive
session with an external computer system. This session is established
using t.he Data Terminal Emulator (DTE). The external system can be an
RSX-ll~[ or RSX-llM-PLUS system, a VAX/VMS system running VAX-II RSX, a
Professional Personal Computer, or another Micro/RSX system.
Once a
local Micro/RSX terminal is logged in to an external system, the
externa.l system becomes the host system.
The host system views
Micro/RSX as remote.
During an interactive session, files can be
transferred between the host system and Micro/RSX.
Files
are
transferred using the Micro/RSX File Transfer Utility (MFT).
The following two conditions must exist
file transfer to be operational:

Refer

9.1.1

for

terminal

emulation

and

The two computers must be connected.

The DTE software must be installed on the local Micro/RSX
system, and MFT must be installed on the host system.

t~o

Sections 9.1.1 and 9.1.2 for more detailed information.

Connecting Two Computers

The two computers can be connected either on-site or at remote sites
througrl an asynchronous serial line. A Micro/RSX system is connected
to an on-site external system by a cable and to a remote system by
DF03 modems and a telephone line.
In either case, there is a
dedicat:ed line between the two systems that establishes the ports at
each end of the line, assigned specifically for terminal emulation and
data transfer.
A direct hardwired connection between two systems can be established
by plugging one end of a cable into the communications port in the
back of the local system unit, and the other end of the cable to a
host system. A permanent connection can also be established by using
a DIGI,]~AL Model H312A null modem cable and two standard EIA RS-232
connect:ors. When the two systems are directly connected with a cable,
the terminal characteristics of the port at the local Micro/RSX system
should be set to SLAVE and NOECHO. This prevents the transmission of
extranE~OUS noise signals when the
port is idle (disconnected from
terminal emulation). Noise signals can create intersystem echo loops
that sE~riously affect system performance.

9-1

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
Transmission speed between systems varies depending
involved. Variations are based on the following:

the

•

Processor type

•

Interface type

•

System load

•

Distance between systems

•

Terminal support (use of higher baud rates requires
remote system support XON/XOFF protocol)

systems

that

the

If XON/XOFF is present, your terminal may run at a speed lower than
that of the physical connection. For consistent performance, use a
baud rate of 2400 for Micro/RSX.
The following figures show
system.

typical

configurations

for

Micro/RSX

User Terminal
Micro/RSX
System

Local POP-11
or VAX
System

OTE Program

MFT Program
TT30:

LOZV11

OZ11J

Connecting Ports
(both set to same baud rate)

ZK-4125-85

Figure 9-1

Terminal Emulation with an On-Site System
User Terminal

Micro/RSX
System

Remote POP-11
or VAX
System

OTE Program

MFT Program

TT30:

OZ11J

LOZV11

ZK-4126-85

Figure 9-2

Terminal Emulation with a Remote System

In these example configurations, when the local Micro/RSX user
terminal
(TT3:) is in terminal emulation, the following conditions
exist:
•

TT3:

is connected to port TT5:

•

Port TT5:

using the DTE software.

is connected to port TT30:

9-2

in a PDP-ll system.

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
•

Port TT5:

is a connector on a DZVll .

•

Port TT30:

is a connector on a DZll.

Note that port TT5:
~t:.

9.1.2

SFT TEF:MINAI.

is set using the following command line:
TTS: lSI AVF/NQFCHO

Location of DTE and MFT

There are two separate programs that support Micro/RSX terminal
emulation and file transfer.
One resides in the local Micro/RSX
system and the other resides in the host system. DTE, which is in the
Micro/RSX system, establishes the local terminal as an emulated
terminal. Establishing terminal emulation means connecting a local
Micro/RSX terminal to an external system so that the local Micro/RSX
termina.l can be logged in as a user of the host system.
The other program is MFT which interfaces with DTE when file
operations are initiated at a local terminal. The MFT software is
execute:d on the external computer system (the host) that is connected
to the Micro/RSX system.
DTE and MFT tasks are separate tasks that work together, but execute
on two physically different systems. Also, note that all user key-ins
are done at a terminal connected to the local Micro/RSX system.

9.2

ESTABLISHING TERMINAL EMULATION

Once you have determined that the two specified computers are
connect.ed and that both DTE and MFT are installed on their respective
systems, you can establish terminal emulation.
To establish a
connect.ion between Micro/RSX and another system, use the following
command line:
SET HOST/DTE device:/MUTE
where device is the Micro/RSX device and unit specification of the
terminal port used for terminal emulation.
Specifying the /MUTE
qualifier ensures that the terminal is set to SLAVE and NOECHO upon
exitin9 from terminal emulation.
The following command example establishes terminal emulation:
$

~1FT

HnST IlHF

TT5: IMUTE

This DeL command runs the DTE task, which establishes terminal
emulation by connecting your terminal to port TT5:.
When data
terminal emulation is terminated, port TT5:
is set to SLAVE and
NOECHO..
After you type this command (and follow it with a RETURN),
you arE~ connected to the host system. You can then log on as a user
of thai: system and use the file transfer utility (see Section 9.3).
To ter~]inate emulation, type the LOGOUT command from the host system.
Then, press and hold the control key (CTRL) and type a P character.
The following message is displayed:
%DTE-S-EMUEXIT,

Emulation

You are then returned
Micro/RSX system.

exitin~ •••

command

9-3

level

p]pasp wait

execution

the

local

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
NOTE
Be sure that you log out from the host system before
exiting terminal emulation.
If you are in terminal
emulation and press CTRL/P before logging out from the
host system, the terminal connection is returned to
the local Micro/RSX system. The host system remains
logged in to your account. Under these conditions, if
another user initiates terminal emulation, that user
will be logged in to the host system under your
account.
To use DTE from the system's console terminal, you
must first disable the console On-Line Debugging Tool
(ODT). Both console ODT and DTE use the CTRL/P
character.

9.2.1

DCL Command Syntax

The DCL SET HOST/DTE command qualifiers provide options that allow you
to do the following:
•

Dial out to the remote system through the DF03 modern

•

Specify the terminal as mute (SLAVE/NOECHO) on termination

•

Display the version of the DTE task

The SET HOST/DTE command line is as follows:
SET HOST/DTE device:[/options]
The options are as follows:
/DIAL=" ... "
Allows the specification of a dial command string
for the DF03
modern.
The string may consist of any of the digits 0 through 9, and
the equal sign (=). The equal sign indicates that another dial tone
is expected (for example, when you dial from an internal telephone
system to an outside telephone number).
/MUTE
Specifies whether DTE should alter certain device characteristics
prior to exiting.
The default is to return all of the device
characteristics to their original states. However, if the device
is set NOSLAVE/ECHO,
it is possible that noise characters can
create intersystem echo loops, which can
severely
affect
performance. Therefore, it is recommended that either the devic~
be set to SLAVE/NOECHO when it is idle (DTE will change these
characteristics), or that the /MUTE option be specified, which
will set the device to SLAVE/NOECHO when DTE exits.
/VERSION
Displays the version of the DTE task.

9-4

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
9.2.2

Examples

Followi.ng are examples using the SET HOST/DTE command.
$

SET HOST/DTE TT40:

This example invokes
terminal TT40:.
$

DTE

establish

terminal

emulation

using

srT HOST/DTE TT50:/DIAL=·S550B37·

This example initiates terminal emulation using terminal TT50:, after
directing the DF03 modern to dial the specified number and establish a
modern (~onnection.
$

8FT HOST/OTE TT2.5:/MUTE

This example establishes terminal emulation using terminal TT25:,
sets the terminal characteristics to SLAVE/NOECHO on termination.

9.3

and

PERFORMING FILE OPERATIONS

The MF~r utility is used to delete and transfer files between a
Micro/RSX system, using terminal emulation and the host system that
the local Micro/RSX is logged in to. Special code in the DTE task is
used 1:0 identify and perform local file operations requested by the
MFT task. File transfer is performed using an error detection and
correc1:ion algorithm to ensure data integrity. The speed of file
transfE:!r varies with the processor and interface types, system load,
and software.
NOTE
Support for variable typeahead buffer size allows
higher transfer rates.

for

Your local terminal is locked out during file transfer operations to
preven1: interference with the data transfer between the two systems.
You ar~~ returned to terminal emulation when the file operation
complet.es.
The command syntax used to perform file operations depends on the host
operating system.

9.3.1

MCR Command Syntax

If the host system is an RSX-IIM or RSX-IIM-PLUS system, or a VAX/VMS
system running VAX-II RSX, you use MCR commands to execute MFT as
follows:
>l~FT

The host system responds with the following:
MJ~T>

9-5

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
You can now copy files from one system to the other,
in either
direction.
To do this, use the following syntax to indicate the files
that you wish to copy:
MFT> to_file[/REM]=from_file[/REM]
where:
to file

The output file or where the file
to.

being

copied

from file

The input file or where the
from.

being

copied

/REM

Means remote; is used to indicate that the file is
on the local Micro/RSX system that is remote to the
host system.

file

If you want to copy from the host to the Micro/RSX system, the
is as follows:

syntax

>MFT MESSAGE.TXT/REM=HOST.TXT
If you want to copy from the Micro/RSX system to the host, the
is as follows:

syntax

>MFT MESSAGE.TXT=MICRO.TXT/REM
To delete files, use the following syntax:
MFT> delete_file[/options]
where:
delete file

The name of the file to be deleted.

/options

/DE indicates the file is to be deleted.
/REM indicates the file is on the Micro/RSX system
remote to the host system.
The absence of /REM
indicates the file is on the host system.

You cannot specify wildcards when using MFT to delete files.
A sample file transfer session follows:
:~ f.; F T H(1 S T,I DTF TT~) :
(B"ITl
>LIlGIN
:: f.d~CClt.lNT Ot, NAI1F:
use T'

>PASSWORD:

P2ssward

:>i-',FT
MFT:>MESSAGF.TXT=MICRO.TXT,IRFM
XDTE-S-MFTINIT, File QPer~tiQn initi~ted
XDTE-S-MFTCOMP, FlIp operation compipte

9-6

T'ERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS

(The cursor will be at the beginning of the last message.
continue the operation, press RETURN.)

,"iFT>

>L.OGOLJT

%DTF-S-FMUFXTT, Fmulation exjtins •••

Please wait

In orde:r to use MFT, you must be using the DTE task, because
protocol used for the file operations is unique to the two tasks.

9.3.2

the

DeL Command Syntax

If the host system is a Micro/RSX system, you use
command syntax to perform file operations:

the

following

DCL

COpy from_file[/option] to_file[/option]
DELETE file[/option]
where:
from file

The name of the input file that MFT is to transfer.

to file

The name of the output file to which MFT is to
the input file (from_file).

/option

/REM (remote) is used to indicate that the file is
on the local Micro/RSX system that is remote to the
host system. The absence of /REM indicates the file
is on the host system.

file

The file name of the file to be deleted.
NOTE

For input files,
/REMOTE indicates that the file
resides on the DTE system. For output files, /REMOTE
indicates that the output file should be created on
the DTE system. When using the DELETE/REMOTE command,
the file to be deleted should be deleted on the DTE
system.

9-7

copy

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
9.3.3

Examples

Following are examples of
programs.

using

the

DTE

the

host

(MFT)

system

This example copies the file INFILE.DAT from the remote
into OUTFILE.DAT on the host (MFT) system.

(DTE)

system

COpy TNFII..F.DAT

file

operations

COPY

MFT

OlITFnF.nAT/F~FMOTF

This example copies the file INFILE.DAT from
into OUTFILE.DAT on the remote (DTE) system.
$.

and

INFtl.F.tlAT/RFMOTF. O!JTFTI.F..f.t(1T

DF L F T F F I I.. F • 0 {\ T I F: F ti 0 r E

This example deletes the file FILE.DAT on the remote (DTE) system.

9.4

MESSAGES

The following sections list and describe the messages produced by
and MFT.

9.4.1

DTE

DTE MESSAGES

The following messages are produced by DTE.
Some messages also
include a 6-character octal field enclosed in parentheses. This field
provides additional internal information regarding the cause of the
error, but is generally not useful to you unless the information is
also mentioned in the message description.
?DTE-F-DEVTYPE, Illegal device type for DTE
DTE assigned the specified emulation device and found that it was
not a terminal. DTE can be used only on terminal devices.
%DTE-S-DF03SEQ, Dialing ...

Please hold

The DTE /DIAL option has been specified, and DTE is attempting to
establish a connection using a DF03 modem (which is assumed
present on the specified emulation terminal line). Your terminal
is locked out until the DF03 responds with either success or
failure.
?DTE-F-DF03TMO, Telephone connection failure due to timeout
DTE sent the dial sequence specified by the /DIAL option, and the
DF03 modem (which was assumed to be present) did not respond
within 40 seconds. DTE will attempt to hang up the line and then
exit in error.
%DTE-S-DIALHNG, Dialup line hung up
DTE is attempting to hang up the specified emulation terminal
It mayor may not have
that is connected to a DF03 modem.
succeeded in hanging up.

9-8

T:ERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS

%DTE-I-DTETVER, Data Terminal Emulator Version x.y [dd-rnrnrn-yy]
DTE displays its version number if the /IDENTIFICATION option was
selected on the command line.'
%DTE-S-,EMUEXIT, Emulation exiting...

Please wait

A CTRL/P was typed on your terminal, and DTE has begun exit
processing.
Your terminal is locked out, all DTE I/O processing
is being completed, and all device characteristics are being
restored.
This operation takes approximately 5 seconds.
?DTE-F-ERDDCMP, Transmission [DDCMP] failure (xxxxxx)
During DTE/MFT file transfer, a DDCMP error occurred that could
not be corrected after several retries. The physical (emulation)
terminal lines are producing too many errors for a file operation
to be performed. Usual causes for this behavior are baud rates
that are too high, systems that are too far apart (physical cable
length must be considered), a lack of the required terminal
support, or some form of electrical interference (noise) along
the physical connection (because of a bad telephone connection,
heavy electrical equipment, and so forth).
?DTE-F-FATALER, Internal error (xxxxxx)
DTE/MFT has encountered an unexpected internal condition.
This
message indicates a bug in the local file operations server
within the DTE task.
%DTE-S-MFTCOMP, File operation complete
A DTE/MFT file operation has completed, and control has been
returned to your terminal.
If the operation has completed in
failure, then this message will be preceded by an error message
showing the cause of the file operation failure.
%DTE-S-MFTINIT, File operation initiated
DTE has received the handshake sequence from the MFT task on the
other system.
DTE invokes the file transfer server to provide
local support for the operation being initiated on the remote
system.
Your terminal is locked out until the operation
completes.
?DTE-F-MSGFORM, Message format error (xxxxxx)
The version of the MFT file server within the DTE task is not
compatible with the version of the MFT task on the remote system.
This may be caused by an error in the remote MFT task, or by an
incompatibility of releases of DTE and MFT.
?DTE-F-NOTSELD, Terminal line not selected
This is an internal error, and indicates that the
lost.

LUN

has

been

%DTE-S-PHONEOK, Telephone connection established
DTE sent the dial sequence specified by the /DIAL option, and the
DF03 modern responded with success (it returned the character
ItAU).
The connection to the remote system has been successfully
established.

9-9

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS
?DTE-F-PHONERR, Failure to establish telephone connection
DTE sent the dial sequence specified by the IDIAL option, and the
DF03 modern did not respond with success. DTE will hang up the
line and then exit in error.
?DTE-F-PORTSEL, Assignment failure on specified device
DTE attempted to assign and attach the specified emulation
terminal device, and was not able to. The device may be attached
by another user, or may be an inappropriate device type for
emulation.
?DTE-F-REJOPER, Operation rejected (xxxxxx)
The file operations server within the DTE task cannot perform the
operation requested by the MFT task executing on the remote
system. Either the DTE task lacks the required support, or the
version of the remote MFT task does not match the version of DTE
being used on the local system.
?DTE-F-RMSRERR, Remote RMS-II error (xxxxxx)
An error occurred during the attempt to perform the file
operation.
The RMS-II error code (in octal) is displayed within
the paired parentheses.
?DTE-F-SYNLOST, Synchronization lost (xxxxxx)
Synchronization has been lost between the local DTE and the
remote MFT tasks.
This may be related to the baud rate of the
emulation terminal lines or the systems'
loads.
Retry the
operation.
?DTE-F-SYNXERR, Syntax error
The syntax of the DTE command either was not appropriate or did
not fit the documented syntax.
Correct the command and try
again.
?DTE-F-UNSPROT, Unsupported protocol operation (xxxxxx)
The version of DDCMP being used by the local DTE file operations
server and the remote MFT task are not compatible. The versions
of DTE and MFT are not compatible, and the requested operation
cannot be performed.

9.4.2

MFT MESSAGES

The following messages are produced by MFT.
Some messages also
include a " ... " field.
This indicates that all or part of the command
line will be displayed with the message.
?MFT-F-BADOPER, Illegal option specified:
A nonexistent or illegal option was specified on
line, or the option(s) selected is out of context.

the

command

?MFT-F-COMFILE, Unable to open specified command file
MFT was unable to access the specified command file.
No details
as to the reason for the failure are available. Typical reasons
for this message are file not found, protection violations, and
so on.
9-10

TERMINAL EMULATION AND FILE OPERATIONS WITH OTHER SYSTEMS

?MFT-F--FOPFAIL, File operation failed
The particular file operation specified could not be performed.
nlere are many possible causes for the failure. Typically, this
mE!Ssage is produced when MFT is unable to synchronize with the
file operations server it requests DTE to invoke. Other possible
causes include baud rates that are too high, systems that are too
far apart (physical cable length must be considered), a lack of
the required terminal support, or some form of electrical
interference (noise) along the physical connection (because of a
bad telephone connection, heavy electrical equipment, and so
forth) .
?MFT-F--ILLNODE, Illegal node combination:
nle MFT command string specifies both file specifications on the
same system. Either /REM appears on both file specifications or
does not appear on either specification.
This is illegal,
because each file specification must specify a different system.
?MFT-F--LINELEN, Command line too long
The command line specified was too long for the command buffer.
BE!CaUSe some of the command may have been lost, the entire
command is considered invalid.
?MFT-F-SPECERR, Error in file specification:
One or both of the file specifications supplied are in error.
File specification syntax is limited to the standard RSX-ll
format, which is "device:[uic]filename.typeiversion".
?MFT-F--SYNXERR, Syntax error:
The syntax of the command line specified is in error.
possible
causes may be illegal options, missing input or output file
specifications, or an error in the file specification syntax.

9-11

CHAPTER 10
VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

This chapter begins with a brief introduction to the Virtual Monitor
ConsolE~ Routine (VMR) and continues with the following sections:

• Starting VMR
• VMR Command Syntax
• VMR File Specifications
• VMR Command Descriptions
• VMR Error Messages
If you are familiar with VMR, you may want to skip directly to Section
10.5, which is called VMR Command Descriptions. Section 10.5 contains
command definitions, a list of parameters and keywords you can use for
each command, and examples of the commands.

10.1

INTRODUCTION TO VMR

VMR is a privileged system task that allows
RSX-IIM or RSX-IIM-PLUS system image file.

you

configure

VMR conwands are a subset of Monitor Console Routine (MCR) commands.
VMR commands differ from MCR commands in that VMR commands are
directE~d to the disk image of a system
rather than to the current
runnin9 system. The system image file that you configure by using VMR
commands can later be bootstrapped.
There are three types of VMR commands: initialization, informational,
and task control. Table 10-1 contains a list of VMR commands grouped
according to the function they perform.
See Section 10.5 for a description of each VMR command.

10.2

STARTING VMR

You can use three methods to start VMR. These methods are described
in thE! following sections. Before you start VMR, however, you must
first assign SY: and LB: to the device that holds the system image
file you want to modify. The symbol definition file that corresponds
to the system image file must meet the following requirements:
•

It must have the same file name as the system image file

•

It must have a file type of .STB

10-1

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
•

It must reside on the same device and in the same directory as
the system image file

The symbol definition file is not necessary if you use the lIM switch.
(See Section 10.4 for a description of the lIM switch.)
Once you have corresponding system image and symbol definition files,
you can start VMR. The methods for starting VMR are described in the
following sections.
Table 10-1
Functional List of VMR Commands
Command Name

Type of Command

ASSIGN

Initialization Commands

CONFIGURATION
INSTALL
LOAD
REDIRECT
SAVE
SET
TIME
UNLOAD
Task Control Commands

ALTER
CANCEL
FIX-IN-MEMORY
REASSIGN
REMOVE
RUN
UNFIX

Informational Commands

DEVICES
LUNS
PARTITIONS
TASKLIST

10.2.1

Method 1:

Running VMR

To run VMR, enter one of the following command lines:

VMR responds by requesting the name of the
you want to modify:

system

image

file

you enter the name of the system image file, VMR opens and
reads the symbol definition file.
Then, VMR opens the system
image file and verifies that the file is actually a system
image.

O~ce

10-2

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
Next, VMR displays the following prompt:

Enter any VMR command, or exit from VMR by pressing CTRL/Z.

On RSX-llM.... PLUS systemstifthesy.st~ itn.ge. file you .. ,pecify
has Executive data s.pace support, VMR displays the following
messages before issuing t.he prompt.:
Loadin~

Fxecutive d$ta space

Dat~sp.c.

10.2.2

Method 2:

lDa~1h~compl~ted

Installing and Running VMR from LB:

To install and run VMR, enter the following command:
>F:UN $Vt1F:

The system installs VMR from the pseudo device LB:
under the
system directory or library directory, and then loads it. On
RSX-IIM systems, the system directory is usually [1,50] for
unmapped
systems
and
[1,54]
for
mapped systems.
On
RSX-IIM-PLUS systems, the library directory is usually [3,54].
Next, VMR responds by requesting the name of the
file ,you want to modify:

system

image

E n t i':~ l' f i 1 E~ n i') ITI E' :

Once you enter the name of the system image file, VMR opens and
reads the symbol definition file.
Then, VMR opens the system
image file and verifies that the file is actually a system
image.
Next, VMR displays the following prompt:

Enter any VMR command, or exit from VMR by pressing CTRL/Z.

On RSX-llM-PLUS systems, .if t.he system image ~ile you specify
has Execut.ive data space suppOrt, VMR<1fsplaysthefOllowing
messages before issuing t.he prompt.:
Loar.Hn~

E}H3CUtj \,Ie

d~t/a

space

Data ,paee laaMin. completed

10.2.3

Method 3:

Running VMR While Specifying an Indirect Command File

To run VMR while specifying an indirect command file,
type VMR
followed by a space, then enter an at sign (@) followed by the
name of the indirect command file.
The first line of the
indirect command file must contain the name of the system image
file you want to modify. For example:
>\')~1H

PTf.lSKS. C~1D

The system loads VMR, and then, VMR executes the indirect command
file. VMR then exits.

10-3

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

Once you have started VMR, you can execute an indirect command
file any time VMR prompts for input. Indirect command files are
useful when you want to repeat a series of commands for several
different systems (INSTALL commands for example).
To execute an indirect command file in VMR, enter an at sign (@)
followed by the name of the indirect command file any time that
VMR prompts for input. For example:

VMR executes the indirect command file, extracting command input
from the specified file until it reaches the end of the file and
then returns to the terminal for further input.
VMR supports two levels of indirect command files.
This means
you can invoke a second indirect command file from within the
first indirect command file. However, if you try to invoke a
third indirect command file from within the second indirect
command file, you receive an error message.

10.3

VMR COMMAND SYNTAX

The following sections describe how to format VMR commands and how
enter comments in VMR command lines.

10.3.1

VMR Command Format

VMR command lines can contain a command name, parameter, keyword(s)
and keyword value(s).
The components of a VMR command line are
described as follows:
Command Name
The name of the VMR command.
You can abbreviate all VMR command names to 3 characters.
VMR accepts 3 characters and then searches for a space or
tab followed by the command parameter or by a RETURN if
there are no parameters.
Note that VMR does not permit
embedded spaces or tabs in command names.
Parameter
The parameter for the command.
Certain VMR commands require parameters. VMR parameters can
-be file specifications, keywords, devices, or task names.
You must always precede a parameter with a space or tab.
Keyword
One or more keywords for the command.
VMR keywords are command specific. Most VMR keywords are
preceded by a slash (f).
Some VMR commands permit more than
one keyword per command line.

10-4

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR keywords can be placed in any order in a command line
and still have the same meaning. For example, the command:
!')HF:> JNS

fFST. TSI</T~\SI<:::~)UF'FR/PMn::::YFS

has the same meaning as:
')MF::>INS TEST. TSI</Pt1r.i::=YF.S/TAS~.::::SIJF'E~:

Keyword Value
The value for the keyword.
You must always precede a keyword value with an equal sign
(=) or colon (:). In the following command line, =SUPER is
the keyword value assigned to the keyword /TASK.
'.)nF:> .rN~; TFST + TSK/TI~SI<:::SUF'FR

10.3.2

Including Comments in VMR Commands

VMR interprets an entire line of text as a comment if
character in the line is a semicolon (i). For example:

the

first

THIS LTNF IS A COMMFNT

')Mr~:> ;

To insert a comment within a command line, use an exclamation point
(1) at the start of the comment, and an exclamation point or RETURN at
the end of the comment.
VMR ignores all text between the two
exclamation points or between the exclamation point and the RETURN.
For example:
I.} MR

>. T (.~ S

! T H J SIS A C (l MMF N T S T F: I N G

Comments are especially
indirect command files.

10.4

useful

(8ITl

clarify

command

lines

VMR

VMR FILE SPECIFICATIONS

VMR accepts the standard RSX-llM/M-PLUS file specification format:
ddnn:[directory]filename.typeiver[/IM]
The components of VMR file specifications are described as follows:
ddnn:
The name of the device on which the file is located.
A device name consists of two ASCII characters (dd),
followed by an optional 1- to 3-digit octal unit number
(nn). You must include a colon (:) at the end of the device
name. For example:
OM1:
The default device in VMR is SYO:.

10-5

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
[directory]
The directory in which the file is located.
There are two types of directories in VMR, numeric and
named. A numeric directory contains two octal numbers, from
1 to 377, separated by a comma and enclosed in square
brackets ([ ]). For example:
[1,54]

Named directories are valid on RSX-llM-PLUS systems only. A
named directory consists of 1 to 9 alphanumeric characters,
enclosed in square brackets
For example:

«( ]).

[IGGY]
If you do not specify a directory, the system defaults
the directory under which VMR is currently running.

filename
The name of the file.
In VMR, a file name can consist
characters. For example:

alphanumeric

RSXllM
There is no default file name in VMR.
type
The type of file.
VMR file types can consist of 1 to
3
alphanumeric
characters. You must precede a file type with a period (.).
For example:
.SYS
File types are optional. However, omitting a file type may
cause VMR to assign one by default. VMR assigns default
file types to the following files:
System Image File

.SYS

Task Image File

.TSK

Indirect Command File

.CMD

ver
The version number of the file.
A version number helps differentiate files that would
otherwise
have
identical file specifications.
Always
precede a version number with a semicolon (i). For example:
i2

On RSX-llM systems, the version number is a number from 0 to
77777(octal).
On RSX-llM-PLUS systems, if you select
support for
decimal
version
numbers
during
system
generation, the version number is a number from 1 to
32767(decimal).
10-6

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
If you do not specify a version number for a file, the
system defaults to the highest version number of that file
in the directory.
lIM

A switch that, when added to the specification for the
system image file, overrides the VMR requirement for the
symbol definition file.
If you use the 11M switch when you
specify a system image file, the only command VMR accepts is
the SAVE command.
You use the 11M switch to write non-RSX-llM/M-PLUS system
images to secondary media in bootable format. The 11M
switch is also useful when you use an RSX-llM/M-PLUS system
as a host system for developing small, memory-resident
systems that must be loaded from a serial medium, such as
paper tape.

10.5

VMR COMMAND DESCRIPTIONS

The following pages include descriptions of the VMR commands in
alphabE!tical order.
Each command description contains the following
informcltion:
Command Abbreviation
The minimum number of letters that you must specify when
using the command name. The command abbreviation is located
at the outside margin of each page in capital letters.
Cc)mmand Name
The full command name in capital letters. The command
is followed by text describing the command's function.

name

Fc)rmat
The format(s) you should use when specifying the command.
Parameters
The command's parameters.

The command's keywords.
El~amples

Examples of command use and output.
N()tes
Additional information about the command.

10-7

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

ALT
ALTER
Use the ALTER command to change the static priority
task.

installed

Format
ALT[ER] taskname /PRI=priority
Parameters
taskname
The name of the task whose priority you want to alter.
/PRI
The keyword that changes the task's static priority.
priority
The new priority, from 1 to
specified task.

250,

you

want

assign

the

250 is the highest priority and 1 is the lowest priority you can
assign.
Therefore, a task with a priority of 200 takes
precedence over a task with a priority of 199.
The priority you enter is assumed to be octal unless you place
period (.) after the priority number.
Example
'Jl"iP>AI .. T

TF~)T

/PRT='24E ,.

Alters the static priority of task TEST to 248(decimal).

10-8

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

ASN
ASSIGN
Use the ASSIGN command to define, delete, or display logical device
assignments.
Logical device assignments are a way to associate
logical names with physical, pseudo, or logical devices.
When you
assign a logical name to a pseudo or logical device, the system
resolves the assignment to the associated physical device.
There are several types of logical-device assignments.
VMR supports
the manipulation of global assignments only. Global assignments apply
to all tasks in the running system.

NOTE
OnRSX-llM-P~US . . syetems. . with
extended log-ieal nam.e
'support, the. VMRASSIGN command cannot be used to
manipulate logioal names of any form otherthanllnnt.•

A logical device name has the same syntax as that of a physical device
unit.
It consists of a 2-character ASCII name (alphabetic) and an
optional 1- or 2-digit octal unit number, followed by a colon (:).
The
2-character
name can be either equivalent to a standard
RSX-llM/M-PLUS device name (for example, OK:) or formed by two letters
picked at random (for example,
ZZ:).
If a logical device name is
identical to a physical device name, the logical name is the one used
by the system.
The ASSIGN command has three formats.

These are described as follows:

Format 1
ASN ppnn:=llnn:/keyword
Defines a global assignment that associates
with the device ppnn:.

the

logical

name

lInn:

omit

lInn:,

Format 2
ASN /keyword
Displays all global assignments for the system.
Format 3
ASN =[llnn:]/keyword
Deletes; the specified global assignment,
deletes: all global assignments.

or,

Pararnet.ers
pp
A physical, logical, or pseudo device name.
nn
A unit number.

10-9

you

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

ASN (Cont.)
11

A logical device name.
/keywords
One of the following:
/GBL

/SYSTEM
Keywords
/GBL
Defines, displays or deletes global logical device assignments.

"., ,'., ." . J

:::.....".

"'. ".::. ......
,
,.

(R$.~~ 1M"-'Lua ..•.•.•y~t..m~R,"l.y.J ....D,~J.n._

aeletes

'syste.-wi<ie ).09tc"l. deviQ$ cuullg.,.ent.s.
Examples

Defines the global logical device name GBO:
to DM:.

V~R>A'N

and

assigns

/Gll

'lH1.(Hf:il fjb~]'

<TE' r.mil"ia 1)

(~SX:-IIM~~:L~S·sy$t.eR't$ :that<hCiY$ sel~Qt:¥ SUPP()~t. for ext.ended

1·(I)9iC,,1 na:mes.) List... all;.lobi$lassig~ent.s.,
3.

VMR}ASN =/GBL
Deletes all global assignments.

10-10

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

CAN
CANCEL
Use the! CANCEL command to cancel time-based initiation requests for a
task.
These requests result from the RUN$ directive or any of the
time-synchronized variations of the VMR RUN command.
The CANCEL command does not affect the execution of a task active in
the
slaved system image.
The CANCEL command removes only the
time-baLsed schedule requests still in the queue.

Format
CA~[CEL]

taskname

Paramet~er

taskname
The name of the task whose time-based initiation requests are

bE! canceled.
ExamplE!
I.) ~1 F: :> CAN

X I·::. E

Cancels all periodic
requests for task XKE.

rescheduling

10-11

and

time-based

initiation

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

CON
CONFIGURATION
(RSX-IlM-PLUS systems only.) Use the CONFIGURATION command to set the
control and status register (OBlt) or vector address o£a device, or to
display system configux:atlon information ..
The CONFIGURATI.ON command has two formats.
follows:

'f'hese

are

described

Format 1
CON[FIGURATION) SET controller-name CaR==value·
or
CON[FIGURATIONJ SET controller-name VEC-value
Sets the CSR or vector address of a device.
value per aommand line.

You can

enter

only

one

Parameters
controller-name
The name of the controller for which the CSR or vector address is
to be changed.
CSR-value
The new CSRaddress for the controller.
VEC-value
The new vector address for the controller.
Format 2
CON[FIGURATION] DIS (PLAY] [keyword] [FOR string]
Displays system configuration information on your terminal.
Parameters
keyword
One of the following:
CON[TROLLERS]
UNI[TS]
CPU
FUL[LJ
FOR string
A parameter tht'.t restricts the display to
the specified string-

10-12

the

devices

matching

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

l(e~rd:'

CON[TRO:rtI~Bi.sl

~~l1a;,liit ~eviQ~contjO~l~rin. t,h••..> ctu;.r.nt.conflguration ..
,,~
Sd1.,playconta.,tns 1:.b. followinginf()rmation:

.Oorit.rbii~r]$nute

•

coliltrollet;·sstarting

•

COntroller's

UNI.[TSJ
l)iSPlct~$ .... ~v,ry>d.Yid~Unll.t. . . in ,tbe durrent
display contains the .' .fol]fowing information:

syst.em.

The

UNITS

•

Log:±cilldeviQename.

•

C()tlt.rq~~Ee~>mUn~a.ndp~ysiQal . unitnLlIri)er of ·t.be device on that
e0rlt.rcr+ler~ . •. . .:!or~ual...aecess

supplied.' .for eaellport.

•

4evlces,

this

information is

Dev.lcestat.U$(wnetner . the deviceieoh oX'.offlirle l.

•
CPU

Displclys.t.l·uICPQs( . t.be oontrollers,·.> and . .·tbe· . . device units
curre)!1t ,,·eQnfigura~ion.·,

the

I fY.o.u d~notspecifYia

:IX_pIes
l.i

VMR>CON.SET

YHr.OS~::i:16010()

Sets t.he CSRaddress for the third DHllcontroller to 160100.
2>.

Vr~R>t:O~4$F:T . VHC VE:C!ll::340

Sets ·the vector address for the third DHII controller to 340.

10-13

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

CON (C,ont.)
Single-Processor Systems
3.

VHR>CONFIGtJRATION [IISPLAY CONTROLLERS
OFL
CPA
CSR=176700
RHB
OFL
CPA
CSR-176300
RHC
DFL
CPA
CSR=172040
RHD
OFl
CPA
CS~~17?440

RHA

'l't1A

OFL

CPA

CSR::::j70S00

YIA
VHR>

OFL

CPA

CBR::::16'O 1 00

UMR>CDN DIS UNI
RHAOl
DBt:
RHAt~
tIEt~.q

RHA~~ :

OFl

flfi:IVFR
nRIVER
DRIVF.R

[1113:

RHA3t

OFL

tlRIVER

Nl.O:

OFt.

IH'<IVFR

*)1'0:

OFt
ONt

tlRIVER
DfHVF.R

D[{ot

OF I..

OFL

R[10:

VEC=254 PRI::=5
VfC;=j,50 f'RI=5
VEC:t;::?04 PR 1 ::::5

VFC=?24 PRJ=5

VFC=300 f'RJ::::5
'JEC=340 PRI=~5

VMI~>

VMR>CDN D!S CPU
CF'A

VMR>
6.

VHR>CON fJl S FUl
ef'A

RHA
RHB

OFL
OFt

CPA
CPA

f{HC

OFt

RHD

OFL

nIt 0 t

RHAO:

OF1..

[lfU Vfr~

riB 1 :

RHA1 :

LIRIVER

DD2:

RHA:?:

r.rf.l3 ~

RHA3:

OFt
OFt
OFt

OFt
OFL

HRIVFR
nRIVER

NLO:
tJTO:
fUIO!
VMF:>

CSR:::: 2~ 76700

VFC::;254 F'F! I::::5

CPA

caR:;:: 176100
CSR::=:ti?040

CPA

CSR::: 1.77. 4 40

VFC:;:1.S0 F'Rt::~5
VFCI:::?04 PRY:;:5
V!:::C"':~24 F'R I::::S

ONt

10-14

DRIVER
til;: t IJE:H

flRIVF.R

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

10-15

VIRTUAL MONITOR CONtOLE ROUTINE (VMR)

DEV
DEVICES
Use the DEVICES command to display the symbolic names of all device
units in the system image of a particular device type.
If you do not
specify a device type, VMR displays the symbolic names of all device
units.
The device names appear in a single vertical column. A second column,
to the right,
contains additional information about a device (see
Notes) .
Format
DEV[ICESJ [dd: ]
Parameter
dd:
The device type.
Example
l.)MR>DFIJ

LPO:

l...oadE~(:I

DBO: I..Ci~df?d
DF:l: I.. ().::>dr:,~d
lJ n:.' ~ I. (),~ (1 f:' t:.l
1)DO! I.o;:ic:.led
DI:t1: 1.0,"1..11"'(\

111-':0:

1..()"I(iE~d

DI< 1.!
D I< ·7.·~:
nI·~ :'):

L oadF'd
I... (J ·s d f:~ d
I. 0 <:~ d E~ d

til.. 0: I.Oddc·:.·cj
'~Ii 1. ~ L o.: .. d f:'i.1
nL?: ! .n.::!ded

nM0:
IH/j 1:
OW.:>:

I. u <:~ d (~ d
1. t , .:>,IJ f~ d

I I.)<~dl.;>d

Dr.:r.'! 1.. (J;:~(:.I(~d
DF.:1.~

D ~:; 0:
!) ~):I.;

nTO!
OTt:
D X 0:
X j!

I::: I'~ () ~
11 H 0:
i1i1:. ~

loadf?d
nf f :!. i n (~! !... q ;:i d €-' Ij
nf f ). i n f' I. n i'! d E·' Ii
1.. 0.::1 I I (·:·!c.i
Lc.I;'>.dpd
t. Cl a ci f..~ d
I. I.) 3 iJ f' d
IJ n l () ,:! d (~ d
I.. (l '.::: d t..~ ".1
1.. (::;:1:-)\-.:::1

(:00:

TlO ~

T T (;!
;- T 1!
"r T .:::.:

! I) ::1 , I p ;'.1

rT.·~:
.~. r,~:

L (I ·~l df:' c:.\
I.. Cl ;:: d f~ d
I. o':>'dpd
I..oadf?d

10-16

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

DEV (Cont.)

CL {) :

!. F' () :

,~: '-,' 0) ':

nF;: 0 !

I)ivi

F:>

Notes
1.

The pseudo device SY:
is not redirected to the
device until the system is bootstrapped.

bootstrapped

The following list describes the types of messages that can
appear in the second column of the device list when you use
the DEVICES command.
(More than one message can appear on
the same line.)
•

LOADED indicates that the driver
loadable and currently loaded.

for

the

device

•

UNLOADED indicates that the
loadable but not loaded.

for

the

device

•

The absence of either LOADED or UNLOADED in the second
column indicates that the driver is permanently resident.
This means the driver is part of the Executive.

•

OF'LINE indicates, on RSX-IIM systems, that

driver

although the
device list contains an entry for the device, the device
is not currently attached to the system.

indicatesi,onRSX-IIM-PLUS, that a device has yet
• OFFL;[NE
to, be brought, on ,line'.'bythe ,reconfiguration. ta$k. All
physical devices in the device list have this notation
the second column.

•

A device name in the second column is the device to which
the corresponding device in the first column has been
redirected.

10-17

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

FIX
FIX-IN-MEMORY
Use the FIX command to load a task into memory and, on RSX-IIM-PLUS
systems, to load a region into its partition in the system image. VMR
can fix a task in the system image only if the partition in which it
is to be fixed is available.
Fixed tasks remain in memory even after they exit.
Therefore, the
system can run a fixed task faster because the task is memory-resident
Clnd does not need to be reloaded. Reexecuting fixed tasks however, is
not always practical.
If you expect to reexecute a fixed task, you
should write it in such a way that it initializes all impure data and
LUN assignments at run time.
The following restrictions apply to the fixing of tasks:
•

You must install a task before you fix it.

•

Active tasks cannot be fixed.

•

On RSX-IIM systems, you cannot fix checkpointable tasks.

•

On RSX-IIM-PLUS systems, do not fix
beoause
fixing
a
checkpointable
noncheckpointable.

•

On RSX-IIM-PLUS systems, you cannot fix tasks whose names are
in the forms ... xxx and xxx$$$ because that copy of the task
is never executed.
(The task is a prototype task.)

•

On RSX-lIS systems, all installed tasks must be fixed because
they cannot be loaded into the running RSX-llS system. If the
RSX-lIS system has memory management (PLAS) support, you
cannot use the FIX command to fix tasks. You must use the
INSTALL /FIX command instead.
See the description of the
INSTALL /FIX command.

•

On RSX-IIM and RSX-IIS systems, you can fix tasks above the
1 24K-word limit.
Before you fix a task above the 124K-word
limit, however, you must first create another copy of the
system image file larger than 498(decimal) blocks. The system
image file you create must be larger than 498 blocks because
the size of the system image file created during system
generation is 498 blocks for a system of 124K-words.

Use either the UNFIX or REMOVE command to remove
memory or remove a region from its partition .

checkpointable
task makes the

fixed

task

task
task

from

.Format
FIX taskname[/keyword]
Parameter
taskname
The task or region that you want to fix in memory. If you do not
specify a keyword, VMR assumes that the task is a single-user
task.

10-18

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

FIX (Cont.)
/keyword (RSX-llM-PLUS systems only)
One of the following:
IDIft
INSF

I REG

IRON

Keyword:s
IDIR
Specifies that the task to be fixed is a directive common.
Directive commons are used to hold some of the Executive
di:rectives instead of keeping them in Executive address space.
Because directive commons contain Executive code, they must be
installed and fixed in the system image before the system can be
bootstrapped.
Directive commons are installed and fixed in the
system image by commands in SYSVMR.CMD as part of the system
generation procedure.
Individual directive commons are installed and fixed contiguously
in memory to form one large. directive common called DIRllM.
DIRlIM must be fixed in memory before any other directive commons
can be fixed. Other directive commons must be fixed contiguously
to DIRllM ..
Directive commons cannot be shuffled, which means means that the
Shuffler cannot move them around in memory after they have been
fixed. For more information about the Shuffler, see Chapter 14.
To eliminate a directive common, use the REMOVE command.
INSF
Specifies that a fixed task cannot be shuffled. This means that
the Shuffler cannot move the task around in memory after the task
has been fixed. For information about the Shuffler, see Chapter
14.
IREG
Specifies that the task to be fixed is a common region.
IRON
Specifies that the task to be·fixed is a multiuser task and
the read-only portion is to be fixed in memory.
You must specify the entire task name.
Examples
1 •

'. ' :''i F: > F T:X:

~<!: F

Fixes the task XKE in its partition.

10-19

that

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

FIX (Cont.)
2.

VHR>FIX

TTCOM/R~8/NSF

Fi,xes tberss1dent cOmmt>n TTCOM in its
specifies tbattlie ta,ak<cannot beahuffled.

partition,

and

Indicates that the EDl editor is ;built as a multiuser
and fixes the task'sread"",onlyportion in memory.

task

10-20

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS
INSTALIJ

Use thE~ INSTALL command to make a task or common recognizable to the
system"
On RSX-llM and RSX-llS systems, you can al so use the INSTALL
command to load a common into a common partition. See the description
of thE~ FIX command for more information. You can install commons
above 1:he l24K-word limit. You cannot run a task until you install
it.
Once a task is installed, VMR creates a Task Control Block (TCB) for
the task in a system image table called the System Task Directory
(STD). The task parameters contained in the TCB enable the system to
run the task when requested to do so by an MCR command, VMR command,
or a system directive.
Format
INS[TALL] filespec[/keyword(s)]
Parameters
filespE:!c
A task image file specification in the form:
LB:[g,m]filename.typeiversion
The task image file you specify must be on the device
file type defaults to .TSK.

LB:.

The

/keyword(s)
Any keyword you specify either provides parameters that were not
specified at task-build time or overrides parameters that were
specified at task-build time.
One or more of the following:

/CKP=option
/CLI=option
/FIX=option

/FMAP-option
/INC=size
/IOP=option
/PAR=pname
/PMD=option
/PRI=number

/PRO=[system,owne:r,group,world]
/RON=option
10-21

VIR'l'UAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
/ROPAR==pname
/SEC=option
/SLV=option
/SYtJC=option

/TASK=taskname
/UIC=[group,member]
/WB==option
/XHR==option
Keywords
IAFF=[URM(s
(RSX-ll tv1-PLUS mu tipr';:)C'2ssor syste]l~3 only.) Che UNIB:JS
Pun Mask
( URM )
.:i f E i nit y
of ~.. he tas k .
You mllst spec
at 1°dSt one URM.
EllClos~' the URM ( ) i:.l square brackf:~Ls ([ J).

If you SIH:~cify In('re 'ha:l one
commas,
Por exar pie

When yenJ

on +:he

URM,

you

mu::::·'

separ

tlH.:'H1

specify the /A.~'F keyword, the inst~a, It:~d tas~
runs
to 'v,hi:::h thE' spec fied CRf-1;:. are con ected.

')Y

ordy

I_~rocessor

UNIBUS-run-mask
T},(::' Lhree-l~ tte~' nlme o f t he URM
f r)llow i..nq
UNIBUS
rur .
T'le

for
name

CPU
ar(~

()r

swi tch,=d

v 1 -Lel

URM

S] o::'cificati( ns:

CPA
CPB

PBE

UBK

UBP

LBF

cpe
CPD

1mB
!'BJ

UBL
UBM

UBf<.
UBS

UBN

l'BT

/CKP=option
(For systems that support dynamic allocation of
space.) Enables or disables checkpointing for a task.

checkpoint

The options are YES and NO.
If /CKP=YES,
checkpointing is
enabled for the task.
If /CKP=NO, checkpointing is disabled for
the task.
The task image file need not contain allocated checkpoint space.
The /CKP=YES keyword instructs the system to allocate checkpoint
space for the task, when required, from a checkpoint file.
On RSX-llM systems, if a task was built with the /XH switch,
/CKP keyword is disabled for that task.

10-22

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
~le /CKP keyword overrides the /CP switch specified at task-build
time.

The default is /CKP=YES.
/CLI=option
Indicates that the task being installed is or is
line interpreter (CLI).

not

command

The options are YES and NO.
/CLI=YES indicates that the task is
a command line interpreter.
/CLI=NO indicates that the task is
not a command line interpreter.
You must indicate that a task is a CLI, either by installing it
with the /CLI=YES keyword, or by taskbuilding it with the /CL
s~",i tch, before you can set a terminal to that CLI
or work with
the CLI by means of the MCR CLI command. See the RSX-IIM/M-PLUS
and Micro/RSX Task Builder Manual for more information on the
Task Builder /CL switch.
The default is whatever was specified at task-build time.
/FIX=option
(RSX-llS systems only.)
Indicates whether tasks on RSX-llS
systems with memory management (PLAS) support will be fixed in
memory.
The options are YES and NO. When you specify /FIX=YES, the
is installed and fixed in memory.

task

On RSX-llS systems with memory management support (PLAS), VMR
r,equires that you fix all tasks by using /FIX=YES. You cannot
install the task and fix it later with the FIX command.
The default is /FIX=NO

/FMAP==opt.ion
(RSX.... l1M-PLUSsy_'tents:only.llnformsthe syst.em that the task
wi.!l . . use1;he .fa$t.-maJ>pin9 •. ~ea;ture ··ofthe Executive. . You can use
the /FMAP keyword only with tasKS that have external headers.
The options. a.reUSan<1NO •.. !FMAJ;>=-YS6indicates . the task will
use
the
fast ...mappin9 .... £eatureo£ the Executi ve •
/FMAP=NO
indicatest.he:ta:'J'kwill not.usethefast-mappin9 feature of the
BlCe:~uti."e . .
SeEitth$i4escr1pti<>n o:f<thEit lXRR keyword for more information
about ext.ernal he.aders and the RSX-IIMIM-PLUS and Micro/RSX
ExecutIve Reference Mai)ua,l for more in forrnat ion about fast
mapping.
.
The <iefault is whatever was specified at task-build time ..

10-23

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
/INC=size
(Mapped systems only.) Indicates the extension size of a task.
The extension size refers to the number of additional words of
address space you want allocated to a task running in a
system-controlled partition.
The extension size is usually
expressed in octal but may also be expressed in decimal by
following the size with a period (.).
Tasks such as MAC, TKB, PIP, VFY, and AT. (Indirect) use the
space from the end of the task image to the end of their address
space, as dynamic memory in which to allocate symbol tables and
buffers.
The /INC keyword defines the number of words in this
dynamic region. The /INC keyword overrides the Task Builder's
EXTTSK or PAR options.
If a common is installed with an increment, it will no longer fit
in its original task image file.
Therefore, you cannot specify
both /INC=size and /WB=YES when installing a common.
The default size is the size specified at task-build time or zero
(0) •

/IOP=option
Informs the system that a privileged task needs access to the I/O
page.
The options are YES and NO.
If /IOP=YES,
INSTALL assumes that
the task will use the I/O page and, if the task is larger than
8K-words, issues a warning message because the I/O page will not
be mapped.
If /IOP=NO, INSTALL assumes that the task does not
need to use the I/O page. No warning message is issued.
The default is whatever was specified at task-build time.
/PAR=pname
Indicates a partition that overrides the partition name specified
at task-build time.
If the partition you specify does not exist,
VMR issues a warning message and attempts to install the task in
the GEN partition.

On RSX-lIM systems, if the task you install is built with
checkpoint space allocated in the task image file, and you
specify auser~contJ:ollea partition with the /PARkeyword, the
task's allocat.ed checkpoint space may no longer be large enough
to hold the task. The reason for this is that when you specify a
user-controlled partition, the size of the task is automatically
extended to the size of the partition.
If the user-controlled
partition specified when the ta8kis installed is larger than the
task size specified when the task was built, the task will no
longer fit in it.s allocated checkpoint space.
The default is whatever was specified at task-build time.

10-24

INS (Cont.)
/PMD=op1:ion
Informs the system whether a Postmortem Dump is required.
Th~~

options are YES and NO.
If /PMD=YES, the system performs a
Postmortem Dump of the task when the task is aborted because of
an SST error condition. If /PMD=NO, the system does not perform
a Postmortem Dump when the task is aborted.
To generate a Postmortem Dump, you must install the Postmortem
/PMD overrides the Task
Dump task PMD...
in the system.
Builder's /PM switch.
The default is whatever was specified at task-build time.

/PRI=number
Indicates the priority, from 1 to 250, you want assigned
installed task.

the

The default is PRI=50(decimal).

/PRO:a[systeIn,owner,grqUP.W0li'ldJ

(~S1C-ll.t4~'Lt)S.S¥~~~~~~l~.)

comroon~

$ •.!t! ...~..
r..• .•. •. ~.t. .·. •·.•·~.•.•.• •(!.·t1.·•. . o.i.n.·• ·•. .m.skfor
'You. m~.tu".flqu_~ebr;.ck'ts .. ( t ] ) ,. . .......
i.•..•.•.•..
·

.......>

i.:·:-:'.....: .:. .

i.::.::\:: ,::...:' ' -.':'.<.: ..'

,." ...... : :"."

."..... , .",.

\ftl.~ .•.•.·.rOusp..~ify .•· .·. ~ . .·.•·. J?rof;_¢~~()~.·i···.lJt~Sk . . . ·~c>r .·.• • •.~·. c~ll.··.·.· .•i··?t~h . . •. . th,· .•.•.· ·..• .·• lpRQ
you r,pla(!,· '. tb_user group" (~~st..E!ln, . ():wr-er,. ·.groUp,
wotld)·•.• witba~cesji:;yp.I1.J(~ea~(Rl,·.····wr;t~ .. (~li.· . ..,~t'~4· . . (El, .• del,t-:

kc;!ywox,-d,

(P). to indic~t'···.·•.·.t:ll'.·. .•.t.y~ofa<?~e&&s~9\l'tial1t . .• . assigned . t.o.·, e~ch
u$e~ ·.group. 'r().·•. ··.l9~~9n.·.~··iJ.C9~$S . ·.typ,t() .• • •Il·•.·•. l?"'?'t.~.<:tt~.~f>.\,lEJ~.r . . ~rQttP,
you' . Pl.~c, it.llEl.'Q~~~~t'1~ ·()lFtYp~s~nth"f.~c;! p()':i.t 1.0 n; as i t.he '
group name • Userg':rQups ....r.e del:i;m1te<i .·bY<::QnUn.as. I'or. example ':

/PR0==·[.RwEl), .Reb,.J!:~,.~l
Tbe ac;<::ess~yp~$ e.r.e d.sQ~l..b.d· asfollowsis

Re.d Acbe,s 'UO
Allows at-ask

Ext. end Aece$s (8)

Allows a task ~q. eX't.endthe ~e9;1.o~ l~ac()mmon.

(Dj

10-25

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont )
The u.ser groups are defined as follows:
System
All system tasks running under a UIC group number
than or equal to lO(octal).

less

Owner
Tasks that run under the same UIC as the file1s owner.
Group
Any task that is running under the same
the file1s owner.

UIC

group

Any task that
categories.

the

World
does

not

fit

one

above

You assign a group unlimited access by specifying RWED in the
group's position.
You assign a group no access by inserting a
comma in the group's position. For example:
/PRO=[RWED,RWED"RWED]
Here, a task running under the same UIC group as the file's owner
has no access.
You cannot specify protection options for a read-only common
region or the read-only portion of a multiuser task. A task
linked to a common region with an improper protection mask cannot
be installed.
The default is IPRO-[RWED,RWED,RWED,RWED].
IRON-option
(RSX-llM-PLUS systems only.) Informs the
region is or is not read-only_

system

that

common

The options are YES and NO. If /RON=YES, the region is installed
as
read-only.
If /RON-NO, the region is installed with
readlwrite access.
The IRON keyword overrides the effect of the /PRO keyword.
The default is IRON=NO.

I ROPAR=pname
(RSX-llM-PLUS systems only.) Indicates the read-only partition
(pname) into which the read-only portion of a multiuser task is
to be installed.
If the partition you specify does not exist, VMR issues a ~arning
message and attempts to install the read-only portion of the task
into the partition containing the read/write portion of the task.
The /ROPAR keyword overrides the Task Builder options.
The default is whatever was specified at task-build time.
10-26

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
/ SEC=op,tion
(RSX-IIM-PLUS systems only.) Places the Task Control Block
fo.r the task being installed in secondary pool.

(TCB)

The options are YES and NO. If /SEC=NO, the TeB for the task is
placed in primary pool instead of secondary pool. The /SEC
keyword is valid only for tasks whose names are in the form
.•• xxx or xxx$$$.
The default is /SEC=YES.
/SLV=option
Informs the system of the task's slave status.
The options are YES and NO.
If /SLV=YES, data sent to the
installed task is marked with the TI: of the sending task. When
the installed task receives the data, the system sets the task's
TI:
to that associated with the data. The /SLV=YES keyword
overrides the Task Builder's /SL switch.
If you specify /SLV=NO,
the TI: of the task does not change when the task receives data.
On RSX-IIM-PLUS, the /SLV keyword cannot be used with tasks whose
names are in the form ... xxx. These tasks are prototype tasks
and cannot be installed as slaved tasks.
The default is whatever was specified at task-build time.
/SYNC=option
(RSX-IIM-PLUS multiprocesso~ systems only.) Synchronizes task use
of a common, permitting several tasks to share a common and use
the common for synchronization. For example, if two tasks access
the same common, the JSYNC keyword ensures that only one of the
tasks executes at one time. This prevents the second task from
reading from or writing to the common while the first task is
executing.
The options are YES and NO. You can specify jSYNC=YES for two or
more tasks, but only one of the tasks can execute at one time.
If one of the tasks becomes blocked, the others compete to
execute.
The default is /SYNC=NO.
jTASK=taskname
Specifies the name you want to give the task.
The default is the name specified at task-build time or the first
six characters of the file name.
See the RSX-IIM System
Generation and Installation Guide or the RSX-IIM-PLUS System
Generation and Installation Guide for an explanation of multiuser
system defaults.

10-27

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
/Ule=[group,member]
Specifies the Ule for the task. The task's Ule determines the
file-protection class (system, owner, group, world) to which a
task belongs. You must use square brackets ([ ]).
You can use the /Ule keyword only when installing tasks started
by a RUN$ directive or started by a RUN command that specifies a
time delay. You can override the Ule with the RUN command.
Tasks installed with names of the form .. xxx and tasks started by
the RUN command without a time delay run under the protection Ule
of the terminal from which the command was issued.
The default is the Ule specified at task-build time.
/WB=option
(RSX-llM-PLUS systems only.) Specifies where a read/write common
will be checkpointed to. By default, a cornman is checkpointed to
a system checkpoint file.
The options are YES and NO.
If /WS=YES, the common
is
checkpointed to its original task image file. When the common is
removed, it is written back to its original task image file.
If
/WB=NO, the common is checkpointed to a system checkpoint file.
The common is not written back when removed.
If a common is read-only, there is no need to checkpoint it.
Therefore, the /WB switch is ignored when a common is installed
with /RON=YES.
If a common is installed with an increment, it will no longer fit
in its original task image file. Therefore, you cannot specify
both /INC=size and /wa=YES when installing a common.
The default is /WB=NO.
/XHR=option
(RSX-llM-PLUS systems only.) Specifies that the Executive's copy
of the task's header will be in an area external to the system's
dynamic storage region (pool).
The options are YES and NO. If /XHR=YES, the task is installed
with an external header. If /XHR=NO, the task is installed with
a resident header.
When you specify /XHR=YES, the task's header is not kept in pool.
Instead, a copy of the header is placed in a reserved area
immediately below the task image. The Executive uses the copy of
the header rather than the actual header. When the task is
checkpointed, the system writes the task image and the copy of
the header into the checkpoint file. The header in the task
image is left unchanged.
The /XHR'keyword correlates. with the /XH option for the Task
Builder.
The default for /XHR and the ability for a user to
override the option specified at task-build time depend on how
the INSTALL task was built during system generation.

10-28

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
You can change the effect of the /XHR keyword by selecting one of
several options.
The options determine the default action the
system takes when a task is installed. To select an option, your
system manager must modify INSBLD.CMD, the build command file for
the ·INSTALL task.
INSBLD.CMO must include the following command line:
GBLPAT == INSROT:$HODEF:/n
where n is the number of the desired option.
is 1.

The default

After the command file has been modified, the INSTALL task
be rebuilt and then reinstalled in the system with VMR.

option
must

You can select one of the following options:
1.

By default, every task is installed with an external header.
You can override this option by specifying /XHR=NO. This
option is provided for users who want their system always to
install
tasks with external headers.
The option also
prevents users from unnecessarily or accidentally using
headers in pool.
For existing RSX-IlM-PLUS sites, selecting this option allows
the use of external headers without having to rebuild the
nonprivileged application system.

By default, the headers for privileged tasks are in pool and
the headers for nonprivileged tasks are external. This
option can be overridden when a task is built or installed.
This option is provided for users who have user-written
privileged code that needs to be converted before it can
execute with an external header. The application system does
not have·to be rebuilt to use external headers.

By default, the headers for all tasks are in pool.
You can
override this option when the task is built (/xH) or when the
task is installed (/XHR==YEs). This option is provided for
users who have user-written ACPs or privileged code that
examines the header of another task.
If you select this option, you must either rebuild or install
a task with an external header (TKB /XH or INS /XHR=YES)
before it can execute with an external header.
Because any
user can specify the IXH switch, this option is recommended
for friendly environments.
(Only privileged users
can
specify the /XHRkeyword.)

By default, the headers for all tasks are in pool.
The
option can be overridden by a privileged user by specifying
IXHR=YES when the task is installed.
This option is similar to option 3, but it cannot be
overridden by the Task Builder's IXH switch. The option
gives the system manager more control over the environment
and must be selected for those systems that cannot allow any
code, including nonprivileged code, to execute with external
headers.
10-29

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
5.

By default, the headers for all tasks are ir pool.
This
option cannot be overridden. Selecting this option is not
recommended. The effect of the option is similar to choosing
a nonstandard Executive during system generation, so that
support for external headers is not included.
This option
must be selected, however,
for those systems that cannot
allow any code, including nonprivileged code, to execute with
external headers.

Note that the options do not apply to tasks that were built with
the /-XH switch specified.
The headers for these tasks are
always in pool when the tasks are installed, regardless of the
option selected, because the /XHR keyword cannot override the
/-XH switch.
Examples

Installs task SCAN using the default priority and directory.

Informs the system that the task SCAN is a CLI.
3•

1,1

('i j'" ! (,'

'::, " (I (.I 'F ' ! ' ! , F :::;

Requests the system to install SCAN and fix SCAN in memory.

Informs the system that the task SCAN
fast-mapping feature of the Executive.

Informs the system that
access to the I/O page.
6 •

i ,i ~i

.;,

J: ,; <:,

the

privileged

will

task,

use

the

SCAN,

needs

increases

the

i'; r::i C i ! I") i'" ;;,~, ,') i::, ,:,;, / F tJ F '; ,~: '( :~,; i" T !

Installs task MAC in the partition SYSCTL and
task size by 4096(decimal)-words.

Installs task SCAN, file type .TSK, version 4, from device
DM1:, group number 1, member number 111, with a priority of
103(octal).

Requests the system to install the task SCAN with
a
protection mask that permits tasks running under the same UIC
as the file's owner to have Read, Write, Extend, and Delete
access. Tasks with other UIC's are denied access.

10-30

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)

Informs the system that other tasks can share a common with
the task SCAN but that only one of the tasks may execute at
one time.

10.

VHk>INS Bon/WB=YFS
Specifies that the read/write common BOO will be checkpointed
to its original task image file.

Notes
1.

On RSX-llM systems, changes mad.e in a cornman are made only in
the memory image of the cornman. Therefore a cornman does not
retain changes when it is removed and then reinstalled.

On RSX-IlM-PLUS systems, changes made in the memory image of
a common can be preserved when the common is removed by
installing the common with the /WB=YES option.
If the common has been installed with the /WS=YES option, the
REMOVE command writes the common, with its changes, into its
original task image file replacing the original image.
When
the common is reinstalled, the new version of the common (as
it existed in memory when it was removed) is placed in
memory.

On RSX-llM-PLUS systems, you cannot use the INSTALL command
to install device commons that have been created with the SET
/PAR command.
(A device common is a special type of cornmon
that occupies physical addresses in the I/O page.)
When you use the SET command to create
the following operations occur:

device

partition,

If the device partition being created is the first device
partition in the system, the system automatically creates
a main partition called 10 PAR.
The partition being
created then becomes a subpartition of 10 PAR.

The system creates an entry for the new device partition
in the Common Block Directory (CBD) and inserts the
partition into the directory. The device partition is
now a device common.

Because the system creates a common block for the device
partition automatically, there is no need to install it as a
common. Attempting to do so results in an error message.
4.

When VMR installs a task in an unsaved system, it stores the
task's Logical Block Number (LBN) in the Task Control Block
(TCB). When you save a system, the SAVE command places the
file identification, rather than the file's LBN, in the TCB.
it opens the task file and
When the system is rebooted,
stores the task's new LBN in its TCB. If a task has been
deleted, the system cannot open the task file when the system
is rebootstrapped. The system then automatically removes the
task's TCB from the System Task Directory (STD).
10-31

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

INS (Cont.)
When VMR installs a task in a saved system image, it stores
the task's file identification, rather than the LBN, in the
TCB to allow a rebootstrap to occur successfully.
It is
important that a saved system image not retain the physical
disk addresses of the installed tasks because the Disk Save
and Compress Utility Program (DSC) or the Backup and Restore
Utility (BRU) can compress and copy a disk containing a saved
system, thus moving the task files to different physical
locations.
Because the TCB entries contain task
file
identifications rather than LBNs, the system can function
normally when it is rebootstrapped.

10-32

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

LOA
LOAD

Use the LOAD command to load a nonresident device driver into the
system image. LOAD either links a driver to an already resident data
base or loads a loadable data base with the driver.
This command
eliminates
the
need to link infrequently used device drivers
permanently into the Executive.
Executive support of loadable device drivers is a system
option on RSX-IIM but is always included on RSX-IIM-PLUS.

generation

Format

LOA[D] dd:[/keyword(s)]
Paramet.ers

dd:
A 2-character ASCII device name.
/keyword(s)
On.e or two of the following:

/CTB=cc[a, b, ••..•. J
/PAR=pname
/SIZE=psize
/VEC
Keywords

lC'rf);:cc(a ,b, ••. ]
(RSX-IIM ....PLQS ~yst.emsonly. )'l'he .ccvalu. is the name of the
multidriver •.•. . c9ntx-0ller . (C1'al that should be used instead of
$ddCTBit).the .loadabledaita base. .

[a.,p, ••• lare.. slots in the CTS'SKRB tablethatsho.uld
the K.RBa in the loadable data baae ..

point

The slots are named ArB,C,D,E,F,B,J,K,L,.M:,N,P,R,S, and.T.
The ICTBkeywordis used to load.adriverthatrefert)nces.a split
data bas·e..
Refer to the .SX...llM.... PLUSGuide~Wri tingan 1/0
.Q!·iver for more information.
/PAR=pname
The partition into which the driver is to be loaded.
value is name of the partition.

The

The /PAR keyword overrides the partition specified at
ti.me.

task-build

10-33

pname

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

LOA (Cont.)
/SIZE=psize
The minimum size of the partition
which the driver is to be loaded.

(psize)

octal-words

into

VMR rounds the partition size up to the next largest unit of
100(octal). The partition size must be less then 77741(octal).
/VEC
(RSX-IIM-PLUS systems only.) Informs the system that the driver
to be loaded is a vectored driver. This prevents the normal
comparison of the driver symbol table file and the system symbol
table file.
Examples
1.

VMR:>L.OA MM:
Loads the TU16 driver (MMDRV).

VMR>LOA

DK!/PAR=DRVPAR

Loads the RK05 driver (DKDRV) into DRVPAR.

VMR>LOA

DR:/CTB=RHB

Loads the RM03 driver
controller.

(DRDRV),

using

the

RHB

mUltidriver

Notes
1.

On RSX-llM systems, you can LOAD drivers above the 1 24K-word
limit.
See the description of the FIX command for more
information.

Guidelines for build~ng user-written, loadable device-driver
tasks are defined in the RSX-IIM Guide to Writing an I/O
Driver and the RSX-IIM-PLUS Guide to Writing an I/O Driver.

The LOAD command requires that a driver's .TSK and .STB files
reside in the same directory and on the same disk as the
system image file you are working on.
For example, the
command:
LOAD DT:
requires that the files DTDRV.TSK and DTDRV.STB reside on the
device SY:, under the current UIC.

The LOAD command requires the following pool space:
•

If the driver data base is being loaded, the
needs contiguous pool space equal to its size.

•

In a mapped system, each interrupt entry in the driver
needs pool space for an Interrupt Control Block (ICB).

•

If the driver is being loaded into a system-controlled
partition, the Partition Control Block (PCB) needs pool
space.
10-34

data

base

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

LUN
LOGICAl. UNIT NUMBERS
Use the! LUN command to display the static LUN assignments for a
specifi.ed task.
Static assignments are those recorded in the task's
disk i.mage file,
for example, those assignments
specified
at
task-build time.
The display consists of a list of physical device
units in one column and their corresponding LUNs in an adjoining
column.
Format
LUN[S] taskname
Paramet:er
taskname
The name of the task whose LUNs you want to display.
ExamplE!

VMR>I...LJN XKE
SYO: 1
SYO: "'")

CL.O:
TT:3:

TT3:
DKO:
TT3:

3
4
C~

b
."/

The display shows static assignments for LUNs
rE~corded
in the task image fi Ie header.
assigned statically to the task XKE.

10-35

1 through 7 as
No other LUNs are

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

PAR
PARTITION DEFINITIONS

Use the PARTITION command to display
partition in the system image.

description

each

memory

The partition display consists of columns that specify the following:

• Partition name
• Partition Control Block address (in octal)
• Partition base address (in octal)
• Partition size (in octal)
• Partition type
• Name of partition occupant(s)
On RSX-llM-PLUS, the symbols accompanying the partition name have
following meanings:
< ) active task

( ] in memory but inactive

+ + multius.er task (read-only section)
1 1

read-write named common

( ) driver
Format
PAR[TITIONSJ
Example
The following example is from a saved system:
Name

PCB

Base

Size

Type

Description

00010000
0001.:3000
001.40000

MAIN
MAIN
MAIN
DRIVER
flF: r VEF:
DRIVER
DRIVER
DRIVER
DF: I VER

<flK! )

'.JMF:>F'AF\
035720 00200300
03~6!,:j4 007.1.0300
DRVPAR 03~i610 00:)23300
035324 0027.3300
035260 00:.)27000

~:;YSF'AR

SF'LF'AR

03~'j21.4

03?.=i150
0351.04
0347"74
034T30
034664
0346::>0
')34~:;34

034470
034424
034360
034:.31.4
()3~.:5040

00003~OO

00001.300
0()230:·~OO 00003600
00:'):~41 00 00001600
O()235700 ()0004;~()0
00:)46400 0000:1300
00?47700 00OOt600
OO?~-:il.~iOO 00001 :)00
00·?~=.i27()0

00035~jOO

00310400
o 0 :3 :.~ 0 <'\ () 0
0033?OOO
o0 :.~ :.~ ~~:3 0 0
003.1,6400
00336500

00020000
00001.400
00001300
000031.00
00000:1.00
00004400

(DB!)
("OR: )
(DS: )
([1M: )
(DT!)

DI;:IVF.I~

( fiX: )

DRIVER
RW COM
DRIVER
DRIVER
flF: I '.JER
DRIVER
flF:IVFR
DRIVEr.:

(IF'! )

10-36

!TTCOM !
( TT : )
(RD: )
(VTt )
(CO: )
( NI. )

01 M : )

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

PAR (Cont.)
LDRPAR

00363300 00003000
033:'74 00363300 00003000
TSTPAR o3~;~; () () 00366:300 00040000
036454 00366300 00040000
SEC POl. 03~i434 00426300 00050000
GEN
0~55370 00476300 04701.500
03~i~j44

IJMF~>-

10-37

MAIN
TASK
MAIN
TASK
SEC

MAIN

<I.. {lR ••• ><SAVTO :>
POOL

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

REA
REASSIGN
Use the REASSIGN command to reassign a task's logical unit numbers
(LUNs)
from one physical device unit to another. REASSIGN has no
effect on the assignments for a task that is fixed or loaded in
memory.
The reassignments affect only the static assignments recorded
in the task's disk image file.
Format
REA[SSIGN] taskname LUN new:
Parameters
taskname
The name of the task for which the LUN is to be reassigned.
LUN
The logical unit number.
new:
The new device unit, which can be a physical, logical, or
device.
Examples

VMR>REA LODN 3 TTO:
Reassigns LUN 3 of task LODN to physical device TTO:.

VMR>RFA TFST 3 XX:
Reassigns LUN 3 of task TEST to logical device XX:.

10-38

pseudo

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RED
REDIRECT
Use the REDIRECT command to redirect all I/O requests
physical device unit to another physical device unit.

from

one

You cannot redirect the following:
•

The pseudo device TI:

•

A device to the pseudo device TI:

•

A pseudo device to itself

•

An attached device

•

A terminal to the null device.

You can redirect a logged-in terminal to a device other than a
terminal (except for the null device); however, it is not generally
advisable to do so because terminal I/O would be written to the
device, which could destroy the boot block.
If you do redirect a
terminal to another type of device, you should redirect the terminal
back to itself before you log out.
Format
RED[IRECT] new:=old:
Paramet.ers
new:
The new device unit to which requests will be redirected.
old:
The old device unit from which requests will be redirected.

VMR>RED TT3:=TT6:
Redirects all I/O requests for device TT6:

to device TT3:.

VMR>RED TT:=lP:
Redirects all I/O requests for device LPO:

10-39

to device TTO:.

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

REM
REMOVE
Use the REMOVE command to delete a task name and, on RSX-llM-PLUS
systems,
a region name from the System Task Directory.
Removing a
task from the system image makes the task unrecognizable to the
system.
The action resulting from this command is the complement of
INSTALL.
The REMOVE command cannot remove an active task from a saved system.
An example of such a task is SAV; an attempt to remove SAV from a
saved system results in an error message.
Format
REM[OVE] name(/REG]
Parameters
name
The name of the task, region, or directive common to be removed.

/REG
(RSX-IIM-PLUSsystems only.) Specifies that the
you specify is the name of a region.

name

parameter

You must specify this keyword when removing the directive
commons. To remove the commons, use the following command line:

VMR>REM DIR11M/REG
Note that When you remove DIRllM, you remove all of the directive
commons in the system.
Example
tv'

t"i R:> RF. M seA N

Removes the task named SCAN from the System Task Directory.
task image file remains unaffected.

The

Notes
1.

If a task or region that is the object of a REMOVE command is
fixed,
the command automatically unfixes the task from the
system image.

REMOVE automatically cancels all time-based schedule requests
for the specified task.

To remove a command line interpreter (CLI) task,
you must
first eliminate the CLI Parser Block (CPB) for the task with
the MCR CLI /ELIM command on the running system.
Then use
the MCR SAVE command to update the system image file, invoke
VMR, and remove the CLI. However, it is recommended that you
work
with
CLls
exclusively with MCR on the running
system -- this includes eliminating and removing old CLls,
and installing and initializing new ones -- and then save the
system.

10-40

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

REM (Cont.)
An exception to this note is the primary MCR task {MCR ... }.
The CPB for this task can never be eliminated and the task
itself can be removed only with VMR.
4.

On ~X-llM-PLUS systems, a region cannot be removed if there
are tasks installed in the system that reference that region.

On RSX-llM systems, changes made in a common are made only in
the memory image of the common. Therefore, a common does not
retain changes when it is removed and then reinstalled.

On RS:x:"'llM-PLUSsystems, changes made in the memory image of
a common can be preserved when thecotnmOn is retnovedby
installing the common with the /wa-YESoption.
If ,the cotnmon ls installed with the twa-YES option, the
conunandwritesthecommon, with 'its 'changes, into its
origin.al.taste, 'image £ile,replacingtheo;riginal image. When
the common isrein$talled, the new version a£the common is
placed in memory.
REMOVE"

10-41

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RUN
RUN
Use the RUN command to initiate the execution of an installed task.
You can use the RUN command to initiate the execution of a task at any
of the following time options:
•

At a time increment from the system image time

•

At a time increment from clock unit synchronization

•

At an absolute time of day

•

At one

cloc~

tick after the system bootstrap

All of these options are available,
Each option has a separate format.

with

without

rescheduling.

On RSX-llM-PLUS, you cannot run a task whose name is in the form
••• xxx or xxx$$$.
These tasks are prototype tasks, which are never
executed.
NOTE
The correct value to be inserted in the clock queue
for Formats 1 through 3 is derived from the current
value of the system time stored in the system image.
Therefore, the system image time must be set before
any RUN requests are made or they may not occur at the
correct time after the system is bootstrapped.
Format 1
RUN taskname time [/keyword(s)]
Runs the task at a time increment from the system image time.
Parameters
taskname
The name of the task.

A task name must be 1 to 6 characters.

time
The number of time units added to the current system image time
to determine the time at which the task will run; or, when used
with the IRSI keyword, the number of time units added to the time
of the task's last completed run to determine the time at which
the task will rerun.

10-42

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RUN (Cont.)
The time parameter has the following format:
mu
where:
m

The magnitude or number of time units to be clocked.
The maximum number of time units you can specify
depends on the type of time units you want to specify.
You can specify the following time unit magnitudes:
If you are specifying hours, m can be
• number
from 0 to 24(decimal).

any

positive

If you are specifying minutes, m can be any positive
• number
from 0 to l440(decimal).
If you are specifying seconds, m can be any positive
• number
from 0 to 32767(decimal).
•

If you are specifying clock ticks, m can
positive number from 0 to 32767(decimal).

any

If you are specifying a reschedule interval with the
IRSI keyword and specify a magnitude (m) of 0, the
magnitude defaults to 1.
For example, specifying
IRSI=OH is the same as specifying IRSI=lH.
The total time must not exceed 24 hours.
is decimal by default.

The magnitude

The type of time units to be clocked.
You can use
single letters to specify the following time units:
H - Hours
M - Minutes
S - Seconds
T - Ticks
A tick is a clock interrupt.
The rate at which
interrupts occur depends on the type of clock installed
in the system.
For a line frequency clock, the tick rate is either 50
or 60 ticks per second, corresponding to the line
frequency.
For a programmable clock, a maximum of 1000 ticks per
second is available.
(The frequency is selected at
system generation.)

10-43

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RUN (Cont.)
/keyword(s)
One or both of the following keywords:
/RSI=time
/UIC=[uic]
Keywords
/RSI=time
Specifies the reschedule interval.
The reschedule interval
informs the system when you want it to rerun the task.
Each time
the interval of time you specify lapses, the system issues an
initiation request for the task. The format for time is mu.
See
the description of the time parameter.
The default is no rescheduling.
/UIC=[uic]
Specifies the UIC for the task. The task's UIC determines the
file protection class
(system,owner,group,world) to which the
task belongs.
When specifying a UIC, you must use square
brackets ([ ]).
The default is the UIC established for pseudo device CO:.
Format 2
RUN taskname sync [time][/keyword(s)]
Runs the task at a time increment from clock unit synchronization.
The system determines the task run-time by waiting for the specified
time unit (sync) and then waiting for the specified time increment
(time) to elapse.
Parameters
taskname
The name of the task.

A task name must be 1 to 6 characters.

sync
Indicates the synchronization unit.
following synchronization values:
H MS T -

Synchronize on the
Synchronize on the
Synchronize on the
Synchronize on the

You

can

specify

the

next hour
next minute
next second
next tick

time
The time increment value,
if present, is
added
to
the
synchronization value to produce the time the task will be run.
The format for specifying time is provided in Format 1.

10-44

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RUN (Cont.)
/keyword(s}
One or both of the following:
/RSI=time
/UIC=[uic]
These keywords are described under Format 1.
Format 3
RUN taskname hh:rnrn:ss [/keyword(s}]
Runs the task at an absolute time of day.
Paramet:ers
taskname
The name of the task.

A task name must be 1 to 6 characters.

hh:rnrn:ss
The absolute time of day at which the task will be run.
The
letters in the format are replaced with decimal numbers and
indicate the following time units:
hh - Hours
rnrn - Minutes
ss - Seconds
/keyword(s}
One or both of the following:
/RSI=time
/UIC=[uic]
These keywords are described under Format 1.
Format 4
RUN taskname [/keyword(s}]
Runs the task one clock tick after the system bootstrap.
Parameters
tasknarne
The name of the task.

A task name must be 1 to 6 characters.

10-45

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

RUN (Cont.)
/keyword(s)
One or both of the following:
/RSI=time
/UIC=[uic]
These keywords are described under Format 1.
Examples

Runs task XKE 15 minutes from the current system image time.

Runs task XKE 15 minutes from the current system image time,
rescheduling it every 90 seconds. The task is running under
UIC [3,1].
3•

I.) j';' F~ ::: p \ N
.1

X,·:.: F H

~.:i M/ F.: ~) J :::: 1 H

Synchronizes with the system image time on the next hour,
runs the task XKE 5 minutes after synchronization, and
reschedules the task to run every hour after the last
completed run.

Runs task XKE at 5 minutes before midnight.

VMP>RUN XKE/RSJ=)M
Runs task XKE one clock tick after the system
reschedules the task to run 2 minutes later.

10-46

bootstrap

and

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SAY
SAVE

Use thE~ SAVE command to write the image of a system onto a sequential
medium in bootable format.
By using the SAVE command, you can copy an
RSX-llS system or a foreign system onto a tape or a diskette. You can
then t:ransport the magnetic tape or diskette to another computer and
bootstrap it, using a hardware bootstrap.
(Refer to the description
of the /IM switch in Section 10.4.)
On papE~r tape, system images are created in absolute loader format and
must be bootstrapped with the absolute loader.
Format
SAV[E] ddnn:[label][/keyword(s)]
Paramet:ers
ddnn:
The device unit onto which the system image is written.
command accepts the following devices:
CT:
DD:
DT:
DU:
DX:
DY:
MM:
MS:
MT:
MU:
PP:

The SAVE

Tape cassette
TU58 DECtape II
DECtape
RX50 diskette/RA60 disk/RC25 disk (removable)
RXOl diskette
RX02 diskette
TE/TU16/TU45/TU77 magnetic tape
TSll/TSV05/TU80 magnetic tape
TE/TUIO/TS03 magnetic tape
TK50 cartridge tape/TU8l magnetic tape
Paper tape

label
The file label name that must be specified for all devices except
paper tape.
The label name can be 1 to 12 alphanumeric
characters.
Keywords:
/ BOOT=t~ ype :
Specifies the type of boot block being used when the system image
is saved.
The options for type are DX:
(for RXOls) and DY:
(for RX02s).
The /BOOT keyword allows you to use an RXOI drive to bootstrap a
system that was saved using an RX02 drive in single-density mode,
or to use an RX02 drive to bootstrap a system that was saved
using an RXOI drive in single-density mode.
If you do not use /BOOT, the boot block for the
being used is written to the device.

10-47

type

device

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SAY (Cont.)
IOENS=1600
Specifies the bits·per inch
9-track magnetic tapes:
TE16

TU16

TU45

(bpi)

density

for

the

following

TU77

These tapes use the device mnemonic MM:.
Example

In this example, the system image is written onto MT:
in
bootable format.
System changes made by other VMR commands are
also saved with the system image.
Notes
1.

On RSX-llM and RSX-llS systems, the maximum memory size of a
system is l24K-words.
The SAVE command limits the size of
mapped systems for certain devices. If a mapped system is
saved and its memory size is greater than the maximum size
imposed by the SAVE command for the specified device, only
the amount of memory equal to the maximum size (starting at
physical location 0) is saved.
The devices for which the SAVE command imposes a maximum size
on saved system images are as follows:
Paper tape punch (pP:)

28K-words

Cassette tape (CT:)

28K-words

RXOl diskette' (OX:)

l23K-words

RX02 diskette (OY:)

l23K-words

When you save RSX-llS systems on paper tape and you do not
apply the 11M switch to the system's file name (refer to
Section 10.4 for a description of the 11M switch), the last
1000(octal) bytes of the system image are not written out.
This allows space to accommodate the absolute loader.
When
you specify the 11M switch with the system's file name, the
entire system image is written to paper tape. In this case,
it is your responsibility to ensure that the system image is
not so large that it overwrites the absolute loader.

When you bootstrap systems on media other than paper tape,
regardless of the size of the system image, the last
1000(octal) bytes of physical memory are not copied to
accommodate the bootstrap.

10-48

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SAY (Cont.)
4.

When you save a system on paper tape, contiguous blocks that
contain only zeros and begin on a 32-word address are
compressed into two words that contain the zero count.
This
compression significantly reduces both the amount of paper
tape required and the time expended to create the tape and
read it into memory. After the entire image has been loaded
into memory, a short routine writes zeroes
into
the
appropriate blocks of. memory before passing control to the
bootstrapped system.

Systems saved on a TE/TU10/TS03 9-track magnetic tape drive
can be bootstrapped from a TE/TU16 drive, and the reverse.

When you specify the /IM switch with the system file
specification, the SAVE command always uses a bootstrap that
does not enable memory management.

None of the bootstraps require that a target
have a driver for the bootstrap device.

Unless you specify /DENS=1600, when you save a system image
to a magnetic tape drive that supports mUltiple densities,
the drive is forced to 800 bpi before the SAVE operation is
started.

10-49

RSX-llS

system

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET
SET
Use the SET command to alter a number of system-wide characteristics.
The SET command allows you to do the following:
•

Set device characteristics for devices

•

Set default UICs for terminals

•

Set system UIC

•

Set and display terminal status

•

Create and eliminate partitions

•

Add space to the system dynamic memory

•

Enable write-checking and seek optimization
support it

devices

that

When using the SET command, a situation can arise in which the system
fails to accept privileged user input. To avoid this, the system
should have at least one nonslaved terminal and one privileged
terminal.
You need a privileged terminal because nonprivileged
terminals cannot enter privileged commands.
You need a nonslaved
terminal because slaved terminals cannot enter unsolicited input to
MCR. For more information, see the description of the /SLAVE keyword.

On RSlt... llM

systems,

number

'. .•.•. ...•

ltfJ~or~s

require: Bxecutive

feiltur:estlj!tt,·must.~j ~~~i\U~e(!l',:,t.: $~ •............ geneFat.if.on.' .I:f;:Yo~ ~p~~iel' a
keywor'(i .tht\1t. requ;t;r'~,,:.' 'feat;u~~ '.' .,.t:.g~~el!at~:;;tll~o . tJ\e,ys~eJB .' ;image,
the SET.Cf>mma:nd'h~II. ri.<:p . ~:fie<::i;' ~d.X't~ults ·i~a~errQrmes'a.ge.:. '. Some
ofth.. SB~}ikeywor(ts\:th~trequ*%1e .x.c:~ttiiv_ f ••tutea ate
l~sCSBo.
/LOWER,an~ IWOHK~':

.,eR,.

In addition, some of the SET keywords are supported with the
full-duplex terminal driver only. The full-duplex terminal driver is
a system generation option for RSX-IIM systems, but is always included
in RSX-IIM-PLUS systems.
Note that if you select the full-duplex
driver on RSX-IIM, you must also select the GET/SET
Multiple
Characteristics
option
to SET or display any terminal-related
characteristics.
VMR permits only one keyword per command line. You can prefix most
keywords by NO to negate or disable the function of the keyword. VMR
returns a syntax error message when NO precedes a keyword for which it
is illegal.
Examples of the SET command follow the keyword descriptions.
Format
SET /keyword[=value]

10-50

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
Parameter
/keyword[=value]
The following table provides a functional listing of the SET
keywords.
You can use one keyword per command line with the SET
command.
Table 10-2
SET Keywords
Type
De!vice
Characteristics

Keywords
/ABAUD[=ttnn:]
/ANSI[=ttnn:]
/AVO[=ttnn:]
/BLKMOD[=ttnn:]
/BRO[=ttnn:]
/BUF=ddnn:[size]
/CRT[=ttnn:]
/DEC[=ttnn:]
/EBC[=ttnn:]
/ECHO[=ttnn:]
/EDIT[=ttnn:]
/ESCSEQ[=ttnn:]
/FDX[=ttnn:]
/FORMFEED[=ttnn:]
/HFILL=ttnn:[value]
/HHT[=ttnn:]
/HSYNC[=ttnn:]
/LINES=ddnn:[value]
/LOWER[=ttnn:]
/OPT[=ddnn:opttyp]
/PARITY[=ttnn:[option]]
/PASTHRU[=ttnn:]
(continued on next page)

10-51

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
Table 10-2 (Cont.)
SET Keywords
Type
Device
Characteristics
(cont. )

Keywords
/PRINTER_PORT[=ttnn:]
/PRIV[=ttnn:]
/PUB[=ddnn:]
/REGIS[=ttnn:]
/REMOTE[=ttnn:[speed]]
/RPA[=ttnn:]
/SERIAL[-ttnn:]
/SLAVE[=ttnn:]
/SOFT[=ttnn:]
/SPEED=ttnn:[recv:xmit]
/TERM=ttnn:[type]
/TTSYNC[=ttnn:]
/TYPEAHEAD[=ttnn:[size]]
/UIC=[[uic]:]:ttnn:
/VFILL[=ttnn:]
/WCHK[=ddnn:]
/WRAP[=ttnn:]

Enable/Disable
Login

/LOGON

Library, Network,
or System UICs

/LIBUIC[-[uic]]
/NETUIC[=[uic]]
/SYSUIC[=[uic]]

Memory
Allocation
(see Notes)

/BOT=pname:value
/MAIN-pname[:base:size:type]
/NOMAIN=pname
/MAXEXT[=size]
(continued on next page)

10-52

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
Table 10-2 (Cont.)
SET Keywords
Keywords

Type
ME~mory

/PAR==pname(:l:>aselsizet:t.ype]]

Allocation
(cont.)

/NOPU==pname
/POOL[=top]
/POOLSIZE[=value]

Is ECPOL
/Sus-mname:sname[:base:size]
/NOSUS-mname:sname
/TOP=pname:value
Pool
Monitor Task

/PLCTL[=[high][:[low][:[frsiz][:basep]]]]

System
Tuning

/RNDC[=nn]
/RNDH[=nn]
/RNDL[=nn]
/SWPC[=nn]
/SWPR[=nn]

Keywords:
/ABAUD[=ttnn:]
(Full-duplex terminal driver only.) Enables autobaud detection
for the remote dial-up line for the specified terminal. The
tE~rminal driver samples the line's first input
character, tries
to determine the incoming speed, and sets the interface speed
accordingly.
When you omit the terminal specification, VMR
tE~rminals with autobaud detection.

displays

all

the

/NOABAUD[=ttnn:]
(I~ull-duplex terminal driver only.) Disables
autobaud detection
for the specified terminal. The terminal driver does not attempt
to determine the incoming speed for the remote dial-up line.

When you omit the terminal specification, VMR displays
tE!rminals that do not have autobaud detection.

10-53

all

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/AFF=[UNIBUS-run-mask, ... ]
(RSX-llM-PLUS multiprocessor systems only.) Specifies which I/O
page will contain the device partition. This keyword is required
for creating device partitions on the system.
You must specify at least one URM.
brackets ([ ]).

Enclose the URM(s) in

If you specify more than one
commas.
For example:

you

URM,

must

separate

square
them

/AFF=[UBE,UBF,UBH]
UNIBUS-run-mask
The three-letter name of the URM with which the device
partition is associated. The following names are valid URM
specifications:
CPA
CPB
CPC
CPD

UBE
UBF
UBH
UBJ

UBK
UBL
UBM
UBN

UBP
UBR
UBS
UBT

If you specify more than
You must specify at least one URM.
URM, you must separate them by commas.

one

You must enclose the URM specification in square brackets ([ ]).
For example, to create a device partition that is mapped to CPA's
I/O page, enter the following command line:
SET /PAR=DEVP:177600:200:DEV/AFF=[CPA]
/ANSI[=ttnn:]
(Full-duplex terminal driver only.) Informs the system
specified terminal supports ANSI escape sequences.

that

the

When you omit the terminal specification, VMR displays
terminals that have the ANSI characteristic set.

all

the

(Full-duplex terminal driver only.) Informs the system that
specified terminal does not support ANSI escape sequences.

the

When you omit the terminal specification, VMR displays
terminals that do not have the ANSI characteristic set.

aI'l

/NOANSI[=ttnn:]

/AVO[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified VT100-series terminal has the advanced video option.
This option gives the terminal the capability to blink, bold, and
flash parts of the screen, and to set the screen at l32(decimal}
columns.

10-54

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
If the word SET-UP blinks in set-up mode, the
advanced
video option.
See your system
information.

terminal has the
manager for more

Mlen you omit the terminal specification, VMR displays
tE~rminals that have the advanced video option.

all

the

(1?ull-duplex terminal driver only.) Informs the system that
specified terminal does not have the advanced video option.

the

Mlen you

all

/NOAVO[=ttnn:]

tE~rminals

omit the terminal specification, VMR displays
that do not have the advanced video option.

/BLKMOD[=ttnn:]
(Full-duplex terminal driver only.) Enables local
block-mode transmission for the specified terminal.

editing

Mlen you omit the terminal specification, VMR displays
tE~rminals that have the block-mode option enabled.

and

all

the

editing

and

/NOBLKMOD[=ttnn:]
(1?ull-duplex terminal driver only.) Disables local
block-mode transmission for the specified terminal.

Mlen you omit the terminal specification, VMR displays
tE~rminals that have the block-mode option disabled.

all

the

/BOT=pname:value
Directs VMR to move the bottom boundary of the specified
system-controlled
partition (pname) up or down the amount
indicated by the value parameter. The /BOT keyword modifies the
bottom boundary of a partition even though it has tasks installed
in it. If you modify the partition so that it becomes too small
to hold the tasks installed in it, VMR displays a warning message
but modifies the partition anyway.
pname
The 1- to 6-character alphanumeric partition name.
value
The number of 64-byte blocks.
The value parameter can be supplied in five formats:
+value, -value, value, +* or *, and -*
These are described
as follows:
+value
Moves the partition's bottom boundary up the amount
indicated by the specified value. Moving the bottom
boundary up makes the partition smaller.

10-55

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)

NOTE
You must supply the value in the same units as
those of the base and size parameters for the
IPAR keyword.
-value
Moves the partition's bottom boundary down the amount
indicated by the specified value. Moving the bottom
boundary down makes the partition larger.
value
Moves the partition's bottom boundary until the
partition size is equal to the specified value.

total

+* or *
Moves the partition's bottom boundary up as far as
possible.
Note that using this format will cause the
bottom boundary to move up to the bottom of the first
fixed task or fixed driver loaded into the partition at
the time the IBOT keyword is executed.
If there is
nothing loaded into the partition, it assumes a size of
one 64-byte block.

-*
Moves the partition's bottom boundary down as far as
possible.
Using this format will cause the bottom
boundary of the partition to move down to the top
boundary of the partition below it, or to the top of
the Executive pool if the partition is the lowest
partition in memory.
/BRO[=ttnn:]
Enables the broadcast option for the specified terminal.
The
terminal can receive messages sent from other terminals with the
MeR BROADCAST command.
When you omit the terminal specification, VMR
terminals that can receive messages.

displays

all

the

The IBRO keyword is valid only on systems with multi-eLI support.
/NOBRO[=ttnn:]
Disables the broadcast option for the specified terminal.
terminal cannot receive messages sent from other terminals.

The

When you omit the terminal specification, VMR
terminals that cannot receive messages.

the

The INOBRO keyword
support.

valid

only

10-56

displays

systems

with

all

multi-eLI

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/BUF=ddnn:[size]
Sets the default buffer size of the specified device.
The size
you specify must be from 0 to 255(decimal).
(For a terminal, the
size you specify must be greater than or equal to 15(decimal».
The /BUF keyword is particularly useful for defining line printer
width (for example, 80 or 132 columns).
When you omit the size specification, VMR
buffer size of the device.

displays

the

current

/CRT[=ttnn:]
Informs the system that the specified terminal is a cathode ray
tube (CRT) terminal and enables the backwards deletion option.
When the backwards deletion option is enabled, pressing the
RUBOUT or DELETE key moves the printing position one space to the
left and erases any character displayed in that position.
When you omit the terminal specification, VMR
terminals that are defined as CRTs.

displays

all

the

Informs the system that the specified terminal is not a
disables the backwards deletion option.

CRT

and

When you omit the terminal specification, VMR
terminals that are not defined as CRTs.

all

the

/NOCRT[=ttnn:]

displays

/DEC[=ttnn:]
(Full-duplex terminal driver only.) Indicates that the specified
terminal is upward-compatible with the VT100-series of terminals.
When you omit the terminal specification, VMR
terminals that are upward-compatible.

displays

all

the

/NODEC[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified terminal is not upward-compatible with the VT100-series
of terminals.
When you omit the terminal specification, VMR
terminals that are not upward-compatible.

displays

all

the

/EBC[=ttnn:]
(Full-duplex terminal driver only.) Enables the 8-bit character
option.
The terminal driver passes all eight bits of the
characters to the specified terminal.
When you omit the terminal specification, VMR displays
terminals that have the 8-bit character option enabled.

10-57

all

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/NOEBC[=ttnn:]
(Full-duplex terminal driver only.) Disables the 8-bit character
option.
The terminal driver clears the eighth bit of the
characters before passing them to the device.
When you omit the terminal specification, VMR displays all the
terminals that do not have the 8-bit character option enabled.
/ECHO[=ttnn:]
Enables the echo option.
The terminal driver displays
character that is typed on the specified terminal.

each

When you omit the terminal specification, VMR
terminals that have the echo option enabled.

the

displays

all

/NOECHO[=ttnn:]
Disables the echo option. The terminal driver does not
the characters that are typed on the specified terminal.

display

When you omit the terminal specification, VMR
terminals that have the echo option disabled.

all

displays

the

/EDIT[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified terminal can perform ANSI-defined advanced editing
functions. The VTI02 is an example of such a terminal.
When you omit the terminal specification, VMR displays all
terminals that can perform the advanced editing functions.

the

/NOEDIT[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified terminal cannot perform ANSI-defined advanced editing
functions.
When you omit the terminal specification, VMR displays all the
terminals that cannot perform the advanced editing functions.
/ESCSEQ[=ttnn:]
Enables the recognition of escape sequences from the specified
terminal.
The terminal driver treats the ESC character as the
beginning of an escape sequence rather than as a line terminator.
(See the RSX-IIM/M-PLUS I/O Drivers Reference Manual for further
information about escape sequences.)
When you omit the terminal specification, VMR
terminals that recognize escape sequences.

displays

all

the

specified

/NOESCSEQ[=ttnn:]
Disables the recognition of escape
terminal.

sequences

the

When you omit the terminal specification, VMR displays all the
terminals
that
do not support the recognition of escape
sequences.
la-58

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/FDX[=ttnn:]
(Full-duplex terminal driver only.) Enables the full-duplex
option.
The terminal driver accepts input from the specified
terminal while simultaneously outputting to it.
When you omit the terminal specification, VMR displays
terminals that have the full-duplex option enabled.

all

the

/NOFDX[=ttnn:]
(Full-duplex terminal driver only.) Disables the full-duplex
option.
The terminal driver will not process input and output
from the specified terminal simultaneously.
When you omit the terminal specification, VMR displays all
terminals that do not have the full-duplex option enabled.

the

/FORMFEED[=ttnn:]
Informs the system
hardware form feed.

that

the

specified

terminal

When you omit the terminal specification, VMR
terminals that support hardware form feeds.

supports

displays

all

a
the

/NOFORMFEED[=ttnn:]
Informs the system that the specified terminal does not support a
hardware form feed.
When you omit the terminal specification, VMR displays all the
terminals on the system that do not support hardware form feeds.
/HFILL=ttnn:[value]
(Full-duplex terminal driver only.) Specifies the number of fill
characters (value) that the terminal driver is to place after a
carriage return when outputting to the specified terminal.
The
value is a number from a through 7.
When you omit the value parameter, VMR displays the number of
fill characters currently being output by the terminal driver to
the specified terminal.
/HHT[=ttnn:]
(Full-duplex terminal driver only.) Indicates that the
terminal supports a hardware horizontal tab.

specified

When you omit the terminal specification, VMR displays all the
terminals on the system that support a hardware horizontal tab.
/NOHHT[=ttnn:]
(Full-duplex terminal driver only.) Indicates that the
terminal does not support a hardware horizontal tab.

specified

When you omit the terminal specification, VMR displays all
terminals that do not support a hardware horizontal tab.

10-59

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/HSYNC[=ttnn:]
(Full-duplex terminal
synchronization.

driver

only. )

Enables

host-terminal

Host-terminal synchronization controls the typeahead buffer to
prevent it from overflowing. When the typeahead buffer is full,
the system temporarily locks the terminal keyboard by generating
a CTRL/S which prevents you from entering more information.
Once the terminal is able to transmit all of the information in
the typeahead buffer to the operating system, the system unlocks
the keyboard by generating a CTRL/Q which allows the terminal to
receive input.
The /HSYNC keyword is recommended for users with terminals that
transmit information in blocks, for example, the DIGITAL VT131
and VT132 terminals. It is also recommended for users with
terminals that emulate these models.
If you do not have one of
these terminals it is unlikely that you will fill the typeahead
buffer.
To change the size of your typeahead buffer, use the
/TYPEAHEAD keyword.
/HSYNC is the default for the VT100-series of terminals.
When you omit the terminal specification, VMR displays
terminals that have host-terminal synchronization.

all

the

/NOHSYNC[=ttnn:]
(Full-duplex terminal driver only.)
Disables
synchronization for the specified terminal.

host-terminal

Disabling synchronization means that when the typeahead buffer
for the terminal is full, the system does not lock the keyboard,
and subsequent input is lost.
/NOHSYNC is the default for VT52 terminals.
When you omit the terminal specification, VMR displays all
terminals that do not have host-terminal synchronization.

the

/LIBUIC[-[uic]]
(RSX-llM-PLUS systems only.) Directs the INSTALL command to
search the specified UIC in response to a RUN $file or INS $file
command when the file is not in the system UIC.
The UIC is in the format (g,m], where g and m are octal numbers
from 1 through 377(octal) that represent a group and member
number, respectively. You must use square brackets «( J).
When
you omit the UIC specification, VMR displays the current library
UIC.
The defalllt library UIC is [3,54].

10-60

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/LINES=ddnn:[value]
(Full-duplex terminal driver only.) Establishes the number of
lines per page on the specified device. The value is a number
from 1 through 255(decimal). If you specify a number that is
larger than the number of lines per page possible for a given
device, VMR defaults to the largest number possible for that
device.
you omit the value parameter, VMR
page for the specified device.

WhE~n

displays

the

lines

per

/LOGON
Enables logging in on terminals in a multiuser protection system.
/LOGON and /NOLOGON clear and set a flag checked by
command when a user attempts to log in on a terminal.

the

HELLO

/NOLOGON
Disables logging
system.

terminals

multiuser

/LOGON and /NOLOGON clear and set a flag checked by
cOllunand when a user attempts to log in on a terminal.

protection
the

HELLO

/NOLOGON provides a means of preventing users from accessing the
system during such activities as system maintenance or account
file maintenance.
/LOWER[ :=t tnn : ]
Specifies that lowercase characters are not
converted
uppercase when received from the specified terminal.

Wh4~n

you omit the terminal specification, VMR displays all
terminals for which lowercase characters are not converted.

the

/NOLOWElR[=ttnn:]
Resets the terminal characteristics of the specified terminal so
that lowercase characters received on input are automatically
converted to uppercase and echoed as uppercase.
Whlen you omit the terminal specification, VMR displays all
terminals for which conversion to uppercase is specified.

the

IMAIN=pnamer:'basel$ize:typ~]

(RSX...;11 M syst.emsonlY_·) E'tabllshescimain p.t't.itiO.~

pname
The 1-t06:"e~aract.e.r . . a.lphanumet:fC!.Pi1~~iflC)n name~
base
The phyaicalbase .address of the partition
number of 64-byte blocks.

10-61

specified

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
size
The size of the p~rtition speclfied , "as a number of 64-byte
blocks. The maximum s.ize is 0 to 1920K ....wprds for a. task, common,
or main part! ti<!>n. .i
type

,he parti~*on type.

You .can assign the following

partition

t.ypes:

$YS

Assign an sYS~rtitiontype. for a
~in~.r;1;.iti()ns
are allocated for
load.able·;dr ivera ..

main
user

partition.
tasks and

Assign a COlt pax;-tittontype for a common partition.
DEV

Ass!gna;DEV pa:rtitiont.ypefor a oommonpartition t.hat
maps.thedevioe registers.
Devioe partit.ions are
allocatedfor~vlce, oOl,'OmOns~hat.are usedJ;>y tasks
to
acces's the c:levioe registers on the I/O page.

Assign a TASK partition type for a task partition.
You c~n enter base an(1size in any of t1,\e following fprmats:
:Calculated Value

nnnn
nnnn••
hnnK
nnn.K

Ootal,(nnnn*lOO)
'Deeima,l (nnnn.*64.)
Oot.al K(nnn*4000)
Decimal K(nnn.*2048oo)

where nnnn is a ~qmberto which a
appli.dto determ~ne thevalue'used.
values are:
Octal
t)eoimal
Ootal K
beclina1 K

O<-'base<177177
G.<-base<65535
QK<-base<3771K
C).K<-base<2()47.K

Jtu,ltiplication factor is
Valid range$ of calculated
0<size<2000
0,. <,slze<1024.
0i«slze<40K
OjOl«size<32.:1(

FQr.st~controlledp.rt.it.i~ns" si$etnal" range front' 0 to
or any valio represent.atl()n of th;eselim;i.tIJ.

19201<

You ca.n specify tbt 'baseaddrE!$~ot a partition with '" a wildcard.
( * ):£orTASK " or 'SYS·' partitions .in a maPped sy:ste~. ,When you
speo:i.;fy awilda~~d.. VNRC:lfeat,s ~,' part.i~ion at the lowest address
possi;blefor apart-it-ionof the size you have specified.

10-62

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
j:ot~'~~~,~i.~~··9~,···~·J>~~~~~~~p.~~¥b • ~iw~14(:11~~ fQX'
':';"'~~'>"~~::,,,~oi~:'tbie~dl~~~~7<t>~ ....'
. '.' t.*. ". t.he
...~~'~~o~·~'t.l;''t.i.n9>a'ttbeba$ea:<!ayou

have

~s~ ,>~~cun.~.J:.

a:n<! j'aej VNa
t.'he :f1rst. 9~J>,i.~ *,'b.e
>~"' t.he
••• :

•

eo ·';rta.me<!

.~ .~11K>4lr.Jll~ct;Ys

l'l..from

romithe

•• :are
1'$ not

/MAXEXT[=size]
Establishes the maximum size to which a task can extend itself
beyond its mapped array area by means of the EXTEND TASK
directive.
(See the RSX-IIM/M-PLUS and Micro/RSX Executive
Reference Manual for a description of the directive.) The size is
given in units of 32(decimal)-word blocks.
The maximum size
allowed is 1777(octal) for systems without memory management and
177777(octal) for systems with memory management.
You can specify size in the following formats:
Specified
Size
n

n.
nK
n.K

Resulting
Size
(n*lOO) octal
(n*64.) decimal
(n*4000) octal
(n*2048.) decimal
1777(octal) maximum for systems without PLAS
177777 (octal.) maximum for systems with PLAS

Wlum you omit the size specification, VMR

displays
maximum extension size in 100(octal)-byte units.

the

current

ThE~ /MAXEXT keyword is valid only on mapped RSX-IIM systems
that
have selected the EXTEND TASK directive option during system
generation and on all RSX-IIM-PLUS systems. However, you can use
b01:h the unmapped and mapped versions of VMR to establish the
maximum extension size for tasks.

/NETUIC[=[uic]]
the UIC in which all DECnet-related tasks are stored.
/NETUIC keyword applies only to systems that select the
external communication products option during system generation.

SpE~cifies

ThE~

10-63

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
The UIC is in the format [g,m], where g and m are octal numbers
from 1 to 377(octal) that represent a group and member number,
respectively. You must use square brackets ([ ]).
When you omit the UIC specification,
network UIC.

10-64

VMR

displays

the

current

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)

'fllepartd.tiC)n type.
types:

You can assign the following

partition

S'fl
~s8i<jnillS'fSpartition type
'Jl>a~tl.tions
are allocated

for amain partition. Main
for user tasks and loadable

drivers.

A$~i~n~IICPOL'partition

partition"
po()l.

type for a.secondary pool
Pool·. partitions are allocated .for secondary

Assign a DE'Vpartition type fora common partition that
maps ....thf! ..... devic., •.. registers. . Device pat"titions are
allocate'd£ordev!cecommons.that . tasks use to access
t;.lle.4eY'ice ..... x-eglsters . . on . the .... I/O . page.
Note that
cr.ati~9· . ·.a . · device .' • partition
automatically . creates a
mainpartitionna.Jlled 10 PAR, which spans the entire I/O
page.···.··'1'hepartition you .·specifywith ··the /PAR keyword
thsI1 . . Qscolltesa
subpartition
of
10
PAR.
On
IItUltipfo~ess()r sYtitems,you must use the
/AFF keyword
to .•. ~".cify
which
I/O page contains the device
pairti.t;.l.on...

A.ssighaCPQpat"tition type for CPU partitions.
CPU
par~it~ons .a:rs .. allocated·onmu~t.iprocessor systems to
stQreiv:e~tQ;relfo):all the devices associated
with the
part:i.cularproce$sor •
. .

The.p~x-t.l.tiQntypei.$oPtional.

Howeve~, .if you. do not specify a
partition type ,S~S .is th.e defaul t partition type assigned.

You oan.enter the base and si2';e in any Of the following formats:
CalcUlated.Value
nnnn
nnnn.
nnnK
nnn.K

O'ctal( nnnn* 100 )
Decimal (nnnn.*64.)
OctalK'Cnnn*4000)
Decimal K( nnn • *2048 .)

whe~ennnnis

a nUmber to which a
applied to determinet.he value used.

multiplication

factor

WhenY9u,a r eestablishing the base and size for a CPU partition,
note that the entire CPU partition must exist below l24K.

10-65

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
For SYS partitions, size can range frQm,O.to19;aOf(:or any valid
representatio~ of . these .. limit,s..J?Olt .~xampl~,< . tlj;e;fOl.lowing
inputs for size allocatee.•.204e(decimal ) ....}:)yte pa~tlti<>n.
40

32.
lK
1.K

You can .specify . the base .addressQf ap~rt+.tionwit.h . . . a .. wildcard
(*) • When you. spec·ify aw!ldcard,VMR cre~tesa pa,~tition.atthe
lowest addre&$possi'blefora p_rtition of thesizt you have
specified.
Toucan also specify the$izeof·a partit~on.with a .·wildc:ard.
When you specify a . . wj.ldoard,VMRcreat.es the largest. pos$ible
partition starting at the base adldressyou.,<specified in •the base
param.ter.
When you spe¢~Jya~ildcaf<i .f<?ra CPU E>ctr't~tion, . . VMR: creates a
parti eion of... size!. (l}-1)~4EC/wl1eFe n iathe ntuiber of processors
specifieddurt~9 $yst~m9~eratj.6.n.

When ou ,pe.~~~,~i~4daX'... fC!~:I?()t.1tt'~~i;:rbas~
creat.ts tP~~ti
n ~~t cQJnPl:i,tel, f,i~~s t.h.·
exist'ng 'pa~tJ.;'t'o~ .¥()~t.~
If .yo. dO: not.:~~e~t:~y:
valu~. pftl:te~ __ pa';t"~~t. . . . . . . . . . . . ~Of

t ." '.

:apeli .i~.e,

'rsiI;.,ap·:Ln the

'i\!~! ...dts'~.J'8·. ·the

t;itiQ~;.L . Jf.!th". ,~amed

partii-ion: is" ~ma1.ntp~rt:4~~n~
of all its subpartlftionsi • .

tbe:' pa:r;a:m,ters

/NOPAR-pna1Jle
(RSX:"'llM-PLU$ '$J!sterns·onl,;,.l 'li.lrtat~sa :na~e<1 . ~r!i'~Qn.from
the .$yet'm •. , ..<The • . . p.rti~:iQn> Y:'<)ills~ec~f¥ '" ;1$ e~.l.1n~a"e4ifromthe
list of partitions and th',$ysteJn~ .If,ny"taES1<.s:o~
insta~led.. in ..... oraitt~oh~41t.O/t~Et part.it.i~l!' ·tbe
elimil'lat.e<!i,andVMR generates<an i err<;>rl8es$age.
/PARITY[=ttnn:[option]]
Enables parity generation and checking.
selects the state of the parity bit.

The option

you

specify

Parity checking is used to verify the transmission of data
between a terminal and the operating system. Verification occurs
by sending an extra bit with each character called the parity
bit, which serves as a check that the transmitted character was
received properly.
If you do not
transmitted.

enable

parity

checking,

parity

bits

are

not

The options for /PARITY are EVEN and ODD.
The state of the
parity bit, which is either 0 or I, is determined by the option
you specify. If you do not specify an option, VMR defaults to
EVEN.

10-66

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
If you specify /PARITy=ttnn:EVEN, either a 0 or 1 is added, to
make the total number of 11111 bits even.
If you specify
/PARITy=ttnn:ODD, either a 0 or 1 is added, to make the total
number of "III bits odd. The system checks parity on input from a
terminal. The terminal checks parity on output from the system.
A parity check does not return an error when an EVEN parity is
specified and an even number of bits are counted, or, when an ODD
parity is specified and an odd number of bits are counted.
Note that the terminal hardware must be set to the same mode of
parity generation and checking as the system for correct data
transmission to occur. On the VT200-series of terminals, this is
done through the terminal's SET-UP mode.
The /PARITY keyword is not related to the /EBC keyword.
8-bit character option clears the eighth data bit only.

The

When you omit the terminal specification, VMR
terminals that have parity checking enabled.

the

displays

all

/NOPARITY[=ttnn:]
Disables parity
terminal.
Data
is not verified.

generation and checking for the
specified
transmitted between the terminal and the system

Wh.en you omit the terminal specification, VMR displays
te'rminals that do not have parity generation and
en.abled.

all the
checking

/PASTHRU[=ttnn:]
(F'ull-duplex terminal driver only.) Requests the system to ignore
the
original function of special characters typed at the
specified terminal and, instead, pass them to a program in their
binary form.
/PASTHRU allows you to suppress standard operating
system
re!sponses to special characters (for example, CTRL/C and CTRL/O),
thereby controlling output to the terminal screen.
While /PASTHRU is enabled, the terminal does not recognize any
control characters, except CTRL/S and CTRL/O if it is set to
/'I'TSYNC, nor does it respond
to
carriage-return/line-feed
characters.
If your terminal does not seem to be
have been set to /PASTHRU.

working

properly,

may

When you omit the terminal specification, VMR
te!rminals that have been set to /PASTHRU.

displays

all

the

/NOPASTHRU[=ttnn:]
(E'ull-duplex terminal driver only.) Requests the system to
recognize the original function of special characters typed at
the specified terminal.

10-67

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
When you omit the terminal specification, VMR
terminals that have not been set to /PASTHRU.

displays

all

the

/NOPASTHRU is the default.
/PLCTL[=[high][:[low][:[frsiz][:basep]]]]
(Systems with pool monitoring support only.) Sets the pool limit
parameters used by the Pool Monitor Task (PMT). The following
list defines the parameters:
high
The high pool limit in bytes.
low
The low pool limit in bytes.
frsiz
The minimum byte size of the largest free pool block
required for avoiding low pool actions by the Pool Monitor
T ask ( PMT ... ) .
basep
The base task priority, which is the lowest priority a
nonprivileged task can have and still be eligible for memory
contention during times of low pool; this priority remains
in effect until pool conditions improve.
(Note that only
those tasks requested to run while the system is in a low
pool state are affected).
The following list defines the limits of the parameters:
84.

<=low <=high <=total size of system pool

84.

<=frsiz <=high

<=basep <=250.

The following list gives the defaults for the parameters:
high

1600. bytes

low

600. bytes

frsiz

200. bytes

basep

51.

See Chapter
parameters.

for

information

determining

When you omit the parameter specifications,
current parameters for the system.

10-68

VMR

values

for

displays

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/POOL[=top]
Increases the size of the dynamic storage region (pool).
top
The first location in memory used for partition allocation.
You specify top in units of 64-byte blocks, in octal or
decimal.
When you do not specify top, VMR displays the virtual
address of the top of the Executive, the size of the longest
block of pool space in words, the total number of words in
the pool, and, on RSX-IIM-PLUS, the lowest physical address
at which a partition can start.
(You can use the address
when calculating partition layouts for systems supporting
kernel data space. If your system is not a kernel data
space system,
this value is always equal to the virtual
address of the top of pool.) The display's format is:
POOL=top:max:total[:par]
where top is given in units of 64-byte blocks, max and total
are in decimal words, and par is the lowest physical address
(32-word blocks).
You can also specify top by using 'a wildcard (*).
The
wildcard directs VMR to supply the maximum amount of pool
possible. Specify the wildcard as follows:
/POOL=*
If you request more pool than can be supplied, VMR prints a
warning message and supplies the maximum amount of pool
possible.
/POOLSIZE[=value]
Increases the size of the dynamic storage
value you specify indicates the total
allocated.

region
amount

(pool).
The
of pool to be

If you do not specify a value, VMR displays the virtual address
of the top of the Executive, the size of the longest block of
pool space in words, the total number of words in the pool, and
on RSX-I1M-PLUS systems, the lowest physical address at which a
partition can start (32-word blocks).
The /POOL and /POOLSIZE keywords perform the same function.
/POOL allows you to specify the top of pool. /POOLSIZE allows
you to specify the total size of pool.
/PRINTE:R_PORT[=ttnn: ]
(F'ull-duplex terminal driver only.) Informs the system that the
specified terminal has a printer port.
The VT200-series of
te!rminals, for example, has printer ports.
When you omit the terminal specification, VMR
te!rminals that have a printer port.

10-69

displays

all

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/NOPRINTER_PORT[=ttnn:]
(Full-duplex terminal driver only.) Informs the system
specified terminal does not have a printer port.

that

the

When you omit the terminal specification, VMR
terminals that do not have a printer port.

all

the

all

the

all

the

all

the

displays

all

the

(Full-duplex terminal driver only.) Informs the system
specified terminal supports the ReGIS graphics set.

that

the

displays

/PRIV[=ttnn:]
Sets the specified terminal to privileged status.
When you omit the terminal specification, VMR
privileged terminals in the system.

displays

/NOPRIV[=ttnn:]
Sets the specified terminal to nonprivileged status.
When you omit the terminal specification, VMR
nonprivileged terminals in the system.

displays

/PUB[=ddnn:]
Establishes the specified device as a public device.
When you omit the device specification,
public devices in the system.

VMR

displays

/NOPUB[=ddnn:]
Causes the specified device to lose its public status.
When you omit the device specification,
nonpublic devices in the system.

VMR

/REGIS[=ttnn:]

The VT125 and the VT240 terminals both support the ReGIS graphics
set.
When you omit the terminal specification, VMR displays
terminals that support the ReGIS graphics set.

all

the

(Full-duplex terminal driver only.) Informs the system that
specified terminal does not support the ReGIS graphics set.

the

When you omit the terminal specification, VMR displays
terminals that do not support the ReGIS graphics set.

the

/NOREGIS[=ttnn:]

10-70

all

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/REMOTE[=ttnn:[speed]]
Informs the system that the specified terminal is connected to a
modem and can be connected to the system by means of a dial-up
network. The terminal has a line to the one of the following
multiplexers:
DHII
DHUll
DHVII
DLII

DLVII
DZII
DZQll
DZVll

Specifying speed establishes the initial speed (answer speed) of
the remote dial-up line for the specified terminal. You can
specify an answer speed only for the following variable-speed
multiplexers:
DHII
DHUll
DHVII
You cannot specify
multiplexer.

DZII
DZQll
DZVll
an

answer

speed

for

DLII

DLVII

For the DHII multiplexer, you can specify the following speeds:

o
50
75
110
134.5
150
200

300
600
1200
1800
2400
4800
9600

EXTA (user-specified speed A)
EXTB (user-specified speed B)
For the DHUll and
following speeds:

DHVII

75
10
134.5
150
300
600
1200

1800
2000
2400
4800
9600
19200

specify

the

For the DZll, DZQll, and DZVll multiplexers, you can specify
following speeds:

the

50
75
110
134.5
150
300
600
1200

multiplexers,

1800
2000
2400
3600
4800
7200
9600

10-71

you

can

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
When you omit the terminal specification, VMR
remote terminals.
When you omit the speed specification, the
the terminal remains in effect.

displays

all

the

setting

for

that

not

displays

all

the

current

/NOREMOTE[=ttnn:]
Establishes the terminal's line as
connected to a modem.

local

When you omit the terminal specification, VMR
local terminals.

line

/RNDC[=nn]
Defines the length
interval in ticks.

the

Executive

round-robin

scheduling

The length value (nn) is assumed to be octal, unless you place a
period (.) after the value.
The minimum value for nn is o.
See
the RSX-llM System Generation and Installation Guide or the
RSX-llM-PLUS System Generatlon--and Installation GUlde for more
information.
When you omit the length specification, VMR displays the
value for the interval.

current

/RNDH[=nn]
Defines the highest priority,
from 1 to 250,
that will be
considered for Executive round-robin scheduling.
250 is the
highest priority and 1 is the lowest priority you can assign.
Therefore,
a priority of 200 takes precedence over a priority of
199.
The priority you enter is assumed to be octal unless you place
period (.) after the number.

The priority you specify must be higher than the one specified
with the /RNDL keyword.
See the RSX-llM System Generation and
Installation Guide or the RSX-llM-PLUS System Generation and
Installation Guide for more information.
When you omit the priority class, VMR displays the current
for the priority.

value

/RNDL[=nn]
Defines the lowest priority, from 1 through 250,
that will be
considered for Executive round-robin scheduling.
250 is the
highest priority and 1 is the lowest priority you can assign.
Therefore,
a priority of 200 takes precedence over a priority of
199.
The priority you enter is assumed to be octal unless you place
period (.) after the number.

10-72

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
The priority class must be lower than the one specified with
/RNDH
keyword.
See
the
RSX-IIM
System Generation
Installation Guide or the RSX-IIM-PLUS System Generation
Installation Guide for more information.

the
and
and

When you omit the priority class, VMR displays the current
for the priority.

value

/RPA[=ttnn:]
(Full-duplex terminal driver only.) Enables the read-pass-all
option.
The terminal driver passes all characters input at the
keyboard to the terminal's input buffer.
When you omit the terminal specification, VMR displays all the
terminals on the system that have the read-pass-all option
enabled.
/NORPA[=ttnn:]
(Full-duplex terminal driver only.) Disables the read-pass-all
option.
The terminal driver does not pass special function
characters (for example, CTRL/C) input at the keyboard to the
terminal's input buffer.
When you omit the terminal specification, VMR displays all the
terminals on the system that have the read-pass-all option
disabled.
ISECPOL

tasx-1I-M....Ptus, .' systernson,ly. ) DisplayssecOndett'y pool· use in the

system.

'l'hedisplay .is.in.the f9llowing·forInat:

SECPOL-secfr:secsiz:pctfr
secfr
The number of free blocks
32(decimal)-word bloc)(.s.

secondary

pool

units

o.f32(decimal}....word

secsiz
The size

secondary

pool

units

blocks.~

pctfr
The percentage of free blocks in secondary pool.
/SEItIAL[=ttnn:]
(l\SlC....IIM.... PLUS systems only.) causes unsolicited input from the
specified terminal to he processed serially, rather than in
parallel.

10-73

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
Usually, IF.It:)ltl'4ult.eri.$4Il~Ond c::onunand . l+ne _e~o:te '. t1te . ,first
comrnan.a. Itn~i,. . ,.k.s ,. cC!'Pl~~Et~ eXi!Cllti t19, the sy..,:tem!:proc.ss~s.the
seoon<i,:COlllfna~cI,~~ne:;~t1:pl;~~~~e~\Y'it.h 'th4i): fil:st.
WIlen. i te~inal
is .' s;er't t.o ~Et·:t·~.~'·~~~P~!s.J4flg, hO~fJYer:~,t~ue .¥s,t~JJl.ai
tlnti1 the
fir.st~ommand ~i~e'.1J•.•·fini~hedprocessi)l)9 be,fo,re
start:.ing the
seoond:.
.

wpenY'~u otni~ .t.he~~,:r1tl~na~.e,ec.tiicati()n t VNRdi splays

the

terminals t.hat. pI"OCe;S s .. ser:l~lly.

'!he! a.fault.,lb5 t'oI~I~.lL.

*" tnni#)
C.'J)C.iS:~n+'h).·•.•. cau~e:~uh~~~~6i1lt.e4

'80l'lll,

i"
t ...... Ito.. the
:.,.,e~ >,ed
:'.' <J: t(;J ..,.•. ~.." PJ:0ce~se.·"n :';para.11
:tat-her than
seriaiJJ.Y.l;iPJI<lJC.,~_t~9.Jn,ali1st'hat ,()ne ormotetcQmmand
lines,:.re p
eel ,at: tbe' s,ametime.·
.
~.. '

;

":':".: ,y~'

::':: . ::: " ,,"

.:.

.....

':",'".

.' :.

. .::

Whe~.:~~u .•..."., . . ~1'l'~~~minilt~l>eCifica~ion~ VKR ·Ci~splay' .• all

.. '~rJn1b.l$ t.h.t.rp,OQ'-.·ii n.:p~~al1.1..

t.he

'lhe d_i:ault1·~!I'o~'IAL.
/SLAVE[=ttnn:]
Establishes the specified terminal as one that can enter data
only if it is solicited by a task. Therefore, the specified
terminal always rejects unsolicited input (other than CTRL/O,
CTRL/Q, and CTRL/S).
When you omit the terminal specification, VMR
terminals currently classified as slaved.

displays

all

the

all

the

/NOSLAVE[=ttnn:]
Sets the specified terminal to nonslaved status.
When you omit the terminal specification, VMR
terminals currently classified as nonslaved.

displays

/SOFT[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified terminal can accept software-defined character sets.
The VT200-series of terminals can accept these character sets.
When you omit the terminal specification, VMR displays
terminals that accept software-defined character sets.

all

the

/NOSOFT[=ttnn:]
(Full-duplex terminal driver only.) Informs the system that the
specified terminal cannot accept software-defined character sets.
When you omit the terminal specification, VMR displays all the
terminals that do not accept software-defined character sets.

10-74

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/SPEED=ttnn:[recv:xmit]
Establishes the receive and transmit speed for terminals attached
to the system through a DHll, DHUll, DHVll, DZll, DZQll, or DZVll
variable-speed multiplexer. The values are described as follows:
recv
the recv value is the ~speed at which characters are input to
the computer from the terminal.
xmit
the xmit value is the speed at which characters
to the terminal from the computer.

are

output

You must specify both the recv and xmit values when setting the
speed.
If you do not ~specify either value, VMR displays the
current settings.
For the DHII multiplexer, you can specify the following speeds:
300
o
50
600
75
1200
110
1800
134.5
2400
150
4800
200
9600
EXTA (user-specified speed A)
EXTB (user-specified speed B)

For the DHUll and DHVII multiplexers, you can specify the
following speeds:
75
110
134.5
150
300
600
1200

1800
2000
2400
4800
9600
19200

For the DZll, DZQll, and DZVll multiplexers, you can specify
following speeds:
50
75
110
134.5
150
300
600
1200

the

1800
2000
2400
3600
4800
7200
9600

If you have a DZll, DZQll, or DZVll multiplexer, the receive and
transmit speeds must be the same because these multiplexers do
not support split speeds.

10-75

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/SUB=mname:sname[:base:size]
(RSX-11M
systems
only.)
Establishes
a
subpartition.
Subpartitions can be established only in user-controlled main
partitions. The values are described as follows:
mname
The 1- to 6-character main partition name. The subpartition
being defined becomes a subpartition in the named main
partition.
snarne
The 1- to.6-character subpartition name.
The subpartition
being defined becomes a subpartition of the main partition
specified in mname.
base
The physical base address of the subpartition, specified
a number of 64...,;byte blocks.

The size of the
64-byte blocks.

size
subpartition

specified

number

Base and size may be entered in any of the following formats;
nnnn is a number to which the system applies a multiplication
factor to determine the value used.
Format

Calculat.ed Value

Octal (nnnn*lOO)
Decimal (nnnn.*64.)
Octal K (nnn*4000)
Decimal K (nnn.*2048.)

n.
n1<
n.K

Valid ranges for calculated values are:
Octal
Decimal
Octal K
Decimal K

O<=base<lOOOO
0.<=base<4096.
0I«=base<200K
0.K<=base<2047.K

O<size<2000
O.<size<1024.
OK<size<40K
O.K<size<32.K

Example:
Any of the following designations
2048(decima;)-byte subpartition:

for

size

will

allocate

32.
lK
1.K
If base and size are omitted, VMR displays the current values for
the named subpartition.

10-76

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/NOSUB=mname:sname
(RSX-llM systems only,,)
from the main partition.

Eliminates the

specified

subpartition

/SWPC[=:nnJ
De!fines the number of clock ticks for a single Executive swapping
interval.
The number of clock ticks (nn)
is in the
range
a to
4S.,568{decimal).
The number of clock ticks is assumed to be
octal unless you place a period (.) after the number.
Se:e the RSX-IIM System Generation and Installation Guide or the
RSX-IIM-PLUS System Generation and Installation GUId"e for more
information.
When you omit the clock ticks specification,
current value for the interval.

VMR

displays

the

/SWPR[=:nnJ
De:fines a priority range for Executive swapping.
Tl1e priority number (nn) is in the range a through 127.
127 is
the highest priority and a is the lowest priority you can assign.
Therefore, a priority of 100 takes precedence over a priority of
99.
The priority you enter is assumed to be octal unless you place
(.) after the priority number.

pe~riod

The value for the /SWPR keyword affects the installed priority of
all tasks.
Each task is initiated at its installed priority,
plus the value for nn as assigned in /SWPR=nn (priority + nn).
While the task is executing, its priority is decremented until it
be~comes the installed priority minus the value for
nn (priority
- nn).
When the priority reaches this lower limit, the task is
swapped out so that another task with a higher priority can
execute.
The priority for the new task changes in the same way.
Se!e the RSX-IIM System Generation and Installation Guide or the
RSX-IIM-PLUS System Generation and Installation Guide for more
information.
When you omit the range specification, VMR displays
value for the priority range.

the

current

/SYSUIC[=[uicJJ
Establishes the UIC for the system and all system tasks. The UIC
has the format [g,mJ, where g and m are octal numbers that
re!present a group and member number, respectively.
On most unmapped systems, the system UIC
mclpped systems, the system UIC is [1,54 J .

10-77

[1,50J.

most

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
The UIC specified with the /SYSUIC keyword also becomes the
default UIC used by the LOAD command and the install-run-remove
option of the MCR RUN command.
When you omit the UIC specification,
system UIC.

VMR

displays

the

current

/TERM=ttnn:[type]
(Full-duplex terminal driver only.) Establishes the terminal type
of the specified terminal. When VMR sets the terminal type, it
automatically sets the HFILL, VFILL, CRT, FORMFEED, and HHT
characteristics for the terminal. The standard terminal types
are as follows:
ASR33
ASR35
DTCOI
KSR33
LA12
LA30S
LA30P

LA34
LA36
LA38
LA50
LAlOO
LA120
LA180S

LA2l0
LN03
LQP02
LQP03
PC3XX
VT05B
VT50

VT52
VT55
VT6l
VT100
VTlOl
VTl02
VTl05

VT125
VT13l
VT132
VT2XX

If you specify a terminal type that is unknown to VMR, VMR does
not set any device characteristics for the terminal. However,
VMR stores the value you have specified in the Unit Control
Block (UCB).
When you omit the type parameter, VMR displays the terminal
of the specified terminal.

type

VMR also accepts an alternate form of the command.
You can
specify the terminal type and equate it to the desired terminal.
This automatically associates certain characteristics of the
particular terminal type with the specified terminal.
(See the
RSX-llM/M-PLUS I/O Drivers Reference Manual for a list of the
implicit characteristics for each terminal type.) The command is
in the format:
SET /term-type=ttnn:
where term-type is one of the standard terminal types.
the terminal types are mutually exclusive.

Note that

The half-duplex terminal driver also accepts the /term-type form
of the command. However, the only legal terminal types for the
half-duplex driver are /ASR33, /LA30S, and /VT05B.
The command
associates implicit characteristics of the terminal type with the
specified terminal, but, unlike the full-duplex terminal driver,
the types are not mutually exclusive.
The following list describes the effects of the keywords for
half-duplex terminal driver:
/ASR33

Converts lowercase letters to uppercase
they are output to the terminal.

10-78

the

before

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
/LA30S

Indicates that fill characters are used after a
carriage return.
The number of fill characters
used depends on the current carriage position at
the time the carriage return occurs.

/VT05B

Sets a vertical fill of three nulls after a line
feed on 60 Hz systems and of four nulls on 50 Hz
systems.

/TOP=pname:value
Di.rects VMR to move the top boundary of the specified partition
up or down the amount indicated by the value parameter.
The /TOP keyword modifies the top boundary of a system-controlled
partition even if the partition has tasks installed in it. If
you modify the partition so that it becomes too small to hold the
tasks installed in it, VMR displays a warning message but
modifies the partition anyway.
pname
The 1- to 6-character alphanumeric partition name.
vSLlue
The number of 64-byte blocks.
The value can be supplied in five formats: +value, -value,
value, +* or *, and -*
These are described as follows:
+value
Moves the partition's top boundary up by the specified
amount.
Moving the partition's top boundary up makes
the partition larger.
NOTE

You must supply the value in the same units as
the base and size parameters for the /PAR
keyword.
-value
Moves the partition's top boundary down
by
the
specified amount. Moving the partition's top boundary
down makes the partition smaller.
value
Moves the
partition's
top
boundary
until
the
partition's total size is equal to the specified value.
+* or *
Moves the partition's top boundary up as far as
possible.
The most the top boundary can move up is to
the bottom boundary of the partition above it, or, to
the top of memory, if the partition is the last
partition in memory.
10-79

VIRTUAL MONITOR CONSOLE -ROUTINE (VMR)

SET (Cont.)
-*
Moves the partition's top boundary down as far as
possible.
The most the top boundary can move down is
to the top of the of the first fixed task, common, or
driver in the partition at the time the /TOP keyword is
executed. If nothing is loaded into the partition, the
partition assumes a size of one 64-byte block.
/TTSYNC[=ttnn:]
(Full-duplex terminal driver only.)
Enables
the
terminal
synchronization option for the specified terminal. This means
that the system responds to the CTRL/S and CTRL/a characters used
to control the flow of information on the terminal screen, when
you type them on the terminal. /TTSYNC is the default.
When you omit the terminal specification, VMR
terminals that have terminal synchronization.

displays

all

the

/NOTTSYNC[=ttnn:]
(Full-duplex terminal driver only.) Disables
the
terminal
synchronization option for the specified terminal. The system
will not respond to the CTRL/S and CTRL/a characters when you
type them on the terminal.
Note that if you set your terminal to /NOTTSYNC,
key on VT100-series terminals and the HOLD
VT200-series terminals, will no longer work.

the NO SCROLL
SCREEN key on

When you omit the terminal specification, VMR displays
terminals that do not have terminal synchronization.

all

the

/TYPEAHEAD[=ttnn:[sizeJ]
(Full-duplex terminal driver only.) Enables the typeahead
for the specified terminal.

option

The terminal driver stores input characters in the typeahead
buffer before passing them to the task. When the typeahead
option is enabled, characters input during periods between
requests are not lost.

If size i$ specified (RSX .... llM-PLUS systems that support kernel
data space only). the typeahead buffer size is set accordingly.
The value for size can be from O. through 255(decimal).
If you
specify 0 or 1, the terminal will not have the typeahead option
enabled (same effect as /NOTYPEAHEAD). The default for size is
86(decimal).
When you omit the terminal specification, VMR displays
terminals that have the typeahead option enabled.

10-80

all

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
INOTYPEAHEAD[=ttnn:]
(Full-duplex terminal driver only.) Disables the typeahead option
for the specified terminal. The terminal driver does not store
characters to prevent their loss because the size of the buffer
is forced to 1.
When you omit the terminal specification, VMR displays all
terminals that do not have the typeahead option enabled.

the

IUle=[[uic]:]ttnn:
Establishes the specified Ule as the default Ule for the
specified terminal (the default is TI:). All tasks run from the
terminal are run with the Ule of the terminal, except in a
multiuser protection system.
In such a system, a privileged user
can override the terminal Ule with the IUle keyword of the RUN
command.
External MeR function tasks are requested with the IUle keyword.
These tasks are the MOUNT, INSTALL, DMO, and UFD commands (which
ex.ecute as tasks), and all system-supplied software.
When you specify only the terminal, VMR displays the Ule for that
te~rminal.

IVFILL[=ttnn:]
(P'ull-duplex terminal driver only.) Enables the vertical fill
characters option for the specified terminal.
The terminal
driver adds four fill characters following each line feed.
wnlen you omit the terminal specification, VMR displays all
terminals on the system that have the VFILL option enabled.

the

INOVFILL[=ttnn:]
(P'ull-duplex terminal driver only.) Disables the vertical fill
characters option for the specified terminal.
The terminal
driver does not add any vertical fill characters following line
fe!eds.
When you omit the terminal specification, VMR displays all the
te!rminals on the system that do not have the VFILL option
enabled.
IweHK[ =:ddnn : ]
Specifies for all Files-II devices, except DX:, DY:, and magnetic
tapes, that all write operations are to be followed by a
write-check. The checks assure the reliability of data transfers
to the specified disk.
On RSX-IIM, Executive support for write-checking is a system
generation opt.i.~na!'l~Ill\lst J?4l! selected for this command to have
a!'lYEl~fec:'t.~ .....• on ·RSX~llM~:eLU~, sllPPOt:t for ~rit.e ... ehecking is
always included.

10-81

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
When you omit the device specification, VMR displays all Files-II
disk drives with write-checking enabled.
/NOWCHK[=ddnn:]
Specifies that write-checking is to be disabled for the specified
device.
When you omit the device specification, VMR displays all
that support write-checking but have the option disabled.

disks

/WRAP[=ttnn:]
(Full-duplex terminal driver only.) Enables the wraparound option
for the specified terminal.
The terminal driver automatically
generates a carriage return/line feed sequence when the number of
input characters exceeds the buffer size of the specified
terminal. Both the carriage return and line feed are transparent
and do not appear in the input buffer.
When you omit the terminal specification, VMR displays all the
terminals on the system that have the wraparound option enabled.
/NOWRAP[=ttnn:]
(Full-duplex terminal driver only.) Disables the wraparound
option for the specified terminal.
The terminal driver does not
accept input characters beyond the input buffer size for the
terminal.
When you omit the terminal specification, VMR displays all the
terminals on the system that have the wraparound option disabled.
Notes on Memory Allocation Keywords
1.

If a command attempts to eliminate a partition in which tasks
are installed or drivers loaded, VMR rejects the command
until the tasks have been removed.

When you define a partition, the name must not already be
defined as a partition.
In addition, a partition cannot
overlap any other partition.
On RSX-IIM, subpartitions can overlap other subpartitions.

The address specified with the /POOL keyword must be lower
than the base address of the first partition in the system.
On RSX-IIM, an exception is the partition
resident loader. LDRPAR is in the Executive.

LDRPAR

for

Once you have allocated space to the dynamic storage region
(pool), you cannot recover the space for use in partitions.

When the highest memory addresses of a system are allocated,
the size of the partition is modified automatically to
reflect the amount of memory present when the system is
bootstrapped.

10-82

VIRTU~

MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
6 ..

On RSX .... 1.1M-PLUS, SBT·/TOP

and

SET

ISOTcan

used

for

secondary·· pool.partition;s ..
7.

If the last partition is system-controlled, its top address
is modified by the SAVE command at boot time to reflect the
actual top of physical mem6ry of the hardware in use.

ExamplE!s
1.

VMR>SET IABAUD=TT4:
Enables the autobaud detection option for TT4:.

VMR>SET IABAUD
ABAlII"I=TT2:
I~IhiUn=TT 4:
(',B(·'Il.lDo-;:TT5 :
Displays all the terminals that have the
option enabled.

terminal

TT22:

has

the

for

the

VMR>SET IBLKMOD=TTJ:
Enables local editing and
terminal TT3:.

5 ..

detection

VMR>SET IAVO=TT22:
Informs the system that the VT100
advanced video option.

autobaud

block-mode

transmission

VMR:> SET I BR 0 :~ T T 5 :

Enables the broadcast option for TT5:.
6.,

VMR> SET IBRO
BRO:::TT2:
BF~O=TT4:

BRO=TT5:
Displays all the terminals that
enabled.
7.

have

the

broadcast

option

VMR:>SET IBlIF=LPO:
BUF:=I...PO: 1.32.
Displays the current buffer size of LPO:.

VMR:>SFT IBUF=TT1:40.
Sets the buffer size of TTl:

to 40(decimal).

VMR>SET ICRT=TT3:
Enables the backwards deletion option on the display terminal
whose number is TT3:.

10-83

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
10.

VMR>SET ICRT
CRT=TT:5:
Cf,T=TT7 :
CRT=TT12:
Displays all the terminals that have the
option enabled.

11.

backwards

deletion

VMR>SfT INODfC=TT10:
Informs
the
system
that
terminal
TTlO:
is
upward-compatible with the VT100-series of terminals.

12.

VMR>SET IEDIT=TT25:
Informs the system that terminal
TT25:
ANSI-defined advanced editing functions.

13.

can

as a terminal that

can

send

and

VMR>SET IESCSEQ
ESCSFQ=TT3:
E<3CSFO::::TT1:
EBCSFO"=TT:I.6 :
Displays all the terminals that can send and
sequences.

15.

perform

VMS>SFT IESCSEQ=TT3:
Establishes terminal TT3:
receive escape sequences.

14.

not

receive

escape

VMR>SET INOESCSEQ=TT3:
Disables support of escape sequences for TT3:.

16.

VMR>SET IHSYNC=TT??:
Enables host-terminal synchronization for terminal TT22:.

17.

VMR>SET II . A30S '::TT2!
'JMR>SFT .It A30S
LA30S::::TTO!
LA30S=:TT? :
Sets TT2:
terminals.

18.

LA30S,

then

displays

all

the

LA30S

VMR>SFT INETUIC
NETUJC=[20,3J
Displays the current network UIC.

19.

VMR>SET INETUIC=[25,6J
Sets the network UIC to [25,6J.

20.

VMR>SfT IOPT=DM1:NEAR

Enables I/O queue
algorithm.

optimization

10-84

for

DMl:,

using

the

NEAR

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
21.

VMR)SET IOPT

OPT=DBO fNF.AR
OPT=DBlINEAR

OPT =[IMO !NE'AR

OPT:::tIMl H~EAR

Displays ... all the ... disk
optimization enabled.
22.

devices

that

C!\leue

VMR>SFT IPARITY=TTtS:EVEN
Enables parity generation and checking for terminal TT15:
and informs the system that if an even number of bits are
counted during data transmission, the transmission of data
does not return an error.

23.

VMR>SET IPASTHRU=TT22:
Informs the system that it should ignore special characters
typed at terminal TT22: and pass them to a program in their
binary form.

24.

VMR>SFT IPLCTl
PLCTL=1600.:600.:200.:S1.
Displays the current pool limit parameters used by
Monitor Task.

25.

supports

the

has a printer port.

VMR>SET IPRIV=TTO:
Sets TTO:

27.

Pool

VMR>SET IPRINTER_PORT=TT22:
Informs the system that TT22:

26.

the

to be a privileged terminal.

VMR>SET IPRIV
PR I V=:TTO!
PRIV=TTl.:
Displays all privileged terminals.

28.

VMR>SET IREGIS=TT1S:
Informs the system that
ReGIS graphic set.

29.

the

terminal

TT15:

VMR>SET IREMOTE=TT21:
as

remote

Displays all the terminals that are currently set
dial-up lines.

remote

Sets the terminal line corresponding to TT21:
dial-up line.

30.

VMR>SET IREMOTE
I~EMOTE=TT:I :
REMOTE=TT2!
1:~EMOTE=Tl3 :
REMOTE=TT4!
REMOTE.=TT21!

10-85

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)
31.

VMR>SET IRNDC
F~NDC:::b •
Displays the current length
interval.

32.

the

round-robin

scheduling

VMR>SET IRNDC=10.

Sets the length of the
lO(decimal) ticks.

33.

round-robin

scheduling

int~rval

VH~)SET /SECPOL
SECPOL~2a5+:'40:44X

Displays the amount of secondary pool currently being used.
34.

VMR>SFT ISLAVE=TT3!
Sets TT3: to be a slaved terminal.

35.

VMR>SFT ISOFT=TT22!
TT22:

accepts

Executive

swapping

Informs
the
system
that
terminal
software-defined character sets.
36.

VMR>SET ISWPR
SWPR::-~5 +

Displays the current
priority range.

37.

value

for

the

VMR>SET ISWPR=10.
Sets the Executive swapping priority range to 10(decimal).

38.

VMR>SFT ITERM=TT25!
Term=TT25: VT100
Displays the terminal type of terminal TT25:.

39.

VMR>SFT ITERM=TT25:VT2XX
Requests the system to give terminal
capabilities as a VT200-series terminal.

40.

VMR>SFT ITTSYNC=TT?2!
Enables terminal synchronization for TT22:

41.

VMR>SET IVT05B
VT05B=TT4:
VTO~:;B::::TT5 !
VT05B:::TT 6:
Displays all VT05B terminals.

42.

VMR>SET IWCHK=DK1!
Enables write-checking on DK1:.

10-86

TT25:

the

same

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

SET (Cont.)

.. . . . . . . . ~ddress

.D.t'J?8;~~.1f;.~()J1 . . . . <p8;l.re9 ...•... S¥SPldt ·.···tlhCl>EJ~ . . . i.~a. ~
420

!44'~

all ···.8;n:d •.···wbos_·l,.ength lsr· • i.IOg.o(oet.~ll. ··.b~es·~

V"~.~S~T I·NI)P"R.·~.S.'1.SPAR···
. Bii~~l~at~sith~~fn~_r.titi()a.S¥SPAR.

45~QHR)'S£T )PAR~G'£Nl*t*

C~eat~~a . .<~~~li~~on~~edGD1, '~tt.i.~g.~lte . . . p~se
lO'\f...~>;pos~;J,bl.an:d ma'J(1n:9 the part it. d;. on as
pp'ssd;.Ple+
46.

as
a.s

VMR>SET IF'OOl..=420
Establishes the top of the dynamic storage region (pool).
Following this command, no user-defined partition can begin
below 42000{octal).

47.

VMR>SET lPOOL
F'OOI..:::1.200::l.1470.:1.1.738.:2003

Shows that the last virtual address in the Executive is
120000, the longest free block is 11470{decimal)-words, and
the total of all pool space is 11738{decimal}-words.
The
lowest physical address at which a partition can start is
2003 (32-word blocks).

10-87

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

TAS
TASKLIST
Use the TASKLIST command to display a description of each installed
task in the system. The display contains several columns that give,
from left .xp TASKLIST command (VMR)display contents to right, the
following information:
•

Task name

•

Task version identification

•

Task Control Block address

•

Partition name

•

Task priority

•

Size of task in bytes (in octal)

•

Load device identification

•

Disk address
systems, or
systems

•

Task memory state (saved systems only)

logical block number (in octal) on unsaved
the image or task file identification on saved

On RSX-llM-PLUS, the display lists the tasks installed in primary pool
and then the tasks installed in secondary pool.
The tasks in
secondary pool are indicated by a plus sign (+).
Format
TAS[KLIST][taskname]
Parameter
taskname
The name of a single installed task, whose description
displayed.

you

want

Examples
1.

The following example is from an unsaved system:
VMR:>TAS
TKTN

03.14

••• MeR 01.01
MCF: ••• 3.3
••• INS 4

••• LOA 03.3
••• UNL 03.4
VMR>

035300
0351.74
035070
035614
035510
035404

GEN
GEN
GFN
GEN
GEN
GEN

248. 0:10000 LBOt-00631.420
160. 040000 LBO:-006~0300
160. OlOOOO L.BOt-00627721
tOO. 040000 I...BOt-00627333
50. 040000 L.BO:-00627643
50. 040000 LBOt-00070512

On a system image generated for a 22-bit system with more
than l24K-words of memory, the size field (sixth column)
contains 8-digit rather than 6-digit numbers.

10-88

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

TAS (Cont.)
2.

The following example is from a saved system:
VMR:>TAS
LDR ••• 08.03
TKTN
03.14
MTAIACP 0010
MCR: ••• 3.3
• •• Del. 011.~5A
DCI...••• 0113A
••• MCR 0:1..01
••• MOU 23.00
Fl1ACF' M0320
DBOOFl M0320
COT.!. XOO.Ol
••• DMO 2~5.0()
••• INI 20.01
••• UFD V04:1.0
PMD ••• 3.1.
HRC ••• 01.01
SHF ••• 03.01
FX~: ••• 01
• •• INS 4
••• SAV 04.35
SA~'TO
04.35
• •• PRV 4.30
••• AT. 04.25
•••. BOO 04.08
•••. ACS 01.1
•••. HEL 01.25
VMR>

034210 lDRf'AR
115424 GEN
11521.4 GEN
116464 SYSPAR
11.5634 GFN
115530 GEN
036770 GEN
036250 GEN
117674 GEN
117570 GEN
117360 GEN
1.17254 GEN
116674 GEN
1.16044 GEN
114630 GFN
036560 GEN
115320 SYSf'AR
U.7104 GEN
116570 GEN
1:1.6254 TSTPAR
036130 TSTPAR
036664 GEN
037254 GFN
1.17464 GEN
115740 GEN
037360 GEN

248. 00003000
248. 00010000
200.00013500
160. 00010000
160. 00040000
160. 00010000
160. 00040000
:1.60. 00040000
149. 00065700
149. 00065700
145. 00015400
140. 00040000
149. 00040000
140. 00040000
140. 00023600
140. 00050400
105. 0001.0000
100. 00003100
100. 00027700
100. 00040000
100. 00040000
100. 00040000
65.00057700
50. 00040000
50. 00040000
50. 000441.00

LBO:LBO:LBO:I..BO:l.BO:LBO:lBO:LBO:l.BO:LBO:l.BO:LBO:lBO:LBO:l.BO:LBO:l.BO:lBO:lBO:LBO:-lBO:LBO:l.BO:L80:lBO:LBO:-

FIl.E
FILE
FJLE
FIl.E
FILE
FILE
FIl.E
FILE
FILE
FILE
FIl.E
FILE
FILE
FILE
FIl.E
FILE
FILE
FILE
FIl.E
FILE
FJl.E
FILE
FIl.E
FILE
FIl.E
FILE

In:(1111,12) FJXED
ID:(3:1.540,27)
In:(31461,24)
1[1:(31454,12)
In:(31344,53)
ID:(31345,5)
1[1:(30546,34)
1[1:(5424,15)
ID:(30101,47)
10:(31370,6)
In:(31336,120)
1[1:(31346,23)
J[I:(31424,~5)

10:(31.541,34)
ID:(31464,70)
10:(31240,21)
ID: (31571,40)
1[1:(31.371,113)
JD:(31435,12)
10: (31475,5)
ID:(31475,5)
1[1:(3433,163)
JII:<31421Pl.3t)
1[1:<31323,6)
JII: (31321,73)
ID:<31.416,1.5)

The display for a saved system differs from the display for a
unsaved system in that the file-ID of the task file, rather
them the logical block number, is displayed.
FIXED indicates
that the task is fixed in memory.

The.following example is from' an RSX-IIM-PLUS
that has tasks installed in secondary pool.:

saved

system

VMR>TAS

. 1.9
1.7
LPO
LP1
1.9
SHe. .•
02

113440
112450
112734
112604
110600

SHUTlJP

110J~o

• • .. DMO 23.20
• •• HeR 2.4

006025+ GEN
OQ6037+ GEN
0060'41+ GEN
006130+ 'lEN

BAF'O

QMG. •

Ot.Ol

• • ..MOlt 2502
• .... Del 00

GEN
aEH
GEM
GEN
GEN
GEH

VMR>

10-89

80. 00045700 LBO:- FILE III: (4J32,27)
75. 000314.00 lBot~ FIl.. E tD:(4366,2)
70. OOQ,15400 LIIO;- FIl.E IDt(4354,135)
O()O15400 Leo: ... FILE ID:<4154,135)
60. 00051700 LBot .... FILE IDt(4360,2)
50. QOot1200 L90t- FILE 10;(4320,65)
160. 00015500 LttOt- FILE IDl(4167,35)
160. O'()03200Q LeOt- FILE tnt<2132,227)
Joo. 00040000 LBOt- FILE Int (4205,13)
160. 00035600 Leo;- FtL.E U:U (2535,1525)

'0.

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

TIM
TIME
Use the TIME command to set the date and time or to display
and time. The TIME command has two formats.

the

date

optional;

the

Format 1
TIM[E] [hrs:mins[:secs]] [ml/day/year]
Format 2
TIM[E] [hrs:mins[:secs]] [day-m2-year]
Parameters
hrs
Hours (range 0 through 23).
mins
Minutes (range 0 through 59).
sees
Seconds (range 0 through 59).
default is zero.

This parameter

ml
Numeric representation of month (range 1 through 12).
m2
Three-letter abbreviation for month.
day
Day (range 1 through 31).
year
Year (range 0 through 99).
The
therefore, 1986 is entered as 86.

year

relative

Examples

VMR>TIM
10:23:31 21-JUN-85

Displays the current system image time and date.

VMR>TIM 14:10 6/24/85
Sets the time to 14:30:00 and the date to 24-JUN-85.

10-90

1900;

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

TIM (Cont.)
Notes
1.

You can specify the time and date in any order.

If you specify the time and the date,
image clock and calendar.

If you specify the time but not the date, VMR only
clock.

sets

the

If you specify the date but not the time, VMR only
calendar.

sets

the

If you don't specify a time. or date, VMR displays the current
system image time and date.

The form used to specify the date does not affect the display
format.
The date is always displayed as day-month-year.

All numeric values are decimal.
required.

10-91

VMR

sets

the

system

No terminating period (.) is

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

UNF
UNFIX
Use the UNFIX command to free a fixed task from the virtual memory of
the system image.
The UNFIX command is the complement of the FIX
command.
If a fixed task exits or aborts, it still occupies the physical memory
in the partition.
Format
UNF[IX] taskname[/keyword]
Parameters
taskname
The task that you want to unfix from memory.
/keyword
One of the following (RSX-llM-PLUS systems only):

/REG
/RON

Keywords
/REG
Specifies that the task to be unfixed is a common region.
/RON
Specifies that the task is a multiuser task,
segment of which is to be unfixed from memory ..

the

read-only

Example
'v'MF:>LJNFIX XKE

Unfixes task XKE, freeing the partition in which it resides.

10-92

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

UNL
UNLOAD

Use the UNLOAD command to remove a loadable device driver from the
system image.
If a device is attached however, its driver cannot be
unloaded.
To unload a device driver from the system image, the driver's symbol
definition file must reside on LB: under the same directory as the
directory of the system image file. The system directory is usually
[1,50J for an unmapped system and [1,54J for a mapped system.
The UNLOAD command cannot remove a loadable data base from the system
image, even if the data base was loaded by means of the LOAD command.
Format
UNL[OADJ dd:(/vEC]
Parameters
dd:
A 2-character ASCII device name.

You must specify a device name.

IVEe
(RSX-llM-PLUS systems orily.) In£orms the ,system that the driver
tbbe unloaded is vectored.
The /VECkeyword prevents the
comparison of the driver symbol table file and the system symbol
table file.
ExampleIJMr~>I.JNL.

LP:

Unloads the line printer driver (LPDRV).

10-93

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
10.6

VMR ERROR MESSAGES

This section contains explanations for VMR error messages.
messages can appear in one of the following formats:

Error

VMR -- *DIAG* message
This format indicates a diagnostic error message.
A diagnostic
error
message
usually indicates that something unexpected
happened, but that the error did not interfere with VMR's
operation.
VMR -- message
This is an unmarked error message.
An unmarked error message
usually indicates that VMR rejected the command line.
If the
offending line is in an indirect command file, VMR ignores the
rejected line and attempts to execute the remaining command
lines.
VMR -- *FATAL* message
This is a fatal error message. A fatal error message indicates
that VMR rejected the command line and that VMR has either exited
or reset itself to the beginning (that is, Enter filename:).
If
the offending line is in an indirect command file, VMR exits
without attempting to execute the remaining command lines.
The following explanations for error messages contain the text of the
error message, but not the format. They are in alphabetical order.
VMR -- Access to common block denied
Explanation: You attempted to install a task that has
illegal access to a shared region.

specified

VMR -- Addressing extensions not supported
Explanation: You attempted to install a task that was built
using the VSECT (virtual section) directive into a system image
that does not support the VSECT feature.
VMR -- Alignment error
Explanation: The base address or size of the partition being
created with the SET command conflicts with existing partitions
or physical memory.
VMR -- Base address must be on a 4K boundary
Explanation: The virtual base address of
installed is not aligned on a 4K boundary.

the

task

being

not

match

VMR -- Base mismatch common block <commonname>
Explanation: The base address of the partition
that of the common block.

does

VMR -- Bus switch not loaded
Explanation: You attempted to load a device requiring a bus
before you loaded the bus switch.

10-94

run

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Cannot fix an I/O space task
Explanation:
and D-space.

You attempted to fix a task that is built
These tasks.cannot be fixed.

with

I-

VMR -- Cannot fix a task in a system controlled partition
Explanation: This is a VMR restriction. To fix a task in a
system-controlled part.i tion, use the MCR FIX command and then
save the system image.
VMR -- Cannot have multiple pool or CPU partitions
Explanation: You attempted to create a secondary pool partition
in a system that already has one.
There can be only one
secondary pool partition in a system.

VMR - .... cannotinstallsharedregion with increment
Bxplanat.ioo: You specified both !INC-sizeand fWD-YES when
installing a common •.... ~WbEan.a . common . ~s insta~led< .with.. an
iricremen:t,it will.no1ollgerf.it ill its original task image file;
therefore,youcanno:talsospe<:ify that the co:mmonbe written
back into its t.ask itnage file (/we-YES).
VMR -- Cannot install tasks or commons from other than LB:
Explanation: SAVE does not allow saving of a system that has
tasks and/or commons that were not installed from the library
dE~vice LB:.
Therefore, a task or common cannot be installed from
ot:her than LB:.
VMR -- Cannot LOAD/UNLOAD a pseudo device
Explanation: When loading or unloading a device
physical name of the driver must be specified.

driver,

the

VMR -- Cannot UNFIX a mapped common region
Explanation: You attempted to unfix
currently mapped by a task.

common

region

that

VMR ...- Cannot UNFIX the-direct.ive common
Bxplan,atioru RSlC ... IIM-PLUS directive commons can be removed but
not. unfixed. eecaUse.directivecommonsare. merged witb·DIRllM as
they are fixed, the size of a particUlar· common is unknown.
VMR -- Checkpoint area too small
Explanation: The area allocated for checkpointing in the task
image file is smaller than the partition into which the task is
bE~ing installed.
The system image does not support the dynamic
allocation of checkpoint space.
VMR -- Checkpoint space too small, using checkpoint file
Explanation: This is a warning message.
The checkpoint space
allocated in the task image file is too small to hold the task
(usually because of the /INC key,,'ord). The system image supports
the dynamic allocation of checkpoint space. It will use the
checkpoint file to store the task when it rolls it out to disk.

10-95

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Circular redirect error
Explanation: The attempt to redirect a device failed because
would result in a circular device list.
VMR -- Command

r/o error

Explanation: The system detected an
an indirect command file.

r/o error during a read from

VMR -- Command syntax error <command-line>
Explanation:

The syntax of the command line is incorrect.

VMR -- Common block currently installed
Explanation: You attempted to install a common
already been installed.

block

that

has

VMR -- Common block is task partition <commonname>
Explanation: A task's request for access to a common block has
been
rejected
because the requested partition is a task
partition.
VMR -- Common block not loaded <commonname>
Explanation: The common block specified by VMR in the error
message has been linked to the task, but the common block has not
yet been installed.
User Action: The common block must be installed before the
can be installed.

task

VMR -- Common block occupied
Explanation: You attempted to install a task in a
that was already occupied.

cornmon

block

VMR -- Cornmon block parameter mismatch <cornmonname>
Explanation: The parameters of the common block named in the
error message do not match the parameters in the label block of
the task that references the cornmon block.
VMR -- Cornmon block segment count error
Explanation: You attempted to install a resident library with
overlays, but the number of overlay segments in the task header
differs from the number specified in the segment descriptors.

VMR -- CTB <name> does not exist
Explanation: The Controller Table (CTa) name that you specified
with the LOAD ICTB keyword does not exist in the resident data
'base.
VMR -- CTB name <name> is a duplicate
Explanation: The loadable data base contains a Controller Table
with a name that is the same as a CTB name in the resident data
base. CTB names must be unique.

10-96

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

VMR ........ CT:B<na,me> not supported by driver -- not loaded

l~p~."'l<m.
This i s a warning message.
meesage\foreither of the following reasons:

VMR

displays

this

l.TheDriverD.ispatchTableinthe driver does not have all the
Conttoller .'. Table mnemonics that the rest of the data base
(that!s, DCSsandCTBs) implies that it should have.
2.
VMR

The.erS is defective • A defective CTBmay
name or it may point at the wrong DCB.

contain

wrong

Data space file exceeds available space in system image
Explanation: The RSXIIM.SYS file is not large enough to
the data space file DSPIIM.TSK.

contain

VMR; ....-OCS table for CTS <name> is full

Bxp,"anattoru . LOAllattemptedto write the address of the Device
Con'erol Sloc"k(DCB')ofthe loadable database into theDCB table
o.f·the . Controller Table .for a multicontroller device. There were
rlOt\u.ll.entriesinthe.DCS table. (See the RSX-IIM-PLUS Guide to
Wri.tingan·I/O Driver.)
VMR -- Device <ddnn:> is attached
Explanation: You attempted to unload a driver that has one or
more of its device units attached. The first attached unit is
ddnn:.
You cannot unload a driver that has device units
at.tached.
VMR -- Device <ddnn:> is not in system
Explanation:
rE!aSons:

VMR

VMR displays this message for any of the
a

device

that

following

You attempted to save an image on
exist on the host system.

does

not

2.,

You attempted to redirect I/O requests to a device that
not exist on the host system.

does

You specified a device in the LOAD command line
there is no data base.
This is caused by
conditions:

for which
one of two

The device does not exist in the system device tables.

You did not declare the device to be loadable and
therefore LOAD cannot find a loadable data base for it.

4..

You specified a device in the command line that has not
defined in the system image.

been

5..

You specified a device in the DEVICES command line that
not exist in the system image.

does

Device not mounted
Explanation: You failed to mount the device
system image file.

10-97

that

contains

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Device not redirectable
Explanation: You attempted to redirect a device that
(in its UCB) as not redirectable.

marked

VMR -- Device not terminal
Explanation: You attempted to set terminal characteristics for a
device that is not a terminal.
VMR -- Device not variable speed multiplexer
Explanation: You attempted to set the speed for a terminal that
is not attached to a DHII, DHUII, DHVII, DZII, DZQII, or DZVII
multiplexer.
VMR -- Directive common already loaded

Expl«rtation:

You attempted to fix in the RSX-IIM-PLUS
image! a directive coml'fton>t.hat is already fixed.

system

VMR -- Directive common not contiguous to DIRIIM
Explanation:
DIRIIM.
VMR -

Directive commons

must

loaded

contiguous

Directive common(s) not fixed in memory

Explanation:

NOt all of the directive commons
that
installed in the RSX-IIM-PLUS system image have been fixed.

were

VMR -- Driver already resident
Explanation: You attempted to load an already loaded device
driver or one that is permanently resident in the system image.
VMR -- Driver built with wrong STB file
Explanation: The symbol definition file for the driver you
attempted to load or unload is not compatible with the Executive
symbol definition file for the current system image. This means
that the driver has been built for another system and must be
rebuilt before you can load it into the current system.
VMR -- Driver cannot be unloaded
Explanation: You attempted to unload a permanently resident
driver (that is, a driver linked permanently to the Executive).
VMR -- Driver dispatch table is inconsistent
Explanation: You attempted to load a driver with an illegally
formatted driver dispatch table.
See the RSX-IIM Guide to
Writing an I/O Driver or the RSX-IIM-PLUS Guide to Writing an 170
Driver for more information.
VMR -- Driver not loaded
Explanation: In the UNLOAD command line, you specified a
not resident in memory.

driver

VMR -- Driver requires running system for LOAD/UNLoad
Explanation: The driver you requested has the symbols $ddLOA or
$ddUNL in its source. Support of driver load/unload calls can be
provided only by the MeR LOAD/UNLOAD commands.
10-98

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

VMR -- Executive common partition eliminated
E:xplanation: This is a warning message. One of the Executive
common partitions has been removed.
A system generated with
Executive common support must have both partitions installed to
run.
VMR -- Executive common(s) not installed
E:xplanation: This is a warning message. For a system generated
with Executive common support, you should install one (or both)
of the commons before you exit VMR.
Otherwise, the system is
unusable.
VMR -- Executive too large
E.xplanation: The Executive is too large to be accommodated in
the system image. This message indicates that the Executive is
larger than 20K. The system is unusable.
VMR -- External headers not supported
Explanation: You attempted to install a task built with external
headers in a system that was not generated with external header
support.

VMR -- Fast map not supported
Explanation: You attempted to install a ta.sk with the /FMAP=YES
keyword, without having first selected support for fast mapping
during system generation.
VMR -- Feature not supported in system image
Explanation:
reasons:

VMR displays this message for any of the

following

You attempted to create secondary pool in a system that
not support it.

does

You attempted to set a device public in a
not support multiuser protection.

does

You attempted to enable/disable the broadcast option for a
terminal, but the system is not a mUltiuser/multi-eLI system.

VMR

system

that

File <name> has illegal format
Explanation: The driver's symbol
illegal object code or data.

definition

file

contains

VMR -- File <name> has inconsistent data
Explanation:

This message can occur for the following reasons:

You attempted to fix a partition or a task that is
beyond the end of the system image file.

The partition for loadable drivers is logically beyond the
end of the system image file.
The system image is probably
corrupt.

The partition of the common library you are attempting to
load is logically beyond the end of the system image file.

10-99

logically

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

VMR -- File <name> not a valid driver task image
Explanation:

One of three things has occurred:

The driver's task image has been overlaid.

The driver has a header.

The driver has referenced a resident library.

VMR -- File not contiguous
Explanation:

VMR

This message can occur for the following reasons:

You attempted to install a task from a noncontiguous
Task images must reside on contiguous files.

The file ddDRV.TSK is not contiguous.
This
contiguous for a device driver to be loaded.

file.

file

must

the

directory

File not found
Explanation: You requested a file not located in
of the volume you specified.

VMR -- File not task image
Explanation: The data in the label block of the task you tried
to install is incorrect, indicating that the file is not a task
image.
VMR -- Illegal device/volume
Explanation: You attempted to save
invalid device. Valid devices are:
CT:
DD:
DT:
DU:
DX:
DY:
MM:
MS:
MT:
MU:
PP:
VMR

your

system

image

built

for

Tape cassette
TUS8 DECtape II
DEC tape
RXSO diskette/RA60 disk/RC2S disk (removable)
RXOI diskette
RX02 diskette
TE/TU16/TU4S/TU77 magnetic tape
TSll/TSVOS/TU80 magnetic tape
TE/TUIO/TS03 magnetic tape
TKSO cartridge tape/TU81 magnetic tape
Paper tape

Illegal driver task APR usage
Explanation: The device driver being loaded must
APR S and must be less than 4K-words.

VMR -- Illegal error severity code <code>
Explanation: This message indicates an internal failure in VMR.
If this error message persists, contact a DIGITAL software
representative.
VMR -- Illegal file specification <filespec>
Explanation: The file specification printed following the
message has an illegal format or contains wildcards.

10-100

error

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)

VMR -- Illegal first APR

VMR

Explanation: The task you tried to install was
incorrect base APR. The following rules apply:

built

using

A nonprivileged task must be built with APR
APR.

its

base

A privileged task that does not map into the
be built with APR 0 as its base APR.

Executive

must

If the Executive is 16K-words or less, a privileged task that
is to map to the Executive routines and data structures must
be built with APR 4 as its base APR.

If the Executive is 20K-words,
(or less on RSX-llM-PLUS
systems), a privileged task that is to map to the Executive
routines and data structures must be built with APR 5 as its
base APR.

Illegal function
E)C:planation: You entered a command that VMR does not recognize,
or the command line refers to a feature that is not supported in
the system.

VMR -- Illegal Get Command Line <error code>
Explanation: This message indicates a system failure.
If
error persists, contact a DIGITAL software representative.

the

VMR -- Illegal keyword value
EJI:planation:
range.

You entered a value for a keyword that

out

mapped

VMR -- Illegal operation for unmapped system
Explanation:
systems.

The SET /POOLSIZE keyword is valid only

VMR -- Illegal parameter for executive common partition
Explanation: You specified a parameter with SET /MAIN that is
illegal for an Executive common.
The partition size must be
200(octal) and the partition type must be COM.
VMR -- Illegal priority
Explanation: You specified an illegal priority for the task.
A
priority value can be a number from 1 to 250. 250 is the highest
priority and 1 is the lowest priority you can assign. A priority
is assumed to be octal unless you put a period (.) after the
priority number.
VMR -- Illegal slave attribute
Explanation: You attempted to install a task with the /SLV
but the task s name is in the form ... xxx. The task is
a prototype task and cannot be installed as a slaved task.

kE~yword,

VMR

Illegal switch <switch>
E:ltplanation: The switch following the error message is incorrect
in the context of the command line you have entered.

10-101

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Illegal use of <pname> partition or common
Explanation: You attempted
secondary pool partition.

install

task

CPU

into

common

VMR -- Illegal use of <pname> partition or region
Explanation: You attempted to load a driver
secondary pool partition.
VMR -- Illegal use of wildcard
Explanation: On an unmapped system, you cannot specify
a
wildcard (*) with the following SET keywords:
/TOP, /BOT, and
/POOL. You also cannot use a wildcard for the size parameter of
task partitions.
VMR -- Illegal value for symbol <symname> in file <filename>
Explanation: LOAD or UNLOAD has determined that symbol <symname>
in the STB <filename> has been defined to an illegal value. This
can occur for several reasons, some general and some specific to
individual symbols.
For example, most symbols generally cannot
be defined to zero or to an odd number. A specific example is
the symbol $INTSV, which must not be referenced by mapped
loadable drivers.
VMR -- Incorrect assignment of SY:

or LB:

Explanation: This is a warning message. The device SY: or LB:
is not assigned to the same device as the system image file you
are trying to work with in VMR.
VMR -- Indirect command syntax error <command-line>
Explanation: You
specification.

entered

improper

indirect

command

file

VMR -- Indirect file depth exceeded <command-line>
Explanation: You attempted to reference more than two levels
indirect command files.

VMR -- Indirect file open failure <command-line>
Explanation: The indirect command file specified in the
line could not be opened.

command

VMR -- Install device not LBO:
Explanation:
boot device.

You attempted to install a task from other than the

VMR -- Installed tasks or commons may no longer fit in partition
Explanation: This is a warning message.
You shortened
a
partition so that the tasks and/or commons that are installed in
it may no longer fit.
VMR shortens the partition even though
this situation exists.
VMR -- Interrupt vector already in use
Explanation: The interrupt vector for the driver being loaded
does not point to one of the nonsense interrupt entry points in
the system image.

10-102

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Invalid driver data base at offset xxxx in file <filename>
Explanation: The driver name has an invalid data base value at
offset xxxx relative to the symbol $ddDAT.
(See the RSX-IIM
Guide to Writing an I/O Driver or the RSX-IIM-PLUS Guide to
Writing an I/O Driver.)
VMR -- Invalid interrupt vector
Explanation: You specified an interrupt vector address
driver data base that is too high for the system image.

the

VMR -- Invalid keyword
Explanation: You specified a keyword that is
context of the command.

incorrect

VMR -- Invalid record address for file <filename>
Explanation: LOAD has attempted to write outside of the system
im.age file or at a byte boundary. Three possible causes are as
follows:
1.

A corrupted system image

An STB file that does not match the system image

An internal problem in VMR

VMR -- Invalid speed
Explanation: VMR displays
following reasons:

VMR

this

message

for

either

the

You requested a speed that the multiplexer line you specified
does not support.

You specified unequal receive and transmit speeds for a DZll,
DZQll, or DZVll multiplexer.
These multiplexers do not
support split speeds.
Invalid time parameter

Explanation: The time field you specified
line is incorrect.

the

RUN

command

VMR -- Invalid UIC
Explanation: You specified an illegal value for either a group
number or a member number. The numbers must be from 1 through
377(octal).
VMR -- I/O error on input file <filename>
Explanation:

An input I/O error occurred on the indicated file.

VMR -- I/O error on output device
Explanation: SAVE has encountered an I/O
de!vice while writing the system image.

error

the

output

VMR -- I/O error on output file <filename>
EJI:planation:

An output I/O error occurred on the indicated file.

10-103

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Keyword not supported for this terminal driver
Explanation: The terminal
driver
selected
during
system
generation does not support the specified SET keyword. For
example, typeahead is a full-duplex terminal driver option only
and your system uses the half-duplex driver.
VMR -- KRB <KRBname> interrupt vector <octal-number> in use
Explanation: You attempted to load a driver that specifies an
interrupt vector that is not pointing to a nonsense interrupt
entry point address. This is usually caused by a previously
loaded driver that has used this vector.
When you get this message, LOAD has loaded the driver
but it has not overwritten the interrupt vector.

correctly,

VMR -- KRB <KRBname> interrupt vector <octal-number> too high
Explanation: You attempted to load a driver that specifies an
interrupt
vector address that is higher than the highest
permissible vector address in the system.
When you get this message, LOAD has loaded the driver
but it has not overwritten the interrupt vector.

correctly,

VMR -- KRB <KRBname> not in loadable data base
Explanation: You attempted
to
load
the
driver
for
a
multicontroller device with a loadable data base. The special
symbol (KRBname) that defines the location of the KRB in the
multicontroller device's CTB table is not defined in the loadable
data base.
See the RSX-IIM-PLUS Guide to Writing an I/O Driver.
VMR -- KRB table of CTB <CTBname> will not accept KRB <KRBname>
Explanation: You attempted
to
load
the
driver
for
a
multicontroller device with a loadable data base.
If this
operation is to succeed, then the following conditions must
exist:
1.

The appropriate slot in the CTB must exist.

The slot in the CTB must be unused.

When VMR issues this error message, one of these conditions does
not exist. See the RSX-llM-PLUS Guide !.2 Writing .!!! I/O Driver.
VMR -- Length mismatch common block <blockname>
Explanation: The length parameter for the common block,
as
described in the label block for the task image, does not match
the corresponding length parameter defined in the system image.
A task's label block data must match system data for that task
before it can be installed.
VMR -- Line not DZll
Explanation: You attempted to set a line to remote that is not
attached to a DZll, but your system uses the half-duplex terminal
driver.

10-104

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Loadable driver larger than 4K
Explanation: This is a warning message.
driver that is larger than 4K-words.

You

are

VMR -- Loadable driver support not in system
Ell::planation: You attempted to load a device into a system image
that does not contain the Executive routine $INTSI. The routine
is needed to support loadable device drivers.
VMR -- Logical device not in system
Explanation: The device you specified has not been defined and
therefore ASSIGN could not find it in the logical device
assignment table.
VMR -- LUN out of range
Explanation: You attempted to reassign a LUN for a task that is
higher than the maximum number of LUNs allocated for the task
when it was built.
VMR -- No checkpoint space, assuming not checkpointable
Explanation: This is a warning message.
You attempted to
install
a
task as checkpointable that was not built as
checkpointable. This means that there is no checkpoint space
allocated in the task image file. Since the system image does
not support the dynamic allocation of checkpoint space,
INSTALL
does not consider the task to be checkpointable.
VMR -- No checkpoint space or dynamic checkpoint file
Explanation: You attempted to install a task built with external
or as checkpointable, but the task does not have any
checkpoint space and the system does not have a checkpoint file.

hE~aders

VMR -- No ICB pool space for CPU <cpu>
Explanation: The Interrupt Control Block
allocated for CPU <cpu> has been exhausted.

(ICB)

pool

space

VMR -- No LUNs
Explanation: The task that you specified as an argument of the
LUN command does not have any logical units assigned to it. This
is not an error message; rather, it is simply an indication that
there are no assignments to display.
VMR -- No pool space
Explanation: The pool space required to load the driver
available in the system image.

not

VMR -- No room available in STD for new task
Explanation: There is no dynamic storage available to make an
entry in the System Task Directory (STD). The task cannot be
installed.

10-105

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- NO table. space for optional directive common
Explanation: You attemptea to fix a directive common in the
RSX-IIM-PLUS system image, but the extra slots built into the
system data base for optional directive commons have all been
used.
VMR -- Nonexistent memory
Explanation:
memory.

You attempted to define a partition in

nonexistent

VMR -- Not enough APRs for task image
Explanation: The Task Builder allows you to specify, as a
mUltiple of 4K, the virtual base address of a task image.
Privileged tasks that access the Executive start at either
virtual address 100000(octal) for a 16K Executive or at virtual
address l20000(octal) for a 20K Executive. If the virtual base
address of the task is set too high, there are not enough APRs
remaining to map the task image.
(See the RSX-llM/M-PLUS and
Micro/RSX Task Builder Manual for information on privileged
tasks. )
VMR -- Old device attached
Explanation:

You attempted to redirect an attached device.

VMR -- Open failure on file <filename>
Explanation:

The indicated file cannot be opened.

VMR -- Operation cannot extend above first l24K of memory
Explanation: VMR displays
following reasons:

this

message

for

either

the

On RSX-llM, you attempted to fix a task above l24K-words.
The largest system that can be saved is l24K-words. If FIX
allowed you to fix a task above this limit, the task would be
lost when the system was saved.

You attempted to create with the SET command a CPU
whose upper limit is above l24K-words.

VMR

partition

Operation not allowed for <ptype> partitions
Explanation: You attempted a SET operation that is not allowed
for the type of partition specified in the error message.
,t,

VMR -- Optional directive common ,'successfully loaded
Explanation: This is an informational
message.
VMR
has
successfully fixed in the system image a directive common that is
not one of the commons required by RSX-llM-PLUS.
VMR -- Partition already exists
Explanation: VMR displays
following reasons:

this

message

for

either

the

You attempted to define a partition, using the SET
with a name already in use as a partition name.

You attempted to define a subpartition, using the SET
command, but there are no more subpartition slots available.
10-106

command,

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Partition or common region is busy
Explanation:
reasons:

VMR displays this message for any of the

following

You attempted to fix a task or common region in a
that is full. The task or region cannot be fixed.

partition

You attempted to load a device driver into a
the partition is full.

You attempted to remove a partition that still has
installed in it. The partition cannot be removed.

(RSX-IIM-PLUS systems only.) You attempted to remove a region
that is referenced by tasks installed in the system.

VMR

partition,

but
tasks

Partition <pname> is a common
Explanation: You attempted to load a device driver into a common
partition. This cannot be done.

VMR -- Partition <pname> is not a common
Explanation:
partition.

Partition <pname> was found, but it is not a common

VMR -- Partition <pname> is too small
Explanation: You attempted to load the driver into a partition
that is either too small for the driver or that does not
currently have enough space for the driver. Or, you attempted to
install a task that is too large for the specified partition.
VMR -- Partition <pname> not in system
Explanation: VMR displays
following reasons:

VMR

this

message

for

either

the

The partition you specified in the command line is not in the
system image.

You attempted to load a driver into a partition that does not
exist in the system, or LOAD found a symbol $xxCOM in the
driver and partition xxCOM does not exist in the system.
Partition <pname> not in system, defaulting to GEN

Explanation: This is a warning message.
You attempted to
install a task in a partition that does not exist. VMR will try
to install the task in the partition GEN.
VMR -- Partition 110t system controlled
Explanation: The SET command keywords /TOP and
only for system-controlled partitions.

/BOT

are

valid

VMR -- Partition reduced to executive ~ommon size
Ex.planation: This is an infoTational
message.
When
an
Executive common is installed in its partition, the partition is
reduced to the top of the common to eliminate any unused space in
the partition.

10-107

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Pool link error at xxxx Block=yyyy zzzz
Explanation: When SET /POOL traced the pool linkage, it detected
an error at location xxxx in the system image. The contents of
xxxx is yyyy and the contents of xxxx+2 is zzzz.
VMR -- Privileged task overmaps I/O page
Explanation: This is a warning message. A privileged task
may need access to the I/O page does not have that access.

that

A privileged task that is mapped to the Executive is often mapped
to the I/O page as well. Ho¥ever, many privileged tasks do not
require access to the I/O page and can use the extra 4K of
address space that would be allocated to the I/O page for the
task image.
If the task does not require access to
ignore this message.

the

I/O

page,

you

can

VMR -- Privileged task larger than 12K
Explanation: You attempted to install a privileged task that is
larger than 12K-words.
(See the RSX-llM/M-PLUS and Micro/RSX
Task Builder Manual for information on privileged tasks.)
VMR -- Pseudo device assignment error
Explanation: You attempted to assign a logical device name to a
pseudo device.
Logical device names cannot be assigned to pseudo
devices.
VMR -- Pseudo device redirect error
Explanation: You attempted to redirect one
another pseudo device. This is not allowed.

pseudo

device

VMR -- R/O partition <pname> not in system, defaulting to task's
Explanation: You specified a read-only partition that does not
exist in the system. INSTALL will place the read-only portion of
your multiuser task into the same partition as the read/write
portion of the task.
VMR -- Receive data or by reference list not empty
Explanation: A task with entries in its receive queues cannot be
removed from the system image.
VMR -- Reference to memory beyond end of system image file
Explanation: VMR attempted to fix a task,
load a driver, or
install a common beyond the space limits of the system image
file. As a result, the command does not execute.
VMR -- Saved system truncated to n. blocks
Explanation:
(RSX-llS systems only.) VMR tried to save a system
greater than n. blocks. This results in VMR truncating the saved
image file to n.: l12(decimal) blocks for 28K-word systems saved
on paper tape, 488(decimal) blocks for l22K-word systems saved on
RXOI diskettes, and 496(decimal} blocks for l24K-word systems
saved on all other bootable devices.

10-108

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Space used
Explanation: You attempted to create a partition
area that is already occupied.

storage

VMR -- Specified partition for common block
EJI:planation:

You attempted to install a task in a common block.

VMR -- Specified partition too small
EJI:planation:

VMR

This message can occur for the following reasons:

You attempted to install a task
smaller than the task.

into

partition

that

You attempted to install a driver into a
smaller than the driver.

partition

that

Symbol <symname> is doubly defined by file <filename>
EJI:planation: The symbol symname is defined twice
in
the
specified file.
Duplicate symbols are illegal. The driver is
not loaded or unloaded.

VMR -- Symbol <symname> is undefined in file <filename>
Explanation: LOAD found the symbol
file, but the symbol is not defined.

symname

the

specified

VMR -- Syntax error
EJI:planation:

You have type~ the command line incorrectly.

VMR -- System image is not RSX-l1M-PLUS
E.xplanation: You attempted to use
non-RSX-IIM-PLUS system image file.

RSX-11M-PLUS

VMR

VMR -- System image is RSX-11M-PLUS
Explanation: You attempted to use RSX-11M VMR on an RSX-IIM-PLUS
system image file.
VMR -- Task active
Explanation: The task
command is active.

you

specified

argument

the

VMR -- Task and partition bases mismatch
EJl:planation: The base of the partition does not match that of
the task being installed or of the driver being loaded. This
mE!Ssage applies only to unmapped systems.
VMR -- Task or common region already fixed
EJl:planation: You attempted to fix' a task
mE!mory that is already fixed.

10-109

common

region

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Task has attached common regions
Explanation:

This message can occur for the following reasons:

You attempted to fix or unfix a task in memory that is linked
to a shared region. VMR cannot fix or unfix such tasks.

You attempted to remove a task that is linked to a shared
region from the system image. VMR cannot remove such tasks.

VMR

Task image currently installed
Explanation: You attempted to install a checkpointable task that
has checkpoint space allocated in its task image.
The task has
already been installed.

VMR

The system allows you to install checkpointable tasks
once subject to the following rules:

than

You must allocate checkpoint space for the task in
checkpoint file.

system

You must use a different name for
install it.

time

the

task

each

you

Task image I/O error
Explanation: The task cannot be installed or the driver cannot
be loaded.
VMR could not read the task image file or could not
rewrite the task image header.
The specified device may be
write-locked.

VMR -- Task image virtual address overlaps common block <blockname>
Explanation: The virtual addresses you reserved for the task
image overlap those you reserved for the common block specified
in the error message. Corruption of the task image file may have
caused the overlap.
VMR -- Task is checkpointable
Explanation: You attempted to fix a checkpointable
memory. Checkpointable tasks cannot be fixed.

task

VMR -- Task is not multi-user
Explanation: You attempted to fix the read-only portion of a
multiuser task in memory, but the task you named in the command
line is not a multiuser task.
VMR -- Task name already in use
Explanation: You attempted to install a task of the same name as
that of one already installed in the system image.
VMR -- Task not installed with external header
Explanation: This is a warning message to indicate that the
specified task is installed with its header in pool (the dynamic
storage region).
VMR -- Task not in system
Explanation:
system.

You referenced a task that is not installed in

10-110

the

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Task not removed, CLI has messages enabled
Explanation: You attempted to remove a CLI task that is able to
rE~cei ve
messages from the system. The task may have messages
that it has not received yet, so the remove request is aborted.
VMR -- Task or common not in memory
Explanation: You attempted to remove a task or common from
system that is checkpointed and, therefore, not in melnory.

the

VMR -- Task or common region is not fixed
Explanation: You attempted to unfix a task that is not fixed
the system image.

VMR -- Task or common region not in system
Explanation: You referenced a task or common region that has not
installed in the system or, on RSX-IIM-PLUS, you attempted
to run a prototype task.

bE~en

VMR -- Task requires system controlled partition
Explanation: You attempted to install a task that was built with
e~{ternal header (/XH) support and as checkpointable (TKB / CP, INS
/CKP=YES). Such tasks must be installed in a system-controlled
partition.
VMR -- TI redirect error
Explanation: You attempted to redirect the
TI: cannot be redirected.

pseudo

device

TI:.

null

VMR -- TT redirect error
Explanation: You attempted to redirect a terminal
d4:!vice. This combination is not allowed.

the

VMR -- Too many common block requests
E:lCplanation: You attempted to install a task that contains too
ma.ny common block requests. A task is limited to seven common
block references.
VMR -- Too many LUNs
E:lCplanation: You attempted to install a task that contains
than 250(decimal) LUN assignment requests.

VMR -- Too many symbols of the form $xxTMO in file name
E:x:planation: LOAD is attempting to extract symbols of the form
$x:xTMO from the driver's symbol definition file. There are more
symbols of this form than LOAD can process.
VMR -- Top of pool set to <value>, requested amount not available
E.xplanation: You requested more pool space than the system can
provide. The system provides as much as possible in this case.
VMR -- Undefined common block <blockname>
Explanation: You attempted to install a task that references a
common block that is not defined in the system image. This
message may indicate that the task was built for another system.
10-111

VIRTUAL MONITOR CONSOLE ROUTINE (VMR)
VMR -- Unknown partition
Explanation: You attempted an operation on a partition that does
not exist in the system.
VMR -- User O-space not supported
Explanation: An attempt was made to install a task with separate
instruction and data space on a system that does not support user
O-space.
(User O-space is a system generation option.)
VMR -- Virtual terminal error
Explanation: You attempted to enable, using the SET
terminal option for a virtual terminal.

command,

VMR -- Write-check not supported for device
Explanation: You attempted to enable write-checking for a device
that does not support it. Write-checking is supported for all
disks except RLOls and RL02s (OL:) and RXOls (OX:).

10-112

CHAPTER 11
COMMAND LINE INTERPRETERS

11.1

INITIAL CONCEPTS

A command line interpreter, or CLI, is a task that
services
unsolicited commands meant for the operating system or an application.
These commands are not prompted for by any task nor are they given to
a task by a read operation on a terminal.
The best-known CLI on RSX-llM and RSX-llM-PLUS systems is MCR, which
controls the operating system.
MCR, like any other CLI, receives
command lines that originate as unsolicited input typed on a terminal
or as issued by a task using an Executive directive. Since all lines
typed on a terminal are seen by the CLI (except those used to satisfy
a task's read requests), the CLI task is, in effect, a complete user
interface. This control over the user at the terminal is absolute.
There is no way to bypass a CLI to send commands to the system or
application.
A eLI is also an efficient means of interfacing an application command
processor to any number of terminals, since no read QIO or character
AST processing is involved. The input from the terminal simply goes
to the CLI by default for processing.
This chapter introduces the concepts of CLls on
RSX-llM
and
RSX-llM.-PLUS systems.
The chapter provides enough information to
allow a programmer to write application-specific CLls.
A brief
description of three DIGITAL CLls supplied with the system illustrates
these concepts. These three system CLls do quite different things
with the command lines they process, but the basic goal of each is the
same: to provide a specific environment for the terminal user.
This
basic goal also applies to any application-specific CLls, which, of
course, may perform completely different command processing functions.
A simple sample CLI
written in both FORTRAN and MACRO-II - is
included in this chapter.
The example is also included on the
distribution kit in either LB:[1,2] with the HELP files or in the
new-user directory [200,1] on RSX-llM systems,
or
[USER]
on
RSX-llM,-PLUS, as TMCLI.MAC and TMCLI.FTN. See your system manager for
more information. The example illustrates the CLI interface and
should clarify the basic operations of a CLI.
NOTE
This chapter describes features available on RSX-llM
and RSX-llM-PLUS. RSX-llS systems include Basic MCR,
but do not support the CLI features discussed in this
chapter.

11-1

COMMAND LINE INTERPRETERS
11.1.1

MCR - The Traditional RSX-llM/M-PLUS CLI

The most important CLI on RSX-llM/M-PLUS systems is MCR. MCR receives
commands from the terminal and executes them to control the system.
MCR is a set of privileged tasks. These tasks call Executive routines
and interact with the system's data base. Therefore, MCR is tied very
closely to the Executive. This bond is necessary because of MCR's
function in system control and has nothing to do with MCR's role as a
CLI.
Most other CLls interact with an application running on the system,
rather than with the system itself. Therefore the CLI designer need
not have any knowledge of RSX-llM/M-PLUS internals.
In fact,
the
resulting CLI need not even be privileged.
The only similarity
between MCR and other CLls is that any CLI controls the terminals
associated
with
it just as MCR does.
Every terminal on an
RSX-llM/M-PLUS system is set to some CLI. Users can do nothing on
their terminals that their CLI does not permit. The CLI controls the
use of the terminal.
NOTE
While MCR is a CLI, it is a special CLI. MCR does not
use the CLI interface directives because it must work
on systems that do not support these directives.
Therefore, MCR is not a pattern for other RSX-llM and
RSX-llM-PLUS CLls.

11.1.2

DCL - DIGITAL Command Language

The DIGITAL Command Language (DCL) interpreter is a CLI that does not
actually execute any commands. DCL provides an interface to operating
system features by translating the commands it receives in DCL syntax
to the equivalent MCR commands.
DCL then passes the translated
command line to the appropriate MCR task or utility for execution.
The CLI interface hides this operation from the user at the terminal,
who does not need to know about MCR or the utilities. DCL is oriented
towards operations, such as COpy or LINK, rather than towards tasks
like PIP and TKB. DCL presents a totally different external interface
to RSX-llM/M-PLUS, one that is easier to learn and use than MCR. This
makes it possible for less technical users
to
do
work
on
RSX-llM/M-PLUS.

11.1.3

RMT - DECnet Remote Terminal Facility

The RMT task is a CLI that gathers commands from the terminals
associated with it and sends them over a DECnet network to be executed
on a remote RSX-llM/M-PLUS system.
The RMT interface provides a
mechanism for command handling with a minimum of overhead or effect on
user tasks. RMT is different from DCL: RMT does not interpret the
command strings it handles, while all DCL does is interpret strings.
All the interpretation and execution of commands passed through RMT is
done by the CLI that receives the commands on the remote system.

11.2

WRITING AN APPLICATION CLI

A CLI is an RSX-llM/M-PLUS task, like any other.
It need not be
privileged unless the application requires it. Any alternate CLI is
expected to interact with the operating system in a certain way,

11-2

COMMAND LINE INTERPRETERS
however. This is necessary to synchronize with the operating system
in command handling and prompting.
This interaction is achieved
through a set of Executive directives for CLls.

11.2.1

Executive Directives for CLls

The most important directive is GCCI$
(Get Command for Command
Interpreter). GCCI$ must be used by every CLI, no matter what the CLI
does. GCCI$ supplies a command to the CLI from a queue maintained by
the system.
It also controls the internal status bits necessary for
correct synchronization of prompting and general command handling in a
manner transparent to the CLI task.
Other CLI directives include the following:
1.

RPOI$ (Request and Pass Offspring Information) and SDRP$
(Send,
Request, and Pass), which can be used to pass the
responsibility for handing a command off to another task so
the CLI is free to handle another command.

SCAA$ (Specify Command Arrival AST), which specifies an AST
in the CLI whenever a command arrives for processing by the
CLI.

GCII$ (Get Command Interpreter Information), which
information about a terminal or CLI to the task.

returns

See the RSX-llM/M-PLUS and Micro/RSX Executive Reference Manual for
complete description of these directives.

11.2.2

Basic Interaction with the Operating System

Before a CLI can process commands,
it must be made known to the
system.
This is done by installing the CLI task with the /CLI=YES
switch and then initializing the CLI with the CLI /INIT command. This
process creates an internal data structure that allows the system to
recognize the existence of the CLI.
See the RSX-llM/M-PLUS MCR
Operations Manual for a description of the INSTALL command and the CLI
commands.
A CLI's operation starts when a command is entered into the system.
The command may originate as a command line typed on a terminal or
from an Executive directive issued by a task.
The source of the
command is generally irrelevant to the CLI. The command is processed
first by the system command dispatcher (the MCR ... task). This task
puts the command into a FIFO queue of commands to be retrieved by the
CLI. The CLI associated with the terminal from which the command
originated is then requested to run (or unstopped if it is already
active). The CLI gets the command from the system by issuing the
GCCI$ directive.
This directive removes a command from the CLI's
queue and copies it into a buffer in the CLI's task space. GCCI$ can
also supply information about the source terminal to the CLI.
Once the CLI has the command, it is free to process it in any manner
it chooses. Generally this involves executing the command, or passing
the command to another task for execution. If the CLI is g01ng to
pass the command to another (non-CLI) task, it should use the RPOI$ or
SDRP$ directive to do this, assuming the CLI has no further interest
in the command. These directives propagate the information the system
needs for controlling, prompting and getting exit status back to a
parent task (if any).
The CLI's obligations to the command are

11-3

COMMAND LINE INTERPRETERS
complete once the command has been passed off; there is no reason for
the CLI to get involved again. This is the recommended procedure for
handling commands, as it avoids the wait for the preceding command to
complete execution. DCL works in this way, translating a command into
a different format and dispatching it to another task for execution.
CLls that process commands themselves should be very careful about
handling any possible delays in execution. This is especially true if
the CLI is to do I/O to a terminal; this means any terminal I/O,
including prompts for input. Otherwise, it would be very easy for one
user to suspend command handling by not responding to a prompt or by
pressing CTRL/S.
Once a CLI has completed processing a command, it must reissue the
GCCI$ directive to get any other command which may have been queued to
it. If the CLI wants to stop or exit when no commands are queued to
it, it should do this by issuing the GCCI$ directive with the
appropriate no-command action specified.
This prevents a command
queued between the return from the GCCI$ and the issuance of an EXIT
or STOP directive from being lost, or not processed until the next
command is queued.

11.2.3

Task Names for CLls

CLls can be installed with task names in the form ... xxx (commonly
called a prototype task name) or with names in some other legal form,
such as xxxxxx (commonly called a conventional task name).
If the CLI has a prototype task name, the system creates a separate
copy of the CLI each time a command is entered on a terminal set to
that CLI. The task is named xxxtnn, following the same general rule
as any other task installed in the system with a prototype task name.
Each copy of the CLI runs with the same TI: and UIC as that of the
terminal the command came from. These tasks should exit when there is
no work left for them to do.
If the CLI has a conventional task name, all commands from all
terminals associated with the CLI are queued to a single copy of the
task. This task runs with a TI:
of CO:
(console output pseudo
device).
CLls with conventional task names must specify the TI: and
UIC fields in any RPOI$ or SPWN$ directives they issue, or the TI:
and UIC will not default correctly. Because there is only one copy of
these tasks in the system, CLls with conventional task names can
simply stop (rather than exiting) when there are no commands queued
for them. This may be necessary if the CLI must maintain information
from one command to the next.
DCL is installed with a prototype task name, ... DCL. RMT is installed
as RMT ... , with a conventional task name. The difference reflects the
use and nature of each CLI.
DCL must be installed with a task name of ... DCL because most DCL
commands issue prompts for input. No command processing can be done
by DCL while it is waiting for the user to respond to a prompt.
If
there were only one copy of DCL on the system, command processing for
all DCL terminals would stop while a prompt request to anyone
terminal
was
outstanding.
This is clearly not an acceptable
situation.
Giving each terminal its own copy of
DCL
allows
independent command processing for each terminal.
To avoid filling

11-4

COMMAND LINE INTERPRETERS
the sysltem with copies of DCL, the individual copies of the task exit
when no commands are left for them. They can do this because there is
no need to maintain any context between commands.
On the other hand, RMT is installed as RMT ... because there can only
be one copy of RMT in the system. This is because RMT provides a
focal point with which the DECnet command handling software running on
the remote system can communicate. Furthermore, it is not practical
to have RMT exit when no commands are outstanding, because it is
necessary to maintain context between commands. If each user got a
separat 9 copy of RMT, the system would be cluttered with copies of RMT
that did not exit.
l

11.2.4

MCR Control Commands

The MCR CLI command is the means by which the system has knowledge of
CLls.
The CLI command has switches which perform such functions as
making a CLI known to the system, eliminating it from the system,
turning on and off its recognition of commands, and so forth. See the
RSX-llM/M-PLUS MCR Operations Manual for a description of the CLI
command.

11.2.5

System Messages to CLls

Depending on the nature of the CLI, it may be necessary for it to
receive messages notifying the CLI of the occurrence of certain events
that could effect it. If the /MESSAGE subkeyword to the CLI /INIT
command is specified, it can receive messages from the system
informing the CLI of such events. These messages are returned by the
GCCI$ directive just like commands .. They can be differentiated from
commands by the first word of the command buffer (G.CCDV) being
cleared, instead of being set up with the name of the device from
which the command originated. The code identifying which message is
present is returned in the unit number byte (G.CCUN). The other
fields have the same meaning for messages as they do for commands.
The actual text field of the buffer may be empty if the message does
not contain any ASCII text. See the RSX-llM/M-PLUS MCR Operations
Manual for further information.
NOTE
The CLI command includes both a/MESSAGE subkeyword to
the
/INIT keyword and a /MESSAGE keyword.
The
/MESSAGE subkeyword specifies that the CLI being
initialized
can
receive messages.
The /MESSAGE
keyword sends an ASCII message to a CLI that has been
initialized with the /MESSAGE subkeyword. See the
RSX-llM/M-PLUS MCR Operations Manual for
further
information.

11.2.5.1 CLI
Message
Descriptions - Message
codes
1
through
l27(decimal) are reserved for use by DIGITAL. Users wishing to create
their own messages to CLls should use codes in the range of
l28(decimal) through 255(decimal). The symbol shown for each message

11-5

COMMAND LINE INTERPRETERS
code
is
defined
in
the
Executive
definition
library:
LB:[l,l]EXELIB.OLB.
Tasks may pick them up at build time by linking
with that library. Messages are as follows:
CLI Initialized into an Enabled Mode
Message Code: 1 (CM.INE)
Text: CLI name in RADSO, length = 4 bytes
Explanation:
This message is sent to a CLI when it
initialized by a CLI /INIT command without specifying
/DISABLE switch.

is
the

CLI Initialized into a Disabled Mode
Message Code: 2 (CM.IND)
Text: CLI name in RADSO, length =.4 bytes
Explanation:
This message is sent to a CLI when it
initialized by a CLI /INIT command with the /DISABLE switch.

CLI Enabled
Message Code: 3 (CM.CEN)
Text: None.
Explanation: This message is sent to the CLI when it is
by a CLI /ENABLE command.

enabled

CLI Disabled
Message Code: 4 (CM.CDS)
Text: None.
Explanation: This message is sent to the CLI when it is disabled
by a CLI /DISABLE command.
CLI Eliminated
Message Code: 5 (CM.ELM)
Text: None.
Explanation: This message is sent to a CLI when
eliminated by an explicit CLI /ELIMINATE command.

has

been

All CLls Eliminated, and must Exit
Message Code: 6 (CM.EXT)
Text: None.
Explanation: This message is sent to all CLls on the system
which were initialized with the /MESSAGE subkeyword to the CLI
/INIT command when a CLI /ELIM=* command is issued. A CLI that
receives this message should exit as soon as possible, since
system shutdown or other emergency procedure is taking place.
11-6

COMMAND LINE INTERPRETERS
Terminal Linked to CLI
Message Code: 7 (CM.LKT)
Text: Name (ASCII) and unit number (octal) of terminal, length
4 bytes.
(2 bytes each).
Explanation: This message is sent to a CLI when a terminal
becomes associated with it. This message could result from a SET
command processed by MCR, or any other use of the SCLI$
directive.
Terminal Removed from CLI
Message Code: 8.

(CM.RMT)

Text: Name (ASCII) and unit number (octal) of terminal, length
4 bytes.
(2 bytes each).
Explanation: This message is sent to
when it is switched to another CLI.

terminal's

former

CLI

General Message
Message Code: 9.

(CM.MSG)

Text: Name (ASCII) and unit number (octal) of terminal where the
CLI /MESSAGE command originated, followed by the text from the
command string. The length is equal to the length of the string
(possibly zero) plus the length of the terminal name and unit
number (2 bytes each).
Ex:planation: This message is the result of a CLI /MESSAGE
command.
It contains whatever text the issuer of the command
included in the string, plus the name and unit number of the
te·rminal on which the command was typed.

11.2.6

Prompts that Affect CLls

There a.re three kinds of prompts issued
CLls. These prompts are as follows:
1.

the

system

that

affect

CTRL/C Prompts - This prompt is issued by the terminal
driver when it receives a CTRL/C character. The string to be
There
issued can be specified when the CLI is initialized.
is no way the CLI can be notified when this prompt is issued,
These
however, since it is handled by the terminal driver.
prompts are of no other concern to CLls.

11-7

COMMAND LINE INTERPRETERS
2.

Empty-Line Prompts - This prompt results from terminal input
consisting solely of a carriage-return character, which is
called a null command line. The standard system action is to
have the MCR ... task issue the default prompt, which can be
specified when the CLI is initialized.
The CLI can be
initialized with the /NULL switch, which causes the system to
send null command lines to the CLI like other commands, and
not output anything.
Any prompting or other action is
therefore the CLlis responsibility.

Task-Exit Prompts - These prompts are issued when a task
started by a command line exits. The standard system action
is to have the MCR ... task issue the same default prompt
string as in the case of an empty line. If the CLI wishes to
be informed of these occurrences, it can be initialized with
the /PROMPT switch, which causes the system to send these
task exit prompt requests to the CLI without terminal output.
Any
prompting
or
other
action
is
then the CLlis
responsibility.
RSX-llM .... PLUS systEmts,. a.e1.I initia~i:1&ed t',orecelve either
empty-line.; or . ta8k .... ~ltit ..•.p~otnpts .. has; to. is.us< an. SNXC$
directi vewhen>its pr9c:essing .< of the prompt.. is complete.
SNJKC$ . tellsthe.t.e~~nalQf~verth~tthe ~urrent;command is
complete, • and it. can sen4 the nextonei'if the 'terminal is in
serial processing mQ(le..'l:'his directi,,~ can beis·sued if the
terminal i$notin se:r:ia1~e·witllout~nya4verse effects.
See Section 11.2,6, Seria,lCommandJ?)tocessing,forfurther
details.
On.

11.2.7

System Handling of Continuation Lines

Continuation lines .are'h.ndled):)y the RSX ....llM.....·.,LUS terminal driver
before the: command is' passed to theCLI~ '!nco':pletesegments. of
command linlas are detected•.. b~ .. the presence of ahyph.n as the
characterd.mmediatelyprece<il;:n9j:;he' . . . termi~1Cltpr
Any. hyphens are
removed and all. the piece8iofthe cQ111ltland.·. pu;t t~ether .• ·before . the eLI
is aware ..pf the COJ'llll'lttndiso. thE!! .CL~ doesnot.haveto4ealwith
continuation lines.··.ln •. an~ way ••...... If toe .CLldoes. ;~ot want. . tbe . system to
interpret the prElsenceof.thEJl1yph,nasch~r1ot.tt'l.' aq9ptlnuatlbn line,
the eLI can be .init.ialized withtlle ISNGL.switc::h •........ This '. tell.8the
system tea.ccept.iJlJgle~irte ceJtUDan(ls o.nly,~pd pas$every line tot.he
CLI as it is enteredJONo continuation line checks are made.
It

.' •

The DCL CLI en RSX-llM does its own handling ef continuation lines.
This is done within DeL itself, and is not available as a general
system feature. This optien is open to CLls on RSX-llM systems, but
is not necessarY forCLIson.,RSX ....llM....PL'OSas<tl!le system puts all the
segments together before the CQmmand!$ sent to the eLI.

11.2.8

Int~raction wi1;hS~,rial.eomma'd

Pr()o... siJl9 (!tSX-11M-PLUS only)

Serial co~nd proc.essingis a.rnQdeinwhiohoommandsfro.m a terminal
are executed in sequentialo.rder,.with a command not being started
until the preceding comma.nd i,finished. The default for command line
processing. on RSX-:-llM,...PLLJSsy,.tems is p.r.~le.l.:process~ngt but a eLI
may need to synchl'onizecommartd..s:anmand$ynchrorti~ation is achieved
by having the termlnal<trivers'torecharactersin the typeahead buffer
if thElY are enteredwbilEJ a cQll,ftand,i$out'sta.nding on tnatterminal.
These characters are issued as the next commatur by a speCial call to

11-8
I"

COMMAND LINE INTERPRETERS

11.3

SAMPLE CLI

Following is a sample CLI, written in both MACRO-II and FORTRAN. This
sample CLI appears in the simplest form possible, so you can easily
learn what is necessary to construct a CLI.
The same MACRO-II and
FORTRA]l programs used here are included on your kit as TMCLI.MAC or
TMCLI.FTN. The primary function of TMCLI is to receive commands and
pass them to MCR for execution.
In addition, TMCLI features two
single letter commands: T to type a file and M to switch back to MCR
mode.
The
comments
in
each sample listing suggest several
modifications that you can make when designing or setting up a CLI.

11-9

COMMAND LINE INTF-RPRETERS
11.3.1

MACRO-II CLI
.:.TITLF TMCLl _. EXAMPLE eLI THAT IMPI.. EMENTS "T" ANft "M" CnMHAND
11.00/

.IDENT

THIS TASK (TMClI) ILLUSTRATES THE USE OF THE ClI CONTROL ftIRECTIVES OF
RSX-l1M V4.0 AND RSX-l1M-PLUS V2.0.
WHEN SET UP AS A TERMINAL'S ClI, IT PROVIftES THE FOLLOWING COMMANDS:
T
M

TYPE FILE
SET TERMINAL TO MCR

IF THE FIRST TWO LETTERS OF THE COMMAND ARE NOT "T" FOLLOWED
BY A SPACE, OR "M" FOLLOWED BY A CARRIAGE RETURN,
THE COMMAND IS PASSED TO MCR FOR EXECUTION. THEREFORE,
USERS AT TERMINALS SET TO THIS ClI WILL SEE THE ENTIRE MCR COMMAND SET
AS BEING PRESENT, PLUS THE "T" AND "M" COMMANDS. IF THE IDPR SUBKEYWORD
IS INCLUDED ON THE CLI IINIT COMMAND, USERS WILL KNOW IMMEDIATELY IF
THEIR TERMINAL IS SET TO THIS CLI BY THE DOUBLE RIGHT ANGLE BRACKET PROMPT.
IF TMCLI IS INITIALIZED WITH THE IMfSSAGE KEYWORD, TMCLI WILL
GREET USERS WHEN THEIR TERMINAL IS SET TO THE ClI, AND SAY GOODBYE
TO THEM WHEN THEY SWITCH AWAY.
I N ORDER TO BR I NG TH I 5 CL. r. UP ON THE SYSTEM, I SSUE THE FOLLOW I NG
COMMAND SEQUENCE:
)MAC
>TKEt
)INS
>ClI

TMCLI,TMCLI/-SP=TMClI
TMCI... I , TMCI. . I 1- SP=TMCl. I , [ 1 , 1 ] EX E'- I BI LB
TMCLI/CLI=YES/TASK= ••• TMC
IINIT=TMCLI/MESSAGE/DPR="<15><t2)/»I"/TASK= ••• TMC
TO SET TERMINALS TO THIS ClI, ISSUE THE FOL.LOWING COMMAND
WHERE TTNN: IS REPLACED BY THE TERMINAL NUMBER OR TI:

>SET ICLI=TTNN:TMCLI
NOTE THAT THE PROMPT ISSUED IN RESPONSE TO A CONTROL./C DEFAULTS TO THE
NAME OF THE ClI, WHICH IS "TMCll>".
TMCLI CAN BE ELIMINATED FROM THE SYSTEM BY THE FOLLOWING COMMANDS, ASSUMING
NO TERMINALS ARE SET TO IT:
>CLI IELIM=TMClI
>REM ••• TMC
EXPERIMENT WITH THE OTHER SUBKEYWORftS OF THE CL.I IINIT COMMAND, THE Cl.I
IENABl.E AND CLI IDISABL.E COMMANDS, AND WITH THE IMESSAGE SWITCH ON THE IINIT
COMMAND TO OBSERVE THE EFFECTS. Al.SO TRY CHANGING THE ITASK=
SWITCH ON THE INS AND Cli IINIT COMMAND TO "/TASK=TMCI_I" AND NOTICE
THAT ONLY ONE COpy OF THE TASK WILL EXIST FOR ALL TERMINAL.S, RATHER THAN
ONE PER COMMAND. IF YOU DO THIS, YOU SHOUI..D ALSO CHANGE THE OPTION
ON THE GCCI$ DIRECTIVE FROM GC.CEX TO GC.CST SO THE TASK WIL.l. STAY ACTIVE
BUT STOPPED WHEN NO COMMANDS ARE OUTSTANDING FOR IT.

II rr~ECT I VE [lPBS

11-10

COMMAND LINE INTERPRETERS

GCCI:
RPOI:

(now:
ALUN:
i

GCCI$
RPOI$
(nOW$
ALUN$

CMDBUF,CBLEN,IBUF,IBLEN,O,GC.CEX
MCR •••
IO.WVB,5,1",,(,,40>
5

BUFFEIR AREAS

CMDBUF: • BLKB

80.+G.CCBF

CBLEN=.-CMDBUF
.EVEN

;LENGTH = HEADER PLUS COMMAND IN BYTES
iNOTE THAT ON M-PLUS THE MAXIMUM COMMAND
iLENGTH IS 255. BYTES, SO THE lENGTH SHOULD
iBE <255.+G.CCBF) OR CHARACTERS MAY BE L.OST.
iCALCULATE LENGTH

IBUF:
.BLKB
IBLEN=.-IBUF
.EVEN

G.CCCA+2

iLONG ENOUGH TO CONTAIN All. JNFORMATION
;CALCUl..ATE LENGTH

TCMD:
.ASCII
TCLEN=. -TCMII
BUF:
.BlKB
.EVEN

IPIP TI:=I

i BAS I C PIP

MCR:
.ASCII
MCMD:
.ASCII
MCLEN=.-MCMD
.EVEN

80.-TCLEN

IM/<15>
%SET IMCR=TI:%

COMMAND TO J MPL.EMENT • T· cm1MAND
;LENGTH OF COMMAND
;BUFFER TO GENERATE COMMANDS IN
iSTRING TO RECOGNIZE AS A SFT TO MCR REQUEST
;SET TERMINAL TO MCR COMMAND
iLENGTH OF COMMAND

TEXT TO BE DISPLAYED UPON RECEIPT OF NEW TERMINAL-L.JNKED OR
TERMINAL-REMOVED MESSAGES FROM SYSTEM.
;

lKT:
.ASCII
LKTLEN=.-LKT
.EVEN

<15><12>/WElCOME TO THE EXAMPl.E ClI/<15><12>

RMT:
.ASCII
RMTLEN::. --RMT
.EVEN

<15><12>/GOOD BYE FROM THE EXAMPL.E ClI/<15><12>

MESSAGE FOR CHARACTERS LOST DUE TO BUFFER BEING TOO SMAI L
CHLOST: .ASCII
CLLEN=.-CHLOST

<15><12>/SORRY, PART OF YOUR COMMAND WAS LOST/<lS><12>

; ILLEGAL COMMAND MESSAGE
;

ILL:
.ASCII
ILLLEN:::.-ILL
.EVEN

<15><12>/ILLEGAL COMMAND/<15><12>

CLI CODE

START:

.ENABL
DIR$
Bes

LSD
tGCCI
100$

;GET A COMMAND FROM SYSTEM
iIF CS, DIRECTIVE ERROR

IF THE GCCI$ DIRECTIVE HAD THE GC.CST OPTION SPECJFIED, WF MAY HAVE
JUST BEEN UNSTOPPED, SO WE HAVE TO GET THE COMMAND.

11-11

COMMAND LINE INTERPRETERS

CMP
BEO
MOV
TST
BEO
CMPS
BLO
MOV

tIS.CLR,SDSW
;WERE WE JUST UNSTOPPED?
START
;IF EO YES
tCMDBUF,RO
;POINT TO COMMAND BUFFER
(RO)
;rs THIS A SYSTEM MESSAGE?
MSG
;IF EO YES
G.CCCT(RO),G.CCCL(RO) ;DID ENTIRE COMMAND FIT IN BUFFER
150S
;IF LO NO
tRPOI,R5
;POINT TO DPB OF RPOIS DIRECTIVE

AT THIS POINT, THE CLI HAS A COMMAND TO BE PROCESSED. THE CODE FROM
THE 'START:I LABEL TO HERE SHOULD BE FAIRLY COMMON AMONG ALL ClIS.
FROM THIS POINT ON, THE CODE WILL BE SPECIFIC TO THE PARTICULAR LANGUAGE
THIS ClI IS IMPLEMENTING. COMMANDS CAN BE ADDED OR DELETED AT WILL
BY MODIFYING CODE IN THIS SECTION. AS STATED ABOVE, THIS EXTREMELY
SIMPLE CLI PROVIDES TWO COMMANDS, AND GIVES EVERYTHING ELSE TO MCR.
THIS CREATES AN OPEN ENDED ENVIRONMENT. REJECTING UNRECOGNIZED COMMANDS
INSTEAD OF PASSING THEM TO MCR WOULD LIMIT THE TERMINAL USER'S USE OF
THE SYSTEM TO ONL.Y THOSE OPERATIONS AL.L.OWED BY THE CLI. TH1S IS
A SECURE WAY OF CONTROllING SYSTEM USE, IN CASES WHEN IT IS NECESSARY.
IN THIS EXAMPLE, CHANGING THE IBNE 50$1 BELOW, TO A aBNE 60S 1
WOUL.D CREATE AN ENVIRONMENT WHERE THE ONLY OPERATION A USER COULD
PERFORM WOULD BE TO TYPE FILES ON THE TERMINAL, OR SWITCH BACK TO MCR.
ALL OF THE REST OF THE SYSTEM IS INACCESSIBLE. IF NO MEANS OF SWITCHING
BACK TO MCR IS PROVIDED, IT IS IMPOSSIBLE FOR THE USER TO DO
ANYTHING THE CLI [lOES NOT EXPLICITLY I..ET HIM [10.
CMP
BEO
CMP

taT ,G.CCBF(RO) ;IS IT A ~TI COMMAND?
10$
;IF EO YES
MCR,G.CCBF(RO) ;IS IT AN IM a COMMAND?

CHANGE THE NEXT INSTRUCTION TO aBNE 60S 1 TO ELIMINATE PASSING UNKNOWN
COMMANDS TO MCR.
BNE

50$

;IF NE NO

THE USER HAS ENTERED AN IMI COMMAND, SO SET THE TERMINAL. TO MCR.
MOV
MOV
BR

tMCMD, R. F'OBF (R5) ; PUT ADDRESS OF CMD TO I SSlJE IN DPB
tMClEN,R.POBL(RS) iPUT LENGTH OF CMD IN DPB
ISSCMD
;ISSUE COMMAND

THE USER HAS ENTERED A aT a COMMAND SO CONSTRUCT THE NECESSARY PIP
COMMAND AND SEND IT TO MCR.

20$:

30$:

MOV
ADD
MOV
MOV
MOVB
CMPB
BEO
CMPB
BEO
MOVB
INC
BR
MOV
MOV

RO,R1
tG.CCBFtl,R1
tBUF,R2
tTCLEN,R4
(Rl)t,R3
t15,R3
30$
t40,R3
20$
R1,(R2)t
R4
20$

;COPY ADDRESS OF BUFFER WITH COMMAND
iPOINT TO SPACE AFTER THE T
;F'OINT TO BUFFER THAT WILl.. CONTAIN CMD
iGET LENGTH OF INITIAL. PART OF COMMAND
iGET NEXT CHARACTER
iiS IT THE END OF THE COMMAND
;IF EO YES
iIS IT A SPACE
;IF EO YES, SKIP IT
iPUT CHARACTER IN OUTPUT BUFFER
;COUNT CHARACTER
iGF.T NEXT CHARACTER
tTCMD~R.POBF(R5);PUT ADDRESS OF CMD TO ISSUE IN DPB
R4,R.POBI.(RS)
iiNSERT LENGTH OF COMMAND

11-12

COMMAND LINE INTERPRETERS
THIS COMMAND WILL BE PASSED TO THE MAIN COMMAND DISPATCHER (MCR ••• ),
WHICH WILL START A COpy OF PIP AND GIVE IT THE COMMAND. THE RPOI
DIRECTIVE COULD BE USED TO GIVE THE COMMAND DIRECTLY TO ••• PIP AND
GIVE THE RESULTING TASK A DIFFERENT NAME. IN THIS EXAMPLE,
WE COULD CALL THE RESULTING PIP TASK "TYPTNN" WHERE THE LAST
THREE CHARACTERS (TNN) ARE REPLACED BY A DEVICE NAME CHARACTER AND
UNIT NUMBER. FOR EXAMPLE, IF THE "T" COMMAND WAS TYPED ON TT10:
THE RESULTING TASK NAME COULD BE MADE TO BE "TYPT10". THIS HAS THE
ADVANTAGE OF ALLOWING THE TASK TO BE ABORTED BY AN "ABO TYP' COMMAND,
INSTEAD OF "ABO PIP", THUS THE USER WOULD NOT HAVE TO KNOW THAT THE
"T" COMMAND HE ISSUED IS ACTUALLY BEING SERVICED BY THE PIP TASK. THIS
IS EXACTLY WHAT THE DCL ClI DOES. IT IS NOT DONE HERE
TO SIMPLIFY THE EXAMPLE. PICKING UP THE TERMINAL NAME AND UNIT
NUMBER, CONVERTING IT TO RAD50, AND SUPPLYING IT IN THE RPOI DIRECTIVE
ALONG WITH A DIRECT REQUEST OF PIP ~ LEFT AS AN EXERCISE TO THE USER.
(BE CAREFUL ON RSX-llM-PLUS SYSTEMS WITH MORE THAN 64. TERMINALS).
NOTE THAT REQUESTING PIP DIRECTLY AVOIDS A SUBSTANTIAL AMOUNT OF SYSTEM
OVERHEAD.
BR

ISSCMD

;EXECUTE COMMAND

COMMAND IS NOT "T" OR 8M', SO GIVE IT TO MCR AS IS.
;

50$:

MOV
MOVB

tCMDBUFtG.CCBF,R.POBF(R5) iPUT ADDRESS OF STRING IN DPB
G.CCCT(RO),R.POBL(R5) ;PUT LENGTH IN RPOI DPB

ISSUE RPOI$ DIRECTIVE TO EXECUTE COMMAND
i

ISSCMD: MOV
MOVB
MOVB
MOVB
MOV
DIR$
BCC
BR

(RO),R.PODV(R5) ;PUT NAME OF ISSUING DEVICE IN RPOI
G.CCUN(RO),R.POUN(R5) iCOPY UNIT NUMBER
IBUFtG.CCPU,R.POUM(R5) ;PROPAGATE UIC OF TERMINAL
IBUFtG.CCPUtl,R.POUG(R5)
IBUFtG.CCOA,R.POOA(R5)
;COPY ID PARENT IN CASE WE WERE SPAWNED
tRPOI
;PASS COMMAND TO EXECUTOR TASK
START
;IF CC, SUCCESS
110$
;ERROR

CONTROL IS TRANSFERRED HERE IF UNKNOWN COMMANDS ARE TO BE REJECTED
INSTEAD OF BEING PASSED TO MCR.
;

60$:

MOV
MOV
CALL
BR

tILL,Rl
tILLLEN,R2
ISSMSG
START

;POINT TO MESSAGE TO BE PRINTED
;GET LENGTH OF MESSAGE
;ISSUE MESSAGE
iTRY FOR NEXT COMMAND

ERROR HANDLING CODE
100$:
110$:
120$:
150$:

CLR
BR
MOV
lOT

RO
150$
t1,RO

MOV
MOV
CALL
BR
.DSABL

tCHLOST,Rl
tCLLEN,R2
ISSMSG
START
LSB

;FATAL ERROR ON GCCI$
;FATAL ERROR ON RPOI$
;FATAL
;POINT TO MESSAGE TO BE PRINTED
;GET LENGTH OF MESSAGE
;ISSUE MESSAGE

A SYSTEM MESSAGE WAS RECEIVED INSTEAD OF A COMMAND.

11-13

COMMAND LINE INTERPRETERS

MSG:

CMf'B
BEQ
CMf'B
BEQ
CMf'B
BEQ
CMPB
BEQ
BR

tCM.LKT,G.CCUN(RO) ;IS IT A NEW TERMINAL. l.INKED TO lIS1
10$
;IF EQ YES
tCM.RMT,G.CCUN(RO) ;IS IT A TERMINAL. FFING RE'MOVED
20$
;IF FQ YES
tCM.EXT,G.CCUN(RO) ;IS IT AN El.IMINATE ALL PACKET
50$
;IF FQ YES
tCM.ELM,G.CCUN(RO) ;IS IT A CLI ELIMINATION MESSAGE
50$
;IF EQ YES
;IGNORE ALL OTHER MESSAGES
START

ISSUE WELCOME MESSAGE
10$:

;

MOV
MOV
ADD
BR

tLKT,Rl
tLKTLEN,R2
tG.CCBF,RO
30$

;POINT TO MESSAGE TEXT
;GET LENGTH
;POINT TO TERMINAL THAT WAS SE'T

ISSUE GOODBYE MESSAGE

20$:
30$:

MOV
MOV
ADD
CALL
JMf'

tRMT,Rl
tRMTLEN,R2
tG.CCBF,RO
ISSMSG
START

;POINT TO MESSAGE TEXT
;GET LENGTH
;POINT TO TERMINAL NAME'
;ISSlJE MESSAGE
;GET NE'XT COMMAND

; WHEN AN ELIMINATE AL.L MESSAGE IS RECE'IVED, EXIT IMMEDIATELY.
;

50S:

EXITSS

ROUTINE TO PRINT TO TERMINAl.
INPUTS:
RO=ADDRE'SS OF NAME OF TE'RMINAl. TO PRINT TO
Rl=ADDRESS OF MESSAGE TO PRINT
R2=LENGTH OF MESSAGE
OUTPUTS:
NONE
THIS ROUTINE' PRINTS THE SPECIFIED MESSAGE ON THE SPECIFIED TERMINAl.
ALL ERRORS THAT MIGHT RESULT ARE IGNORED. IN GENERAL, ellS SHOULD
DO ASYNCHRONOUS I/O WITH COMPLE'TION ASTS, AND PROVIDF A TIME-OIIT
FACILITY TO KILL THE I/O IF IT HASN'T COMPLETED IN A CERTAIN
AMOUNT OF TIME. THIS PREVE'NTS TERMINAL I/O FROM HOLDING UP
COMMAND PROCESSING. THIS IS NOT DONE HERE FOR SIMPLICITY.
ISSMSG: MOV
MOVB
CLRB
DIRS
Bes
MOV
MOV
DIR$
10$:
RETUIi:N

<RO),AlUNtA.LUNA ;SET UP DEVICE NAME
2(RO),AI. . UNtA.LI.JNIJ ;AND UNIT NUMBER
ALUNtA.LUNU+l
;CL.F.AR HIGH BYTE
tAlUN
;ASSIGN lUN 5 TO THE SPECIFIED DEVICE
10$
;IF CS, SKIP I/O
Rl,QIOW+Q.IOPL ;SET ADDRESS OF MESSAGE
R2,QIOWtQ.IOPLt2 jINSFRT LENGTH OF MFSSAGF
lQIOW
;00 I/O AND WAIT FOR IT
\

11-14

11.3.2

COMMAND LINE INTERPRETERS

FORTRAN CLI

C THIS TASK (TMCLI) ILLUSTRATES THE USE OF THE CL.I CONTROL DIRECTIVES OF
C RSX-l1M V4.0 AND RSX-llM-PLUS V2.0.
C

C WHEN SET UP AS A TERMINAL'S ClI, IT PROVIDES THE FOLLOWING COMMANDS:
C

C
C

T
M

->
->

TYPE FILE
SET TERMINAL TO MCR

C IF THE FIRST TWO lETTERS OF THE COMMAND ARE NOT "T" FOLLOWED
C BY A SPACE, OR "M" FOLLOWED BY A CARRIAGE RETURN,
C THE COMMAND IS PASSED TO MCR FOR EXECUTION. THEREFORE,
C USERS AT TERMINALS SET TO THIS ClI WIll SEE THE ENTIRE MCR COMMAND SET
C AS BEING PRESENT, PLUS THE "T" AND "M" COMMANDS. IF THE IDPR SUBKEYWORD
C IS INCLUDED ON THE Cl.I IINIT COMMAND, USERS WIll KNOW IMMEDIATELY IF
C THEIR TERMINAL IS SET TO THIS ClI BY THE DOUBLE RIGHT ANGLE BRACKET PROMPT.
C

C IF TMClI IS INITIALIZED WITH THE IMESSAGE KEYWORD, TMCLI WILL
C GREET USERS WHEN THEIR TERMINAL IS SET TO THE ClI, AND SAY GOODBYE
C TO THEM WHEN THEY SWITCH AWAY.
C

C IN ORDER TO BRING THIS ClI UP ON THE SYSTEM, ISSUE THE FOLLOWING
C COMMAND SEQUENCE:
C

C >FOR TMCLI,TMCLI/-SP=TMCLI
C >TKB TMClI/FP,TMClI/-SP=TMClI,[l,llFOROTS/lB
C >INS TMClI/ClI=YES/TASK= ••• TMC
C >CLI IINIT=TMCl.I/MESSAGE/DPR="<lS><12>1»I"/TASK= ••• TMC
C

C IF USING FORTRAN IV-PLUS INSTEAD OF FORTRAN IV, THE FIRST TWO
C COMMANDS ABOVE WOUl.D BE:
C

C >F4P TMClI,TMCLI/-SP=TMClI.FTN
C >TKB TMCLI/FP,TMCLI/-SP=TMClI,[1,llF4POTS/lB
C

C TO SET TERMINALS TO THIS Ct.I, ISSUE THE FOt.lOWING COMMAND
C WHERE TTNN: IS REPl.ACED BY THE TERMINAL NUMBER OR TI:
C

C >SET IClI=TTNN:TMCLI
C

C NOTE THAT THE PROMPT ISSUEfi IN RESPONSE TO A CONTROl./C DF-FAUL.TS TO THE
C NAME OF THE ClI, WHICH IS "TMCL.I>".
C

C TMClI CAN BE ELIMINATED FROM THE SYSTEM BY THE FOt.LOWING COMMANflS, ASSUMING
C NO TERMINALS ARE SET TO IT:
C

C >ClI IElIM=TMClI
C >REM ••• TMC
C

C EXPERIMENT WITH THE OTHER SUBKEYWORDS OF THE ClI IINIT COMMAND, THE Cl.I
C IENABlE AND ClI IDISABLE COMMANDS, AND WITH THE IMESSAGE SWITCH ON THE IINIT
C COMMAND TO OBSERVE THE EFFECTS. AL.SO TRY CHANGING THE ITASK=
C SWITCH ON THE INS AND ClI IINIT COMMAND TO "/TASK=TMClI" AND NOTICE
C THAT ONLY ONE COPY OF THE TASK WIll EXIST FOR All TERMINALS, RATHER THAN
C ONE PER COMMAND. IF YOU DO THIS, YOU SHOULD ALSO CHANGE THE OPTION
C ON THE GTCMCI DIRECTIVE FROM GC.CEX TO GC.CST SO THE TASK WIll STAY ACTIVE
C BUT STOPPED WHEN NO COMMANDS ARE OUTSTANDING FOR IT.
C
C

11-15

COMMAND LINE INTERPRETERS

C BUFFER AREAS

e
e

COMMAND BUFFER - THIS BUFFER IS USED IN THE GTCMCI DIRECTIVE. IT CONTAINS INFORMATION ON THE COMMAND RECEIVED (8 BYTES)
AND THE COMMAND TEXT.
BYTE CMDBUF(264)
INTEGER*2 CBlEN
! NOTE THAT ON M+ THE MAXIMUM COMMAND
DATA CBLEN/2631
! LENGTH IS 255.
INTEGER*2 GCCDV, GCCCL ! ASCII DEV NAM, t CHARS IN CMD LINE
BYTE GCCCT, GCCUN, GCCBF(255) ! t OF CHARS, TERMINAL UNIT t, CMD
EQUIVALENCE (GCCDV,CMDBUF), (GCCCL,CMDBUF(5», (GCCCT,CMDBUF(4»,
1
(GCCBF,CMDBUF(9», (GCCUN,CMDBUF(3»

C
C

INFORMATION BUFFER - AL.SO RETURNED IN THE GTCMCI DIRECTIVE.

BYTE IBUF(14)
INTEGER*2 GCCPU
DATA IBLEN/14/,GCCPU/9/ ! LENGTH OF IBUF, LOGIN UIC OFFSET
INTEGER*4 GCCOA
! AD DR OF OFFSPRING CONTROL BLOCK FROM PARENT
EQUIVALENCE (GCCOA,IBUF(7»

BUFFER IN WHICH TD GENERATE COMMANDS

BYTE BUF(72)
REAL*8 TCMD(2)
EQUIVALENCE (BUF,TCMD)

BUFFER IN WHICH TO GENERATE COMMANDS
FOR CONVENIENCE IN ASSIGNMENT STATEMENTS

MCR TASK NAME IN RAD50

INTEGER*4 IMCR
DATA IMCR/6RMCR ••• /

MCR TASK NAME IN RAD50

C DIRECTIVE SYMBOLIC VALUE DEFINITIONS
C

INTEGER*2 GCCCS, GCCEX, GCCST, GCCND
DATA GCCCS, GCCEX, GCCST, GCCND 10, 1, 2, 1281 ! INCP VALUES IN GTCMCI
DATA ISCLR 101
! IS.CLR RETURN CODE
INTEGER*2 CMELM, CMEXT, CMLKT, CMRMT ! TERMINAL CODES FOR SYSTEM MSGS
DATA CMELM, CMEXT, CMLKT, CMRMT 15, 6, 7, 8/
C

C CLI CODE

C TO FORCE THE CLI TO EXIT INSTEAD OF RETURNING, THE GC.CEX OPTION IS SPECIC FlED IN THE GTCMCI DIRECTIVE BELOW. IF THE CLI IS INSTALLED SO THAT ONLY
C ONE COPY OF THE TASK WILL EXIST FOR ALL TERMINALS, CHANGE THE VARIABL.E
C GCCEX BELOW TO GCCST. THIS SPECIFIES THE GC.CST OPTION SO THAT THE TASK
C WILL STAY ACTIVE BUT STOPPED WHEN NO COMMANDS ARE OUTSTANDING FOR IT.
C

CALL GTCMCI(CMDBUF,CBLEN,IBUF,IBL.EN,O,GCCEX,IDS) ! GET CMD FOR CLI
IF (IDS .LT. 0) GO TO 100

C IF THE GTCMCI DIRECTIVE HAD THE GC.CST OPTION SPECIFIED, WE MAY HAVE
C JUST BEEN UNSTOPPED, SO WE HAVE TO GET THE COMMAND.
C

I F (I DS • EQ. I SC LR) GO TO 1

WERE WE JUST UNSTOPPED?

IF (GCCDV .EQ. 0) GO TO 200

IS THIS A SYSTEM MESSAGE?

IGCCUN = GCCUN
CALL ASNLUN(5,GCCDV,IGCCIJN,IDS)
IGCCCT=GCCCT
IF (I GCCeT • GE. 0) GO TO 5
IGCCCT = 256 + IGCCCT
IF (IGeeeT .LT. GCCCL) GOTO 150

CONVERT BYTE TO INTEGER (UNIT
ASSIGN TERMINAL TO UIN 5
CONVERT BYTE TO INTEGER

11-16

CONVERT NEGATIVE TO UNSIGNED
DID ENTIRE COMMAND FIT IN BUFFER?

COMMAND LINE INTERPRETERS

C AT THIS POINT, THE CLI HAS A COMMAND TO BE PROCESSED. THE CODE FROM
C THE LABEL 1 TO HERE SHOULD 8E FAIRLY COMMON AMONG ALL ClIS.
C FROM THIS POINT ON, THE CODE WILL BE SPECIFIC TO THE PARTICUl.AR LANGUAGE
C THIS ell IS IMPLEMENTING. COMMANDS CAN BE ADDED OR DELETED AT WILL
C BY MODIFYING CODE IN THIS SECTION. AS STATED ABOVE, THIS EXTREMELY
C SIMPI_E CLI PROVIDES TWO COMMANDS, AND GIVES EVERYTHING ELSE TO MCR.
C THIS CREATES AN OPEN-ENDED ENVIRONMENT. REJECTING UNRECOGNIZED COMMANDS
C INSTEAD OF PASSING THEM TO MCR WOULD LIMIT THE TERMINAI_ USER'S USE OF
C THE SYSTEM TO ONLY THOSE OPERATIONS ALLOWED BY THE Cl.I. THIS IS
C A SECURE WAY OF CONTROLLING SYST~M USE, IN CASES WHEN IT IS NECESSARY.
C IN THIS EXAMPLE, CHANGING THE IGO TO 50 BELOW, TO A IGO TO 60
C WOULD CREATE AN ENVIRONMENT WHERE THE ONLY OPERATION A USER COULD
C PERFORM WOULD BE TO TYPE FILES ON THE TERMINAL, OR SWITCH BACK TO MCR.
C ALL OF THE REST OF THE SYSTEM IS INACCESSI8LE. IF NO MEANS OF SWITCHING
C BACK TO MCR IS PROVIDED, IT IS IMPOSSIBLE FOR THE USER TO DO
C ANYTHING THE CLI DOES NOT EXPLICITLY I..ET HIM DO.
1

C IS IT A ITI COMMAND?
C

IF «GCCBF(I) .EG. 'T') .AND. (GCCBF(2) .EG. '

'»

GO TO l.0

C CHANGE THE NEXT IF STATEMENT TO IGO TO 60
C COMMANDS TO MCR.

TO ELIMINATE PASSING UNKNOWN

C IS IT ALSO NOT AN IMI COMMAND?
C

IF «GCCBF(1) .NE. 'M') .OR. (GCCBF(2) .NE. 13» GO TO 50

M(CR>

C THE USER HAS ENTERED AN IMI COMMAND, SO SET THE TERMINAL. TO MCR.
C

TCMD(l) = 'SET IMCR'
TCMD(2) = '=TI:
IGRP :: IBUF(GCCPU+l)
IMEM = IBUF(GCCPU)

SET IMCR=TI:
(CONVERT BYTE TO INTEGER) GROUP
MEMB~R PART OF UIC

C ISSUE RPOI$ DIRECTIVE TO EXECUTE COMMAND
C

CALL RPOI(IMCR,IGRP,IMEM"TCMD,12"GCCDV,IGCCUN"GCCOA,IDS)
IF (IDS .LE. 0) GO TO 110 ! ERROR?
GO TO 1
! BACK TO START
C

C THE USER HAS ENTERED A ITI COMMAND SO CONSTRUCT THE NECESSARY PIP
C COMMAND AND SEND IT TO MCR
C

TCMD(I) = 'PIP TI:='

PUT BEGINNING OF PIP CMD IN BUFFER
POINTER INTO TARGET BUFFER
DO 20, 11 = 10, CBlEN
BEGIN AT SPACE AFTER THE T IN CMDBUF
IF (C MDBUF ( I () • EG• 13) GO TO 30 ! END OF COMMAND? «CR»
IF (CMDBUF(Il) .EG. , ') GO TO 20 ! SKIP ANY SPACES
12 :: 1'2 + 1
COUNT CHARACTER
BUF(I2) = CMDBUF(Il)
COPY INTO OUTPUT BUFFER
CONTINUE
IGRP = IBUF(GCCPU+l)
(CONVERT BYTE TO INTEGER) GROUP
IMEM = IBUF(GCCPU)
MEMBER PART OF UIC
12

20
30

C ISSUE RPOI$ DIRECTIVE TO EXECUTE COMMAND
C

CALL RPOI(IMCR,IGRP,IMEM"TCMD,I2"GCCDV,IGCCUN"GCCOA,IDS)
IF (IDS .LE. 0) GO TO 110 ! ERROR?
GO TO 1
! BACK TO START
C

11-17

COMMAND LINE INTERPRETERS

C IN THE ABOVE SECTION OF CODE, THE RPOI DIRECTIVE WAS USED TO PASS
C THE PIP COMMAND TO THE MAIN COMMAND DISPATCHER (MCR ••• ),
C WHICH WILL START A COpy OF PIP AND GIVE IT THE COMMAND. THE RPOI
C DIRECTIVE COULD BE USED TO GIVE THE COMMAND DIRECTLY TO ••• PIP AND
C GIVE THE RESULTING TASK A DIFFERENT NAME. IN THIS EXAMPLE,
C WE COULD CALL THE RESULTING PIP TASK "TYPTNN" WHERE THE LAST
C THREE CHARACTERS (TNN) ARE REPLACED BY A DEVICE NAME CHARACTER AND
C UNIT NUMBER. FOR EXAMPLE, IF THE "T" COMMAND WAS TYPED ON TT10:
C THE RESULTING TASK NAME COULD BE MADE TO BE "TYPT10". THIS HAS THE
C ADVANTAGE OF ALLOWING THE TASK TO BE ABORTED BY AN "ABO TYP" COMMAND,
C INSTEAD OF "ABO PIP"; THUS THE USER WOULD NOT HAVE TO KNOW THAT THE
C "T" COMMAND HE ISSUED IS ACTUALLY BEING SERVICED BY THE PIP TASK. THIS
C IS EXACTLY WHAT THE DCL CLI DOES. IT IS NOT DONE HERE IN ORDER
C TO SIMPLIFY THE EXAMPLE. PICKING UP THE TERMINAL NAME AND UNIT
C NUMBER, CONVERTING IT TO RAD50, AND SUPPLYING IT IN THE RPOI DIRECTIVE
C ALONG WITH A DIRECT REGUEST OF PIP IS LEFT AS AN EXERCISE TO THE USER.
C <BE CAREFUL ON RSX-11M-PLUS SYSTEMS WITH MORE THAN 64. TERMINALS).
C NOTE THAT REGUESTING PIP DIRECTLY AVOIDS A SUBSTANTIAL AMOUNT OF SYSTEM
C OVERHEAD.
C
C
C
C COMMAND IS NOT "T" OR "M", SO GIVE IT TO MCR AS IS.
C
IGRP
IBUF(GCCPU+l)
(CONVERT BYTE TO INTEGER) GROUP
50
IMEM = IBUF(GCCPU)
! MEMBER PART OF UIe
IGCCCT = GCCCT
! • OF CHARS IN COMMAND
C

C ISSUE RPOI$ DIRECTIVE TO EXECUTE COMMAND
C

CALL RPOI(IMCR,IGRP,IMEM"GCCBF,IGCCCT"GCCDV,IGCCUN"GCCOA,IDS)
IF (IDS .LE. 0) GO TO 110 ! ERROR?
GO TO 1
! BACK TO START
C
C CONTROL IS TRANSFERRED HERE IF UNKNOWN COMMANDS ARE TO BE REJECTED
C INSTEAD OF BEING PASSED TO MCR.
C

60
62

WRITE (5,62)
FORMAT('OILLEGAL COMMAND')
GO TO 1
! BACK TO START

C
C ERROR HANDLING CODE
C
100
WRITE (5,102) IDS
! ERROR IN GTCMCI
102
FORMAT('OFATAl ERROR IN GTCMCI DIRECTIVE. DSW=',I6)
GO TO 250
! EXIT
C
110
WRITE (5,112) IDS
! ERROR IN RPOI
112
FORMAT('OFATAL ERROR IN RPOI DIRECTIVE. DSW=',I6)
GO TO 250
! EXIT
C
150
WRITE (5,152)
! ENTIRE COMMAND DID NOT FIT IN BUFFER
152
FORMAT('OSORRY, PART OF YOUR COMMAND WAS LOST')
GO TO 1
! BACK TO START
C

C A SYSTEM MESSAGE WAS
C
CONTINUE
200
IF (GCCUN .EG.
IF (GCCUN .EG.
IF (GCCUN .EG.
IF (GCCUN .EG.
GO TO 1

RECEIVED INSTEAD OF A COMMAND
CMLKT)
CMRMT)
CMEXT)
CMELM)

IS IT A NEW TERMINAL LINKED TO US?
GO TO 210
IS IT A TERMINAL BEING REMOVED?
GO TO 220
GO TO 250
IS IT AN ELIMINATE ALL PACKET?
GO TO 250
IS IT A ell ELIMINATION MESSAGE?
! IGNORE All OTHER MESSAGES

11-18

COMMAND LINE INTERPRETERS

C ISSUE WELCOME MESSAGE
C

210
212

IGCCUN = CMDBUF(ll)
! CONVERT BYTE TERMINAL. UNIT t TO INTEGER
CALL ASNUJN (5, GCCBF rI GCCUN, IDS) ! ASS I GN llJN 5 TO SPEC I F I ED DEV I CE
WRITE (5,212)
FORMAT('OWELCOME TO THE EXAMPl.E Cl.I')
GO TO 1
! BACK TO START

C ISSUE GOODBYE MESSAGE
C

220
222

IGCCUN = CMDBUF(11)
! CONVERT BYTE TERMINAL UNIT t TO INTEGER
CALL ASNUJN(5,GCCBF,IGCCUN,IDS) ! ASSIGN llJN 5 TO SPECIFIED DEVICE
WRITE (5,222)
FORMAT('OGOOD BYE FROM THE EXAMPLE ClI')
GO TO 1
! BACK TO START

C WHEN AN ELIMINATE ALL MESSAGE IS RECEIVED, EXIT IMMEDIATELY
C

250

CONTINUE
CALL EXIT
END

11-19

CHAPTER 12
THE DeL TASK

The DIGITAL Command Language (DCL) is a general purpose command
language syntax implemented on several DIGITAL operating systems.

12.1

INTRODUCTION

DCL on RSX-llM/M-PLUS systems is a task that receives DCL commands by
means of the generalized CLI command dispatcher, translates the DCL
commands to equivalent MCR commands, and sends the MCR commands to the
MCR command line interpreter for interpretation and execution. The
DCL task, in conjunction with the CLI dispatcher, provides DCL support
on RSX-llM/M-PLUS operating systems.
chapter explains the ways in which DCL can be installed on your
system and documents the means by which the DCL task parses and
translcltes commands. In addition, this chapter documents the Macro
MetaLanguage, a set of MACRO-II macros used to define DCL. An
experiE~nced programmer can add commands to
DCL or remove them, or
alter DCL by changing parts of it, such as altering defaults or
eliminating qualifiers.
~his

For information on DCL syntax and functions, see the RSX-llM Command
Language Manual or the RSX-llM-PLUS Command Language Manual. For
information on MCR syntax and functions, see the RSX-llM!M-PLUS MCR
Operations Manual. For information on the CLI command dispatcher, and
on alternate CLls, see Chapter 11, Command Line Interpreters, in this
manual.. For information on the Executive directives used to implement
alternate CLls, see the RSX-llM/M-PLUS and Micro/RSX
Executive
Reference Manual.
The examples of source code in this chapter illustrate features of DeL
and tcte DCL task, but they are often changed from the actual source
code to -make the example clearer. See the DCL source code in [23,10]
for exact information. The command tables for the ASSIGN command are
includE~d in this chapter (Section 12.11.6) as a general example of DeL
coding.

12.2

INSTALLING AND BUILDING DeL

The DeI~ task is best installed as an alternate CLI, but it can also be
run as a task or installed as an external MCR task. External MCR
tasks have task names in the form ... abc.
Furthermore, you can
rebuild DCL either to eliminate direct access to MCR from DCL, or to
allow all commands not in DeL syntax to fall through DCL for handling
by MCR.
Your choice on these options depends on the requirements of
your system users and your installation.

12-1

THE DCL TASK
12.2.1

Conventional Installation of DCL as a CLI

Installing DCL as an alternate CLI is the cleanest use of DCL.
This
allows you to classify users by CLI in the system account file.
Users
can log in using either HELLO or LOGIN. The HELLO task checks the
account file for the CLI and sets the user's terminal to the
designated CLI.
On RSX-llM systems, DCL and alternate CLI support require a mapped
system with multiuser protection.
If you choose DCL at system
generation, you are also choosing alternate CLI support, as DCL is an
alternate CLI.
In addition, choosing DCL support also gives you
support for the following directives:
•

Stop-bit

•

Install-request-remove

•

Parent-offspring tasking with chaining

•

AST

•

Specify request exit AST

•

Get task parameters

•

Get command for command interpreter

•

Request and pass offspring information

•

Specify command arrival AST

•

Get command interpreter information

The last four directives listed are those specifically added for
alternate CLI support. See Chapter 11, "Command Line Interpreters,"
and the RSX-llM/M-PLUS and Micro/RSX Executive Reference Manual.
During syst~m.gen.er~rlon 'on RSX711M....P~lJSt you ar~ aSked,. if

you

want

a1t.er'xUlte .,FLlaUPP<j)r1:,or DeL filupport,•...... Theoth~~ (non~LI). directive"
Ii.ted albo'Y'~ ·ar'Q s'ilpported on all JJSX-11M.,..PLUS systems with t.he
fu11- function EXecut :Lve.

Installing DCL as an alternate CLI on either RSX-llM or
requires only two commands:

RSX-llM-PLUS,

MeR:> INS T A I .. L $ n c I... • T SKI C I... r ;.:: YES

MCR>CL.I IINIT=DCL
When you choose DCL support during system generation, the INSTALL
command is issued in the SYSVMR portion of system generation. You
must also include the CLI /INIT command in the system STARTUP.CMD
file.

12.2.2

Alternative Ways to Use DeL

If, for some reason, you choose not to have alternate CLI support, you
can still use many of the features of DCL by taking advantage of
alternative ways of installing DCL.
You can run DCL as a task,
install DCL as an external MCR task under the name ... DCL, or install
DCL as the system catchall task under the name ... CA.

12-2

THE DCL TASK
If DCL is not a CLI, you cannot log in with the LOGIN command, you
cannot change your defaults with the SET DEFAULT command, breakthrough
writes do not break through, and spawned tasks are not renamed (that
is, a DIRECTORY command spawns a task named PIPTnn, not DIRTnn).

12.2.2.1 Run DCL as a Task - If you wish, you can simply run DCL as a
task.
If you place the task image file in the system directory on
RSX-IIM or the library directory on RSX-IIM-PLUS, users can run DCL
with the command:
>F:UN $DCL

DCL runs from your terminal as a task. The terminal remains set to
MCR.
All DCL commands work in the normal way, but a carriage return
on a line by itself causes the task to exit.

12.2.2.2 Install as ••• DCL - If you install the DCL task as an
external MCR task under the name ... DCL, users can issue DCL commands
from an MCR terminal simply by preceding the command with DCL, as in
the following example:

MCR>DCL SHOW USERS

12.2.2.3 Install as ••• CA. - If you install the DCL task under the
name ... CA., all commands not recognized by MCR are handled by DCL
running as the catchall task. This means that DCL commands such as
MOUNT and SET that are identical with MCR commands in the first three
characters must be in MCR syntax. These commands in DCL syntax are
recognized by MCR, but only as errors. To avoid infinite loops, the
DCL installed as MCR's catchall must not be built with MCR as its
catchall.

12.2.3

The MCR Command

The MCR command is included in the default DCL task.
This command
permits users to issue a one-line MCR command without leaving DCL.
The MCR command is not affected by SET DEBUG.
Some installations may prefer not to permit DCL users any access to
MCR.
If you wish to restrict access to MCR, you must modify
DCLBLD.CMD following the instructions contained therein' and then
rebuild DCL.

12.2.4

DCL SET Commands from MCR

All DCL SET commands may be used from MCR. MCR has been modified to
pass all SET commands that do not have a slash in front of the keyword
to DCL.

12-3

THE DCL TASK
12.2.5

Allowing Unrecognized Commands to Fall Through to MCR

The default DCL task returns an error for any command not recognized
as a DCL command.
You may prefer that DCL allow any unrecognized
commands to fall through to MCR for another chance at execution. This
permits users direct access to MCR tasks and utilities without using
the MCR command or the RUN command.
If you wish to allow commands to fall through DCL to MCR, modify
DCLBLD.CMD following the instructions contained therein and then
rebuild DCL.

12.2.6

Flying Installs

Tasks need not be installed for DCL to access them.
Comments in
DCLBLD.CMD explain how to enable flying installation of tasks. Again,
modify DCLBLD.CMD and rebuild DCL.

12.2.7

Task Building DCL

All of the changes to DCL described in this chapter require that the
DCL task be rebuilt. The overlay structure of the DCL task forces a
complex task build that actually requires two passes by the Task
Builder before it is complete. The first pass creates a symbol table
(.STB file) that is used by TKB on the second pass to build the DCL
task. The following two sections summarize the task-build process.
NOTE
The file [1,24]DCLBLD.CMD is called by SYSGEN when you
request DCL support. You should read this file before
attempting to task build DCL.

12.2.7.1 Summary of First Task Build - The following
first task build process:
table

summarizes
(or

PT)

the

•

Each DCL command is defined in a parser
defines the DCL syntax of the command.

•

The PT is paired with a translator table, or TT, which defines
the MCR equivalents for the DCL command.

•

The addresses of the PT and TT are included in
command table (MCT) that lists all DCL commands.

•

When DCL parses a command,
it seeks the address of that
command in the MCT and then goes to that address for
translation of the command to MCR at the PT/TT.

•

The parser tables and translator tables are overlaid on the
master command table; this means that at the time of the first
task build, the master command table entries are undefined
symbols.

that

master

The first task build uses a command in the following form:
:> ll\ H • 7 nc I. ; :~) T B :::: 1"1 C L.

This results in one or more undefined symbols for each command,
the PT/TT addresses for each command are in the .STB file.
12-4

but

THE DCL TASK
12.2.7.2 Summary of Second Task Build - The following summarizes
second task build process:
of

the

•

The master command table symbols are defined by means
.STB

the

•

The addresses in the PT/TT are doubly defined, once in the
.STB and once in their overlays. The two definitions are
identical. In fact, this process is accomplished through two
.ODL files.
See DCLBLD.CMD for more information.

The second task build uses a command in the following form:

>TKB DCLvDCL=DCL,DCL.STB

12.2.8

How the DCL Task Works

This section describes how DCL commands are interpreted
an overview of how DCL command tables are constructed.

and

provides

12.2.8.1 Interpreting DCL Commands - There are
three
processes
involved in interpreting DCL commands
the receive process, the
parser/translator process, and the send process. The receive process
gets
the
command
line
from
the
system.
The table-driven
parser/translator process translates the command line to an equivalent
MCR command line. The send process sends the equivalent MCR command
line to. the system for further interpretation and execution.
These
processes are further described as follows:
•

The receive process involves two tasks:
the CLI dispatcher
task (MCR ... ) and the DCL task ( ... DCL). The CLI dispatcher
task gets the command line from the terminal driver, queues it
to a CLI queue, and activates the DCL task (if not already
active). The DCL task activated is named DCLTnn, where nn is
the number of the issuing terminal.
The DCL task (being
nonprivileged) issues the Get Command for Command Interpreter
(GCCI$) directive to remove (or receive) the command line from
the CLI queue.

•

The parser/translator process involves two subprocesses:
the
parser process and the translator process. The parser process
checks syntax to ensure that the received command line is a
valid DCL command line. The parser constructs an intermediate
form (/FORM) to pass data about the command line to the
translator.
The
translator process uses this data to
construct an equivalent MCR command line from the valid DCL
command line.

•

The send process dispatches the equivalent MCR command line to
MCR or MCR utility tasks by means of the Request and Pass
Offspring Information (RPOI$) directive. The RPOI$ directive
is functionally similar to the SPWN$ directive. There are two
significant differences from SPWN$: RPOI$ allows the spawned
task to be named (for example, spawn PIP and name it COPTnn),
and RPOI$ does not create OCBs (Offspring Control Blocks).

12-5

THE DCL TASK
The DCL task needs the task-naming ability to track the association
between the DCL command name and the MCR or utility task that executes
the command. And, instead of creating an OCB, RPOI$ takes the OCB
attached to the DCL task and attaches this OCB to the spawned task.
This enables the spawned task to communicate exit status directly to
t:he parent task,
DCL.
In this way, the DeL task can spawn a task
without having to wait for the task to exit.

12.2.8.2 Constructing DCL Command Tables - The remainder of this
chapter describes how to construct the DCL command tables, which drive
the parser/translator process.
Basically, the tables contain the
following for each DCL command:
•

The syntax of the DeL command

•

The syntax of the equivalent MCR command (that is, the
of the MCR command that the DCL command translates to)

•

The relationship (or mapping) between the DeL syntax
MCR syntax.

syntax
and

the

MACRO-II macros and rules define the tables.
The macros and rules
form a language designed to allow the user to express the tables.
The macros and rules are called the Macro MetaLanguage (MML). Here is
a list of some of the features of the language and how they are
employed in the DeL task:
•

MML is modeled after a Backus-Naur Form (BNF) metalanguage. A
BNF language specifies which sequences of symbols constitute a
syntactically valid statement in a given language.
In this
case, MML is used to describe the proper syntax of a DCL
command and the equivalent syntax of an MCR command.

allows the specification of a prompt string for each
• MML
syntax
element.
DCL prompts for more input, with the
specified string, if a test for end-of-line is successful.
•

MML interfaces with the RSX-IIM/M-PLUS HELP utility. The user
requests help by typing a "?" character in reply to a prompt.

•

MML allows the specification of an error message string for
each syntax element.
If DCL detects an error while processing
a syntax element and that syntax element has a specified error
message, DCL issues the error message and aborts the parse.

allows the specification of contradictory bit masks for
• MML
each syntax element.
DCL uses the bit masks to detect
contradictory syntax.
•

MML allows the use of globally defined syntax elements, such
as file specifications, device specs, numerals,
letters,
alphanumerics and so forth.

•

MML allows MACRO-II Assembly Language subroutines to be mixed
with MML statements in the event that a command cannot be
completely defined using MML.

12-6

THE DCL TASK
•

MML allows one DCL command to translate to more than one MCR
command.
For instance, the DCL SET DEFAULT command can
generate both an MCR ASN command and an MCR SET /urc command.

•

MML supports floating qualifiers. A floating qualifier can be
specified anywhere in the command line.

The following section describes the DCL command tables.
The
command tables define all DCL commands and are written in MML.
Sections 12.6 through 12.10 for more information on MML.

12.3

DCL
See

DCL COMMAND TABLES

The parser/translator process of DCL is table-driven.
A master
command table (MCT) contains an entry for each DCL command. Each
entry in the MCT contains the following:
•

The name (verb) of the command

•

The address of a parser table (PT) for the command

•

The address of a translator table (TT) for the command

•

The name of
(optional)

the

overlay

containing

the

and

the

Thus, there is a PT and a TT for each DCL command.
Each PT/TT
contains the information that the parser/translator process needs to
translate a DCL command line to an equivalent MCR command line.
For
ease in adding and modifying commands, MCT and each PT/TT are kept in
separate files.
The file for the MCT is called COMMAND.MAC. The files for the PT/TTs
are named after the DCL command, with the type .MAC. For example, the
PT/TT for the DCL COpy command is in a file named COPY.MAC.
The DCL task uses MCT to recognize an arbitrary command and to locate
the PT/TT for that command.
MCT consists of calls to the COMMAND
macro. There is a COMMAND macro for each DCL command. Arguments to a
COMMAND macro specify the name (or verb) of the command, the address
of the PT for the command, the address of the TT for the command, and
the overlay name for the command.
The PT/TTs drive the parser/translator process. The parser/translator
process ensures that the syntax of the DCL command line is correct and
creates the /FORM, which is the parser subprocess, and subsequently
constructs equivalent MCR command lines, which is the translator
subprocess. The PT drives the parser subprocess and the TT drives the
trandlator subprocess.
The PT is an MML definition of the syntax or
structure of the DCL command and the TT is an MML definition of the
syntax or structure of the corresponding MCR command.
Table 12-1 shows the structure of the DCL command table files.
The PT defines the syntax for a DCL command line. The TT defines the
syntax for the corresponding MCR command line. For the translator to
know which particular MCR command line to construct from a particular
DCL command line, the PT and the TT must express a relation between
the DCL syntax and the MCR syntax.

12-7

THE DCL TASK
Table 12-1
DCL Command Tables
COMMAND.MAC
Master Command Table

ABORT.MAC

UNLOCK.MAC

ABOPT: :

UNLPT: :

COMMAND ABORT ABOPT ABOTT
COMMAND ASSIGN ASSPT ASSTT

Parser
Table

ABOTT: :

UNLTT: :

Translator
Table

COMMAND UNLOCK UNLPT UNLTT
The PT/TT expresses this relation by mapping elements from DCL syntax
to elements in MCR syntax. For example, the DCL qualifier II/GLOBAL II
maps to the MCR switch II/GBL II (that is, the switch II/GBL II is output
when the qualifier II/GLOBAL II is input).
The parser passes the mapping information to the translator by means
of a dynamic data structure called the Intermediate Form (IFORM). The
parser constructs the IFORM and the translator examines the IFORM.
The IFORM contains the essential information that the translator needs
to construct the equivalent MCR command line. Both the PT and the TT
define the mapping from DCL to MCR syntax.
The Macro MetaLanguage (MML) defines the PT and the TT. MML is a set
of MACRO-II macros and rules implementing a language in which a user
can define DCL commands. With MML, a user can express the information
in the PT and the TT in a BNF-type metalanguage.
The following section describes the structure of the file that
contains the MCT and of the files that contain the PT/TTs.
It also
describes how these files assemble, overlay, and task build into the
DCL task. Section 12.4.1.1 describes how to create the PTs and TTs.

12.4

MODIFYING DCL COMMAND TABLES

A DCL command consists of an entry in the master command table (MCT) ,
a parser table (PT), and a translator table (TT). The PT defines the
syntax of the DCL command.
The TT defines the syntax of the
corresponding MCR command. The entry in the MCT connects the PT and
the TT to the DCL task. Thus, to add a new command to the DCL task,
the user must construct a PT and a TT and make an entry in the MCT.

12.4.1

Adding Commands

Adding a command to the DCL task involves the following:
1.

Creating the PT and the TT

Creating the file that contains the PT and the TT

12-8

THE DCL TASK
3.

Making an entry in the MCT

Making an entry in the overlay description file for
task

the

DCL

Incorporating the new PT/TT file and the
into the DCL task

MCT

file

modified

12.4.1.1 The PT/TT File - The file that contains the PT and the TT is
named after the verb of the command. The file type is .MAC (for
example, the PT and the TT for the COpy command are in a file named
COPY.MAC).
The PT/TT file must specify the MACRO-II assembly
directives .TITLE, .PSECT, and .END. The title of the file (specified
as an argument to the .TITLE directive) must also be the same as the
verb of the command. Normally, the program-section name is .CDEF,
which
stands
for
command
definition.
If, however, MACRO-II
subrout.ines are interspersed with MML notation by means of the $JSR
predefined syntax element, the subroutines must be in the blank
program section.
(See Section 12.11 for details on $JSR.)
In addition to these directives, the PT/TT file must contain a
(MACRO-·ll) global label on the first MML macro of the PT and a global
label on the first MML macro of the TT. By convention, the label on
the PT' is the same as the verb of the DCL command, and the label on
the TT is the same as the verb on the corresponding MCR command.
The
following shows the structure of the file that contains the PT and the
TT for the DCL ASSIGN command:
ASSIGN.MAC
.TITLE
.PSECT

ASSIGN
.CDEF

ASSIGN: :
Parser Table
ASN: :
Translator Table
.END
The twC) global labels in the PT /TT file connect the PT and the TT
the DCIJ task. This is accomplished by making an entry in the MCT.

12.4.1.2 The MCT Entry - The file COMMAND.MAC contains the master
command table (MCT). The MCT consists of a list of (MACRO-II) COMMAND
macrocalls. Each COMMAND macrocall identifies a DCL command.
The
list of COMMAND macrocalls is ordered alphabetically by the name or
verb of the command. The COMMAND macro takes five arguments.
The
first four are mandatory and the fifth is optional. The format for
the COMMAND macro is as follows:
COMMAND

name, min, ptaddr, ttaddr, [ovrnamJ

where:
name

Name or verb of the command

min

Minimum number of characters necessary to make the name
unique
12-9

THE DeL TASK
ptaddr

Label of the PT for the command

ttaddr

Label of the TT for the command

[ovrnamJ

Three-character name of the overlay for the PT and TT

The fifth argument to the COMMAND macro (ovrnam) is optional. The PT
and TT must, however, be in an overlay whether or not you specify this
argument. The default overlay name is the command verb, assuming the
PT and TT are in the same module.
If they are in separate modules,
the PT overlay is named for the verb by default, and the TT is named
for the verb preceded by a "T" (for example, TSET.MAC).
The MCT is in two parts. Part 1 of the MCT includes all DCL command
verbs in alphabetical order, as described in this section.
Part 1 is
searched with a binary search algorithm. Part 2 of the MCT makes
possible the brief forms of commonly used DCL commands.
If the search
of Part 1 for a command verb fails -- if a line is too short,
for
instance -- a
search of Part 2 is initiated.
Part 2 is not
necessarily in alphabetical order as it is searched from the top down.

12.4.1.3 The Overlay Entry - Each PT/TT must reside in
Use one of the following structures to overlay a PT/TT:
•

One overlay for two or more PT/TTs

•

One overlay for one PT/TT

•

Two overlays for one PT/TT

•

More than two overlays for one PT/TT

overlay.

Specify an overlay by making an entry in the overlay description files
DCLBLD.ODL and DCDBLD.ODL -- and connect the new overlay entry to
the root segment overlay entry.
One Overlay for Two or More PT/TTs
The format for this overlay entry is as follows:
label:

. NAME
.FCTR

ovrnam
ovrnam-DCLO/LB:cmdnaml:cmdnam2 ... :cmdnamn-L

where:
label

Connects the entry to the root segment

ovrnam

Three-character name of the overlay

DCLO

Object library containing the modules in the overlays

cmdnaml

Title of the file containing the first PT/TT

cmdnam2

Title of the file containing the second PT/TT

cmdnamn

Title of the file containing the last PT/TT

For each entry in the MCT whose command tables
(PT/TTs) are in an
overlay that has two or more PT/TTs, you must include the overlay
name, ovrnam.
12-10

THE DeL TASK
One Overlay for One PT/TT
The format for this overlay entry is as follows:
label:

.FCTR DCLO/LB:cmdnam-L

where:
labE~l

Connects the entry to the root segment

cmdnam

Title of the file ,that contains the PT/TT

This s1:ructure, one overlay and one PT /TT, does not specify the
overlay name.
In this case, the DCL task uses the name or verb of the
command as the overlay name because the Task Builder default for the
overlay name is the title of the file.
For this reason, the title of
the file containing the PT/TT must be the same as the name or verb of
the command.
Two Overlays for One PT/TT
The format for this overlay entry is as follows:
label:

.FCTR (DCLO/LB:cmdnam-L,DCLO/LB:tcmdnam-L)

where:
labE~l

Connects the entry to the root segment

cmdnam

Title of the file that contains the PT

tcmdnam

Title of the file that contains the TT

Note tllat this overlay structure, two overlays and one PT/TT, requires
that the PT and TT reside in separate files. The separate files have
the same format as a single file that contains the PT/TT except that
there is only one global label in each file. By convention, the file
containing the PT is named for the verb of the command and the file
containing the TT is named for the verb prefixed by "T". The titles
of the files follow the same convention.
For example the file
containing the PT for the DCL SET command is named SET.MAC with title
SET, and the file containing the TT for the DCL SET command is named
TSET.MAC with title TSET.
More than Two Overlays for One PT/TT
The format for this overlay entry is as follows:
label:

.FCTR
(DCLO/LB:cmdnam-L,DCLO/LB:tcmdnam-L,DCLO/LB:ovrnaml-L)

where:
labE~l

Connects the entry to the root segment

cmdnam

Title of the file that contains the PT

tcmdnam

Title of the file that contains the TT

ovrnaml Title of a file containing more parts of the PT/TT
Basically, the overlay structure of more than two overlays and a
single PT/TT allows a PT or a TT to invoke additional overlays
containing additional portions of the PT or TT. Since the PT and TT

12-11

THE DeL TASK

are read-only data, the additional overlay segments are loaded on top
of the overlay that is invoking them.
On return from the invoked
overlay, the DCL task reloads the previous overlay.
Control returns
to the point in the previous overlay whence the additional overlay was
invoked.
Use the $CALLOV predefined syntax element to invoke additional
overlays from a PT or a TT.
(See Section 12.11, for details on the
$CALLOV predefined syntax element.) To specify additional overlays,
repeat the previous format.
That is, for each additional overlay,
specify an additional argument to the .FCTR directive using the
format:
DCLO/LB:ovrnam-L.
Next, connect the new overlay entry to the root segment of the DCL
task by adding the label of the entry to the list of labels for other
entries. The list of labels for other entries is found in the overlay
description file after the label OLAY.
By convention, enter the
labels in alphabetical order. The following shows the list of overlay
entry labels:
OLAY:

.FCTR (ll,12,13,14,15, ... ,ln)

where:
ll, ... ,ln Labels of overlay entries
Note that since there are two overlay description files for building
the DCL task (DCLBLD.ODL and DCDBLD.ODL), you must make new overlay
entries in both files. The format is the same for both overlay
description files.
For details on how to build the DeL task, see
Section 12.2.
For details
on
overlay
structures,
see
the
RSX-llM/M-PLUS Task Builder Manual.
the DCL task is to
into the DCL task, as

The last step required to add a command to
incorporate all created or modified files
described in the following section.

12.4.1.4 Incorporating the PT/TT and MCT - The last step in adding
new commands to DCL -- assembly and task building -- is accomplished
through the indirect command file [23,24]DCL.CMD, which is on the same
disk as the DCL sources. This file prompts for the name of a file
containing the names of all modules you have changed or created.
The
input file consists of one module name per line, with no file type or
version number. DCL.CMD then assembles the modules, updates the
object libraries, and task builds the new version of DCL.
Invoke DCL.CMD as follows:
:. (i' ~~! (:: L

:+: 0 U

':3 (. 1..\

1;.,0 .:::

n t,

'::' ; :':. ;::: r: d p d

[y./ H :'1 !

I.' (i In In F' r it·::.;

Answer Y to this question.
remainder of the process.

The

comments

DCL.CMD

direct

the

If all source files assemble correctly, DCL.CMD then builds the DCL
task.
See Section 12.2 for information on how to determine if the DCL
task was built correctly and for information on how to install DCL as
a CLI in a multi-CLI environment.
The DCL.CMD command file is designed to run under MCR with
PIP, and TKB installed. DCL.CMD is also designed to run

12-12

MAC, LBR,
using one

THE DeL TASK

UFD: t.he one that you invoke the command file from.
the following files must be in this UFD:

This means

that

•

Specified source files

•

Library files for DCL:
root, respectively)

DCLO.OLB and DCLR.OLB (the overlay and

•

Prefix files for DCL:

DCLMAC.MAC and COMMAC.MAC

•

Task-build command file:

•

Overlay description files:

DCLBLD.CMD
DCLBLD.ODL and DCDBLD.ODL

Additionally, RSXMC.MAC must be in LB:[ll,lO].
Although DCL is
nonprivileged, DCL needs this file to determine, at assembly time,
whether your system is RSX-llM or RSX-llM-PLUS.

12.4.2

Deleting Commands

To delete a command from DCL, you must break the link between the MCT
and the PT/TT. To do this, delete the appropriate COMMAND macro entry
in the MCT, which is in the file COMMAND.MAC. Then,
incorporate the
modified COMMAND.MAC file into the DCL task by following the procedure
outlin€!d in the preceding section. You can also delete the entry in
the overlay description files and the object modules for the PT/TT in
the DCLO.OLB library, but this is optional.

12.4.3

Modifying Commands

Modifying an existing DCL command involves modifying the PT/TT files
to reflect the desired change and incorporating the modified files
into the DCL task, as described in Section 12.4.1.
The us€!r defines DCL PTs and TTs using MML.
The following section
describes a metalanguage in general terms, using a simple English
sentence as the example. Following the introduction of these general
concept.s in Section 12.5 is a more detailed explanation of the Macro
MetaLanguage (MML) itself in Section 12.6. For instance, the general
introduction in Section 12.5 includes a description of ANDing and
ORing in metalanguages, while Section 12.6 describes the AND and OR
macros of the Macro MetaLanguage.

12.5

DESCRIPTION OF A METALANGUAGE

~,GENERAL

Consid€!r a sentence in the English language. A syntax
the structure or syntax of a sentence as shown below:

tree

<sentence>
I

THE

OLD

<verb>

I
MAN

WALKED

THE

12-13

<nounl>

DOG

defines

THE DeL TASK

Note that the sentence liThe old man walked the dog" is one of many
sentences that could fit the above structure (syntax). The following
description of the syntax tree is a metalanguage definition of the
sentence:
sentence

: : = <subject>

subject

: : = <article> <adjective> <noun>

predicate

: : = <verb>

direct object

: : = <article> <nounl>

article

: : = THE

adjective

: : = OLD

noun

: : = MAN

verb

: : = WALKED

nounl

: : = DOG

Note the equivalence of the metalanguage definition and the syntax
tree.
They describe the same thing. Note also that the metalanguage
definition uses the symbols "<", ">", and "::=".
The symbols "<" and ">" denote category references.
These symbols
enclose the name of the category.
Categories define classes of
objects. For example, the category <subject> defines English words
that fit the structure of an <article> followed by an <adjective>
followed by a <noun>.
The symbol "::=" means "is defined as" and denotes a production rule.
In a production rule, you specify the category name to the left of the
"::=" symbol and the definition for the category to the right of the
"::=" symbol.
A category reference means there is a production rule
for the category that requires that the right part of the production
rule be substituted for the name of the category. For example, here
is the production rule for <subject> that references the category
<adjective>:
subject ::= <article> <adjective> <noun>
The production rule for the category <adjective> is as follows:
adjective ::= OLD
Thus, you can rewrite the production rule for <subject> as follows:
subject ::= <article> OLD <noun>
Note that you can also substitute further for references to the
categories <article> and <noun> to produce the production rule as
follows:
subject ::= THE OLD MAN
You cannot substitute for the words: THE, OLD, and MAN. These words
are literal strings.
For simplicity,
literal strings are called
literals, and category references are called nonliterals. A category
definition (the right part of a production rule) consists of literals
or nonliterals (or both) concatenated by implied-ANDs.

12-14

THE DeL TASK

The implied-AND has no symbol in the metalanguage (thus the term
implied).
Use the implied-AND to form category definitions by
concate:nating arbitrary numbers of syntax elements. A syntax element
is ei t.her a literal or a nonli teral. For example, in the category
definition
for
<subject>
are
three
nonliterals -- <article>,
<adject.ive>,
and
<noun> .
An
implied-AND
concatenates these
nonliterals.
Two additional notations in the metalanguage are as follows:
Exclusive-OR indicator
Optional syntax indicators

Use the: exclusive-OR indicator "1" to show that a category can be
defined in several ways. For example, here is the production rule for
the category <adjective>:
adjective ::= OLD I YOUNG I MIDDLE-AGED
When su.bstituting for a nonliteral with more than one definition
(separa.ted
by
"1"), use only one of the definitions in the
substit.ution.
For
example,
substituting
for
the
nonliteral
<adject.ive> defined in this way in the production rule for <subject>
yields one of the following three production rules:
subject ::= THE OLD MAN
or
subject :: = THE YOUNG MAN
or
subject ::= THE MIDDLE-AGED MAN
The square brackets,
"[" and "J", enclose optional syntax.
For
example:, the following production rule defines the category <subject>:
subject ::= <article> [ <adjective> J <noun>
The square brackets around the nonliteral <adjective> indicate that
<adject.i ve> is optional syntax.
This would allow, by means of
substit.ution, rewriting the production rule for <subject> to either of
the following:
subject ::= <article> OLD <noun>
or
subject ::= <article> <noun>
In addition to denoting optional syntax, the square brackets also
indicat.e iteration.
That is, syntax denoted as optional can also be
used re~peatedly to define the syntax. For example, if the following
defines <adjective>:
adjective ::= MEAN I OLD I FAT
you could then rewrite the production rule for <subject> (if <subject>
is defined with "[" and "J" as above) to the following:
subject ::= <article> MEAN OLD FAT <noun>
Note, t.he repeated substitution for the nonli teral <adjective>.

12-15

THE DeL TASK

Thus, you can use the symbols, rules, and logic described above as a
language (that is, as a metalanguage) to define the structure of other
languages. The structure or syntax of a language is called the
grammar
of
that language.
The grammar is used to determine
mechanically whether an arbitrary sentence is a sentence in the
language.
Our interest here is in the grammars for DCL and
MCR,
the
RSX-llM/M-PLUS command languages. Sentences in these two grammars are
called commands. Here is a metalanguage definition for the grammar of
the DCL ASSIGN command:
assign ::= ASSIGN [ / <qual> ] <device> <device>
qual ::= LOCAL I LOGIN I GLOBAL I TERMINAL:
Here is a metalanguage definition for
command:
asn ::= ASN <device>=<device> [ /

the

grammar

the

MCR

ASN

<qual> ]

qual ::= LOGIN I GBL I TERM= <device>
The following section describes the Macro Metalanguage (MML).
MML
implements the logic of the metalanguage above. MML defines the
grammars for the DeL and MCR command languages.
Additionally, MML
expresses the mapping from DCL grammar to semantically equivalent MCR
grammar. MML provides a more efficient means of generating (by means
of the MACRO-II assembler) the data structures that drive the
parser/translator process than the metalanguage notation.

12.6

THE MACRO METALANGUAGE

The Macro MetaLanguage (MML) is a set of MACRO-II macros and rules.
The
following describes the correspondence of the metalanguage
notation presented in the preceding section to MML notation.
The general metalanguage presented in the preceding
two logical operators:
•

implied-AND

•

exclusive-OR

section

supports

The Macro MetaLanguage has two MACRO-II macros to correspond to
logical operators:
•

AND macros

•

OR macros

The general metalanguage presented in the
two types of syntax elements:
•

literals

•

nonliterals

section

these

supports

In MML, literals and nonliterals are presented as arguments to the AND
and the OR macros.

12-16

THE DeL TASK

In MML, literals are distinguished from nonliterals by making the
first character a quote character (for example, 'ASSIGN). An optional
argument that you can specify with a literal is the abbreviation
count. The abbreviation count is a numeral that indicates the minimum
number iQf characters that the parser needs to match for a successful
parse. For example, you could rewrite
'ASSIGN -- to -- <'ASSIGN,4>
to indicate that the literal "ASSIGN" can be abbreviated to "ASSI"'.
NOTE
The use of the symbols "<" and ">" indicates (to
MACRO-II)
that
the argument "'ASSIGN,4" is one
argument (not two: ASSIGN and 4).
Do not confuse
these symbols with the identical metalanguage symbols
used to identify nonliterals.
In the general metalanguage presented in the previous section, a
nonliteral is a reference to a category. You define a category with
the "::=" symbol by specifying the name of the category to the left of
the symbol and the definition for the category to the right of the
symbol.
In MML, you define a category by placing a MACRO-II label on either
the AND or the OR macro. The label is the name of the category, and
the arguments to the macro are the definition for the category. Thus,
in MML, a nonliteral is the label (of an AND or OR macro) that you use
as an argument to an AND or OR macro.
For example, the metalanguage notation for the category <qual>
follows:
qual ::= GLOBAL I LOCAL I TERMINAL:

The equivalent MML notation is as follows:
QUAL:

OR 'GLOBAL 'LOCAL TERM

TERM:

AND 'TERMINAL:

$DEV

There a.re two categories:
QUAL and TERM. There are three category
definitions for QUAL:
'GLOBAL, 'LOCAL, or TERM.
'GLOBAL and 'LOCAL
are literals and TERM is a nonliteral.
The category definition
'TERMINAL:
$DEV
defines the category TERM, which consists of a
literal 'TERMINAL and a predefined nonliteral, $DEV.
(See Section
12.11 for a description of $DEV).
Note that you must express a category definition like 'TERMINAL: $DEV
on a separate line (using the AND macro) because an argument to either
the AND or the
OR
macro
can
only
represent
one
syntax
element -- either a literal or a nonliteral.
Use the! MML notation "OPT=T" (optional=true) to indicate that syntax
element.s are optional. This notation corresponds to the metalanguage
notation "[" and "]". The optional syntax notation "OPT=T" is an
attribute
of
syntax elements (literals and nonliterals).
You
represe~nt literals and nonliterals in MML notation as arguments to AND
and OR macros. Therefore, you specify the optional syntax indicator
1I0PT=T" as part of the arguments.

12-17

THE DCL TASK
To specify "OPT=T" as an attribute of a syntax element, enclose the
syntax element and the "OPT=T" notation in angle brackets. For
example, to specify that the terminal device specification ($DEV) in
the previous example is an optional syntax element (nonliteral),
rewrite the category TERM as follows:
TERM:

AND 'TERMINAL:

<$DEV OPT=T>

Use the "OPTR=T" attribute to indicate that a syntax element is
optional and to indicate that the parser/translator can process the
syntax element repeatedly.
The notation OPT means a syntax element can occur, at most, one time.
The notation OPTR means a syntax element can occur many times.
In
either case, the element can occur zero times.
For a complete
description, see Section 12.10.
To specify an arbitrary number of arguments for the AND and OR macros,
use the OR., AND., and the END macros. Use the AND. and OR. macros
as continuation markers for the AND and OR macros respectively.
That
is,
if there is not enough space on the line for all the arguments to
either the AND or OR macros, place additional arguments on the next
line.
To do this, place the AND. or the OR. macro on the next line
followed by the continuation of the specification of the arguments.
For example, you could rewrite the category for <qual> to the
following:
QUAL:

OR 'GLOBAL 'LOCAL
OR. TERM
END

Use the END macro to indicate the end of the specification of the
arguments.
Note,
to allow this continuation ability (without any
additional overhead), you need the END macro whether or not you use
the continuation ability. For example, you would need the END macro
in the following category for <qual>:
QUAL:

OR 'GLOBAL 'LOCAL TERM
END

Thus, you can use MML like the metalanguage of the general description
in Section 12.5 to define the syntax of a DCL command and the syntax
of the corresponding MCR command. The parser table (PT) defines the
syntax of the DCL command and the translator table (TT) defines the
syntax of the corresponding MCR command.
The following section
describes how the PT and TT drive the parser/translator process (or
how the parser and the translator interpret the PT and the TT).

12.7

INTERPRETING DCL COMMAND TABLES

A parser table (PT)
and
translator
table
(TT)
drive
the
parser/translator process.
There is a PT/TT for each DCL command~
The PT defines the DCL syntax and the TT defines the corresponding MCR
syntax. The parser/translator process locates the PT and the TT for a
particular DCL command line by searching the master command table
(MCT)
for the command entry. The parser/translator extracts from the
command entry the address of the first AND or OR macro of the PT and
the address of the first AND or OR macro of the TT.

12-18

THE DeL TASK
12.7.1

Parser Processing

The parser starts processing at the address of the first macro in the
PT.
If the processing of this macro succeeds, then the parser process
succeeds. A successful parser process means that, at this point, the
input command line is a syntactically correct DCL command line (as
defined by the PT) and the intermediate form (IFORM) has been
constructed.
The IFORM is a condensed representation of the input
command line. If the processing of this macro fails, then the parser
process fails.
The parser processes the AND macro. by processing (left-to-right) each
argument (syntax element) of the AND macro until either all arguments
process successfully or an argument is encountered that does not
process successfully.
If all arguments process successfully, then the
processing of the AND macro succeeds; otherwise, the processing of the
AND macro fails.
The parser processes the OR macro by processing (left-to-right) each
argument (syntax element) of the OR macro until either the parser
successfully processes one syntax element or the parser fails to
process any of the syntax elements.
If the parser successfully
processes one syntax element, then the processing of the OR macro
succeeds; otherwise, the processing of the OR macro fails.

12.7.2

Translator Processing

The translator starts proces~ing at the address of the first macro of
the
'1~T.
If the processl.ng of this macro succeeds, then the
translation succeeds and an equivalent MCR command line (as defined by
the T'1~) has been constructed from the IFORM.
If the processing of
this macro fails, then the translator process fails.
The processing
of thE~ AND and OR macros by the translator is the same as the
processing of the AND and OR macros by the parser (as described in the
previous section).
Arguments to AND and OR macros can be literals or nonliterals.
NonlitE~rals
are handled in the same way by both the parser and the
translator. Literals, however, are handled differently by the parser
and the translator.

12.7.3

Parser/Translator Handling of Nonliterals

Here is a description of how
parser and the translator.

nonliterals

are

handled

both

the

In MML" when you use the label of an AND or OR macro as the argument
to an AND or OR macro it is called a nonliteral; thus, a nonliteral is
the address of another AND or OR macro.
The processing of a
nonlit.~ral
is the processing of the other AND or OR macro that the
nonlit.~ral
addresses.
That is, when the parser or
translator
encoun1:ers a nonli teral
(as an argument to an AND or OR macro), the
parser or translator transfers parsing or translation control to the
macro that the nonliteral addresses. The addressed macro is either an
AND or OR macro and the parser/translator processes this macro like
all ru~D or OR macros (as described in the previous section).
If the
processing of this macro succeeds, then the processing of the
nonlit4~ral succeeds; otherwise the processing of the nonliteral fails.

12-19

THE DCL TASK
12.7.4

Parser/Translator Handling of Literals

Here is a description of the different handling
parser and the translator.

literals

the

string of ASCII characters used as an argument to an AND or OR macro
is called a literal. The string typically is a keyword in the DCL or
MCR command grammar.
The parser and translator process literals
differently.

In parsing a literal, the parser attempts to match the literal to the
input DCL command line.
If the input command line contains the same
J~SCII string as the literal, then the
match is successful and the
processing of the literal succeeds: otherwise, nothing happens.
However, in translating a literal, the translator copies the literal
from the TT to the MCR command line buffer.
If you do not associate
attributes with a literal in a TT, then the processing of the literal
always succeeds.
(Writing a literal to the MCR command line buffer
always succeeds.) A literal in a TT can fail only if you have
associated one of the following attributes with the literal:
MAP, CBM, BCT, BST
with these attributes associated
processes the attributes before
command line buffer.

with a literal, the translator
the literal is written to the MCR

rrhe MAP attribute instructs the translator to check for a mapping
number in the IFORM.
If the number is not there, the translator does
not write the literal to the MCR command line buffer and the
processing of the literal fails.
The CBM, BCT, and BST attributes instruct the translator to check the
status of certain bits in its internal data structures.
If the status
of the bits is not correct, the translator does not write the literal
to the MCR command line buffer and the processing of the literal
fails.
{See Section 12.10 for more information on these attributes}.

12.7.5

Summary of Parser/Translator Functions

In summary, the parser table (PT) drives the parser and the translator
1:able (TT) drives the translator. The parser/translator succeeds only
if the processing of the first AND or OR macro of the PT/TT succeeds.
~rhe processing of an AND or OR macro succeeds only when the processing
of the arguments to the macros succeed.
Arguments can be either
literals or nonliterals. A nonliteral instructs the parser/translator
1:0 process (recursively) another AND or OR macro and succeeds only if
1:he subsequent AND or OR macro succeeds. A literal instructs the
parser to ensure the input command line matches the literal and
succeeds only if the match is successful. A literal instructs the
translator to output the literal (possibly conditionally) to the MCR
command line and the translator succeeds only if either the literal is
not conditionalized or the conditionals are satisfied.

12-20

THE DeL TASK
12.7.6

Examples

The following is an example of a parser table (PT) for the DCL
command.

ASSIGN

MML NOTATION for PARSER TABLE
ASSIGN:: AND
END
QUAL:
AND
END
QUALI:
OR
OR.
OR.
OR.
END
TERM:
AND
END

'ASSIGN <QUAL OPTR=T> $DEV $DEV
1/ QUALI
<'LOCAL,4>
<'LOGIN,4>
< GLOBAL, 2>
TERM
I

TERMINAL: <'TERMINAL,4>':

The following is an example of a translator table (TT) for the MCR ASN
command.
MML NOTATION for TRANSLATOR TABLE
ASN: :
LAUQ:

MRET:

AND
END
OR
OR.
OR.
END
AND
END

'ASN $DEV 1= $DEV <LAUQ OPTR=T>
'/LOGIN
'/GBL
MRET
'/TERM= $DEV

These E~xamples show the first two steps you must follow in creating
the tables for the DCL ASSIGN command. The last step is to express
the mapping of the syntax elements in the PT to the syntax elements in
the
,]~T.
This
mapping
provides
the
information
that the
parser/translator process needs to construct a particular MCR ASN
command line given a particular DCL ASSIGN command line.
The
following section describes how to express this mapping.

12.8

MAPPING DeL TO MeR

The mapping of a given DCL command line to the equivalent MCR command
line is accomplished in the IFORM.
The parser processes mapping
information and records it in the IFORM. The translator searches the
IFORM for mapping information and then generates the MCR command line.
Mappin9 information is expressed in MML with the IMAP=n" attribute.
MAP takes one or two values. The first value is called the primary
mappin9 number. The second value is called the secondary mapping
number..
If you need only the primary mapping number, specify it in
the following form:
M1\.P=n

12-21

THE DCL TASK

If you need to specify both mapping numbers, which is allowed only in
a TT, or if you need to specify only the second number, then enclose
the numbers in angle brackets and separate them with a comma in the
following form:
MAP=<n,n> or MAP=<,n>
'ro associate the MAP attribute with a syntax element, enclose the
syntax element and the MAP attribute in angle brackets as follows:
<syntax-element

MAP=n>

To map a DeL syntax element in a PT to an MeR syntax element in the
corresponding TT, use MAP with the same mapping number for both syntax
4elements.
For example, in the ASSIGN command, the DeL qualifier "/GLOBAL" maps
to the MeR qualifier "/GBL".
That is, when the DeL qualifier
"/GLOBAL" is input (as part of the DeL command line), the MeR switch
"/GBL" is output (as part of the MeR command line).
following expresses this mapping in MML notation
the use of the primary MAP number.

~rhe

QUAL:

OR <'/GLOBAL MAP=l> ...
END

LAUQ:

OR <'/GBL MAP=l> ...
END

and

illustrates

MML macros at QUAL: define DCL syntax. MML macros at LAUQ:
(QUAL
spelled backwards) define the corresponding MeR syntax. When the
parser reaches QUAL:, it tries to match the literal "/GLOBAL" to the
input (DeL) command line.
If the match is successful, then the parser
queues the MAP number "PI" (the "p" indicates a primary mapping
number) to the IFORM queue. When the translator reaches LAUQ:, it
searches the IFORM queue for the MAP number "PI". If the translator
finds the MAP number "PI", it outputs to the (forming) MeR command
line the literal "/GBL". If the translator cannot find the MAP number
in the IFORM queue,
it does not use the syntax element (associated
with the MAP number) in the translation.
The MAP attribute in a PT can associate either a primary or a
secondary mapping number with a syntax element, but not both.
However, the MAP attribute in a TT can associate either or both
mapping numbers with a syntax element.
Associating a primary mapping number with a syntax element in the PT
(by means of the MAP attribute) instructs the parser to queue the
primary mapping number to the IFORM queue.
Associating a secondary
mapping number with a syntax element in the PT instructs the parser to
queue the secondary mapping number to the IFORM queue.
In both cases
the parser queues a mapping number only if the parser processes the
associated syntax element successfully.
The MAP attribute in a TT instructs the translator to search the IFORM
queue for a mapping number.
When found, the translator marks the
r~apping number used and processes the associated syntax element.

12-22

THE DeL TASK

The search for a primary mapping number differs from the search for
secondary mapping numbers. The translator searches the entire IFORM
queue from head to tail to find." primary mapping numbers.
The
translator limits its search for' secondary mapping numbers, however.
The translator starts its search for secondary mapping numbers at the
queue element containing the last used primary mapping number and
stops t~he search at the next queue element containing a primary
mappin9 number.
Specifying both a primary and a secondary mapping number in the TT
(for example, MAP=<l,l» instructs the translator to search the entire
IFORM queue for the specified primary mapping number such that the
specified secondary mapping number follows without any intervening
primary mapping numbers. The secondary mapping number qualifies the
primary mapping number. The primary mapping number is the object of
the search.
If the translator finds a mapping number in the IFORM queue, the
translator processes the associated syntax element.
If the translator
fails 1:0 find the mapping number, the processing of the associated
syntax element fails. When the translator finds a mapping number and
successfully processes the associated syntax element, the translator
marks as used the queue element containing the found mapping number.
A used mapping number can no longer be found. This prevents infinite
loops in the TT without requiring the specification of termination
conditions.
A MAP attribute can be specified in both the PT and
associating it with a syntax element, as follows:

the

without

<MAP=n>
If you specify this attribute as an argument to an AND or OR macro in
a PT, 1:he parser assumes a null syntax element. A null syntax element
always succeeds.
If you specify a null syntax element in a TT, the translator (after
findin9 the queue element containing the mapping number) checks to see
if a character buffer is attached to the queue element.
If a
charac1:er buffer is attached, then the translator copies the contents
of the buffer to the MCR command line buffer. If a character buffer
is n01: attached, then the translator (like the parser) assumes a null
syntax element (which always succeeds).
The parser attaches the character buffer to the queue element.
The
COP a1:tribute instructs the parser to create the character buffer and
copy the text parsed by the associated syntax element to the character
buffer (See Section 12.10 for details on the COP attribute).
Thus, rnapping starts in the parser process when the parser queues
mappinq numbers to the IFORM queue, as it successfully processes
syntax elements that have associated MAP attributes.
Mappinq is completed in the translator process when the translator
detects mapping numbers in the IFORM queue and translates the syntax
elements. Note that the translator does not output a syntax element
that has a MAP attribute associated with it unless (1) the translator
first finds the mapping number in the /FORM queue, and (2) the mapping
number has not been previously used.

12-23

THE DCL TASK
Here is an example of a complete command table (with DCL-MCR
for the DCL ASSIGN command:

mapping)

ASSIGN MML NOTATION FOR PARSER TABLE
ASSIGN:: AND
END
QUAL:
AND
END
QUALI:
OR
OR.
OR.
OR.
END
TERM:
AND
END

'ASSIGN <QUAL OPTR=T> <$DEV MAP=l> <$DEV MAP=2>
1/ QUAL I
<'LOCAL,3>
<'LOGIN,3 MAP=3>
<'GLORAL,2 MAP=4>
TERM
< TERMINAL, 4>
I

ASN MML NOTATION FOR TRANSLATOR TABLE
ASN: :
LAUQ:

MRET:

AND
END
OR
OR.
OR.
END
AND
END

'ASN <MAP=l> 1= <MAP=2> <LAUQ OPTR=T>
<'/LOGIN MAP=3>
<'/GBL MAP=4>
MRET
'/TERM= <MAP=5>

For a complete description of the MAP attribute, see Section 12.10.
For information on related attributes see the discussions of the
following:
DMAP, NO, COP, OCOP, TST, and DIR
The parser records mapping information; the translator detects the
mapping information.
The following section presents IFORM, the
dynamic data structure that passes mapping information from the parser
to the translator.

12.9

THE INTERMEDIATE FORM (IFORM)

The IFORM contains the essential information (extracted from the input
DCL command line) that the translator needs to construct the MCR
command line. The IFORM consists of three data structures:
the
queue, the character buffers, and the general bit-mask words.
NOTE
To display the IFORM for a given DCL command, use
DEBUG/FULL.

SET

The parser creates the IFORM queue when it successfully processes
syntax
elements
with
MAP
attributes.
Each time the parser
successfully processes a MAP attribute, it queues the mapping number
to the IFORM queue.
The parser creates a character buffer when a syntax element has both
MAP and COP attributes. The parser attaches the character buffer to
the queue entry that contains the mapping number.
The character
buffer
contains the text parsed during the processing of the
associated syntax element.

12-24

THE DeL TASK

A syntax element with a COP attribute and no MAP attribute instructs
the parser to copy the text parsed to the last queued mapping number
(creating and attaching the character buffer if neccessary).
The general bit-mask words are two words used as a set of 32 flags.
The parser/translator process attaches no meaning to the flags, but
MML provides a set of attributes to set flags, clear them, test if the
flags are set, and test if the flags are clear. You can use the flags
to check for contradictory syntax. In addition, use the flags to pass
information from the parser to the translator. For example, set a
flag during the parser process if a DeL qualifier is seen and detect
the SE~t flag during the translator process, generating the equivalent
MCR switch.
The translator searches the IFORM queue for mapping numbers.
If the
translator
finds the mapping numbers,
it processes the syntax
elements. If the translator cannot find the mapping numbers, then the
syntax elements fail.
If a MAP attribute is specified without an associated
as follows:

syntax

element

<~1AP=n>

the translator first finds the queue element containing the mapping
number and then examines the queue element for a character buffer
attachE~d by means of the COP attribute.
If the translator finds an
attachE~d character buffer, it cQpies the contents of the buffer to the
MCR co~wand line buffer. If the translator cannot find an attached
buffer, it assumes a null syntax element (which always succeeds).
Use the following attributes (in the PT) to direct the parser
creation of the IFORM:

Ml\.P=n

MAP= < , n>

(map)

Dr.1AP=n

DMAP= < , n>

(map unless duplicate exists)

COP=T

OCOP=T

(copy, or copy optional input)

BS=n

BS=<,n> BS=<n,n>

(set bit in mask word)

BC=n

BC=<,n> BC=<n,n>

(clear bit in mask word)

NO=T

(repeats for negative
syntax element)

Use thE! following attributes (in the TT) to direct the
the examination of the IFORM:

the

form

translator

MllI.P=n

MAP=<,n> MAP=<n,n>

(unmap)

BST=n

BST=<,n> BST=<n,n>

(test for bit set in mask word)

BCT=n

BCT=<,n> BCT=<n,n>

(test for bit clear in mask word)

TST=T

(test for mapping
mark as used)

DIR=T

(search IFORM in reverse direction)

For details on these attributes, see Section 12.10.

12-25

number,

not

THE DCL-TASK
l~or

example, if the input command line is:
ASSIGN OKl:

SY:

then the IFORM would be:
Queue

Character Buffer

OKl:

GJ -----.-;. . .

SY:

If the input command line is:
ASSIGN/LOGIN/T:TT12:

OKl:

SY:

then the IFORM would be:
Queue

Character Buffer

12.10

TT12:

OKl:

SY:

ATTRIBUTES OF SYNTAX ELEMENTS

Attributes associate characteristics with literal and nonliteral
syntax elements.
The parser/translator processes attributes either
before or after it processes the associated syntax elements (depending
on the attribute).
The processing of attributes can influence the
processing of the associated syntax elements.
Here is the format for specifying attributes as part of an argument to
an AND or OR macro:
<'literal

KEY=value KEYl=value ... >

or
<label

KEY=value KEYl=value ... >

where:
literal

Literal (ASCII) string

label

Nonliteral (address of an AND or OR macro)

KEY

Attribute keyword identifying the attribute

value

Value assigned to the attribute

Note the use of the angle brackets 11<11 and 11>11.
Use these MACRO-II
symbols to indicate that everything enclosed is considered as one
argument (when expanding macros).
Do not confuse these MACRO-II angle
brackets with the angle brackets used to indicate nonliterals in
metalanguage notation.

12-26

THE DeL TASK

12.10.1

AND

AND allows you to extend a syntax element by specifying a nonliteral
that is ANDed to the syntax element. The primary function of AND is
to allow OR logic to be mixed with AND logic. Assign a nonliteral to
the AND attribute as follows:
AND=label
where:
label

Nonliteral address of an AND or OR macro

AND instructs the parser/translator to process the AND or OR macro
that t:he label (the nonliteral) addresses in addition to processing
the syntax element with which the AND attribute is associated.
For example, in the following MML definition for QUAL,
syntax element defines the structure IFILE:<filespec>":
QUAL:

OR
OR.
OR.
END

'BRIEF
<'FILE AND=FNAME>
'FULL

FNAME:

AND
END

' : $FILE

the

second

There are three syntax elements in this structure:
FILE
and

and
<filespec>
The lit:eral ": and the nonliteral <filespec> connect to the literal
"FILE" by means of the AND attribute. The parser/translator processes
all three elements as one element to the OR macro by definition of the
AND att:ribute.
II

12.10.2

BC and BS

BC (Bit Clear) and BS (Bit Set) operate on two global
as follows:

bit-mask

words

•

The BC attribute instructs the parser/translator to clear bits
in these two global words.

•

The BS attribute instructs the parser/translator to
in these two global words.

Use thE! BCT and BST attributes to test
section. )

these

bits.

The format for these attributes is as follows:
BC=n

BC=<,nl>

BC=<n,nl>

BS=n

BS=<,nl>

BS=<n,nl>

12-27

(See

set

bits

the

THE DCL TASK
'where:
n

Bit mask specifying bits in the first glohal word

Bit mask specifying bits in the second global word

Specify a bit mask by ORing single bit specifications with the
MACRO-II symbol fllf1.
The symbols Bl, B2, ... B32 are predefined to
correspond to single bit specifications for each bit in the two global
words.
For example, BS=BllB21B5 means to set bits 1, 2, and 5 of the first
global word. See the next section for an example of these attributes
in use.

12.10.3

BCT and SST

BCT (Bit Clear Test) and BST (Bit Set Test) test the status of bits in
the two global bit-mask words as follows:
•

The BCT attribute instructs
whether bits are cleared .

the

parser/translator

test

•

The BST attribute instructs
whether bits are set.

the

parser/translator .to

test

See the previous section for information on how these bits are set or
cleared. The parser/translator does not clear the two global bit-mask
words between the parse and the translation. You can use these words
as part of the IFORM to pass information from a PT to a TT.
The format for these attributes is as follows:
BCT=n

BCT=<,nl>

BCT=<n,nl>

BST=n

BST=<, nl>

BST=<n,nl>

where:
n

Bit mask specifying bits in the first global word

Bit mask specifying bits in the second global word

For example, BST=<,B191B31> means to test whether bits 19
the second global bit-mask word are set.

and

The following example illustrates the use of BS, BC, BST, and BCT:
COPY:

AND

FILE <FILE OPTR=T> QUA=QUAL

END
FILE:

OR
OR.
END

<$NFIL
$FILE

BS=Bl

BCT=B21B3>

QUAL:

OR
OR.
END

<'INDEX
<'SEQUENTIAL

BS=B2
BS=B3

BCT=BllB3>
BCT=BllB2>

In this example, INDEX and SEQUENTIAL are qualifiers, $NFIL is a
predefined syntax element that is a file specification that has a node
name prefixing it, and $FILE is a predefined syntax element that is a
conventional file specification (without a node name). The example
specifies that the qualifiers INDEX and SEQUENTIAL are contradictory,
12-28

THE DCL TASK
that INDEX and $NFIL are contradictory, that SEQUENTIAL and $NFIL are
contradictory, but that duplicates of each are not contradictory. The
BS attribute instructs the parser to set the specified bits if the
processing of the associated syntax elements is successful. The BCT
instructs the parser to test whether the specified bits are clear.
If the tested bits are set, the parser does not process the associated
syntax elements. Thus, bits are set to remember which syntax elements
process successfully, and bits are tested to determine
if
a
contradiction would result from the processing of syntax elements.
The main difference between the BC, BCT, BS, and BST attributes and
CBM (described in the next section) is that CBM always prevents
duplicate syntax as well as contradictory syntax, but CBM cannot pass
information from the parser to the translator.

12.10.4

CBM, CCBM

Use CB~1 (Contradictory Bit Mask) to prevent the parser or translator
from allowing contradictory syntax.
To indicate that two or more
syntax elements cannot be specified in the same command line, specify
CBM with each syntax element. Assign a bit mask as the value to CBM.
Specify the same bit in each bit mask associated
with
each
contradi~tory syntax element.
CBM conditionalizes the processing of the associated syntax element.
The parser uses the specified bit mask to set bits in two global
words. If the parser detects that any bits specified in the bit mask
are already set in the two global words, then the parser assumes a
contradiction and the syntax element fails. This also means CBM does
not allow duplicate syntax elements.
Also note that the parser/translator clears the two global words
between the parse and the translation. You cannot use CBM to pass
information from a PT to a TT.
The format of the CBM attribute is as follows:
CBM=n or CBM=<,nl> or CBM=<n,nl>
where:
n

Bit mask specifying bits in the first global word

Bit mask specifying bits in the second global word

Specify a bit mask by ORing single bit specifications with the
MACRO-II symbol "I".
The symbols Bl, B2, ... , B32 are predefined to
correspond to single bit specification.
For example, CBM=BIIB21B5
specifies
bits
1,
2, and 5 of the first global word, and
CBM=<,1319IB31> specifies bits 19 and 31 of the second global word.
The following example illustrates the use of the CBM attribute:
QUAL:

OR
OR.
OR.
END

<'LOCAL
<'LOGIN
<'GLOBAL

CBM=BIIB2>
CBM=B2>
CBM=Bl>

The example specifies that the literals "LOCAL" and "GLOBAL" are
contra6ictory, and that the literals "LOCAL" and "LOGIN" are also
contradictory, but that the literals LOGIN " and "GLOBAL" are not.
The example also specifies that each of these elements can be used
only once.
II

12-29

THE DCL TASK
CCBM (Clear Contradictory Bit Mask) clears the bits in the two global
words. The format for specifying CCBM is identical to the format that
you use to specify the CBM attribute.

12.10.5

COP, OCOP

COP (COPy) is legal only in a PT and only with a literal syntax
element.
COP passes a literal from the input DCL command line to the
IFORM. The translator can then use the literal in the MCR command
line.
The parser copies the literal to a character buffer and
attaches it to the mapping number last queued. If you specify a MAP
attribute with the COP attribute, the mapping number (assigned to the
MAP attribute) is the mapping number last queued. The format of the
COP attribute is as follows:
COP=T
For example, the following code defines a terminal specification:
TERM:

OR <ITT COP=T AND=N>
OR. <IHT COP=T AND=N>
OR. <IVT COP=T AND=N>
OR. <ITI COP=T AND=N>
END
AND <$ONUM,0,3> <I: OCOP=T>

This code parses and copies a terminal name as TT, VT, HT, or TI
followed by an octal number as terminal names.
(See Section 12.11.1
for a description of $ONUM, which defines an octal number.) The OCOP
attribute assures the presence of the terminating colon by copying it
into a character buffer whether or not the user inputs one.
To instruct the translator to copy the character buffer to the MCR
command line, specify the MAP attribute as follows, without specifying
an associated syntax element:
<MAP=n>
When the translator processes a MAP attribute that has no associated
syntax element, the translator examines the mapping number queue
element for an attached character buffer. If a character buffer is
found,
the translator copies the contents of the character buffer to
the forming MCR command line buffer. If a character buffer is not
found,
the translator assumes a null syntax element (which always
processes successfully).
OCOP (Optional COPy) is identical to COP except for one significant
difference.
OCOP instructs the parser to copy the literal to the
IFORM whether or not the processing of the literal succeeds. That is,
the literal is optional and always succeeds if you associate OCOP with
it.
The following illustrates the use of the OCOP attribute:
DEV:

AND

<$ALF,2,2> <$NUM,0,3> <I:

OCOP=T>

The MML definition defines a device specification such that the colon
on the end of the specification is optional. The translator copies
the colon to the output MCR command line whether or not the parser
found a colon in the input DCL command line.

12-30

THE DeL TASK

12.10.6

DIR

DIR (DIRection) is legal only in the TT and only when you
specify it
with a MAP attribute.
DIR instructs the translator to search the
IFORM queue for the specified mapping number in reverse order.
The
normal direction of the search is from the head of the queue to the
tail of the queue. DIR instructs the translator to search the IFORM
queue from the tail to the head of ~he IFORM queue. The format for
DIR is as follows:

DIR=R
The following example of a TT fragment illustrates the use of the
attribute:

FILE:

DIR

<MAP=l DIR=R <MORE OPT=T>

AND

END
MORE:

«~I

AND

,»

FILE

END
This E!xample defines (recursively) the
structure
of
a
file
specification list, where the file specifications are mapped to
mapping number 1. Due to the associated DIR attribute, the translator
searches for the mapping numbers in reverse order: thus, the list of
file specifications is output to the MCR command line in reverse
order.
NOTE
The double angle brackets are necessary in cases where
the contents of the brackets include a MACRO-II
separator character (in this case, the comma) that is
to be treated as a literal by MML.

12.10.7

ERR

ERR (ERRor)

allows you to associate error messages with syntax
If the parser or the translator fails to process a syntax
element~, and the syntax element has ERR specified, then the parser
or
translator prints the error message specified and aborts the parse or
translation. The format for ERR is as follows:
element~s.

ERR='string
or
ERR=label
label:

ERROR </string/>

For example, to specify an error message for the device being
assigned, use the following MML notation in the PT for the ASSIGN
command:
AND

'ASSIGN <QUAL OPT=T> <$DEV ERR=<'Invalid device»

12-31

THE DCL TASK
If the parser cannot parse the input DCL command line text that
corresponds to the device specification ($DEV), the parser prints the
message "ASSIGN -- Invalid device", and aborts the parse.

12.10.8

HLP

Use HLP (HeLP) in a PT only to associate help text with syntax
elements that have the PRO attribute (Section 12.10.12) specified.
When the parser is prompting and a "?" character is input, the parser
spawns a HELP command. The parser appends the text specified in the
HLP attribute to the HELP command "HELP command" where
command
is
the name of the DCL command being processed. The format of the HLP
attribute is as follows:
II

HLP='string
or
HLP=label
label:

HELP </string/>

where:
string

Appended to the HELP command

label

Label of a HELP macro

The parser appends the string to the command
HELP command", where
command
is the name of the current command being processed. For
example, if you specify the PT for ASSIGN as:
II

AND

<QUAL OPTR=T> <$DEV PRO='Device?

HLP=<'Logical name»

and the user types a "?" in response to the prompt "Device?",
parser forms and spawns the command "HELP ASSIGN LOGICAL NAME".

the

This requires a file named DCLASSIGN.HLP containing the necessary help
text.
For the format of the HELP file, see the HELP documentation in
the RSX-llM Command Language Manual, the RSX-llM-PLUS Command Language
Manual or the RSX-llM!M-PLUS MCR Operations Manual.

12.10.9

MAP, DMAP

MAP is legal in both the PT and the TT. However, the parser and the
translator interpret MAP differently. The following summarizes the
types of legal MAP attributes in a parser table:
MAP=n

Instructs the parser to queue the specified primary
mapping number n to the IFORM queue only if the
associated syntax element is successfully parsed.

MAP=<,nl>

Instructs the parser to queue the specified secondary
mapping number nl to the IFORM queue only if the
associated syntax element is sucessfully parsed.

Note that specifying COP with MAP in a PT instructs the parser to
create and attach a character buffer to the mapping number, and copy
the text parsed by the associated syntax element to the attached
character buffer. For additional details, see Section 12.10.5, which
describes COP.

12-32

THE DeL TASK

The following summarizes the
translator table:

types

legal

MAP

attributes

MAP=n

Instructs the translator to search the IFORM queue
from top to bottom for the specified primary mapping
number n. If found, the translator places the element
in the MCR command line.
If not found, nothing
happens.

MAP=<,nl>

Instructs the translator to search the IFORM queue for
the secondary mapping number nl.
Because the object
of the search is a secondary (not primary) mapping
number,
the translator does not search the entire
IFORM queue. The translator starts searching at the
last used primary mapping number and stops the search
at the next primary mapping number.
If the secondary
mapping number is found, then the associated syntax
element is processed; otherwise, nothing happens.

MAP=<n,nl>

Instructs the translator to search the IFORM queue
from head to tail for the specified primary mapping
number n.
If found, the translator searches for the
specified secondary mapping number nl.
If found, the
associated syntax element is processed.
If not found,
another occurrence of primary mapping number n is
sought.
If another instance of primary mapping number
n is found,
then the translator looks again for the
specified secondary number nl.
This search process
continues until either all primary mapping numbers n
have been found and none of them have a secondary
mapping number nl after them, or until a primary
mapping number n is found that does have a secondary
mapping number nl after it.

If you specify a MAP attribute in a TT without specifying an
associated syntax element, the translator examines the queue element
containing the specified mapping number for an attached character
buffer.
If the translator finds an attached character buffer, the
translator copies the contents of the buffer to the forming MCR
command line buffer.
If the translator does not find an attached
character buffer, the translator assumes a null syntax element (which
always processes successfully).
To allow additional flexibility in the search for secondary mapping
numbers,
the translator supports the following additional formats for
specifying the MAP attribute in a TT:
MAP=<X,nl>

Instructs the translator to search the IFORM queue
from head to tail for the specified secondary mapping
number nl.
If found,
the translator processes the
associated
syntax
element.
If not found,
the
associated syntax element fails to process.
The
keyword "X" identifies this MAP attribute as an
unconditional search for a secondary mapping number.

MAP=<Xl,nl>

Instructs the translator to seach the IFORM queue for
the secondary mapping number nl.
The keyword "Xl"
instructs the translator to limit the search of the
queue as follows.
The search is started at the head
of the queue and proceeds until the first primary
mapping number is detected.
If the secondary mapping
number nl is not found,
then another search is
conducted. The second search looks for the secondary

12-33

THE DeL TASK
mapping number nl such that it follows a negative
primary mapping number.
If found,
the translator
processes the associated syntax element.
If not
found, nothing happens.
Note that you use the "X" MAP attribute to search for a secondary like
a primary (that is,
unconditionally) and the "Xl" MAP attribute to
search for floating command qualifiers. For information on floating
command qualifiers see Section 12.10.13, which describes QUA.
When the translator finds a mapping number and processes
the
associated syntax element, the translator marks the mapping number as
used. A used mapping number cannot be found again by the translator.
Thus marking mapping numbers used prevents infinite loops in the TT
without the need to specify termination conditions. To override the
marking of mapping numbers, use TST. To reset all marked mapping
numbers, use the $RESET predefined syntax element.
(This is useful
for generating multiple MCR commands by means of the $NEW predefined
syntax element.)
DMAP (duplicate map) is identical to MAP in most ways. However, it is
only allowed in a PT.
DMAP instructs the parser not to queue the
mapping number to the IFORM queue if the same mapping number is
already present in the IFORM queue.
If the parser does not queue the
mapping number, then the syntax element that MAP is associated with
fails to process.
Thus, the DMAP attribute can prevent duplicate
syntax.
For additional information on the use of the MAP
Section 12.8, Mapping DCL to MCR.
The following example shows the use of primary
predefined syntax elements.

attribute,
mapping

see

the

numbers

with

DCL file specifications, device specifications, numerals, and so
forth, map to themselves. That is, when a file specification, device
specification, numeral, and so forth,
is input, the same file
specification, device specification, numeral, and so forth, is output.
Here is an example of how a terminal device specification maps to
itself.
Parser Table
TERM:

AND 'TERMINAL:
END

<$DEV,MAP=2>

Translator Table
MRET:

AND 'TERM= <MAP=2>
END

'The parser table specifies at label TERM: If the input command line
matches a device specification ($DEV), then queue mapping number P2 to
the IFORM queue, attach a character buffer to this queue element, and
copy the device specification to the attached character buffer. The
translator table specifies at label MRET:
If P2 is in the IFORM
queue,
then output the contents of any attached buffer to the forming
iMCR command line.
'rhe following example illustrates the use of secondary mappings.

12-34

THE DeL TASK
When translating the DCL MACRO command to the MCR MAC command,
it is
necessary to determine which (if any) input file specification has the
qualifier /LIST on it. That is,
the translator must be able to
determine
(by means of information in the TT)
that the file
specification "C" in the DCL command line "MACRO A,B,C/LIST,D" has the
/LIST qualifier on it. The IFORM must map the DCL file specification
that has the /LIST qualifier on it to the right position in the MCR
command line.
The mapping can more easily be understood from the viewpoint of the
translator.
The translator generates the MCR MAC command from left to
right. When the translator reaches the position in the output MCR
command line where the list file must be placed, the translator looks
in the IFORM queue for the mapping number that represents the file
specification with the /LIS~ qualifier on it.
Since the file
specification and qualifier are two distinct syntax elements,
there
are two mapping numbers in the IFORM queue to represent them.
Also,
since the IFORM queue is a linear data stucture (and not a
tree), a
means of associating the /LIST qualifier with the file specification
is needed.
To express an association between elements in the IFORM queue,
use
primary and secondary mapping numbers.
Secondary mapping numbers
(such as Sl) have meaning only as related to primary mapping numbers
(such as PI).
The following MML notation expresses this mapping and illustrates
use of primary and secondary mappings.

the

Parser Table

FILES:
MORE:

AND
END
AND
END
AND
END

'MACRO FILES
<$FILE MAP=l> <'/LIST OPT=T MAP=<,l»
«~I

,»

FILES

Translator Table

LST:

AND
END
AND
END
SELIF:

'MAC <OBJ OPT=T> <LST OPT=T> '= SELIF
«~I ,»

<MAP=<l,l»

It is possible when parsing (due to the recursive definition of FILES)
to qUE~ue to the IFORM queue identical map numbers
("PI") that
represent the
input file specifications.
The
only
means
of
distin9uishing
the "PI" map numbers
is by their left-to-right
positioning. For the translator to find the "PI" map number that
represents the file specification with the /LIST on it, the translator
has to find the "PI" map number that is followed by the "Sl" map
number such that there are no intervening "Pn" map numbers.
In MML,
to instruct the translator to perform such a search, use the argument
"<MAP=<l,l»", as specified at label LST.
RemembE~r that if a reference is made to a secondary map number without
specifying a primary map number, then the translator looks for a
secondary map number that is associated with the last used primary map
number.

12-35

,THE DeL TASK
12.10.10

NO is allowed only in a PT. NO instructs the parser to process either
a literal "NO" or a literal "_" before it processes the associated
literal. The NO attribute is legal only when associated with a
literal syntax element.
The format for the NO attribute is as
follows:
NO=T
If you specify a MAP with a NO, the parser queues two different
mapping numbers.
If the parser does not process either the "NO" or
1:he "_", the parser queues the mapping number assigned to MAP.
If the
parser does process either the "NO" or the "_", the parser increments
1:he mapping number by one before it queues the mapping number.
~rhe

following illustrates the use of NO:
OR

<'LIST MAP=lO.

NO=T>

In this example, the parser attempts to parse either NOLIST, -LIST, or
LIST.
If LIST is parsed, the parser adds the mapping number 10 to the
IFORM queue. If either NOLIST or -LIST is parsed, the parser queues
the mapping number 11.

12.10.11

OPT, OPTR

Use OPT (OPTional) to indicate that a syntax element is not required.
You can use OPT in both the PT and the TT.
The parser and the
·translator interpret OPT identically.
The format for OPT is as
follows:
OPT=T
For example, to specify that qualifiers
(label QUAL) are optional
syntax in the ASSIGN command, use the following MML notation:
AND

'ASSIGN <QUAL OPT=T>

The parser goes to label QUAL and processes the syntax defined at
label QUAL.
If the parser cannot process a syntax element in an AND
macro, the failure implies the failure of the AND macro.
The OPT=T
attribute tells the parser to ignore the failure and continue
processing the AND macro with the next (left-to-right) argument to the
AND macro.
Use OPTR (OPTional Repeat) in the same way to indicate that a syntax
E~lement
is not required.
In addition, use OPTR to indicate that the
syntax element can be used repeatedly in the parse/translation until a
failure results.
In other words, the presence of OPTR indicates that
the syntax element can be used to parse or translate syntax from zero
t~o an infinite number of times.
The format for OPTR is as follows:
OPTR=T
E'or example, to specify that qualifiers
(label QUAL) are optional
syntax in the ASSIGN command and that the qualifiers can be used
repeatedly in the input command line, use the following MML notation:
AND

'ASSIGN <QUAL OPTR=T> ...

The parser goes to label QUAL and processes the syntax defined there.
If a syntax element in an AND macro fails, the failure cannot be used
i.n the parse, implies the failure of the AND macro.
The OPTR=T
12-36

THE DeL TASK
attribute tells the parser to ignore failure and to
continue
processing the AND macro with the next (left-to-right) argument to the
AND macro. However, if and while the syntax defined at label QUAL
matches the input command, the parser uses it repeatedly.
If the OPT and AND attributes are used in the same syntax element, the
OPT modifies the AND.
That is, the OPT does not modify the entire
syntax element.
For eXclmple, here is a fragment of code based on the LINK command
translator table. The TT specifies a TKB switch that can be specified
with or without arguments attached.

PRIV:

OR.
END

<'/PR MAP=l AND=PRIV OPT=T>

AND
END

': <MAP=3>

In the example, the optional argument to the /PR switch is attached to
The OPT applies to AND=PRIV and not to the whole
mappinsr number 3.
syntax element. If the OPT applied to the entire syntax element, then
the entire OR macro, of which this fragment is a part, would always
succeed.

1 2 . 1 0 . 12

PRO

Use PRO (PROmpt) in the PT to associate prompt strings with syntax
element.s.
If the parser detects end-of-line while processing a syntax
element. that has the PRO attribute specified, the parser prints the
prompt string specified, and suspends itself to wait for more input.
The parser appends any input received to the input DCL command line.
PRO is legal only in the PT. The translator does not prompt. The
format of PRO is as follows:
PRO='string
or
PRO=label
label:

PROMPT </string/>

where:
st.ring

ASCII string to be used as the prompt string

label

(MACRO-II) label of a (MACRO-II) PROMPT macro

Thus, s:pecify the prompt string directly after the "=" symbol, or as
the argument to the PROMPT macro. The PROMPT macro allows global
prompt strings, which conserve space.
The following example illustrates the use of PRO:
AND <QUAL OPTR=T> <$DEV PRO='Device?> <$DEV PRO=PRODEV>
PRODEV:

PROMPT </Logical device?
12-37

THE DeL TASK
'The command requires two device specifications {$DEV}. If the parser
expects the first $DEV but reaches the end of the line, then the
parser prompts as follows:
Device?
If the parser expects the second $DEV but reaches the end of the line,
then the parser prompts as follows:
Logical device?

1 2 • 1 0 • 13

QUA

Use QUA {QUAlifier} to specify qualifiers. You can specify floating
or positional qualifiers. Floating qualifiers are qualifiers that are
legal anywhere in the input DeL command line.
Positional qualifiers
are qualifiers that are legal only at specific positions in the input
DCL command line or output MCR command line.
The positional form of the QUA attribute is legal in both a PT and a
TT.
The floating form is legal only in a PT. The format for QUA is
as follows:
QUA=label
where:
label

Nonliteral (address of an AND or OR macro)

When the QUA attribute is used in a PT and the parser encounters a
slash {/} in an appropriate location, it attempts to match the text
following the slash with one of the elements of the AND or OR macro at
-the specified label.
If an end-of-line is encountered after the
slash, the parser issues a prompt.
If an illegal qualifier is given,
then an error message is printed and the parse is aborted. The list
of qualifiers is repeatedly scanned until all qualifiers in the input
command line have been parsed.
'ro specify a positional QUA attribute, use QUA as
I~lement.
For example:

QUAL:

AND
END

<'ASSIGN,3 QUA=QUAL> $DEV $DEV

OR
OR.
OR.
OR.
END

<'GLOBAL,l>
<'LOCAL,3>
<'LOGIN,3>
TERM

part

syntax

In this case, any qualifiers {such as /GLOBAL} must immediately follow
"ASSIGN" in the command line.
(See the following example for more
details on how the QUA attribute works.)
To specify floating qualifiers, use QUA as a separate argument to an
AND macro, not as part of another argument. The parser attempts to
rnatch the qualifiers defined at the label before and after it
processes each argument of the AND macro. That is, the qualifiers
float before and after each syntax element defined by the AND macro.
Furthermore, the parser attempts to parse the floating qualifiers
after any prompts.
If QUA is being used to specify floating
qualifiers, it must be an argument to an AND macro, rather than an
AND.
{extension} macro. The floating-qualifier form of QUA is legal
only in a PT.
12-38

THE DeL TASK
The following illustrates the floating-qualifier form of QUA:

QUAL:

AND
END

'ASSIGN, 3 $DEV $DEV QUA=QUAL

OR
OR.
OR.
OR.
END

< 'LOCAL, 3>
<'LOGIN,3>
< 'GLOBAL, 1>
TERM

The label QUAL defines the allowable qualifiers.
The parser checks
for the qualifiers before, between, and after the $DEV syntax
elements. Before the parser transfers parsing control to the OR macro
at label QUAL, the parser attempts to parse the slash "/" character.
Only if the parser successfully parses the slash, does it attempt to
parse t:he qualifiers defined at label QUAL.
If the parser detects the
end of the input DCL command line after it parses a slash character,
the parser prompts for more input.
If a slash is detected and the
qualifiers defined at label QUAL fail to process, the parser issues an
error message and aborts the parse. The parser repeatedly attempts to
parse 1~e qualifiers until it no longer can parse a slash character.
Thus, using
following:

QUA

the

example

equivalent

the

AND
END

QUAL:

AND

'/ <QUALl PRO='Qualifier? ERR=<'Illegal qualifier»

QUAL1:

OR
OR.
OR.
END

<'LOCAL,2>
<'LOGIN,2>
< 'GLOBAL, 1>

The following illustrates the use of the QUA attribute in a TT.
ASN: :

AND «'ASN »
END

LAUQ:

OR < 'GBL
OR. <'LOGIN
OR. MRET
END

<MAP=l> '= <MAP=2 QUA=LAUQ>
MAP=4>
MAP=3>

The label LAUQ defines the MCR switches equivalent to the DCL
qualifiers.
The translator processes QUA just as does the parser.
However, instead of parsing the input DCL command line for qualifiers,
the translator uses the qualifiers to construct the equivalent MCR
command line. Remember that QUA automatically includes slashes before
each s,,,i tch.

12.10.14

TST

TST is legal only in a TT and only when specified with MAP.
TST
instructs the translator not to mark a mapping element used in a
translation as having been used. The format of the TST attribute is
as follows:
TST=T

12-39

THE DCL TASK
1~e

following illustrates the use of the TST attribute:
MCRCOP: OR
OR.
OR.
END

<PIP
<PIP
<NFT

MAP=l TST=T>
MAP=2 TST=T>
MAP=3>

In the previous example, the OR macros instruct the translator to
process the nonliteral PIP if either mapping numbers 1 or 2 are in the
IFORM queue, or to process the nonliteral NFT if mapping number 3 is
in the IFORM queue.
The TST attribute associated with the syntax
E~lement PIP instructs the translator not to mark mapping numbers 2
or
3 as having been used.
This allows the syntax defined at label PIP to
use these mapping numbers also.

1.2.11

PREDEFINED SYNTAX ELEMENTS

Predefined syntax elements (PSEs) are syntax elements defined for use
by
all
DCL
command
tables.
PSE names, by convention, are
distinguished from local category names by having a 11$11 as their first
character.
NOTE
If the syntax of a command does not match that of a
predefined syntax element, then the parse fails.
Several PSEs have two forms, one ending with an "Ell
and one not, such as $NOD and $NODE, $FIL and $FILE,
$DEV and $DEVE, and $UIC and $UICE. The form ending
in
Ell produces an error message before aborting the
parse. The shorter form does not.
Use the shorter
form when defining optional syntax.
II

following list briefly defines the PSEs.
Note that some PSEs
require arguments. Specify the required arguments in the order shown
and enclose the PSE and the arguments in angle brackets to identify
t:he PSE and arguments as one argument to the MACRO-II assembler.
1~he

12.11.1

Basic Data Types

The
use
t:he
by
and

following list of PSEs define basic data types in MML.
You can
them only in a PT. The parser copies to an IFORM character buffer
text in the input DCL command line that fits the structure defined
the PSE. The buffer is attached to the last queued mapping number
can be accessed by the translator for use in constructing the
E~qui valent MCR command line.
$NUM,Al,A2

Defines the structure or syntax of a numeric string
(0 through 9). The arguments Al and A2 designate the
minimum and maximum length, respectively,
for the
numeric string.
Additionally, the PSE allows an
optional decimal point on the end of the string. The
decimal point is not copied to the IFORM character
buffer.

12-40

THE DeL TASK

$DNUM,Al,A2

Defines the structure or syntax of a decimal numeric
string (O through 9).
The arguments Al and A2
designate
the
minimum
and
maximum
length,
respectively,
for· the numeric string. Additionally,
the PSE allows an optional decimal point on the end
of the string.
A decimal point is copied to the
IFORM character buffer whether or not it is specified
in the input DCL command line.

$ONUM,Al,A2

Defines the structure or syntax of an octal numeric
string (O through 7).
The arguments Al andA2
designate
the
minimum
and
maximum
length,
respectively, for the numeric string.

$WONUM,Al,A2

Defines the structure or syntax of $ONUM or the
wildcard character 11*"
The arguments Al and A2
designate
the
minimum
and
maximum
length,
respectively, for the numeric string.

$DONUM,.Al,A2[.]

Defines the structure or syntax of a decimal or octal
numeric string (O through 9). The arguments Al and
A2 designate the minimum
and
maximum
length,
respectively,
for the numeric string. Additionally,
the PSE allows an optional decimal point on the end
of the string.
A decimal point is copied to the
IFORM character buffer if either the input DCL
command line or the parsed string contains the
characters 8 or 9.

$WDONUM,Al,A2

Defines the structure or syntax of $DONUM or a "*"
character.
The arguments Al and A2 designate the
minimum and maximum length, respectively,
for the
numeric string.

$BNUM,Al,A2

Defines the structure or syntax of a binary numeric
string (O through 1).
The arguments Al and A2
designate
the
minimum
and
maximum
length,
respectively, for the numeric string.

$ALF,Al,A2

Defines the structure or syntax of an alphabetic
string (A through Z).
The arguments Al and A2
designate the minimum and maximum length for the
alphabetic string.

$ALFN,Al,A2

Defines the structure or syntax of an alphanumeric
string (O through 9 and/or A through Z).
The
arguments Al and A2 designate the minimum and maximum
length for the alphanumeric string.

$WALFN,Al,A2

Defines the structure or syntax of $ALFN with the
additional
characters:
"*"
and
"% " •
These
characters are used by some RSX-llM/M-PLUS utilities
as wildcard characters.
The arguments Al and A2
designate the minimum and maximum length for the
alphanumeric string.

$R50,Al,A2

Defines the structure or syntax of a Radix-50 string
( 0 through 9, A through Z,
"$ " , and" . " ) . The
arguments Al and A2 designate the minimum and maximum
length for the Radix-50 string.

12-41

THE DCL TASK

12.11.2

Common Command Elements

You can
The following PSEs define parts of the DCL command grammar.
use them only in a PT. The text (except for $DATE) parsed from the
input DCL command line that fits the structure defined by the PSE is
copied to an IFORM character buffer that is attached to the last
queued mapping number.
$FIL

Defines
the
structure
or
syntax
of
a
file
specification. Each element explicitly included in the
file specification sets a bit in the global bit-mask
words. These are:
device B28
UIC B29

filetype B3l
version B32

filename B30
These bits are also set
predefined syntax elements.

the

other

$FIL-based

$FILE

Defines the structure or syntax of $FIL. Additionally,
if the parser fails to process $FILE, the parser issues
an error message and aborts the parse.

$WFIL

Defines the structure or syntax of $FIL. Additionally,
the wildcard characters:
"*" and "%" are allowed as
part of the file specification.

$WFILE

Defines
the
structure
or
syntax
of
$WFIL.
Additionally,
if tr= parser fails to process $WFILE,
the parser issues an error message and aborts the
parse.

$NFIL

Defines the structure or syntax of $WFIL if preceded by
a DECnet node specification.

$NFILE

Defines
the
structure
or
syntax
of
$NFIL.
Additionally,
if the parser fails to process $NFILE,
the parser issues an error message and aborts the
parse.

$IFIL

Defines the structure or syntax of $FIL. Additionally,
the indirect file indicator "@" must prefix the file
specification.

$IFILE

Defines
the
structure
or
syntax
of
$IFIL.
Additionally,
if the parser fails to process $IFILE,
the parser issues an error message and aborts the
parse.

$NOD

Defines the structure or syntax of a DECnet
specification.

$NODE

Defines the structure or syntax of $NOD. Additionally,
if the parser fails to process $NODE, the parser issues
an error message and aborts the parse.

$DEV

Defines the structure
specification.

$DEVE

Defines the structure or syntax of $DEV. Additionally,
if the parser fails to process $DEVE, the parser issues
an error message and aborts the parse.

12-42

syntax

node

name

device

THE DCL TASK
$ODEV

Defines the structure or syntax of $DEV.
the character ":" is optional syntax.

$ODEVE

Defines
the
structure
or
syntax
of
$ODEV.
Additionally, if the parser fails to process $ODEVE,
the parser issues an error message and aborts the
parse.

$UIC

Defines the structure or syntax of a UFD specification.

$UICE

Defines the structure or syntax of $UIC. Additionally,
if the parser fails to process $UICE, the parser issues
an error message and aborts the parse.

$WUIC

Defines the structure or syntax of $UIC. Additionally,
the wildcard character "*" is allowed as part of the
UIC specification.

$WUICE

Defines
the
structure
or
syntax
of
$WUIC.
Additionally,
if the parser fails to process $WUICE,
the parser issues an error message and aborts the
parse.

$OUIC

Defines the structure or syntax of $UIC. Additionally,
the characters "[", "]", and "," are optional syntax.

$OUICE

Defines
the
structure
or
syntax
of
$OUIC.
Additionally, if the parser fails to process $OUICE,
the parser issues an error message and aborts the
parse.

$ DATE

Defines
the
structure
or
syntax
of
a
date
specification.
A date specification can take one of
two forms: mm/dd/yy or dd-rnrnrn-yy. $DATE produces the
following data structures in the IFORM queue: the day
is attached to secondary mapping number 210, the month
is attached to secondary mapping number 211, and the
year is attached to secondary mapping number 212.
The
output format is always dd-rnrnrn-yy (with the first three
characters of the month name spelled out) even if the
slash format (with the number of the month) is used.

$DATEI

For commands that require two dates (for example, SINCE
and THROUGH), a second PSE for dates, $DATEl, uses
secondary mapping numbers 213, 214, and 215 for the
day, month, and year respectively.
$DATEI is otherwise
identical to $DATE.

$TIME

Defines
the
specification.
hh:mm[:ss].

12.11.3

Additionally,

structure
or
syntax
of
a
time
The time specification is of the form

Special Parser Elements

You can specify the following PSEs only in a PT.
$ALL,la.bel

Defines the syntax or structure of an arbitrary string
of characters.
$ALL matches all characters in the
command line (left-to-right) until anyone of a set of
specified terminating characters is detected. The set
of terminating characters are specified with
the
TERMINATORS macro.
The label is a label on the

12-43

THE DeL TASK

TERMINATORS macro. The text parsed from the input DeL
command line that fits the structure defined by $ALL is
copied to an IFORM character buffer that is attached to
the last queued mapping number.
Here is an example of $ALL with the TERMINATORS macro:

AND. <$ALL,EXCEPT>

EXCEPT: TERMINATORS

III

'J $EOL

This example allows the "," the ")", and the "J" as
terminators,
in addition to the $EOL predefined syntax
element, discussed next.
$EOL

$EOL is used to parse end-of-line characters.
For
instance, in the previous example, a carriage-return or
escape would also be acceptable as a terminator.

$COP, 'lit

$COP does not define syntax. $COP instructs the parser
to copy the specified literal, 'lit, unconditionally to
an IFORM character buffer. The IFORM character buffer
is always attached to the last queued mapping number.

$DSB

$DSB (disable skip blanks) does not define syntax.
$DSB
instructs
the
parser not to skip blanks.
Normally, blanks are ignored. $DSB and $ESB must be in
the same syntax element, such as AND or OR, but need
not be on the same line.

$ESB

$ESB (enable skip blanks) does not define syntax. $ESB
restores the default state, which is to ignore blanks.
For example, a
blanks.
The
specification:

file specification cannot
following
could
define

$DSB $DEV $UIC <$ALFN,O,9> '.

<$ALFN,O,3> ';

include
file

<$ONUM,O,3> $ESB

(The actual file specification definition
complex. This is only an example.)

$DDR

$DDR does not define syntax.
$DDR instructs the parser
to
disable
delimiter
recognition.
Delimiter
recognition is enabled by default and instructs the
parser to ensure that all literal syntax elements have
delimiting characters terminating them.
$DDR must be
used on the same line with $EDR. See the next example.

$EDR

Enable delimiter
case.

recognition.

This

the

default

For example, the following line allows you to attach
the first one to three characters to one mapping number
while the remainder are attached to another.

12-44

THE DCL TASK
COMl:

AND $DDR <$R50,1,3 MAP=l> <$R50,O,7 MAP=2> $EDR
END

Notice that no delimiting character distinguishes the
two strings, and that the second string may be null.
$SEP

$SEP defines the colon (:) or equals (=).
These are
used as separators between qualifiers and arguments.

$OSEP

$OSEP defines an optional
equals, or null.

$CSEP

$CSEP is the same as $SEP, but
colon to the IFORM.

copies

$COSEP

$COSEP is the same as $OSEP, but additionally copies
colon to the IFORM whether anything is input or not.

$FSEP

$FSEP defines the comma (,)
specification separators.

$TERM

$TERM defines a terminal specification and copies it to
the IFORM.

$PROC

$PROC defines· a processor name for the Queue Manager as
either a device name followed by a colon or six
Radix-50 characters followed by a colon.

$PRONC

$PRONC defines a processor name for the Queue Manager
as a device name followed by a colon or six Radix-50
characters not followed by a colon.

12.11.4

separator,

that

additionally

and

plus

(+)

colon,

file

Special Translator Elements

You can specify the following PSEs only in a TT.
$ NEW

Used to indicate the start of an additional MCR command
line.
$NEW instructs the dispatcher subprocess of the
DCL task that there are mUltiple MCR commands that must
be dispatched serially.

$RESET

Used to reset the IFORM queue.
Resetting the IFORM
queue allows all used mapping numbers to be reused.
$RESET is designed to be used with $NEW to define
multiple MCR commands.

$FNAM

Used to specify that only the file name in a file
specification is to be copied to the MCR command line
buffer as a result of unmapping a
mapped
file
specification.

$SY

Converts the assigned device for SY:
to ASCII and
appends it to the MCR command line; for example, DB2:.

$TI

Converts the assigned terminal device for TI: to ASCII
and appends it to the MCR command line; for example,
TT15:.

12-45

THE DeL TASK

$CUIC

Converts the current UIC for the user to ASCII and
appends it to the MCR command line: for example,
[301,l13J.

$LUIC

Converts the login UIC for the user
appends it to the MCR command line.

12.11.5

ASCII

and

Program Control Elements

You can specify the following PSEs in either a PT or a TT.
$JSR,A

A special category used to gain control of the CPU.
The argument A must be the label of a MACRO-II
subroutine.
To
indicate
failure,
the
MACRO-II
subroutine should (on return) set the carry bit to
indicate failure and clear it to indicate success.
Remember,
the routine must be in the blank program
section.

$TST

$TST is used to test if a mapping number is in the
IFORM queue.
A MAP attribute specifies the mapping
number. $TST succeeds only if the mapping number is in
the IFORM queue: for example, ($TST MAP=l>.

$TSTNOT

$TSTNOT is used to test if a mapping number is not in
the IFORM queue. A MAP attribute specifies the mapping
number. $TSTNOT succeeds only if the mapping number is
not in the IFORM queue. The syntax is identical to
$TST.

$LOAD,name

$LOAD is used to load an overlay from a parser or
translator table.
The argument name specifies the
name of the overlay as specified in the overlay
description file.
II

$CALLOV,name

$CALLOV is used to load and activate part of either a
parser or translator table.
The starting address
within the overlay must be contained in the first word
of the overlay. Use .WORD to specify the address. On
return, the previous overlay is loaded.
The argument
name
specifies the name of the overlay as specified
in the overlay description file.
II

$NULL

$NULL is used to execute attributes without specifying
a syntax element.
$NULL succeeds if the attributes
succeed.

$AB

$AB (angle bracket) is equivalent to the literal 11(11
and is used to pass the 11(11 as an argument to MACRO-II.

$BA

$BA is equivalent to the literal ">11 and
pass the 11>11 as an argument to MACRO-II.

12-46

used

THE DCL TASK

12.11.6

Example from DCL Command Tables
• TITI.. F.
.IDfNT
.PSECT
.ENABl

ASSIGN
/00/

.CDEF
I.. C

THIS SOFTWARE IS FURNISHfD UNDfR A LICENSE AND MAY
BE USED OR COPIF.D ONLY IN ACCORDANCE WITH THE TERMS
OF SUCH LICENSE.
COPYRIGHT (c) 1981 BY DIGITAL EQUIPMFNT CORPORATION.
ALL RIGHTS RESERVED.
AUTHor~

J.M. SALMAN

DATE:

07-0CT-80

MODIFIED:

DATE

ABSTRACT

FUNCTION:
TRANSl.ATE THf DCI.. COMMANDS 'ASSIGN', 'ASSIGN/QUFUE', 'ASSIGN/RFDIRFCT',
'ASSIGN/TASK' TO THE SF.MANTICALLY EQUIVAI..F.NT MCR COMMANDS 'ASN', 'QUE',
'F<ED', 'REA'.
THE FOLLOWING TABl.E DFFINFS THF MAPPING OF THE DCl. TO MCR SYNTAX:
Del.. SYNTAX ELEMENT

MCR SYNTAX ELEMFNT

MAPPING l..fTTER/NlIMBFR

<GuelJE'name>

F' ':)

<olddf.'vice>
<nl?wdevice>

<o]ddE'vicE':>
<nl?wdevice>

F'4

<tasv.,nalTle>
<devlce>
<lun>

<dp.vice>

P6
P7

<dev:i.ce>

<ll..ln>

.
/GL..OBAL..
/LOGIN
/TERMINAl=<terlTldE'v>
<1(J~ .!lc?'1.r.18vic(~>

/GBl.
II.OGIN
ITFRM:::<te T'lTIdev>

P8.
P9.

Pl.O.
Pli.

P1:?

.PAGE
AS!3IGN::

() r,

END
QUEUE:

AND
.; Nn •
END

' I <'QUFUE,1> <$PRONC MAP=l. PRO=$QNMSG
<$ F' ROC t1 (i P:::: 2 PRO = $ F' R11 S G FF: R:: $ I PM S G>

REDIR:

AND

FRR~$BQMSG>

<'REDIRECT,l> <$ODEVE MAP=3 F'RO=$FRMSG>

END
Tr~SI<:

(~ND

ANti.
AND.
END

II <'TASI<,2> SOSEP <$R50 1,6 MAP=5 PRO~$TI<MSG FRR=$JTMSG>
<$OtlFVE MAP~6 F'RO=$tlVMSG
<$flNl..IM, 1. ,:7; MAp:::? F'FW::::$L U SG FRf.:=$NEMSG>

12-47

THE DCL TASK

.TITI..E
.IDENT

ASSIGN
/00/
THE ncL. TASK

LOGDEV: AND
END
QUAL.:
OR
OR.
OR.
Ol~ •

or< •

($ODEVF MAP=8. PRO=$DVMRA) ($ODFVE MAP=9.

PRO~$I_DMSG)

('GL.OBAL,1 MAP=jO. CBM=Bl!B?)
('L,OCAL,3 CBM';:;Bl>
('L.OGIN,3 MAP=jl. CBM=B1>
('SYSTEM,1 MAP=10. CBM=B1!B2>
($TERM MAP=12. CBM=B2)

END
.PAGE
MCRASN::

or<

(QUE BST=Bl> (RED BST=B?) (RFA BST=B1) (ASN BST=B4>

END

QUE:

AND
END

«'QUE

RED:

AND
END

«'RED // (MAP=4> ,- (MAP=3>

REA:

AND
END

«'REA

» (MAP=5> « '

ASN:

AND
END

« ' ASN

» <MAP=8.:> , . - <MAP:::9. > <!1UA:.::l Al.IQ>

L.AUQ:

Of.:

('GBL MAP=10.)
<'LOGIN MAP~tl+)
('TERM= AND:.::VTFRM)

OR.

oF< •
IJTFRM:
SBOMSG:
SDVMSG:
SFRMSG:
SIPMSG:
SI1MSG:
'LDMSG:
SLUMSG:
SPRMSG:
SQNMSG:
'TKMSa:
$TOMSG:

(MAP=?) 'lAS: (MAP=l)

(MAP=7) //' "

END
<MAp::::l2 +:>
AND
END
.ENABL.E L.C
ERROR
</Illegal Queue name/>
PROMPT </Device? I>
PROMPT <IF rom? I:>
ERROR
</Illeg~l processor name/)
ERROR
(/Il]e~a]
task name/>
PROMPT </Lo~ical devi e? /~.
PROMPT (/Lo~ical unit I )
PROMPT (/Process r? I
PROMPT (/Queup?
PROMPT (/Task? I
PROMPT </Tu? I:>
• D:::;ABI.F. LC
.END

12-48

(MAP=6>

QUA=QUAL

CHAPTER 13
POOL MONITORING SUPPORT

Pool monitoring support controls the use of the system's dynamic
storage region (pool). This support monitors pool levels, restricts
use, and notifies you when pool is near depletion.
This support
consists of two parts:
the RSX-llM/M-PLUS Executive pool monitor
code, and the privileged Pool Monitor Task (PMT).
Pool monitoring support is not available on unmapped systems.

13.1

HOW YOU GET POOL MONITORING SUPPORT

On RSX-llM systems, you receive pool monitoring support when you
select the pool monitoring support option in system generation
(SYSGEN). If you select the option, you receive the Executive pool
monitor code and SYSGEN assembles and task-builds PMT. If you do not
select the option, you do not receive any pool monitoring support.
On RSX-llM-PLUS systems, pool monitoring support, including the
Executive pool monit.or code and PMT, is included by default. SYSGEN
establishes the support for you.. You need not select any option for
. it.
One of PMT's features is that it responds to extreme fragmentation.
Due to the seriousness of this pool problem, PMT requires your
interaction to aid in system recovery. Therefore, if you select pool
monitoring support, you must be prepared to respond to PMT's prompts
(see Section 13.3.4).

13.2

THE EXECUTIVE POOL MONITOR CODE

The pool monitor code within the Executive monitors the amount of free
pool and detects major pool events. When a major pool event occurs,
the Executive notifies PMT of the event and of the current condition
of pool.

13.2.1

Pool Events Affecting the Executive

The Ex€!cutive pool monitor code responds to three major pool events.
One is classified as a high pool event and two are classified as low
pool events. The occurrence of these events directly affects the
condition of pool, creating either a high or low pool condition. The
Executive responds by notifying PMT of the pool event and the
resultant pool condition and also activates PMT. Any further response
to the pool condition is left to PMT.

13-1

POOL MONITORING SUPPORT
13.2.1.1
event:
•

High Pool Event - The following is the
The attainment of a
condition.

This event occurs when a
relinquishes enough pool
above the high limit.

high

pool

condition

possible
from

high

pool

low

pool

system that has a low pool condition
to cause the amount of free pool to rise

The high pool limit is set using the MCR and VMR SET jPLCTL
See Section 13.4 for further discussion of the high limit.

command.

13.2.1.2
events:

low

Low Pool Event - The following are

the

possible

•

The degradation of pool from a high pool condition
pool condition

•

A pool allocation failure

pool
low

The degradation of pool occurs when the total amount of free pool has
fallen below the low limit. A pool allocation failure occurs when the
largest pool fragment is too small for the process requesting it.
A
pool allocation failure is not to be confused with future discussions
in this chapter of pool fragmentation.
Pool allocation failures and
pool fragmentation are, in the context of this chapter, different pool
problems and are, therefore, discussed separately. See Section 13.3.1
for additional information on pool fragmentation.
The low pool limit is set using the MCR and VMR SET jPLCTL
See Section 13.4 for further discussion of the low limit.

command.

13.2.1.3 Pool Monitoring Interface - The mechanism used by
the
Executive to detect pool events is called the pool monitor interface.
The details of how this interface works are beyond the scope of this
manual.
However,
it is fully described in the source code for the
Executive module CORAL.MAC. CORAL.MAC is in [ll,lOJ on your kit.
In
summary, the interface functions as follows:
•

Provides the Executive with the ability to declare information
to a pool monitor task.

•

Provides the Executive with the capability to receive a
response or acknowledgement from a pool monitor task.
(An
acknowledgement can be used by the Executive to control
further information declarations.)

13.2.2

Pool Conditions

The condition of pool is directly related to major pool events and
also to the acceptable high and low pool limits you specify.
(You set
and manipulate these limits using either the MCR or VMR SET jPLCTL
command described in Section 13.4). When a major pool event occurs
and causes the size of free pool to cross the low or high limit, a new
pool condition exists. The possible pool conditions are low pool and
high pool.

13-2

POOL MONITORING SUPPORT
A high pool condition exists when the amount of free pool
sufficient to support current and less demanding system workloads.

A low pool condition exists when the amount of free pool is nearing
the point where system performance will degrade seriously if the
system's workload increases.
Major pool events cause either a high or low pool condition to exist.
In turn,
a high or low pool condition, combined with a specific pool
fragmentation level, creates either a high or low pool state.
Pool
states are discussed in Section 13.3.

13.3

THE POOL MONITOR TASK

The Pool Monitor Task (PMT) is task built and installed during the
SYSGEN procedure. Whenever the resultant system is bootstrapped, PMT
is activated by the Executive.
(If you do not wish to use the DIGITAL-supplied Pool Monitor Task, you
do have the option to write and run your own pool monitor task.
If
you wish to write your own pool monitor task, you should first be
familiar with the Executive pool monitor interface. The interface is
documented in the Executive module [ll,lO]CORAL.MAC. A task, with the
task
name "PMT ... ",
installed on a system that supports pool
monitoring, is considered to be a "pool monitor task".)
PMT's first responsibility is to monitor pool conditions.
The
conditions that PMT responds to include those detected and reported by
the Executive (see Section 13.2). PMT's second responsibility is to
monitor pool fragmentation. Through this monitoring, PMT can respond
to another major pool event and also react to
extreme
pool
fragmentation.
The other major pool event (not reported by the
Executive) occurs when PMT detects that the largest free pool fragment
is less than the minimum required fragment size.
(See Section 13.3.4
for further discussion of extreme fragmentation.)
Once it: has been activated by the Executive, PMT basically operates in
a cycle.
PMT determines the size of the largest pool fragment
whenever it receives the Executive's notification of a pool condition,
or at least at regular time intervals.
It then compares this size to
the minimum required fragment size. Based on the Executive's report
on the current pool condition and what PMT detects when monitoring
fragmentation, PMT determines what the current state of pool is and
responds to it accordingly.
The minimum required fragment size is set using the MCR and VMR SET
/PLCTL command.
See Section 13.4 for further discussion of the
minimum required fragment size.

13.3.1

Conditions Affecting PMT

PMT responds to pool fragmentation and to pool conditions; however,
the
response varies depending upon the current level of pool
fragmentation. The two levels that influence PMT's response are as
follows:
1.

If the largest fragment is equal to or greater than the
minimum required fragment S1ze,
PMT then acts only on the
condition of pool as reported by the Executive.

13-3

POOL MONITORING SUPPORT
2.

If the largest fragment becomes smaller than the minimum
required fragment size, PMT considers this to be a low pool
event.
If the system is not already in a low pool state,
this event causes a transition to that state. PMT then
responds accordingly.

Pllthough extreme fragmentation is another pool event that PMT responds
to,
it is different from those previously described.
It is defined
and documented in Section 13.3.4.
PMT uses the information it has concerning the current level of
fragmentation and also the information provided by the Executive to
determine the overall state of pool. Following is a discussion of
PMT's response to specific pool events and conditions.

13.3.1.1 Pool
Level and
Fragment
Size Are Satisfactory - The
Executive notifies PMT that the pool level is above the high limit and
PMT detects that fragment size is greater than the minimum required
fragment size.
PMT concludes that a high pool state exists and executes
appropriate for a high pool state (see Section 13.3.2).

actions

13.3.1.2 Low Pool Condition - The Executive notifies PMT that
pool condition is achieved.

low

PMT determines whether the change in pool reported by the Executive is
temporary.
The change is temporary if, by the time PMT responds to
the Executive's notification, enough free pool has accumulated to push
t:he total above the high limit.
If the change is temporary, PMT
ignores the notification and continues to execute high pool state
actions.
If the change is not temporary, PMT concludes that a low
pool state exists and executes actions appropriate for a low pool
state (see Section 13.3.3).

13.3.1.3 High Pool Condition - The Executive notifies PMT that a high
pool condition is achieved.
PMT determines whether the change in pool reported by the Executive is
t:emporary.
The change is temporary if, by the time PMT responds to
the Executive's notification, the total amount of free pool has moved
below the high limit.
If the change is temporary, PMT ignores the
notification and continues to execute low pool state actions. If the
change is not temporary, PMT initiates actions appropriate for a high
pool state (see Section 13.3.2).

13.3.1.4 Largest Pool Fragment Is Too Small - PMT detects that the
largest pool fragment is smaller than the minimum required fragment
size.
PMT concludes that a low pool state exists and executes actions for a
low pool state.
Note that this low pool state overrides any pool
conditions reported by the Executive. This pool event will cause the
system to be in a low pool state even if the Executive reports a high
pool condition.

13-4

POOL MONITORING SUPPORT
13.3.1 .. 5
size of
requirE~d

Largest Pool Fragment Becomes Larger - PMT detects that the
the largest pool fragment has become larger than the minimum
fragment size.

PMT decides that the current pool state must be based on the latest
pool condition reported by the Executive.
If the Executive reported a
high pool condition, PMT decides that a high pool state exists.
If
the Executive reported a low pool condition, PMT decides that a low
pool st:ate exists. In either situation, PMT takes the appropriate
action for that state.

13.3.2

PMT Default Actions for a High Pool State

When PMT concludes that a high pool
following actions:

state

exists,

Sets its internal cycle interval to 1 minute

Enables checkpointing for itself

3..

Removes any pool use controls

executes

the

PMT then stops itself so that its impact on system resources is
minimized.
PMT unstops itself when the internal cycle interval has
elapsed.

13.3.3

PMT Default Actions for a

Lo~

When PMT concludes that a low . pool
following actions:

Pool State
state

exists,

1..

Disables checkpointing for itself.

2..

Sets its internal cycle interval to 20 seconds.

Establishes pool use controls as follows:

executes

Prevents nonprivileged users from logging in.

Suppresses INSTALL/RUN/REMOVE sequences on
terminals.

Delays nonprivileged task loading.

nonprivileged

NOTE
Nonprivileged tasks with a task priority less
than the specified base priority cannot compete
for memory resources until a high pool state
exists (see Section 13.4.3). This does not mean
that such tasks cannot be requested; they will
simply remain blocked from execution until PMT
concludes that a high pool state exists.
All
other tasks,
including any tasks already active
at the onset of the low pool state, are not
affected by this control.

13-5

the

POOL MONITORING SUPPORT
d.

Sends a warning message to all logged-in terminals (or
on-line
terminals
on
systems
without
multiuser
protection). This message cannot be suppressed by the
MCR SET /NOBRO command or the DCL SET TERM /NOBROADCAST
command.

Sends a warning message to and displays
at the console terminal.

pool

statistics

13.3.3.1 PMT Output to Terminals During Low Pool State - When PMT
determines that a low pool state exists, PMT sends the following
warning message to logged-in terminals (or on-line terminals on
systems without multiuser protection):
08-AUG-85 13:35:10 -- low pool -- Please exit

~rtive

t~sks

- 7FPHYR

The effectiveness of this message depends on whether users exit from
their active tasks. If they choose to ignore this message, a low pool
state continues to exist.
ZEPHYR is the system name selected during SYSGEN or
name (if DECnet is running on your system).

the

DECnet

node

PMT sends this message at 20-second intervals until it concludes
a high pool state exists.

that

13.3.3.2 PMT Output to the Console Terminal During Low Pool State In a low pool state, PMT also sends a warning message to and displays
pool statistics at the console terminal.
The following is an
annotated example of PMT output to the console terminal:
08-AUG-85 1.3:35:1.0 -- Warning
Total free pool = 1116. bytes
LaT''i.fest fragment - :1.1."2. b~~tF.·~s

In this example, PMT:

•
•

••

Pool. is

l.ow

Sends a warning message
Displays the amount of free pool existing at
the low pool state

the

Displays the size of the largest free fragment
existing at the onset of the low pool state

PMT broadcasts this message at 20-second
concludes that a high pool state exists.

13.3.4

criti.r.all~

time

intervals

onset

pool

until

PMT Default Actions for Extreme Fragmentation

Extreme fragmentation exists whnn the largest pool fragment is less
thqn 84(decimal) bytes. In this case, pool is exhausted and it is not
possible to free any pool by unsolicited terminal input, for example,
i.ssuing an ABORT command. At this point, PMT takes immediate action
to prevent total pool depletion by executing the following steps:
1.

Enters kernel mode, which prevents any other tasks from
executing but does allow the system to respond to device
interrupts.

13-6

POOL MONITORING SUPPORT
2.

Prevents the invocation of TKTN.
(Invoking TKTN at this time
depletes the available pool.) It does this by clearing TKTN's
special TCB pointer that is stored within the Executive.

Sends a warning message to the console terminal.

Prompts you to abort one or more of the tasks displayed.
(You must be at the console to free pool in response to the
PMT prompts.) After you select a task to abort, PMT returns
to user mode until the abort operation is finished.

Displays a message at the terminal running the task and
console terminal if the task is successfully aborted.

Displays (upon request) an updated list of abortable tasks at
the console terminal.

(On RSX-IIM systems 84(decimal) bytes is the size
buffer. )

eLI

the

command

13.3.4.1 Abortable Tasks - The abortable task list includes only
those t.asks that PMT considers eligible to abort. A task is abortable
if it meets the following requirements:

• It must be active.
• It must be resident in memory.
• It cannot be privileged and running from the console terminal.
• It cannot be a Command Line Interpreter (CLI) task.
• It cannot be an Ancillary Control Processor (ACP) task.
• It cannot be the task loader.
•

It cannot have any internal conditions that prevent it from
exiting upon an abort request (for example, it is already
aborted) .

The ability to abort tasks included in this list is a powerful feature
and one that is potentially harmful to your system. You should abort
tasks that consume pool and are relatively expendable.
This action
should release pool resources for use by the remaining active tasks
and allow the system to continue operation, rather than deadlock over
pool re!sources.
It is important that you use discretion when selecting tasks to abort.
Aborting certain tasks could render all or part of the application
unusable. You can abort certain ·tasks (for example, PIP or MAC) and
experience relatively few side effects.
As an added measure of
protection for your system, PMT does not, by default, include in the
abortable task list the privileged tasks running from the console
terminal. Therefore, if it is possible, you should run the privileged
tasks that you do not want considered abortable (by PMT) from the
console terminal.

13-7

POOL MONITORING SUPPORT
13.3.4.2 PMT Messages - When extreme pool fragmentation occurs, PMT
displays a message in the following format and a list of abortable
t:asks at the console terminal:
dd-mrnrn-yy hh:rnrn:ss -- Warning -- Free pool exhausted
Abortable tasks in memory:
tttttt

I/O=xxx.

ttnn:

'Iihere:
tttttt

The name of the abortable task

The indicator that the task is privileged (a blank means
that it is nonprivileged)

xxx

The total outstanding I/O count for the task

ttnn

The terminal where the task is running from

PMT lists the tasks in order of decreasing
display the priority of individual tasks.

but

does

not

the

list

If the task you specify is not installed or not on the
abortable tasks, PMT displays one of the following messages:

list

PMT then prompts you to select one of
follows:
En t p r

i:':

T :::: <:; i-. n (.I t

t ;,,, ~:; 1-:1.'. 0

",; i" 0 ("" t,

(I J"'

"i. n ,c.. t .:;:: 1 l P 1\ fl'. ,. ':;i

the
F~ F T U F: hi

P (" F' <c.. ':;:,

priority
tasks

from

t c)

I?:' ;< :i t

a <:i .ci "i. n ;

PMT displays the list of abortable tasks if you press LINE FEED in
response to either prompt.
If you press RETURN, PMT relinquishes
control of the system, by returning to user mode, for at least seven
seconds, giving the system an opportunity to recover from the low pool
state unassisted.
If PMT is not able to abort the task you specify and the task is
listed as abortable, PMT displays the following message (this occurs
only if the task exits before PMT is able to abort it):

If PMT successfully aborts the task, it sends the following message to
the console terminal:

Also, if the task was not running
displays the following messages
running from:

ofl···· tt l.J C1 ... :~ '5 1:3! ~~; t:) : 3 0 -- "tt. tttt"

from the console terminal, PMT
at the terminal where the task is

IN ;:1 r n :i n ~.~ -- -

Fr PP

F·' (~ C1 1

p >~ h .;3 U ;:-. t p d

el)nrtf.-~d

PMT then sends the following message to the console terminal:
Press lTNF FEED for an updated task list,
L a <:; k t, C) ;:; b (J r t, 0 r' P r 17: <;=, ~::. RET I JF: N toe ;.: :i. t :

e n l, ':.' 'i' a

13-8

POOL MONITORING SUPPORT
13.3.4.3 Annotated Example of PMT Output for Extreme FragmentationAn annotated example of PMT output for extreme fragmentation is shown
in the following example. The numbers in the example correspond to
the numbered items in the list that follows Example 13-1.
Example 13-1

PMT Output for Extreme Fragmentation

8 ::: C:l UG:: 8 5 1 3 .:.4 2 .!. 2 3 -:; -::. II.! a r [:1 i n ::.{ =- :: E .r.: e e

Bb 0 :r tab 1 e t a s k s i 0
RIHIEMO

1/0;:::

0 .•

F'
E'

liD=.

o.t.
1...

M'~II20

I LO:::
1/0::;:
I/O::::

JEST
E:IPT21

I10~~

M'~CI47

110::::

110:~:

IIIf~ ffi 0 l~ ~ .:.

COI .•.t .t
AI ... T30
[DIT14

e ~~ b a us ted

2 0 ell

IIO.!,
110.:.
1130.:.
111:4.:.
1120.:.

Lt.

1 ...
0 ...
1 ..
1.•.

COOt

1121.:.
I I:4Z .!.

[nter a task io abort.:. 01~ f::.r:ess F.~EIUf~N to e::~it.: Plf'T21

.~. E: I P T 21.~ abo J' ted

P£ess LINE fEED for an uedaied task lisiL
enter. a task to abort.l.

O.T::

F::r-:ess RETUrW to e;:att

(HHH'table tasks in llIeIIlOJ·~':.
EH1DEMO

cnr .......

AL~ T30
ElJII14

F.'
P
P

M(;~II20

I/O=.

O.t.

l/O:~:

o.t.

I/O;:::
liD::::

1 ..
1.•.
1 ...

I!O:~:

lEST

110:::

Mt~ICT47

110::::

110':'
110.:.
1130.:.
1I1:~.!.

1:I2D.:.

0 ...
1.•.

Et::J t 12 r a t ask t a abo .r t .1.

COO.!.

IL12.!.
0 1~

tI~ a;3aiCl.!

.~'.[DIT14.~

f~es~

REI UE~ N toe ;:l it.:. E It T

E I: e s s

L~sk [~Oi insialled.,

aborted

EItIT14

LINE ([ED for an u2daied task list.:.

e n t era :I:. ask t 0

abo .r: :L .,.

0 1::

c! r' e S 5

REI UF; N t u [ Y. I 1.:'

illD)

In this example, PMT:

t»

Sends a warning message to logged-in terminals (or on-line
terminals
if
the
system does not support multiuser
protection) .
Displays 'the
terminal.

list

abortable

tasks

the

Prompts for a task to abort (PIPT2l is entered).

Aborts "PIPT21".

console

Prompts for an updated task list, a task to abort, or an
exit.
(A LINE FEED is entered for an updated task list.)

13-9

POOL MONITORING SUPPORT

Displays the list of abortable tasks.

Prompts for a task to abort (EDT is entered).

o
CD
CD

13.3.5

Indicates that a task with the name "EDT" is not installed,
and requests that you try again (EDIT14 is entered).
Aborts "EDIT14".
Prompts for an updated task list, a task to abort,
exit.
(The RETURN key is pressed for an exit.)

PMT Task-Build Options

You can modify PMTls response to pool conditions by editing PMTls
task-build file PMTBLD.CMD and task building PMT again.
If you wish
to modify PMT, you must do the following:
1.

Remove PMT (the task name is PMT ... ) by using VMR

Edit the task-build file

Task build PMT again

Install the modified task image by using VMR

When the system is rebooted, the new PMT task will begin executing.
If, however, you want the modified task image to run immediately, you
must first abort PMT before you remove and reinstall it using MCR or
DCL.
You can modify the following PMT features:
•

Timing control

•

Actions

•

Pool use controls

The specifics of modifying PMTBLD.CMD are documented in the file
itself.
Following is a discussion of the PMT features that you can
modify.

13.3.5.1 Controlling PMT Timing - PMT basically operates in a cycle.
It becomes unstopped at regular intervals to monitor fragmentation and
then stops itself. When the Executive interrupts the cycle to report
a new pool event, PMT resets the cycle to begin at the point at which
it was interrupted.
PMTls cycle can have one of two possible time lengths.
The length
depends on the current state of pool.
If a low pool state exists, the
cycle is 20 seconds long (plus the time PMT requires to execute all
low pool state actions).
If a high pool state exists, the cycle is 60
seconds long (plus the time PMT requires to execute all high pool
state actions).
You can modify PMTls cycle; however, the only modification allowed is
lengthening the high pool state cycle. The 60-second value is not
only the default value but also the minimum value that you can
specify.
If you lengthen the cycle, PMT may not be as effective at

13-10

POOL MONITORING SUPPORT

monitoring pool fragmentation problems. You can partially compensate
for this, by using the SET /PLCTL command (see Section 13.4.2) to
increase the minimum size of the largest pool fragment parameter.
This ensures that PMT will detect imminent pool fragmentation problems
earlier.

13.3.5 .. 2 Controlling PMT Action - You can modify some of the actions
that PMT executes during the cycle. The actions are as follows:

•

Sending warning messages to logged-in terminals (or on-line
terminals on systems that do not support multiuser protection)

•

Forcibly checkpointing stopped tasks in memory

•

Aborting certain privileged tasks

When a low pool state exists, PMT sends warning messages to logged-in
terminals (or on-line terminals on systems that do not support
multiuser protection). You can suppress this action by modifying
PMTBLD.CMD and task building PMT again.
When a low pool state exists, PMT requests the Executive to forcibly
checkpoint all memory-resident stopped tasks without outstanding
nonbuffered I/O. These tasks include CLI tasks, ACP tasks, and tasks
with outstanding buffered I/O, only if they are stopped during a low
pool state. When the Executive checkpoints a task, it deallocates the
task header, thereby reducing fragmentation.
You can modify PMTBLD.CMD to enable such checkpointing for a high pool
state as well.
This reduces the effect of long-term fragmentation,
making it more likely that a long-lived data structure will be
allocated
to a lower address within pool.
This clusters the
long-lived data structures together, leaving larger blocks of free
pool available for more dynamic types of allocation. Although this
can increase the effective use of available pool space, it also causes
a noticeable increase in disk I/O as tasks are checkpointed. CLI
tasks, ACP tasks, and tasks with outstanding buffered I/O are exempt
from checkpointing while a high pool state exists.
The renlaining option concerns PMT's list of abortable tasks.
During
extreme fragmentation,
PMT displays a list of abortable tasks and
prompts for tasks to abort. By default, PMT does not list or abort
privilE!ged tasks running from the console terminal. You can override
this dE!fault by modifying PMTBLD.CMD. There are, however, exceptions
to this option. These exceptions, CLI tasks, ACP tasks, and the task
loader~ are never listed by PMT as abortable tasks.

13.3.5 .. 3 Controlling Pool Use - When a low pool state is in effect,
PMT executes the default pool use controls described in Section
13.3.3.,
You can suppress any of these controls by
modifying
PMTBLD . CMD and task building PMT again.

13.3.6

Aborting PMT

If you wish to terminate PMT, you can easily abort it.
one of the following to abort PMT:
•

Issue an ABORT command from a privileged terminal

•

Issue an Abort directive from a privileged task
13-11

You

must

POOL MONITORING SUPPORT
When you select either of these methods. PMT
actions before it exits:

performs

the

following

•

Restores TKTN's special TCB pointer if PMT previously cleared
the pointer and TKTN is still installed (see Section 13.3.4).
This restores normal TKTN operations.

•

Prevents the Executive's pool monitor code from requesting PMT
after PMT exits.
This is done by clearing the special TCB
pointer for PMT ... as set by MCR INSTALL,
DCL INSTALL, and
VMR INSTALL commands.

•

Cancels any outstanding pool use controls
imposed because of a low pool state.

•

Displays the following message at the console terminal:

that

may

have

• Pl"iT • • • • .,:lhortp(\

This indicates that PMT's spec1al TCB pointer has been cleared
so that the Executive can no longer request PMT to run. To
restore the pointer, you must remove and reinstall PMT using
MCR or DCL.

13.4

THE SET /PLCTL COMMAND

The SET /PLCTL command sets the pool limit parameters used by the
Executive pool monitor code and PMT. The syntax, parameters, and
parameter limits for the command are discussed in Chapter 10 and also
in the RSX-llM/M-PLUS MCR Operations Manual. Basic guidelines for
setting the four command parameters are discussed in the following
subsections.
During a low pool state, you can compare the values you set and the
information that is output to the console terminal (see Section
13.3.3.2) to determine whether the parameters
require
further
modification.

13.4.1

Low and High Pool Limits

The first two parameters of the SET /PLCTL command establish the low
and high pool limits.
The Executive pool monitor code uses these
limits to determine when major pool events occur.
In general, you should set the low limit value to the least desirable
pool level.
This is a limit where your system's workload cannot
increase without the risk of a pool resource
deadlock.
The
appropriate value for this limit varies with each system. You can
determine the best value by experimenting with various limits.
The
low limit defaults to 600(decimal) bytes.
Set the high limit value to reflect the type of use your system
receives.
The high limit parameter essentially controls the point
where a low pool state is transformed into a high pool state.
The
high limit defaults to l600(decimal) bytes.

13-12

POOL MONITORING SUPPORT
If pool use fluctuates considerably, a limit set relatively higher
than the low limit will tend to reduce the number of pool state
transit.ions.
If pool use is typically constant, a high limit set
close to the low limit will quickly show critical changes in the pool
state. Since pool needs and use vary, you should experiment with this
paramet~er to determine the optimum value.

13.4.2

Pool Fragment Size

This parameter establishes the minimum size of the largest pool
fragment.
PMT uses this limit to determine when pool fragmentation
problems exist. When the largest pool fragment is the minimum size or
greater, a high pool state exists -- as far as fragmentation is
concerned. A low pool state exists when the largest pool fragment is
smaller than the minimum size. The lowest permissible size of the
largest pool fragment is 200(decim~1) bytes by default.
You should
experiment with this parameter to judge the optimum value.
Fragmentation is one of the more frequent and less desirable pool
problems.
Thus, the value that you specify for this parameter can
have an immediate impact on successful pool monitoring.

13.4.3

Base Priority for Nonprivileged Tasks

This parameter establishes the base priority for nonprivileged tasks.
The optimum value of this parameter is application specific, but
default~s to 51(decimal).
During a low pool state, PMT uses this
paramet.er
to restrict newly requested nonprivileged tasks from
competi.ng for memory resources (see Section 13.3.3). Only those tasks
with aL priority less than the specified base priority are so
restricted.

13-13

CHAPTER 14
THE SHUFFLER

The Shuffler (SHF) is a privileged task designed to compact space in
system-·controlled partitions when a memory allocation failure occurs.
The Shuffler operates only within system-controlled partitions and is
available for the RSX-IIM/M-PLUS operating systems, but is not
available for unmapped systems or for RSX-IIS.
This chapter describes Shuffler interaction with the operating system.
Briefly, it describes system-controlled partitions. In more detail,
it describes Shuffler structure, ways to monitor the Shuffler, and
Shuffler algorithms for the operating system.

14.1

EXECUTIVE AND MEMORY USAGE

Memory is the processor storage medium in which the Executive and
tasks reside when executing.
The Executive is the kernel of the
operating system that interfaces the hardware system with other
components of the operating system and with the user.
The Ex€!cutive brings a task into memory for execution and places the
task in competition with other active tasks. When tasks are brought
into memory, they are placed in a section of memory called a
partition.
Partitions are contiguous areas of memory in which
executa.ble tasks run i however, a common partition may be defined that
contains only data or code.

RSX-llM-PI.tUS· .supports only syst.ern-controlled p-.X'tit.ion.s.
RSX-llM supports three types of partitions:
1.

System-cont.rolled partitions

User-controlled partitions

Common partitions

User-controlled partitions and system-controlled partitions are used
to load waiting tasks. User-controlled partitions accommodate only
one task at a time. If you want to run multiple tasks within a
user-controlled part.ition, you must define multiple subpartitions.
System-controlled partitions accommodate as many tasks as possible at
any
Cine
time.
The
Executive
allocates available space in
system-·controlled partitions and creates the dynamic subpartition for
each ta.sk.

On RSX-lIM-PLUS, tasks,devicedri'Vers,.dynamic common :regions, and
static common regions reside in subpartiti()nso:f the system-controlled

14-1

THE SHUFFLER
partition. Static common regions are resident libraries and resident
commons and both may be shared by tasks for more efficient use of
physical memory.
Resident libraries contain code, and resident
commons contain data.
On RSX-llM, static common regions must be loaded into
common
partitions. A common partition is a dedicated area of memory that may
be shared by tasks. Tasks, device drivers, and dynamic common regions
created
by
memory
management directives must be loaded into
subpartitions of the system-controlled partition.

14.1.1

System-Controlled Partitions

Only mapped systems support system-controlled partitions.
A mapped
system is a system with memory management. A task in a mapped system
can run in any system-controlled partition large enough to contain it,
and the Executive is responsible for allocating space in that
partition. Refer to the RSX-llM/M-PLUS MCR Operations Reference
Manual for detailed information on system-controlled partitions and
memory management.
The Executive allocates dynamic memory space for waiting tasks in
following manner:

the

Uses a priority level of 1 through 250 to determine a waiting
task's use of a system-controlled partition. A higher number
indicates a higher priority.

Begins at the base of the partition and searches for a
contiguous area large enough for the waiting task.

Creates a dynamic subpartition within
partition.

Eliminates the subpartition to free memory when the task
finished execution.

the

free,

system-controlled
has

In some instances, a waiting task cannot be
loaded
into
a
system-controlled partition because there is not enough memory space
available. If there is not enough space to load a waiting task, the
Executive uses checkpointing to make memory space available to the
waiting task.
To make room for a waiting task, the Executive searches
the
system-controlled partitions for one or more tasks with a lower
priority than that of the waiting task.
The
Executive
then
checkpoints (moves) the task of lower priority from memory to disk to
make room for the waiting task of higher priority.
The checkpointed
task is immediately placed in competition with other tasks waiting for
residency. When the checkpointed task is reloaded, it continues
processing from the point where it was interrupted.
On RSX-llM-PLUS, the EXecutive keeps track of outstanding I/O on a
partition-sy-partition basis.
Thus, the Executive may checkpoint
subpartitions with dynamic common regions, static COrnmon regions, and
task regions if there is no I/O pending_
On RSX-lIM, the Executive keeps track of outstanding I/O on a
task-by-task basis.
The Executive cannot easily determine to which
partition outstanding I/O is directed. Therefore, RSX-llM can only
checkpoint subpartitions with task regions. Common partitions and
dynamic common regions created by memory management directives cannot
be checkpointed.

14-2

THE SHUFFLER
14.1.2

Partition Fragmentation

Checkpointing does not always create enough memory space to load a
waitin9
task.
This
is a result of partition fragmentation.
Fragmentation in system-controlled partitions occurs when tasks of
various sizes are entering and exiting memory, or when, for example,
device drivers are loaded in the middle of a system-controlled
partiti.on. Device drivers, which cannot be checkpointed, often create
space between subpartitions and below subpartitions called fragments.
Tasks with nonbuffered, outstanding I/O cause fragmentation
of
system--controlled partitions. Such tasks cannot be checkpointed. The
Executive must wait for the task's I/O count to reach zero before the
task can be checkpointed. While the Executive waits for the task's
I/O count to reach zero, the task is blocked from execution to prevent
the task from issuing more I/O requests that could delay the loading
of the waiting task.
The following lists the serious causes of
fragmentation in system-controlled partitions:
1.

Device drivers loaded in the middle
partition

system-controlled

Subpartitions that are connected to the IPll driver

Subpartitions that are connected to an
means of a CINT$ directive

interrupt

vector

Subpartitions with nonbuffered, long-outstanding
whose I/O count has not yet dropped to zero

I/O,

and

Regions that have been fixed by the Executive
parity error

Dynamic regions created by PLAS directives (RSX-IIM only)

for

memory

If, for any reason, including fragmentation, the Executive is unable
to load a waiting task into a subpartition, the Executive requests the
ShufflE!r.
The Shuffler moves subpartitions in system-controlled
partiti.ons in an attempt to create the free space necessary to load a
waitin9 task. Thus, the Executive requests the Shuffler only when all
other attempts to load a waiting task fail.

14.2

SHUFFLER PERFORMANCE

The Shuffler is approximately 700(decimal) words and can be installed
only on a mapped system.
The Shuffler is installed during system
generat~ion by a VMR command and by default is built for the
partition
SYSPAR, which can also be used by the MCR dispatcher and TKTN. Refer
to the RSX-IIM or RSX-IIM-PLUS System Generation and Installation
Guide for more information on installing the Shuffler.
The overhead incurred for the Shuffler task is found in the Shuffler,
not in the Executive. The Shuffler responds well on a system if there
are fewer tasks loaded in memory and if the Shuffler does not execute
frequently.
If you have a heavily loaded system, the Shuffler may
executE! more than you want because of repeated memory allocation
failurE!s.
If the Shuffler executes frequently on your system, better
perfornlance is obtained when the Shuffler is fixed in its own
partiti.on where it does not have to compete with MCR and TKTN for
memory.
The word, $SHFTM, in the Executive's system common area limits the
number of times the Shuffler may be requested within a time interval.
$SHFTM heightens the Shuffler's effectiveness on your system.
Each
14-3

THE SHUFFLER
time the Executive requests the Shuffler, this timer is checked.
If
the timer registers zero, the Shuffler may be requested. If the timer
registers a positive number, the request for the Shuffler is ignored.
The amount of time (clock ticks) that must elapse before the Shuffler
is requested again is stored in the system common area, $SHFCT.
When
the Shuffler is successfully requested, $SHFTM is initialized for the
new interval with the value stored in $SHFCT.
If you are a privileged user, you may change $SHFCT.
To change
$SHFCT, you need a copy of RSXll.MAP, the Executive map produced
during system generation. Using the map, you must determine the
address of the global symbol $SHFCT. You can change the contents of
the system $SHFCT with the MCR OPEN command.
The Shuffler is
requested infrequently if the value is set too high.
If the value is
set too low (zero), system response may decrease because the Shuffler
is being requested too frequently.

14.2.1

Monitoring The Shuffler

Several memory allocation failures during peak usage periods result in
the repeated request of the Shuffler. The repeated execution of the
Shuffler can produce a noticeable decrease in response time. You may
monitor the Shuffler's effect on your system by using RMD. RMD is a
privileged task that displays information concerning task activity on
the operating system.
Refer to Chapter 6 for a detailed explanation
of RMD.
If you want to monitor Shuffler activity with RMD, you must dedicate a
video terminal on which to run the RMD display. The key features to
monitor on the memory display page are as follows:
•

The currently executing task; *IDLE* indicates that no task is
executing

•

The number of active tasks in memory and the amount of memory
they occupy, plus the number of active tasks checkpointed (on
disk) and the total memory they would require.

These features show task activity.
If the Shuffler is active,
tasks
are moving down in the partition, and the currently executing task
field registers the Shuffler as the active task.
Occasionally, the Shuffler registers as the active task, but tasks
cannot be seen moving down in the partition. To verify that tasks are
not moving when the Shuffler is executing, check the number of active
tasks checkpointed (on disk) and the number of tasks waiting for
memory. If this count remains the same over a period of time, the
Shuffler is executing but cannot create enough space for waiting
tasks.
Thus, the Shuffler is using too much of the system's
resources.
If the system does not recover, it might be better to
abort the Shuffler fro~ your system.
If the Shuffler task continues to use too much of the system's
resources, you should remove the Shuffler from your system with the
MCR REMOVE command.

14.3

THE SHUFFLER ALGORITHMS

When a memory allocation failure occurs, the Executive requests the
Shuffler.
The Shuffler searches memory for a system-controlled
partition that has at least one task waiting for space.
When the
Shuffler locates such a system-controlled partition, it attempts to

14-4

THE SHUFFLER
move (shuffle) subpartitions in the memory partition
continuous area necessary to load waiting tasks.

create

the

On RSX-IIM, the Shuffler can only shuffle task subpartitions. Because
an
outstanding
I/O count on a
RSX-IIM
does
not
maintain
partition-by-partition basis, 'bhe Shuffler cannot determine whether
outstanding I/O is pending to a common partition or a dynamic common
region. Thus, the Shuffler does not shuffle common partitions or
subpartitions with dynamic common regions created by memory management
directives.
OnRlX..;,llM..;,PLliJ"
out"tal'l.~U.~9

tl'le$llUfflerdQe...:n~~f le~o~p~:t~,ioris ... 'be~a\l$e

I/o . . ~(Jllntl •... ~Clil'l.t_:i.n~q()tJ;~J?~r:tlt~Q~~~l'<"i~arti tion basis.

Thus/subp~rtitions··con;tain:i.n9 . stati~·· . oo~ollX'e,ions .•. ()r·dynamic

regions.can.'beshuffleCJ whentherEfls no I/O pending.

common

The Shuffler uses two algorithms to move subpartitions in memory.
Each algorithm executes several steps repeatedly until the partition
reaches a stable state.

14.3.1

The First Pass Algorithm

In the first pass, the Shuffler attempts to move each subpartition to
the base of the partition. When subpartitions are moved to the base
of the partition, free space is created at the top of the partition so
that a waiting task can enter memory if there is enough space.
Shuffling occurs in the following steps:
1.

The Shuffler requests the Executive to
unconditionally
checkpoint
all stopped checkpointable subpartitions and
checkpointable subpartitions that have been blocked with a
eLI command.

The Shuffler attempts to move each subpartition to the base
of the partition and blocks each executable task from further
execution.
If a subpartition has outstanding I/O, the
Shuffler waits for the task's nonbuffered, outstanding I/O
count to reach zero. If the I/O count does not reach zero in
approximately .5 seconds, the Shuffler marks the subpartition
as having outstanding I/O, and restarts the first pass
algorithm.
The Executive clears the subpartition's I/O
indicator when the task's I/O count becomes zero.

The Shuffler moves each task to the base of
If the subpartition's I/O count reaches
seconds.

Each subpartition is unblocked to allow further execution
after shuffling is complete, and the free space, now above
the subpartition, is deallocated.

the partition.
zero within 30

Be aware that a fixed task can be shuffled. If you do not want to
have
a
fixed
task shuffled, you must fix this task
in a
user-controlled partition or in its own dedicated system-controlled
partition.
If fragmentation has not occurred at the end of the first pass, it
means the Shuffler has successfully merged the free space in the
partition into one continuous area at the top of the system-controlled
partition.
A task may then be loaded into memory if there is enough
space available.

14-5

THE SHU.FFLER

However, memory space may not be available if there are several tasks
already loaded in memory, or if fragmentation is dividing the
system-controlled partition into two or more partition sections.
A
partition section is a subset of the area in a system-controlled
partition. Each partition section is flanked on at least one side by
a subpartition that cannot be shuffled. For example, if a device
driver is loaded in the middle of a system-controlled partition, the
system-controlled partition is divided into two partition sections
because a device driver is a subpartition that cannot be moved.
If, during the first pass algorithm, the Shuffler encounters a
subpartition that cannot be moved, the Shuffler begins to shuffle
subpartitions that can be moved to the base of the partition section
·that bounds it.
The Shuffler cannot shuffle subpartitions around a
subpartition that cannot be moved. Therefore, if fragmentation has
occurred during the first pass, the system-controlled partition is
divided into two or more partition sections, and the free space in the
partition may no longer be merged at the top of the partition, but
rather at the top of the partition section.
The Shuffler initializes the second pass algorithm if enough memory
space is not available for waiting tasks, or if fragmentation has
divided the system-controlled partition into
several
partition
sections.
Little memory space or partition sections prevent the
Shuffler from accumulating all the free space at the top of the
partition.
The free space in each partition section is separate and
cannot be merged with the free space in another partition section.

14.3.2

Second Pass Algorithm

The second pass algorithm is executed once for each partition section
within a system-controlled partition. This pass attempts to create a
reverse priority list of subpartitions that can be checkpointed by the
waiting task.
During the second pass, the Shuffler creates a list in ascending
priority order of the subpartitions in each partition section. The
Shuffler then compares the size of the waiting task with the sum of
free space in the partition section plus the total of one or more
lower priority, checkpointable tasks. If the waiting task is smaller,
the Shuffler requests the Executive to checkpoint the lower priority
task{s).
Checkpointing the lower priority task{s) may create new space, but the
new space may not comprise a continuous area in memory. The Executive
may begin the first pass algorithm to accumulate the free space of the
partition section.
The free space is then allocated to the waiting
task. As long as there are subpartitions that cannot be moved in a
system-controlled partition, memory is still divided into two or more
partition sections.
If the Shuffler completes the second pass without finding room for a
waiting task, the Shuffler searches for the next system-controlled
partition with waiting tasks. If there are no other system-controlled
partitions with tasks waiting for memory space, the Shuffler exits.

14-6

CHAPTER 15
RSX-llM-PLUS SYSTEM RECONFIGURATION

A reconfigurable system is a system in which you can add or remove
system resources such as memory and devices. Reconfiguration is a
means of physically and logically connecting and disconnecting various
resources.
This chapter discusses the purpose and application of
reconfiguration, and describes the components and commands of the
reconfiguration services.
System reconfiguration is available only on RSX-llM-PLUS systems.
Some of the information in this chapter, however, applies only to
multiprocessor systems.
Blue ink is used to distinguish
this
informa.tion.

15 .1

~rHE

RECONFIGURATION SERVICES

The reconfiguration services allow you to reconfigure an RSX-llM-PLUS
system to bypass faulty hardware elements and to isolate the system
from the effects of these elements.
With the reconfiguration services, you can define a set of hardware
resources that are accessible from the on-line system and also remove
devices from the pool of resources allocated to the on-line system.
For example, after bootstrapping the system, you can place a failed
disk drive off line and then use another drive that is already on line
or place one on line to take over for the disabled unit.

15.1.1

Reconfiguration Components (CON,RD:,HRC)l

You reconfigure system resources by using together a command interface
(CON), a loadable driver (RD:), and a privileged reconfiguration task
(HRC). CON and HRC must have enough checkpoint space allocated for
them both to be resident in memory at the same time. If the operating
system cannot load both tasks at the same time, CON commands will
fail.
CON, as the command interface, receives and parses the commands that
you issue to reconfigure the current system. CON then creates and
submits QIO packets to the reconfiguration driver (RD:).
RD:, the reconfiguration driver, serves as an interface between a user
task (either CON or a user application task) and the HRC task; it is
the ga1:eway between tasks that generate reconfiguration requests and
the ac1:ual implementation of those requests. RD: accepts QIO packets

1. DIGITAL will accept SPRs regarding the interface, but reserves
right to treat such SPRs as informational only.
15-1

the

RSX-IIM-PLUS SYSTEM RECONFIGURATION
from any task and places these packets into the receive queue of HRC.l
Before passing the QIO packets to HRC, RD: performs privilege and
address boundary checks on them. The checks ensure that the packets
are using valid addresses and legal function codes, and, for some
functions, that RD:
is attached to them.
HRC, the privileged reconfiguration task, performs
the
actual
reconfiguration operations for the system. To process reconfiguration
requests, HRC calls Executive routines, which then call the associated
device
drivers.
HRC
services the requests for configuration
information by passing the desired information directly to the user
buffer.
After HRC services the request, a status is returned (by means of I/O
completion) to the requesting task. The status return was implemented
in part to allow tasks other than CON to interface with HRC.
The data base for each system device contains status words that
reflect device state.
When you change a system device state, HRC
modifies the appropriate data base status word to either grant or
inhibit device access.

15.1.2

Device States

The RSX-IIM-PLUS system
reconfiguration
services
control
the
configuration state (on line or off line) of the hardware devices and,
therefore, control device access. A system device can assume one of
four states:
1.

On line - device on line, access granted

Off line - device off line, access denied

Marked for on line - device will be
access path exists, access denied

Marked for off line - indeterminate state, access denied

brought

line

when

In the on-line state, a device is logically on line for access.
This
state indicates that an access path exists between the device and an
on-line processor and that a call (if any) to the driver's controller
or unit status change entry points was successful. RSX-IIM-PLUS
grants access to on-line devices only. To access an on-line disk or
tape
volume and perform virtual I/O on it (for example, read or
write operations to files), the volume must be mounted.
(See the
~SX-IIM/M-PLUS
MCR Operations Manual or the RSX-IIM-PLUS Command
Language Manual for a description of volume access rights and mounted
volumes. )

1. Note that programs written to use the current version of RD:
may
have to be modified in the next release. You should centralize all
code concerning RD: so that modifications can be made easily.
Because of the likely changes, RD: has not been documented. For some
information, check the reconfiguration sources located in UFD [27,10]
of the distribution kit (except the RL02 kit, which does not contain
any sources).
Important modules for the interface are CNHRC, HROOT,
and HRSUB.
(See also the macro OLRDF$ in [l,l]EXEMC.MLB for a
description of volume access rights and mounted volumes.)
15-2

RSX-llM-PLUS SYSTEM RECONFIGURATION
When a device is in the off-line state, the system denies access to
the device.
Attempts to access an off-line device result in an I/O
error (IE.OFL).
(See the RSX-llM/M-PLUS and Micro/RSX I/O Operations
Reference Manual for lists and explanations of error codes.) Taking a
controller off line also takes all of its associated units off line,
which places the units in the marked for on-line state.
The marked for on-line state indicates that a request to bring a
device or controller on lin~ has been made, but part of the access
path to the device or controller is off line. Access attempts yield
the error code IE.OFL.
HRC places a device marked for on line
logically on line when it brings the entire access path on line.
The marked for off-line state indicates that the system encountered an
unexpected error in attempting to place a specific device logically on
line. You must issue an explicit off-line command before attempting
or retrying an on-line operation.

15.1.3

Placing Devices Logically On Line and Off Line

To place a device logically on line, HRC first verifies that the
device driver is loaded (for loadable drivers only) and then tests
whether the controller can access the device (the controller must be
on line).
If the controller can access the device (an access path
exists), HRC modifies the appropriate status word to reflect that the
device is on line. If the controller or device cannot be accessed,
HRC marks the device for on line and then places the device on line
when the access path is brought on line.
Before placing a device off line, HRC attempts to protect against
inadvertent loss or possible corruption of data by verifying that the
state change will not interfere with active I/O.
HRC considers a
device active and rejects off-line commands if the device has context.
The reconfiguration services define device context as a condition that
indicat.es (or permits) I/O activity on the device. The following is a
list of conditions that define device context:
task is attached to the device (for example,
• Adespooler
attaches the line printer) .

the

• The device (or an associated device) is a logged-in terminal.
The device (or an associated device) contains a mounted
• volume.
•

For the DT07 bus switch, a port is logically
processor (linked).

connected

•

For memory boxes, the memory within the box
line (multiprocessor systems only).

•

A disk device has data caching enabled.

You cannot take a controller off line if
controller have context.

any

the

logically

units

the

For dual-port
disks
(RK06/RK07,
RM02/RM03/RMOS/RM80/RP07,
and
RP04/RPOS/RP06), which have each port connected to a different
controller, you can place off line one path with context as long as
the alternate path is on line.
(See the description of the OFFLINE
command for more information.)

15-3

RSX-IIM-PLUS SYSTEM RECONFIGURATION
INITIATING THE RECONFIGURATION SERVICES

15.2
~{ou

reconfigure an RSX-llM-PLUS system interactively from a terminal
or by means of indirect command files. The reconfiguration services
act as an interface between your terminal and the RSX-llM-PLUS system.

rro issue a reconfiguration command, type a command line in response to
1:he default prompt (»
or to the explicit command interface prompt
(CON». A command line consists of three components: a command name,
any required parameters, and a line terminator.
(Note that there is
no DCL command to access CON.)

15.2.1

Invoking CON

It is not necessary to use the entire command name when issuing a
command line; CON requires only the first three characters of the
name. However, to make the intent of the command input clear to
someone reading a printed copy, you can use the entire command name.
For example, you can issue the ONLINE command as follows:
Formats
CON>ONL dev-spec ®]
or
CON>ONLINE dev-spec ®]
<:lev-spec
The target device.

The RETURN key (the line terminator).
A space or tab signals the end of the command name.
Therefore, no
spaces or tabs are permitted within the name itself. To use the
reconfiguration services, first invoke the command interface CON and
then
issue
the commands.
There are two ways to invoke CON
interactively:
1.

Use the one-line format to invoke
command, and return control to MCR.

Use the direct task format to invoke CON and
prompt (CON». For example:
i'-iCF;: .>C"i")N
C::Ui-l.>

CON, execute
For example:

obtain

single

task

®]

Type CTRL/Z to exit from the direct task format.
You can also enter commands through indirect command files.
An
indirect command file that contains reconfiguration commands does not
require terminal interaction when the file is executed.
Thus,
indirect
command
files
are
a
convenient means of creating
configuration command sequences that create different configurations
or restore previous configurations.

-15-4

RSX-IIM-PLUS SYSTEM RECONFIGURATION
For example:
MCI~:>CON

fi!CONFIG ~

This command line invokes CON, executes the reconfiguration commands
contained in the indirect command file CONFIG.CMD, and returns control
to MCR .
The following command line executes
CONFIG.CMD and returns control to CON:
C OJ N ::.- n en:'! F T (i

the

commands

the

file

Indirect command files can be nested to a maximum depth of three.

15.3

CON COMMAND SUMMARY

The following table summarizes the reconfiguration commands and
provides a compact overview of the commands.
Detailed command
descriptions appear in alphabetical order in Section 15.4.
Table 15-1
CON Command Summary
BUILD

Creates a command sequence in an internal
buffer that, if executed, duplicates the
current system configuration.

C]~EAR

Erases the command sequence created by
BUILD (but not the file created by LIST)
that is stored in the internal buffer by
CON.

DISPLAY

Displays the configuration and status of
the
hardware devices in the current
system.

ESTATUS

Emits the current status
device.

HJt~LP

Displays the help text for CON.

IDENT

Displays the current versions of CON and
HRC and the date and time the two tasks
were built.

LINK

Logically connects a port of
bus run to a processor.

LIST

Displays the results from a BUILD command
or puts the command sequence into a
specified file. A file type of .CMD is
suggested because that is the default
type for an indirect command file.

OFFLINE

Removes a device without context from the
active set of devices in the current
configuration.

specific

switched

(continued on next page)

15-5

RSX-IIM-PLUS SYSTEM RECONFIGURATION
Table 15-1 (Cont.)
CON Command Summary

OFFLINE MEMORY

(Multiprocessor systems only.)
Removes
the memory box with the highest dddresses
from the system.
Note that you must
first ensure that notiting is using tl-!e
nemory in the memory box.

ONLINE

Attempts to place a device
line.

ONLINE MEMORY

Multiprocessor systems only.)
Adds a
memory box to the on-li~le confi~uration.
Not e tha t you must expand t_he parti t ion
structure to use the additional ~emory.

SET

Alters the CSR or
interrupt
vector
address values of a device
and,
on
multiprocessor systems,
activates
or
lnhibits the sanity tim(=~r and ts dlarm.

SWITCH

(Multiprocessor systems only.) Logically
disconnects a port of a switched bus run
from a processor and then connects the
port to another processor.
The command
is equivalent to a LINK command followed
by an UNLINK command.

UNLINK

port
of
a
Logically disconnects a
switched bus run from its respective
processor.

logically

CON also accepts two switches, /HE and /NOMSG.
These switches are
used alone in the CON command line. Their functions are as follows:
/HE

Displays the help text for CON.

/NOMSG

Suppresses all information displays and
error messages returned by CON. You must
exit from and then reenter CON to have the
messages displayed again.

15-6

RSX-IIM-PLUS SYSTEM RECONFIGURATION

BUI
15.4

CON COMMAND DESCRIPTIONS

This s~~ction describes each of the reconfiguration commands.
Note
that some of the commands must be issued from a privileged terminal.
BUILD
The BUILD command creates a sequence of commands that, when executed,
duplicates
the
current system configuration.
The sequence of
reconfiguration commands resulting from a BUILD command is held in a
buffer in memory.
When this sequence of commands executes, the
reconfiguration commands restore the system to the exact state
existing when the BUILD command was issued.
Format
CON>BUI[LD]
Example

This command creates a sequence of commands that
current system configuration.

15-7

duplicates

the

RSX-llM-PLUS SYSTEM RECONFIGURATION

CLEAR
CLEAR
1~he

CLEAR command erases from the internal buffer the current sequence
of commands created by the BUILD command.
The command does not delete
t:he file created by the LIST command (described later in this
section) .

CON> CLEAR
Example

c urJ ·: fJ, 1.1 Ti... D
CON:· CI .. F:(.:lP

The CLEAR command removes from the internal buffer
sequence resulting from the previous BUILD command.

15-8

the

command

RSX-IIM-PLUS SYSTEM RECONFIGURATION

DIS
DISPLAY
The DISPLAY command provides current system configuration information
about the device units, device controllers, processors, memory boxes,
and memory box controllers.
Format
CON>DIS[PLAY] [keyword{s)] [FOR string]
Keywords
UNI[TS]
Displays every device unit in the current configuration.
The display equates each device unit with its respective
controller.
CON[TROLLERS]
Displays
every
configuration.

device

controller

current

the

FUL[L]
Displays the status flags for every device unit and device
controller in the current configuration. The status flags
indicate the following:
Accpath

The device has an on-line access path.

Context

For a tape or disk (mountable device), the
device
contains a mounted volume.
For a
terminal, a user is logged in.
Other devices
are attached.

Driver

For a device unit, the driver is loaded. For a
device controller, a driver is available.

Massbus

The device
controller.

Multiport

The device is dual-ported
(a
dual-access
device) between two controllers (for example, a
dual-ported RP06 drive).

Offline

The device is off line.

Online

The device is on line (or marked for on line).

Prv-Diag

(Used with the OFFLINE and ONLINE keywords.)
The device is marked for on line or off line,
but nothing can happen until the respective
controller is brought on line or taken off
line.

Unknown

The CSR assignment for the device is 160000 and
thus cannot be accessed.

15-9

connected

MASSBUS

RSX-llM-PLUS SYSTEM RECONFIGURATION

DIS (Cont.)
ALL
Same display as for the FULL keyword with the addition of
interrupt vector addresses and CSR assignments for device
controllers.
ATT[RIBUTESJ
Displays interrupt vector addresses and CSR assignments
device controllers.

for

The DISPLAY command allows more than one keyword per command
line. However, some combinations (such as DISPLAY UNITS FULL FOR
DB) are
meaningless.
The
DISPLAY
command
ignores
an
inappropriate keyword.
If the command omits a keyword, the display contains the logical
names
and status flags
for every device unit and device
controller in the current configuration.
FOR string
An optional parameter that allows a selective display of a
particular device or device group. When you use this parameter,
CON displays the requested information for the devices specified
in the string.
You can also use one or two wildcard characters
(*)
in the
string.
You use one wildcard to find out which devices are
connected to the controller you have specified after
the
wildcard.
You use two wildcards to find out which devices have
the attribute you have specified after the wildcards (either
ONLINE or OFFLINE).
For example:
CON>DIS FULL FOR RH
This command displays all of the RH controllers.
CON>DIS FULL FOR **ONL
This command checks to see which devices have
attribute (port-specific status is not displayed).

the

ONLINE

Examples

CON>DISPLAY FULL FOR DB
DBa:
Offline,Multiport,Massbus,Accpath,nrjv~r
PORT DBOA RHBO:
Online
PORT DBOB RHCO:
Online,Curr~nt,Accpath
DB 1:
Off line, Ml.Il t i PO rt, Mi3Sc;iblJs, flcCPi3th, nl' i ve T'
PORT DB1A RHB1:
Online
PORT DBlB RHC1:
Online,CIJrrent,Ar.r.path
This command displays information about
devices configured into the system.

15-10

all

the

DB:-type

RSX-IIM-PLUS SYSTEM RECONFIGURATION

DIS (Cont.)
CON DISPLAY UNITS

DBO
DBl

RHBO:,RHCO:
RHB1:,RHC1:

DF:O

F.:HI~O:

D ~;:. :1.

R~.: ;\ 1 :

~1MO

F:H1H)O:

i'·l 1"1 1

'~: HD1 :1. :

COO
T or ()
TT 1. :
.: T::.::'.:;
TT:·:~ i

D I·: 1 !
III...('~

L F' 0 ;
!. ~. t :
LP?:
i··~l..O !

Y' I. l~1 () :
Y7:('·;O ~
YZti 1 :
Y7A2 Z

(I ~< tl 1 ;.
l"tLr!iO:
1.. P ti 0 !
l. F' POt
I .. PCO!

This command displays all of the
configured into the system.

15-11

device

units

and

controllers

RSX-IIM-PLUS SYSTEM RECONFIGURATION

ESTAT
}t~STATUS

The ESTATUS command causes CON to exit with its exit status word
reflecting the current status of a specified device. Used with the
Indirect Command Processor (Indirect; see the RSX-IIM/M-PLUS Indirect
Command
Processor
Manual), the ,command returns a 16-bit word
(lescribing device status. You can use the status word to obtain
information about the configuration. The meanings of the bits in the
word are given in Table 15-2. Note that the meanings for units and
controllers are different from those for ports.
Table 15-2
Exit Status Values for CON ESTATUS
If the status is for a unit or controller:
Bit
No.

Bit
Value

0
1
2

1
2
4

6
8

100
200
400

1000

10
11
12

2000
4000
10000

20000

14
15

40000
100000

Description

Display

Exit status value:
o Warning
Success
1
Error
2
Severe error
4
This is a subcontroller device.
This is a controller device.
O-device is on line, I-device is
off line.
This device is restricted to privileged
and diagnostic functions.
This is a multiport device.
This is a MASSBUS device.
This device's CSR is 160000
(unknown) .
This device has an on-line access
path.
This device has context.
A driver is loaded for this device.

Online
Offline
Prv_Diag
Multiport
Massbus
Unknown
Accpath
Context
Driver

If the request is for a port:
Bit
No.

Bit
Value

0
1
2
8

1
2
4
400

10
13

2000
20000

40000

Description

Display

Exit status value (see above)
O-port on line, I-port off line.
This is the current port.
There is an on-line access path to
this port.
This port or the device it services
has context.

15-12

Online
Offline
Current
Accpath
Context

RSX-llM-PLUS SYSTEM RECONFIGURATION

ESTAT (Cont.)
Example
>@TI!
AT.>.ENABL.E SUBSTITUTION
AT.>CON ESTAT DB1!
>CON EST AT DB1:
AT.>;'<EXSTAT>'
>;126401
AT. )"'Z
>@ <EOF>

Invoke IndirElC't.
Enable substitution mode.
Type CON command linEl.
System displays command line.
Reauest contents of <EXSTAT> to he displsyed.
System displaws current <EX STAT> contents.
E:dt Indi rect

Using Indirect interactively, the CON command line emits the
current status of DBl:, which is stored in the Indirect special
symbol <EXSTAT>.
The number 126401 has the following meaning:
100000
20000
6000
400
1

Device's driver loaded.
Device has on-line access path.
Device is both multiport and MASSBUS.
Device is off line.
Exit status value = Success.

15-13

RSX-IIM-PLUS SYSTEM RECONFIGURATION

HE
HELP

The HELP command displays the help text for CON.
Format
CON>HE[LP]
Example
CON>HEl..F'
CON -- Confi~uration Control Command Task
Implem@nted commands:
ONLINE <device_list>
ONLINF MEMORY <memor~_box>
ONL.INE ALL
OFFLIN~ <device_list>
[) F F I. I NF ME M0 F: Y <: ITI e IT! 0 r ~ ... b 0 :-: >OFFI .. INE AL.L
SET <controller_sp
(User typed CTRLjO to suppress further output.)
This example shows the form in which the HELP
information about the system configuration.

15-14

command

displays

RSX-IIM-PLUS SYSTEM RECONFIGURATION

IDENT
IDENT
The IDENT command displays the current version numbers of the CON and
HRC tasks.
The date and time the tasks were task built are also
displayed.
Format
CON)IDENT
Example

CON>rDENT
CON -- CONFIGURE Version 4.00
Task blJilt: 1-DF.:C-85 1.2:52:43.5
NRC -- HRC
Task built:

004.000
t5-DF.:C-R5 23:59:10.9

V~rsjon

In this example, Version 4.0 of CONFIGURE was task built on
December 1, 1985; Version 4.0 of HRC was task built on December
15, 1985.

15-15

RSX-llM-PLUS SYSTEM RECONFIGURATION

LIN
LINK
The LINK command logically connects a port of a switched bus run to a
processor and thus permits access to the devices on the switched
segment of the bus run.
To logically connect a switched bus run to the processor1s UNIBUS, the
devices on the switched segment must all be off line or marked for on
line. You cannot dynamically link switched bus runs.
Format
CON>LINK UBx TO CPx
UBx
The target-switched bus run. Switched bus runs are named using
the designation UB followed by a letter from the DIGITAL hardware
alphabet as follows: UBE, UBF, UBB, UBJ, UBK, UBL, UBM, UBN,
UBP, UBR, UBS, and UBT.
CPx
The target processor.
Example

CON>LINK UBE TO CPA
This command logically connects the first switched bus run
to processor A (CPA).

15-16

(UBE)

RSX-llM-PLUS SYSTEM RECONFIGURATION

LIST
LIST

The LIST command displays the current command sequence or writes the
sequence to a file.
You can use this command to keep a list of the
commands that will duplicate the current configuration. If the buffer
in which the current command sequence is stored (see the description
of the BUILD command) is empty, CON returns the following message:
CON -- Command list is empty. Nothing to print
If you specify a .CMD file type, you can execute the commands from the
indirect command file (that is, BUILD, LIST filename.CMD, @filename)
and then return to CON.
Format
CON>LIST [filespec]
filespec
Any legal RSX-llM-PLUS
file
ddnn:[g,m]filename.type;version.
Example
CD N> H!,! 1 L 1::
CUN>!. J~:;T
I::: H(.-\
CNLINF.
OUI. JNF
ONI...Tt,IF
(I t~ F!. TtiF
UFF!.INF.:
'JNI. TNF
J](il .. l NF:
flNI :: NF
ONI .. INF.:

f;:HB
:::HC
Iti1A
\' L (:'1

YZf.i
t:r 1< (~
DLi:'.j
I.. F' ~':j
IH<O t

DUI...INF
ON!..TNF.

lIBl :

UNLTNF

DF:O:

DNI.INF
t1~! l... IN F

11110 t

DNLINE
UNI.. INE
ONI.INF.

ONLINE
OUt .. I NI~
01"--11.. 1 NF
UN!.. J NF

ON\.. TNF
ONI . ,[NF.
UN\...INf
ONI...TNF.

ONLINE

T.tR1:
l'iM 1 :

COO:
TTO!
TTl!
fT2:
l T~~ :

lT4:

TT5:
TT6:

TTl:
TT10!

ONI .. INE

DI{O:
Y:tl'( l.

UNI.. INF
ONI.INF.

IHO:
I..F'O:

I)NI...INE

NLO:
T:lM()t
ftMlt

DNI.IN~:

ONLINE

15-17

specification

the

form

RSX-llM-PLUS SYSTEM RECONFIGURATION

LIST (Cont.)
In this example, the BUILD command creates a sequence of commands
that duplicates the current system configuration. Next, using
the LIST command displays the sequence of commands you would use
to reestablish the current system configuration.

15-18

RSX-IIM-PLUS SYSTEM RECONFIGURATION

OFF
OFFLINE

The OFFLINE command changes the state of a inactive device to
off-line, thus removing the device from the active set of resources in
the current system configuration.
This prevents further device
access.
To take a device off line, it must not have context (see
Section lS.1.3), and HRC must be able, in lOOO{decimal) tries or less,
to detect when there is no I/O activity in progress.
The transition to the off-line state for a specific device controller
is completed only if all associated devices are also off line.
If an
associated device is not off line, HRC rejects the OFFLINE command
because placing the device off line could interfere with active I/O.
Issue the appropriate MCR command{s) to remove device context.
This
ensures that the device does not have context and can be placed off
line.
If a ta.sk has attached the device unit, the task must be detached (or
request. to be aborted) before the unit can be placed off line. For
example, if you issue an OFFLINE command for a line printer controller
(such as OFF LPB), and a connected unit (such as LPl:) has context (in
this case, LPl: is a spooled device and attached by the Queue
Manager), CON rejects the command and issues the following error
message! :

If the device is marked for on line (for example, a device unit with
its controller off line), the command changes the device state to
off-line. Subsequently, when the controller is brought on line, the
system does not activate the device.
If the device is marked for off line, the command changes the
state t~o off-line and thus enables a future on-line attempt.

device

Individual

ports of dual-port devices can be taken
off
line
You may want to do this if the port does not work
correct~ly (for example, you
cannot access the device through the
port), or if you want to increase system throughput. Figure lS-l is
an example of the way throughput could be increased:
separat~ely.

RHB ------------------------,--------DBOB
DBO:

DBOA

RHA
DB1A
DB1:

ZK-S7S-81

Figure lS-l

Sample Configuration for Increasing System Throughput
lS-19

RSX-IIM-PLUS SYSTEM RECONFIGURATION

OFF (Cont.)
With this configuration, it is probable that the system will use the
DBOA port.
Because activity on DBI: must use the DBIA port, it has
to wait until DBOA is free.
If you put only ports DBOB and DBIA on
line, each DB disk has its own controller and does not have to wait
for another port to be free.
The OFFLINE command also accepts an optional keyword, ALL, which
places off line all devices except the system disk and the terminal
that issued the command.
(The OFFLINE ALL command is useful prior to
a system save.) Before issuing the OFFLINE ALL command, you must first
dismount all volumes (tapes and disks) except the system disk and log
out all terminals except the issuing terminal.
Formats
CON>OFF[LINE] device-specl[,device-spec2 ... ,device-specn]
CON>OFF[LINE] ALL
Note that device-spec also includes processors (CPx).
Requirements
•

Only a privileged user can modify the system configuration.

•

No tasks are attached to the device.

•

No volumes are mounted on the device.

•

If the device is a terminal, no users are logged in on it.

Example
C i""1 i,1 ':, nF F I , 1 NFl I:' tl ? I F")'
CCN>OFF Y7A,YZB,YZr.Y7D

r f-' rlll:i n ;:,:1

The command sequence logically places the devices off line, which
allows the bus run UBE to be placed off line.

15-20

RSX-IIM-PLUS SYSTEM RECONFIGURATION

OFF MEM
OFFLINE MEMORY

(Mul tiprocessor systems only.) The OFFLINE MEMORY ~ommand remOVE~S a
memory box from the system configuration.
Because memory must be
contiguous, the target box must be the memory box in the system
configuration with the highest addresses (the last memory box added to
the sys·tem).
I f the target box is not the last box in the mE~mory
configuration, CON rejects the command and issues the message:
¥:l<HI>r:

"";r'\ i

If a partition maps to a memory box targeted for off-line status,
rejects the command and issues the following message:

CON

r: .

Therefore, you must contract the partition structure before removing
the memory box.
The MCR SET /TOP command can adjust the partition
structure up or down (see the RSX-llM/M-PLUS MCR Operations ManuaJ~ for
details),
but it is your responsibility to ensure that nothing is
using the memory in the memory box. The system is protected so that
you cannot bring the memory box off line if anything is using it.
Format
CON>OFF[LINE] MEM[ORY] memory-box
Example

This command removes
configuration.

memory

box

15-21

MK2:

from

the

system

RSX-IIM-PLUS SYSTEM RECONFIGURATION

ONL
ONLINE

The ONLINE command changes the state
enables device access.

device

line

and

'rhe transition to the on-line state is completed only if an access
path exists between the device and the processor, and if the device
driver can successfully initialize the device.
If the device lacks an access path, the ONLINE command changes device
state to marked for on-line; the device is activated when an on-line
access path becomes available (when the controller is brought on
line) .
'rhe ONLINE command also accepts an optional keyword, ALL, which places
logically on line every device controller and device unit known to the
system.
Note that the data base values for interrupt vector and
CSR
assignments have no effect on the system until the device is brought
on line.
Formats
CON>ONL[INE] device-specl[,device-spec2 ... ,device-specn]
CON>ONL[INE] ALL
Requirements
•

Only a privileged user can modify the system configuration.

•

The specified device must be physically present in the target
system and included in the syatem at system generation.

•

If the specified device is serviced by a loadable driver,
driver and device data base must be loaded.

the

The ONLINE command activates a device unit only if the associated
controller is on line. The command first tests the unit to determine
whether it actually exists on the controller and then performs drive
sizing to determine device unit type. If the unit exists, it is now
ready for user access.
If the associated controller is off line, the
command marks the unit for on-line status; it is presence-tested and
sized when the access path is completed and, if present, activated.
To activate a device controller, the ONLINE command tests the
controller's
status register (CSR) to determine whether it is
physically present. If the controller is present, then all of the
associated
units
that
are
marked
for
on-line
status are
presence-tested, sized, and brought on line. Off-line units remain in
the relative off-line state regardless of any ONLINE command performed
on the associated controller.
r,) act i vat.E <t proce s s, >r 0
]lul t P /"I.) (. e S 5 H" S Y ,5 t.. en' ,
t1-. e t l rt:j e t p CJ' .
i 3sues
<l
\(),)tst.rap
reg JE' t-.
cocessor i lllores t_he bouts'i-ap I F,e~jt or C:,·1:1n.)
{~'i)N iSSUt~b ~hf' follow:.ng Tie ;3 a,::",
,1ftel"
timc'-'))
>\..

: :1 i i ,

tTl!

15-22

>(); ,

i f

:lUI) ..

''..l,'

,)!"

'1, j S )

RSX-llM-PLUS SYSTEM RECONFIGURATION

ONL (Cont.)
You can also bring on line individually the ports of a dual-port
device, thus increasing system throughput because you do not have to
wait for both ports if one does not work.
For dual-port terminals, you need a Status Control Block (SCB)
for
each tE~rminal to bring the ports of dual-port terminals on line
individually and to switch them individually. To switch the ports,
the software will bring the controller on line, but the terminals must
be switched manually using the CSll switch on each terminal.
If you
have only one SCB for each controller, all of the terminals on a
controller have to be switched over to the same controller.
Examples
Thle following command sequence (used on a multiprocessor system)
assumes that the UBE bus run has been switched from CPA to CPB.
The commands place the software bus devices on line for access:

CON)ONLtNE LPA,LPO:
CON)ONL YZA,YZB,YZC,YZn
CON)ONL TT2:,TT3:,TT4:,TT5:
CON)ONL TT6:,TT7:,TT10:,TT11:

On line line printer and controller

on 1 j n E' t E' r nl i n i:I ]
I

i rd, E' r f i:I (' e s

On line terminals

The following command places all devices on the system
on line:

logically

CON>ONL ALL
This command places on line every device controller and device
unit (except CPUs) known to the system (that is, all controllers
and devices included at system generation). If a device unit or
device controller lacks an access path, the command marks these
for on-line status.
Note that placing all devices on line takes several seconds on a
large system and that the command does not generate any error
messages saying that a device may not be on line.

15-23

RSX-IIM-PLUS SYSTEM RECONFIGURATION

ONL MEM
ONLINE MEMORY
(Multiprocessor systeJlls only.) The ONLINE MEMORY command adds a memory
box to the system configuration.
To place the additional memory on
line, you must first place the appropriate memory box port controllers
and the memory box itself logically on line. The box you specify will
have the highest memory addresses.

To use the additional memory, you must expand the partition structure
with the MCR SET /TOP command (see the RSX-llM/M-PLUS MCR Operations
!\1anual) .
;Pormat
CON>ONLINE MEMORY memory-box
:Example

This command adds
configuration.

the

memory

15-24

box

MK2:

the

system

RSX-IIM-PLUS SYSTEM RECONFIGURATION

SET
SET
The SET command changes the value of the CSR or the interrupt vector
address for an off-line device.
The values are stored in the device
driver's data base.
SET cannot verify the CSR or interrupt vector address that you
specify.
If you specify an incorrect CSR address, the system will not
be able to access the device when you issue the ONLINE command for the
device.
If you specify an incorrect interrupt vector address, the
system will send interrupts to nonexistent interrupt vectors when you
place the device logically on line; the device cannot be accessed.
Also, if you specify an interrupt vector that is in use, you will get
an error when you attempt to place the controller on line.
(See the
RSX-llM-PLUS Guide to Writing an I/O Driver for descriptions of the
CSR and vector assignment errors.r-On multiprocessor systems, the SET command also activates
timer and enables an alarm if the timer expires.

the

sanity

CSR

address

Format
CON>SET controller option=value
controller
The device controller (for example, RHA or DMA).
option
One of the following:
CSR

Alters the value of the controller's
stored in the driver data base.

VEC

Alters the value of the controller's interrupt vector
address stored in the driver data base.

TIMER

(Multiprocessor systems only.) Activates or
the sanity timer (controller is RHx).

ALARM

(Multiprocessor systems only.) Activates or inhibits
an alarm upon sanity timer timeout (controller is
RHx) .

inhibits

value
If the SET option is CSR, the value must be between l60000(octal)
and l77777(octal).
Note that if you specify a CSR address of
160000 or less, the device is "unknown" and cannot be placed on
line.
This allows you to use the CON ONLINE ALL command without
bringing every device on line when the
current
hardware
configuration differs from the generated system.
For example, if
the target system has a DMCll with a CSR address of 160100, but
the generated system has a DZll at that address, CON ONL ALL
attempts to bring the DMCll on line as a DZll.
Note that the
at:tempt may crash the system.
If the SET option is VEC, the value must be less than 774(octal).

15-25

RSX-llM-PLUS SYSTEM RECONFIGURATION

SET (Cont.)
On multiprocessor systems, if the SET option is TIMER or
the value is either ON (to activate) or OFF (to inhibit).

ALARM,

Requirement
The device must be off line and the driver must be loaded.
Examples

CON)S(f LPA VFC=t60
This command changes the interrupt vector address for
line printer controller to l60(octal).

This command changes the CSR address for the first
controller to l77600(octal).

15-26

the

line

first

printer

RSX-IIM-PLUS SYSTEM RECONFIGURATION

SWI
SWITCH

(Multiprocessor systems only.) The SWITCH command logically inverts
the processor association of a switched bus run; that is, it performs
an unlink operation followed by a link operation. The command uses a
special hardware feature of the DT07 to guarantee that the switched
bus is linked to the target processor after the unlink operation.
Thus,
1the SWITCH command ens ures that the switched bus wi 11 be
logically connected to the desired processor.
For example,
in a three-processor system,
a properly confi9ured
swi tched bus can be connected to anyone of three processors '. An
UNLINK command permits any processor to then link the switched bus.
However, the SWITCH command specifies that only a specific processor
can link the switched bus run following the unlink operation.
If CPA
and CPS are running as a dual-processor system and CPC is a
single-processor system, a switch from CPA to CPB occurs even if CPC
is trying to gain control of the bus.
CON rej42cts the command if a device attached to the switched bus has
context (that is, the device is processing or allowing processing of
I/O) .
Format
CON>SWITCH UBx TO CPx
UBx
The target-switched bus run. Switched bus runs are named using
the designation UB followed by a letter from the DIGITAL hardware
alphabet as follows: UBE, UBF, UBH, UBJ, UBK,
UBL, UBM,
UBN,
UBP, UBR, UBS, and UBT.
CPx
The target processor.
Example

CON)OFF LPA,LPO:
CON)OFF YZA,YZB,YZC,YZD
CON>OFF TT2:,TT3:,TT4:,TT5:
CON)OFF TT6:,TT7:,TT10:,TTll:
CON>SWITCH USE TO CPS
CON)ONL LPA,LPO:
CON)ONL YZA,YZB,YZC,YZD
CON)ONL TT2:,TT3:,TT4:,TT5:,
CON)ONL TT6:,TT7:,TT10:,TT11:

Off lin~ printer ~nd ~ontro]]er
Off line termin~l interfaces
Off line a]l terminals
Terminals assum~d not log~ed in
On line line printer and controller
On line t~rmina] int~rfares
On line terminals
(Devices now ronn~rted to CPR)

This command sequence logically disconnects the first switched
bus run (UBE)
from its respective processor and then logically
connects UBE to processor B.

15-27

RSX-IIM-PLUS SYSTEM RECONFIGURATION

UNL
UNLINK

The UNLINK command disconnects a port of a switched bus run from its
respective processor.
This command reverses the effect of the LINK
command.
CON rejects the command if any device attached to the switched bus has
context (that is, the device is processing or allowing processing of
I/O) .
Format

CON>UNLINK UBx
UBx
The switched bus.
Example

CON>UNI... UBE

T e r mi. n a 1. s ass I J I1t r~ d

n (J t

1. () (~ g (~ d

This command disconnects the switched bus port of
respective processor.

15-28

UBE

from

its

RSX-llM-PLUS SYSTEM RECONFIGURATION
15.5

SYSTEM FAULTS

System faults cause an RSX-llM-PLUS system to stop processing an
application properly.
A fault could be a user error, a system
software failure, an application software error, or a hardware fault.
User E!rrOrS (for example, accidentally removing a disk from the
system) are obvious because the fault usually occurs immediately after
the user action. System software failures usually occur when a system
bug is encountered while you are debugging the application software.
Application software errors are application-specific and not discussed
in this manual. Hardware faults -- their detection, isolation, and
recovery from -- are discussed in the remainder of this chapter.

15.5.1

Hardware Faults

Hardware faults can be placed in the following categories:
•

Media failures

•

Transient failures

•

Intermittent failures

•

Soft errors

•

Hard errors

The following sections describe each of these types of faults.

15.5.1.1 Media Failures - Media failures occur when I/O operations
fail because portions of the medium (a disk or tape) are bad. For
both disks and tapes, when a media failure is detected, read
operations are retried.
Before disks are initialized, you should check them for faulty sectors
with the BAD utility. BAD marks the bad sectors, which prevents the
file system from using them.
(See the RSX-llM/M-PLUS Utilities Manual
for more information.)
Occasionally, sectors on the media become bad, causing I/O operations
to those sectors to fail.
The error logging system can be used to
detect these failures.
(See the RSX-llM/M-PLUS Error Logging Manual
for more information.) You should probably replace faulty media if
they have critical data recorded on them or if a large number of
errors occur on them.
On devices supported by DUDRV, bad blocks may be replaced by the Bad
Block Replacement Control Task (RCT).
See Chapter 5 for more
information on this process.

15.5.1.2 Transient Failures - Transient failures cannot be repeated
and are caused by electrical factors such as static from clothing or
carpeting. If the failure occurs on an I/O device, the I/O operation
is retried automatically and the application software never sees the
failure.
(The Error Logger records the failure, however.) If the
failure occurs in memory or in a central processor, the system may
crash and have to be rebooted.

15-29

RSX-llM-PLUS SYSTEM RECONFIGURATION
15.5.1.3 Intermittent Failures - Intermittent failures are caused by
irregular conditions within the system and usually happen during
periods of high system or device activity. The failures usually occur
where recorded data is corrupted enough so that it cannot be read.
The data becomes corrupted when the device on which it is recorded is
not working properly, usually because of a temporary power shortage.
An example of an intermittent failure is a disk device detecting a
power failure, which causes the disk's volume valid bit to be reset.
Dismounting and remounting the disk clears this condition and may
allow I/O operations to proceed.
If the sources of intermittent failures are not obvious or directly
reproducible, try to recreate the conditions that caused the failure
by using the I/O Exerciser (lOX). lOX simulates high system activity,
which
could cause the failure to recur.
(See Chapter 4 for
information on lOX).
Intermittent failures that result in device errors appear in the error
log.

15.5.1.4 Soft Errors - Soft errors are device errors that do not
prevent an I/O operation from completing successfully. The device
driver retries the operation and, depending on the capabilities of the
device, performs ECC correction or disk-head offset positioning.
Soft errors usually indicate poor media or a misaligned device.
For
example, disk heads that are not aligned properly cause disk errors.
These errors can be corrected by head offset positioning.
If several soft errors occur on a device, you should find the source
of the errors and correct it through field service maintenance.
Soft errors are recorded by the Error Logger.

15.5.1.5 Hard Errors - Hard errors are solid device failures that
prevent a device from working properly. The errors make the device
unusable, but they are also the easiest to diagnose and correct.
The Error Logger records failed operations on the disks and tapes, but
that information is usually unnecessary since the failures are
obvious.
You can also use lOX to test the capabilities
devices to determine if they are failing.

15.5.2

many

peripheral

Recoverable and Nonrecoverable Errors

Soft errors and many media errors are recoverable errors.
They
recorded by the Error Logger but do not impact system operation.

are

Hard errors and some media errors are nonrecoverable errors.
They
usually
result in recurring device errors and failure of the
application software.
(The application can survive one failure on
each device type before it will stop processing completely.) However,
the operating system itself often survives the failure because all it
requires
to continue running is the system disk, the central
processor{s), and memory.

15-30

RSX-llM-PLUS SYSTEM RECONFIGURATION
15 .6

.FAULT ISOLATION

Once the software is stable, the availability of a system depends on
the reliability of individual devices and the time required to restore
processing. RSX-IIM-PLUS systems can, in some cases, work around
equipment failures in individual devices; but you must eventually
isolate a faulty device, correct the reason for the failure, and
restore it to the system. Depending on the severity and location of
the error, you may have to restart the application and/or the system.
Failures often exhibit symptoms that allow you to detect a failing
device before it can disrupt system operation. Because of this, you
should regularly monitor the condition of all RSX-IIM-PLUS peripherals
and
their
ability
to respond correctly to I/O requests, by
periodically examining the error log reports on all devices and
occasionally running lOX on infrequently used devices. The Error
Logger gathers information concerning all types of errors as they
occur and generates comprehensive error reports.
lOX tests the
validity of mass storage devices. The tests exercise combinations of
devices under high I/O activity.
Both the Error Logger and lOX provide error reports that contain a
description of device fault conditions. Use the reports to determine
whether the device should remain in operation.
If the
fault
conditions are transient (see Section 15.5.1.2) and the device is
capable of correctly performing its I/O functions, the device can
remain in operation. However, you should closely monitor the device
and schedule it for future maintenance as required.

15.7

SYSTEM RECOVERY

The procedure you use to diagnose and recover from a system fault
depends on the primary use of your system. If it is mainly used for
application development, then you would want to use the Error Logger
or lOX to determine the cause of a failure to prevent future failures.
If your system is used for process control and is running an
application that requires enhanced availability, utilities such as the
Executive Debugging Tool (XDT) are necessary only as much as they can
be used to isolate and correct failed components. Your main objective
is to bring the system back up and restart the application, with only
limited diagnostics for future references.
To restart the system and the application, first bring up the minimum
system required for running RSX-IIM-PLUS.
Then, gradually bring
devices on line until you have the minimum system required for running
the application. If any of the devices are faulty, you can take them
back out of the system and bring others on line until you have the
required configuration.
The method for recovering from system faults also depends on the
of fault. For example:

type

•

Transient errors could cause the system to crash, which
require rebootstrapping.

•

Hard errors require the device not to be used and possibly to
be reconfigured out of the system so that diagnostics for it
can be run.

•

Intermittent errors, because their source is not so obvious,
could require you to begin with a minimum configuration and
then gradually add devices until you find the one that caused
the error.

15-31

would

RSX-llM-PLUS SYSTEM RECONFIGURATION
If the minimum configuration has the problem, you will have to switch
1:0 another one.
Another possible way to recover from intermittent
failures is to turn the error into a hard error by imposing an
appropriate system load using lOX. By recreating the error, you can
discover its source and, therefore, how to correct it.
The following sections describe how to recover from different kinds of
hardware failures.

15.7.1

Device Unit and Controller Failures

r10st failures in an operating system result from disk, tape, or other
such device failures:
either the units themselves fail or the
respective controller fails.
The time needed to reconfigure around these failures depends entirely
on the application.
If the application can notify an operator of the
failure, thus allowing the operator to remove and inspect the media,
mount it on another drive, and reintegrate it into the system, then
1:he time to reconfigure is short. If, on the other hand, the operator
rnust find a way to halt the application, move the media, and restart,
then the time to reconfigure increases.
On RSX-llM-PLUS systems, TKTN prints a message at the console terminal
whenever an unrecoverable hardware error occurs. For example:
:~.,: l :t~

nl{ 1.:

.... -.. U f; r ".' c'

'./ ,...• f ,'\ i.'" :I f'

II.,':: f 1,3 ");: r c·

d f."'" : ,,::::.

C' r r ("If

These messages can alert an operator to an impending failure and allow
1:ime to issue the commands to remove the failing unit from the system.

15.7.2

Processor Failures

Although it occurs rarely in comparison with device unit
and
controller failures, a processor failure also halts system operation.
Note that, on multiprocessor systems, a crash or trap or other failure
may occur on a processor other than the faulty one.
If a processor fails, the system usually exhibits one of the following
symptoms:
•

The system traps to XDT or crashes.

•

The sanity timer expires for
(multiprocessor systems only).

•

The console lights on nonremote diagnostic consoles show
the system is halted in the Executive.

•

The system halts with no printouts or visual indicators.

one

processors
that

On multiprocessor systems, regardless of the cause of a processor
failure,
the recovery technique is straightforward and direct: you
rnust isolate and exclude the disabled processor and reboot the system.
rrhe memory configuration need not change unless you wish to perform
stand-alone diagnostics (see Section 15.8) on the failed processor.

15-32

RSX-llM-PLUS SYSTEM RECONFIGURATION
15.7.3

MKll Memory Box Failures

The two most cornmon causes of memory failures are uncorrectable
double-bit errors (parity errors) and loss of memory power.
If a user-state task encounters an uncorrectable memory parity error,
the system aborts the task and locks that portion of memory. The
Fixer t'3.sk (FXR) detects the parity errors and creates a distinct
segment in the task's region using the memory in which the errors were
detected. This segment is separate from the rest of the region and is
not used by other tasks. FXR is completely transparent to both users
and tasks.
If the Executive or a system-state task encounters an uncorrectable
parity error, the system prints the following message and then halts:

Also, the sanity timers on multiprocessing systems may expire.
Regardless of system state (user or kernel), a double-bit error causes
the memory' box hardware to light the UNCOR ERROR light (s) on the
respective memory box port controllers.
When an uncorrectable error halts the system, you
exclude that memory box and rebootstrap, as follows:

must

manually

Switch all ports of the faulty box off line.
If necessary,
use the thurnbwheel switches to properly address the remaining
memory box(es).
(The thumbwheel switches are used when the
failed box is box 0, which is the boot box, or when you want
to disable a memory box by changing the starting addresses of
the remaining boxes.)

Halt the
system.

processor,

initialize

it,

and

rebootstrap

When loss of power causes the memory failure, the system
system exhibits one or more of the following symptoms:

the

halts.

The

•

No lights or indicators are lit. This usually indicates
the outside power supply has failed.

that

•

No MEM POWER READY lights are lit on the memory box.
This
indicates that the memory box's power supply has failed or has
been powered down. Check the power switch on the Port A
controller to the box.

•

No MEM POWER READY lights are lit on one port of all memory
boxes.
This indicates that the CPU's power supply has failed
or that the CPU has been powered down. Note that the power
supply failure could have corne through an expander box or
through the far side of a switched bus currently switched to
the CPU.

In all of the above cases, if a CPU or a memory box has been switched
off but then switched back on before the memory batteries discharge,
the system usually recovers without rebootstrapping.
Otherwise,
follow the same two steps used when an uncorrectable error halts the
system.

15-33

RSX-IIM-PLUS SYSTEM RECONFIGURATION
15.8

STAND-ALONE MAINTENANCE FOR MULTIPROCESSOR SYSTEMS

em mUltiprucessing systems, when a device fails,

it is often necessary
to run diagnostic
tasks before servicing the device. However, the
d iagnost ic tasks regl: ire a proces sor for execut~i on.
Thus, to serv ice
rrost devices, you must r~move a processor from the system.
The following list gives the requirements for
reripheral devices:

testing

and

servicing

A processor must be available to execute the diagnostics
the peripheral.

Memory must be available for the diagnostics.

A mechanism to
available.

oad the Jiagnostic task into memory

must

for

The processor that executes the diagnostics must be connected to the
UNIBUS on which tl.e device to De tested resid,~s.
This implies that
other peripherals on that
bus r'ln will not be avai table to the
remainder of the system.
Therefore,
when determining the initial
system confiquration, you must ensure that duplicate devices are
located on distinct bus runs.
If the devic~ to be tested is on a
switched bus run, the switched bus can be connecLed to dny processor
to which it has access.
To make memory available for diagnostic tasks, ttJe usual procedure is
to logically remove a memory box from the running system and use the
box for diagnostics only.
This memory box is then switched manually
so that the processor to be used for diagnostics views the box with a
starting address of O.
Far loading a diagnostic into mem()ry, the RSX-IIM-PLUS multiprocessor
system provides the Diagnostic Loader task
(OLD).
DLD loads a
diagnostic Ilrogram into a partition in the memory box of the
d. i..agnostic
processor
(t'ne processor to whicr' the faIled device is
attached).
Diagnostic programs are system image files that you use to
b~st
the failed de'lices.
The partition is created and specified by
YI)U and is mapped by Program Logical Address Space (PLAS)
directives.
By default,
DLD clears the partition to the end after loading the
program.
The diagnos~ic is then run stand alone.
The steps for using OLD ace as

fO~.lows:

Use FLX to transfer the diagnostic program
from
the
diagnostic Lape or disk to a Files-II device attached t.o the
diagnostic processor.
(See the RSX-IIM/M-PLUS Utilities
Manua 1 for information on FLX.) Because the tape or disk is
inDOS-ll fOl-mat, use the FLX Image Mode switch
(11M)
to
convert the ile (the diagnostic progr.:un) to Fi.1es-ll format.
The file is Ln formatted binary format and has a file type of
. BIC or
. BIN.
(Note that binary format ted files are not
paLchable.)

Reconfigure :lour system so that you have a system with two
CPUs and two nemory boxes
(each box has 256K words of
memory).
Thp configuration would be as follows:
BOX 0

PORT A
paR']' B

ONLINE, START=OOO
OFFLINE

BOX 1

PORT A
POR'I' B

OFFLINE
ONLINE, START=OOO

:rST

Off line botn sides.
15-34

RSX-11M-PLUS SYSTEM RECONFIGURATION

Bootstrap RSX-llM-PLUS on CPA.

Set BOX 0 PORT A to ONLINE, START=OlO

Bring Box 1 on line.
diagnostic partition.

This memory
For example:

box

will

contain

the

Use the CON DISPLAY command to find out the base address
size of the memory box. For example:

and

CON>ONl. MKE,MK2:
6.

CON:> DIS f' FU'- L ATT FOR t1 K2 :
The base address of the partition will be the base address of
the diagnostic program.
7.

Create the diagnostic partition in the memory box by using
the
command
SET /PAR and specifying type DIAG.
This
partition will be devoted to diagnostic functions and should
begin at the location in memory that the diagnostic processor
will see as location 0 or the bottom of memory. For example:

>SET /PAR=JIMK:20000:1777:DIAG
This command creates a partition named JIMK with a base
address of 2000000 and consisting of l777(decimal) 32-word
blocks. The other processors see the memory box used for
diagnostics
as
starting at location 2000000, but the
processor running the diagnostic will see the box as starting
at location o.
Other partition types used with the SET /PAR command ensure
that the requested memory is within the system image area
(less than $SYSIZ), but DIAG ensures only that the memory
physically
exists.
For
the
other processor to run
concurrently with the diagnostic processor, the partition
must be larger than $SYSIZ.
8.

Use DLD to convert the binary formatted file into a bootable
system image file (patchable with ZAP; see the RSX-llM/M-PLUS
Utilites Manual) and then to load it into the partition. The
DLD command line has the following format:
Format
DLD>[partition][/HE]=filename[.typ][/qualifier]
partition
The partition created in the diagnostic processor's
memory box into which the diagnostic program will be
loaded. You must specify a partition name if you do not
use
the /NL switch (see below).
DLD produces a
"partition not found" error message otherwise.
If you
specify both a partition name and the /NL switch, the
switch overrides the name.
/HE
Provides a brief description of DLD's use and format.
typ
The file type for the diagnostic program.
can be .BIC, .BIN, or .SYS.
15-35

The file type

RSX-IIM-PLUS SYSTEM RECONFIGURATION
If the file type is .BIC or .BIN, DLD converts the file
into a system image file.
If you specify either file
type, but DLD cannot find the file, it searches for the
other file type before giving up.
If you do not specify
any file type, DLD first looks for a file with the
.BIC
file type and then for one with the .BIN file type.
If the file type is .SYS, DLD does not have to convert
the filej it is ready to be loaded into the memory box.
Iqualifier
One of the following:
INL

Inhibits loading of the diagnostic program
(DLD only creates the system image file).

INC

Inhibits clearing (zeroing) of any remaining
memory in the partition after the diagnostic
program has been loaded. The default is to
clear the remaining memory.

IOFF:n

Offsets the starting location of the load by
n times 32(decimal) words.
The area between
the beginning of the partition and the
beginning of the diagnostic is untouched.

ILl

Lists information about the partition and
the file:
the partition name (if you have
specified one), the base and size of the
partition,
and the new name of the system
image file (if converted).
Specifying this switch
gives
you
the
transfer address
(usually 200 or 1000) of
program.
The
transfer
the diagnostic
needed
to
initiate
the
address
is
diagnostic.

ILW

Accounts for the DOS-II link word that may
exist in bytes 0 and 1 of every input block.

Example

DLD>JIMK=TEST.BIN/LI
F' A F: TIT ION N A MF !

.J J MK

PARTITION BASF: 20000
FII.E NAME: TEST.SYS;l
TRANSFER ADDRESS:
?OO

SIZE:

:tTl?

(3?

WORD BIOrKS)

This command sequence converts the binary Eormatted diagnostic
file TEST.BIN into the system image file TEST.SYS.
DLD also lists
the transfer address of the file and other information about the
file and the partition.
9.

DLD loads the program into a
region that it creates in the
diagnostic partition.
The region is called DIAG and is the same
size as the partition. After the program is loaded,
DLD clears
any
remaining
memory from the partition
(unless otherwise
specified) .

10.

To run the diagnostic program, halt the processor (in this case,
CPB),
toggle in the transfer address of the program (from using
the ILl switch), and then push the START button to begin the
diagnost.ics.

15-36

RSX-11M-PLUS SYSTEM RECONFIGURATION
11.

Use the following MCR command
partition from the memory box:
::. l~: E t1 GV F

15.9

line

remove

the

diagnostic

(I T. A G/ PEl!

ERROR MESSAGES

The CON and HRC error messages consist
informa-tion in the following format:

one

lines

The

second

and

any

CON -- error message
(detail of error message)
The first line is the general error message.
succeeding lines define the error message.

In addi,tion to the description, the error messages may include
Directive
Status
Word error codes and I/O error codes.
For
explanations of these codes, refer to the RSX-IIM/M-PLUS and and
Micro/RSX I/O Operations Reference Manual.
A list of the CON and HRC error messages and a
each follows.

15.9.1

CON Error Messages

CON

Bad indirect command file specification
Explanation: The name of an indirect
was specified with incorrect syntax.

brief

command

explanation

file

(@filename)

CON -- Command execution error
command

Explanation: CON
cannot
process
the
specified
line.
(More specific information is also given.)
CON -- Command intent inconsistent with device state

EX.planation: An attempt was made to place on line a device
is in the marked for off-line state.

that

CON -- Command list is empty. Nothing to print
Ex:planation: The CON LIST command was issued when CON
bu.ffer was empty.

internal

CON -- Command syntax error
Explanation:
rules.

The command line does not conform to command syntax

The command is displayed with a question mark (?)
following the
last recognized keyword or parameter typed by the user. Check
the command description for correct format and reenter the
command line.
CON -- CONFIGURE Version nnn
Explanation:

This message is returned by the CON IDENT command.

15-37

RSX-llM-PLUS SYSTEM RECONFIGURATION

CON -- CON is unable to do an extend task operation to obtain pool for
a read of the system configuration.
Please ensure that a
checkpoint file has been allocated and reissue the CON command
Explanation:

Self-explanatory.

CON -- File open error/FILE=filename/No such file
Explanation: An invalid file specification was used with the
LIST command.
Check the device name and UFD and reenter the
command line.
CON -- HRC has timed out during initialization
Explanation: This message could indicate an error in the I/O
data structure.
Please verify that your device data structures
are correct.
CON -- HRC version nnn
Explanation:

This message is returned by the CON IDENT command.

CON -- Illegal command
Explanation: The command is not a valid CON command or
command was used illegally.

valid

CON -- Illegal keyword
Explanation: The keyword is not valid for the
command or a valid keyword was used illegally.

specified

CON

CON -- Initialization error
Explanation: CON was unable to properly initialize itself or its
links with the RD: driver and the HRC ... task. Verify that the
driver is loaded and that HRC ...
is installed.
CON -- Initialization request of HRC ... has failed. Please ensure that
HRC ... is installed.
Explanation:
CON

CON is unable to start HRC running.

Input error on input command file
FILE=filename
Explanation:
not read it.

The file you have specified exists, but

CON

could

CON -- Internal consistency error
Explanation: An error internal to either CON or HRC
has
occurred.
This is most often an internal addressing trap or a
malfunctioning driver.
Submit a Software Performance Report
(SPR) if the problem seems to be with DIGITAL-standard software.
CON -- Internal core pool exhausted
Explanation: CON has run out of internal pool space or was
invoked without checkpoint space first being allocated.
If out
of pool space, check the /MAXEXT setting.
(See the description
of the SET command in the RSX-IIM/M-PLUS MCR Operations Manual.)

15-38

RSX-llM-PLUS SYSTEM RECONFIGURATION
CON -- Maximum indirect command file depth exceeded
Explanation: You have specified that CON use an indirect command
file that exceeds CON's maximum nesting depth of three.
CON -- No device name matches select string
Explanation: You have specified with the DISPLAY command
10<Jical device name that does not exist in the system.

CON -- No HRC version information available
Explanation: This message is returned by the CON
if HRC is not installed.
CON

IDENT

command

No reconfiguration driver is available
Output to HRC is suppressed
Explanation:
thE~ system.

CON

The reconfiguration driver (RD:) is not

loaded

Open error on input command file
l!'ILE=filename
Explanation:

The input file you have specified does not exist.

CON -- Unable to assign command LUN
Explanation:
TI:: .

CON was unable to assign its command input

LUN

read

the

CON -- Unknown command error
Explanation:
command.

For

undetermined

reasons,

CON

cannot

CON -- Unknown device or invalid device specification
Explanation: The device specified for a command other than the
DISPLAY command is not known to the system. Consult the system
configuration for the proper name of the target device.
CON -- You must be privileged to modify the system configuration
Explanation: The command specified in the command line
issued from a privileged terminal.

15.9.2

must

HRC Error Messages

The following messages are related to HRC but also come from CON.
Attempt to quiet unit for controller failed
Explanation: When a controller with units on line is taken off
line, the on-line units are quieted and set to the marked for
on-line state. HRC attempts to access the unit when it does not
have context and can be taken off line. HRC makes 1000(decimal)
attempts to quiet the device.
If the device has not been
successfully accessed after the 1000 attempts, CON displays this
message.

15-39

RSX-llM-PLUS SYSTEM RECONFIGURATION
Attribute format error
Explanation: HRC received a read or write attributes QIO in
which the desired attributes were either incorrectly specified or
inappropriate for the specified device.
CSR for controller not present in I/O page
Explanation: An attempt was made to bring on line a controller
that does not exist in the current hardware configuration.
Device already linked
Explanation: A LINK command was issued for a
already linked to a CPU.

bus

run

that

Explanation: An UNLINK command was issued for a bus run that
not currently linked to a CPU.

Device not linked

Device is unknown in this configuration
Explanation: HRC has received a request to bring on line a
device that is unknown because it had been previously assigned a
CSR address of 160000 or less.
Executive or driver status change error
Explanation: During a controller on-line or off-line operation,
either
the
executive
controller
status
change routines
($ONKRB/$OFKRB) or the driver's controller status change routine
(xxKRB) were unable to change the state of the controller.
HRC ... can't take box offline. Not last box in memory
Explanation: An attempt was made to take off line a memory box
that
is
not at the end of the current physical memory
configuration.
HRC ... can't take box offline. Partition overmaps box
Explanation: An attempt was made to take a memory box off line,
but the memory is currently in use for a partition. The
partition must either be removed with SET /NOPAR or reduced in
size with SET /TOP (see the RSX-IIM/M-PLUS MCR Operations
Manual) .
HRC ... detected I/O data base consistency error
Explanation:
detected an
base.

During the course of taking a device off line, HRC
error in the structure of the system device data

HRC ... internal addressing error
Explanation: An odd address trap (or other software trap) has
occurred within HRC.
This may be due to a bug in HRC or an
inconsistency in the system's I/O data base.

15-40

RSX-IIM-PLUS SYSTEM RECONFIGURATION
HRC .•. internal tables insufficient for this system
Explanation: HRC creates a list of units on the stack when
taking a controller off line. This message is produced if HRC
encounters a controller with too many units to create a list.
The maximum number of units for each controller is defined by the
symbol .MXCTL in HRPRE and is currently set to 256(decimal).
HRC ... invalid device specification
El!:planation: HRC received a request to bring memory on line, but
the specified device was not a memory box.
HRC •.. request format error
Explanation: HRC received a QIO in which the format of the
parameters was incorrect.
If the issuing task for the request
was CON, this error implies a software fault.
HRC ... unable to access device to size drive
Ex:planation: When certain types of device units are brought on
line, HRC must "size" the drive (for example, to determine if a
DB:-type device is an RP05 or an RP06). This message is issued
if the sizing process fails for any reason (for example, the
drive is not powered up when the CON ONL command is issued).
HRC ... unknown error from online/offline call
Explanation: HRC received from the driver on-line/off-line call
an unsuccessful status that is not one of the normally expected
re~turn codes.
Invalid device descriptor
Explanation: HRC received a request to take a port off line, but
the port description was invalid.
Memory box parameter error
Explanation: An attempt has been made to bring on line a set of
memory boxes whose current physical configuration does not allow
the specified command to be executed.
Offline controller failure
Explanation: HRC attempted to take a controller off line, but
the controller did not properly change state.
However, no
explicit error was recognized.
Offline unit failure
Explanation: HRC attempted to take a unit off line, but the unit
did not properly change state. However, no explicit error was
rE!cogni zed.
Paramet~er

error

Explanation: HRC received a request to link a bus run, but the
dE!vice specified was not a bus switch. If the requesting task
was CON, this probably implies a software fault.

15-41

RSX-llM-PLUS SYSTEM RECONFIGURATION

Syntax error
Explanation: HRC received a command to
device that is not a CPU.

link

bus

run

Timeout on unit quieting operation
Explanation: HRC was unsuccessful in attempting to "catch" a
unit in its quiet state to take it off line after lOOO(decimal)
attempts.
Unable to access bus run
Explanation: HRC was unable to create or remove the vectors for
a device because the device's bus run was inaccessible. Because
HRC checks bus run status and uses the marked for on-line state
for devices on off-line bus runs, this message probably implies a
software fault.
Unable to switch unit from the current controller
Explanation:

This error is displayed for two reasons:

HRC attempted to take off line the controller for a
which the bus switch is currently switched.

HRC attempted to take off line a controller
whose access path cannot be changed.

port

(with

units)

Unable to take unit with context offline
Explanation: An attempt was made to take one
units off line:

•

A mounted Files-II device

•

An attached device

•

A logged-in terminal

•

A bus switch whose bus run is currently linked

•

A m'?mory box 'lni t

whose

rrH~mory

15-42

the

is curren! lyon Ilne

following

CHAPTER 16
RSX-IIM-PLUS I/O QUEUE OPTIMIZATION

I/O Queue Optimization is used to improve the throughput of the disk
subsystem used in your RSX-llM-PLUS system.
Disk throughput is
improved by making the most effective use of the list of I/O requests
in the queue for a particular disk device. The I/O queue for the
device is scanned by I/O Queue Optimization and after each request is
examined,
the best request is dequeued and passed to the I/O driver
for processing. How Queue Optimization determines which I/O request
is best, depends on which method of I/O Queue Optimization is used.
There are three methods of I/O Queue Optimization available (you can
also choose not to have I/O Queue Optimization):
1.

Nearest Cylinder

Elevator

Cylinder Scan

The me!thod that serves you best depends
on
your
processing
environment.
All three methods attempt to minimize head-seek time,
which decreases the seek-time component of the file service time.
Because' I/O Queue Optimization works by optimizing requests in the
queue, optimization happens only when I/O requests are present in the
queue.
If the system loading is such that there are few,
if any,
request.s in the queue, little optimization is achieved.
Without. I/O Queue Optimization, the operating system groups the I/O
request.s in the queue, by priority, on a first-in/first-out basis.
The highest priority requests appear first in the queue and are
processed in sequence. With I/O Queue Optimization, the I/O requests
within priority groups are examined and the request having the
appropriate disk address is chosen as the next I/O operation. The
highest. priority requests are still
serviced
first;
however,
throughput is increased by advantageous reordering of requests within
priority.
In SOmE! cases, I/O Queue Optimization may
operati.on by reducing erratic head movement.

16.1

provide

smoother

disk

INITIATING OPTIMIZATION

The MCR SET /OPT command is used to initiate I/O Queue Optimization.
The parameters in this command are used to specify the disk device,
the met~hod of opt~miza tion, and a fairness count limit for passed over
I/O rE!quests.
These parameters are explained in detail in following
paragraphs.

16-1

RSX-IIM-PLUS I/O QUEUE OPTIMIZATION

The SET command is only for privileged users.
Nonprivileged users can
use this command only to display the optimization status of devices in
the system.
Format:
SET /[NO]OPT[=ddn:opttype:fairnesscount.]
Parameters
ddn
The disk device requiring optimization:
DBn
DRn
DMn
DLn

RP04,RP05,RP06 pack disks
RM02,RM03,RM05,RM80,RP07 pack disks
RK06 and RK07 cartridge disks
RLOI and RL02 cartridge disks

opt type
The type of optimization needed:
NEAR [EST]

Initiates Nearest Cylinder method; next
picked is the closest to current request

ELEV[ATOR]

Initiates Elevator method;
requests are processed
first
in one direction along the disk and then in
the reverse direction

CSCAN

Initiates Cylinder
processed in only
(lowest to highest)

Scan
method;
one direction

request

requests
are
along the disk

The default is NEAREST.
fairnesscount
A limit on the number of times the most
request is passed over (see Section 16.2.1).

unsatisfactory

I/O

The default is 10.

16.1.1

Displaying Optimization Status

You can display the optimization status for all devices in the system
that are currently using I/O Queue Optimization by entering the
following:
>~3FT

/(]F'T

This displays status in the following form:
OPT=ddn:opttype:fairnesscount
For example:
() F' T ::" nH 0 N E A I~: : 1. 0 +
nr· T ::: DB 1. F LEI.,) : 5 +
[) F' T :::: nB ~'.) CB CAN : 8 •

16-2

RSX-llM-PLUS I/O QUEUE OPTIMIZATION
You can also display which
Optimization by entering:
::- ~:) F T

devices

are

not

using

I/O

Queue

d POP T

This displays status in the form:
NOOPT=ddn:
For example:
r·j I )

nF' 'r : : 'ill~: 1. ;

Nonprivileged as well as privileged users can display status.

16.2

SELECTING THE TYPE OF OPTIMIZATION

Selecting the correct optimization method is dependent upon the I/O
processing environment in which your application is running, the
physical location of data on the disk drive, and how often tasks
access certain data areas.
A general guideline is to try the default first.
(This initiates the
Nearest Cylinder method with a fairness count limit of 10.) Then
compare the difference in throughput by timing the application run
time against a suitable clock.
For a closer look at disk activity and
throughput,
use Resource Accounting (see Chapter 17).
Resource
Accounting provides this data under the heading DEVICE STATISTICS in
the output from the Resource Accounting transaction file.
The default (NEAREST, and a fairness count of 10)
is an average
setting and,
in most cases, should improve I/O throughput. As you
become more familiar with the I/O load and data organization on the
disk in your application, you can make adjustments by changing the
fairness count limit or by using one of the other methods of I/O Queue
Optimization (see the sections following).

16.2.1

Adjusting the Fairness Count Limit

When using I/O Queue Optimization, you should watch for increased
waiting time.
I/O requests to some data areas may have slower than
normal access times, because Optimization categorizes
them
as
unsatisfactory.
When this happens, Optimization passes over these
requests for a better choice, keeping the unsatisfactory requests in
the queue longer. This may cause a decrease in performance for some
tasks even though overall system performance has improved.
To counteract increased waiting time and acquire a better balance, you
can adjust the fairness count limit. This places a limit on how many
times an I/O request can be passed over. Optimization increments the
fairness count for the first I/O request in the queue whenever that
request in the queue is passed over. When the fairness count for an
I/O request reaches the limit indicated with the SET command, the
request is 6equeued and the fairness count is cleared.
Decreasing the fairness count limit reduces waiting time but decreases
the overall throughput initially gained with the higher count.
If you
find you must decrease the fairness count limit,
try
another
optimiz,ation method.
It may be more applicable to your situation.

16-3

RSX-llM-PLUS I/O QUEUE OPTIMIZATION
16.2.2

Nearest Cylinder Method

The Nearest Cylinder optimization methoq processes the I/O request
that is closest to the current cylinder.
In general, this method is
effective for both long and short I/O queues.
There may be an
increase in waiting time, however, and this may be unacceptable in an
interactive environment. To remedy this, reduce the fairness count
limit (which reduces the throughput) or try one of the other
optimization methods.
(The Elevator method may be the next best
choice. )

16.2.3

Elevator Method

The Elevator optimization method processes I/O requests like an
elevator.
It processes requests as it moves in one direction along
the disk until it reaches the last request in that direction.
Elevator then changes direction and processes requests in that
direction. This method is effective if there are many I/O requests
outstanding.
Also, waiting time tends to be less with the Elevator
method than with the Nearest Cylinder method.
The Elevator method favors the center of the disk.
Requests are done
as they are passed, and the center of the disk tends to be passed over
twice as often as the periphery. Therefore, a task that has a number
of requests located in the center of the disk tends to have faster I/O
than a task with requests at the periphery.

16.2.4

Cylinder Scan Method

'The Cylinder Scan optimization method operates like the Elevator
method except the Cylinder Scan method processes I/O requests only
while passing in one direction along the disk. The direction is from
the lowest cylinder number to the highest cylinder number. This
method is most effective if each task tends to do I/O to a localized
area on the disk.
It results in a more even distribution of I/O among
tasks.

16.3

ERROR MESSAGES

SET -- Privileged conunand
Nonprivileged users can display status only.
SET -- Feature not supported
User tried to initiate Optimization for a disk device
not support Optimization.

that

does

SET -- Device not in system
User tried to initiate Optimization for a disk device that is not
mounted in the system.
SET -- Illegal keyword value
User specified a fairness count higher than l28(decimal).

16-4

RSX-IIM-PLUS I/O QUEUE OPTIMIZATION
SET -- Invalid keyword
User tried to use an invalid ~eyword.
SET -- Device offline or privileged diagnostic
User tried to initiate Optimization for an off-line device.

16-5

CHAPTER 17
RSX-IIM-PLUS RESOURCE ACCOUNTING

17.1

INTRODUCTION

RSX-ll~l-PLUS

Resource Accounting is a system generation option that
a transaction file of system usage information. Accounting
gathers data for both the user and the system. The data allows the
billin9 of individual users for the resources used, as well as the
measuring of overall system usage.
providE~s

Some of the system usage information gathered by
and saved in the transaction file is as follows:

Resource

User Data
•

Session identification, terminal, and account number

•

Billing stop date and time

•

CPU usage time

•

Tasks active at time of logout or crash

•

Number of tasks run

•

Number of directives and OIOs issued

•

Status at logout or crash

Task Data
•

Session identification, terminal, and account number

•

Disk overlay loads

•

Number of times checkpointed

•

Number of times context has been loaded

•

Highest running priority

•

Task begin time and end time

•

CPU usage time

•

Number of directives and OIOs issued

•

Status at logout or crash

17-1

Accounting

RSX-IIM-PLUS RESOURCE ACCOUNTING

System Data
•

Accounting start date and time

•

Accounting stop date and time (0 if system crashes)

•

Shutdown code

•

Transaction file 10, sequence number, and device

•

Last scan date, time, and scan rate in seconds

•

Total CPU time and total CPU zero intervals

•

Total number of tasks executed

•

Total number of logins

•

Number of current users

•

Number of checkpoints

•

Number of Shuffler runs

•

Number of directives issued

•

Number of QIOs issued

User name, 10, terminal, and account number

•

Illegal password

Device Allocation, Deallocation Data, or Dismount Data
•

Session 10, terminal, and account number

•

Allocation or deallocation date, time, and device

Device Mount
•

Session 10, terminal, and account number

•

Mount date, time, and device

•

Volume label for Files-II mounted device

•

Type of mount (foreign, shared, and so on)

•

Owner UIC

•

Volume protection code

•

Name of ACP for device

Print Job Data
•

Session 10, terminal, and account number

•

Print job date and time

•

Job name and page count

17-2

RSX-IIM-PLUS RESOURCE ACCOUNTING

•

Number of files printed, printer device, and forms number

•

Job priority

Card Reader Job Data
•

Session 10, terminal, and account number

•

Batch or print job name

•

Number of cards read

•

Reader device name and number

System Time Change

• Old Time
• New Time
Device Usage Data

• I/O counts
• Error counts
• Tuning information
There are several ways to access the system usage
contained in the transaction file.
They are as follows:
•

information

The SHOW ACCOUNTING commands (see Section 17.3):
SHOW
ACCOUNTING/INFORMATION
displays
information about specific terminals.
SHOW ACCOUNTING/TRANSACTION FILE
version of the transaction fIle.

system

generates

usage
formatted

•

A report program written by DATATRIEVE-ll (see Section 17.4)

•

User-written analysis programs (see Section 17.5)

Resource Accounting gathers system usage information by collecting the
data in account blocks in secondary pool and writing each account
block as a record in the transaction file. These account blocks are
as follows:
•

Task Account Block (TAB)

•

User Account Block (UAB)

•

System Account Block (SAB)

•

Transaction account blocks

For a description of account blocks, their structure, and how Resource
Accounting uses them, see Section 17.6.
The following sections describe the Resource Accounting commands.
Paramet:ers are separated by spaces, you may abbreviate, and you are
promptE~d
for missing parameters.
All
commands,
except
SHOW
ACCOUNTING/INFORMATION, are privileged.
(Slashes in SET and SHOW
commands are optional.)

17-3

RSX-IIM-PLUS RESOURCE ACCOUNTING

'I'he Resource Accounting commands are:
START/ACCOUNTING

Starts
up
subsystem

the

Accounting

STOP/ACCOUNTING

down
Shuts
subsystem

the

Accounting

SET ACCOUNTING

Changes parameters in a started
Accounting subsystem

SHOW ACCOUNTING/INFORMATION'

Displays Accounting information
about a specific terminal

SHOW ACCOUNTING/TRANSACTION_FILE

Converts the transaction file
to a readable format so it can
be displayed on a terminal or
put in a file

SHOW ACCOUNTING/DATATRIEVE

Converts a transaction file
a file that is readable
DATATRIEVE-ll.

17-4

to
by

RSX-IIM-PLUS RESOURCE ACCOUNTING

START/ACCOUNTING
17.2

CONTROL COMMANDS

17.2.1

START/ACCOUNTING Command

The START/ACCOUNTING command starts up the Accounting subsystem.
The
SYSLOG and ... ACC tasks must be installed before you issue the
START / A.CCOUNTING command.
I f you do not supply
the
optional
paramet,ers, they assume defaults.
Format
START/ACCOUNTING [parameterl][parametern]
Paramet~er

FILE:fi.lespec
This file specification is the name of the transaction file that
Accounting creates to store the data. You can name the file with
this parameter or accept the default, LB:[1,6]ACNTRN.SYS.
EXTEND SIZE:value
This value is the size of the initial allocation for the
transaction file and for each extension when it is needed. The
value can be any reasonable amount. If there is low Accounting
activity,
a small extension size is adequate because few
extensions are required and overhead is low.
If Accounting
activity is high, a larger ext"ension size lowers the overhead if
disk space is available for the larger extension.
The default value is 10(10) blocks.
POOL RESERVE:decimal value
This value is the number of blocks of secondary pool that
Accounting must leave free after each allocation. If Accounting
cannot leave this amount free,
the allocation will fail and
prevent the swamping of secondary pool.
The default is a quarter of the total secondary pool
of the default is recommended.

size.

Use

SYSTEM._STATISTICS :yes/no
This parameter specifies to Accounting whether or not
to
accumulate system-wide statistics.
System-wide statistics are
the contents of the accumulation fields in the System Account
Block. These fields are as follows:
•

B.CPU Total CPU time used

•

B.DIR Total directive count

•

B.QIO Total QIO$ count

•

B.TAS Total task count

The default is yes.

17-5

RSX-IIM-PLUS RESOURCE ACCOUNTING

START/ACCOUNTING (Cont.)
STATISTICS_SCAN[:value]
This value specifies a scan ra~e for the collection of device
statistics.
These device statistics are used mainly to measure
seek-optimization parameters.
They also
provide
excellent
information
on
disk activity and throughput.
The device
statistics are collected either once or periodically.
To
indicate a one-time only collection, no value is specified. To
collect statistics periodically, the value specifies the rate in
minutes
(nM) or seconds (nS). The default value is one hour if
SYSTEM STATISTICS:YES is specified.
If STATISTICS SCAN is specified, SYSTEM STATISTICS must
be
specified.
This restriction does not apply to a one-time only
request.
If a value of 0 is specified or SYSTEM STATISTICS:NO is
specified, this feature is turned off. The example below shows
the type of statistics collected in a transaction file.
SCAN RATE:decimal value
This value is the time interval between the periods when
Accounting writes the SAB and active UABs to the scan file called
LB:[1,6]SYSSCAN.TMP for protection against loss in event of a
system crash.
The value can be supplied as "nM" or "n" for n
minutes, or "nS" for seconds.
If you specify 0, no scanning is
done:
therefore,
if the system crashes, the active UABs and the
SAB are not recorded in the transaction file and the data is
lost.
The default value is 5 minutes.
If Accounting finds a scan file when you start,
it outputs a
crash transaction and copies the data in the scan file to the new
transaction file. A copy of this crash transaction, followed by
the transaction file,
is shown as the output of the SHOW
ACCOUNTING/TRANSACTION FILE
command
in
Section
17.3.2.
Accounting copies all the old data before it writes the startup
transaction and before it processes any new data.
When you stop Accounting, the scan file is deleted.
CRASH_REASON: yes/no
If you enter "yes" and Accounting is started after a crash that
occurred when scanning was active, Accounting prompts you to
enter a reason for the crash. The reason can be as many as 60
characters in length and is stored in the Crash Recovery
Transaction Block. Accounting prompts for "reason for crash"
when Accounting is restarted.
If the system did not crash, no
prompt occurs.
If you enter "no", a prompt never occurs: the default is no.
TASK:yes/no
If you enter "yes," task accounting is
initiated.
Task
accounting gathers data on individual tasks running in the
system. You can run task accounting when the system is running
at peak load times and the task accounting data can be analyzed
on a per task basis to identify heavy resource users.

17-6

RSX-llM-PLUS RESOURCE ACCOUNTING

START/ACCOUNTING (Cont.)
If you enter "no," task accounting is stopped.
no.

The

default

Task accounting should only be specified when you absolutely need
task accounting data.
The reason is that task accounting
requires substantial disk space because the transaction file can
become quite large.

Example
The type of device statistics collected by Resource Accounting is
shown in the following output from a transaction file:
Device

St~tistics

Itt? V i, ~t?
Time of Device Statisti~s ::: 1S-DEC-a5 16:27:23
Words Transferred Count:::: O.
IO Count::: O.
Soft Error Count::: O.
Soft Error Limit::: 8.
Hard Error Count::: O.
Hard Error Limit:: 5.
C~ljnder Crossed Count::: O.
Current F~irnt?ss Count
Fairness Count Limit:: to.

flR1:

Device Statistics
Timt? of Device Statistics ::: 15-DFC-8~ 16:27:23
Devi~t?::: flR2:
IO Count :;:: 13832.
Words Transferrf~d Count::: 9002804.
Soft Error Limit::: 8.
Soft Error Count::: O.
Hard Er'por Limit::: 5.
Hard Error Count:: O.
C~linder Crossed Count::: 1053
Currt?nt Fairnpss Count
O.
Fairness Count '-i.mit :: to.
Device Statistics
Time of Devi~e St~tistics ::: 15-DEC-aS 16:27:24
Devi~t?::: DR3:
IO CC)lJrrt, :: 68490.
Words Transferred Count::: 80640306.
Soft Error Limit::: 8.
Soft Error Count:: O.
Hard Error Limit::: 5.
Hard Error Count:: O.
C~linder Crossed Count::: 313.
Current F~irness Count
7.
Fairness CrJunt I_inlit": 1.0.

Some definitions are as follows:
•

10 COUNT - The number of I/O requests.

•

WORDS TRANSFERRED COUNT - The number of words transferred.

•

SOFT ERROR - A recovered error.

•

HARD ERROR - A nonrecovered error.
(See the RSX-IIM/M-PLUS
Error Logging Reference Manual for more information about hard
and soft errors.)

•

CYLINDER CROSSED COUNT - The number of cylinders crossed while
accessing data.
This data can be analyzed for I/O Queue
Optimization purposes.

•

FAIRNESS COUNT - A Queue Optimization parameter that indicates
how many times an I/O request was passed over (see Chapter
16).

17-7

RSX-IIM-PLUS RESOURCE ACCOUNTING

SET ACCOUNTING
17.2.2

SET ACCOUNTING Command

This command allows you to change the value of parameters specified
when Resource Accounting was started with the START/ACCOUNTING command
or previously modified with a SET command.
(A transaction is written
containing the old value and the new.)
The following options can be
running:

changed

while

Resource

Accounting

Defaults

• The file that transactions are written to
• The size of the extensions
• The scan rate for the scan file
• The scan rate for collecting device statistics
• The state of task accounting (on or off)
Format

SET ACCOUNTING/[parameterl] [parametern]
Parameter

FILE[:filespec]
Changes the file that transactions are written to.
the current file specification, if not specified.
EXTEND SIZE:value
This value changes the size for each extension of the transaction
file specified in the START/ACCOUNTING EXTEND SIZE parameter.
STATISTICS SCAN:value
This value
statistics.

changes the scan rate
for
A value of 0 stops this option.

collecting

device

SCAN RATE:value
This value changes the scan rate for the scan file specified
the SCAN RATE parameter. A value of 0 stops this option.

rrASK:yes/no
If you enter "yes," task accounting is started.
When specified, task accounting creates task account blocks for
all active tasks in the system. All data, for each task, is
gathered starting at this time.
If you enter "no," task accounting is stopped.

17-8

RSX-IIM-PLUS RESOURCE ACCOUNTING

SET ACCOUNTING (Cont.)
When specified, task accounting on a per task basis is terminated
and the data for all active tasks is written to the transaction
file.
The only exception is tasks that have a CPU time limit
specified, because the data is necessary for the time limit to be
checked. The data for these tasks is written to the transaction
file when the task exits.

17-9

RSX-IIM-PLUS RESOURCE ACCOUNTING

STOP/ACCOUNTING
17.2.3

STOP/ACCOUNTING Command

This command shuts down the Resource Accounting subsystem.
The
parameter is provided to indicate why the shutdown is occurring and
must be entered with the command.
Accounting puts the reason for
stopping into the System Account Block.
Formats

STOP/ACCOUNTING reason
STOP/ACCOUNTING CLEAN UP
Reason
MAINTENANCE
You can use this reason
maintenance.

when

you

stop

Accounting

for

system

REBOOT
You can use this reason if you must rebootstrap the system.
SCHEDULED SHUTDOWN
You can use this reason when the system is being shut down
used for other purposes where Accounting is not applicable.

SHUTUP
The SHUTUP program uses this reason as a default because
no means of determining a shutdown reason.

has

You can use this reason when any of the
adequate.

are

not

OTHER
above

reasons

The STOP/ACCOUNTING CLEAN UP command has a special use.
It must be
used if the SYSLOG task aborts or Accounting encounters a fatal error.
This command cleans up all the data structures to allow Accounting to
restart successfully.
Accounting accepts this command only if it is
necessary (after an Accounting failure or abort).
When you use this command, the system assumes all Accounting data in
memory to be invalid and deal locates the data back to secondary pool
without writing it to the transaction file.
Note that if the
Accounting data structures are corrupted, the system may crash while
it attempts to deallocate secondary pool.
You can restart Accounting normally after you issue this command.

17-10

RSX-IIM-PLUS RESOURCE ACCOUNTING

SHOW ACCOUNTING/INFORMATION
17.3

SHOW COMMANDS

17.3.1

SHOW ACCOUNTING/INFORMATION Command

This command displays on the terminal from which the command was
issued
the
Accounting information for the specified terminal.
Nonprivileged users can receive only their Accounting data.
A
privileged user can obtain any Accounting data.
Format
SHOW ACCOUNTING/INFORMATION[parameter]
Parameter
TTn:
If you specify TTn:, this command displays the Accounting data
for the specified terminal. A privileged user has access to the
Accounting data of any terminal on the system.
A nonprivileged
user can only get his own data. The default terminal is TI:.
If you enter no terminal name, the Accounting
terminal issuing the command is displayed.

data

If you specify CO:, the Accounting data
running is displayed on the terminal.

the

CO:
of

the

system

tasks

If you specify SYS, the current system totals
the terminal.

are

displayed

SYS
on

TASK=ta.skname
Shows Accounting data for the specified task
maintaining task accounting.

17-11

the

system

RSX-IlM-PLUS RESOURCE ACCOUNTING

SHOW ACCOUNTING/TRANSACTION_FILE
17.3.2

SHOW ACCOUNTING/TRANSACTION_FILE Command

The SHOW ACCOUNTING/TRANSACTION FILE command converts the transaction
file into a readable format~
It either displays this file on a
terminal or writes it into another file.
The SHOW ACCOUNTING/
TRANSACTION FILE command uses the current transaction file as the
default fife.
(When Accounting is not running, there is no default
file. )
Format
SHOW ACCOUNTING/TRANSACTION_FILE[:inputfilespecJ outputfilespec
Parameter
inputfilespec
The input file is the transaction file to be read. If you do not
specify an input file, the current transaction file is used.
out~putfilespec

The output file can be either a terminal (specified as
TI:) or a file of your choice.

TTn:

Notes
UIC [126,10J on the distribution kit includes the source code for
the SHOW ACCOUNTING/TRANSACTION FILE command to serve as an
example for how to read the file.- Note that the record size in
the file is equal to the transaction length. The only exception
to this is the Accounting startup transaction that only occurs
once and is 512(10) bytes long. The startup transaction consists
of a header only, but its size is increased to 512(10) bytes to
force a file extension. See Section 17.6 or [126,10J ACNDF.DOC
on the distribution kit for the format of this file.
Example
The output of the SHOW ACCOUNTING/TRANSACTION FILE command is a
formatted display of the transaction file. -The default file is
the transaction file named in the START/ACCOUNTING command. This
example of output of a SHOW ACCOUNTING/TRANSACTION_FILE command
is keyed to the following explanatory comments:
M~COUNTING

DAHl -- CUF:F:FNT FIIF

SYSTEM CRASH RECORD
TIME OF LAST SCAN = 7-1)rC-85 10:48:17
RESTART TIME = 7-DEC-85 19:~R:15
I(E(.I~~nN

::::

17-12

1]-1)F[-85 16:56:04

SCAN

RATF (SFC)

300.

RSX-IIM-PLUS RESOURCE ACCOUNTING

SHOW ACCOUNTING/TRANSACTION_FILE (Cont.)
USER _.. ALPHA
P 6)
ACCOLINT ::: 1.
SESSION ID ::: F1143
TI: = TT40:
L.OGIN UIC :::; [7,1.1.1J
LOGGE"O ON
7-DEC-8S 08:58:53
BILLING STOPPED::: 7-DFC-85 10:48:17
LOGGED OFF = 00-000-00 00:00:00
CPU ~ 4461.
T~SKS ACTIVE; 1.
TASKS RUN::: 95.
(HOS ::: 621.5.
DIRECTIVES::: 1.0240.
STATLJS
ACT
CRH

USER - SYSTEM TASKS
SESSION ID == $SYO
TI: =.CO:
ACCOUNT::: O.
LOGON UIC::: r:O,OJ
LOGGED ON::: 6-DEC-8~:'i 15:48:16
LOGGED OFF::: 00-00-00 00:00:00 BILLING STOPPED::: 7-DEC-85 10:48:17
CPU;;;; 1.03866.
TASKS ACTIVE .;: 9.
TtlSKS RUN:::: 1>01.
alaS::: 128967.
DIRECTIVES: 667250.
STATUS
ACT
CRH

TOTAL SYSTFM STATISTICS
I~CCOUNTING STARTED == 6-DEC-85 15:48:16
(~CCOl.lNTINn STOPPED =:: 00--000-('0 00:00:00
SHUTDOWN CODE:::: 0
n;;ANS FlU::: II) :::: 1.422
SFO NIJM :::: 1
"OEVIr:E ::: DB1:
rIME OF LAST S~AN = 7-DFC-85 1.0:48:1.7
SCAN RATF (SFC) ::: 300.
TOTAl... CPU .::: 411'::'~64.
7.F.F:O CPU INTERVAI.S .;: 3746,<SS.
TOTAl TASKS ".: 323t..
TOTAl.. L.O(WNS ::: 60.
Cl.JRI~FNT I.JSFRS :::: ??
r.HEr:KPOINTS :::: 23.
SHF RUNS::: O.
DIRECTIVES = 2373564.
OIOS
55601~.
ACCOUNTING STARTUP
ACCOUNTING STARTED

7-DFC-8~

19:58:1.6

TI: ::: TT26:
ACCOUNT::: O.
TIME = 7-"OEC-85 19:58:35

TI: ::: TT55:
ACCOUNT::: 1.
TIME = 7-DEC-85 20:05:44

DEVICE MOUNT
T I: :::: TT5~i:
SESSION ID ::: F112
ACCOUNT ::: 1.
TIME ~ 7-0EC-A5 20:06:37
"OEVlr.E = DR1:
VOL ID ::: WELCOMEBACK
OWNER UIC
[0,0)
ACP NAME :::F1.1ACP
VOL. PROT MASK ::: 0
USFR -- ALPHA
SESSION ID ::: Fl12
TI: = TT55:
ACCOUNT::: 1.
LOGON UIC = (7,111]
I_OGGED ON
7-DEC-85 20:05:44
LOGGED OFF
7-DFC-85 20:06:43
BILlING STOPPED = 7-DFC-85 20:06:43
CPU = 141.
T~SKS ACTIVE ~ O.
T~SKS RUN ~ 17.
DIRECTIVES
472.
OIOS = 166.

17-13

RSX-IIM-PLUS RESOURCE ACCOUNTING

SHOW ACCOUNTING/TRANSACTION_FILE (Cont.)
LOGIN - OMEGA
D
SESSION ID = RXP3
LOGON UIC = [7,71J

TI: = TT37:
ACCOUNT = 4.
TIME ~ 7-DEc-a5 20:08:11

DEVICE ALLOCATION
SESSION ID = RXP4
TI: = TT37:
ACCOUNT
TIME:: 7-DEC-85 20:09:12,
DEVICE = DL.O:
LOGIN - THETA
D
SESSION ID = SPR5
LOGON UIC = [7,327J

TI: = TT55:
ACCOUNT = O.
TIME = 7-DEC-85 20:09:14

DEVICE MOUNT
SESSION 10 = RXP4
TI: = TT37:
ACCOUNT = 4.
TIME = 7-DEC-85 20:09:15
DEVICE
DLO:
VOL ID
OWNER UIC = [7,107J
ACP NAME = TSTACP
VOL. PROT MASK
DEVICE DEALLOCATION
SESSION ID = RXP4
TI: :: TT37:
ACCOUNT
TIME::: 7-DEC-a!) 20:09:15
DEVICE = DLO:

USER - SYSTEM TASKS
SESSION 10 = $SYO
TI: = CO:
ACCOUNT = O.
LOGON UIC = (O,OJ
LOGGED ON
7-DEc-a5 19:58:16
LOGGfD OFF = 00-000-00 00:00:00
RILLING STOPPED = 7-DEC-85 20:13:21
CPU;;:: 1603.
TASKS ACTIVE:: 4.
TA~KS RUN = 64.
DIRECTIVES = 2986.
TOTAL SYSTEM STATISTICS
ACCOUNTING STARTED = 7-0fC-85 19:58:16
ACCOUNTING STOPPED::: 7-0EC-85 20:13:21
SHUTDOWN CODE = 4
TRANS FILE HI = 205
SEQ NUM = 20
DEVICE = rIRO:
STATISTICAL SCAN RATE (SEC.) = 3600.
FILE EXT. SIZE = 10.
TIME OF LAST SCAN = 7-DEC-85 20:13:17
SCAN RATE (SEC) = 300.
TOTAL CPU = 4260.
ZERO CPU INTERVAI..S = 3063.
TOTAL. TASKS = 243.
TOTAL. LOGONS = 7.
CURRENT USERS;;:: 1.
CHECKPOINTS;;:: O.
SHF RUNS = O.
DIRECTIVfS = 10241.
QIOS = 4946.

Ct
~

The crash reason appears here if Accounting prompts you for a
reason for the crash. The prompt occurs only if you answered yes
to the CRASH REASON parameter in the START/ACCOUNTING command.
To minimize loss of data, Accounting writes the SABs and
currently active UABs to a temporary file every n seconds or
minutes unless you specify a scan
rate
of
in
the
START/ACCOUNTING command.
The process of writing this file is
called a scan.
When you restart Accounting, it copies any
existing temporary file of Accounting data into the Accounting
file now starting.
If the scan rate is 0, the SABs are
memory-resident until you stop Accounting or the system crashes.

17-14

RSX-IIM-PLUS RESOURCE ACCOUNTING

SHOW ACCOUNTING/TRANSACTION_FILE (Cont.)
Also, the currently active UABs are memory-resident until a user
logs out. Therefore, if a crash occurs with the scan rate at 0,
all the SAB and current UAB data is lost.

The User Account Block (P. Alpha) shows a logged out date and
time of 0 because the system crashed. There mayor may not be a
"status" line as the last line of the User Account Block.
The
status line indicates the bit setting of the status mask byte
(B.STM) in the UAB. Three of the bits have external importance
and cause this line to appear if they are on. These bits are as
follows:
ACT (BS.ACT)

Indicates that the UAB was written to the
file while still active (all activity had not
ceased).
This can happen when UABs are
copied from the scan file, or when all the
data structures are written out
because
Accounting has stopped.

LGO (BS.LGO)

Indicates that the user has logged off with
tasks remaining active or with clock queue
requests pending.

CRH (BS.CRH)

Indicates that this UAB came from the scan
file and was copied into the transaction file
when Accounting was started after a system
crash.

The TOTAL SYSTEM STATISTICS block contains the shutdown code as a
digit in the range 0 through 5. These digits have the following
meanings:

Accounting not stopped due to crash

Maintenance

Rebootstrap

Scheduled shutdown

Shutup

Other

The ZERO CPU INTERVALS field shows the possible error in the CPU
time measurements. The error occurs because the system clock is
usually run at 60 Hz and is slower than the context switch time
of the Executive.
Therefore, a task can sometimes execute for
"zero" ticks, because the time needed for its execution is less
than the resolution of the clock. Resource Accounting rounds
each zero tick to one-half tick of CPU time and counts them. The
ZERO CPU INTERVALS field contains the count of the number of zero
ti.cks that have occurred.

17-15

RSX-llM-PLUS RESOURCE ACCOUNTING
17.4

WRITING AN ACCOUNTING REPORT PROGRAM USING DATATRIEVE-ll

The data collected in the transaction file pertains to your computing
environment.
How you interpret and analyze this data depends on your
objectives. For instance, are you interested in billing or system
measurement?
To obtain the Accounting data you are looking for, in
the form you want, you will most likely write your own report program.
'rhis program accesses the transaction file, reads the required data
fields, and writes a report containing the Resource Accounting data
you are interested in.
One way to write this specialized report is to use DATATRIEVE-1l; but
before a DATATRIEVE-ll program can access the transaction file, the
file must be converted to a DATATRIEVE-1l readable file.
To convert
-the file,
use the Resource Accounting SHOW ACCOUNTING/DATATRIEVE
command (see Section 17.4.1). The format of the converted file is
shown in LB:[126,24]ACNTRN.CMD along with an example of a simple
report generator written in DATATRIEVE-ll.
'ro obtain a report using
perform the following:

the

example

report

generator,

you

must

Use the SHOW ACCOUNTING command (see Section 17.4.1) to
convert the appropriate transaction file to a file that is
readable by DATATRIEVE-ll. Name the file ACCOUNT.DAT (this
is the name used in ACNTRN.CMD, for example purposes only).

Copy the following
directory:

files

from

the

system

disk

your

[1,2]OUERY.DIC
[126, 24]ACNTRN.CMD
After the above files are made available, use
line to generate a report:

the

following

command

>DTR @ACNTRN.Cf"iD
This command line calls DATATRIEVE-ll and executes the DATATRIEVE-ll
commands in the ACNTRN.CMD file.
A brief description is then
displayed on your terminal screen with a portion of the DATATRIEVE-ll
commands that make up the report generator.
After this you are
prompted with the following:

Enter DEVICE OR FILE:
You then enter where you want the Resource Accounting information
displayed.
The information can be displayed on a device or directed
to a file. For example, the device could be your terminal:

Enter DEVICE OR FILE:

TI:

If you wanted to put the information in
response would be:

Enter DEVICE OR FILE:

file

named

ACT.REP,

the

ACT.REP

While creating the report, you are prompted to respond with where the
report should be displayed. These prompts appear at junctures in the
report generating process where certain parts of the report can be
either displayed or directed to a file. For example, the first prompt
you receive is at a point where the STARTUP TRANSACTION part of the
report can be displayed.
The next prompt is at a point where the

17-16

RSX-llM-PLUS RESOURCE ACCOUNTING
first part of USER ACCOUNT BLOCK TRANSACTION can be displayed.
At
each prompt, you can direct that part of the report to the same report
file, a different report file, or to a device.
To stop the Resource Accounting report process before it is finished,
you must abort DTR. If this is done, you must recopy [1,2J QUERY.DIC
back into your area before using the example Resource Accounting
report program.

17.4.1

SHOW ACCOUNTING/DATATRIEVE Command

This command allows you to write your own Resource' Accounting report
generat:or using DATATRIEVE-ll.
This command is used to convert an
existing transaction file to a file that is readable by DATATRIEVE-ll.
Format
SHOW ACCOUNTING/DATATRIEVE[:trnsfilespecJ outfilespec
Parame1:er
trnsfilespec
Specifies the name of an existing Resource Accounting transaction
file.
outfilE~spec

Specifies the name of the output
transaction file is to reside.

17.5

file

where

the

converted

USER TASK INTERFACE FOR CREATING TRANSACTIONS

You can define and create your own transactions and write them into
the transaction file by using specific entry points in the Executive
Account:ing module. The task that you write must be privileged.
The
privilE~ged
task must enter the system state (by means of $SWSTK) and
call one of the following entry points in the Executive module ACSUB:
$QTRAN" $QTRNl, or $QTRN2.
In general, before calling one of the three entry points, the task
must have the address in register RO of a defined area (packet) that
is within the task. Also, the task must supply in the packet a value
for B . LEN and B.TYP (see Section 17.6.2). The packet contains the
header and the information that is to be written as a transaction.
The action taken by the ACSUB code depends on the entry point called
by the privileged task.

17.5.1

Calling $QTRAN

The $QTRAN routine automatically fills in the user-ID fields of the
packet from those used by the TI: terminal of the calling task.
In
effect this shows that the new transaction is coming from the same
user who ran the task.
j'

To call this entry point, the task must have the address of the
transaction packet in register RO. The two fields, B.LEN (containing
the trclnsaction length) and B.TYP (containing a transaction code from

17-17

RSX-llM-PLUS RESOURCE ACCOUNTING
128 through 255), must be filled in and contained within the packet.
$QTRAN obtains the transaction header from the UAB of the privileged
task, copies the header except for B.LEN and B.TYP into the packet,
t,ime-stamps the packet, and links the packet into a queue to be
written into the transaction file by the SYSLOG task.
$QTRAN does not
a.lter the task's space, but copies the packet into secondary pool
space before copying the header and queuing the packet into the SYSLOG
queue.
Example 17-1 is an example of the code needed to call $QTRAN.
Example 17-1
.MCALL ACNDF$
ACNDF$
TRAN:

.BLKB

Code That Calls $QTRAN

;DEFINE ACCOUNTING SYMBOLS

B.MLEN

This area contains code that
describes the data to be
written into the transaction
file.

MOV
MOVB
MOVB
CALL
CALL

17.5.2

#TRAN,RO
#BT.MOV,B.TYP(RO)
#B.MLEN,B.LEN(RO)
$SWSTK,
$QTRAN

;GET PACKET ADDRESS
;FILL IN TYPE
;FILL IN LENGTH
;SWITCH TO SYSTEM STATE
;TO CALL QUEUE TRANSACTION EXEC ROUTINE

Calling $OTRNI

The $QTRNI routine allows the user-ID fields to be obtained
specified place, instead of assuming the current task.

from

To call this entry point, the task must have filled the B.LEN and
B.TYP fields within the packet and must have the address of the
transaction packet in register RO.
In addition, register Rl must
contain an APR value that points to a UAB or TAB that contains the
llser-ID data that should be copied into this transaction.
The intent is that the privileged task will write a transaction
associated with another task.
$QTRNI time-stamps the packet and
obtains the transaction header from the UAB of the other task. $QTRNI
then queues the packet in the SYSLOG queue to be written \ into the
transaction file.
$QTRNI does not alter the packet within the task,
but copies identifying information from the specified UAB into
secondary pool, then copies data into the packet, and queues the
packet into the SYSLOG queue.
Example 17-2 is an example of the code needed to call $QTRNI.

17-18

RSX-IIM-PLUS RESOURCE ACCOUNTING

Example 17-2

Code That Calls $OTRNI

.MCALL ACNDF$
ACNDF$

:DEFINE ACCOUNTING SYMBOLS

This example assumes that Rl contains the pointer
to the TCB of the task for which the transaction
is to be posted.

TRAN:

17.5.3

:START OF TRANSACTION

.BLKB B.MLEN

MOV
BEO
MOV

T.ACN(Rl),Rl
10$
#TRAN,RO

:GET OTHER TASK'S UAB OR TAB ADDRESS
:IF EO NO ACCOUNTING DATA PRESENT
:POINT TO TRANSACTION HERE

MOVB
MOVB
CALL

#BT.MOV,B.TYP(RO)
#B.MLEN,B.LEN(RO)
$SWSTK,

:FILL IN TRANSACTION TYPE
:FILL IN TRANSACTION LENGTH
iSWITCH TO SYSTEM STATE
:TO CALL EXECUTIVE ROUTINES

CALL

$OTRNl

Calling $OTRN2

The $OTRN2 routine assumes the calling task completely fills in the
user-IO area of the transaction. The Executive queues the packet with
no modification, except for a time stamp.
To call this entry point, the task must have the address of the
transaction packet in register RO. $OTRN2 does not obtain a header
from any other source. Therefore, except for the transaction time,
the privileged task must have completely filled in the transaction
header and the transaction data contained within the packet.
$OTRN2
fills in the transaction time field in the transaction header area of
the packet created by the user task and queues the complete packet to
the SYSLOG queue to be written to the transaction file.
Example 17-3 is an example of the code needed to call $OTRN2.
Example 17-3

Code That Calls $OTRN2

.MCALL ACNDF$
ACNDF$
TRAN:

:DEFINE ACCOUNTING SYMBOLS

.BLKB B.MLEN
This area contains the code that
describes the header and data to
be written into the transaction
file.

(continued on next page)

17-19

RSX-IIM-PLUS RESOURCE ACCOUNTING
Example 17-3 (Cont.)

MOV
MOVB
MOVB
MOV
MOV
MOV
MOV
CALL
CALL
RETURN

#TRAN,RO
#BT.MOV,B.TYP(RO)
#B.MLEN,B.LEN(RO)
UID,B.UID(RO)
UID+2,B.UID+2(RO)
ACN,B.ACN(RO)
TID,B.TID(RO)
$SWSTK, 10$
$QTRN2

Code That Calls $QTRN2

;POINT TO TRANSACTION
;FILL IN TRANSACTION TYPE
;FILL IN TRANSACTION LENGTH
;USER SESSION ID
;SECOND HALF
;ACCOUNT NUMBER
;TERMINAL ID
;SWITCH TO SYSTEM STATE
;TO USER

10$:

Figure 17-1 describes the privileged task interface just discussed.
Section 17.6.2 contains a description of the header area fields.

17.6

ACCOUNT BLOCKS

T'here are two types of Resource Accounting account blocks:
the
memory-resident
and
non-memory-resident
account
blocks.
The
memory-resident account blocks are the Task Account Block (TAB), the
User Account Block (UAB) , and the System Account Block (SAB). The
Task Account Block (TAB) accumulates accounting data per task and
stays in secondary pool as long as a task is active. The User Account
Block (UAB) for each logged-in user accumulates the Accounting data
a.nd stays in secondary pool as long as the user is logged on. The
system's UAB accumulates data for tasks running on terminal co:.
The
SAB stays in secondary pool and accumulates system accounting data as
long as Resource Accounting is running.
A,ll other account blocks are non-memory-residenti that is, they are
created and filled when any transaction occurs, copied by Accounting
into secondary pool and immediately written into the transaction file.
After these operations are completed, the space is deallocated back to
secondary pool.
A.ll of the blocks have a header area that contains the same fields and
offsets.
In addition,
the TAB, the UAB, and the SAB have data
accumulation field areas following the header. All data accumulation
fields have the same offsets. The information specific to the TAB,
UAB, and SAB follows the accumulation areas.
You can find the size and the description of the offsets in Section
17.6.2.
The offsets are grouped 10gicallYi the header offsets are
described in one group, the accumulation field offsets in another
group, and so forth. The account and transaction block diagrams in
Section 17.6.1 show how these groups fit together to make a functional
account and transaction block.
The account and transaction block
diagrams are shown before the offset descriptions.
Check the [126,10]ACNDF.DOC file on the distribution kit for the
correc£ numeric offsets if you plan to write a program that uses the
offsets. In MACRO-II programs, use the symbolic names defined by the
ACNDF$ macro in [l,l]EXEMC.MLB.
The names will not change even if
t.heir associated offsets change.

17-20

RSX-IIM-PLUS RESOURCE ACCOUNTING

[CALLING $QTRAN
INPUT
USER TASK

PROCESS

OUTPUT

CALLS $QTRAN.

SYSLOG QUEUE

USER TASK FILLS
IN B.LEN, B.TYP,

TRANSACTIONS

TRANSACTION

AND PACKET

HEADER OF

PACKET:

TRANSACTION

B.LEN =
B.TYP =

DATA. HEADER IS
FROM USER TASK
UAB or TAB.

USER TASK
UAB OR TAB

DATA

DATA
FROM PACKET

[CALLING $QTRN1
INPUT
USER TASK

ITW

OUTPUT

CALLS $QTRN1.

SYSLOG QUEUE

USER TASK FILLS

TRANSACTION

IN PACKET DATA,
B.LEN, AND B.TYP.
HEADER IS FROM

TRANSACTION
PACKET:

ANOTHER TASK'S

B.LEN =
B.TYP =

UAB OR TAB
(TASK A).

DATA
~

PROCESS

HEADER OF
UAB OR TAB
OF TASK A
DATA FROM
PACKET

-DD]
TASK A
UAB or TAB

I HEADER I

C::ALLlNG $QTRN2
INPUT
USER TASK

~O
TRANSACTION
PACKET:
FILLED IN
HEADER

PROCESS

OUTPUT

CALLS $QTRAN2.
USER TASK FILLS
IN ENTIRE
HEADER AND

SYSLOG QUEUE

TRANSACTION
DATA WITHIN
PACKET.

TRANSACTION
HEADER AND
DATA FROM
PACKET

FILLED IN
DATA

ZK-165-81

Figure 17-1

Privileged Task Interface Overview

17-21

RSX-IIM-PLUS RESOURCE ACCOUNTING

17.6.1

Account and Transaction Block Diagrams
OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM
12

B.ACN

B.TID

B.UID

B.CPU
B.DIR
B.OIO
B.TAS

RESERVED
50

40
B.BEG

B.CPUL
B.PNT
B.STM

B.PRI

B.TNAM
72

B.TCB
B.TST3
RESERVED

100

B.CUIC

102

B.PUIC

104

68
B.CTXT

110

72
B.TCKP

114

76
B.OVLY

120

80
B.EXST

124

B.TLEN=-.

ZK -593-81

Task Account Block

17-22

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM
12

B.UID

B.ACN

B.TlD

B.CPU
B.DIR
B.OIO
B.TAS

RESERVED
50

40
B.BEG

46
B.CPUL

B.PNT

B.ACT

B.UUIC

B.UCB

B.STM

B.USE

B.LGO
102

104

B.ULNK
B.RNA

112

74
B.NAM
(15. BYTES)

132

90
B.LPS

144

B.ULEN

100

ZK-594-81

User Account Block

17-23

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM

B.ACN
B.TID

B.UID

B.CPU
B.DIR
B.QIO
B.TAS

RESERVED

40
B.BEG

B.CPUL
B.PNT
B.STM

B.UHD

B.ULO

102

106

112

B.SHDN

B.ULT
B.CKP
B.SHF
B.RND

B.FID

120

122

B.UNIT

124

B.EXTS

126

B.DVNM

B.LSCN

134

B.SCNR

136

B.DSCN

140

RESERVED

(18. bytes)
162

114

B.SLEN
ZK-595-81

System Account Block

17-24

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM
12

B.ACN

B.TID

B.SSLN --

B.UID

ZK-596-81

Accounting Startup Transaction Block
OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM

10
B.UID

B.ACN

B.TID

B.CTLS

B.CSRT
B.CRSN

r'../

T
126

(60. bytes)

rl.l

B.CLEN~-.

ZK-598-81

Crash Recovery Transaction Block

17-25

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM

10
B.UID

B.ACN

B.TID

18
B.OFID

24
B.ODNM

B.OUNT

B.NFID

B.NDNM

B.NUNT

B.OEXS

B.NEXS

B.OSCR

B.NSCR

B.ODSC

B.NDSC

B.RTLN
ZK-597-81

Set Accounting Transaction Block

17-26

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

.:1

B.LNK

B.TYP

B.LEN

B.TIM

B.UID

B.ACN

B.TID

18
B.INAM

(14. bytes)

32
B.IUIC

38
B.IPSW

B.ILEN~=

ZK-599-81

Invalid Login Transaction Block
OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

B.ACN

B.TID

B.DNAM

B.UID

B.DUNT

UNUSED

B.DLEN·
ZK-600-81

Allocate Device Transaction Block

17-27

RSX-llM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

B.UID

B.ACN
B.TID

B.DNAM

B.DUNT

UNUSED

B.DLENc
ZK-601-82

Deallocate Device Transaction Block
OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

10
B.UID

B.ACN

B.TID

B.DNAM

B.DUNT

UNUSED

B.DLBL

B.DMST

B.DUIC

B.DVPR

B.DACP

B.MLEN
ZK-602-82

Mount Device Transaction Block

17-28

RSX-IIM-PLUS RESOURCE ACCOUNTING

OCT

DEC

B.lNK

B.TYP

B.lEN

B.TIM

B.ACN

B.TID

B.DNAM

B.UID

B.DUNT

UNUSED

B.DlEN~=.

ZK-603-82

Dismount Device Transaction Block
OCT

DEC

B.lNK
B.TYP

B.lEN

B.TIM

B.ACN

B.TID

B.UID

B.TOlD
30

24
B.TNEW

B.TMlN==.
ZK-604-82

System Time Change Transaction Block

17-29

RSX-IIM-PLUS RESOURCE ACCOUNTING
OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

B.ACN

B.TID

B.UID

B.PNAM

B.PPGS

B.PNFI

B.PFRM

B.PPRI

B.PDEV
B.PPUN

I
B.PLEN
ZK-605-82

Print Despooler Transaction Block
OCT

DEC

B.LNK
B.TYP

B.LEN

B.TIM

B.ACN

B.TID

B.LUIC

B.UID

B.LNAM

1"1...1

T
43

(15. bytes)

,..."

B.LLEN
ZK-606-82

17-30

RSX-IIM-PLUS RESOURCE ACCOUNTING
OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

B.ACN

B.TID

B.UID

B.RNAM

B.RCDS

B.RDEV

B.RUNT

B.RLEN

B.RSOP
ZK-607-82

Card Reader Spooling Transaction Block
OCT

DEC

B.LNK

B.TYP

B.LEN

B.TIM

B.ACN

B.TID

32
34

26
28

38
40
42

50
52
54
56

44
46

B.UID

X.NAME
X.IOC
X.ERHL
X.ERSC

I
I

X.ERSL
X.ERHC

X.WCNT
X.CYLC
X.CCYL
X.FCUR

X.FUM

X.DNAM
X.UNIT

UNUSED

X.LGTH ==
ZK-902-82

Device Statistics Block

17-31

RSX-IIM-PLUS RESOURCE ACCOUNTING
17.6.2

Account and Transaction Block Offset Definitions

The header area fields precede the accumulation fields for the TAB,
UAB,
and SAB.
The header area fields also precede each transaction
block.
1~he

header provides user identification by two fields
(B.UID and
B.ACN) that appear in every transaction. These fields are the unique
session identification and the account number.
The unique session
identification is two words long.
The first word,
the session
identification, is three RAD50 characters supplied by the user when he
creates the system account by using the ACNT program. The second word
is a unique number assigned by the system at login.
Thus,
it is
possible to match every transaction with the login session that
produced it. The account number field is a binary word (entered
through ACNT) that is copied into every transaction.
Resource
Accounting does not use either of these fields, except to ensure that
they appear in every transaction.
Header Area Fields
Offset

Size or
Value

13.LNK: :
B. TYP: :

.BLKW 1
.BLKB 1

BT.SAB==l
BT.UAB==2
BT.TAB==3
BT.SS==ll
BT.INV==12
BT.TIM==13
BT.ALL==14
BT.DEA==15
BT.MOU==16
BT.DMO==17
BT.PRT==20
BT.LOG==23
BT.CRH==24
BT.DST==25
BT.RTP==26
BT.INP==27
B .LEN: :
B. TIM: :

.BLKB 1
.BLKW 3

B.HID==.
B.UID::

.BLKW 2

Definition
Start of header area:
Link to next in SYSLOG queue
Transaction type:
000 through 127 - reserved for DIGITAL
use
128 through 255 - reserved for customer
use
System Account Block (SAB)
User Account Block (UAB)
Task Account Block (TAB)
Accounting startup transaction
Invalid login transaction
System time change transaction
Allocate device transaction
Deallocate device transaction
Mount device transaction
Dismount device transaction
Print despooler transaction
Reserved
Reserved
Login transaction
Crash recovery transaction
Device Statistics (UCB Extension)
Reset Transaction Parameters
Card Reader Spooling Transaction
Transaction length in bytes
Ending time of transaction (supplied by
$QTRAN,$QTRNl,$QTRN2)
Start of header identification area
Unique session identification
First word - RAD50
Second word - binary

17-32

RSX-IIM-PLUS RESOURCE ACCOUNTING

B.ACN: ::
B.TID: ::

.BLKW 1
.BLKB 1
.BLKB 1

B.HEND==.

Account number
ASCII terminal type: V - virtual,
T - real, B - batch, C - console
Unit number
End of header identification area

Accumulation Fields for User Account Block, Task Account
Block, and System Account Block
B.CPU: ::
B.DIR:::
B.QIO: ::
B. TAS: ::
B.BEG: ::
B.CPUL:: :

.BLKW 2
.BLKW 2
.BLKW 2
.BLKW 2
.BLKW 3
.BLKW 3
.BLKW 2

B.PNT: ::

.BLKW 1

B.STM: ::

.BLKB 1
BS.ACT==200
BS.CRH==lOO
BS.LGO==40
BS.CO==40
BS.TML==20
BS.SIL==20
BS.ZER==lO
BS.SCN==4

Total CPU time used
Total directive count
Total QIO$ count
Total task count (not used in TAB)
Reserved
Beginning/login time
CPU time limit in TAB or UAB
(not used in SAB)
Pointer to SAB if system statistics
to be collected. Equals 0 if no
system statistics collection.
In TAB
this points to UAB.
In UAB points to
SAB if SYSTEM-STATISTICS:YES or zero.
In SAB always zero.
Status mask
Control block active (UAB, TAB)
Record from TMP file after crash (UAB, SAB)
Logged off with outstanding
activities (UAB only)
Tasks TI: is co: (TAB only)
TAB exists only for time limit (TAB only)
TABS with this bit set will not
be written to the transaction file.
Silent login/logout (UAB only)
Last CPU interval was zero length (TAB, UAB)
Transaction ready for write to scan (UAB,
SAB) file
User Account Block

Note:

User Account Blocks must end on a word boundary.

B. USE: :
B.ACT: :
B.UUIC::
B. UCB: :
B. LGO: :
B. ULNK: :
B.RNA: :

.BLKB 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 3
.BLKW 1
.BLKW 3

Use count
Number of currently active tasks
Login UIC
Pointer to UCB
Logout time
Link to next User Account Block
Location in system account file (offset, VBN-hi, VBN-Io)
This will be inaccurate if the
account file is changed (additions,
deletions, sorts).

17-33

RSX-llM-PLUS RESOURCE ACCOUNTING
B.NAM: :
B. LDS: :
B.ULEN==.

.BLKB 14.
.BLKB 1
.BLKB 1
.BLKB 10

Last name of user
First initial of user
Flag byte for UAB (BS.SIL etc.)
Login directory string
User Account Block Length
Task Account Block

NOTE:

Task Account Blocks must end on a word boundary.

B.PRI::
B .TNAM: :
B. TCB: :
B .TST3: :
B.CUIC: :
B.PUIC::
B. CTXT: :
B. TCKP: :
B .OVLY: :
B .EXST: :
B.TLEN==.

.BLKB 1
.BLKW 2
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 2
.BLKW 2
.BLKW 2
.BLKW 2

Highest running priority
Task name
TCB address
T.ST3 from task IS TCB
Reserved for future status bits
Current UIC of task
Protection UIC of task
Number of context loads
Times task has been checkpointed
Number of disk overlay loads
Exit status and abort code 1
TAB length

1. The abort codes are as follows:
S.CACT=-4.
S.CEXT=-2.
S.COAD=O.
S.CSGF=2.
S.CBPT=4.
S.CIOT=6.
S.CILI=8.
S.CEMT=lO.
S.CTRP=12.
S.CFLT=14.
S.CSST=16.
S.CAST=18.
S.CABO=20.
S.CLRF=22.
S.CCRF=24.
S.IOMG=26.
S.PRTY=28.
S.CPMD=30.
S.CELV=32.
S.CINS=34.
S.CAFF=36.
S.CCSM=38.
S.COTL=40.
S.CTKN=42

Task still active
Task exited normally
Odd address and traps to 4
Segment fault
Break point or trace trap
lOT instruction
Illegal or reserved instruction
Non-RSX EMT instruction
TRAP instruction
PDP-ll/40 floating point exception
SST abort-bad stack
AST abort-bad stack
Abort via directive
Task load request failure
Task checkpoint read failure
Task exit with outstanding I/O
Task memory parity error
Task aborted with PMD request
TI: virtual terminal was eliminated
Task installed in 2 different systems
Task aborted due to bad affinity (required by runs are
offline or not present)
Bad parameters or bad stack
Task has run over its time limit
Abort via directive with no TKTN message
17-34

RSX-IIM-PLUS RESOURCE ACCOUNTING
System Account Block
B. SHDN: :

.BLKB 1

B. UHD: :
B. ULO::
B. ULT: :
B .CKP: :
B. SHF: :
B.RND: :

.BLKW 1
.BLKW 1
.BLKW 2
.BLKW 2
.BLKW 2
.BLKW 2

B.FID: :
B. DVNM: :
B.UNIT: :
B. EXTS:: :
B.LSCN: :
B. SCNR: :
B.DSCN: :

.BLKW 3
.BLKB 2
.BLKW 1
.BLKW 1
.BLKW 3
.BLKW 1
.BLKW 1
. BLKW 9 •

B.SLEN==.

Accounting shutdown reason code
1 - Maintenance
2
Reboot
3
Scheduled shutdown
4
Accounting shutdown by Shutup
task
5
Other
User Account Block listhead
Number of users currently logged on
Total number of logons
Total number of checkpoints
Total number of shuffler runs
Number of CPU intervals rounded up
to 1/2
File-ID of transaction file
Device of transaction file
Unit of transaction file
Extend size for transaction file
Time of last scan
Scan rate in seconds
Device statistical scan rate in
seconds
Reserved
System Account Block length

SYSLOG Startup Transaction Block
B. SSLN=:=.

Transactior length
Set Accounting Transaction Block

B.OFID: :
B.ODNM: :
B.OUNT: :
B .NFID: :
B .NDNM: :
B.NUNT: :
B.OEXS::
B.NEXS: :
B.OSCR: :
B.NSCR: :
B.ODSC: :
B .NDSC: :
B.RTLN=:=

.BLKW 3
.BLKB 2
.BLKW 1
.BLKW 3
.BLKB 2
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 1

File-ID of old transaction file
Device of old transaction file
Unit of old transaction file
File-ID of new transaction file
Device of new transaction file
Unit of new transaction file
Extend size for old transaction file
Extend size for new transaction file
Old scan rate in seconds
New scan rate in seconds
Old statistical scan rate
New statistical scan rate
Transaction length

Crash Recovery Transaction Block
B.CTLS: :
B.CSRT: :
B.CRSN: :
B.CLEN=:=.

.BLKW 3
.BLKW 1
.BLKB 60.

Time of last scan before crash
Scan rate before crash
ASCII text explaining crash
Transaction length

17-35

RSX-llM-PLUS RESOURCE ACCOUNTING
Invalid Login Transaction Block
B. INAM::
B.IUIC::
B. IPSW::
B.ILEN==.

.BLKB 14.
.BLKB 6.
.BLKB 6.

Name from login line
UIC from login line
Password from login line
Transaction length

Device Transaction for Disk Accounting
(ALLOCATE, DEALLOCATE, MOUNT, and DISMOUNT)
B. DNAM: :
B. DUNT: :
B.DLEN==.

.BLKW 1
.BLKB 1

ASCII device name
Octal device unit number
Transaction length for ALLOCATE,
DISMOUNT, and DEALLOCATE

rrhe following fields only appear for MOUNT transactions

B. DLBL: :
B. DMST: :
13.DUIC: :
B. DVPR: :
13. DACP: :
13.MLEN==.

.BLKB 1
.BLKW 6
.BLKW 1
.BLKW 1
.BLKW 1
.BLKW 2

Unused byte
Volume label
Mount Status Bits
Owner UIC
Volume protection code 2
Name of ACP for device
Length of MOUNT transactions

System Time Change Transaction Block
13.TOLD: :
13 .TNEW: :
13.TMLN==.

.BLKB 6
.BLKB 6

Old time (yr, mon, day, hr, min, sec)
New time (yr, mon, day, hr, min, sec)
Transaction length

2. The volume protection codes are as follows:
Bits

Protection

0-3
4-7
8-11
12-15

system
owner
group
world

The bit settings within each protection group are as follows:
Bit

Access denied (if bit set)

read
write
create
delete

1
2
3

17-36

RSX-IIM-PLUS RESOURCE ACCOUNTING
Print Despooler Transaction Block
B. PNAM::
B.PPGS::
B. PNFI: :
B. PFRM:: :
B. PPRI:: :
B. PDEV:: :
B. PPUN:: :
B.PLEN==.

Print job name (RADSO)
Page count
Number of files printed
Form number
Print priority
Print device name (ASCII)
Unit number of print device
Transaction length

.BLKW 3
.BLKW 1
.BLKW 1
.BLKB 1
.BLKB 1
.BLKW 1
.BLKB 1

Card Reader Spooling Transaction Block
B. RNAM:. :

B.RCDS:: :
B. RDEV:. :
B.RUNT:: :
B. RSOP:. :
B.RLEN==.

Batch or print job name
Number of cards read
Reader device name (ASCII)
Unit number of reader device
Submit or print (O=SUBMIT, l=PRINT)
Transaction length

.BLKW 3
.BLKW 1
.BLKW 1
.BLKB 1
.BLKB 1

.BLKW 1
.BLKB 14.
.BLKB 1

B.LLEN==.

The following globals are also defined:
B.MAXL==128.
B.MINL==9.

Maximum transaction length (words)
Minimum transaction length (words)
Device Statistics Block

X.NAME:: :
X. laC: ::
X.ERHL:: :
X.ERSL:: :
X.ERSC:: :
X.ERHC:: :
X.WCNT:: :
X.CYLC: :
X.CCYL:: :
X.FCUR:: :
X.FLIM:: :
X.DSKD:: :
X.DNAM:: :
X. UNIT::
X. LGTH===.

.BLKW 2
.BLKW 2
.BLKB 1
.BLKB 1
.BLKB 1
.BLKB 1
.BLKW 2
.BLKW 2
.BLKW 1
.BLKB 1
.BLKB 1
.BLKB 1
.BLKB 1
.BLKB 1

Drive name in RADSO
I/O Count
Hard error limit
Soft error limit
Soft error count
Hard error count
Words transferred count
Cylinders crossed count
Current cylinder
Current fairness count
Fairness count limit
Disk direction (high bit l=out)
Device name for accounting
Unit number for accounting
Unused
Length of the UCB extension

17-37

RSX-IIM-PLOS RESOURCE ACCOUNTING

17.6.3

Account Block Linkages

SYSCM

$SABPT

o
I

TCB
TAB

V
V
C
T.UCB

T.ACN

B.PNT

TCB

TAB

T.UCB

T.ACN

(»

B.PNT

UCB

UAB

TT5:

B.PNT
B.UCB
B.ULNK

U.UAB

SAB

~r7
~~
-

B.UHD
B.PNT=O

TCB
TAB

l/I
C
T.UCB

T.ACN

B.PNT

UCB

TT7:

UAB

B.PNT
B.UCB
B.ULNK

U.UAB

SYSCM

$SYUAB

1
I

TCB
TAB

V
C
T.UCB

T.ACN

B.PNT

UCB

SYSTEM
UAB

B.PNT

co:

B.UCB
B.ULNK=O
ZK-166-81

Figure 17-2

Account Block Linkages
17-38

RSX-IIM-PLUS RESOURCE ACCOUNTING

Terminal TT5:, which is indicated by the UCB, is that of the
most recently logged-in user. The user of this terminal has
started two tasks, which are indicated by the two Task
Control Blocks (TCB) that contain pointers to the UCB
(T.UCB) and each associated TAB (T.ACN).
Each TAB then
points to the terminal's UAB. The total usage of terminal
TT5: is totaled in the associated UAB.

Terminal TT7:
is that of the next most recently logged-in
user.
The user has started a task indicated by the single
TCB, which points to a TAB which points to a UAB. The total
usage of terminal TT7:
is totaled in the associated UAB.

The CO: console terminal has associated with it a single
TCB that indicates a system task is running.
In effect, the
system is also a user and has system usage accumulated at
the task level in the TAB and totaled in the UAB associated
with the CO: terminal.

The SAB contains the usage totals for all the users
including the system itself. The B.URD pointer in the SAB
points to the UAB of the most recently logged-in user.
B.URD and the B.ULNK words in each UAB are the linkages that
are used when Accounting periodically writes the UABs to the
scan file.

The pointer to the SAB ($SABPT) is in the
SYSCM.

The pointer to the system UAB ($SYUAB) is in
module SYSCM.

Executive
the

module

Executive

NOTE
Although all active UCBs point to the appropriate
UABs using U.UAB, this is not true for CO:. U.UAB
does not exist for CO:, but instead is reflected by
location $SYUAB.

17.7

SYSTEM RESOURCES USED

The following sections discuss the amount of system space that
Resource Accounting uses. Secondary pool usage varies from a certain
minimum to an amount determined by the number of logged-in users and
event-associated transactions.

17.7.1

Executive Space Requirements

Account:ing support, which is a SYSGEN option, takes up approximately
532 words.
Space in system pool is required for one active task and
one opE~n file.

17.7.2

Secondary Pool Usage

Each logged-in user requires two blocks (32 words per block) of
secondary pool for the User Account Block (UAB); that is, two blocks
for each logged-in terminal or virtual terminal. Each task running in
the system requires two blocks for the Task Account Block (TAB), if

17-39

RSX-IIM-PLUS RESOURCE ACCOUNTING
task accounting is enabled. Resource Accounting needs two blocks for
the SAB and two blocks for the system UAB. Non-memory-resident
events, such as device mounts, 1'equire one block for a brief period of
time.

17.8

RESOURCE ACCOUNTING MESSAGES

Accounting messages are numbered from 1(10) through 79(10).
However,
not all of the numbers in this range are used. The number appears at
the start of the Accounting message. The Accounting messages have the
following format:
hh:mm:ss aaaTnn nne

*aaaaaa* message ...

where:
hh:mm:ss
The time of the message occurrence is hh:mm:ss
aaaTnn
The task issuing the message and the terminal executing the task
are displayed as aaaTnn.
The first three letters of the task
name are indicated by aaa. Tnn is the terminal number of the
terminal executing the task.
SYSLOG appears if the message
originated from that task.
nne
The message number is nne The message number enables you to find
a description of the message in the following list of messages.
*aaaaaa*
The message severity code is aaaaaa and it has four forms.
It
may not be present; if it is not, the message is an informational
message. The four forms of the severity code are as follows:
*DIAG* - Information only
*WARN* - Possible error condition
*ERROR* - Command did not succeed
*FATAL* - Extreme error condition
The following is a list of the Accounting messages:
nn:nn:nn aaaTnn 1.

Undefined message number nne

at PC aaaaaa

Explanation: The message number is a decimal number specified by
nne The location is specified by the address aaaaaa. This is an
internal Accounting error.
User Action:

Submit a Software Performance Report (SPR).

17-40

RSX-llM-PLUS RESOURCE ACCOUNTING

nn:nn:nn aaaTnn 2.

Directive error.

$DSW=nnn PC is just before aaaaaa

Explanation: The directive error code is an octal
number
specified by nnn. The PC contains an address just preceding the
octal address aaaaaa.
This
message
provides
additional
information to a message that will appear with it.
User Action: Look up the directive
error
code
RSX-IIM-PLUS Mini-Reference to obtain more information.

the

nn:nn:nn aaaTnn 4. FCS aaa ERROR CODE = nnn
FILE: DBn: [???,???]filename.filetype:v
Explanation: The word "I/O" or "DSW" is specified by aaa.
The
error code is specified by "nnn. The UIC is inaccessible and
appears as question marks.
User Action: Refer to the RSX-llM-PLUS
explanation of the error code.
nn:nn:nn aaaTnn 5.

nn:nn:nn aaaTnn 6.

for

*ERROR* Illegal filename

Explanation: The file name
command is invalid.
User Action:

Mini-Reference

specified

the

START/ACCOUNTING

Correct the file name and reenter the command.
*FATAL* Can't open transaction file

[message]
Explanation: The transaction file could not be created for the
reason
specified in the message that follows "Can't open
transaction file."
User Action:
nn:nn:nn aaaTnn 7.

Determine the cause of the error and correct it.
*FATAL* Can't open transaction file (by id)

[message]
Explanation: After it was created, the transaction file became
inaccessible for reason specified in the message that follows
"Can't open transaction file (by id)."
User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause
of the error, correct it, and restart Accounting.

17-41

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 8.

*FATAL* Can't write transaction file

[message]
Explanation: The transaction file could not be written for the
reason specified in the message that follows
"Can't write
transaction file." Accounting cannot recover from this error.
Accounting data is lost because the file cannot be written.
User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause
of the error, correct it, and restart Accounting.
nn:nn:nn aaaTnn 9.

*ERROR* Can't close transaction file

Explanation: The transaction file
could
Acounting cannot recover from this error.
lost because the file cannot be closed.
User Action: If possible, determine
closed.
Restart Accounting for a
error recurs.
nn:nn:nn aaaTnn 10.

not
be
closed.
Accounting data is

why the file cannot be
short period to see if the

*FATAL* Can't init new blocks

Explanation: The transaction file cannot be written when the
file is being extended.
Accounting cannot recover from this
error. Accounting data is lost because the file cannot be
written to be extended.
User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause
of the error, correct it, and restart Accounting.
nn:nn:nn aaaTnn 11.

*FATAL* Can't init new blocks.

I/O error = nnn

*FATAL* Can't write attributes.

the

I/O error = nnn

17-42

code

can

found

the

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 13.

* FATAL * Can't write attributes

*FATAL* Secondary pool allocation failure

Explanation: There is insufficient secondary pool
start Accounting.

remaining

User Action: Use VMR (Chapter 10) to increase the secondary pool
partition size, and rebootstrap.
nn:nn:nn aaaTnn 15.

*FATAL* Bad SYSLOG queue

Explanation: The SYSLOG
Accounting startup.
User Action:
Accounting.
nn:nn:nn aaaTnn 16.

Issue

task's

input

STOP/ACCOUNTING

not

empty

during

CLEAN UP

and

restart

*ERROR* Accounting already active

Explanation:

Accounting is already active.

User Action:

None.

nn:nn:nn aaaTnn 17.

*FATAL* Error spawning SYSLOG

[message]
Explanation: The SYSLOG task could not be started due to the
reason specified in the message that follows "Error spawning
SYSLOG."
User Action: Determine the cause of the error, correct
restart Accounting.
nn:nn:nn aaaTnn 18.

it,

and

Accounting system not started

[message]
Explanation: Accounting was not started because of the reason
specified in the message that follows "Accounting system not
st.arted.
II

User Action: Determine the cause of the error, correct
restart Accounting.

17-43

it,

and

RSX-11M-PLUS RESOURCE ACCOUNTING

SYSLOG exit with status = n.

nn:nn:nn aaaTnn 21.

[message]
Explanation: The exit status of the SYSLOG task is represented
by the decimal number n. See the accompanying SYSLOG message.
User Action:
again.

Correct the problem,

nn:nn:nn aaaTnn 22.

there

one,

and

*ERROR* SYSLOG not installed
not

Explanation: The
SYSLOG
task
START/ACCOUNTING was specified.

was

User Action:
command.

reissue

Install SYSLOG

nn:nn:nn aaaTnn 23.

and

*ERROR* Error bit set.

installed

the

User Action: Issue
restart Accounting.
nn:nn:nn aaaTnn 25.

Cleanup before restart.

Explanation:

STOP/ACCOUNTING

CLEAN UP

restarted

command

and

*ERROR* Accounting did not crash

Explanation: A
unnecessarily.

nn:nn:nn aaaTnn 27.

the

when

START/ACCOUNTING

Explanation: Accounting had an error and cannot be
until you issue the STOP/ACCOUNTING CLEAN_UP command.

User Action:

try

STOP/ACCOUNTING

CLEAN UP

command

issued

was

None.
*FATAL* System command handling error
This is a Get MCR command line directive failure.

User Action: None. The ACC task was RUN, so no command line was
queued.
Access to this task is only legal with the specified
Accounting commands.
nn:nn:nn aaaTnn 28.
Explanation:
operation.

*ERROR* Privilege violation
for

the

specified

User Action: None. Nonprivileged users can see
data for their terminal only.

the

Accounting

nn:nn:nn aaaTnn 29.

You did not have the privilege

*ERROR* Accounting not supported in system

Explanation: Accounting cannot be used unless it is selected
an option in SYSGEN.

User Action:
option.

Do another

SYSGEN

17-44

and

select

Accounting

RSX-IIM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 30.

*ERROR* Illegal command or parameter

Explanation:

The entered command is incorrect.

User Action:

Enter the correct command.

nn:nn:nn aaaTnn 31.

*ERROR* Command or parameter ambiguous

Explanation: Parameter was entered with too few
uniquely identified.

letters

Us,er Action:
parameter.

let ters

the

nn:nn:nn aaaTnn 32.

Reenter

the

command

with

*ERROR* Syntax error

Explanation:

The entered command is incorrect.

USler Action:

Enter the correct command.

nn:nn:nn aaaTnn 33.

*ERROR* Terminal I/O error

Explanation: A terminal I/O error occurred during a prompt or
read to the terminal.
Us,er Action:
nn:nn:nn aaaTnn 34.

Try the operation again.
*ERROR* Repeated or contradictory parameter

Explanation:

Illegal or duplicate parameter combination.

User Action:

Enter the correct command parameter.

nn:nn:nn aaaTnn 35.

*ERROR* Required parameter missing

Explanation:

A parameter is missing in the command line.

User Action:

Reenter the command with the required parameter.

nn:nn:nn aaaTnn 36.

*ERROR* Value out of range

Explanation:
small.

The value entered

User Action:

Reenter the command with the correct value.

nn:nn:nn aaaTnn 38.

was

either

too

large

too

*ERROR* No accounting data present

Explanation: The terminal specified in the SHOW ACCOUNTING/I N.FORMATI ON command either does not have any Accounting data or
is not logged in.
User Action:
the command.

Determine the correct terminal to use

17-45

and

reenter

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 39.

*ERROR* Device specification error

Explanation: A device specification was entered
the command line.
User Action:
command.
nn:nn:nn aaaTnn 40.

Determine

the

correct

device

incorrectly
and

reenter

in
the

*FATAL* No startup transaction found

Explanation: The START/ACCOUNTING command and the SYSLOG task
are closely related and depend on each other for correct
operation. Any attempt to start the SYSLOG Accounting task by
any method other than the use of START/ACCOUNTING results in this
message.
User Action: If START/ACCOUNTING and SYSLOG
intended and this error resulted, submit an SPR.
nn:nn:nn aaaTnn 41.

*WARN* Bad transaction length.
pool may be lost

were

nn:nn:nn aaaTnn 42.

Internal consistency error.

User Action:

Submit an SPR.

Internal consistency error.

User Action:

Submit an SPR.

transaction.

See

* FATAL * UAB Not found in list

Explanation:

Internal consistency error.

User Action:

Submit an SPR.

nn:nn:nn aaaTnn 45.

small

*ERROR* Transactions follow SAB

Explanation:

nn:nn:nn aaaTnn 44.

too

*ERROR* UAB Listhead not zero on shutdown

Explanation:

nn:nn:nn aaaTnn 43.

the

Block(s) of secondary

Explanation: A transaction was probably too large or
and is probably a user-designed transaction.
User Action: Correct the generation
B.MINL or B.MAXL in Section 17.6.2.

used

*FATAL* Exiting due to error

Explanation: SYSLOG exited for the specified reason.
The
specified reason is in the message that appears with this one.
User Action: Issue STOP/ACCOUNTING CLEAN UP, determine the cause
of the error, correct it, and restart Accounting.
nn:nn:nn aaaTnn 46.

*FATAL* Transaction not in secondary pool

Explanation:

Internal consistency error.

User Action:

Submit an SPR.
17-46

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 47.

Exiting

Explanation:

Normal SYSLOG exit due to STOP/ACCOUNTING command.

User Action:

None.

nn:nn:nn aaaTnn 50.

Accounting not active

Explanation:
running.

The

User Action:

Issue START/ACCOUNTING and reissue the command.

nn:nn:nn aaaTnn 51.

command

issued

requires

Accounting

Accounting failed.

User Action:

Issue the STOP/ACCOUNTING CLEAN UP command.

Explanation:

*ERROR* SYSLOG Not active
SYSLOG has unexpectedly exited.

User Action: Issue
restart Accounting.
nn:nn:n.n aaaTnn 53.

*ERROR* Accounting had a fatal error, must be
cleaned up

Explanation:

nn:nn:n.n aaaTnn 52.

the

STOP/ACCOUNTING

CLEAN UP

command

and

*ERROR* Cannot write crash transaction

[message]
Explanation: The crash transaction could not be written to the
new transaction file for the specified reason following "Cannot
write crash transaction." The crash data is lost.
User Action:
nn:nn:nn aaaTnn 54.

None.
*ERROR* Error during scan file rename

Explanation: The specified error was
with the scan file.
User Action:
nn:nn:n.n aaaTnn 55.

when

dealing

Determine the cause of the problem and correct it.
*ERROR* On scan file PUTS

Explanation: The specified error was
with the scan file.
User Action:

encountered

when

dealing

Determine the cause of the problem and correct it.

17-47

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 57.

Enter reason for the crash (Maximum 60.

characters)

Explanation: This is the prompt for the user-supplied crash
reason because "yes" was answered as the CRASH REASON parameter
on the START/ACCOUNTING command.
User Action:

Enter a crash reason.

nn:nn:nn aaaTnn 58.

*ERROR* Terminal I/O Error

Explanation: An I/O error occurred from the terminal during the
input of the crash information. The crash information is lost.
User Action:
nn:nn:nn aaaTnn 60.

None.
*ERROR* I/O Error

Explanation: The specified I/O error occurred
ACCOUNTING TRANSACTION command.

during

User Action:
again.

try

I1n:nn:nn aaaTnn 64.

Correct the

I/O

condition

Iln:nn:nn aaaTnn 65.

the

SHOW

command

*ERROR* Illegal file name

Explanation: There is an incorrect file
SHOW ACCOUNTING TRANSACTION command.
User Action:
again.

and

the

specification

Correct the file specification and try the

for

the

command

*ERROR* Open error

Explanation: The specified error occurred during a file
procedure of the SHOW ACCOUNTING/TRANSACTION_FILE command.

open

User Action: Determine the cause of the error, correct
try the operation again.

and

nn:nn:nn aaaTnn 70.

it,

*ERROR* On scan file open

Explanation: The specified error was encountered when Accounting
was processing the scan file.
User Action:
nn:nn:nn aaaTnn 71.

Determine the cause of the problem and correct it.
*ERROR* On scan file delete

Explanation: The specified error was encountered when Accounting
was processing the scan file.
User Action:

Determine the cause of the problem and correct it.

17-48

RSX-llM-PLUS RESOURCE ACCOUNTING
nn:nn:nn aaaTnn 72.

*ERROR* On scan file close

Explanation: The specified error was encountered when Accounting
was processing the scan file.
User Action:
nn:nn:nn aaaTnn 73.

Determine the cause of the problem and correct it.
*ERROR* On scan file open

Explanation: The specified error was encountered when processing
the scan file.
User Action:
nn:nn:nn aaaTnn 74.

Determine the cause of the problem and correct it.
*ERROR* Copying scan file to trans file

Explanation: The specified error was encountered when processing
the scan file.
The crash information that would have appeared in
the transaction file is lost.
User Action:
nn:nn:nn aaaTnn 75.

None.
*ERROR* On scan file close

Explanation: The specified error was encountered when processing
the scan file.
User Action:
nn:nn:nn aaaTnn 76.

Determine the cause of the problem and correct it.
*ERROR* On scan file delete

Explanation: The specified error was encountered when processing
the scan file.
User Action:
nn:nn:nn aaaTnn 79.

Determine the cause of the problem and correct it.
*ERROR* Task not in memory or not active

Explanation: The
task
specified
with
the
SHOW
ACCOUNTING/INFORMATION TASK=taskname command was not in memory or
was not active. Therefore, there is no task accounting date for
this task.
User Action:

None.

17-49

CHAPTER 18
RSX-IlM-PLUS SHADOW RECORDING

Shadow Recording (which is a system generation option) is an Executive
featur.~
of RSX-llM-PLUS that allows your system to back up all new
data as it is written to a Files-II disk.
This chapter describes
Shadow Recording, how to prepare your system for it, and how to
control it. There is also a discussion of bad block handling and a
list of error messages.
Shadow Recording creates two identical sets of disks called a
shadowed
pair.
More than one pair of disks may be shadowed, but
shadowed disk pairs cannot overlap. The first disk of the pair, the
primary disk,
is the original disk that exists whether or not Shadow
Recording is active. You can make any disk on your system, including
the system disk, the primary disk of a shadowed pair. By using the
preparatory procedure described in Section 18.1 and the START command
described in Section 18.2, the second disk of the pair (the secondary
disk) becomes an exact copy of the primary disk.
II

The START command invokes a Shadow Recording task called SHAddn (or
SHddnn), where ddnn is the device unit of the primary disk. This task
is the catchup task that copies the primary disk to the secondary
disk. Shadow Recording occurs while catchup is in progress. In other
words, records are written to both the primary disk and secondary
disk, without interfering with the catchup process.
II

After you issue the START command, Shadow Recording provides a dynamic
backup of all blocks as they are written to the primary disk. Shadow
Recording has important uses in the following applications:
•

Duplicating important information to prevent
inadvertent
damage or loss.
With Shadow Recording, critical data is
duplicated on two disks. This redundancy prevents loss of
data if a disk error occurs and, therefore, may provide
quicker recovery time in critical
applications.
Also,
downtime may be reduced because disk errors do not necessarily
mean an application must be halted.

•

Providing on-line backup to give an lIinstant
duplicate
where later backup time or resources are unavailable.
ll

disk

The Shadow Recording feature operates transparently because writing to
and reading from the secondary disk is an Executive function. The
Execut~ive always writes the same data to the secondary
disk that it
writes to the primary disk when Shadow Recording is active. However,
when Cl disk read occurs, the Executive reads the primary disk first.
If a read error occurs on the primary disk, the Executive reads the
secondary disk. The Executive displays all I/O errors occurring on a
Shadow Recording disk pair on the operator's console.

18-1

RSX-IIM-PLUS SHADOW RECORDING

Now that you are generally familiar with Shadow Recording, proceed
first to Section 18.1 to prepare your system, and then to Section 18.2
to learn how to control Shadow Recording, beginning with the START
command.
START is one of five commands you can use to control Shadow
Recording. Note, however, that you can enter these commands only from
a privileged terminal.
If you encounter errors during any of the Shadow Recording procedures,
refer to Sections 18.3 and 18.4.

18.1

PREPARING YOUR SYSTEM FOR SHADOW RECORDING

More than one pair of disks can be shadowed, but shadowed pairs cannot
overlap.
For example, if you make DBO: and DBl: a shadowed pair,
you can make DB2: and DB3: a shadowed pair but not DB1:
and DB2:.
Additionally, the devices must be of the same type.
Before you can use a pair of disk drives for Shadow Recording, you
must have available two identical disk packs. The two disk packs must
have the same bad block data. You can make the bad block data on the
two
disks
functionally equivalent by following the procedures
discussed next.
In the following procedure, the assumption is made that you will
shadow record the system disk. However, the procedure is valid for
any two devices of the same type. To get ready for Shadow Recording,
you must perform the following actions for each shadowed pair:
1.

You must select Shadow Recording as an option during
generation before you can run Shadow Recording.

system

Determine which two device units you want to use for the
shadowed pair.
They must be the same type of device, for
example, two RP06s or two RM02s. One of these two devices
will be the device that will contain the primary disk that
you want to be "shadowed." The other will contain the
secondary disk.
If, for example, your system has four RP06s and you decide to
shadow record the system device, DBO:, you can select one of
the three remaining devices as the secondary device of the
shadowed pair: DBl:, DB2:, or DB3:.

Next, gather a set (three or more) of disks that you can use
for Shadow Recording. There are two principles involved with
the selection of the set of disks for Shadow Recording:
•

The disks being used for Shadow Recording must
be
logically equivalent (have the same bad blocks). To make
the disks logically equivalent, you select one disk of the
set as the primary disk and make its bad block descriptor
block a logical OR of all the bad blocks in the set of
disks.
Then, when you start Shadow Recording, the
contents of the primary disk,
including the bad block
information,
are
copied
to
the
secondary
disk.
Subsequently, the Executive writes the same data to the
secondary disk that it writes to the primary disk.
Because the bad block information on the primary disk is
an OR of its own bad blocks and those of the secondary
disk, the write to the secondary disk does not occur for a
defective block.

18-2

RSX-IIM-PLUS SHADOW RECORDING
You can make the disks logically identical by making
entries in the bad block descriptor block of the primary
disk (see step 4).
•

You can use another disk of the set as a spare, logically
equivalent disk in case of disk errors. This is why you
should have selected three or more disks for your set of
Shadow Recording disks.
Using one of these spare disks
enables quick recovery from possible disk errors and
decreases
downtime
in critical applications.
Error
recovery is discussed in Section 18.3.

Before you make entries in the bad block descriptor block of
the primary disk,
run the Bad Block Utility (BAD) with the
/LI switch on all the disks in the set of Shadow Recording
disks.
BAD locates the bad blocks and lists them on your
terminal. This list includes the information you need to
make the bad block descriptor block on the primary disk the
logical OR of all the bad blocks.
Now, you can make entries in the bad block descriptor block
of the primary disk by using the INITVOLUME command with the
/BAD=[MAN] keyword, as follows:
>INI ddnn:/BAD=[MAN]
After you enter the INITVOLUME command, the following
is displayed:

prompt

INI>LBN(S)=
In response to this prompt, you can then type from the
terminal the list of bad blocks.
(The INITVOLUME command is
described in greater detail in the RSX-IIM/M-PLUS
MCR
Operations Manual.) Also, this bad block information will be
used by subsequent INI, DSC, or BRU operations on this
volume.
The Disk Save and Compare Utility (DSC) and the
Backup and Restore Utility (BRU) are described in the
RSX-IIM/M-PLUS Utilities Manual.
5.

Copy the data from your system disk to your primary disk.
This disk becomes the primary disk and your new system disk
for Shadow Recording.
For example, if you want to shadow record your system disk,
copy it to the primary disk. After this is done, you will
have two system disks with identical data, but they will not
be identical physically because of the bad block locations.
The new system disk becomes the primary disk for shadow
recording.

Mount as foreign one of the previously selected disks on
secondary device. Use the following MOUNT command:

the

>MOUNT ddnn:/FOR
Now you are ready to use Shadow Recording, beginning
command (see Section 18.2).

18-3

with

the

START

RSX-IIM-PLUS SHADOW RECORDING
JL8.2

CONTROLLING SHADOW RECORDING

You can use five commands to control Shadow Recording.
The commands
allow you to start, stop, abort, or continue Shadow Recording and to
display all device pairs that are being "shadowed." The five commands
a.re:
1.

START

STOP

ABORT

CONTINUE

DISPLAY

Note, however, that
privileged terminal.
t~xample :

you can only enter these commands from a
You may enter these commands on one line, for

>SHAdow START
Or, you may enter the commands on two lines, for example:
>SHA
SHA>START
'rhe following sections describe the commands.

18-4

RSX-IIM-PLUS SHADOW RECORDING

START
18.2.1

START Command

The START command:
•

Verifies that the primary disk is a
mounted

•

Verifies that the secondary
device

•

Verifies that both
identical disk types

•

Sets up the Shadow Recording data structure (UMB) ,
starts the Shadow Recording task within the Executive

which

•

Starts the copying of the primary disk to the
(catchup)

disk

the

disk

Files-II
is

primary

device

and

foreign

mounted

and

secondary

disks

are

secondary

Format
START ddnn: TO ddxx:
Paramet~ers

ddnn:
The primary Files-II device
secondary Files-II device.

that

shadowed

the

ddxx:
The secondary device that is to
primary device.

the

shadowed

copy

The START command copies the primary disk onto any secondary disk of
the same device type.
After you make the bad block information
identical and then use the START command, the secondary disk becomes a
logical duplicate of the primary disk. This means that all copied
data blocks, bad blocks, headers, directories, and so forth occupy the
same logical locations on the secondary disk as they do on the primary
disk.
Both disks have equivalent logical block numbers and, in the case of
system disks, both disks are bootable.
In addition, after the START
command is issued, the secondary disk becomes a Files-II format disk
becausE:! the START command makes an exact copy of the primary disk on
the secondary disk.
If new data is written to the primary disk after Shadow Recording is
initiated with the START command, Shadow Recording also writes the new
data to the secondary disk. That is, when a write occurs on the
primary disk,
it also occurs on the secondary disk. However, the
secondary disk can only be read from the last portion that has been
copied.
The information about the last block copied is in the UMB
control block. A fully redundant secondary disk does not exist until
catchup has completed.
Further action on your part is unnecessary
unless you want to stop Shadow Recording.

18-5

RSX-IIM-PLUS SHADOW RECORDING

STOP
18.2.2

STOP Command

The STOP command:
•

Verifies that the primary device is part of a shadowed pair

•

Unlinks the UMB data structure, if no outstanding I/O
thereby stopping the Executive from Shadow Recording

•

Marks the data structure for deletion if outstanding I/O
exist

exists,
does

Format

STOP ddnn:
Parameters

ddnn:
The device unit of the primary device.
The STOP command prevents Shadow Recording from continuing.
However,
during catchup, the STOP command cannot stop Shadow Recording.
In
fact, if you issue the STOP command during catchup, you receive an
error message. To stop Shadow Recording during catchup, use the ABORT
command (see Section 18.2.3).
The absence of outstanding I/O does not necessarily mean that all file
activity has stopped. You must make certain that all tasks that write
records to the shadowed pair have stopped to ensure the integrity of
the secondary data before you issue STOP or ABORT.

18-6

RSX-IIM-PLUS SHADOW RECORDING

ABORT
18.2.3

ABORT Command

The ABORT command:
•

Verifies that the primary disk is part of a shadowed pair

•

Aborts catchup if it is in progress and then executes
command

•

Stops Shadow Recording even if catchup is in progress

Format
ABORT ddnn:
Parameters
ddnn:
The device unit of the primary device.

18-7

STOP

RSX-IIM-PLUS SHADOW RECORDING

CONTINUE
18.2.4

CONTINUE Command

'1'he CONTINUE command:
•

Assumes that the primary and secondary disks are identical

•

Verifies that the primary
mounted properly

•

Verifies that the secondary disk is mounted foreign

•

Verifies that both disks are identical device types

•

Sets up the Shadow Recording data structure,
Shadow Recording within the Executive

disk

Files-II

format

which

and

starts

Format
CONTINUE ddnn: TO ddxx:
Parameters
ddnn:
The device unit of the primary device.
ddxx:
The device unit of the secondary device.
'rhe CONTINUE command allows you to restart Shadow Recording on the
same two disks that you were using when the STOP command was issued.
The CONTINUE command assumes that the two disks are physically alike,
.and it does not check the disks for equality. You must be sure that
no writing occurred on the primary or secondary disks after you issued
the STOP command.

18-8

RSX-llM-PLUS SHADOW RECORDING

DISPLAY
18.2.5

DISPLAY Command

The DISPLAY command shows all shadowed pairs.
Format
DISPLAY
The shadowed device pairs are displayed in the following format:
UMS

PRIMARY

SECONDARY

ddnn:

ddxx:

Parameters
xxxxxx
xxx xxx
Th4~

address of the UMS control block for Shadow Recording.
control block is in the system Executive pool space.

ddnn:
Th.~

device unit of the primary device.

ddxx:
The device unit of the secondary device.

18-9

This

RSX-IIM-PLUS SHADOW RECORDING

18.3

BAD BLOCK HANDLING

.Except for the START command, which copies the primary disk to the
secondary disk, the Executive writes the data from a task buffer to
the primary disk and then writes it from the task buffer to the
secondary disk.
If write errors occur on one of the disks, you may
not know it until the Executive attempts to read the block in error.
To be notified of write errors as they occur, you can run Shadow
Recording with write check for both disks of the shadowed pair. The
MCR command:
>SET /WCHK=ddnn:
enables write check on the device that you specify in ddnn:. However,
be aware that a write check of every write operation takes more time
to execute than a write only.
When write check is enabled, the Shadow Recording program prints the
error messages on the console terminal. These error messages consist
of device and logical block numbers when available.
In the case of a read, the Executive reads from the primary disk
first.
If it encounters an error on the primary disk, it reads the
same record from the secondary disk.
It is unlikely that both disks
would develop an error in exactly the same place. However, if they
do, a notification of read errors on the secondary disk means that the
primary disk is also bad in the same location.
If read errors occur, several procedures can be followed, as discussed
in the following subsections.

18.3.1

Errors on the Primary Disk

If errors occur when the Executive tries to read from the primary
disk,
the Executive tries to read the same record from the secondary
disk. You are notified of the errors by a message on the console and,
at this point, you may decide to let your task continue.
If you do
decide to let your task continue, be aware that the shadowed pair are
no longer alike.
If you decide not to let your task continue, stop the processing task
(or tasks) and use the STOP command to stop Shadow Recording. The
secondary disk contains all the data that was on the primary disk,
including the bad block record. Use the secondary disk as the new
primary disk. Designate a new device of the same type for the new
secondary disk. Mount the new secondary disk on the secondary device
as foreign.
After mounting the old secondary disk on the primary device as the new
primary disk,
issue the START command. The START command causes the
copying of the primary disk to the secondary disk, including the bad
block record.

18.3.2

Errors on the Secondary Disk

If errors occur on the secondary disk, the shadow of the primary data
is no longer valid.
Shadow Recording should be stopped, a new
secondary disk should be mounted, and Shadow Recording restarted. The
catchup task will then copy the primary disk to the new secondary
disk.

18-10

RSX-IIM-PLUS SHADOW RECORDING
18.3.3

Errors on the Primary and Secondary Disk

The simultaneous occurrence of bad data in the same blocks of two
different
disks
is unlikely,
and this kind of error is not
recoverable.
However, whether or not an error occurs at the same or
different places on both disks, the only recourse is to stop Shadow
Recording and your tasks. Then, select a new primary disk and new
secondary disk, mark the bad block information on the new primary disk
as before, and copy the old primary disk to the new primary disk.
If the error occurred on different blocks on both disks, the
previously processed information can be salvaged by using the old
primary and secondary as a shadowed pair input to the Backup and
Restore Utility (BRU). BRU copies all the data that is on the input
disk and writes it to the output disk.
If you use a shadowed pair as
input to BRU, only the good data is written to the output disk because
of the alternative read that the Executive does on the secondary disk
if primary disk errors occur.
Using BRU will not give you a new primary disk. You must create a new
primary disk from the output of BRU as discussed in Section 18.1.
Information about how to use BRU is in
Manual.

18.4

the

RSX-llM/M-PLUS

Utilities

SHADOW RECORDING MESSAGES

hh:mm:ss -- Handler Error code-nne on ddnn:
Shadow Pair: ddnn: ddxx:
Task: xxx xxx
Logical Block: nnn.
Bytes in xfer: nnn.
File 10: n,n
File Name: xxxxxx
nne errors lost due to saturation.
Explanation:
hh:mm:ss
The time in hours, minutes, and seconds of the error.
code-nne
The I/O error code (decimal) for the error.
I/O error codes
Mini-Reference.

are

summarized

the

RSX-llM-PLUS

File 10
File Name
The file 10 and file name are printed only when they can
determined at the time of the error.

nne errors lost
When an error occurs on a shadowed disk,
the Executive
notifies the shadow error reporting task that prints the
above message on the console terminal. The Executive stores
the information about the error in pool for the error
reporting task to pick up and print.

18-11

RSX-llM-PLUS SHADOW RECORDING

If more than fifteen errors occur rapidly, pool can fill up
with error information before the error reporting task can
process it. This may cause a shortage of pool,
so that
there may be no pool left to run the system. To prevent
this from occurring, the Executive allows only as many
errors as it can process to be queued in pool at one time.
If fifteen errors have already taken place, and still more
errors occur, the Executive keeps track of the errors
without processing them. The message linn.
errors lost"
tells the user how many errors were ignored. The term
"saturation" refers to pool being saturated with as many
error messages as the Executive limit allows.
This message is only
processed.

not

been

Explanation: This message occurs if the Shadow Recording
command cannot abort Shadow Recording during catchup.

ABORT

User Action:

printed

when

errors

have

See Section lS.3, Bad Block Handling.

SHA -- Abort error

User Action: Wait until catchup terminates and
STOP command.

then

issue

the

SHA -- Bad indirect file specification
Explanation:

The indirect command file name is incorrect.

User Action:

Reissue the indirect command file specification.

SHA -- Bad volume type
Explanation: The disk is not in Files-II format or
and secondary devices are different device types.
User Action: Check the command line
trying to use.

devices

the
that

primary
you

are

SHA -- Catch-up completed
Explanation: This is an informational message. The primary disk
has been copied completely to the secondary disk.
User Action:

None.

SHA -- Catch-up in progress
Explanation: You tried
catchup process.
User Action:
progress.

issue

Issue an ABORT

command

lS-12

STOP
if

command
catchup

during

the

still

RSX-llM-PLUS SHADOW RECORDING
SHA -- I/O error on logical block nnn.
Explanation:

An I/O error occurred during catchup.

User Action: None, unless the I/O errors are frequent.
If the
I/O errors are frequent, enter the ABORT command, change disks,
and restart Shadow Recording.
SHA -- Illegal command
Explanation:
command.

The

command

that

User Action:

Reenter the command.

you

enterec.

not

legal

SHA -- Input error on input command file
FILE=
Explanation: An error occurred while the indirect
was being read.
User Action: Take
different indirect
command file.

command

file

appropriate action;
for example, use
a
command file, or use a copy of the specified

SHA -- Illegal parse data (internal error)
Explanation: This is an internal system error.
correctly entered.
User Action:

The command

was

Reenter the command.

SHA -- Invalid device
Explanation:

The device is not a disk device.

User Action:

Check the device specification and the device.

SHA -- Maximum indirect command file depth exceeded
Explanation: The indirect command file was nested
levels. Only three levels are allowed.

too

many

Explanation: Not enough pool space exists to allocate space
the UMB control block for Shadow Recording.

for

User Action:

Check the indirect command file.

SHA -- No room available for UMB

User Action: Check your system.
of running out of pool space.

18-13

The system may be on the

verge

RSX-IIM-PLUS SHADOW RECORDING
SHA -- Not a shadowed pair
Explanation:
specified.

When STOP or ABORT was issued, the wrong device was

User Action:

Reissue the command with the correct device unit.

SHA -- Open error on input command file

FILE=
Explanation:

The input command file could not be found.

User Action:

Check the command file and its location.

SHA -- Privileged command
Explanation:

You are not using a privileged account or terminal.

User Action:

SHA -- Send/Receive error
Explanation: A Receive Executive
Shadow Recording during catchup.
User Action:

None.

directive

error

occurred

This is a system error.

SHA -- Shadow Recording not in system
Explanation:

Shadow Recording is not part of your system.

User Action:
generation.

Shadow

Recording

must

specified

system

SHA -- Start-up error
Explanation: Shadow Recording cannot spawn the catchup task,
Shadow Recording exits.
User Action:

Restart Shadow Recording.

SHA -- Syntax error
Explanation:

The entered command has incorrect syntax.

User Action:

Reenter the command.

SHA -- System error
Explanation:

A system error occurred.

User Action:

Determine the effects of the error if possible.

18-14

RSX-llM-PLUS SHADOW RECORDING
SHA -- Unknown command error
Explanation: Shadow Recording received a command
could not recognize.

line

User Action: Check the command that you entered or the
command file.

that

indirect

SHA -- Volume currently part of shadowed pair
Explanation:
rE~corded .

The

specified

device

already

User Action:
command.

Check the devices being shadowed with

being

shadow

the

DISPLAY

SHA -- Volume not mounted properly
Explanation: The primary device is not mounted Files-II, or
sE~condary device is not mounted foreign.
User Action:

Check the devices and mount them properly.

18-15

the

CHAPTER 19
DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS

Disk data caching is a feature on RSX-llM-PLUS and Micro/RSX systems
that Emhances I/O operations by reducing the number of physical I/O
requests directed to a disk.
The Dat:a Cache Manager (DCM), also referred to as the
cacher
acts
as an intelligent preprocessor to any disk driver.
In addition to
monitoring all I/O operations performed on disk devices, the DCM
decreases the number of physical I/O operations taking place on
cached disk drives by using a cache region in memory.
Copies of
disk data are placed in the cache region, making the data available
for mernory-to-memory transfers instead of disk-to-memory transfers
during an I/O request.
II

II ,

The DCM option is enabled by default on Micro/RSX systems and on
pregen~~rated
RSX-llM-PLUS systems. The DCM can be chosen as a system
generation option for RSX-llM-PLUS systems; it is included as part of
the Full-functionality Executive.
Disk data caching must be activated explicitly for a disk.
You can
activate, disable, override, monitor, or modify disk data caching
using -the commands in Sections 19.4 and 19.5.

19 . 1

DATA CACHE FEATURES

Disk data caching is available for various types of I/O operations.
Cachin9 is most effective when blocks of data are read repeatedly or
accessed sequentially in small increments.
The following
list
describes types of I/O operations that can be enabled or disabled for
da ta c,aching.
•

Directory I/O
Enabled by default, this operation can be disabled.
All I/O
operations which are issued by an ACP task with context
switching enabled are treated as "directory 1/0" operations.
Typically, this would be for files such as [O,O]BITMAP.SYS;,
[O,O]INDEXF.SYS;, and the [O,O].DIR [directory] files.

•

Overlay Loads
Enabled by default, this operation can be disabled.
All
IO.LDO and IO.LOV operations are cached depending on their
size. If the load request is considered to be too large, then
the request is not cached. This prevents overlay loads from
monopolizing the cache buffers.

19-1

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
•

Data I/O
Enabled by default, this operation can be disabled.
All
IO.RVB and IO.WVB operations are cached. Operations which are
issued by an ACP with context switching disabled are also
considered data I/O, to differentiate them from directory I/O.

•

User logical I/O
Disabled by default,
this operation can be enabled.
All
IO.RLB and IO.WLB operations (not from an ACP) are considered
logical I/O.
Typically, tasks that use logical I/O are doing
so for a special purpose.
BRU,
for example, reads file
extents randomly throughout the disk.
In this case, there is
little to gain by caching this class of operations.

•

Read ahead for virtual I/O
Disabled by default, this operation can be enabled. When the
highest block of a cache extent is read using a virtual read,
then, if there is sufficient context, another extent of the
file's data is loaded automatically by the cache, without
having been requested by the user.
The maximum number of
blocks that can be read is the number of blocks in the extent
or the number of blocks in the maximum extent size.
This
operation is beneficial for disks that contain numerous
sequential files which are frequently accessed sequentially.

Cache I/O is handled by the cache code.
During a read operation for a
t,ype of I/O that is to be cached, the DCM intercepts an I/O request
and checks the request against the data stored in memory.
If the
correct data is stored in memory, the DCM processes the request. If
the cache does not contain the requested data, the DCM forwards the
I/O request to the appropriate driver for processing. When the
physical I/O completes, the DCM resumes processing by copying the
appropriate portion of the data to the user's buffer.
During a write operation for a type of I/O that is to be cached,
the
appropriate data is copied from the user's buffer to the corresponding
cache buffer.
If there is no corresponding cache buffer, the request
is forwarded to the disk driver for processing, and the data is not
cached. When the copy operation is finished, the DCM completes the
I/O by passing the user's packet to $IOFIN.
Special handling is required to ensure that the cache buffers reflect
valid data for mounted disks only.
For that purpose, the cache
handles the IO.STC operation.
Normally, IO.STC is issued by the MOUNT
command as part of mount processing, and by DMOUNT as part of dismount
processing (for /UNLOAD) in order to set hardware and software volume
valid.
When the cache manager receives the mount parameters, it
initializes the cache (this may include purging the cache before
initialization to prevent stale data from a removed disk pack from
being used), and duplicates and dispatches the user's packet while
retaining the original request. The status is returned to the user
via $IOFIN.
If the operation was successful, the related cache region
use count is incremented,
to prevent its deallocation.
When a
dismount packet is received, the user's packet is stalled until all
outstanding buffers
(if any)
are written to the disk first. All
further cache processing is disabled for that device. When the cache
context for the drive is clear,
the stalled dismount request is
forwarded to the driver.

19-2

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
19.2
The

DATA CACHE MANAGER (DCM)

Cache Manager (DCM) is the code that provides data cache
It resides in a directive common. The DCM is responsible
for monitoring disk data cache operations. It ensures that disk data
is stored in memory and that the data stored in meffiory is available
for USE! during I/O requests.
Dat~a

support~.

The DC~1 executes wi thin the I/O system after all packet preprocessing
and before disk driver activation. The DCM will execute if the device
is a mass storage device (DV.MSD) and not a tape device (not DV.SQD).
If thE~ device to which an I/O request is directed is not a disk (or
the cache support is not within the Executive), the driver will be
mapped and activated at the initiation entry point. The positioning
of the DCM at this point in processing allows all I/O packets to be
intercE~pted
when all but the driver processing (including the
placemE~nt of the request into the device queue) has been performed for
the packet.
In order for the cacher to run, regions must be established for
cachin9, and the devices which are to use them must be notified. This
requirE~s that the appropriate commands be used to
define and enable
cachin9 (see sections 19.4 and 19.5).

19.2.1

PERMANENT DCM IN A SYSTEM CONFIGURED USING VMR

The following VMR commands are provided in SYSVMR.CMD to permanently
incl udE~ disk data caching as a directive common in the bootstrapped
system::
INS DCMEXP
FIX DCMEXP/DIR

19.3

THE DATA CACHE REGION

A data cache region must be created and formatted before caching is
activated.
If you want to use a region other than the default region
provided by the system, you must specify the region name when you
create a cache region.
When the device{s) associated with a cache
region has completed processing, the cache region is deactivated (but
not deleted) by a DISMOUNT or SET command. Section 19.4 describes the
DCL crnnrnands used to specify, create, and deactivate a cache region.
Section 19.5 describes MCR commands to specify, create, and deactivate
a cachle reg ion.
The data cache region contains extents.
Extents are ranges of
physically contiguous memory blocks which are memory-resident copies
of ranqes of physically contiguous disk blocks.
These blocks are
tagged with their corresponding disk logical block numbers (LBN) so
that they can be found in the cache.
The blocks of disk data are stored in a cache region during a request
for a read operation or when read-ahead is enabled. If read-ahead is
enabled, blocks of data residing in the same extent as a read request
are also placed in the cache region. As blocks of data are placed in
a cache region, they are tagged with their LBNs so that the data can
be found during a subsequent I/O request.

19-3

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
~'o maintain a data cache region, adequate memory must be available
to
hold copies of the disk data in the cache region. You can use the
SHOW command to monitor a cache region as well as the activity of the
DCM.
See Sections 19.4.2, 19.5.2, and 19.5.3 for information on
monitoring a data cache operation.

~'ypical

RSX-IIM-PLUS and Micro/RSX systems define one main partition
for general use.
This partition, named GEN by default, may contain
nlany regions.
These regions can be commons, Extended Executive
Partitions (EXP), and task images.
For disk caching purposes, a
region is used to contain the cache-specific data structures and disk
data buffers.
This region can have any name.
It is marked with the
following PCB status bits:
P.STAT
PS.FXD - Region is fixed in memory
PS.NSF - Region is not shuffleable
PS.COM - Region is a common
P.PRO - Protection word blocking all access [,' ,]
P.ST2
P2.RON - Read only (external users)
P2.APR - Depends on Executive:
P2.APR = 5 for I/O systems
P2.APR = 6 for non-I/O systems
P2.LMA - Do not remove this region
P2.CHE - Cache region (informational only)
Cache regions may be shared by mUltiple devices, or one region may be
used exclusively by one device. When caching is enabled for a device,
t~he system default cache region, named CACHE, is used
unless another
region is specified.
This "other" region must be created and
formatted for the cacher to be able to use it. The region may also be
in use by another device that has caching enabled.

19.3.1

CREATION AND DELETION

Data cache regions are allocated and deallocated by the appropriate
commands. The region is formatted at the time of creation. When data
caching is enabled for a disk device, the Unit Control Block Extension
(UCBX) is marked with the address of the data cache region (PCB). To
force the binding of the region with the device to prevent illegal
deallocation, the P.RMCT field (resident, mapped task count) reflects
the number of devices which currently have caching enabled for that
region.
The region cannot be deleted as long as P.RMCT is non-zero.
When there are no devices with access for that region, P2.LMA is
cleared, allowing the region to be removed from the system.

19.3.2

FORMAT

The data cache region has two parts.
(See Figure 19-1.) The beginning
of the region contains pool space. Non-I/O systems map pool through
APR 6 and have a 4KW limitation; I/O systems map pool through data
space APR 5 and APR 6 with an 8KW limitation. The standard $ALOCB
(entry point $ALOCl) and $DEACB (entry point $DEACl), which are the
pool allocation and deallocation routines within the Executive, are
used to allocate and deallocate space from this area.
The dynamic
data structures, which are cache-specific, are retained in this area
t~o minimize the load of data caching on
the primary pool resource.
The remainder of the cache region is used to buffer disk data blocks.
It is allocated on 32-word boundaries in 256-word increments.
19-4

lDISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
The Cache Extent Descriptor (CED) is a data structure within the
region' :s pool that describes all data buffer space in the cache
region, whether the space is in use or not.
This allows contiguous
blocks of space to be reclaimed when needed.

} Cache-specific pool

~----------------~

Disk data buffer space

ZK-4187-85

Figure 19-1: Format of Data Cache Region
The pool area of the cache region contains a header which is used
control various region-specific structures.
(See Figure 19-2.)
H.CSTS

+00

H.IIOC

H.PAVL

+02

H.PKTQ

H.CMDH

H.CEDH

+10

+14

+20

H.TEMP1

+24

H.TEMP2

+26
ZK-4188-85

Figure 19-2: Format of Pool Header Area
H.CSTS Region code status.
defined in this byte:

The following

CS.REQ = 1
CS.RIN
2
CS.DNF
4

19-5

bits

are

DISK DATA CACHING O~ RSX-IIH-PLUS AND MICRO/RSX SYSTEMS
is

not

Region internal I/O count.
used by the data cache.

H.PAVL

Pool available list. This is a standard
3-word pool list head, which contains the
alignment word followed by the list head,
which is a pointer to the next available
block and the size of the block.

H.PKTQ

Pending packet
queue
(in
descending
priority
order).
These
packets are
waiting
for
data
cache
completion
processing.
They either have I/O in
progress, are waiting for data movement to
begin, or are waiting to be dispatched to
either the user [$IOFIN] or the driver.

H.CMDH

List head
allocation.

H.CEDH

(the
List head for CEDs ordered by age
oldest are at the head of the queue) •

H.TEMPI

Pointer used in allocating new extents

H.TEMP2

Pointer used in allocating new extents

for

region

The region is formatted before caching is
disk devices.

19.4

This

H.IIOC

space

buffer

enabled

any

dependent

DCL COMMANDS USED WITH DISK DATA CACHING

This section describes the DCL commands and qualifiers you use
the following:
•

Associate caching with a device

•

Specify the type of caching you want enabled

•

Monitor data cache operations

•

Modify data cache operations

19.4.1

MOUNT Command

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
Oualifiers
/CACHE
Lets you associate caching with the specified disk, and allows
you to override the disk data caching defaults and set one or
more of the options.
The following options are available with disk data caching:
CREATE[:[region][:[main_partition][:[cache_size]]]]
REGION: name
[NO]DIRECTORY[:extent size]
[NO]LOGICAL[:extent sIze]
[NO]OVERLAY[:extent-size]
[NO]READ AHEAD[:extent size]
[NO]VIRTUAL[:extent_size]
The extent size argument specifies the maximum size of an I/O
request that will be considered for caching. The extent size
radix is decimal. The minimum value for an extent size is Ii the
maximum is 15. Extent sizes can be modified for cached devices
using the SET command.
/NOCACHE
Specifies that caching is not associated with
mounted.

the

device

being

Options
CREATE[:[region][:[main_partition][:[size]]]]
Creates a cache region and associates caching with the
device in that region.

specified

The default name for the region is CACHE: the default name for
the main partition is GEN. The default size is lOO(decimal) disk
blocks.
REGION: name
Associates caching for
existing cache region.

the

specified

device

You can specify a region to be used in
default. The default region is CACHE.

with

already

the

system

This is

the

system

place

[NO]DIRECTORY[:extent_size]
DIRECTORY enables caching of directory I/O.
default and need not be specified.

NODIRECTORY disables caching directory I/O.
You must specify
this option if you want to disable caching of directory I/O.
The default extent size for DIRECTORY is 1.
[NO]LOGICAL[:extent_size]
LOGICAL enables caching of logical I/O. You must specify
option if you want to enable caching of logical I/O.
NOLOGICAL disables caching of logical I/O.
~le

default extent size for LOGICAL is 1.
19-7

this

This is the default.

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
[NO]OVERLAY[:extent_size]
OVERLAY enables caching of
default.

overlay

I/O.

This

the

system

NOOVERLAY disables caching of overlay I/O. You must specify this
option if you want to disable caching of overlay I/O.
The default extent size for OVERLAY is 4.
[NO]READ_AHEAD[:extent_size]
READ AHEAD enables reading of data (for virtual I/O) before
explIcitly requested.
You must specify this option if you want
to enable reading of data before explicitly requested.
NOREAD AHEAD disables reading of data
requested. This is the default.

before

explicitly

This

the

The default extent size for READAHEAD is 5.
[NO]VIRTUAL[:extent_size]
VIRTUAL enables caching of
default.

virtual

I/O.

system

NOVIRTUAL disables caching of virtual I/O. You must specify this
option if you want to disable caching of virtual I/O.
The default extent size for VIRTUAL is 5.

19.4.2

SHOW CACHE Command

Once disk data caching is established through the MOUNT or SET
command, you can monitor the performance of data caching using the DCL
command SHOW CACHE.
This command allows you to display system
information on data caching. To display data cache information on a
specific device, you must supply the device name on the command line.
Format
SHOW CACHE [/DEVICE=ddnn:] [/REGION=name] [/RATE:n]
Qualifier
/DEVICE=ddnn:
Specifies the device about which you want to display detailed
data cache information. Note that /DEVICE and /REGION cannot be
used together.
/REGION=name
Specifies the cache region about
general data cache information.
cannot be used together.

which you want to display
Note that /DEVICE and /REGION

/RATE:n
Specifies in seconds the rate at which the screen refreshes.
default rate is 1 second.

19-8

The

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
19.4.3

SHOW DEVICE Command

Once disk data caching is established through the MOUNT or SET
command, you can list cached devices using the DCL command SHOW
DEVICE. This command displays information about devices recognized by
the system.
To display information about a particular device, you
must specify the device name on the command line.
Format
SHOW DEVICE [ddnn:] /[NO]CACHE
Parameter
ddnn:
Specifies the device for which you are displaying information.
Oualifier
/CACHE
Lists all devices known to the system
device is specified).

that

are

cached

(if

/NOCACHE
Lists devices that are not cached, but could be cached.

19.4.4

SET DEVICE Command

To modify data caching on your system, or to associate caching with a
device, use the DCL command SET DEVICE. This command allows you to
modify various system values and behavior. To modify the behavior or
the va.lue of specific devices, you must supply the device name. Note
that a region associated with a specific device cannot be modified
while caching is enabled for that device.
Format
SET DEVICE ddn:

/[NO]CACHE[:(option,option, ... )]

Paramet.er
ddnn:
Specifies the device you are mOdifying.
Oualifi.ers
/CACHE
Modifies the data caching behavior for the specified device.
may modify the following options:
CREATE[:region][:[main partition][:[cachesize]]]]
REGION: name
[NO]DIRECTORY[:extent size]
[NO]LOGICAL[:extent sIze]
[NO]OVERLAY[:extent-size]
[NO]READ AHEAD[:extent size]
[NO]VIRTUAL[:extent_size]

19-9

You

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
The extent size argument specifies the maximum size of an I/O
request that will be considered for caching. The extent size
radix is decimal. The minimum value for an extent size is 1; the
maximum is 15. Extent sizes can be modified for cached devices
using the SET command.
These options are described in Section 19.4.1.
/NOCACHE
Deactivates caching for the specified device.

19.5

MCR COMMANDS USED WITH DISK DATA CACHING

This section describes the MCR commands and qualifiers you use
the following:
•

Associate caching with a device

•

Specify the type of caching you want enabled

•

Monitor data cache operations

•

Modify data cache operations

19.5.1

MOUNT Command

The MOUNT command makes a disk volume available for processing.
To
associate caching with a selected disk, use the /CACHE qualifier with
the MOUNT command.
Format
MOUNT ddnn:volumelabel /[NO]CACHE[: (option,option, ••• )]
Parameters
ddnn:
Specifies the device on which the volume is to be mounted.
volumelabel
Specifies the name that is associated with that volume.
Qualifiers
/CACHE
Lets you associate caching with the specified disk, and allows
you to override the disk data caching defaults and set one or
more of the options.
The following options are available with disk data caching:
CREATE [: [region] [: [main parti tion] [: [cache_size]]] ]
REGION:name
[NO]DIRECTORY[:extent size]
[NO]LOGICAL[:extent sIze]
[NO]OVERLAY[:extent-size]
[NO]READ AHEAD[:extent size]
[NO]VIRTUAL[:extent_size]
19-10

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
The extent size argument specifies the maximum size of an I/O
request that will be considered for caching. The extent size
radix is decimal. The minimum value for an extent size is 1: the
maximum is 15. Extent sizes can be modified for cached devices
using the SET command.
/NOCACHE
Specifies that caching is not associated with
mounted.

the

device

being

Options
CREATE[:: [region] [ : [main_partition] [: [size]]]]
Creates a cache region and associates caching with the
device in that region.

specified

default name for the region is CACHE: the default name for
main partition is GEN. The default size is lOO(decimal) disk
blocks.
ThE~

thE~

REGION:name
Associates caching for
existing cache region.

the

specified

device

You can specify a region to be used in
default. The default region is CACHE.

with

already

the

system

This is

the

system

place

[NO]DIRE:CTORY[: extent_size]
DIRECTORY enables caching of directory I/O.
default and need not be specified.

NODIRECTORY disables caching directory I/O.
You must specify
thi.s option if you want to disable caching of directory I/O.
The default extent size for DIRECTORY is 1.
[NO]LOGICAL[:extent_size]
LOGICAL enables caching of logical I/O. You must specify
opt.ion if you want to enable caching of logical I/O.
NOLOGICAL disables caching of logical I/O.

this

This is the default.

The default extent size for LOGICAL is 1.
[NO]OVERLAY[:extent_size]
OVERLAY enables caching of
default.

overlay

I/O.

This

the

system

NOOVERLAY disables caching of overlay I/O. You must specify this
option if you want to disable caching of overlay I/O.
The default extent size for OVERLAY is 4.
[NO]READ_AHEAD[:extent_size]
READ_AHEAD enables reading of data (for virtual I/O) before
explicitly requested.
You must specify this option if you want
to enable reading of data before explicitly requested.

19-11

DISK DATA CACHING ON RSX-llM-PLUS AND MICRO/RSX SYSTEMS
NOREAD AHEAD disables reading of data
requested. This is the default.

before

explicitly

This

the

The default extent size for READAHEAD is 5.
[NO]VIRTUAL[:extent_size]
VIRTUAL enables caching of
default.

virtual

I/O.

system

NOVIRTUAL disables caching of virtual I/O. You must specify this
option if you want to disable caching of virtual I/O.
The default extent size for VIRTUAL is 5.

19.5.2

RMD C Command

Once disk data caching is established through the MOUNT
command, you can use the RMD command to monitor performance.

SET

The RMD command allows you to display various pages of system
information.
The RMD C command allows you to display the C page,
which shows general statistics about a particular cache region. After
you analyze this information, you can use the SET command to modify
system values and behaviors to possibly enhance performance.
Format
RMD C [,REGION=region][,RATE=nn]
Setup Commands
REGION
Selects the cache region to be displayed.
CACHE.

The default region

RATE
Specifies the number of seconds between
default is 1 second.

screen

refreshes.

The

Example
Figure 19-3 is a sample RMD C page display; it is followed by
explanation.
RSX-11M-PLUS V3.0

BL21B

Cache Statistics

o Cache Re<:li.on NaRle: CACHE 8 Regi.on S i
Device
Name
DR4:
DR5:

48 Total

e e 0 0
Total Hit Fail

·;·~e:

/1-MAR-85 09:49:39

(Gener~l)

~')()()O

(288. di.s¥.. blocks)

Reads Rate Rate Rate
117165.
69i.
:~i.
18i.
21691..
271.
!59i.
?i.

Hjt F i~ i 1 Defer
Wl'l l()(~ R-ilte Rate Rate
t,9i.
25666.
01.
01.
3f>;~
12336.
ot.:
01.

Tr.lta]
tiD f)ps
1.42831
34027.

138856.

38002.

176858.

l.oad

63i.

37.

2~;i.

Total

58%

07.

01.

Cache
Used
6~=j I.

33i.

991.
ZK-4184-85

Figure 19-3: RMD C Page Display

19-12

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
~

Cache Region Name indicates the name of the cache.

Region Size shows the actual memory size in octal of the
cache region in 32-word memory blocks. This size includes
the private cache pool area as well as the extent storage
area. The second part of the size field displays the size of
the extent storage area in disk blocks.

The Total Reads field displays the count of all read requests
issued to that device.
These include VIRTUAL, READAHEAD,
DIRECTORY, LOGICAL, and OVERLAY read requests.

The Hit Rate is the percentage of all read requests that were
satisfied by the cache.

The Fail Rate is the percentage of all read requests that
could not be satisfied by the cache because of an extent
overlap or a cache pool allocation failure, or because the
request size exceeded the specified extent size limit.
Actual errors in loading the cache from the disk are not
counted in this rate.

The Load Rate is the percentage of all read requests that
resulted in data being loaded into the cache. The total of
the Hit, Fail, and Load rates should be close to 100%.
The
total may not always equal 100%, because read requests can
fail because of a primary pool allocation failure, which is
not associated directly with read or write requests. The
failure rate of primary pool allocation is shown on the RMD D
page: it should be small.

The Total Writes field displays the count of all write
requests issued to that device.
These include VIRTUAL,
DIRECTORY, and LOGICAL write requests.

The Hit Rate is the percentage of all write requests
caused updating of blocks already loaded in the cache.

The Fail Rate is the percentage of all write requests that
could not be directed to the cache because of an extent
overlap. The Hit Rate and Fail Rate will not total 100%,
because a write miss is not considered a write failure.
Also, write requests to a cache can fail because of a primary
pool allocation failure, which is not associated directly
with read or write requests. The failure rate of primary
pool allocation is shown on the RMD D page: it should be
small.

The Defer Rate is the percentage of all write requests that
were deferred: that is, the actual write operation to the
disk was done some time after the user's write request was
completed.

that

The Total I/O Operations is the total of all read
operations for that device.

and

write

The Cache Used field indicates the percentage
extent storage area used by the device.

the

cache

The bottom line displays the grand totals for the region.

19-13

DISK DATA CACHING ON RSX-llM-PLUS AND MICRO/RSX SYSTEMS
1.9.5.3

RHD D Command

'rhe RMD D command allows you to display the D page of the RMD display,
which shows detailed statistics about a particular cached device.
After you analyze this information, you can use the SET command to
modify system values and behaviors to possibly enhance performance.
Format
RMD D[,DEVICE1=ddnn:][,RATE=nn]
Setup Commands
DEVICEl
Specifies the device to be displayed.

The default device is SY:.

RATE
Specifies the number of seconds between
default is 1 second.

screen

refreshes.

The

Example
Figure 19-4 is sample RMD D page display; it is
explanation.
RSX-llM-PLUS V3.0
Device Name:

BL2tB

SYO:

8 Cache StatlJs: Act i ve

Cache Statistics

(Det~iled)

followed

21-MAR-85 09:46:02

o Resion Name: CACHE

R~(~I.I~sts

Rp'~{j (In Size:
5000
Being Cached: Dir,OvT',Vir

77515.
e Reads
Read Hit Rate
731.
o Read Load Rate 22r.

Readahead

[lj T'ectorY

Logical

OVE'T'lClY
16919.

Total
1161.89.

01.

49r.

69~~

01.

::1.1755.
72%
171.

41.

191.

or.
3r.

or.

Or.
Or.

or.

Or.

21.

•

1•

12956.

12507.

t O~j.

91r.

Or.

25568.

48i.
Oi.

01.

51.

69i.
Oi.

34262.

105.

Virtual

{ Read Overlap
E:·:tent Too Big
CD Ma:-: E:-:tent Size
•

Writes

~{wr~te Hit Rate
~

Wrlte Overlap

CD Total I/O
~

90471.

01.

Or.

16919.

Primar~ Pool Allocation Failure Rate,' (as a i. of Total liDs):
Cache Pool Allocation Failure Rate (as a % of Total Rf.'ad I/Os)!
Rear.! Loar.! Failure Rate (as a I. of Cache Load liDs)!
Deferred Write Rate (as a % of Total Write liDs):

141757.

or.
01.

Or.
01.
Z'<-4185-85

Figure 19-4: RMD D Page Display

t»

•

The Region Name and Region Size fields are the same as in the
C page description, except that the extent storage area size
in disk blocks is not displayed .
The Cache Status field shows whether the cache is ACTIVE
ACTIVE means the device is being cached
and/or ENABLED.
through the region;
ENABLED means that the device will
automatically be cached when it is mounted (even if the MOUNT
command does not explicitly request that the device be
cached) .

19-14

DISK DATA CACHING ON RSX-IIM-PLUS AND MICRO/RSX SYSTEMS
The Requests Being Cached field shows the types of cache I/O
operations enabled for the device. The types can be VIRTUAL
(VIR), READAHEAD (RDH) , DIRECTORY (DIR), LOGICAL (LOG), and
OVERLAY (OVR).
The Reads section shows the number of read requests issued
for each of the I/O types listed in the display, as well as
the total of all read requests.
These four lines show the Read Hit Rate, the Read Load Rate,
the Read Overlap Rate, and the Extent Too Big rate for each
type of request. Each of these rates is computed as a
percentage of the total number of read operations for the
particular type of request.

o
8

The Maximum Extent Size for each of the I/O types.
The Writes
for each
requests.
not exist,

section shows the number of write requests issued
of the I/O types and the total of all write
Note that READAHEAD and OVERLAY write requests do
so these fields are blank.

The Write Hit Rate and Write Overlap Rate for each type of
I/O request. Each of these rates is computed as a percentage
of the total number of write operations of a particular type.
The total amount of each type of I/O, as well
amount of all I/O.

the

total

The last four lines show rates that are not accumulated by
I/O type. All cache I/O requests require that an I/O packet
be allocated from primary pool.
The Primary Pool Allocation Failure Rate line shows how often
the allocation cannot be done as a percentage of the total
number of I/Os issued for that device.
The Cache Pool Allocation Failure Rate is similar to the
failure
rate for primary pool allocation, except that
allocation from the cache pool is only required on read
operations.
The rate is therefore computed as a percentage
of the total number of read operations.
The Read Load Failure Rate is the percentage of all
load attempts that failed because of an I/O error.

cache

The Deferred Write Rate is the rate that write operations
were able to be deferred. This is computed as a percentage
of the total number of write operations.

19.5.4

DEV Command

The DEV command displays system information about various devices. If
no device is specified, then all the devices known to a system are
listed. If a device but no unit is specified, then all the units of
that device are listed with some minimum amount of status.
If both a
device and unit are specified, then the maximum amount of information,
including the current cache attributes for that particular device, are
displayed.
Format
DEV [dd[nnJ:J

19-15

DISK DATA CACHING ON RSX-IIM-PLUS AND MICROjRSX SYSTEMS
Parameters
dd:
Specifies the devices about which information will be displayed.
nn
Specifies the unit of a particular
information will be displayed.

19.5.5

device,

about

which

SET Command

The MCR command SET allows you to display and modify various system
values and behaviors; it also allows you to associate caching with a
device. If no device is specified, then all the devices with a
corresponding cache status are listed.
If a device is specified, then
the current cache behavior for that device is modified appropriately.
The region size can only be specified when you create a cache region
(see the CREATE option). The region name can only be modified while
all types of caching are disabled for that device (see the REGION
option) .
Format
SET /[NO]CACHE[:ddnn:[(option, ... )]]
Oualifiers
/CACHE
If no device is specified, lists devices with disk data caching
enabled.
If a device is specified, enables caching or modifies
the caching behavior.
/NOCACHE
Lists devices with disk data caching disabled. You can specify a
device but no options with the /NOCACHE qualifier.
Argument
ddnn:
Specifies the device to be modified.
Options
The following options are available with disk data caching:
CREATE[:[region][:[main partition][:[size]]]]
REGION: name
[NO]DIRECTORY[:extent size]
[NO]LOGICAL[:extent sIze]
[NO]OVERLAY[:extent-size]
[NO]READ AHEAD[:extent size]
[NO]VIRTUAL[:extent_size]
These options are described in section 19.5.1.

19-16

APPENDIX A
SERIAL DES POOLER TASK

The Serial Despooler Task (PRT ... ) provides a means of eliminating
content.ion for the system line printer. Rather than waiting for the
line printer to become available, a task directs the output intended
for th.e line printer to a disk file. The task issues a Send Data
directive to the serial despooler, placing a data block
that
identifies the file to be spooled in the serial despooler queue. A
Request. directive is then issued by the task to activate the serial
despooler,
in case it is not already active. PRT handles FCS-created
files, but RMS files can be read only if they are sequential.
All
files identified in the serial despooler queue are printed in
first-in/first-out (FIFO) order.
You may wish to compare the capability of this task with the RSX-IIM
Queue Manager and its associated despooler. See Chapter 7 for more
information about the Queue Manager.

A.l

RECEIVE QUEUE OPERATION

The standard method of placing a user file in the serial despooler
receive! queue (and requesting its execution) is through the PRINT$
macro call, which is described in the RSX-IIM/M-PLUS and Micro/RSX I/O
Operations Reference Manual. Files are spooled in this same manner by
the RSX-ll utilities that support the spool (/SP) option. Each entry
in the serial despooler receive queue consists of a 13-word data block
containing the file-related information illustrated in Figure A-I.

A.2

TEXT REQUIREMENTS

The serial despooler task prints ASCII text with a maximum line length
of 132 bytes.
It will properly handle files with all modes of FCS
carriag'e control (that is, standard, embedded, and FORTRAN).

A.3

TASK-BUILD INFORMATION

The serial despooler task must be built during an RSX-IIM system
generat.ion because the task image file (PRT.TSK) is not distributed on
the sta.ndard release kits. Normally, the serial despooler is built to
retain all files that have been spooled, but the serial despooler
build file can be edited during system generation to enable the
automat,ic delete feature.
(Note also, that a nondeleting despooler
can be made to delete, if the data block mentioned in Section B.l and
shown in Figure A-I has a negative value in word 7.) When the serial
despooler is built without automatic delete, spooled files are
retained after printing.
If the system has a deleting serial
despooler, all spooled files are deleted after printing.
A-I

SERIAL DES POOLER TASK
See the RSX-llM System Generation and Management
system generation information.

Guide

for

detailed

WORD
1

File name

RADIX-50

File type in RADIX-50

File version (binary)

Device name in ASCII

Unit number (binary)

8
9

File ID

10
11

Directory ID

13
Figure A-I

PRT Send Data Buffer Format

'I'he serial despooler is set to spool files to LPO:.
It uses LUN3 as
the spool device. The system manager can redirect print files to any
record-oriented device (that is, a device similar to the printer) by
reassigning LUN3.
See the RSX-llM/M-PLUS MCR Operations Manual for
information on the REASSIGN command.

1.... 4

PRT ERROR MESSAGES

error messages issued by PRT are sent to the console terminal
t:hrough pseudo-device CO:.
The error messages have the following
format:

1~11

PRT -- text
]~ll

messages (except for the receive failure error) supply information
identifies the sender task and the file in question. All PRT
E~rrors are fatal; once an error is detected, PRT
terminates printing
of the input file, and a cleanup/restart procedure is entered.
t:hat

In the case of the receive failure error, the sender and file
information are unavailable.
Furthermore,
PRT does not attempt to
dequeue additional spool requests because of the nature of this error
condition.
Instead, PRT exits causing its receive queue to be purged
by the system.
RECEIVE FAILURE, d. -- TASK EXITING
Explanation: The Receive Data or Exit directive failed while
attempting to obtain the next file specifier from the queue. The
system error code (d.) is printed to identify the error.
A-2

SERIAL DES POOLER TASK
NO DEVICE NAME - SENDER: task FILE: filename.typ;ver
Explanation:
name.

The dequeued print request did not contain a device

NO FILE 10 - SENDER: task FILE: filename.typ;ver
Explanation:
ID.

The dequeued print request did not contain

file

OPEN FAILURE INPUT FILE - SENDER: task FILE: filename.typ;ver, d.
Explanation: The specified file could not be opened.
following six conditions may exist:

One of the

The file is protected against access for read privileges.

A problem exists on the physical device (for example,
cycled down).

The volume is not mounted.

The specified file directory does not exist.

The named file does not exist in the specified directory.

The file is already deleted.

device

The system error code (d.) is printed to identify the failure.
ATTACH FAILURE - SENDER: task FILE: filename.typ;ver, d.
or
DETACH FAILURE - SENDER: task FILE: filename.typ;ver, d.
Explanation: The line printer could not be attached/detached
(that is,
the system does not contain a line printer). The
system error code (d.) is printed to identify the error.
PRINT ERROR - SENDER: task FILE: filename.typ;ver, d.
Explanation: A Queue I/O request to the line printer has failed.
The system error code (d.) is printed to identify the error.
I/O ERROR INPUT FILE - SENDER: task FILE: filename.typ;ver, d.
Explanation: An error was detected while reading the input file.
One of the following three conditions may exist:
1.

A problem exists on the physical device (for example,
cycled down).

device

The length of the text line is greater than 132 bytes.

The file is corrupted or the format is incorrect.

The system error code (d.) is printed to identify the error.
d. LINES WERE TRUNCATED
Explanation:

While printing the file, PRT truncated d.

A-3

lines.

APPENDIX B
RSX-IIM/M-PLUS UFD CONVENTIONS

The RSX-IIM and RSX-IIM-PLUS operating systems observe a set of User
File Directory (UFD) conventions for files on disk.
These conventions
provide a consistent method of locating, allocating, and maintaining a
file on disk.
A UFD is itself a file, named in the format gggmmm.DIR where g and m
are octal numbers in the range 1 through 377 (0 is reserved).
The
numbers represent the file owner's
group
and
member
number
respectively.
For more information on file ownership and directories,
see the RSX-IIM/M-PLUS MCR Operations Manual,
the RSX-IIM Command
Language Manual, and the RSX-IIM-PLUS Command Language Manual.
The usa.ge of certain UFDs is common to both operating systems; other
UFDs are specific to the RSX-IIM or RSX-IIM-PLUS operating systems.
The following sections describe group and member numbers and their use
in identifying the contents of system UFDs. A section on file naming
conventions is also included.

B.l

GROUP NUMBER

The group number identifies groups of directories.
By convention,
group numbers 1 through 200 are reserved by DIGITAL for system files,
and group numbers 201 through 377 are reserved for user files.
The
group numbers may vary between RSX-IIM and RSX-IIM-PLUS.
Table B-1
lists t.he group numbers and their usage.
Table B-1
Group Number Identification
Group Number

Usage

Executive files

MCR files

FCP files (RSX-IIM-PLUS)

RMD files

Privileged utility tasks

DCL files
(continued on next page)

B-1

RSX-IIM/M-PLUS UFD CONVENTIONS

Table B-1 {Cont.}
Group Number Identification
Group Number

B.2

Usage

Queue Manager files

On-line configuration {RSX-llM-PLUS}

K-Series files

FCS files

121

Line printer despooler (RSX-llM-PLUS)

125

Shadow Recording {RSX-llM-PLUS}

126

Accounting tasks (RSX-llM-PLUS)

200

SYSGEN Indirect command files

MEMBER NUMBER

The second number (member number) identifies the different file
within each group. Table B-2 lists the member numbers.

types

Table B-2
Member Number Identification
Member Number

File Types

Source modules

Object modules, assembly and task-build
command files, and object module libraries
for
RSX-llM
nonprivileged
tasks
and
RSX-llM/M-PLUS build files

Object modules, assembly and task-build
command files, and object module libraries
for the RSX-llM/M-PLUS Executive and for
privileged
and
nonprivileged tasks on
RSX-llM-PLUS

RSX-llM unmapped system listing and map
files
for privileged and nonprivileged
tasks

RSX-llM-PLUS and RSX-llM mapped
system
listings and map files for privileged and
nonprivileged tasks

SLP correction files
under member number 10

RSX-llM unmapped
image files

for

system

files
image

located
and

task

(continued on next page)
B-2

RSX-IIM/M-PLUS UFD CONVENTIONS

Table B-2 (Cont.)
Member Number Identification
Member Number

B.3

File Types

RSX-IIM-PLUS and RSX-IIM
image and task image files

mapped

RSX-llS· unmapped system
SLP
and
PAT
correction files applied by Update, and
system image and task image files

RSX-llS mapped system image and task
files

200

SYSGEN Indirect command files

system

image

EXAMPLE SYSTEM USER FILE DIRECTORIES

The system UFDs consist of a group number and a member number.
These
numbers identify the specific contents of each directory.
For
example:, if you wanted to locate all the MCR listing and map files,
you could find the group number for MCR files (12) and the member
number for listing and map files (34) and combine them to specify the
UFD [12:,34]; this UFD contains the MCR listing and map files.
Table B-3 lists the MCR UFDs and the files contained in each UFD.
Table B-4 lists the UFDs used by the RSX-IIM/M-PLUS operating system.
Table B-3
MCR User File Directories (UFDs)
[12,10]

MCR source files

[12,20]

Unmapped MCR object
modules,
assembly
command files, and library build command
file

[12,24]

Mapped MCR object modules, assembly command
files, and library build command file

[12,30]

Unmapped MCR listing and map files

[12,34]

Unmapped MCR listing and map files

[12,40]

SLP correction
[12,10]

files

for

files

under

Table B-4
System UFDS
[1,1]

System and macro object module libraries

[1,2]

System message and help files

[1,3]

Lost files found by VFY
(continued on next page)

B-3

RSX-IIM/M-PLVS UFD CONVENTIONS

Table B-4 (Cont.)
System UFDS

B.4

[1,4J

Postmortem and snapshot dumps

[1,6J

Error logging files and,
Accounting

[1,7J

Spooling queue file and transparent listing
file

[l,llJ

RSX-IIM-PLUS
maintenance

[1,20J

module
libraries
RSX-IIM
object
task-build overlay descriptor files
nonprivileged tasks

[1,24J

Object module libraries, task-build command
files
for
mapped
tasks, and overlay
descriptor files for privileged tasks

[1,34J

Executive and task maps

[1,54J

Executive and system tasks

[2,300J

UETP files

[200,lJ

Sample files for system introduction

[200,2J

Field service files

work

space

RSX-IIM-PLUS,

for

system
and
for

SYSTEM FILE-NAMING CONVENTIONS

System file names have the following general format:
nnnsss.typ
where:
nnn

The system identification for the task. For example, DMP
is the identification for the File Dump Utility Program.

sss

A suffix for noting the relationship of the file to the
task specified in the nnn identification. For example,
PIPBLD.CMD is the command file for building PIP.
Suffixes:
ASM - Assembly command file
BLD - Task Builder command or overlay descriptor
file
RES - FCSRES version of the task
FSL - FCSFSL version of the task (RSX-IIM-PLUS)

typ

The standard mnemonic for file type. RSX-IIM/M-PLUS has
a set of conventional and default file types that are
used to reflect the contents of a file. See Table B-5.

B-4

RSX-IIM/M-PLUS UFD CONVENTIONS

Table B-5
System File Types
Type

File Contents

. BAS

BASIC-II language source file

. BAT

Batch file

.BLD

Indirect command file used as input to SYSGEN

.B2S

BASIC-PLUS-2 language source file

.CBL

COBOL language source file

.CDA

Crash dump binary file

.CFS

Error logging control file string

.CLB

Indirect Command Processor command file library

.CMD

Indirect command file

.COR

SLP correction file

.CRF

Cross-Reference Processor symbol table file

.DAT

File containing data (as opposed to a program)

.DIR

Directory file

.DMP

File Dump Utility output file

.gRR

Error Logger output file

.F'TN

FORTRAN IV, FORTRAN IV-PLUS or FORTRAN 77 language
source file

.HLP

Help file

. LOG

Batch or console log file

.LST

Listing file

. MAC

MACRO-II source file

. MAP

Task Builder memory allocation map

.~1LB

Macro library file

.OBJ

Object module (output from either
Assembler or a compiler) file

.ODL

Task Builder overlay descriptor file

.OLB

Object module library file

. PAT

PAT Utility Correction file

.POB

Patched object module used by the PAT Utility

the

MACRO-II

(continued on next page)

B-5

RSX-IIM/M-PLUS UFD CONVENTIONS
Table B-5 (Cont.)
System File Types
Type

File Contents

.SML

System macro library file

.STB

Task symbol table file

.SYS

Bootable system image or other system file

.TMP

Temporary file

.TSK

Task image file

.TXT

Text file

.ULB

Universal library file

B-6

INDEX

/ABAUD keyword (VMR), 10-53
ABORT command
lOX, 4-24
Shadow Recording, 18-7
Account File Maintenance Program
See A.cNT
Accounting Startup Transaction
Block, 17-25
ACNT, 1-1, 2-1
Account entry
contents, 2-1
deleting, 2-9
examining, 2-5
listing, 2-8
modifying, 2-7
Account file
maximum number of entries,
2-3
sorting, 2-10
account file
copying, 2-3
ext.ending, 2-3
changing password, 2-1
copying account file, 2-3
error messages, 2-11
ESCAPE key, 2-3
invoking, 2-2
options, 2-2
Add, 2-3
Cre!a te, 2- 3
Delete, 2-9
Exa.mine, 2-5
Exit, 2-11
List, 2-8
Modify, 2-7
Sort, 2-10
password encryption, 2-1
prote!ction
restoring, 2-3
ACSUB, 17-17
Activity report
lOX, 4-20, 4-42
Add option
ACNT, 2-3
/AFF keyword (VMR), 10-22, 10-54
Allocate Device Transaction Block,
17-·27
ALT
See ALTER command (VMR)
ALTER command (VMR), 10-8
definition, 10-8
example, 10-8
forma.t, 10-8
keyword
/PFtI, 10-8
parameters, 10-8
/ANSI keyword (VMR), 10-54
ASN
See ASSIGN command (VMR)

ASSIGN command (VMR), 10-9
definition, 10-9
examples, 10-10
formats, 10-9
keywords
/GBL, 10-10
/SYSTEM, 10-10
parameters, 10-9
ASSIGN/QUEUE command
DCL, 7-9
MCR, 7-9
/AVO keyword (VMR), 10-54
Backus-Naur Form metalanguage,
12-6
Bad block
bad block replacement functions,
5-1
detection, 5-1, 5-3
handling
MSCP disks, 5-3
listing
lOX, 4-26
notification, 5-1, 5-3
recovery techniques, 5-1
removing from testing
lOX, 4-25
replacement, 5-1, 5-3 to 5-4
partial, 5-4
revectoring, 5-1, 5-4
specifying
lOX, 4-25
Bad Block Replacement Control
Task, 1-2
See also RCT, 5-1
BADBLOCKS
display command, 4-26
lOX command, 4-25
parameter command, 4-25
Base priority for nonprivileged
tasks, 13-13
Batch processing, 7-1
Batch processor
initialization, 7-11
DCL command, 7-11
MCR command, 7-11
installation, 7-9 to 7-10
Batch processor prototype task
See BPR
Batch queue, 7-12
assignment
DCL command, 7-13
MCR command, 7-13
BC, 12-27
BCT, 12-28
Bit Clear
See BC
Bit Clear Test
See BCT

Index-1

Bit Set
See B
Bit Set Test
See BST
/BLKMOD keyword (VMR), 10-55
/BOOT keyword (VMR) , 10-47
/BOT keyword (VMR), 10-55 to
10-56
BPR, 7-2
BPR.TSK, 7-10
/BRO keyword (VMR) , 10-56
£IS, 12-27
BST, 12-28
/BUF keyword (VMR) , 10-57
Buffer space
statistics
with PARAMETERLIST, 4-44
BUFFERSIZE command
lOX, 4-27
BUILD command, 15-7
CAN
See CANCEL command (VMR)
CANCEL command (VMR), 10-11
definition, 10-11
example, 10-11
format, 10-11
parameter, 10-11
Card Reader Spooling Transaction
Block, 17-31
CBM, 12-29
Checkpoint
dynamic common regions, 14-1
static common regions, 14-1
tasks, 14-1
Checkpointab1e task
fixing, 10-18
Checkpointing, 10-22, 10-28
common, 10-28
/CKP keyword (VMR) , 10-22
CLEAR command, 15-8
CLI, 1-3, 11-1, 11-3
adding to account entry, 2-3
changing, 2-7
continuation lines, 11-8
displaying, 2-5, 2-8
examples, 11-11, 11-16
FORTRAN, 11-16, 11-20
MACRO-II, 11-11, 11-15
Executive directives, 11-3
in account entry, 2-1
interaction with system, 11-3
MCR, 2-3, 11-2
mu1ti-CLI support, 2-1, 2-3,
2-7
prompting, 11-7 to 11-8
prompts
CTRL/C, 11-7
task-exit, 11-8
See Command Line Interpreter,
10-23
serial command processing, 11-8
system messages to, 11-5
task names, 11-4

CLI (Cont.)
writing, 11-2 to 11-3
CLI dispatcher task, 12-5
/CLI keyword (VMR) , 10-23
CO:, 3-1
as pseudo device, 3-1
attaching, 3-3
detaching, 3-3
monitoring status, 3-6
reading from, 3-3
redirecting, 3-7
CODRV, 3-1
Command (VMR)
See also VMR commands
comments in, 10-5
components of, 10-4
file specifications, 10-5
keyword, 10-4
keyword value, 10-5
name, 10-4
parameter, 10-4
Command format (VMR) , 10-4
Command Language Interpreters,
1-3
Command line
comments, 10-5
file specifications, 10-5
format, 10-4
rejected, 10-94
Command Line Interpreter
See CLI
task, 10-23
Command syntax (VMR), 10-4
abbreviating commands, 10-4
command keywords, 10-4
command line format, 10-4
command names, 10-4
command parameters, 10-4
entering comments, 10-5
keyword values, 10-5
Common
checkpointing, 10-28
directive
fixing, 10-19
partition, 14-1
protecting, 10-25
synchronizing task use, 10-27
task sharing, 10-27
unfixing, 10-92
COMPAREDATA YES/NO command
lOX, 4-28
Compatibility mode
See VAX-II RSX
CON
see CONFIGURATION command (VMR)
command descriptions, 15-7,
15-30
error messages, 15-39, 15-41
format, 15-39
invoking, 15-4
indirect command files, 15-4
CON command summary, 15-5
CON commands
BUILD, 15-5, 15-7

Index-2

CON commands (Cont.)
CLEAR, 15-5
DISPLAY, 15-5, 15-9
ESTATUS, 15-5, 15-12
HELP, 15-5, 15-14
IDENT, 15-5, 15-15
LINK, 15-5, 15-16
LIST, 15-5, 15-17
OFFLINE, 15-5, 15-19
OFFLINE MEMORY, 15-22
ONLINE, 15-6, 15-23
ONLINE MEMORY, 15-26
SET, 15-6, 15-27
SWITCH, 15-6, 15-29
UNLINK, 15-6, 15-30
Configuration
of devices in lOX, 4-29
CONFIGURATION command (VMR),
10--12
definition, 10-12
examples, 10-13, 10-16
formats, 10-12
keywords
CONTROLLERS, 10-13
CPU, 10-13
FULL, 10-13
UNITS, 10-13
parameters, 10-12
CONFIGURE command
lOX, 4-29
Console Logger, 1-1, 3-1
communication with, 3-2
task communication, 3-2
user communication, 3-2
ConsolE~ Loggi ng
CO:
writing to, 3-2
commands, 3-3
error messages, 3-11
installing COT ••• , 3-2
loading CODRV, 3-2
log file
disabling, 3-5
reassigning, 3-5
multiple commands, 3-6
reading log file, 3-8
sample session, 3-8
starting, 3-4
stopping, 3-4
Console Output Device
See CO:, 3-1
Console terminal
disabling, 3-5
display, 3-4
reassigning, 3-5
Continuation line
CLI, 11-8
CONTINUE command
Shadow Recording, 18-8
Contradictory Bit Mask
See CBM, 12-29
Control
lOX command
category, 4-3

CONTROL C command
CONTROL C YES/NO command
lOX, 4-32
lOX
effect on CTRL/C, 4-32
. CONTROL P
See CTRL/P
Controller failures, 15-34
COP, 12-30
COpy command, 9-7
COT ••• , 3-1
Crash Recovery Transaction Block,
17-25
Create option
ACNT, 2-3
/CRT keyword (VMR), 10-57
/CTB keyword (VMR), 10-33
CTRL/C command
See CONTROL C command, 4-32
CTRL/P, 9-3, 9-7
Data terminal emulation
See DTE, 9-1
Data Terminal Emulator
See DTE
see DTE
Date
displaying, 10-90
setting, 10-90
DCL, 11-2, 11-5, 11-8
building, 12-1
conventional installation, 12-2
deleting files, 9-7
IFORM, 12-24
installation, 12-1
alternatives, 12-2
catchall task, 12-3
MCR task, 12-3
intermediate form
See IFORM
MCR fallthrough, 12-4
parser process, 12-5
parser table example, 12-21
SET commands, 12-3
task, 12-3
task building, 12-4
task-building
first task build, 12-4
second task build, 12-5
telephone number
specifying, 9-4
terminal emulation
specifying, 9-3, 9-5
transferring files, 9-7
translator process, 12-5
DCL command table, 12-7
constructing, 12-6
example, 12-46, 12-48
interpreting, 12-18
modifying, 12-8
DCL commands
interpretation, 12-5
mapping to MCR, 12-21

Index-3

DCL Master Command Table
See DCL MCT
DCL MCT, 12-9
DCL QMG commands
DCL task, 1-4, 12-5
adding commands, 12-8
definition, 12-1
deleting commands, 12-13
modifying commands, 12-13
overlay, 12-10
PT/TT, 12-12
file, 12-9
Deallocate Device Transaction
Block, 17-28
/DEC keyword (VMR), 10-57
DECnet Remote Terminal Facility
See RMT
DECtape
exercising
lOX, 4-2
Default (VMR)
device, 10-5
directory, 10-6
file name, 10-6
file types, 10-6
version number, 10-6
DELETE command, 9-7
Delete option
ACNT, 2-9
DELETE/REMOTE command, 9-7
/DENS keyword (VMR), 10-48
Density
tape
in lOX, 4-33
DENSITY command
lOX, 4-33
DESELECT command
lOX, 4-35
Despool prototype task
See LPP
DEV
See DEVICES command (VMR)
DEV command
disk data caching, 19-15
Device
exercising
examples
RL02, 4-10
lOX
adding, 4-29
displaying, 4-29
exercising
steps, 4-2
status during exercise, 4-60
testing
removing, 4-35
time of, 4-57
null, 10-39
offline, 10-17
placing off line, 15-3
placing on line, 15-3
pseudo, 10-3
redirecting, 10-39
redirecting restrictions, 10-39

Device (Cont.)
removing, 10-93
removing attached device, 10-93
system default
adding to account entry, 2-3
changing, 2-7
displaying, 2-5, 2-8
in account entry, 2-1
Device context, 15-3
Device Statistics Block, 17-31
Device statistics example
Resource Accounting, 17-7
Device unit failures, 15-34
DEVICES command (VMR), 10-16
definition, 10-16
example, 10-16
format, 10-16
notes, 10-17
parameter, 10-16
Diagnostic error message, 10-94
Diagnostics Loader task
See OLD
Digital Command Language
See DCL
task, 12-1
DIR attribute, 12-31
/DIR keyword (VMR), 10-19
Disk
block
random or sequential
lOX, 4-51
testing range display
lOX, 4-52
testing range for NFS volumes
lOX, 4-52
exercising
examples
RL02
lOX, 4-10
lOX, 4-2
exercising (lOX)
examples
NFS volume, 4-15
Files-11
parameter commands
lOX, 4-8
testing
lOX, 4-63
testing
selecting random testing
lOX, 4-51
skipping blocks
lOX, 4-41
Disk Data Caching, 1-5, 19-1
Data Cache Manager, 19-3
DCL commands, 19-6, 19-10
features, 19-1
I/O operations, 19-1
including in system, 19-1, 19-3
MCR commands, 19-10, 19-16
options, 19-7, 19-10
region, 19-3
Dismount Device Transaction Block,
17-29

Index-4

Display
lOX
bad blocks list, 4-26
commands as a category, 4-3
continuing
with PROCEED, 4-S0
status during exercise, 4-60
DISPLAY command, lS-9
Shadow Recording, 18-9
OLD, lS-36
how to use, lS-36, lS-39
DMAP attribute, 12-32
DTE, 1-3, 9-1
Dynamic common region
checkpointing, 14-3
shuffling, 14-6
/EBC keyword (VMR) , 10-S7
/ECHO keyword (VMR) , 10-S8
Echo loops, 9-4
/EDIT keyword (VMR) , 10-S8
ERR attribute, 12-31
Error limit
altering
lOX, 4-36
Error Logger, lS-32
Error message format, 10-94
Error messages
lOX, 4-68
Error messages (VMR) , 10-94,
10-112
diagnostic, 10-94
fatal, 10-94
format, 10-94
unmarked, 10-94
Error report
data compare
lOX, 4-21
directing to device
lOX, 4-42
disabling
lOX, 4-S4
enabling
lOX, 4-S4
I/O error
lOX, 4-22
types
lOX, 4-S4
ERRORLI.MIT command
lOX, 4-36
ESCAPE key
requesting list of options
ACN'T, 2-3
/ESCSEQ keyword (VMR) , 10-S8
ESTATUS command, lS-12
Event flag
lOX, 4-66
Examine option
ACNT, 2-S
EXECUTE command
lOX, 4-37
Execution
termination of task
lOX, 4-24

Execution mode
entering
lOX, 4-61
lOX, 4-18
Executive data space support,
10-3
Executive pool monitor code, 13-1
EXIT command
lOX, 4-38
Exit option
ACNT, 2-11
Fast-mapping, 10-23
Fatal error message, 10-94
Fault isolation, lS-33
/FDX keyword (VMR) , 10-S9
File
See also Account file
copying
See also File transferring
transferring, 9-1, 9-3, 9-S,
9-8
Professional Personal
Computer systems, 9-1
VAX-II RSX systems, 9-1, 9-S
File size
specifying in blocks, 4-63
File specification (VMR)
components, 10-S
defaults, 10-S
device name, 10-S
directory, 10-6
file name, 10-6
file type, 10-6
format, 10-S
/IM switch, 10-7
named directory, 10-6
specifying, 10-S
version number, 10-6
File-structured device
exercising
lOX, 4-3
Files-II
disk
selecting for testing
lOX, 4-39, 4-6S
volume
protecting with TEMPORARYFILE
lOX, 4-63
volume exercise
example
lOX, 4-10
Files-II volume
selecting, 4-7
FILESll command
lOX
default parameters, 4-39
FIX command (VMR) , 10-18
definition, 10-18
examples, 10-19
format, 10-18
keywords
/DIR, 10-19
/NSF, 10-19

Index-S

FIX command (VMR)
keywords (Cont.)
/REG, 10-19
/RON, 10-19
parameter, 10-18
/FIX keyword (VMR), 10-23
FIX-IN-MEMORY command
See FIX command (VMR)
Fixing
directive common, 10-19
Flying installs, 12-4
/FMAP keyword (VMR) , 10-23
/FORMFEED keyword (VMR) , 10-59
Full-duplex terminal driver,
10-50
GET/SET option, 10-50
Function commands
lOX category, 4-3
/GBL keyword

(VMR) , 10-10

Hard errors, 15-32
Hardware faults, 15-31
intermittent failures, 15-32
media failures, 15-31
transient faiLures, 15-31
HELP command, 15-14
lOX, 4-40
/HFILL keyword (VMR) , 10-59
/HHT keyword (VMR) , 10-59
High pool, 13-3 to 13-4
High pool event, 13-2
HLP attribute, 12-32
HRC, 15-2
error messages
format, 15-39
HRC error messages, 15-41, 15-44
/HSYNC keyword (VMR) , 10-60
I/O error report
lOX, 4-22
I/O exercise
steps, 4-2
termination, 4-24
I/O Exerciser
See lOX
I/O Queue Optimization, 1-5, 16-1
Cylinder Scan, 16-1, 16-4
default, 16-3
Elevator, 16-1
Elevator Method, 16-4
error messages, 16-4
fairness count
adjustment, 16-3
Fairnesscount, 16-1
initiating, 16-1
Nearest Cylinder, 16-1, 16-4
optimization status, 16-2
optimization types, 16-1
selecting method, 16-3
IDENT command, 15-15
IFORM, 12-24
/IM switch (VMR)
definition, 10-7, 10-47

/IM switch (VMR) (Cont.)
relationship to symbol
definition file, 10-7
uses, 10-7
/INC keyword (VMR) , 10-24
Indirect command file
lOX, 4-6
Indirect Command File (VMR) , 10-3
levels allowed, 10-4
specifying, 10-4
VMR requirements, 10-3
INS
See INSTALL command (VMR)
INSTALL command (VMR) , 10-21
definition, 10-21
examples, 10-30 to 10-31
format, 10-21
keywords
/AFF, 10-22, 10-25
/CKP, 10-22
/CLI, 10-23
/FIX, 10-23
/FMAP, 10-23
/INC, 10-24
/IOP, 10-24
/PMD, 10-25
/PRI, 10-25
/PRO, 10-25
/RON, 10-26
/ROPAR, 10-26
/SEC, 10-27
/SLV, 10-27
/SYNC, 10-27
/TASK, 10-27
/UIC, 10-28
/WB, 10-28
/XHR, 10-28
notes, 10-31 to 10-32
parameters, 10-21
Interactive mode
lOX, 4-19
INTERLEAVE command
lOX, 4-41
Intermittent failures, 15-32
Interval report
lOX, 4-20
Invalid Login Transaction Block,
17-27
/IOP keyword (VMR) , 10-24
lOX, 1-1
command
LOOPBAC K, 4 -4 3
parameter list
for Files-II, 4-8
command mode, 4-18
commands
ABORT, 4-24
BADBLOCKS, 4-25
BUFFERSIZE, 4-27
categories, 4-3
COMPAREDATA YES/NO, 4-28
CONFIGURE, 4-29
CONTROL C YES/NO, 4-32
CTRL/C,-4-31

Index-6

lOX
commands (Cont.)
DENSITY, 4-33
descriptions, 4-22
DESELECT, 4-35
ERRORLIMIT, 4-36
EXECUTE, 4-37
EXIT, 4-38
files, 4-6
FILESll, 4-39
HELP, 4-40
in interactive mode, 4-19
INTERLEAVE, 4-41
LOGFILE, 4-42
parameter
by device type, 4-9
with FILESll, 4-8
with SELECT, 4-9
wi th VERIFY, 4-9
parameter list
for NFS volumes, 4-9
PARAMETERLIST, 4-44
PATTERN, 4-48
PRINTSUMMARY, 4-49
PROCEED, 4-50
RANDOM, 4-51
RANGE, 4-52
RECORDS, 4-53
REPORT ERRORS YES/NO, 4-54
RESTART, 4-55
RETRIES, 4-56
RUNTIME, 4-57
SELECT, 4-58
SPY, 4-60
START, 4-61
SUMMARYTIME, 4-62
syntax, 4-22
TEMPORARYFILE, 4-63
VERIFY, 4-64
VOLUMECHECK, 4-65
WAIT, 4-66
WRITECHECK, 4-67
considerations for, 4-1
controlling with CTRL/C, 4-32
data
compare error report, 4-21
pattern checking, 4-28
transfer size of, 4-27
DEC tape exercising, 4-2
defaults
changing during task build,
4-22
device
exercising steps, 4-2
status display, 4-60
testing
time of, 4-57
disk exercising, 4-2
error messages, 4-68
execution mode, 4-18
entering, 4-18
exercise parameters
general list, 4-8
exiting, 4-38

lOX (Cont.)
file-structured exercising, 4-3
increment, 4-5
indirect command files, 4-6
installation
on RSX-l1M, 4-4
on RSX-IIM-PLUS, 4-4
interleaving with Executive,
4-66
interval report output
frequency, 4-62
invoking
on RSX-IIM, 4-5
on RSX-IIM-PLUS, 4-5
when installed, 4-5
when not installed, 4-5
with an increment, 4-5
without an increment, 4-5
nonfile-structured exercising,
4-3
output type
activity report, 4-20
interval report, 4-20
summary report, 4-20
parameter
command exercIsIng magnetic
tape, 4-12
exercising
device-dependent exercise,
4-8
Files-II volumes, 4-10
NFS volume, 4-15
general list of exercise
parameters, 4-8
overriding default
FILESll, 4-39
SELECT, 4-58
showing default with
PARAMETERLIST, 4-44
parameter command category, 4-3
pattern
altering test, 4-48
displaying test, 4-48
restarting, 4-55
running steps, 4-1
selecting
NFS volume, 4-8
starting, 4-61
task termination, 4-18
task-build file
location of, 4-22
termination, 4-38
using PROCEED, 4-50
test configuration, 4-29
adding units, 4-6
displaying, 4-6
setting up, 4-6
testing
removing devices from, 4-35
wait-for-event flag, 4-66
write-check, 4-67
LBN, 5-2
/LIBUIC keyword

Index-7

(VMR) , 10-60

/LINES keyword (VMR), 10-61
LINK command, 15-16
LIST command, 15-17
List option
ACNT, 2-8
LOA
See LOAD command (VMR)
LOAD command (VMR), 10-33
definition, 10-33
examples, 10-34
format, 10-33
keywords
/CTB, 10-33
/PAR, 10-33
/SIZE, 10-34
/VEC, 10-34
notes, 10-34
parameters, 10-33
LOGFILE YES/NO command
lOX, 4-42
Logical AND, 12-27
Logical Block Number, 10-31
Logical blocks
See LBN
LOGICAL UNIT NUMBERS command
See LUNS command (VMR)
LOGIN command, 9-6
Login Transaction Block, 17-30
/LOGON keyword (VMR), 10-61
LOGOUT command, 9-3, 9-7
LOOPBACK
parameter command, 4-43
Low pool, 13-3 to 13-4
Low pool event, 13-2
/LOWER keyword (VMR), 10-61
LPP, 7-2
LUN
See LUNS command (VMR)
LUNS command (VMR), 10-35
definition, 10-35
example, 10-35
format, 10-35
parameter, 10-35
Macro Metalanguage
See MML
Magnetic tape
density
displaying in lOX, 4-33
specifying in lOX, 4-33
error retries, 4-56
exercise
example, 4-12
using SELECT, 4-12
records tested, 4-53
testing
altering record count, 4-53
/MAIN keyword (VMR), 10-61, 10-63
MAP attribute
secondary mappings, 12-35
MAP attributes, 12-33 to 12-34
Master Command Table
See MCT
/MAXEXT keyword (VMR), 10-63

MCR, 11-1 to 11-2
CLI default, 2-3
transferring files, 9-5, 9-7
translator table example, 12-21
MCR CLI command, 11-5
MCR command, 12-3
MCR QMG commands
MCR UFDs, B-3T
MCT
contents, 12-7
Media failures, 15-31
Memory, 14-1
compacting space
See SHF
Memory management
fi~ing tasks, 10-18, 10-23
Metalanguage, 12-13
category references, 12-14
exclusive-OR, 12-15
optional syntax indicators,
12-15
production rule, 12-14
adjective, 12-14
subject, 12-14
syntax tree, 12-14
MFT, 9-1
MFT command, 9-5, 9-7
Micro/RSX File Transfer Utility
See MFT
MKll memory box failures, 15-35
MML, 12-16
features, 12-6 to 12-7
literals, 12-20
nonliterals, 12-19
parser functions, 12-20
handling of literals, 12-20
handling of nonliterals,
12-19
translator functions, 12-20
handling of literals, 12-20
handling of nonliterals,
12-19
Modify option
ACNT, 2-7
Monitor Console Routine
See MCR
Mount Device Transaction Block,
17-28
MOUNT/CACHE command
disk data caching, 19-6, 19-10
MSCP disks
configuration, 5-2
Multistream line printer spooling,
7-1
Mutiprocessor systems
stand-alone maintenance, 15-36
/NETUIC keyword (VMR), 10-63
NFS
exercise example, 4-15
testing range of blocks, 4-52
volume
altering range of test blocks,
4-52

Index-8

NFS
volume (Cont.)
displaying range of test
blocks, 4-52
error retries, 4-56
selecting with SELECT, 4-58
selecting with VERIFY, 4-64
NFS volume
selecting
with VERIFY, 4-8
NO attribute, 12-36
Non-file-structured exercising
lOX, 4-3
Nonrecoverable errors, 15-32
/NSF keyword (VMR) , 10-19
Null device, 10-39
OCOP, 12-30
ODT
disabling, 9-4
OFFLINE command, 15-19
OFFLINE MEMORY, 15-22
On-Line Debugging Tool
See ODT
ONLINE command, 15-23
ONLINE MEMORY, 15-26
/OPT keyword (VMR) , 10-64
PAR
See PARTITIONS command (VMR)
/PAR keyword (VMR) , 10-33, 10-64,
10-66
Parameter
lOX
command category, 4-3
exercising
device-dependent exercise,
4-8
Files-II volumes, 4-10
magnetic tape, 4-12
NFS volume, 4-15
list of exercise parameters,
4-8
overriding default
FILESll, 4-39
SELECT, 4-58
showing default with
PARAMETERLIST, 4-44
PARAMETERLIST command
lOX, 4-44
displaying buffer space, 4-44
displaying defaults, 4-44
Parameters (VMR), 10-4
/PARITY keyword (VMR) , 10-66 to
10-67
Parser processing, 12-19
Partition
common, 14-1
common block, 10-31
creating, 10-54
definition, 14-1
fragmentation, 14-3
rna in, 19-4
modifying, 10-55

Partition (Cont.)
overriding, 10-24
region, 10-18
system-controlled, 14-1
type, 10-65
user-controlled, 14-1
PARTITION command (VMR) , 10-36
definition, 10-36
example, 10-36
format, 10-36
PARTITION DEFINITIONS command
See PARTITIONS command (VMR)
Partition display
contents, 10-36
symbol meaning, 10-36
Password
adding to account entry, 2-3
changing, 2-1, 2-7
characters, 2-3
contained in account entry, 2-1
displaying, 2-5, 2-8
/PASTHRU keyword (VMR) , 10-67
Pattern
lOX
altering test, 4-48
displaying test, 4-48
PATTERN command
lOX, 4-48
Peripheral Interchange Program
See PIP utility
PIP utility
account file
copying, 2-3
extending, 2-3
PLAS
fixing tasks, 10-23
/PLCTL keyword (VMR) , 10-68
/PMD keyword (VMR), 10-25
PMT, 1-4
abortable tasks, 13-7
aborting, 13-11 to 13-12
action, 13-11
activation, 13-3
conditions affecting, 13-3
controlling pool use, 13-11
defaults
extreme fragmentation, 13-6
high pool state, 13-5
low pool state, 13-5
functions, 13-3
installation, 13-3
messages, 13-8
output
example of extreme
fragmentation, 13-9 to
13-10
low pool state, 13-6
task-build options, 13-10
timing, 13-10
Pool
conditions, 13-2
largest fragment increases,
13-5

Index-9

Pool
conditions (Cont.)
largest fragment too small,
13-4
fragmentation, 13-1
pool
definition, 13-1
Pool fragment size, 13-13
/POOL keyword (VMR) , 10-69
Pool limits, 13-12
high, 13-12
low, 13-12
Pool Monitor Task
See PMT
See PMT, 13-1
Pool monitoring interface
functions, 13-2
Pool Monitoring Support, 1-4
receiving, 13-1
/POOLSIZE keyword (VMR), 10-69
Predefined syntax elements, 12-40
basic data types, 12-40 to
12-41
common command elements, 12-42
to 12-43
program control elements, 12-46
special parser elements, 12-43,
12-45
special translator elements,
12-45 to 12-46
/PRI keyword (VMR) , 10-8, 10-25
Primary RBNs, 5-4
Print Despooler Transaction Block,
17-30
print processors
installation
DCL command, 7-6
MCR command, 7-6
print queue
initialization
DCL command, 7-5
MCR command, 7-5
/PRINTER PORT keyword (VMR) ,
10-6~

PRINTSUMMARY command
lOX, 4-49
/PRIV keyword (VMR) , 10-70
Privileged user input
rejection of, 10-50
PRO attribute, 12-37
/PRO keyword (VMR) , 10-25
PROCEED command
lOX, 4-50
Processor failures, 15-34
Professional Personal Computer
file transfer, 9-1
Prompting
CLI, 11-7 to 11-8
Protection
file, 2-3
Protection mask, 10-25
Protection UIC, 10-25
Prototype task
fixing, 10-18

Prototype tasks, 10-27
PRT error messages, A-2
PRT task, 1-6
PRT •••
See Serial Despooler Task
Pseudo device
installing from, 10-3
/PUB keyword (VMR) , 10-70
QMG, 1-2, 7-1
commands, 7-14
ASSIGN/QUEUE, 7-23
DCL format, 7-14
DEASSIGN/QUE, 7-23
DELETE, 7-21
DELETE PROCESSOR, 7-21
DELETE/QUEUE, 7-21
INITIALIZE/PROCESSOR, 7-16
MCR format, 7-14
START, 7-27
START/PftOCESSOR, 7-29
START/QUEUE, 7-27
START/QUEUE/MANAGER, 7-27
STOP, 7-24
STOP/ABORT, 7-26
STOP/PROCESSOR, 7-25
STOP/QUEUE, 7-24
STOP/QUEUE/MANAGER, 7-24
INITIALIZE command, 7-14
INITIALIZE/QUEUE, 7-14
installation, 7-3, 7-9
starting, 7-4
DCL command, 7-4
MCR command, 7-4
QMGCLI, 7-1
$QTRAN, 17-17
$QTRANl, 17-18
$QTRAN2, 17-19
QUA attribute, 12-38
Queue management subsystem, 7-1
to 7-2
Queue Manage~, 1-2, 7-1
RANDOM command
lOX, 4-51
RANGE command
lOX, 4-52
RBNs, 5-2
primary
secondary
status codes, 5-2 to 5-3
RCT, 5-1, 5-5
See Bad Block Replacement
Control Task
and Error Logger, 5-5
installation, 5-2
RD:, 15-1
REA
See REASSIGN command (VMR)
Read
nondestructive
NFS volumes, 4-64
REASSIGN command (VMR) , 10-38
definition, 10-38

Index-lO

REASSIGN command (VMR) (Cont.)
examples, 10-38
format, 10-38
parameters, 10-38
Reconfiguration components, 15-1
CON, 15-1
HRC, 15-1
RD:, 15-1
Reconfiguration driver
See 1<:D:
Reconfiguration services, 1-4,
15-,1
initiating, 15-4
system faults, 15-31
Reconfiguration task
See HlRC
RECORDS command
lOX, 4-53
Recoverable errors, 15-32
RED
See R:EDIRECT command (VMR)
REDIRECT command (VMR) , 10-39
definition, 10-39
examples, 10-39
format, 10-39
parameters, 10-39
restrictions, 10-39
/REG keyword (VMR) , 10-19, 10-40,
10-,92
Region
disk data cache, 19-3
extent, 19-3
forma t, 19-4
dynamic storage, 10-69
fixing, 10-19
read-only, 10-26
read/write access, 10-26
unfixing, 10-92
/REGIS keyword (VMR) , 10-70
REM
See REMOVE command (VMR)
/REMOTE: keyword (VMR) , 10-71 to
10-·72
REMOVE command (VMR), 10-40
definition, 10-40
examples, 10-40
forma.t, 10-40
keyword
/RE:G, 10-40
notes, 10-40
parameters, 10-40
Replacement blocks
See R:BNs
Report
interval
output frequency, 4-62
REPORTERRORS YES/NO command
lOX, 4-54
Reschedule interval, 10-43
Resource Accounting, 1-5, 17-1
See a.lso Transaction file
commands, 17-4
SET ACCOUNTING, 17-4, 17-8

Resource Accounting
commands (Cont.)
SHOW ACCOUNTING/DATATRIEVE,
17-3, 17-17
SHOW ACCOUNTING/INFORMATION,
17-3, 17-11
SHOW ACCOUNTING/TRANSACTION FILE,
17-3, 17-12
START/ACCOUNTING, 17-4 to
17-5
STOP/ACCOUNTING, 17-4, 17-10
device statistics example, 17-7
interface for creating
transactions
$QTRAN, 17-17
$QTRANl, 17-18
$QTRAN2, 17-19
messages, 17-40
privileged task interface,
17-21
scan rate, 17-6
secondary pool, 17-5
statistics scan, 17-6
system resources, 17-39
system statistics, 17-5
task accounting, 17-6
user-written analysis programs,
17-3
using DATATRIEVE-ll for an
accounting report, 17-16
Resource Monitoring Display
See RMD
RESTART command
lOX, 4-55
RETRIES command
lOX, 4-56
Revector control tables, 5-2
RL02 exercise
lOX, 4-10
RMD, 1-2, 6-1
Active Task Display, 6-8
altering
from MCR, 6-9
altering from setup page, 6-8
Active Task List Page, 6-1
cache region
detailed statistics
altering from MCR, 6-18
detailed statistics display,
6-16
altering from setup page,
6-17
general statistics
altering from MCR, 6-16
general statistics display,
6-14
altering from setup page,
6-15
General Statistics Page, 6-1
cached device
Detailed Statistics Page, 6-1
display pages, 6-1

Index-II

RMD
displaying
disk data cache statistics,
19-14
displaying disk data cache
statistics, 19-12
displays available on
RSX-IIM-PLUS, 6-11
error messages, 6-18
Help display, 6-3
Help Page, 6-1
I/O Counts Display
altering
from MCR, 6-12
from setup page, 6-12
I/O Counts Page, 6-1
installation, 6-2
MCR INSTALL command, 6-2
RSX-IIM systems, 6-2
RSX-IIM-PLUS systems, 6-2
invoking, 6-2
memory display, 6-4
FREE command, 6-7
modifying, 6-7
RATE command, 6-7
Memory Page, 6-1
pages, 6-1
running on a slaved terminal,
6-3
setup command, 6-2
setup pages, 6-2
System Statistics Display, 6-13
altering
from MCR, 6-14
from setup page, 6-14
System Statistics Page, 6-1
Task Header Display, 6-9
altering
from MCR, 6-11
from setup page, 6-10
contents, 6-10
Task Header Page, 6-1
task-build command file
altering, 6-18
using at terminals, 6-2
RMT, 11-2
/RNDC keyword (VMR) , 10-72
/RNDH keyword (VMR) , 10-72
/RNDL keyword (VMR) , 10-72
/RON keyword (VMR) , 10-19, 10-26,
10-92
/ROPAR keyword (VMR) , 10-26
/RPA keyword (VMR) , 10-73
/RSI keyword (VMR) , 10-44
RSXll. SYS
See Account file
RUN command (VMR), 10-42
definition, 10-42
formats, 10-42, 10-46
keywords
/RSI, 10-44
/UIC, 10-44
parameters, 10-42
restriction, 10-42

RUN command (VMR) (Cont.)
time options, 10-42
Running VMR, 10-2
RUNTIME command
lOX, 4-57
SAB
Resource Accounting, 17-11
Sample configuration
increasing system throughput,
15-20
SAY

See SAVE command (VMR)
SAVE command (VMR) , 10-47
definition, 10-47
example, 10-48
format, 10-47
keywords
/BOOT, 10-47
/DENS, 10-48
notes, 10-48
parameters, 10-47
Scan rate
Resource Accounting, 17-6
/SEC keyword (VMR) , 10-27
Secondary pool
Resource Accounting, 17-5
Secondary RBNs, 5-4
/SECPOL keyword (VMR) , 10-73
SELECT command
lOX, 4-58
Serial command processing
CLI, 11-8
Serial Despooler
See PRT
Serial Despooler Task
error messages, A-2
receive queue operation, A-l
task-build information, A-l
text requirements, A-l
/SERIAL keyword (VMR) , 10-73
SET /PLCTL command, 13-12
SET ACCOUNTING
Resource Accounting, 17-4
Set Accounting Transaction Block,
17-26
SET command, 15-27
disk data caching, 19-16
I/O Queue Optimization, 16-1
SET command (VMR) , 10-50
definition, 10-50
examples, 10-83, 10-87
Executive features, 10-50
format, 10-50
keyword table, 10-51, 10-53
keywords
/AFF, 10-54
/BOT, 10-55 to 10-56
/BUF, 10-57
/HFILL, 10-59
/LIBUIC, 10-60
/LINES, 10-61
/MAXEXT, 10-63
/NETUIC, 10-63

Index-12

SET command (VMR)
keywords (Cont.)
/[NO]ABAUD, 10-53
/[NO]ANSI, 10-54
/[NO]AVO, 10-54
/[NO]BLKMOD, 10-55
/[NO]BRO, 10-56
/[NO]CRT, 10-57
/[NO]DEC, 10-57
/[NO]EBC, 10-57
/[NO]ECHO, 10-58
/[NO]EDIT, 10-58
/[NO]ESCSEQ, 10-58
/[NO]FDX, 10-59
/[NO]FORMFEED, 10-59
/[NO]HHT, 10-59
/[NO]HSYNC, 10-60
/[NO]LOGON, 10-61
/[NO]LOWER, 10-61
/[NO]MAIN, 10-61, 10-63
/[NO]OPT, 10-64
/[NO]PAR, 10-64, 10-66
/[NO]PARITY, 10-66 to 10-67
/[NO]PASTHRU, 10-67
/[NO]PRINTER PORT, 10-69
/[NO]PRIV, 10-70
/[NO]PUB, 10-70
/[NO]REGIS, 10-70
/[NO]REMOTE, 10-71 to 10-72
/[NO]RPA, 10-73
/[NO]SERIAL, 10-73
/[NO]SLAVE, 10-74
/[NO]SOFT, 10-74
/[NO]SUB, 10-76 to 10-77
/[NO]TTSYNC, 10-80
/[NO]TYPEAHEAD, 10-80 to
10-81
/[NO]VFILL, 10-81
/[NO]WCHK, 10-81
/[NO]WRAP, 10-82 to 10-83
/PLCTL, 10-68
/POOL, 10-69
/POOLSIZE, 10-69
/RNDC, 10-72
/RNDH, 10-72
/RNDL, 10-72
/SE:CPOL, 10-73
/SPEED, 10-75
/SWPC, 10-77
/SWPR, 10-77
/SYSUIC, 10-77
/TERM, 10-78 to 10-79
/TOP, 10-79 to 10-80
/UIC, 10-81
parameter, 10-51
uses, 10-50
SET HOST/DTE command, 9-3, 9-5 to
9-6
SET PASSWORD, 2-1
SET TERMINAL command, 9-3
Shadow Recording, 1-5
Bad block handling, 18-10
commands, 18-4
ABORT, 18-4, 18-7

Shadow Recording
commands (Cont.)
CONTINUE, 18-4, 18-8
DISPLAY, 18-4, 18-9
START, 18-4 to 18-5
STOP, 18-4, 18-6
controlling, 18-4
error messages, 18-11
preparation, 18-2
primary disk errors, 18-10
secondary disk errors, 18-10
simultaneous disk errors, 18-11
uses, 18-1
SHF, 1-4
algorithms
first pass, 14-5
second pass, 14-6
conventions, 14-1
installation, 14-4
monitoring with RMD, 14-4
overhead, 14-4
performance, 14-4
removal, 14-5
shuffling
dynamic common regions, 14-5
fixed tasks, 14-5
partition sections, 14-5
static common regions, 14-5
size, 14-4
$SHFCT
changing contents, 14-4
$SHFTM, 14-4
SHOW ACCOUNTING commands, 17-11
SHOW ACCOUNTING/INFORMATION
Resource Accounting, 17-3
SHOW ACCOUNTING/TRANSACTION FILE
Resource Accounting, 17-3SHOW CACHE command
disk data caching, 19-8
SHOW DEVICE command
disk data caching, 19-9
Shuffler
See SHF
Shutdown
RSX-11M system
example, 8-5
procedure, 8-4
RSX-11M-PLUS system
example, 8-7
procedure, 8-6
SHUTUP
examples
RSX-11M, 8-2
RSX-11M-PLUS, 8-2
input, 8-2
invoking, 8-1
output, 8-2
prerequisites to running, 8-1
SHUTUP program, 1-3, 8-1
SHUTUP.CMD, 8-3
example of file, 8-4
/SIZE keyword (VMR), 10-34
/SL switch (TKB), 10-27
/SLAVE keyword (VMR), 10-74

Index-13

/SLV (VMR)
and /SL switch (TKB) , 10-27
and prototype tasks, 10-27
/SLV keyword (VMR), 10-27
Soft errors, 15-32
/SOFT keyword (VMR) , 10-74
Sort option
ACNT, 2-10
/SPEED keyword (VMR) , 10-75
SPWN$ directive
lOX
in EXECUTE command, 4-37
Spy command
lOX, 4-60
START command
lOX, 4-61
Shadow Recording, 18-5
START/ACCOUNTING
Resource Accounting, 17-5
Starting VMR, 10-2
STARTUP.CMD, 7-1
Static common region
checkpointing, 14-3
resident common, 14-3
resident libraries, 14-3
shuffling, 14-6
Statistics scan
Resource Accounting, 17-6
STOP command
Shadow Recording, 18-6
STOP/ACCOUNTING
Resource Accounting, 17-4
/SUB keyword (VMR) , 10-76 to
10-77
Summary report
generated by PRINTSUMMARY, 4-49
lOX, 4-20
SUMMARYTIME command
lOX, 4-62
SWITCH command, 15-29
/SWPC keyword (VMR) , 10-77
/SWPR keyword (VMR) , 10-77
Symbol Definition File
/IM switch, 10-2
relationship to system image
file, 10-1
specifying, 10-2
VMR requirements, 10-1
/SYNC keyword (VMR) , 10-27
Syntax elements
attributes, 12-26
System Account Block, 17-3, 17-24
System device
states, 15-2
System faults, 15-31, 15-33
System file names
conventions, B-4
System File Types, B-5T to B-6T
System Image File
assigning SY: and LB:, 10-1
bootstrap, 10-1
relationship to symbol
definition file, 10-1
VMR prompt, 10-3

System Image File (Cont.)
creating, 10-18
size, 10-18
/SYSTEM keyword (VMR) , 10-10
System reconfiguration, 15-1
System recovery, 15-33
methods, 15-33
System statistics
Resource Accounting, 17-5
System Task Directory, 10-31
System Time Change Transaction
Block, 17-29
System UFOs, B-3T to B-4T
example, B-3
System-controlled partition, 14-1
conventions, 14-3
definition, 14-3
fragmentation
causes of, 14-4
subpartitions of, 14-3
waiting tasks, 14-3
/SYSUIC keyword (VMR) , 10-77
TAB
Resource Accounting, 17-11
TAS
See TASKLIST command (VMR)
Task
access to commons, 10-25
after exit, 10-92
checkpointable, 10-18
checkpointing, 10-22, 10-28
execution termination, 4-24
extension size, 10-24
file identification, 10-32
fix ed, 10-18
initiation
lOX
EXECUTE command, 4-37
install options, 10-29
memory management support,
10-18
name
CLI, 11-4
reexecuting, 10-18
removing, 10-18
restrictions for fixing, 10-18
size, 10-63
system size, 10-18
unfixing from memory, 10-92
with external headers, 10-28
with resident headers, 10-28
Task Account Block, 17-3, 17-22
Task accounting
Resource Accounting, 17-6
Task Control Block, 10-31
/TASK keyword (VMR) , 10-27
Task-bu i Id file
location of lOX, 4-22
TASKLIST command (VMR) , 10-88
definition, 10-88
examples, 10-88 to 10-89
format, 10-88
parameter, 10-88

Index-14

Telephone
dial command string, 9-4
TEMPORARYFILE command
lOX, 4-63
/TERM keyword (VMR) , 10-78 to
10-· 79
Terminal
baud rate, 9-2
emulation, 9-1, 9-5
mute, 9-4
nonslaved, 10-50
port, 9-1
slaved, 10-50
typeahead, 9-5
Terminal emulation, 1-3
establishing, 9-3
terminating, 9-3
Test configuration
lOX
pattern altering, 4-48
pattern displaying, 4-48
setup, 4-6
TIM
See '1'IME command (VMR)
Time
displaying, 10-90
setting, 10-90
TIME command (VMR) , 10-90
definition, 10-90
examples, 10-90
formats, 10-90
notes, 10-91
parameters, 10-90
/TOP keyword (VMR) , 10-79 to
10-80
Transaction Account Block, 17-3
Transaction file
account block linkages, 17-38
account blocks, 17-11, 17-20
system account block (SAB) ,
17-11
task account block (TAB),
17-11
transaction account blocks,
17-11
user account block (UAB) ,
17-11
accumulation fields, 17-33
block diagrams, 17-22
card reader job data, 17-3
card reader spooling block,
17-36
crash recovery block, 17-35
OATATRIEVE-ll, 17-16
device allocation,
deallocation, or dismount
data, 17-2
device mount data, 17-2
device statistics block, 17-37
device usage da ta ,. 17-3
disk accounting block, 17-36
example, 17-12
header area, 17-32
invalid login block, 17-36

Transaction file (Cont.)
login data, 17-2
offset definitions, 17-32
print despooler block, 17-36
print job data, 17-2
set accounting block, 17-35
size, 17-5
system account block (SAB) ,
17-35
system data, 17-2
system time change, 17-3
system time change block, 17-36
task data, 17-1
user account block, 17-33
user data, 17-1
Transient failures, 15-31
Translator processing, 12-19
Transparent spooling, 7-1
TST attribute, 12-39
/TTSYNC keyword (VMR) , 10-80
Typeahead buffer, 9-5
/TYPEAHEAO keyword (VMR) , 10-80
to 10-81
UAB
Resource Accounting, 17-11
UFO, B-1
group number, B-1
Accounting tasks, B-2
OCL files, B-1
Executive files, B-1
FCP files, B-1
FCS files, B-2
K-Series files, B-2
Line printer despooler, B-2
MCR files, B-1
On-line configuration, B-2
Privileged utility tasks, B-1
Queue Manager files, B-2
RMO files, B-1
Shadow Recording, B-2
SYSGEN Indirect command files,
B-2
member number, B-2
Object modules, B-2
SLP correction files, B-2
Source modules, B-2
UFO conventions, 1-6
UFO Group Number Identification
Table, B-lt to B-2t
UFO Member Number Identification
Table, B-2t to B-3t
UIC, 10-25
authorized, 2-1
contained in account entry, 2-1,
2-7, 2-9
displaying, 2-5, 2-8
distinction by password, 2-1
/UIC keyword (VMR) , 10-28, 10-44,
10-81
UNF
See UNFIX command (VMR)
UNFIX command (VMR) , 10-92
definition, 10-92

Index-15

UNFIX command (VMR) (Cont.)
example, 10-92
format, 10-92
keywords
/REG, 10-92
/RON, 10-92
parameters, 10-92
UNL
See UNLOAD command (VMR)
UNLINK command, 15-30
UNLOAD command (VMR), 10-93
definition, 10-93
example, 10-93
format, 10-93
keyword
/VEC, 10-93
parameter, 10-93
restrictions, 10-93
User Account Block, 17-3, 17-23
User File Directory
See UFO
User groups, 10-26
User Identification Code
See UIC
User-controlled partition, 14-1
User-written encryption routines
support, 2-1
VAX-ll RSX file transfer, 9-1,
9-5
VAX/VMS file transfer, 9-1, 9-5
/VEC keyword (VMR), 10-34, 10-93
VERIFY command
lOX, 4-64
effect on NFS volume, 4-8
/VFILL keyword (VMR), 10-81
virtual Monitor Console Routine
See VMR
Virtual Monitor Console Routine
(VMR)
see VMR
VMR, 1-3
before starting, 10-1
command abbreviations, 10-4
command description format,
10-7
command descriptions, 10-7,
10-93
command format, 10-4
command keyword values, 10-5
command keywords, 10-4
command names, 10-4
command parameters, 10-4
command syntax, 10-4
command types, 10-1
comments, 10-5
definition, 10-1
error messages, 10-94, 10-112
exi ting, 10-3
file specifications
components, 10-5
default device, 10-5
default directory, 10-6
default file name, 10-6

VMR
file specifications (Cont.)
default file types, 10-6
default version number, 10-6
device name, 10-5
directory, 10-6
file names, 10-6
file type, 10-6
format, 10-5
/IM switch, 10-7
specifying, 10-5
version number, 10-6
version number range, 10-6
indirect command file, 10-3
instalLing from LB:, 10-3
introduction, 10-1
prompt, 10-3
relationship to MCR, 10-1
running, 10-2
starting, 10-1 to 10-2, 10-4
system image file
assigning SY: and LB:, 10-1
bootstrap, 10-1
relationship to symbol
definition file, 10-1
VMR commands
ALTER, 10-8
ASSIGN, 10-9
CANCEL, 10-11
CONFIGURATION, 10-12
DEVICES, 10-16
FIX, 10-18
INSTALL, 10-21
LOAD, 10-33
LUNS, 10-35
PARTITIONS, 10-36
REASSIGN, 10-38
REDIRECT, 10-39
REMOVE, 10-40
RUN, 10-42
SAVE, 10-47
SET, 10-50
TASKLIST, 10-88
TIME, 10-90
UNFIX, 10-92
UNLOAD, 10-93
Volume
Files-ll
protecting with TEMPORARYFILE,
4-63
NFS
altering block range, 4-52
displaying block range, 4-52
error retries, 4-56
list of parameter commands
for, 4-9
selecting
with lOX, 4-58
with VERIFY, 4-64
selecting
Files-ll for lOX, 4-8
NFS for rox, 4-8
VOLUMECHECK command
lOX, 4-65

Index-16

WAIT c()mmand
lOX, 4-66
/WB keyword (VMR), 10-28
/WCHK keyword (VMR), 10-81
/WRAP keyword (VMR), 10-82 to
10--83
Write-back cache data
preventing loss, 5-5

Write-check
enabling in lOX, 4-67
WRITECHECK command
lOX, 4-67
/XHR keyword (VMR), 10-28
XON/XOFF protocol, 9-2

Index-17

RSX-IIM/M-PLUS
System Management Guide
AA-FD12A-TC
READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

o Assembly language programmer
o Higher-level language programmer

o Occasional programmer (experienced)

o User with little programming experience
o Student programmer
[J Other (please specify)
Name _________________________________________________ Date _________________________________
Organization
Street
City _______________________________________________ State _ _ _ _ _ _ Zip Code _ _ _ _ __
or Country

Do Not Tear - Fold Here and Tape -

~D~DDmD

IIIII

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

Do Not Tear - Fold Here