Digital PDFs

AA-H268A-TC

June 1979

666 pages

Original

28MB

Document:	RSX-11 Utilities Manual
Order Number:	AA-H268A-TC
Revision:	0
Pages:	666
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/4_Utilities/AA-H268A-TC_RSX-11M_V3.2_Utilities_197906.pdf

OCR Text

RSX-11
Utilities Manual
Order No. AA-H268A-TC

RSX-11M Version 3.2
RSX-11 M-P LUS Version 1.0

··~·

lr·o order additional copies of this document, contact the Software Distribution
L,:enter, Digital Equipment Corporation, Maynard, Massachusetts 01754

digiital equipment corporation · maynard, massachusetts

First Printing, June 1979
The information in this document is subject to change without notice
and should not be construed as a conunitment 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 only be used or copied 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 or its affiliated companies.

1979 by Digital Equipment Corporation

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-lo
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

10/79-14

;;

t t !i!iJii ii!!ii

Ji!

!qi UL iii iliiiiii; 1Jiiiii4 ;;::::

\...,..;
CONTENTS
Page
SUMMARY OF TECHNICAL CHANGES

xvii

PREF'ACE

xxi
PART 1

CHAPTER

\.,J

INTRODUCTION

1-1

Ll
1..1.1
Ll.2
1..1.3
1.1.4
1..1.5
1..1.6
1..2
1. 3
1..4
1.. 4 .1
1.. 4. 2
1. 4. 3
1..4.4

RSX-11 UTILITY PROGRAMS
Editing Utilities
File Manipulation Utilities
File Spooling Utilities
Volume Maintenance Utilities
Programming Utilities
Program Maintenance Utilities
ENTERING RSX-11 COMMAND LINES
ENTERING FILE SPECIFICATIONS
INVOKING RSX-11 UTILITIES
Installing Utilities on Your System
Invoking Installed Utilities
Invoking Uninstalled Utilities
Using Indirect Command Files

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

PART 2
CHAPTER

'-'/

INTRO DUCT ION

EDITING UTILITIES

DEC EDITOR (EDT)

2-1

2 .. 1
2 .. 2
2v2el
2n2e2
2o2e3
2 .. 3
2o3el
2o3e2
2o3.3
2o3e4
2 .. 3.5
2o3.6
2.3.7
2o3e8
2.3.9
2a3.10
2o3.ll
2" 3 .12
2 .. 3.13
2o3ol4
2.3.15
2 .. 3.16

INVOKING EDT
THE EDT COMMAND STRING
EDT Commands
Range Specification
Options
DETAILED COMMAND DESCRIPTIONS
CHANGE
COPY
DELETE
EXIT
FIND
INCLUDE
INSERT
MOVE
PRINT
QUIT
REPLACE
RESEQUENCE
RESTORE
SAVE
SET
SHOW
SUBSTITUTE
TYPE
WRITE

2-2
2-4
2-5
2-10
2-19
2-20
2-21
2-22
2-23
2-25
2-25
2-26
2-28
2-30
2-32
2-33
2-34
2-35
2-37
2-38
2-38
2-40
2-42
2-44
2..:.45

2~3.17

2 .. 3.18
2 .. 3.19

~
iii

CONTENTS
Page

CHAPTER

2.3.20
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.5
2.6

XEQ {Execute)
CHARACTER MODE
Editing Subconunands
Cursor Manipulation
Subconunand Concatenation
Subconunands to Terminate Character Mode
SUMMARY OF EDT COMMAND MODE COMMANDS
ERROR REPORTING AND ERROR MESSAGES

2-46
2-48
2-49
2-55
2-58
2-59
2-60
2-62

LINE TEXT EDITOR {EDI)

3-1

3.1
3 .1.1
3.1. 2
3.1. 3
3.1. 4
3 .1. 5
3.1. 6
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.2.7
3.2.8
3.2.9
3.2.10
3.2.11
3.2.12
3.2.13
3.2.14
3.2.15
3.2.16
3.2.17
3.2.18
3.2.19
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.4.7
3.4.8
3.4.9
3.4.10
3.4.11

USING EDI
3-1
Invoking EDI
3-1
Control Modes: Input and Edit
3-3
Text Access Modes
3-3
Text Files
3-6
Terminal Conventions
3-7
EDI Conunand Conventions
3-8
BASIC EDI COMMANDS
3-10
ADD
3-11
3-12
ADD & PRINT
3-12
BOTTOM
3-13
CHANGE
<CTRL/Z>
3-13
DELETE
3-13
DELETE & PRINT
3-14
<ESCape>
3-14
.l:!;XIT
3-15
3-15
INSERT
LOCATE
3-15
NEXT
3-16
NEXT & PRINT
3-16
PRINT
3-17
3-18
RENEW
<RETURN>
3-19
RETYPE
3-19
TOP
3-19
TOP OF FILE {TOF)
3-20
EDI COMMANDS: FUNCTION SUMMARY
3-20
Setup Conunands
3-20
Locator Conunands {Line-Pointer Control)
3-21
Text Modification and Manipulation Conunands 3-23
Macro Commands
3-24
File Input/Output Conunands
3-25
Device Output Conunands
3-25
CLOSE and EXIT commands
3-25
EDI COMMANDS: DETAILED REFERENCE SUMMARY
3-27
ADD
3-27
ADD & PRINT (AP)
3-27
BEGIN
3-27
BLOCK ON/OFF
3-28
BOTTOM
3-28.
CHANGE
3-28
CLOSE
3-28
CLOSE SECONDARY {CLOSES)
3-29
CLOSE & DELETE (CD)
3-29
CONCATENATION CHARACTER {CC)
3-29
CTRL/Z
3-30

'Ill

Jil ! I i i

iiiiii

I IJ4i!I

iiii2

i!UiiiJ.lii.i I 1111041

CONTENTS
Page
3.4.12
3.4.13
3.4.14
3.4.15
3.4.16
3.4.17
3.4.18
3.4.19
3.4.20
3.4.21
3.4.22
3.4.23
3.4.24
3.4.25
3.4.26
3.4.27
3.4.28
3.4.29
3.4.30
3.4.31
3.4.32
3.4.33
3.4.34
3.4.35
3.4.36
3.4.37
3.4.38
3.4.39
3.4.40
3.4.41
3.4.42
3.4.43
3.4.44
3.4.45
3.4.46
3.4.47
3.4.48
3.4.49
3.4.50
3.4.51
3.4.52
3.4.53
3.4.54
3.4.55
3.4.56
3.4.57
3.4.58
3.5
3.6
3.6.l
3.6.2
3.6.3
3.6.4

'-''

DELETE
DELETE & PRINT (DP)
END
ERASE
<ESCape>
EXIT
EXIT & DELETE (ED)
FILE
FIND
FORM FEED (FF)
INSERT
KILL
LINE CHANGE (LC)
LIST ON TERMINAL (LI)
LIST ON PSEUDO-DEVICE (LP)
LOCATE
MACRO
MACRO CALL (MC)
MACRO EXECUTE
MACRO IMMEDIATE
NEXT
NEXT & PRINT
OPEN SECONDARY
OUTPUT ON/OFF
OVERLAY
PAGE
PAGE FIND
PAGE LOCATE
PASTE
PRINT
READ
RENEW
<RETURN>
RETYPE
SAVE
SEARCH & CHANGE
SELECT PRIMARY
SELECT SECONDARY
SIZE
TAB ON/OFF
TOP
TOP OF FILE (TOF)
TYPE
UN SAVE
UPPER CASE ON/OFF
VERIFY ON/OFF
WRITE
EDI USAGE NOTES
EDI ERROR MESSAGES
Command Level Information Messages
File Access Error Messages
Error Messages Requiring EDI Restart
Fatal Error Messages
PART 3

CH.A.PTER

3-30
3-30
3-31
3-31
3-31
3-31
3-32
3-32
3-32
3-33
3-33
3-33
3-34
3-34
3-35
3-35
3-35
3-36
3-37
3-37
3-38
3-38
3-38
3-39
3-39
3-40
3-40
3-41
3-41
3-41
3-42
3-42
3-42
3-43
3-43
3-44
3-44
3-45
3-45
3-45
3-46
3-46
3-47
3-47
3-47
3-48
3-48
3-49
3-50
3-50
3-54
3-55
3-57

FILE MANIPULATION UTILITIES

PERIPHERAL INTERCHANGE PROGRAM (PIP)

\...r·
v

4-1

CONTENTS
Page

4. 1. 2
4 .1. 3
4.2
4.2.1
4.2.2
4.3
4.4

PIP COMMAND STRING
PIP Defaults for File Specification
Elements
PIP Switches and Subswitches
Wildcards
PIP COMMAND FUNCTIONS
Copying Files-11 Files
Performing File Control Functions
PIP ERROR MESSAGES
PIP ERROR CODES

4-1
4-3
4-4
4-5
4-5
4-9
4-38
4-46

FILE TRANSFER PROGRAM (FLX)

5-1

5.1

FLX COMMAND STRING
FLX SWITCHES
Volume Format Switches
Transfer Mode switches
Control Switches
DOS-11 VOLUME DIRECTORY MANIPULATION
Displaying DOS-11 Directory Listings
Deleting DOS-11 Files
Initializing DOS-11 Volumes
RT-11 VOLUME DIRECTORY MANIPULATION
Displaying RT-11 Directory Listings
Deleting RT-11 Files
Initializing RT-11 Volumes
FLX TA11/TU60 CASSETTE SUPPORT
Multivolume Cassette Support
FLX Cassette Output Files
FLX Cassette Input Files
FLX PAPER TAPE SUPPORT
FLX ERROR MESSAGES

5-2
5-3
5-3
5-4
5-6
5-8
5-8

4.1
4 .1.1

CHAPTER

5.2
5.2.1
5.2.2
5.2.3
5.3

5.3.1
5.3.2
5.3.3
5.4
5.4.1
5.4.2
5.4.3

5.5
5.5.1
5.5.2
5.5.3
5.6
5.7

PART 4
CHAPTER

5-10
5-10
5-10

5-10
5-11
5-11

5-12
5-13
5-13

5-14
5-15
5-16

FILE SPOOLING UTILITIES

PRINT AND QUEUE UTILITY

6.1

6.6

INTRODUCTION TO THE PRINT COMMAND AND
QUEUE MANAGER
PRINT COMMAND FORMAT
PRINT COMMAND DESCRIPTION
QUEUE MANAGER COMMAND FORMAT
QUEUE /LIST Command
QUE /MOD Command
QUEUE /HOLD Command
QUEUE /RELEASE Command
QUEUE /DELETE Command
PRINT JOBS QUEUED BY USER TASKS - OUTPUT
SPOOLING
Opening A File On Disk and Using FCS
Opening A File On Disk and Using the
Print Command
ERROR MESSAGES

THE QUEUE MANAGER

7-1

7.1
7.2

NARRATIVE INTRODUCTION AND REVIEW
REFERENCE EXAMPLE

7-2
7-4

6.2

6.3
6.4
6.4.1
6.4.2
6.4.3
6.4.4
6.4.5
6.5
6.5.1
6.5.2

CHAPTER

4-1

6-1
6-1
6-3
6-4
6-9
6-9
6-13

6-14
6-15
6-16
6-17
6-18

6-18
6-18

'!1111

iii!

iii Ui i ! !. .ii 2 I I .iiiii! tt I .Jiii!

ij iii$211!41 $l!ili23!!!1!ii21A

CONTENTS
Page
7.3
7.3.l
7.3.2
7.3.3
7.3.4
7.3.5
7.3.6
7.4

QUEUE MANAGER COMMAND DESCRIPTIONS
STOP
START
SPOOL
UN SPOOL
ASSIGN
DEASSIGN
ERROR MESSAGES
PART 5

CHA.PTER

\.._.,·

cm.PTER

7-4
7-5
7-6
7-8
7-10
7-10
7-11
7-11

VOLUME MAINTENANCE UTILITIES

DISK VOLUME FORMATTER (FMT)

8-1

8.1
8.2
8.2.1
8.2.2
8.3
8.3.1
8.3.2

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

8.3.3
8.3.4
8.3.5
8.3.6
8.4
8.4.1
8.4.2
8.4.3
8.4.4
8.4.5
8.4.6
8.4.7
8.4.8
8.5

INITIATING AND TERMINATING FMT
MODES OF FMT OPERATION
Normal Operating Mode
Manual Operating Mode
FMT-SUPPORTED DEVICES
DB: Devices (RP04/RP05/RP06 Disk Packs)
DK: Devices (RKOS Disk Cartridge or
RK05F Fixed Media Disks)
OM: Devices (RK06/RK07 Disk Cartridges)
DP: Devices (RPR02/RP02/RP03 Disk Packs}
DR: Devices (RM02/RM03 Disk Packs)
DY: Devices (RX02 Floppy Diskettes)
FMT SWITCHES
/BAD
/DENS
/ERL
/MAN
/OVR
/VE
/WLT
/@Y
FMT MESSAGES

8-5
8-5
8-6
8-6
8-6
8-6
8-7
8-7
8-7
8-7
8-8
8-8
8-8
8-8
8-8

BAD BLOCK LOCATOR UTILITY (BAD)

9-1

9.1
9.2
9.2.1
9.2.2
9.3
9.3.l
9.3.2
9.3.3
9.4
9.4.1
9.5
9.5.1

INTRODUCTION TO BAD
INVOKING BAD
BAD Switches
BAD And Indirect Files
PROCESSING BAD BLOCK DATA
Verifying Devices
Format of Bad Block Descriptor Entries
The INI Conunand and BAD
USING THE BAD UTILITY
Progranuning Considerations
BAD SWITCH DESCRIPTIONS
Switches for both Task and Stand-Alone
System Versions Of BAD
The Manual and Update Switches
Switches for Stand-Alone System Version
Only
DEVICES SUPPORTED BY THE STAND-ALONE
VERSION
BAD MESSAGES

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

9.5.2
9.5.3
9.6
9.7

vii

9-5
9-6
9-7
9-8
9-8

CONTENTS
Page
CHAPTER 10

BACKUP AND RESTORE UTILITY (BRU)

10-1
10-1

10.5.1
10.5.2
10.5.3
10.6

OVERVIEW OF COMMAND QUALIFIERS AND DEFAULTS
Command Qualifiers For Selective Backup
And Restore
Command Qualifiers for Controlling Disk
Processing
Command Qualifiers for Controlling Tape
Processing
Command Qualifiers for Verifying the
Accuracy of Data Transferred
Command Qualifiers for Displaying
Information About Files Transferred
Command Qualifiers for Initializing Disks
DISK AND TAPE DEVICE INFORMATION
Files-11 Structures
Disk Volume Labels and Backup Set Names
Devices Supported for Backup and Restore
BACKUP AND RESTORE COMMAND LINE DESCRIPTIONS
Command Line Syntax Definition
Descriptions of Prompts
Description of Command Line Parameters
Description of Command Qualifiers
USING BACKUP AND RESTORE
Using the Format Utility with Backup and
Restore
Using the Bad Block Utility with Backup
and Restore
Using Backup and Restore to Initialize
Disks
Selective Transfer of Data
Backup and Restore to Disks of Different
Size
BRU and File Characteristics
TAPE FORMAT INFORMATION FOR BACKUP AND
RESTORE OPERATIONS
Backup Sets
Tape Sets
Multivolume Tape Operations
BACKUP AND RESTORE ERROR PROCESSING

10-26
10-27
10-27
10-27
10-28

DISK SAVE AND COMPRESS (DSC)

11-1

11.1
11.2
11. 3
11. 4
11.5
11. 5 .1
11. 5. 2
11. 5. 3
11. 5. 4
11. 5. 5
11. 5. 6
11. 5. 7
11. 5. 8
11. 6

DSC-SUPPORTED VOLUMES
INITIATING AND TERMINATING ONLINE DSC
INITIATING AND TERMINATING STAND-ALONE DSC
DSC COMMAND FORMAT
DSC FILE LABELS, SWITCHES, AND OPTIONS
File Label
Append Switch
Bad Block Switch
Block Factor Switch
Compare Switch
Density Switch
Rewind Switch
Verify Switch
DSC OPERATION OVERVIEW

11-4
11-6
11-6
11-7
11-8
11-9
11-10
11-10
11-13
11-14
11-15
11-16
11-18
11-19

10.1
10 .1.1
10 .1. 2
10 .1. 3
10 .1. 4
10 .1. 5
10 .1. 6
10.2
10.2.1
10.2.2
10.2.3
10.3
10.3.1
10.3.2
10.3.3
10.3.4
10.4
10.4.1
10.4.2
10.4.3
10.4.4
10.4.5
10.4.6
10.5

CHAPTER

10-3
10-5
10-5
10-6
10-6
10-7
10-7
10-7
10-9
10-9
10-10
10-10
10-10
10-11
10-13
10-21
10-22
10-22
10-23
10-24
10-24
10-25

.~
~

::~~'

viii

••:z•••••••-------.•••:1••••••:•1!!1•1•u•:.•:l2•u•:•;•JJ•11•1J!l l•..•: •.:••:•.••ilii•2••12s•1•••t•z••!S•¥1111•u:•m•

'·•

CONTENTS
Page
11. 7
11. 7 .1
11. 7. 2
11. 7. 3
11. 7. 4
11. 8
11. 8 .1
11. 8. 2
11. 8. 3
11. 8. 4
11.9
11. 9 .1

CHAPTER

11-19
11-20
11-21
11-22
11-22
11-23
11-23
11-23
11-25
11-25
11-26

11. 9. 2
11. 9. 3

STAND-ALONE DSC
Control Status Register Switch
TM02 Switch
Unit Switch
Vector Address Switch (/VEC=)
DSC OPERATION
Data Transfer from Disk
Data Transfer to Tape
Data Transfer from Tape
Data Transfer to Disk
DSC MESSAGES
DSC Messages: Text, Explanation, and
Corrective Action
DSC I/O Messages
Stand-Alone DSC Messages

VOLUME PRESERVATION UTILITY (PRESRV)

12-1

12.1
12 .1.1
12 .1. 2
12 .1. 3
12.2
12.2.1
12.2.2
12.2.3
12.3
12.3.l
12.3.2
12.3.3
12.3.4
12.3.5
12.4

12-1
12-1
12-2
12-3
12-4
12-6
12-7
12-9
12-10
12-13
12-13
12-18
12-20
12-21

12.5

INTRODUCTION TO PRESRV
Files-11 Format
Logical Tape Format
Image Format
PRESRV OPERATING PROCEDURES
Bootstrap Procedure
Tape Handling
Disk and DECtape Handling
PRESRV COMMAND LINE AND SWITCHES
List Switches (/HE and /LI)
Format and Blocking Switches
Administrative Switches
Magnetic Tape Switches
Stand-Alone PRESRV Switches
COMPUTING THE NUMBER OF BLOCKS REQUIRED
FOR BUFFERING
PRESRV ERROR MESSAGES

FILE STRUCTURE VERIFICATION UTILITY {VFY)

13-1

13.1
13.2
13.3
13.3.l
13.3.2
13.3.3
13.3.4
13.3.5
13.3.6
13.3.7
13.3.8
13.4
13.5

INTRODUCTION TO VFY
VFY COMMAND STRING
VFY SWITCHES
Validity Check
Delete Switch (/DE)
Free Switch (/FR)
List Switch {/LI)
Lost Switch (/LO)
Read Check Switch (/RC)
Rebuild Switch (/RE)
Update Switch (/UP)
VFY ERROR MESSAGES
VFY ERROR CODES (IAS SYSTEM ONLY)

13-1
13-2
13-3
13-4
13-8
13-8
13-9
13-9
13-9
13-10
13-11
13-11
13-14

PART 6
CHAPTER

11-27
11-39
11-41

12-25
12-27

PROGRAMMING UTILITIES

LIBRARIAN UTILITY PROGRAM (LBR)

14-1

14.1
14.2

INTRODUCTION TO LBR
LBR COMMAND STRING

14-1
14-1

CONTENTS
Page
14-2
14-3
14-4
14-4
14-4
14-5
14-5
14-10
14-10
14-11
14-12
14-13
14-15
14-16
14-17

14.6.9
14.6.10
14. 6. 11
14.6.12
14.6.13
14.6.14
14.7
14.8
14.9
14.9.1
14.9.2

DEFAULTS IN LBR FILE SPECIFIERS
LBR SWITCHES
FORMAT OF LIBRARY FILES
Library Header
Entry Point Table
Module Name Table
Module Header
LBR SWITCHES
Compress Switch (/CO)
Create Switch (/CR)
Delete Switch (/DE)
Default Switch (/DF)
Delete Global Switch (/DG)
Entry Point Switch (/EP)
Extract Switch (/EX)
Insert Switch (/IN) for Object and Macro
Libraries
List Switches (/LI, /LE, /FU)
Modify Header Switch (/MH)
Replace Switch (/RP)
Spool Switch (/SP)
Selective Search Switch (/SS)
Squeeze Switch (/SZ)
COMBINING LIBRARY FUNCTIONS
LBR RESTRICTIONS
LBR ERROR MESSAGES
Effect of Fatal Errors on Library Files
LBR Error Messages

FILE DUMP UTILITY (DMP)

15-1

15.1
15 .1.1
15 .1. 2
15.2
15.3
15.4

INTRODUCTION TO DMP
File Mode
Device Mode
DMP COMMAND STRING
DMP SWITCHES
DMP ERROR MESSAGES

15-1
15-1
15-1
15-2
15-2
15-6

14.3
14.4
14.5
14.5.1
14.5.2
14.5.3
14.5.4
14.6
14.6.1
14.6.2
14.6.3
14.6.4
14.6.5
14.6.6
14.6.7
14.6.8

CHAPTER

PART 7
CHAPTER

CHAPTER

14-18
14-20
14-21
14-22
14-27
14-28
14-29
14-31
14-32
14-32
14-33
14-33

PROGRAM MAINTENANCE UTILITIES

THE FILE COMPARE UTILITY (CMP)

16-1

16.1
16.2
16.2.1
16.2.2
16.2.3
16.3

CMP SWITCHES
FORMATS OF CMP OUTPUT FILES
Differences Format
Change Bar Format
SLP Command Input Format
CMP MESSAGES

16-2
16-4
16-4
16-5
16-6
16-6

SOURCE LANGUAGE INPUT PROGRAM (SLP)

17-1

17.1
17.1.1
17.1.2
17.1.3
17.1.4
17.2

SLP INPUT AND OUTPUT FILES
The Input File
Command Input
The SLP Listing File
The SLP Output File
HOW SLP PROCESSES FILES

17-2
17-2
17-2
17-3
17-3
17-4

ii I

CHS i iiiii! iii jL! I Ji!

1111

CONTENTS
Page
17.3
17.3.1
17.3.2
17.3.3
17.3.4
17.4
17.4.1
17.4.2
17.4.3

CHl~PTER

17.4.4
17.4.5
17.4.6
17.5
17.5.1
17.5.2

USING SLP
Specifying SLP Edit Commands
Entering SLP Edit Commands
Updating Source Files Using SLP
Creating Source Files Using SLP
CONTROLLING SLP
SLP Switches
Controlling the Audit Trail
Setting the Position and Length of the
Audit Trail
Changing the Value of the Audit Trail
Temporarily Suppressing the Audit Trail
Deleting the Audit Trail
SLP MESSAGES
SLP Information Message
SLP Error Messages

17-17
17-17
17-18
17-19
17-19
17-20
17-20

OBJECT MODULE PATCH UTILITY {PAT)

18-1

18.1
.18.2
18.2.1
18.2.2
18.2.3

18-2
18-3
18-3
18-3

18.3
18.3.1
18.3.2
18.3.3
18.3.4
18.3.5
18.3.6
18.3.7

SPECIFYING THE PAT COMMAND STRING
HOW PAT APPLIES UPDATES
The Input File
The Correction File
How PAT and the Task Builder Update
Object Modules
Determining and Validating the Contents
of a File
PATCH MESSAGES
Information Messages
Command Line Errors
File Specification Errors
Input/Output Errors
Errors in File Contents or Format
Internal Software Error
Storage Allocation Error

18-7
18-7
18-8
18-8
18-9
18-11
18-12
18-13
18-13

TASK/FILE PATCH PROGRAM {ZAP)

19-1

19.1
19.2
19.3
19.3.1
19.3.2

INVOKING AND TERMINATING ZAP
ZAP SWITCHES
ADDRESSING LOCATIONS IN A TASK IMAGE
Relocation Biases
ZAP Addressing Modes: Absolute and Task
Image
THE ZAP COMMAND LINE AND COMMAND LINE
ELEMENTS
ZAP Commands
ZAP Internal Registers
ZAP Arithmetic Operators
ZAP Command Line Element Separators
The Current Location Symbol
ZAP Command Line Location-Specifier
Formats
USING ZAP OPEN/CLOSE COMMANDS
Opening Locations in a Task Image File
Changing the Contents of a Location
Closing Task Image Locations

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

18.2.4

'-";

CHllPTER

19.4
19.4.1
19.4.2
19.4.3
19.4.4
19.4.5
19.4.6
19.5
19.5.1
19.5.2
19.5.3

17-5
17-5
17-7
17-10
17-14
17-15
17-15
17-16

18-4

19-3
19-5
19-5
19-6
19.-6
19-7
19-8
19-8
19-9
19-10
19-11
19-11

CONTENTS
Page
19.6
19.6.1
19.6.2
19.6.3
19.6.4
19.6.5
19.6.6
19.7

USING ZAP GENERAL-PURPOSE COMMANDS
Exit from ZAP
Compute an Off set and Store It in the
Quantity Register
Display the Branch and Jump Displacements
from the Current Location
Display the Value of an Expression
Verify the Contents of a Location
Set The Value For A Relocation Register
ZAP ERROR MESSAGES

19-13
19-13
19-13
19-14
19-15
19-15
19-16
19-16

APPENDIXES
APPENDIX A
A.l
A. 2

A. 3
A. 4·
A. 5
A. 6
A. 7
A. 8

A.9
A.10
A.11

A.12
A.13
A.14
A.15
A.16
A.17
A.18
A.19

APPENDIX B
B.l
B.1.1
B.1. 2

B. l. 3
B.l. 4

B.2
B.2.1
B.2.2
B.3
B.3.1

B.3.2
B.3.3
B.3.4

COMMANDS AND SWITCHES

A-1

INTRODUCTION
EDT COMMAND SUMMARY
EDI COMMAND SUMMARY
PIP COMMAND SUMMARY
FLX COMMAND SUMMARY
PRINT AND QUE COMMAND SUMMARY
QUEUE MANAGER COMMAND SUMMARY
FMT COMMAND SUMMARY
BAD COMMAND SUMMARY
BRU COMMAND SUMMARY
DSC COMMAND SUMMARY
PRESRV COMMAND SUMMARY
VFY COMMAND SUMMARY
LBR COMMAND SUMMARY
DMP COMMAND SUMMARY
CMP COMMAND SUMMARY
SLP COMMAND SUMMARY
PAT COMMAND SUMMARY
ZAP COMMAND SUMMARY

A-1
A-1
A-3
A-8
A-10
A-12
A-15
A-17
A-18
A-18
A-22
A-23
A-24
A-25
A-26
A-28
A-29
A-30
A-30

LBR, EDI AND DMP EXAMPLES

B-1

SAMPLE LISTINGS FOR LBR LIST SWITCHES
(OBJECT LIBRARY}
List Module Names
List Module Names and Full Module
Information
List Module Names, Full Module Information
and Module Entry Points (Global Symbols}
List Module Names and Module Entry Points
(Global Symbols}
SAMPLE LISTING FOR LBR LIST SWITCHES
(MACRO LIBRARY}
List Module Names
List Module Names and Full Module
Information
SAMPLE EDITING OPERATIONS
File Editing Sample
SAVE and UNSAVE Example
Use of Inunediate Macro Conunand
Use of Macro Conunands

B-1
B-1
B-2
B-3
B-7
B-13
B-13
B-14
B-15
B-16
B-20
B-23
B-24

~
1

xii

USS

CONTENTS
Page
B.4
B.4.1
B.4.2
B.4.3
B.4.4
APPENDIX C
C.l

c.2

C.3
C.4
APPENDIX D
D.l
D.1.1
D. l. 2

D.2
D.3
D.4

SAMPLE DMP LISTINGS
Use of /LB Switch
"Standard" Command Line
Dump Only the Header from SYSGEN.CMD
Use of /BA Switch

B-26
B-26
B-26
B-28
B-28

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

C-1
C-1
C-1
C-1
C-2

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR

D-1

HOW CRF PROCESSES DATA
MACR0-11/Task Builder Processing
CRF Processing
THE CRF SYMBOL TABLE FILE
THE CRF SEND PACKET
CRF ERROR MESSAGES

D-1
D-1
D-3
D-3
D-4
D-5

FIGURES
FIGURE

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

Input Line Number Sequencing
Results of Copy Command With and Without
/NV Specified
Sample Directories Before and After
Execution of /EN
Directory Listing Examples
Format of Protection Word
Use of the Purge Switch
Results of Rename Switch With and Without
/NV Specified
DOS-11 Directory Listings
RT-11 RK05 Cartridge Disk Directory Listing
Job Flag Page and File Flag Page
Standard Tape Format for Magnetic Tapes
Data Transfer for DSC Copy Operation
Data Transfer for DSC Compare Operation
Logical Tape Format
VFY Listing Sample Using the /LI Switch
General Format for Object and Macro Library
Files
Universal Library File Format
Contents of Library Header
Format of Entry Point Table Element
Format of Module Name Table Element
Module Header Format for Object and Macro
Libraries
Module Header Format for Universal Libraries
Sample Files Used in LBR Examples 1-4
Output Library File After Execution of
Example 1
Output Library File After Execution of
Example 2

xiii

2-13
4-10
4-17
4-23
4-26
4-28
4-30
5-9
5-11
6-6
10-26
11-2
11-3
12-5
13-9
14-5
14-6
14-7
14-8
14-8
14-8
14-9
14-24
14-25
14-25

CONTENTS
Page
FIGURES (Cont.)
FIGURE

14-11
14-12
14-13
14-14
17-1
18-1

c-1
D-1
D-2
D-3

Output Library File After Execution of
Example 3
Sample Files for Universal Library Replace
Example
Output Library File After Execution of
Universal Library Replace Example
MACRO Listing Before and After Running LBR
with /SZ Switch
Input Files and Output Files Used During SLP
Processing
Processing Steps Required to Update a
Module Using PAT
PRT Send Data Buffer Format
How MACR0-11, Task Builder, and CRF
Generate Cross-Reference Listings
Format of the CRF Symbol Table File
Format of the CRF SEND Packet

14-26
14-27
14-27
14-31
17-4
18-2
C-2
D-2
D-4
D-5

TABLES
TABLE

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

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

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

EDT File Specification Defaults
EDT Commands
Single Line Specifications
Variable Line Specifications
Compound Line Specifications
Inclusive Line Specifications
Command Options
Cursor Manipulation Subcommands
EDI Default File Specifications
Line-by-Line vs. Block Mode
Basic EDI Commands
EDI Setup Commands
EDI Locator Commands
EDI Text Modification and Manipulation
Commands
EDI Macro Commands
EDI Input/Output Commands
EDI Device Output Commands
EDI Close Operation Commands
PIP Default File Specifications
PIP Copy Command and Merge Subswitches
PIP Switches and Subswitches
List Switches
Response Choices for the Selective Delete
(/SD) Switch
PIP Error Codes
FLX Volume Format Switches
FLX Transfer Mode Switches
FLX Control Switches
Demonstration Forms Settings
Valid Ranges for Manual FMT Operations
FMT-Supported Devices
FMT Device Status

2-4
2-5
2-15
2-17
2-17
2-19
2-20
2-56
3-3
3-5
3-10
3-21
3-22
3-23
3-24
3-25
3-26
3-26
4-2
4-7
4-10
4-21
4-33
4-47
5-3
5-4
5-6
7-9
8-4
8-4
8-5

xiv

' ~•

Et&.!!

:;:

222 !iiliiiii!Si

I sq::

I !1$Jl2Uiiil4J411S

CONTENTS
Page
TABLES (Cont.}
TABLE

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

14-1
14-2
15-1
17-1
17-2
19-1
19-2
19-3
19-4

BAD Switches
Summary of BRO Command Qualifiers
Command Qualifiers That Perform Selective
Backup and Restore Operations
Command Qualifiers That Control Disk
Processing
Command Qualifiers That Control Tape
Processing
Command Qualifiers That Verify the Accuracy
of Data Transfers
Command Qualifiers That Provide Information
Initialization Qualifiers
Devices Supported by BRO
DSC-Supported Devices
DSC Device Status
DSC Switches and Options
Operating System Limits for DSC Block Factor
Commands Using DSC Rewind Switch
Stand-Alone DSC Switches
System-Generated CSR and Vector Addresses
General Error and I/O Error Message Codes
Legal Multifile/Volume Format in Logical
Tape
Summary of PRESRV Switches
Default Blocking Factors
CSR and Vector Addresses
VFY Default File Specifiers
VFY Functions and Switches
VFY Error Codes
Defaults in LBR File Specifiers
LBR Switches
DMP Switches
SLP Operators
SLP Switches
ZAP Arithmetic Operators
ZAP Command Line Element Separators
ZAP Open/Close Commands
ZAP General-Purpose Commands

9-2
10-2
10-4
10-5
10-6
10-6
10-7
10-8
10-9
11-5
11-6
11-8
11-14
11-17
11-20
11-21
11-27
12-8
12-10
12-17
12-22
13-3
13-4
13-14
14-2
14-3
15-2
17-9
17-16
19-7
19-7
19-9
19-14

11
"

.lllJ

!iiiiii iiii!iii i lli iii! . u:::

ill

iii

iii!i!i

:::=

I.I

ilii!

!.ti

iiiil

ii ili!il ii!! I i!iii:U I iiiill!lh I .

SUMMARY OF TECHNICAL CHANGES

Utilities can now be used from the DIGITAL Command Language (DCL)
environment (on RSX-llM-PLUS) as well as from the Monitor Console
Routine (MCR) environment (on RSX-llM and RSX-llM-PLUS).
The RSX-llM Print Spooler Task (PRT) is now called the Serial
Despooler Task. The new name distinguishes it from another task named
PRT that is part of the Queue Manager (see below).
The choice of
Serial Despooler or Queue Manager is made at system generation. All
switches or commands that despool output operate the same way with
either task.
The following lists the technical changes (such as new functionality,
new and revised switches, and new utilities) by utility, in the order
in which the utility appears in this manual.

Peripheral Interchange Program (PIP)

/CD - Creation Date (new) - allows the output file to take the
creation date of the input file rather than the date of transfer.
/EOF -· End-of-file (new) - specifies the end-of-file pointer
a file.

for

/FR - Free blocks (revised) - displays the amount of free space
on the specified volume and the largest contiguous free space on
that volume.
/LD - List Deleted files (new) - lists the files that

have

been

deletE~d.

/NM - No Message (new) - suppresses certain PIP error messages.
/TR - Truncate (new) - truncates file(s) to logical end-of-file.
/SD - Selective Delete (new) - deletes files selectively
prompting for user response before deleting them.

/SR - Shared Reading (new) - allows shared reading of a file that
has already been opened for writing by another user or task.
/SU - Supersede (revised) - allows you to copy one or more input
files to a file whose file name, file type, and version number
already exist in a User File Directory.

\......:'
xvii

File Transfer Program (FLX)
FLX now supports RK06/RK07, RLOl, and RX02 disks, and the
data cartridge. All devices are RT-11 compatible only.

TU58

/DNS:n - Density (new) - specifies the density
tape; n is 800 or 1600 bpi.

the

magnetic

/RW - Rewind (new) - rewinds the magnetic tape
the file transfer.

before

beginning

The Queue Manager
The Queue Manager is a collection of programs that provides for
the orderly processing of queued files. The Queue Manager allows
you to specify how, when, and where a file will be despooled.
You
can
also
display
information about the queue.
On
RSX-llM-PLUS only, the Queue Manager supports batch processing.
This manual describes the Queue Manager for RSX-llM V03.2 only.
For information on the Queue Manager for RSX-llM-PLUS, see the
RSX-llM-PLUS Batch and Queue Operations Manual.

Disk Volume Formatter (FMT)
FMT is a new utility that formats disk volumes (cartridges,
packs, and flexible disks) and, optionally, spawns the Bad Block
Locator Utility (BAD) if your system supports spawned tasks. FMT
allows you to format an entire volume or, where permitted,
individual tracks or sectors of a volume.

Bad Block Locator Utility (BAD)
/MAN - Manual (new) - prompts you for bad block information and
enters the blocks you specify in the bad block descriptor file.
/UP - Update (new) - allows you to update
the
bad
block
descriptor file by entering additional bad block information in
response to prompts.

Back-Up and Restore Utility (BRU)
BRU is a new fast back-up and restore utility that features:
•

Disk-to-tape back-up

•

Tape-to-disk restore

•

Disk-to-disk copying

•

Incremental back-up or restore

•

Copying from an unmounted disk

•

Copying to a disk that is either unmounted (BRU
the disk) or mounted (using the file system)

initializes

xviii

ll!i5 lid

I i!ii I i

II II I i i !i! p:

iii I I i Sil

i i JUI! ii

!iij iii! I ii Jiiii!2!U iiiill Sh 121 i!i i

Disk Save and Compress Program· (DSC)
DSC now supports TS04 magnetic tape drives.
Specifying a label name for an output volume is now permitted.
/BAD - Bad Block Locator Utility (revised) - agrees
syntax for the current version of the BAD utility.

with

the

/BL - Blocking Factor (new) - sets the blocking factor at which
DSC accesses blocks of data by enabling the user to change the
number of 512(10)-byte blocks in each of DSC's internal buffers.

Librarian Utility Program (LBR)
LBR can now create and maintain universal libraries.
can be installed as a module into a universal library.
/MH - Modify Header (new) - allows you to add
universal library header.

Any

information

file
to

File Dump Utility (DMP)
/FI - File Identification (new) - allows you to enter
number as a file identifier instead of a file name.
/HF - Header Format (new) - formats
header structures.
Other blocks
octal dump.

file

blocks that have Files-11
are output as an unformatted

/RW - Rewind (new) - issues a rewind command before it refers
a specific tape.

Source Language Input Program (SLP)
SLP and its audit trail switch (/AU) have been modified to
a maximum line-length of 132(10) characters.

allow

/CS - Checksum (new) - calculates the checksum value for the edit
commands.
/TR - Truncate (new) - reports lines that have been truncated
the audit trail.

xix

••1112•u•a•.1111•:•£•2•::•:m:m•s•,•£:•2!•::•:•1.11:::•--11!411m••:u••a•::•:•a•t•::::•,:s::•:•t:•::::••u•l!•&";•:••:;~::•••H•:•2•::•:•t•:a:•:•u•.•::•::•:a•:••:•:s•t;u•:::a•c.•Je•sa•:::•:

1
·"•

PREFACE

MANU.~L

OBJECTIVES

The RSX-11 Utilities Manual is a reference manual describing the
of
the 17 utilities supported by DIGITAL on the RSX-llM
RSX-llM-PLUS operating systems.

use
and

INTENDED AUDIENCE
This manual is for all users of the RSX-llM and RSX-llM-PLUS operating
systems.

STRUCTURE OF THIS DOCUMENT
Chapter l describes briefly each of the utilities, and explains how to
enter command lines and how to invoke and use the utilities.
Chapter 2 describes the DEC Standard Editor

(EDT).

Chapter 3 describes the Line Text Editor (EDI).
Chapter 4 describes the Peripheral Interchange Program (PIP).
Chapter 5 describes the File Transfer Program (FLX).
Chapter 6 describes the Print and Queue Utility (PR! and QUE).
Chapter 7 describes the Queue Manager.
Chapter 8 describes the Disk Volume Formatter (FMT).
Chapter 9 describes the Bad Block Locator Utility (BAD).
Chapter 10 describes the Back-Up and Restore Utility (BRU).
Chapter 11 describes the Disk Save and Compress Program (DSC).
Chapter 12 describes the Preservation Utility (PRESRV).
Chapter 13 describes the File Structure Verification Utility (VFY).
Chapter 14 describes the Librarian Utility Program (LBR).
Chapter 15 describes the File Dump Utility (DMP).
Chapter 16 describes the File Compare Program (CMP).

xxi

Chapter 17 describes the Source Language Input Program (SLP).
Chapter 18 describes the Object Module Patch Utility (PAT).
Chapter 19 describes the Task/File Patch Program (ZAP) •
Appendix A
utilities.

summary

the

commands

and

switches

for

the

Appendix B contains examples of the LBR, EDI, and DMP utilities.
Appendix c describes the RSX-llM
Summary of Technical Changes).

Serial

Despooler

Task

(see

the

Appendix D describes the Cross-Reference Processor (CRF).

ASSOCIATED DOCUMENTS

The RSX-llM/RSX-llS Documentation Directory and the RSX-llM-PLUS
Documentation
Directory
briefly
describe
the manuals in the
documentation set for each system. With them, you can find out where
to obtain more information.

--:,

',~,-,···,_
'~

The RSX-llM/M-PLUS MCR Operations Manual describes the Monitor Console
Routine (MCR) environment and its commands. The utilities can be
invoked from the MCR environment.
This manual provides background
information about MCR.
The RSX-llM~PLUS Command Language Manual describes the DIGITAL Command
Language routine (DCL) and its commands. The utilities can be invoked
from the DCL environment. This manual provides background information
about DCL.

CONVENTIONS USED IN THIS DOCUMENT

Use of Second Color
User (operator) input appears in red.
Use of Uppercase Characters
Uppercase characters in a command line indicate characters that must
be entered as they are shown. For example, utility switches must
always be entered as they are shown in format specifications.
An
exception is the <CR> symbol, which denotes a carriage return.
Use of Lowercase Characters
Lowercase letters, words, or symbols in
command
line
format
specifications represent variables for which the user substitutes
values. For example:
filename.filetype;version
The line represents the values that comprise a file specification;
values are substituted for each of these variables as appropriate.

xx i i

iii iii I

i I

JIJ!

iiiiiii

Command Abbreviations
Where short forms of commands are allowed, the shortest
form
acceptable is represented by uppercase characters. The following
example shows the minimum abbreviation allowed for the EDI WRITE
command:
Write
This notation means that W, WR, WRI, WRIT,
specifications for the WRITE command.

and

WRITE

are

all valid

Use iof Brackets ([])
Brackets denote optional entries in a specification.
Brackets also
are a part of the User File Directory portion of file specifications,
that is, [group,member]. When this portion of a file specification is
entered explicitly, brackets are required syntax elements; that is,
they do not indicate optional entries. Note that when an option is
entered, the brackets are not included in the command line.
~

Use 1of commas (,)
Commas are used as separators for command line parameters and indicate
positional entries on a command line.
Use iof At Sign (@)
The at sign (@) invokes an indirect command file.
The at sign
immediately precedes the file specification for the indirect command
:file:

@filename.filetype;version
Use iof Periods (.)
Periods in the file specification separate the file name and file
type.
When only the file name is used as the file specification, the
period need not be specified.
~

Use 1of Semicolons (;)
Semicolons in the file specification separate the file type from the
file version.
If the version is not specified, the semicolon may be
omitted from the file specification.
Use of Slashes (/)
Slashes precede switches in the file specification. When shown in the
command line format, they must be specified as shown.
Carriage Return
Command lines are terminated by typi~g the RETURN key (carriage
return) unless otherwise indicated in the text. Two forms used to
denote the RETURN key are <CR> and~.

xx i i i

i!j

I ii

Ji!!

r·

.,,J i!i lb$! h I

PART 1
INTRODUCTION

~iiia

!!bi! ill!!

iii

5 I I I

!SIS Ji

CHAPTER l
INTRODUCTION

The RSX-llM and RSX-llM-PLUS operating systems provide several kinds
of utilities for your use. Utilities are programs that allow you to
work with different kinds of files and the contents of those files,
and also with different kinds of media (such as disks, magnetic tapes,
and cassettes). The RSX-11 utility programs are listed and described
briefly in Section 1.1;
reference information for each utility is
presented in a separate chapter of this manual. Four appendixes are
also included to provide you with information related to the utilities
and to describe the Cross-Reference Processor (CRF), which is used
with the MACR0-11 assembler and the Task Builder.
In addition to summarizing the RSX-11 utilities, this introduction:

1.1

and

file

following

RSX-11

•

Describes how to enter RSX-11 command
specifications (Sections 1.2 and 1.3)

lines

•

Describes how to invoke utilities (Section 1.4)

RSX-11 UTILITY PROGRAMS

This manual provides reference information for
utilities:
Editing Utilities
DEC Editor (EDT)
Line Text Editor (EDI)
File Manipulation Utilities
Peripheral Interchange Program (PIP)
File Transfer Program (FLX)
File Spooling Utilities
Print and Queue Utility (PRI and QUE)
The Queue Manager
Volume Maintenance Utilities
Disk Volume Formatter (FMT)
Bad Block Locator Utility (BAD)
Bac~-Up and Restore Utility (BRU)
Disk Save and Compress Program {DSC)
Preservation Utility (PRESRV)
File Structure Verification Utility (VFY)
Programming Utilities
Librarian Utility Program (LBR)
File Dump Utility (DMP)

1-1

the

INTRODUCTION
Maintenance Utilities
File Compare Utility (CMP)
Source Language Input Program (SLP)
Object Module Patch Program (PAT)
Task/File Patch Program (ZAP)

P~ogram

The following sections briefly describe each utility.

1.1.1

Editing Utilities

DIGITAL supports two editing programs
text and source files.

for

creating

and

maintaining

1.1.1.l ,DEC Editor (EDT) - EDT is an interactive text editor that is
particularly useful for creating and maintaining text files. EDT has
two features that distinguish it from EDI:
•

Provides unlimited access to an entire file at one time,
making it unnecessary to work with most files in smaller
sections.
(However, a file can be too large for EDT.)

•

Provides character-mode editing
for
users
with
video
terminals. Character mode allows you to edit at the character
and word levels as well as at line level.

1.1.1.2 Line Text Editor (EDI) - EDI is a line-oriented,
editor used to create and maintain text and source files.

1.1.2

interactive

File Manipulation Utilities

With
these
DIGITAL provides two file manipulation utilities.
utilities,
you can, among other jobs, copy and spool files and
transfer files between volumes.

1.1.2.1 Peripheral Interchange Program (PIP) - PIP copies files and
performs several file control functions, such as concatenating,
renaming, spooling, listing, deleting, and unlocking.

1.1.2.2 File Transfer Program (FLX) - FLX is a file transfer and
format conversion program that transfers files between DOS-11, RT-11,
and Files-11 volumes, with some restrictions.

1.1.3

File Spooling Utilities

File spooling is handled differently on RSX-llM and RSX-llM-PLUS. For
RSX-llM-PLUS, see the RSX-llM-PLUS Batch and Queue Operations Manual.
RSX-llM systems can include either the Queue Manager or the Print
Spooler task, ••• PRT. PRT is described in Appendix c.

1-2

qaa

¢4

INTRODUCTION

\...I'

1.1.3.l Pribt Command and the Queue Manager (PRI and QUE) - This
chapter describes how the user interfaces with the Queue Manager.
With the Queue Manager, files can be spooled with the Print command.
Files spooled by tasks will also be queued automatically. You can set
many attributes of the job with the Print command or with the
QUE /MODIFY commands.
You can also display the queues and you can
alter, hold, or release a job after it has been placed in the queue.

1.1.3.2 The Queue Manager - This chapter describes the
commands for setting up and running the Queue Manager.

1.1.4

privileged

Volume Maintenance Utilities

Volume maintenance includes backing up files onto the volumes,
locating bad blocks on the volumes, and verifying the contents of the
volumes. DIGITAL provides six volume maintenance programs.

1.1.4.1 Disk Volume Formatter. (FMT) - FMT formats and
verifies
RP02/RP03, RP04, RPOS, RP06, RM02, and RM03 pack disks, RKOS, RK06,
and RK07 cartridge disks, and RX02 flexible disks. FMT can:
•

Write complete headers for each sector of a disk

•

Verify the headers it writes

•

Set the.density for RX02 flexible disks

•

Set the maximum error limit for a disk
processing when the limit is reached

•

Allow spawning of the Bad Block
system allows spawned tasks)

Locator

pack

and

Utility

terminate
(if

your

1.1~4.2
Bad Block Locator Utility (BAD) - BAD determines the number
and location of bad blocks on a volume (including magnetic tape). The
information gathered from running BAD on a volume can be used in
different ways when that volume is initialized.

l.lti4.3 Back-Up and Restore Utility (BRU) - BRU transfers files from
a
Files-11
volume to one or more back-up volumes (including
non-Files-11 volumes) and retrieves files from the back-up volume(s).
BRU is faster than DSC or PRESRV (described below) in most areas.
Also, BRU compresses data, the volumes do not have to be initialized,
and incremental back-ups are possible.

l.lu4.4 Disk Saye and Compress Program (DSC) - DSC copies Files-11
disk files to disk or tape and from DSC-created tape back to disk.
While copying the files, DSC also consolidates the data storage area
and writes files in contiguous blocks unless it encounters a bad
block. DSC can be run either online or stand-alone.

1-3

INTRODUCTION
stand-alone
Unlike DSC,

1.1.4.S Preservation Utility (PRESRV) - PRESRV is a
program that allows you to create copies of volumes.
PRESRV does not flag bad blocks or compress volumes.

1.1.4.6 File Structure Verification Utility (VFY) - VFY is a disk
verification program that verifies the consistency and validity of the
file structure on a Files-11 volume.

1.1.5

Programming Utilities

DIGITAL supports two programming utilities. The utilities
to work with library files and to examine file contents.

allow

l~l.5.1
Librarian Utility
Program
(LBR) - LBR
is
a
maintenance program that creates and modifies library files.
process macro, object, and universal libraries.

you

library
LBR can

1.1.5.2 File Dump Utility (DMP) - DMP is a file listing program that
allows you to examine file contents.
DMP also provides options that
control the format of the contents.

1.1.6

Program Maintenance Utilities

Program maintenance includes modifying, patching, and comparing files.
DIGITAL provides four program maintenance utilities.

1.1.6.l File Compare Utility (CMP) - CMP compares two text files,
record by record, and lists the differences between the two files.

1.1.6.2 Source Language Input Program (SLP) - SLP is a noninteractive
editing program that is used to maintain and audit source files.

1.1.6.3 Object Module Patch Program (PAT) - PAT is an object module
patch utility that updates, or patches, a relocatable binary object
module.

1.1.6.4 Task/File Patch Program (ZAP) - ZAP is a patch utility that
examines and directly modifies locations in a task image or data file.

1.2

ENTERING RSX-11 COMMAND LINES

The general format for entering command lines to RSX-11 utilities is:

f"'\

outfile, ••• outfile=infile, ••• infile<CR>

1-4

JUI! I .i lt..£111

Uiiii Ji i2 i L.i!i!iil I !ill

iii!

::: ;

!fall : . :::::::

iii!!!

\ .iii

I ii iii

iiiiii:S ifaiiiiS .iiiiiiiii IIr Ji

iil!iil Qii!llii ;:. I .JI&! ... ; i I III

INTRODUCTION
outfile and inf ile are file specifications for
input files to be operated on by the utility.

wherE~

the

output

and

This general format varies from utility to utility.
Some use the
entire command line and others use abbreviated forms of the command
line..
For some other utilities (such as BRU), the format is
different.
The syntax for each utility is described in the chapter
that describes that utility.
The utilities also accept indirect
command files containing command lines, as described in Section 1.4.4.

1.3

ENTERING FILE SPECIFICATIONS

In the command line format described in Section 1.2, outfile and
inf ile
represent
file
specifications.
The
number
of file
specifications you can enter depends on the utility.
The maximum
terminal line length depends on the size of the output buffer for your
terminal.
The format for entering file specifications is:
dev: [group,member]filename.filetype;version/sw ••• /subsw ••• <CR>
dev:
The physical device containing the desired volume.
The name
consists of two or three ASCII characters followed by an option~l
1-, 2-, or 3-digit octal unit number and a colon, for example,
DKO:, TTlOO:, or DBAO:. For RSX-llM, device names are limited to
two ASCII characters.
The default is the system device, SYO:.
[group, member]
The group number and member number associated with the User File
Directory (UFD) containing the desired file. Both numbers are
octal.
The default is the current UIC.
filename
The name of the file. RSX-11 file names can be null
of up to nine alphanumeric characters.

consist

There is no default.
filetype
The file type of the file. The file type provides a convenient
means for distinguishing different forms of the same file. For
example, a FORTRAN source program file might be named COMP.FTN
and the object file for the same program might be named COMP.OBJ.
File type and file name are separated by a period. The file type
can
be
zero
to three alphanumeric characters.
See the
RSX-llM/M-PLUS MCR Operations Manual for a list of standard file
types.
There is no default.

1-5

INTRODUCTION

version
An octal number that specifies different versions of the same
file.
For example, when a file is created, it is assigned a
version number of l by default. Thereafter, each time the file
is opened and unless you specify otherwise, the file system
creates a new file with the same file name and file type, but
with a version number incremented by 1. Version numbers can
range from O through 77777(8). Version number and file type are
separated by a semicolon.
The default is the latest version.
/sw
An ASCII name specifying a switch associated with a function to
be
executed
by the utility.
Most utility functions are
implemented by means of switches and subswitches.
Switches can
take one of three forms:
/sw
/-sw
/NOsw

invokes the switch function
negates the switch function
negates the switch function

Switches can take values in the form of ASCII strings and numeric
strings.
Most numeric values are octal by default. To specify a decimal
number, terminate the number with a decimal point. Values
preceded by a pound sign (#) are octal; this optional notation
provides explicit documentation of octal values. Any number can
be preceded by either a plus (+) or minus (-) sign; plus is the
default. Where explicit octal notation (#) is used, the sign, if
specified, must precede the pound sign.
The following are valid switch specifications:
/SW:27.:MAP:29.
/-SW
/NOSW:-#SO:SWITCH
/subsw
An ASCII name specifying a subswitch associated with a switch.
Subswitches provide a subset of functions related to the main
switch function. The following is an example of a subswitch
specification:
PIP> [200,200] *• *;*/PR/FO<CR>
In this example, /FO is a subswitch applied to the PR switch.
Syntactically, subswitches are identical to switches. The
for entering switches also apply for entering subswitches.

1.4

rules

INVOKING RSX-11 UTILITIES

You can invoke a utility from the Monitor Console Routine
(MCR) or
DIGITAL Command Language
(DCL) environment.
MCR is on both the
RSX-llM and RSX-llM-PLUS systems. DCL is on RSX-llM-PLUS only.
Both
MCR and DCL monitor your terminal activity; that is, they accept or
reject commands you enter and they display messages.
(For more

1-6

i i i i i!i i

!iii& ii

fl j

iii

221 Ji it

i&ih

INTRODUCTION
information on MCR, see the RSX-llM/M-PLUS MCR Operations Manual.
For
more information on DCL,
see the RSX-llM-PLUS Command Language
Manual.)
To determine whether you are using MCR or DCL,
type CTRL/C,
returns the explicit monitor prompt:
either MCR> or DCL>.

which

You invoke a utility and then work with it directly or by means of
indirect command files.
For systems in which all utilities are
installed, you can use any of three methods to invoke a
utility.
Sections 1.4.l and 1.4.2 describe these methods.
For systems in which
not all utilities are installed, you can use two methods for
invoking
a utility. Section 1.4.3 describes these methods.
Section 1.4.4 describes how to invoke a utility that can
commands from an indirect command file.
You invoke a utility when the RSX-llM/M-PLUS MCR or
routine prompts you.

then

RSX-llM-PLUS

DCL

For HSX-llM/M-PLUS, the MCR prompts are:
>

or (if you type CTRL/C first)

MCR>

For HSX-llM-PLUS, the DCL prompts are:
>

or (if you type CTRL/C first)

DCL>

DCL has commands that access utilities transparently to the user, that
is,
you do not have to explicitly specify the utility in order to use
it.
For example, the DCL command DIFFERENCES invokes the File Compare
Utility
(CMP);
and the DCL commands COPY~ DELETE, and PURGE invoke
the Peripheral Interchange Program (PIP).
This transparent access to
utilities covers most common instances of utility needs for DCL users.
If you use these DCL commands, the general format for specifying files
is:
>command[/qualifiers] infile outfile
DCL users can also use any MCR command forms by using the DCL MCR
command.
However,
if you are using DCL and you want to have full
access to the utilities as detailed in this manual,
you must invoke
the utility using the RUN command.
Sections 1.4.2.3 and 1.4.3
describe this procedure.

1.4.l

Installing Utilities on Your System

RSX-11 systems provided in distribution kits require the use of the
MCR RUN or DCL RUN command to invoke a utility.
Utilities must be
installed on your system before you can invoke a utility by its name.
To install utilities on your system, use the MCR command INSTALL or
the DCL command INSTALL.

1.4.2

Invoking Installed Utilities

You can use three primary methods for
invoking installed utilities.
Sections 1.4.2.1, 1.4.2.2, and 1.4.2.3 describe the methods.

1-7

INTRODUCTION
Invoking a Utility and Returning Control to MCR - Use one of
the following forms of command lines to invoke a utility to execute a
function and then return control directly to MCR:

1.4.2.l

>utilityname commandstring<CR>
or
MCR>utilityname commandstring<CR>
Using this method to invoke the utility allows you to enter a single
command for execution.
The utility is loaded, the command is
executed, and control returns to MCR.
(The method described in
Section 1.4.2.3 allows you to enter more than one command line because
control returns to the utility rather than to MCR.)
Two exceptions to this command format are the SLP and ZAP utilities.
You must first invoke these utilities and then enter the command lines
as described in Section 1.4.2.3.
(However, you can specify SLP
@indirectcommandfile; see Section 1.4.4.)

Invoking a Utility and Returning Control to DCL - Use the
following form of command line to invoke a utility to execute a
function and return control directly to DCL:

1.4.2.2

>command<CR>
Using this method to invoke the utility allows you to enter a single
command for execution.
The DCL command transparently accesses the
utility (see Section 1.4), the utility is loaded, the command is
executed, and control returns to DCL.
Two exceptions to this command format are the SLP and ZAP utilities.
You must first invoke these utilities and then enter the command lines
as described in Section 1.4.2.3.
(However, you can specify SLP
@indirectcommandfile; see Section 1.4.4.)

1.4.2.3

following
to it:
•

Invoking and Passing Control to a Utility - Use one of the
forms of command lines to invoke a utility and pass control

For MCR:
>utilityname<CR>

For DCL:
>RUN $utilityname<CR>
or
>MCR utilityname<CR>

These commands do not execute a function;
rather, they make a utility
available for execution of more than one function without returning
control to MCR or DCL. When invoked using one of these forms, the
utility responds with the prompt:
utilityname>

1-8

12!2 lits ii

a ;;

I 22 Ji t

Ji iii J liii!ib I lilfl

I at

INTRODUCTION

You may then enter the command string that specifies the function you
want executed. For example, if you are executing a PIP function, PIP
displays the prompt:
PIP>
To terminate the utility and return to MCR or DCL, type CTRL/Z.

Invoking Uninstalled Utilities

1.4.3

There are two methods for invoking uninstalled utilities.
These
methods are useful for smaller systems in which not all utilities are
installed. Both methods use either the MCR command RUN or the DCL
command RUN (depending on which monitor you are using) to invoke the
utility.
The first method
command:

invokes

the

utility

means

the

following

>RUN $utilityname<CR>
RUN is the MCR command RUN or the DCL command RUN;
the dollar sign
($) directs MCR or DCL to search the system directory for the utility
and to bring it into storage. On RSX-llM-PLUS, if the utility is not
in the system directory, MCR or DCL then searches in the library
directory and invokes the utility from there.
When the utility gains control, it displays the prompt:
utilityname>
Then it waits for you to enter a command line. The utility continues
to prompt you after each command is executed. To terminate the
utility, enter CTRL/Z.
The second method for invoking an uninstalled utility is the same as
the first except that it allows the utility to run under a UIC other
than the current UIC:
•

For MCR:
>RUN $utilityname/UIC=[group,member]<CR>

•

For DCL:
>RUN/UIC: [group,member] $utilityname<CR>

When the utility gains control, it prompts for
until you enter CTRL/Z.

1.4.4

functions

execute

Using Indirect Command Files

An indirect command file contains a sequence of command lines that can
be interpreted by a single task (usually a system-supplied task such
as a utility, the MACR0-11 assembler, or the Task Builder).
These
command lines appear in the indirect command file exactly as you would
enter them from your terminal.

1-9

INTRODUCTION

The commands contained in the indirect command file are executed when
the indirect command file is invoked.
For example, an indirect
command file might contain a series of PIP command lines.
To invoke
such an indirect command file, enter one of the following sets of
commands:

• For MCR:
>PIP @PIPCMDS.CMD<CR>

•

For DCL:
>RUN $PIP<CR>
PIP>@PIPCMDS<CR>
or
>MCR PIP @PIPCMDS<CR>
or
>MCR PIP<CR>
PIP>@PIPCMDS<CR>

In this example, PIP is invoked and accesses the file PIPCMDS.CMD,
which contains the sequence of PIP commands.
PIP executes the
commands and returns control to MCR, DCL, or PIP, depending on which
commands you use.
RSX-llM and RSX-llM-PLUS also allow you to use indirect command files
that contain MCR commands. The indirect command file contains both
the commands for invoking the utility and the commands that you want
the utility to execute. An indirect command file can contain command
lines for more than one utility.
You invoke the indirect command file by entering only the file
specification preceded by the at sign (@) in response to the MCR
prompt:
>@indirectcommandfile<CR>
The default values for indirect command file specifications are:
•

Device -- SYO:

•

[group,member] -- the current UIC

•

File name -- no default;

•

File type -- .CMD

•

Version -- the latest version of the file

must be specified

For complete information on how to use MCR indirect
refer to the RSX-llM/M-PLUS MCR Operations Manual.

command

files,

1-10

·11111

z Jii!ii!JJIJI

a!illil

I i i mt JIU I iiiiii

iii!

Ji!iii!li!i

::::

1ii .I I 42 !1111112$ l ii

I Ji

i!4 iii!!!

i!U!i I

¥#

ii\ ( kii I

PART 2
EDITING UTILITIES

CHAPTER 2
DEC EDITOR (EDT)

The DEC Editor (EDT) provides a means of creating and editing text
files.
While editing a file using EDT, you always have access to the
entire file. It is not necessary to deal with the file in pages or
buffers of fixed size.
Within EDT, there are two basic modes of operation:
Chara1cter Mc>de.

Command Mode

and

•

Command Mode allows you to usa EDT as a line-oriented editor.
In Command Mode, each line has a line number assigned by EDT.
By issuing commands that ref er to these numbers or to
character strings within a line, you can manipulate lines or
groups of lines.
You can also replace character strings
within a line or a group of lines. While in Command Mode, EDT
maintains a line pointer that points to one line, called the
current line.

•

Character Mode can only be used on video terminals. It allows
you to maneuver the cursor from character to character within
a line, or from line to line within a file. Using the cursor
as a pointer, you can manipulate individual characters, words,
lines, and groups of lines.

You gain access to Character Mode through the Change command, which
you issue at Command Mode. It is not possible to go directly from the
monitor to Character Mode without passing through Command Mode.
In
this respect, Character Mode can be viewed as one function of Command
Mode. However, you should treat Character Mode as a separate editor
from Command Mode.
Character Mode and Command Mode complement each
other to provide a complete editing system.
EDT offers several other features.

Among them:

•

Main and alternate text buffers. A buffer is a text storage
area.
The editing commands that you issue affect text in
buffers; they do not affect files directly. By default, EDT
maintains a single text buffer, called the main buffer.
However, you can create alternate buffers to contain text
which, for some reason, you wish to hold apart from the main
body of text. EDT commands allow you to move lines and groups
of lines back and forth between buffers.

•

Editing session backup commands. You can save the current
state of your editing session, including alternate buffer
contents and line pointer location, in a specially formatted
file.
At a later time, you can restore the state of your
editing session and take up exactly where you left off.
This
feature allows you to pause during a complicated editing
session and also to protect yourself against the accidental
loss of text generated during the session.
2-1

DEC EDITOR (EDT)
•

File and buffer I/O commands. While working in Command Mode,
you can create a file from a text buffer or part of a text
buffer. You can also copy the contents of an existing file
into a text buffer. This feature allows you to incorporate
material from several different files into one buffer during a
single editing session.

This chapter is organized into six sections:

2.1

•

Section 2.1 describes the procedures used to invoke
discusses EDT input and output files.

EDT,

•

Section 2.2 describes the elements of an EDT Command Mode
command string, provides a functionally organized list of EDT
commands, and explains range and option specification in EDT.

•

Section 2.3 lists Command Mode commands
provides a detailed description of each.

•

Section 2.4 contains a complete guide to EDT's Character Mode,
including the special Character Mode subcommands.

•

Section 2.5 contains a summary, in tabular form,
Command Mode commands.

the

•

Finally, Section 2.6 lists EDT error messages,
explanations and corrective actions for them.

and

provides

alphabetically,

and

EDT

INVOKING EDT

You can use most of the methods described in Chapter 1 to invoke EDT.
However, there is one major difference, which occurs if you invoke EDT
using the form
>utilityname commandstring
In this situation, EDT replies with its Command Mode prompt (*). Most
utilities, when invoked in this manner, perform the function specified
in the command string and return to the monitor.
To invoke EDT, follow one of these two sequences:
>EDT [outfile=] [infile]<RET>

*
or
>EDT<RET>
EDT> [outfile=] [infile]<RET>

*
outfile
Specifies the output file that EDT creates at the end of the
editing session.
When you exit EDT at the end of the session,
EDT creates the output file and fills it with the contents of the
main text buffer.
If you do not specify the output file, the output file name and
type default to the input file name and type. The output file
version number defaults to the version number of the input file,
plus one.

2-2

11
·"

iii iii421CU

iii!!!

I iii 2i!ii!i!i 2241! 4

i i .Ji! !Ziiiii

2iJ

I iii!

::4:

I;: 21 I tu

$! t ii 112!1 I

DEC EDITOR (EDT)

inf ile
Specifies the file that EDT uses as an input file; or, if infile
names a file that does not exist, sets the default file name and
type for the output file that EDT creates when you exit at the
end of the editing session. If you specify an existing input
file, EDT loads its main text buffer from that file.
If you do
not specify an input file, or specify an input file that does not
exist, EDT does not load the main text buffer; this means that
you begin the editing session with an empty buffer.

*
EDT's Command Mode prompt, indicating that EDT is in Command Mode
and ready to accept editing commands.

""1

Note that you do not have to specify either an input file or an output
file.
If you specify neither one, you begin the EDT session with an
empty main text buffer; furthermore, you must specify an output file
when exiting EDT if you wish to save the text generated during the
session. If you specify an output file only, you begin the session
with an empty buffer, but you will not need to specify the output file
when you exit. For example:
>EDT BILBO. TXT=

*
or
>EDT
EDT> BI I..BO. TXT=

*
both cause EDT to create the output file BILBO.TXT upon exit.
(This
example illustrates two principal methods of invoking EDT;
the two
methods are equivalent.) By default, the version number of the output
file is 1, if the file did not exist previously; or, if the file
already exists, n+l, where n is the highest current version number.
(See Table 2-1 for a complete list of EDT file specification
defaults.)
If you specify only the input file, there are two possibilities:
the
input file that you specify exists, or it does not exist. If the file
exists, EDT loads its main text buffer from the contents of the file
and also sets the default output file to match the input file, with a
version number one higher than that of the input file. If the input
file does not exist, EDT does not load the text buffer;
it simply
sets the default output file to match the input file.
For example:
>EDT FRODO.TXT

*
is equivalent to
>EDT FRODO.TXT=FRODO.TXT
if the file FRODO.TXT currently exists, and equivalent to
>EDT FRO DO. TXT=
if the file FRODO.TXT does not currently exist.

2-3

DEC EDITOR (EDT)

Table 2-1
EDT File Specification Defaults
Default Value
for Input File

Element

Default Value
for Output File 1

dev:

SYD:

Same as input device

[ufd]

UFD under which EDT
is currently running

Same as input [ufd]

filename

No default--must
be specified

Same as input file name

.filetype

Null

Same as input file type

;version

Latest version

Latest version+l

1 Output file defaults take effect only when no output file
is specified.
If you specify an output file name and type,
the output file device and UFD default to your current SYO:
and UFD, even if the device and/or UFD of the input file are
different.

In the normal situation of editing an existing file with the intention
of creating a new version of the file, you need only specify an input
fi~e.
If you are creating a new file, you also need only specify an
input file in order to set EDT's default output file. Note, however,
that EDT does not explicitly distinguish between these two situations;
you do not receive a message that tells you whether your input file
existed or not. It is possible to mistype the name of an existing
file and then begin your editing session in the belief that EDT has
loaded the text buffer. You usually find out that, the buffer is empty
as soon as you issue an editing command. In these cases, issue the
Quit command to leave EDT without creating an output file, and start
over again.

2.2

THE EDT COMMAND STRING

EDT makes changes to the text in response to commands that you enter
at your terminal.
You can issue commands only when you receive the
asterisk prompt that indicates Command Mode.
When you enter a command, you have to specify the action you want EDT
to take, and you have to specify the buffer and buffer portion you
want to affect. The buffer and buffer portion, taken together, are
called the range. Finally, you can modify the action of the command
by specifying an option or options to the command. Thus, the entire
command string can consist of:
•

Command name

•

Range specification

•

Options

•

Carriage return

2-4

,I!

.Iii!

SJ i!2

;;;

llL!li!ISJ

DEC EDITOR (EDT)

\.,i

The command name tells EDT which command to execute.
The range
specification tells EDT which buffer or buffer portion is to be
affected by the command. The options let you control the command
execution or specify actions for EDT to perform during_ execution.
In one command or another, all of the above command string components
are optional except the carriage return. Most commands provide a
default range specification if you do not specify a range explicitly.
If you do not specify a command explicitly, EDT defaults to the Type
command. However, EDT takes no action on any command string until you
terminate it with a carriage return.

2.2.JL

EDT Commands

EDT commands are English words that tell EDT what action to take.
In
each case, the full command name suggests the intended action.
However, you need not type the full command name;
you can type an
abbreviation for the command. Most of these command abbreviations are
one or two letters long.
Table 2-2 lists the commands by category; a brief description of each
category follows.
Section 2.3 contains complete descriptions of each
command, presented in alphabetical order.
Table 2-2
EDT Commands
Command

"'---

Section
Reference

Function

· - - - - ' - - - - - - t

Commands to Locate and Display Lines

Find

Repositions the
specified line

Type

Displays lines
terminal

line pointer to the
of the

text buffer on the

2.3.5
2.3.18

Commands to Input and Modify Text
Copy

Copies one or more lines from one buffer
location to another

2.3.2

Move

Moves one or more lines from one buffer
location to another, and deletes the
lines from the original location

2.3.8

Delete

Deletes one or
buffer

2.3.3

Insert

Inserts
buffer

the text

2.3.7

Replace

Deletes one or more lines, and replaces
the deleted lines with terminal input

2.3.11

Substitute

Changes characters
text buffer

2.3.17

terminal

lines from the text

input

within

into

lines of the

(continued on next page)
2-5

DEC EDITOR (EDT)

Table 2-2 (Cont.)
EDT Commands
Section
Reference

Function

Command

Commands to Leave EDT
Exit

Outputs the main text buffer contents to
a file, and then returns to the monitor

2.3.4

Quit

Returns to the monitor without creating
an output file

2.3.10

Commands to Back Up and Restore Editing Sessions
Save

Creates a file containing the contents of
all text buffers currently in use

2.3.14

Restore

Recreates all text buffer contents from a
temporary file created by
the
Save
command

2.3.13

Commands to Output To and Input From Files
Write

Creates a

file from text buffer contents

2.3.19

Creates a file from text buffer contents,
including the line numbers that
EDT
assigns

2.3.9

Include

Copies

file

into

text buffer

2.3.6

Commands to Establish and Display Parameters
Set

Specifies display and match criteria
be used by EDT for character searches

Show

Displays
current
match
criteria and buffer status

and

2.3.15

display

2.3.16

Miscellaneous Commands
Change

Invokes Character Mode

Resequence

Renumbers

XEQ
(Execute)

Executes
a group
EDT commands

the

2.3.1
the text buffer

2.3.12

of previously entered

2.3.20

lines in

2-6

;11111

iii!! iiilk!i I iiiiJ

iii

iii& ii !!Ii $ !i ISilii . it i i I

ijS JI iii

i!iiii!i

iii ii !iiii!

!iiiiiilll!i

iij! I I ii !iiil(.ii!llU

iii!! iii

i i! I iiiiiii

.!JQ I I ii 2J2lih Iii!$ 2J 2ii Uii!ZS::

DEC EDITOR (EDT)
Commands to Locate and Display Lines

The two commands in this group both cause EDT's line pointer to point
to a new line, but they do not modify any text. The Find command
positions the line pointer at the line that you specify.
You can
specify the line in any of a variety of ways, as explained in Section
2.2.2. The Type command also repositions the line pointer, but Type
additionally prints the line or lines you specify on your terminal.
Commands to Input and Modify Text

Use the commands in this group to modify existing text or create new
text.
All of these commands, with the exception of Substitute, work
on a line basis; that is, the smallest unit of text they can handle
is a complete line.
The Copy and Move commands are similar in that they direct EDT to move
a line or group of lines from one location to another. However, the
Copy command does not delete the lines from the original location,
while the Move command does.
Both the Copy and Move commands can
affect the position of the line pointer.
The Copy and Move operations can take place within a buffer or between
buffers;
in fact, it is possible to Copy or Move an entire buffer to
a specified location within another buffer. This is useful in cases
where you wish to take text from a file, modify it, and insert it into
your main text buffer. Typically, you might first use the Include
command to place the file into an alternate text buffer; then issue
various editing commands to modify the text in the alternate buffer;
and finally Copy the text to the desired location in the main buffer.
The Delete command allows you to delete a single line of text;
a
block of lines in a text buffer; all lines in a text buffer that
contain a specified character string; or an entire buffer.
The Insert and Replace commands are similar in that both allow you to
insert one or more lines of text in a text buffer. However, Replace
deletes the line or lines that you specify before you insert the text;
in other words, Replace replaces specified lines with text that you
supply. Insert and Replace are unusual in that they do not return
directly to the Command Mode asterisk prompt when you enter them.
Instead, there is no prompt; EDT waits for you to supply input.
You
then insert one or more lines of text until you type a <RET> at the
end of a line, followed by a <CTRL/Z>. At this point, EDT recognizes
that the insert is finished and returns the asterisk prompt; you can
then issue more Command Mode commands.
The Substitute command is the only Command Mode command that can
affect text within a line, instead of affecting the entire line. It
allows you to replace a specified character string with another
character string.
The strings need not match in length. You can
replace a string in a single line; in each of a group of lines;
or
in
all lines in a buffer.
If you wish, you can substitute
selectively: you specify a substitution to be made in all lines, and
EDT prompts you at each substitution opportunity, allowing you to
accept or reject each substitution as appropriate.
All the commands in this group can affect the position of the line
pointer as part of their function.
See the individual command
descriptions in Section 2.3 for detailed information.

2-7

DEC EDITOR (EDT)
Commands to Leave EDT
The Exit and Quit commands both direct EDT to terminate the current
editing session and return to the monitor. The Quit command does this
without creating an output file;
in other words, EDT does not output
the contents of its main text buffer into a file when you issue the
Quit command. Note, however, that you can direct EDT to create a file
during the editing session by issuing a Write command.
The Exit command terminates the editing session and does direct EDT to
output the contents of its main text buffer into an output file.
There are two ways to specify the name of this file:
•

When you first invoke EDT, you can specify the output file as
described in Section 2.1, that is, explicitly, or implicitly,
by specifying only the input file.

•

When you issue the Exit command to leave EDT, you can use the
/Rename option to specify the output file. The output file
specification that you provide with the /Rename
option
overrides the output file specification that you provide when
you invoke EDT. If you specify neither an input file nor an
output file when you invoke EDT, you must use the /Rename
option with the Exit command; otherwise, EDT cannot create an
output file because it has no output file specification
available.

Note that the Exit command automatically outputs the entire contents
of the main text buffer to the output file. You cannot specify that
an alternate text buffer be output instead of the main text buffer,
and you cannot specify that only a portion of the main buffer be
output. If you wish to create a file from a buffer other than the
main buffer, you can use the Write command.
The Write command
provides greater flexibility than the Exit command, because it allows
you to specify the buffer, and lines within the buffer, to be output.
Commands to Back Up and Restore Sessions
The Save and Restore commands work as a pair to provide a means of
backing up the work that you do during an editing session. You can
issue the Save command at any time during an editing session.
This
directs EDT to create a file containing the following information:
•

Contents of main and alternate text buffers

•

Current line pointer location

•

Input and/or output file specifications

•

EDT parameters

"""

...

·-ii

After EDT creates the file, you can continue your editing session as
if you had never paused to issue the command. If you want, you can
create an output file by issuing the Exit command.
However, at a
later time, you might want to recreate the editing session as it was
when you issued the Save command. To do this,
invoke EDT without
specifying either an input or an output file, and issue the Restore
command, specifying the same file that you specified when you issued
the Save command. EDT will reconstruct its buffers, its line pointer,
its file specifications, and its parameters from the contents of the
file that you specify. It will be as if you had never left the Saved
session.

2-8

iWS41

DEC EDITOR (EDT)
There are two principal uses for the Save and Restore commands:
•

In the middle of a long, complicated editing project involving
several text buffers, you can use the Save command to save all
text buffers. This allows you to spread your work over
several sessions.

•

If you fear the accidental loss of text that you have
generated during a session, you can use the Save command to
create a backup file at any time during the session.
Later,
after you have issued the Exit command and successfully
created the output file, you can delete these backup files.

The file that EDT creates as a result of a Save command is in a
special format and is useful only as input to EDT's Restore command.
For this reason, you should be sure to provide a file specification
with the Save command that is different from your output file
specification. Typically, you might want to reserve a special file
type to be used only with the Save command.
Commands to Output To and Input From Files
The Write and Print commands allow you to create an output file while
your editing session is in progress, in contrast to the Exit command,
which creates the output file and then returns control to the monitor.
Additionally, Write and Print offer you more flexibility in creating
an output file than the Exit command, since Write and Print allow you
to specify the text buffer and the lines within the buffer that you
want to output.
The Write and Print commands differ in that Print creates a file that
contains the line numbers assigned by EDT, while Write creates a file
without the line numbers. The format of a file created by the Write
command is identical to that of a file created by the Exit command.
The Include command allows you to bring the contents of a file into a
text buffer during an editing session. You can insert the file's
contents into a buffer that already contains text, or you can create a
new buffer to hold the file's contents.
The Include command is
particularly useful in situations where you need to prepare a file
using parts of several existing files~
Commands to Establish and Display Parameters
The Set and Show commands work as a pair to provide a means of
examining and altering several EDT parameters.
These parameters
include:
•

String match criteria. When searching for strings, EDT
require that both the characters and the cases of
characters match, or that only the characters match.
strings ABC and abc are a match in the second instance,
not in the first.

•

Case display criteria.
EDT can flag either upperor
lower-case characters with an apostrophe while displaying
text, or can display text "as is." If you are working at a
terminal that displays only upper-case characters, you may
want EDT to flag those characters that are upper case in the
text buffer,
in order to distinguish them from lower-case
characters.

2-9

can
the
The
but

DEC EDITOR (EDT)

•

Terminal type. When EDT is in Character Mode,
it requires
information about what kind of terminal is in use. Before
using Character Mode, you should be sure that the terminal
type is set correctly.

You can use the Set and Show commands to establish and examine each of
these
parameters.
In addition, you can use Show to display
information about the current state of EDT's text buffers and the
version of EDT in use.
Miscellaneous Commands

:he Change command invokes EDT's Character Mode.
You should only
issue it from a video terminal.
Although many Character Mode
operations are analogous to the Command Mode operations discussed in
this section, you should treat Character Mode as a separate editor.
Section 2.4 contains a complete description of Character Mode.
The Resequence command directs EDT to renumber the lines in a
specified text buffer.
EDT initially numbers the lines in a text
buffer by tens; that is, the first line is line 10, the second line
is line 20, and so on. Following any one of several text modification
commands, there may not be enough line numbers available to number all
the lines in an area of the buffer. For example, if you insert 15
lines between lines 10 and 20, there will be six lines without line
numbers.
By issuing a Resequence command, you can restore orderly
line numbering to the buffer.
The Resequence operation is available to several Command Mode commands
as an option. See the individual command descriptions in Section 2.3
for details.
The Execute command directs EDT to execute a series of commands that
you have previously placed in a text buffer. The Execute command is
particularly useful when you need to repeat a series of operations
several times.

2.2.2

Range Specification

When you issue an EDT editing command, you must also specify what
portion of the text buffer you wish that command to affect. The
portion of the buffer is called the range; the information that you
give EDT to allow it to find the range is called the range
specification.
A range can be as small as a single line, or as large as an entire
buffer.
It can consist of a contiguous group of lines within a
buffer, or all lines in a buffer that contain a certain string.
Most commands allow you to omit an explicit range specification.
These commands provide default range specifications when you do not
specify the range explicitly. The individual command descriptions in
Section 2.3 provide details.
A complete range specification contains two broad elements:
1.

A buffer specification. The buffer specification tells EDT
which buffer contains the range. The buffer can be the main
text buffer or one of the alternate text buffers.

2-10

•:s•••••u•:••••::•:•:•••1111•:::•:•••••••2•JJ•&&••••111;•2••1:•11!!•:1uu1::r••••••••••••••t•o•.:•s•n•

~111••JJ111:::e•:•:

DEC EDITOR (EDT)

A line specification. The line specification tells EDT which
lines within the buffer make up the range. There are four
general types of line specification:
•

Single line specifications.
Single line
allow you to specify one line of text.

specifications

•

Variable
line
specifications.
Variable
line
specifications allow you to specify an indeterminate
number of contiguous lines. Examples are: all lines in
the current text buffer, all lines between the current
line in the text buffer and the end of the buffer~

•

Compound
line
specifications.
Compound
line
specifications
combine
single
line
specifications,
operators, and integers to allow you to strictly define
groups of lines within the buffer. Examples are: all the
lines between two specified lines, a group consisting of a
specified number of lines following a specified line.

•

Inclusive
line
specifications.
Inclusive
line
specifications allow you to specify a string that each
line in the range must contain. The range consists of all
lines containing the specified string.

You can combine these different types of line specifications
to produce the desired effect. For example, by combining
compound and inclusive line specifications, you can specify a
range consisting of all lines between lines 70 and 180 that
contain the string ABC.
The remainder of this section discusses each of the elements that make
up a range specification. Also presented are three concepts common to
all forms of line specification:
•

The line pointer

•

Line numbers and line sequencing

•

String searches

2.2.2.1 Buffer Specification - When you invoke EDT, EDT creates a
text buffer, or storage area, called MAIN. If you specify the name of
an existing file as an input file when you invoke EDT, EDT copies the
contents of that file into the main text buffer. However, if you
specify the name of a new file, EDT creates MAIN with no data stored
in it. EDT performs the editing commands you issue on the contents of
the text buffer. Commands can add to or take away from the contents
of a buffer, move text from one buffer to another, or simply change
EDT's position within a buffer.
If you are working your way through an EDT text buffer and
the end of the buffer, EDT prints the following message:

you

reach

[EOB]
In effect, the [EOB] designation is a line that follows the final text
line of the buffer and tells you that you have passed that final line.
Since EDT inserts lines in front of a specified line, you must specify
the
[EOB] line if you want to insert text at the end of the buffer.
(See Section 2.2.2.5 for a discussion of
single
line
range
specifications, and Section 2.3.7 for a description of the Insert
command.)
2-11

DEC EDITOR (EDT)
EDT can create text buffers other than MAIN.
For example, you can
access other files using the Include command to copy their contents
into an alternate text buffer. EDT allows you to name the alternate
text buffers you use, and to make edits to the buffer contents in the
same way you edit the main text buffer.
There is no limit to the size of text buffers other than the limits of
the system that you are using; however, EDT does not assign line
numbers above 65535.
EDT creates a text buff er when you give it a name and then use the
buffer name as part of a command. Buffer names can be up to six
alphanumeric characters long. Each time you refer to a buffer, you
must precede the buffer name with either an equal sign (=) or a %BUF
notation. Thus, the following are all legal buffer references:
%BUF MAIN
=MAIN
%BUF ALTl
=AL Tl
%BUF lOSNEl
=lOSNEl
The first two examples above both refer to the main text buffer.
The number of text buffers available during an editing session is
determined when EDT is installed in your system. You will always be
able to use the main buffer and at least two alternate buffers, but
you should check with your system manager to find out the maximum
number of buffers available on your system.
EDT does not save the contents of any alternate buffers when you
terminate the editing session. You can save the contents of alternate
text buffers either by using the Write command to directly create a
file from the buffer, or by using the Move or Copy command to place
the alternate buffer's contents in the main text buffer.
EDT maintains an internal record of which buffer is currently in use.
This buffer is called the current buffer. A buffer becomes current
when an EDT command moves the line pointer into the buffer and leaves
it there.
(Section 2.2.2.2 describes the line pointer; the command
descriptions in Section 2.3 provide information on each command's
effect on the line pointer.) You can use the Show command (Section
2.3.16) to find qut which buffer is the current buffer.
The current buffer can serve as an implied range specifier.
Several
commands take the current buffer as their range argument if you do not
specify range explicitly.

2.2.2.2 The Line Pointer - The line pointer is an internal EDT
mechanism that keeps track of EDT's position within text buffers. As
you issue commands, EDT moves from line to line and from buffer to
buffer, using the line pointer to keep track of its position. The
line pointer does not point at any part of the line;
rather it
indicates an entire line. The current position of the line pointer
(the current line) can be displayed by typing a period followed by a
carriage return in response to the Command Level asterisk prompt. A
carriage return immediately following the asterisk prompt advances the
line pointer to the next line and displays that line.

2-12

•r•

iii l!ibi!!i!!!Liii!i!iiii

!!iii! l!!i!

Lili

I.ii

I iill! l:Uiiiltiiiii

iiiii

!iii

J I 114

ii I !ii!il&U!ii I L!!ii!iiijiilllii!iii!li

DEC EDITOR (EDT)

The position of the line pointer changes as EDT executes commands.
Each command's effect on the line pointer is documented in the
detailed command descriptions in Section 2.3.
The line pointer can serve as an implied range specifier.
Several
commands take the current line as the range argument if you do not
specify a range explicitly.
Line Numbers and Line Number Sequencing - EDT automatically
assigns a line number to each line in a text buffer to help you locate
and reference the lines in the buffer~ Line numbers are integers in
ascending order from l to 65535. They appear at the left margin of
the terminc1l display, separated from the text by a tab. Line numbers
can be changed or completely removed from the buffer, but are not part
of the text.

2.2.2.3

By default, EDT assigns 10 as the number of the first line and
increments by 10 for each additional line. Thus, the default system
line numbers are 10, 20, 30, 40, and so on. However, you can use the
Rese·quence command
(Section 2.3.12) to override this default and
specify the line numbers you want assigned.
Many commands that transpose, insert, or delete lines have an option,
/Sequence, that allows you to specify numbers for the transferred or
inserted text. Often the line numbers that result after one of these
commands have varying increments between them, and some lines may not
have numbers at all. If this occurs, you can use the Resequence
command to reassign uniform line number increments to all the lines in
you r bu ff er •
The Move, Replace, Include, and Insert commands, among others, put
lines into text buffers. The following example shows how EDT assigns
line numbers to new lines in buffers. If the lines in the buffer are
numbered 10, 20, 30, and so on up to 80, and if 12 lines are inserted
between lines 50 and 60, EDT assigns line numbers to the group as
shown in Figure 2-1.

PUTS \
2 NEW
3 LINES
4 OF
5 TEXT
6 INTO
7 A
8 TEXT
9 BUFFER
10 AND
11 HOW
12 IT
l

I-

10
20
30
40
50
60
70
80

THIS
EXAMPLE
SHOWS
HOW
EDT
HANDLES
LINE
NUMBERING

10
20
30
40
50
51
52
53
54
55

57
58
59

60
70
80

Lines Being
Inserted
Figure 2-1

Original
Buffer

THIS
EXAMPLE
SHOWS
HOW
EDT
PUTS
NEW
LINES
OF
TEXT
INTO
A

TEXT
BUFFER
AND
HOW
IT
HANDLES
LINE
NUMBERING

Resulting
Buff er

Input Line Number Sequencing

2-13

DEC EDITOR (EDT)

As Figure 2-1 shows, EDT numbers as many of the new lines as possible
without reassigning or changing any line numbers alr'eady in use. EDT
then puts the remaining lines in their proper position without
assigning them any numbers.
The Move, Replace, and Delete commands take lines out of text buffers.
When you use these commands, EDT removes the lines you specify, as
well as their line numbers, from the buffer. The numbers of the lines
that remain in the text buffer do not change. If a line number is no
longer assigned to a line, it is available for either EDT or you to
assign to a new line or to reassign to an existing line.

2.2.2.4 String Searches - Line numbers are not the only way for you
to specify a line in a buffer. You can direct EDT to search the
buffer contents for a string, which consists of a specific word or
combination of letters. When you specify such a character string, you
give EDT an object string to search for, and EDT examines the text
buffer looking for an equivalent or match string.
In its search, EDT normally examines the current line first to see if
it contains a match of the object string. If no match is found in the
current line, EDT then examines the next line, and the next, and so on
until it either finds a match or reaches the end of the buffer.
An exception to this arises if EDT located the current line through a
previous string search or through a Substitute command (see Section
2.3.17). In these cases, the search proceeds from a point in the line
immediately following the string that was searched or substituted for.
For example, you search for the string ILLUSTRATES,
the line:
120

and

EDT

locates

THIS LINE ILLUSTRATES STRING SEARCHES

You can now successfully search forward for STRING or SEARCHES, but
not for THIS, LINE, or ILLUSTRATES. You could, however, successfully
search backward for THIS, LINE, or ILLUSTRATES.
This mechanism allows you to search through a file for repeated
occurrences of a string without having to move the line pointer
forward each time you search.
Once you determine the object
perform, you must:

string

and

action

the

you

want

• Specify the string
• Dictate the direction of the search
• Determine what constitutes a match
EDT treats characters enclosed in apostrophes or quotation marks as
object strings. If you enclose a character or group of characters in
two apostrophes (') or two quotation marks ("), you direct EDT to
search for the first occurrence of an identical string of characters
(without the delimiters) contained in the text buffer.
Apostrophes
and quotation marks are the only character string delimiters that EOT
accepts as part of a range specification.
The way you specify the object string determines the direction of
EDT's search. If you enter "ABC", EDT searches from the current line
toward the bottom of the buffer looking for the first occurrence of

2-14

:::::

!. 121 I ii !ii22

DEC EDITOR (EDT)

ABC. If you precede the object string with a minus sign (-), that is,
-"ABC", EDT searches from the current line toward the top of the
buffer looking for the first occurrence of ABC.
EDT lets you specify whether or not a match occurs when the case of
the characters in the match string differs from the case of the
characters in the object string. For example, if you are searching
your text buffer for an occurrence of BASIC, do you want EDT to return
a match when it encounters the string basic?
The Set command (see Section 2.3.15) allows you to specify whether
match strings must correspond to the cases specified in the object
string. If you issue the Set Exact Case command, EDT returns as a
match only those strings that are identical in both case and content
to the object string. If you issue the Set Exact None command, EDT
returns any occurrence of the characters in the object string as a
match, regardless of case. Exact None is the default setting.

2.2.2.5 Single Line Specifications - Single
line
specifications
identify one line of a text buffer~ Single line specifications and
the lines they specify are listed in Table 2-3.
Square brackets
enclose optional portions of the specifications.
All of the single line specifications, with the exception of %L, can
be preceded by a buffer specification (see Section 2.2.2.1). A space
must separate the buffer specification from the line specification.
If you do not provide a buffer specification, EDT locates the single
line in the current text buffer.
Table 2-3
Single Line Specifications
Line
Specification
Line number nn

Meaning

(period)

The current line

"object string" or
'object string'

Starting with the current line, the first
line located that contains an acceptable
match of the object string

-"object string" or
1
- ' object string'

The first preceding line that contains
acceptable match of the object string

%BE [GIN]

The first line of the text buffer

%g [ND]

The [EOB] designation that follows
last line of the text buffer

%L [AST]

The line in a previous text buffer at
which the line pointer was positioned
when the command to enter the current
buffer was issued

\w·
2-15

the

DEC EDITOR (EDT)
Examples
*40

Locates and displays line 40 in the current text buffer. If line
currently does not exist, locates and displays the first line
with a number higher than 40.
40

Locates and displays line 130 in buffer X.
*'THIS HOUSE'
Locates and displays the first line of the
contains the string THIS HOUSE.

current

buffer

that

*=NEWBUF "FOR SALE"
Locates and displays the first line in buffer
the string FOR SALE.

NEWBUF

containing

*"FIND THIS STRING'
Missing string quote.
In this example, the string
returned an error message.

delimiters

were

mismatched;

EDT

Locates and displays the first line in the current text buffer.
* =MORDOR %E
Locates and displays the [EOB] designation that follows the
line in buffer MORDOR.

last

*=MAIN %L
Buffer Specification Conflict.
In this example, %L specifies a line in a previous text buffer.
Since %L already provides a text buffer specification, you cannot
explicitly specify a buffer with %L.
EDT returned an error
message indicating a conflict in buffer specifications.

2.2.2.6 Variable Line Specifications - Variable line specifications
identify an indeterminate number of lines in the text buffer. The
specifications and the lines they identify are listed in Table 2-4.
Square brackets enclose optional portions of the specifications.
As indicated in Table 2-4, a buffer specification used by itself is a
variable line specification, because it implies all lines in the
buffer. The remaining variable line specifications
(%BEF, %R, and

2-16

'"'Ill!

!JI

L LI

iiiill I

jiJI lhliL&S !J&!!IJU

21!

22!il:ZZ iiiiil i!()U:iQISi

DEC EDITOR (EDT)

%WH) imply the current text buffer; therefore, you cannot use them in
combination with an explicit buffer specification. If you attempt to
do so, EDT returns the error message:
Buffer Specification Conflict.
Table 2-4
Variable Line Specifications
Line
Specification

Meaning

=bufname or
%BUF[FER] bufname

All lines contained
bufname

in the text buffer

%BEF[ORE]

All lines in the current text
from
the first line in the
through the current line

%R[EST]

All lines in the current text buffer
from the current line through the last
line in the buffer

%WH [OLE]

All lines in the current text buffer

buffer
buffer

2.2.:2.7 Compound Line Specifications - Compound line specifications
identify a specific number of lines in the buffer and consist of
single line specifications, operators, and integers. Table 2-5 lists
the forms that compound line specifications may take. In the table,
sl stands for any of the single line specifications from Table 2-3.
Table 2-5
Compound Line Specifications
Line
Specification

Meaning

sl.l:sl2
or
sl.l %THRU sl2

The lines
between and
including the
first single line (sll) and the second
single line (sl2) where sll must precede
sl2

sl;i
or
sl %FOR i

The total number of lines specified by
the positive integer i that begins with
the line specified by the single line sl

sl.l,sl2,sl3, •••
or
sll %AND sl2 %AND sl3

The individual lines identified by
single line specifications

the

sl+i

The single line that is i lines
the single line specified by sl

after

sl·-i

The single line that is i lines
the single line specified by sl

before

2-17

DEC EDITOR (EDT)
Any of the compound line specifications can be preceded by a buffer
specification (see Section 2.2.2.1). A space must separate the buffer
specification from the line specification. If you do not provide a
buffer specification, EDT locates the lines in the current buffer.

•, , , "'I\,&~,·.:. , '_

Examples
*40:80
Locates and displays lines 40 through
buffer.

the

current

text

*•ALTl 'ABC' %THRU %E
Locates and displays the block of lines beginning with the first
line in buffer ALTl that contains the string ABC, and ending with
the last line in the buffer.
*150;20
Locates and displays a block of lines in the current text
that begins with line 150 and extends for 20 lines.

buffer

*•MAIN "STARTLINE" %FOR 35
Locates and displays a block of lines in the main text
that begins with the first line that contains the
STARTLINE and extends for 35 lines.

buffer
string

*%BUF GHORT 10,30,'KLATAAU',%E
Locates and displays the following lines from buffer GHORT: line
10, line 30, the first line following line 30 that contains the
string KLATAAU, and the [EOB] designation following the last line
of the buffer.
*"WORLD"+6
Locates and displays the sixth line following
contains the string WORLD in the current buffer.

the

line

that

2.2.2.8 Inclusive
Line
Specifications - The
inclusive
line
specifications identify lines of a buffer that contain a specific
string. You can find all lines in the buffer that contain the string,
or you can limit the lines that are checked for the string by
qualifying the inclusive line specification with
another
line
specification. Table 2-6 illustrates inclusive line specifications.
You can precede an inclusive line specification with a buffer
specification (see Section 2.2.2.1). A space must separate the buffer
specification from the line specification. If you do not include a
buffer specification, EDT locates the lines in the current buffer.

2-18

!~ II

& i!!!Ui!Jl

l&EL 22

I #I I

;: I I iii!ii! I :mm i

DEC

EDITOR (EDT)

Table 2-6
Inclusive Line Specifications
Line
Specification

Meaning

"string"

All lines in the text buff er that
contain acceptable matches of the
specified object string

ls %ALL 'string'
or
ls %ALL "string"

All lines that contain acceptable
string
matches of
the object
within the line specification ls

%.~LL

'string'

or
%.~LL

Exa11nples
*%ALL ' VAN GOGH'
Locates and displays all lines containing the string VAN GOGH
the current text buffer.

*%R %ALL 'MONET'
Locates and displays all lines in the current text buffer between
the current line and the end of the buffer that contain the
string MONET.
*=PAINT 50:300 %ALL 'PICASSO'
Locates and displays all lines between lines 50 and 300 of buffer
PAINT that contain the string PICASSO.

2.2.3

Options

Command line options either allow you to control the command execution
or specify actions that EDT is to take when the execution has been
completed. Each detailed command description in Section 2.3 includes
a description of each option that is allowed with the command. Table
2-7 shows options with their functions and associated commands.
Each option has an abbreviation that you can use instead of the full
option name.
Table 2-7 shows the abbreviation outside of brackets;
the remainder of the option name is inside the brackets.
When you
specify an option, you can use either the abbreviation or the full
name.

2-19

DEC EDITOR (EDT)
Table 2-7
Command Options

•

:---,,-,---!"'~~

Option

Meaning

Commands

/BR [ IEF]

Displays first ten
characters of lines
in range

Type,
Substitute

/FI [LE]

Specifies a file
that is either
accessed or created

Write, Save,
Include, Print,
Restore

/NL

Allows deletion of
line terminators

Change

/Q [UERY]

Prompts you to control execution of
command

Substitute,
Move, Copy,
Delete

/RE [NAME]

Specifies an output
file

Exit

/SEQ [ UENCE]

Specifies sequence
numbers

Include,
Insert, Copy,
Move, Replace,
Resequence

/-T[YPE]

Inhibits display of
lines affected by
the command

Substitute

/UN [SEQUENCED]

Inhibits renumbering
of lines

Include,
Insert, Copy
Move, Replace,
Resequence

2.3

DETAILED COMMAND DESCRIPTIONS

This section lists the EDT Command Mode commands alphabetically. Each
command description includes the format of the command, a description
of each of the options available with the command, examples of the
command in typical editing situations, and usage notes.
In the command format descriptions, the command abbreviation is shown
outside of brackets, while the remainder of the command name is shown
in brackets.
When issuing a command, you can use either the
abbreviation or the full command name. Thus,
REST[ORE]
in the format description for the Restore command indicates
can type either REST or RESTORE when you issue the command.

2-20

ilP•

Iii!& llZ!iii:S

!E!iiill

SZ!d& iii!!

Qi!

that

you

DEC EDITOR (EDT)

2.3.l

CHANGE

Use the Change command to invoke EDT's Character Mode.
contains a complete description of Character Mode.)

(Sect ion

2. 4

Format

c [HANGE] [range] [/NL]
CHANGE
Specifies the Change command.
range
Specifies the lines that you will be able to access while in
Character Mode.
If you do not specify a range, the entire
contents of the current text buffer can be accessed.
/NL
Specifies that, while in Character Mode, you can delete line
terminators such as form feeds, line feeds, and carriage returns.
Examples

c
This command invokes Character Mode and gives you access
of the current text buffer.

all

C =:X 50:200/NL

This command invokes Character Mode, giving you access to lines
50 through 200 of the text buffer named X. While in Character
Mode, you will be able to delete line terminators.

•

You can use the Change command only if you are using a video
display terminal.
You must use the Set Terminal command to
correctly establish your terminal type before you can edit in
Character Mode. Section 2.3.15 contains a description of the
Set command.

•

While in Character Mode, you only can edit the contents of the
range you specified in the Change command. If you want to
edit lines that are outside the range, you first must issue an
EX (Exit) subcommand and then re-enter the Change command
specifying the new range.

•

When you invoke Character Mode and specify the /NL option, EDT
treats end-of-line characters as single characters that may be
inserted or deleted.
EDT displays these characters
as
follows:

indicates an ASCII form feed
indicates an ASCII line feed
indicates an ASCII vertical tab character

2-21

DEC EDITOR (EDT)

Character Mode does not give any special representation to a
carriage return, but allows you to delete i~ as well~ When
you delete an end-of-line character, EDT concatenates the
following line to the line whose end-of-line character w~s
deleted.
If you attempt to delete a line terminator without having
specified the /NL option, EDT takes no action in response to
the subcommand you enter.
•

2.3.2

Two Character Mode subcommands, EX (Exit) and Quit, terminate
Character Mode.
Typing EX returns EDT to Command Level from
Character Mode. Typing EX does not terminate EDT if issued
from Character Mode.
Typing QUIT terminates both Character
Mode and EDT. The Quit subcommand does not create or update
any files.

COPY

Use the Copy command to transfer lines from one location
without deleting them from their original location.

another

Format

CO[PY] range-1 %TO range-2

[/Q[UERY]]
[/SEQ[UENCE] :initial-number: increment]
[/UN[SEQUENCED]]

COPY ••• %TO
Specifies the Copy command.
range-1
Specifies the lines that are to be copied. If you specify more
than one line in range-1, all the lines you specify are copied.
range-2
Specifies the line ahead of which the lines in range-1 are
copied.
If you specify more than one line in range-2, the lines
in range-1 are copied ahead of the first line in range-2.
/QUERY
Allows you to specify how each line in range-1 is to be treated.
Before EDT transfers each line, it prints the line and waits
until you type one of the following responses:
Response
Y or YES
N or NO
Q or QUIT
A or ALL

Result
Copies the line
Does not copy the line
Stops copying lines and displays the asterisk
prompt
Copies the remaining lines in the range
without printing them first

2-22

•:u

a; I I I

iii!

;

ft II ii

lh I !IL.ii)

DEC EDITOR (EDT)
/SEQUENCE: initial-number: increment
Assigns specific line numbers to the copied
lines.
The
initial-number argument specifies the number of the first line
that was copied, and the increment argument specifies the
increment between numbers. For example, /SEQ:lOO:lOO creates the
copied lines with line numbers of 100, 200, 300, 400, and so on.
/UNSJE:QUENCED
Causes EDT to copy the lines without assigning them line numbers.
Exam1ples

CO.:".MAC"%TO=X 40
This command copies all lines, beginning with the current line
and continuing through the first line containing .MAC, to a
position preceding line 40 in buffer X.
C0.;20 %TO %BE
This command copies 20 lines, starting with the current line,
the beginning of the current text buffer.

Notes
•

After a line or group of lines has been copied, EDT positions
the line pointer at the first line of the copied lines in
their new position preceding the first line in range-2.

•

You cannot overlap ranges:
any of the same lines.

range-! and range-2 cannot contain

If you do not use either the /Sequence or /Unsequenced option
• to
specify line numbers, EDT numbers the new lines in the
following manner:
If EDT can number the new lines by incrementing the
existing line numbers in steps of 10, it does so as long
as the resulting line numbers do not duplicate existing
line numbers or violate the ascending order of line
numbers.
If incrementing by 10 would result in an illegal line
number, EDT begins incrementing subsequent new lines in
steps of 1.
If incrementing the new lines in steps of l would result
in illegal or duplicate line numbers, EDT places all
further lines in the correct order, but does not assign
them any line numbers.

2.3.3

DELETE

Use the Delete command to delete lines from a text buffer.

2-23

DEC EDITOR (EDT)

Format
D[ELETE]

[range]

[/Q[UERY]]

DELETE
Specifies the Delete command.
range
Specifies a range of lines to be deleted.
a range, the current line is deleted.

If you do not

specify

/QUERY
Specifies that you want to control the Delete operation using EDT
prompts and responses. EDT prompts you by displaying the line to
be deleted;
you can then enter any one of the following
responses:
Response

Result

y or YES

Deletes the prompt line
Does not delete the prompt line
Stops deleting lines and returns to Command
Mode
Deletes all remaining lines in the range; does
not display the deleted lines

N or NO
Q or QUIT

A or ALL

·~

Examples
D 20:40

This command deletes lines 20 through
current text buffer.

40,

inclusive,

from

the

D %ALL 'ABC'/Q
This command finds all the lines in the current text buffer
containing the string ABC, displays each line, and then waits for
you to enter a Y, N, Q, or A response.
D =BUF2 %ALL '438'

This command deletes all lines containing
text buffer BUF2.

the

string

438

from

Notes
•

After a line or a group of lines has been deleted, EDT
positions the line pointer at the line immediately following
the last line deleted.

•

The /Query option allows you to delete specific lines at
random from the specified range of lines. After you delete
lines using the /Query option, EDT positions the line pointer
at the undeleted line nearest the beginning of the range.

•

If you enter
specification,
error message.

nonexistent
line
numbers
in
a
range
EDT rejects the specification and displays an
2-24

11
·•

Li . 2iii!6S ii ii!iiiil!I iii2£iiii!L I

i.i

iiilli!i

I 2 iiii;tll i i S

iiiii i U!fi &

4 ii 2ii2

:u ;cm

DEC EDITOR (EDT)
2.3.4

EXIT

Use the Exit command to terminate EDT, return control to
monitor, and save the contents of the main text buffer.

the

system

Format

EX [IT]

[/RE [NAME] : f ilespec]

EXIT'
Specifies the Exit command.
/RENAME: f i lespec
Specifies the output file to which the contents of the main text
buffer are written. The /Rename option overrides the output file
specified when EDT was invoked. Section 1.3 contains a complete
description of file specifications.

Example
EX/RE:SYS.MAC
This command causes EDT to write the contents of
buffer to the file SYS.MAC, then terminate.

the

main

text

NotE~S

•

The Exit command only saves the contents of the text buffer
named MAIN.
The contents of all other text buffers are lost
if they are not incorporated into MAIN or written to permanent
files through the Write command.
(See Section 2.3.19.)

•

The /Rename option allows you to specify an output file
whether or not an output file was originally specified in the
EDT invocation command.

2 .3 .• 5

FIND

Use the Find command to move the line pointer.
Format

F[IND] range
FIND
Specifies the Find command.

Specifies the line to which the line pointer is positioned.
If
you specify a range of more than one line, EDT positions the line
pointer at the first line in the range.

'-''
2-25

DEC EDITOR (EDT)

Examples
F = X 20
This command causes EDT to position
number 20 in text buffer X.

the

line

pointer

line

This command causes EDT to search upward and position the
pointer at the first line encountered that contains ABC.

line

F-'ABC'

F 20:40

This command causes EDT to position the line pointer at line
the first line of the range.

20,

Notes
•

2.3.6

The Find command does not generate any terminal output.

INCLUDE

Use the Include command to locate a file and to copy it
buffer.

into

text

Format
INC [ LUDE]

[range]

/FI: f ilespec
[/SEQ[UENCE]: initial-number: increment]
[/UN [SEQUENCED]]

INCLUDE
Specifies the Include command.
range
Specifies the line ahead of which the contents of the file are to
be inserted.
If you specify a range of more than one line, EDT
inserts the file ahead of the first line in the range. If you do
not specify a range, EDT inserts the file ahead of the current
line.
/FI:filespec
Specifies the file that is to be copied.
(See Section 1.3 for
complete description of file specifications~)

/SEQUENCE: initial-number: increment
Assigns specific line numbers to the included lines.
The
initial-number argument speciifes the number assigned to the
first line, and the increment argument specifies the increment
between numbers. For example, /SEQ:lOO:lOO creates the new lines
with line numbers of 100, 200, 300, 400, and so on.

2-26

II (.

.. I I

iii!

.t . I

::x

ill)!

I14££$JJU4 .ii U:

DEC EDITOR (EDT)

/UNSEQUENCED
Causes EDT to include the lines without assigning line numbers.
Examples

INC =ADD /FI:SYS.MAC
This command causes EDT to copy the contents of file SYS.MAC into
text buffer ADD. If ADD contains some data, EDT inserts the new
lines at the beginning of the buffer.
INC 'ABC' /SEQ:l00:2/FI:EDT.FTN
In this example, EDT first copies the contents of file EDT.FTN,
then inserts them before the next line in the current buffer that
contains the character string ABC, and finally numbers the new
lines as 100, 102, 104, 106, and so on.
Notes

•

After a file has been included into a text buffer, EDT
positions the line pointer at the first line following the
newly included text.

•

The Include command copies a file into your current text
buffer or to an alternate text buffer, allowing access to any
portion of that file during your editing session.
Once the
file is copied, you can use other EDT commands to manipulate
its contents.
For example, to access a portion of a file other than the
you are currently editing, perform the following steps:

•

file

into

one

Issue the Include command to copy the
alternate text buffer.

Issue the Move command to transfer the desired
portion of the file from the alternate text buffer to
the main buffer.

If more lines exist in the file being included than there are
line numbers available, EDT correctly inserts the extra lines
into the text buffer but does not assign them any line
numbers.
If you use the /Sequence option to specify line numbers that
conflict with other line numbers in the file, the new lines
are included without line numbers.
If you do not use either the /Sequence or /Unsequenced option
to specify line numbers, EDT numbers the new lines in the
following manner:
If EDT can number the new lines by incrementing the
existing line numbers in steps of 10, it does so as
long as the resulting line numbers do not duplicate
existing line numbers or violate the ascending order
of line numbers.
If incrementing by 10 would result in an illegal line
number, EDT begins incrementing subsequent new lines
in steps of l.
2-27

DEC EDITOR (EDT)
If incrementing the new lines in steps of 1 would
result in illegal or duplicate line numbers, EDT
places all further lines in the correct order, but
does not assign them any line numbers.

When you use the Include command to insert a file into a text
buffer that already contains some data, you may want to use
the Resequence command to establish uniform line number
increments throughout that buffer.

2.3.7

INSERT

Use the Insert command to place text you type at your terminal into
text buffer.

Format

I[NSERT]

[range]

[/SEQ[UENCE]: initial-number: increment]
[/UN [SEQUENCED]]

text
<CTRL/Z>
INSERT
Specifies the Insert command.
range
Specifies the line ahead of which the text you type is to be
inserted.
If you specify more than one line in the range, the
text is inserted ahead of the first line in the range. If you do
not specify a range, the text is inserted ahead of the current
line.

/SEQUENCE: initial-number: increment
Assigns specific line numbers to the newly inserted lines.
The
initial-number argument specifies the number assigned to the
first new line and the increment argument specifies the increment
between numbers.
For example, /SEQ:lOO:lOO creates new lines
with line numbers of 100, 200, 300, 400, and so on.

""'--·""':
_ _ :_
-

/UNSEQUENCED
Causes EDT to insert the new lines without
numbers.

assigning

them

line

last

line

text
Represents one or more complete lines of
must end with a carriage return.

text.

The

<CTRL/Z>
Causes EDT to stop accepting insert text and display the asterisk
prompt.

2-28

1 •:

lilt - iii

:;a

::um ; _::

DEC EDITOR (EDT)
Exan1ples

*I <RET>
LINE 1 <RET>
LINE 2 <RET>
LINE 3 <RET>
<C~rRL/Z >

*
This example illustrates the entire Insert command sequence. The
command, I, which is issued while EDT is displaying the asterisk
prompt, directs EDT to insert the text that follows above the
current line.
EDT then accepts three lines of input from the
terminal, inserting them above the current line.
Finally,
<CTRL/Z> causes EDT to terminate the insert and display the
asterisk prompt.
I

==B 40

This command causes EDT to insert all the lines you
of line 40 in buffer B.
I

II.

enter

ahead

OR II

This command causes EDT to insert the lines you enter ahead
the next line encountered that contains the string .OR.
I

This command causes EDT to insert the lines you enter at the end
of the buffer (that is, between the last line of the buffer and
the [EOB] designation).
NotE~S

•

After a line or group of lines has been inserted into a text
buffer, EDT positions the line pointer at the line following
the last inserted line.

•

When you issue an Insert command, EDT first positions the line
pointer ahead of the first line in the range. Without
prompting you, EDT begins to accept lines of text you enter at
the terminal.
When all the lines have been entered from the
terminal, terminate the insert by typing <CTRL/Z>.
EDT
inserts the lines you typed ahead of the first line in the
specified range.
It is important to remember that EDT does not prompt you for
input following an Insert command. Type the command line and
a carriage return, and then the lines you want to insert.

•

If you specify line numbers with the /Sequence option that
conflict with other line numbers in the file, EDT inserts the
new lines without line numbers.

2-29

DEC EDITOR (EDT)
If you do not use the /Sequence or /Unsequenced option to
specify line numbers, EDT numbers the new lines in the
following manner:

""'

If EDT can number the new lines by incrementing the
existing line numbers in steps of 10, it does so as
long as the resulting line numbers do not duplicate
existing line numbers or violate the ascending order
of line numbers.
If incrementing by 10 would result in an illegal line
number, EDT begins incrementing subsequent new lines
in steps of 1.
If incrementing the new lines in steps of 1 would
result in illegal or duplicate line numbers, EDT
places all further lines in the correct order, but
does not assign them any line numbers.
If you insert a large number of lines, you may want to enter a
Resequence command to uniformly renumber the lines in the
buffer.
(See Section 2.3.12.)
•

2.3.8

After you type all the lines to be inserted, type a line that
contains only <CTRL/Z>. This <CTRL/Z> causes EDT to terminate
the insert and display the asterisk prompt, allowing you to
enter further commands.

MOVE

Use the Move command to transfer lines from one location
and to delete them from their original location.

another

Format
M[OVE] range-1 %TO range-2

[/Q[UERY]]
[/SEQ[UENCE]: initial-number: increment]
[/UN[SEQUENCED]]

MOVE ••• %TO
Specifies the Move command.
range-1
Specifies the lines that are to be moved. If you specify more
than one line in range-1, all the lines you specify are moved.
range-2
Specifies the line ahead of which the lines in range-1 are moved.
If you specify more than one line in range-2, the lines in
range-1 are moved ahead of the first line in range-2.

2-30

Ji! I

::Si

a t.t

IJ JUI JUJ5$ J Ji41

DEC EDITOR (EDT)
/QUERY
Allows you to specify how each line in range-1 is to be treated.
Before EDT transfers each line, it prints the line and waits
until you type any one of the following responses:
Response
y or YES
N or NO
Q or QUIT

A or ALL

Result
Moves the line
Does not move the line
Stops moving lines and displays the asterisk
prompt
range
Moves the remaining lines in the
without printing them first

/SEQUENCE: initial-number: increment
Assigns specific line numbers to the transferred lines.
The
initial-number argument specifies the number of the first line
that was moved, and the increment argument specifies
the
increment between numbers. For example, /SEQ:lOO:lOO creates the
transferred lines with line numbers of 100, 200, 300, 400, and so
on.
/UNSEQUENCED
Causes EDT to transfer the
numbers.

lines

without

assigning

them

line

M.:"MAC" %TO =X 40
This command moves all lines, beginning with the current line and
continuing through the first line containing the string MAC, to a
position preceding line 40 in buffer X.
M.; 2 0 %TO %BE
This command moves 20 lines, starting with the current
the beginning of the current text buffer.

line,

This example appends the contents of text buffer X to the end
buffer MAIN.

M =X %TO =MAIN %E

Not.es
•

After a line or group of lines has been moved, EDT positions
the line pointer at the first line of the transferred lines in
their new position preceding the first line in range-2.

•

You cannot overlap ranges:
any of the same lines.

•

If you use the Move command to transfer a large number of
lines, you can issue a Resequence command to establish uniform
line number increments.
(See Section 2.3.12.)

range-1 and range-2 cannot contain

2-31

DEC EDITOR (EDT)

If you do not use either the /Sequence or /Unsequenced option
to specify line numbers, ~OT attempts to number the new lines
in the following manner:
If EDT can number the new lines by incrementing the
existing line numbers in steps of 10, it does so as
long as the resulting line numbers do not duplicate
existing line numbers or violate the ascending order
of line numbers.
If incrementing by 10 would result in an illegal line
number, EDT begins incrementing subsequent new lines
in steps of 1.
If incrementing the new lines in steps of 1 would
result in illegal or duplicate line numbers, EDT
places all further lines in the correct order, but
does not assign them any line numbers.

2.3.9

Use the Print command to create a file from the contents of a text
buffer.
The file that you create in this way contains as part of the
text the EDT line numbers assigned to the lines in the range.
Format

PR [INT]

[range] /FI : f ilespec

PRINT
Specifies the Print command.
range
Specifies the buffer contents that you want placed in the
permanent storage file you create.
If you do not specify a
range, EDT uses the entire current text buffer as the range.
/FI: f ilespec
Specifies the output file that you create. You must specify the
filespec using the /FI option. Section 1.3 contains a complete
description of file specifications.
Examples

PR =B 10:70/FI:INT.FOR
This command creates a file called INT.FOR that contains lines 10
through 70, inclusive, of buffer B.
PR =MAIN/FI:SY.MAC
This command creates a file called SY.MAC from the contents of
the main text buffer. The file SY.MAC has as part of the text of
the file the line numbers that existed in the MAIN buffer at the
time the Print command was issued.

2-32

. . . . .,~,...............,;:...................................................
,;a...........,.a•:•::. .::•s•;. . . . .11. .;•s:•:•:•122•:•11:•:::. .

DEC EDITOR (EDT)
Note1s

•

2.3.10

EDT does not reposition the line
command generates on output file.

pointer

after

the

QUIT

Use the Quit command to terminate EDT and to return control to
system monitor without saving the contents of any text buffers.

the

Format

QUIT
QUI'l'
Specifies the Quit command.
Example

QUIT
This command erases all text buffer contents and returns
to the system monitor.

control

NotE!S

•

The Quit command does not modify any buffers.
It does not
write out the contents of the main buffer or any other buffer,
nor does it generate any files.

you invoke EDT with only an input file, you must either
• If
issue a Quit command to return to the system monitor or issue
an Exit command with the /Rename option to specify an output
file.
You can also use the Write command to generate a file
from the contents of the main text buffer or an alternate text
buffer.
See Section 2.3.19 for a description of the Write
command.

'-')

If you use the Write command to generate a file before you
issue the Quit command, that file is not affected by Quit or
any other subsequent EDT command.
Quit command is especially useful if you have made an
• The
error that results in the loss of all or part of a buffer you
are editing. If you make a mistake that results in a loss of
your buffer's contents, issuing a Quit command negates all
changes made since EDT was invoked.

2-33

DEC EDITOR (EDT)

2.3.11

REPLACE

Use the Replace command to delete one or more lines of text in a
buffer and replace them with new lines.

text

Format

R [EPLACE]

[range]

[/SEQ[UENCE]: initial-number: increment]
[/UN [ SEQUENCED] ]

text
<CTRL/Z>
REPLACE
Specifies the Replace command.
range
Specifies those lines that are to be deleted.
The replacement
lines begin with the first line in the range. If you do not
specify a range, the Replace command deletes the current line and
inserts the replacement lines in its place.

/SEQUENCE: initial-number: increment
Assigns specific line numbers to the replacement lines.
The
initial-number argument specifies the number of the first line,
and the increment argument specifies the increment between
numbers.
For example, /SEQ:lOO:lOO creates replacement lines
with line numbers of 100, 200, 300, 400, and so on.
/UNSEQUENCED
Causes EDT to create the replacement lines without assigning them
line numbers.
text
Represents one or more complete lines of
must end with a carriage return.

text.

The

last

line

display

the

<CTRL/Z>
Causes EDT to stop accepting replacement
asterisk prompt.

text

and

Examples

R <RET>
GOTO 40 <RET>
<CTRL/Z>
This example deletes the current line, replaces it with
and terminates the replacement text with <CTRL/Z>.

GOTO 40,

R 'ABC'+20 <RET>
IF XYZ THEN DEF <RET>
<CTRL/Z>
This example deletes the twentieth line after
the
first
occurrence of ABC, replaces it with the "IF ••• THEN ••• " statement,
and terminates the replacement text with <CTRL/Z>.

2-34

··!11111

ill

::::

;u:

I ii

t; Ii I Jlillll!l iii i

DEC EDITOR (EDT)
Note1s

a line or group of lines has been replaced, EDT
• After
positions the line pointer at the line following the last
replacement line.
•

If you replace a single line with several lines, you can issue
a Resequence command to assign uniform line number increments
to all lines in the text buffer.
(See Section 2.3.12).

•

If you specify line numbers with the /Sequence option that
conflict with other line numbers in the file, EDT inserts the
replacement lines without line numbers.
If you do not use the /Sequence or /Unsequenced option to
specify line numbers, EDT numbers the new lines in the
following manner:
If EDT can number the new lines by incrementing the
existing line numbers in steps of 10, it does so as
long as the resulting line numbers do not duplicate
existing line numbers or violate the ascending order
of line numbers.
If incrementing by 10 would result in an illegal line
number, EDT begins incrementing subsequent new lines
in steps of 1.
If incrementing the new lines in steps of 1 would
result in illegal or duplicate line numbers, EDT
places all further lines in the correct order, but
does not assign them any line numbers.

•

When you issue the Replace command, EDT does not prompt you to
begin entering the replacement lines of text. You should type
the Replace command line, a carriage return, and then type the
lines you want to insert.
After you type the replacement lines, type a line that
contains only <CTRL/Z>. <CTRL/Z> causes EDT to terminate the
replacement and display the asterisk prompt, allowing you to
issue further commands.

2.3~12

RESEQUENCE

Use the Resequence command to assign new line numbers to the lines
text: buffers.

For111at

RES[E(JUENCE]

[range]

[/SEQ[UENCE]: initial-number: increment]
[/UN [SEQUENCED]]

RESgQUENCE
Specifies the Resequence command.
ran9e
Specifies the lines and text buffer to be renumbered. If you do
not specify a range, EDT resequences all lines in the current
text buffer.

2-35

DEC EDITOR (EDT)
/SEQUENCE: initial-number: increment
Assigns specific line numbers to the lines in the range.
The
initial-number argument specifies the number of the first line in
the range, and the increment argument specifies the increment
between numbers.
For example, /SEQ:lOO:lOO renumbers the range
with line numbers of 100, 200, 300, 400, and so on.

i'"""

/UNSEQUENCED
Causes EDT to remove line numbers from the range.
Examples
RES
This command causes EDT to renumber
lines at 10, 20, 30, and so on.

the

current

text

buffer's

RES =A /SEQ:l:l
This command causes EDT to renumber the lines of buffer A
2, 3, 4, and so on.

•

After a buffer or a group of lines has been resequenced,
positions the line pointer at the first line that
resequenced.

EDT
was

•

If you d~ not specify the /Sequence or /Unsequenc~d option,
EDT assigns to the lines in the text buffer the default line
numbers 10, 20, 30, and so on.

•

As a general practice, resequence the entire text buffer
instead of a portion of it. This ensures that uniform line
number increments exist for your convenience.

Notes

When you renumber only ~art of the text buffer, none of the
line numbers you assign can match those in the part of the
buffer not being renumbered. If you specify a line number for
the resequenced range that is less than the line numbers
before it, all lines in the range are written without numbers.
The highest sequence number that you can use is 65535; the
lowest is 1.
•

After you insert or delete a large number of lines, the line
numbers of the remaining lines may be difficult to work with.
Use the Resequence command to restore uniform line number
increments to the text buffer.

•

Use the Type command (Section 2.3.18) to display on your
terminal the line numbers that are currently assigned to the
contents of the buffer. Use the Print command (Section 2.3.9)
to create a file that contains the new line numbers as part of
the text.

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

2-36

Uii! ill

lit

iiiti

lit

iiiiiiii

Iii

;::: :::: itiilll!t :a:12!!iili! : : bm lift !iiii

::u ;::u: !!1!4 m::m:

DEC EDITOR (EDT)
2 • 3 • 13

RES'tORE

Use the Restore command first to locate a file created by a save
command and then to use the file to recreate the status of all files
and the contents of all text buffers as they were preserved in the
file ..

Format
REST[ORE] /FI:filespec
RESTORE
Specifies the Restore command.
/FI: :file spec
Specifies the file that was created by previously issuing a Save
command.
That file, when accessed by the Restore command,
recreates the contents of all text buffers in use at the time the
Save command was entered.
EDT does not provide defaults for either the file name or the
file type in the Restore and Save commands. See Section 1.3 for
a complete description of file specifications.

Exam]Ple
»EDT <RET>
EDT> <RET>
*REST /FI:TXT.SAV

*
This example illustrates the sequence you must follow if you want
to use the Restore command. Restore must be the first command
you issue after invoking EDT without specifying either an input
or an output file. EDT then locates the file TXT.SAV, and uses
that file to recreate the contents of all text buffers in use at
the time the Save command created TXT.SAV.

Notes
•

In ord~r to issue a Restore command, Restore must be the first
command that you issue after you invoke EDT. Therefore you
must:
l.

Invoke EDT without
output file.

specifying

either

Have all text buffers empty.

Issue the Restore command, and
created by a Save command in
session.

input

specify the file
a previous editing

After your text buffer contents have been restored, EDT
positions the line pointer at the line that was the current
line when the Save command created the input file.

2-37

DEC EDITOR (EDT)
2.3.14

SAVE

Use the Save command to preserve in a file that you specify the
contents of the text buffers and the status of all files you use
during your editing session. You can later use the Restore command to
recreate your editing session as it was when you issued the Save
command.
Format
SA[VE] /FI:filespec
SAVE
Specifies the Save command.
/FI:filespec
Specifies the file that EDT creates.
This file contains the
current status of all the buffers in use. You must use the /FI
option to specify the name of the file.
EDT does not provide defaults for either the file name or the
file type in the Restore and Save commands. See Section 1.3 for
a complete description of file specifications.
Example
SA /FI:TXT.SAV
This command saves all text buffer contents by creating the file
TXT.SAV.
The file TXT.SAV contains the contents of all the text
buffers in use at the time the Save command was issued. You can
use the TXT.SAV file only by issuing a Restore command to
recreate the contents of the text buffers.
Notes
•

EDT does not reposition the line pointer after the Save
command generates the file, nor does the Save cqmmand alter
the contents of text buffers. After a Save command, you can
continue to edit as if you had never issued the command.

•

The file created by a Save command is in a special format and
is useful only as input to the Restore command (see Section
2.3.13). Do not try to use the file created by a Save command
as a normal EDT input file.

2.3.15

SET

Use the Set command to establish criteria that are used by other EDT
commands to flag upper-case or lower-case characters, to determine if
two strings match, and to establish the correct parameters for the
terminal you use.

2-38

1111111111

iii!! &;: :221
I.

DEC EDITOR (EDT)
Format
CA[SE]
EXACT
SET

TE[RMINAL]

[UPPER~
LOWER
NONE

CCANONE[SE]]
HCPY
VTOS
VTSO
VT52
VTSS
VT61
LA30
LA36

SET
Specifies the Set command.
~

CASB
Specifies that characters of the case you specify, either Upper,
Lower, or None, are to be preceded by an apostrophe when they are
displayed on the terminal.
If you specify Case Upper, all
upper-case characters are flagged. If you specify Case Lower,
all lower-case characters are flagged. If you specify Case None
(the default setting), no characters are flagged, and any
previously entered Case specifications are terminated. EDT does
not flag characters while in Character Mode.

"'-';

EXACT
Specifies whether object string matches must conform to the cases
specified in the object string.
If Exact Case is specified,
match strings must conform to the cases of characters specified
in the object string.
If Exact None (the default setting) is
specified, only the characters must match; case matches are not
required.
TERMINAL
Specifies the terminal type that you are using.
The valid
terminal types are listed above in the command format. Enter the
terminal type that corresponds to the terminal you are using.
The default setting for the Terminal parameter is established
when EDT is installed.

Exa1nples
*SET CASE LOWER <RET>
*40 <RET>
40 IF ABC 'L'T 'X'Y'Z GOTO 'X'X'X
Text of line 40 actually exists in the buffer as:
40 IF ABC lt xyz GOTO xxx
This example illustrates that Set Case Lower
lower-case characters with a leading apostrophe.

2-39

displays

all

DEC EDITOR (EDT)
*SET EXACT CASE <RET>
*'ABC' <RET>
No such line found.
*SET EXACT NONE <RET>
*'ABC'<RET>
130 IF abc, GOTO x

·~
J

This example illustrates that, when Set Exact
specified, EDT accepts only exact case matches.

Case

has

1~'

been

Notes
Using the Set Case Command
•

The Set Case Upper and Set Case Lower commands do not alter
the characters in the text buffer; they only change the way
the characters are displayed on the terminal.
You should generally use the Set Case Lower command when you
have
an
upper-case-only terminal.
All characters that
subsequently appear with a preceding apostrophe are lower-case
characters.
Lower-case characters cannot be changed or
inse~ted from an upper-case-only terminal,
but they can be
deleted.

•

EDT does not flag characters while in Character Mode.
You
therefore cannot distinguish between upper-case and lower-case
while in Character Mode if you have an upper-case-only
terminal.

Using the Set Exact Command
•

The Set Exact commands do not cause any changes in the text
buffer.
These commands only control the criteria that EDT
uses to evaluate a string match.

Using the Set Terminal Command
•

Setting the correct terminal type is mandatory only when you
edit in Character Mode. Generally, however, you should always
have the correct terminal type set.
The default setting for the Terminal parameter is established
when EDT is installed in the system. Use the Show Terminal
command (Section 2.3.16) to find out what default terminal
type is in effect, then use the Set Terminal command to alter
the Terminal parameter if necessary.

2.3.16

SHOW

Use the Show command to display buffer and
software
version
information, and EDT parameters established by the Set command.
Format
SH [OW]

BU [FFERS]
CA [SE]
EXACT
[ TE[RMINAL]
VE [RS ION]

2-40

1
· '•

••••:•t••:•u •••••••••••••:•:•••:•nz•:•iiii•ii!•t•u••::•: ••:•ii!i•l•t1•t•t:,•::;•:111.. •

•••t1:•2:•:::•:1:1u•••:•:•:::•::::••:.•:

•t111

:•::1111;

DEC EDITOR (EDT)

SHOW
SpeciUes the Show command.
BUFF'ERS
Specifies that EDT display the name and summarized contents of
each buffer you have used since invoking EDT, and indicate the
current buffer with a leading equal sign (=).
CASE:
Specifies that EDT display the Case parameter currently in effect
as established by the Set command.
EXACT
Specifies that EDT display the Exact parameter
effect as established by the Set command.

currently

Specifies that EDT display the version number of the current
program.

EDT

TERMINAL
Specifies that EDT display the Terminal parameter
effect as established by the Set command.
VERSION

Examples

*SH CASE
UPPER

.'
·~I

*
This example shows that the Case Upper parameter is in effect.
*SH BU
MAIN
A

BUF2
=BUF

14 LINES
0 LINES
143 LINES
390 LINES

*
This example display~ the buffers referenced since EDT was
invoked, the order in which they were created, and a summary of
their contents. The current buffer is shown with a leading equal
sign (=).
Notes
•

The Show command, except for the Buffers and Version options,
displays only those options that have been specified, or that
can be specified, through the Set command (see Section
2.3.15).

2-41

DEC EDITOR (EDT)
2.3.17

SUBSTITUTE

Use the Substitute command to change characters within
text buff er.

lines

the

Format
S[UBSTITUTE]/object-string/replacement-string/[range]

[ /BR [ IE F ] ] [ : n ]
[/Q[UERY]]
[/-T[YPE]]

or
S[UBSTITUTE] N[EXT]
SUBSTITUTE
Specifies the Substitute command.

I
Represents a string delimiter. String delimiters can be slashes
or any other printing, nonalphanumeric character. The delimiters
in a given Substitute command must match each other.
object-string
Specifies the characters in the text buffer that you want to
locate and to change. See Section 2.2.2.4 for more information
about object strings.
replacement-string
Specifies the characters with
object string characters.

which

you

want

replace

the

range
Specifies the range of lines within which all occurrences of the
object string are changed to the replacement string. If you do
not specify a range, EDT changes only the first occurrence of the
object string that it locates.
/BRIEF
Specifies that EDT display the first n characters of each line in
which it makes a substitution. If you omit the n argument, EDT
displays the first 10 characters.
/QUERY
Specifies that you want to control the operation by using
prompts and responses.
EDT prompts you by displaying
substitution about to be made and waits for you to enter any
of the following responses:

EDT
the
one

Response

Result

Y or YES
N or NO
Q or QUIT

Makes the substitution
Does not make the substitution
Stops substituting and displays the asterisk
prompt
Makes substitutions in the
rest
of
the
appropriate lines in the range without printing
them first

A or ALL

2-42

11
. •

Qi.I !Iii!! 22!1221

:ams m: ::

T I Li! iii! !iii

ii:;:

I JM

DEC EDITOR (EDT)

/-TYPE
Inhibits EDT's automatic display
substitution is made in that line.

each

after

line

NEXT
Repeats the operation of the
immediately 1:ollow.

Substitute

command

that

must

Exam1ples

S/ABC/XYZ
This command causes EDT to change the next occurrence of ABC to
XYZ.
If ABC exists on the current line, it is changed. If not,
the contents of the buffer are searched, and the first occurrence
is changed.
S'/'\'

This command causes EDT to change the first slash (/) to a
backslash
(\), and uses an apostrophe (') as the string
delimiter.
S/A/B/.
This command changes every occurrence of A to B
line cmly.

the

current

Note that the final slash (/) string delimiter must be included
here since the current line range is specified by the period (.).
S/001/100/%WH/Q
In this example, EDT attempts to change every occurrence of 001
to 100 in the entire text buffer but queries you before making
each substitution.
L~I
~'

S/ .. AND/. OR/%REST /-T
In th:is example, EDT changes every occurrence of .AND to .OR from
the current line through the end of the text buffer but does not
display any of the resulting lines.
*S/.MAC/.BAS//-T
*S N
150
IF THE FILE TYPE IS .BAS, THE COMPILER MAKES
In this example, EDT changes the first occurrence of .MAC to
.BAS, but does not display the changed line. The S N command
then changes the next occurrence of
.MAC
to
.BAS
and
automatically displays the line.
Note in the first command line that two consecutive slashes
are
used.
The first of these indicates the end of
replacement string and the second that an option follows.

2-43

(/)
the

DEC EDITOR (EDT)

Notes

•

EDT displays each line that contains a substitution on the
terminal after it makes the substitution. If you specify a
range that requires substitutions in more lines than you wish
to have displayed, specify the /-Type option to inhibit the
display.

•

The S N or Substitute Next command format must immediately
follow another Substitute command. When entered, S N repeats
a single substitution as performed by the command it follows.
The S N command format does not accept a range or any options.
It allows you to perform one more substitution that has
already been defined without requiring you to retype the
command string.

•

After EDT makes substitutions, it positions the line
at the last line in which a substitution was made.

pointer

You can replace the slash (/) string delimiter with any
printing character except a letter or number, for example, a
question mark (?),semicolon (;),apostrophe ('),and so on.
You can omit the final string delimiter if no range or options
follow and if the omitted delimiter is the last character in
the command line.

2.3.18

TYPE

Use the Type command to display lines of text at your terminal.
Formats

[T[YPE]]

[range]

or
T[YPE]

[range]

[/BR[IEF]] [:n]

TYPE
Specifies the Type command. Note that this field is optional
you do not specify the /Brief option.

range
Specifies the lines that you want displayed at your terminal. If
you omit the range argument, the range defaults to the line
following the current line (see Notes).
/BRIEF
Specifies that EDT display only the first n characters of each
line in the range.
If you omit the n argument, EDT displays the
first 10 characters.

2-44

1 ~1111

ill$

$Sill&

llJ!ij$

lib iii

DEC EDITOR (EDT)

Examples
'ABC': "DEF"
This command displays all lines of text from the first line that
contains ABC through the first line that contains DEF, inclusive.
T 1 0 : 1 0 0 /BR : 5
This command displays the first five characters of each line with
line numbers between 10 and 100, inclusive.
%WH
This command displays the entire text buffer contents.
*<RET>
120 DID GYRE AND GIMBLE IN THE WABE

*
This command, consisting only of a carriage return, advances the
line pointer to the next
line and prints the line.
Line 120
becomes the new current line.

Notes

""'

•

You can issue a Type command that consists of only a
range.
The contents of that range are displayed on the terminal.
However, if you issue this format of the Type command,
you
cannot include any command options.

•

After EDT displays the lines in the range on your terminal,
positions the line pointer at the first line in the range.

•

A special case of the Type command occurs when you omit both
the command and the range;
that is, when you enter a command
line that consists only of a carriage
return.
EDT first
advances the line pointer to the next line, then types that
line.
The line just typed becomes the current line.
This
variation of
the Type command allows you to step through the
lines in a file simply by pressing <RET> repeatedly.

2.3.19

WRITE

Use the Write command to create a file from the
bu Her.

For·mat
WR [ ITE]

[range]

/FI : f i lespec

WRITE
Specifies the Write command.

2-45

contents

text

DEC EDITOR (EDT)
range
Specifies the buffer contents that you want to store in the file.
If you do not specify a range, EDT uses the entire contents of
the current text buffer as a range.
/FI: f ilespec
Specifies the output file that EDT creates. You must use the /FI
option to specify your output file.
Section 1.3 contains a
complete description of file specifications.
Example

WR =B 10:70/FI:INT.FOR
This command creates a file named INT.FOR that contains lines
through 70, inclusive, of buffer B.

Notes
•

EDT does not reposition the line pointer after a Write
command, nor does the Write command alter the contents of the
range or buffer.

•

Use the Write command to generate a file that contains the
contents of alternate text buffers that you want to save.
When you issue the Exit command, EDT saves only the contents
of the main text buffer; all other buffers are erased.
(See
Section 2.3.4 for a description of the Exit command.)
You can also use the Write command to save the contents of the
main buffer if you did not specify an output file when you
invoked EDT.

2.3.20

XEQ (Execute)

Use the Execute command to execute a previously
EDT commands.

entered

sequence

Format

X[EQ] range
XEQ
Specifies the Execute command.
range
Specifies the lines of text that contain the EDT commands
executed.

2-46

·:iuu:m till

I .ii

Iii$

ii!!i!JS

; ii

!GO :U .CAZ Ui. JIH

DEC EDITOR (EDT)
Exam.pl es

x l.0:30
where lines 10 through 30 contain:
10
20
30

I ABC I
S/40/70/.
<RET>

In this example, EDT searches for the next line that contains
ABC, and attempts to change all occurrences of 40 to 70 within
the line. The blank line implied by the <RET> symbol advances
the line pointer past the now current line that contains ABC so
that further X 10:30 commands locate the next succeeding line
that contains ABC.

x •8
1

where buffer B contains:
=MAIN %BE
'ABC'
R

XYZ
"'Z

This example returns the line pointer to the first line of the
main buffer, locates and deletes the first line that contains an
occurrence of ABC, inserts a line consisting of XYZ, and
terminates the insert with the circumflex-z ("'Z) combination.
Not4~S

•

Use the Execute command if you have identical or complex edits
to perform, or if you have an established series of commands
that are often issued.

•

EDT positions the line pointer as directed by the commands
contained in the range specified with the Execute command.

•

The Execute command cannot alter the
containing the commands in any way.

•

If the range specified with the Execute command contains
Insert
or Replace command, use the following steps
terminate the Insert or Replace command properly:

•

contents

the

range
an
to

Create the sequence of commands that will be excuted
by the Execute command,
including the Insert or
Replace command.

Enter the new or replacement lines as part
sequence of commands contained in the range.

When all new or replacement lines are entered, enter
a circumflex-z ("'Z) combination as part of the
sequence of commands. When EDT executes the sequence
of commands, the "'z is interpreted as <CTRL/Z>.

When the commands in the range
displays the asterisk prompt.

2-47

have

been

executed,

the

EDT

DEC EDITOR (EDT)
2.4

CHARACTER MODE

When you issue the Change command from EDT's Command Mode, you invoke
Character Mode. Character Mode allows video terminal users to work at
the character and word levels, in addition to the line level provided
by Command Mode.
Character Mode does this by using the video
terminal's cursor as a pointer to the current position in the buffer.
All Character Mode editing operations use the position of the cursor
as a reference point.
Unlike Command Mode's line pointer, which
points to an entire line, the cursor in Character Mode points to one
character within a line.
Similarly, where Command Mode commands
generally operate on no unit smaller than an entire line of text,
Character Mode subcommands can operate on the single character
indicated by the cursor. Character Mode can also operate on multiple
characters, words, and lines.
Character Mode differs from Command Mode in several other respects.
The most obvious difference is the lack of line numbers in Character
Mode. A second difference is that Character Mode only operates in one
buffer at a time.
As a result of these two differences, Character
Mode is not useful for moving lines of text from place to place and
especially from buffer to buffer. You should use Command Mode for
these operations. Character Mode is at its best when you must perform
extensive editing operations within a line.

~:_--,,..:·----~_,_,_,• ___

When you are working in Character Mode, the video terminal screen
always displays the exact contents of the buffer. After each edit,
Character Mode updates the display to reflect the current text.
When you issue the Change command, the video terminal screen goes
blank, except for the current line of the buffer, which appears at the
top of the screen. The cursor is positioned at the first character of
the line.
Although there is no indication on the screen, Character
Mode is waiting for a subcommand (so called because Character Mode is
a subfunction of the Change command). If you type something, whatever
you type appears at the bottom of the screen, in a zone reserved for
subcommands.
Depending on the subcommands you issue, you can perform
some editing operation within the line at the top of the screen, or
cause Character Mode to display more lines of the buffer.
When Character Mode is in use, you have access to the entire range
specified in the Change command. However, since your screen can only
display a certain number of lines of text, the screen is like a window
on the text buffer. If you direct the cursor to a line that is not in
the current display, Character Mode scrolls the display up or down, as
appropriate, to bring the specified line into view.
(If you mQve the
cursor a large number of lines, the display does not scroll;
it
vanishes, and the specified line is displayed at the top of the
screen.)
Once the cursor is positioned at the beginning of the line you wish to
change, you direct the cursor to the desired character within the
line. You do this either by issuing subcommands or by using the arrow
keys on your terminal's keypad (if your terminal is so equipped) to
move the cursor. You can then perform any of these actions:
•

Delete a specified number of characters, words, or lines

•

Replace a specified number of characters, words, or lines with
new text

~I
2-48

:r• I i IL I.JtJJl!iiiii!i!S!!.!b ii Ii !i i i 21 I.i iiiiiii I l!i.111 Jiliiiiii!! iii iii

;;

:::;

$&$.Ii ISL!iiii I I

i $! .i .I I Uiil!Q ti IJSM fa!JIJ iiii!l!U$

DEC EDITOR (EDT)
•

Insert text in front of the cursor

•

Substitute the next (or previous) occurrence
string with another string

specified

At the end of the Character Mode session, you issue the Exit
subcommand to terminate Character Mode and return to Command Mode.
When you use Character Mode, it is important that EDT's Terminal
parameter matches the type of terminal you are working on. Sections
2.3.15 and 2.3.16 describe the Set and Show commands, which allow you
to establish and display the value of the Terminal parameter.
In addition, you should be sure that your terminal is correctly
described in the operating system's list of devices. Use the MCR Set
command or (for RSX-llM-PLUS users) the DCL Show command to make sure
your terminal is set correctly (see the RSX-llM/M-PLUS MCR Operations
Manual or the RSX-llM-PLUS Command Language Manual, respectively).
The remainder of this section describes:

'--'

•

Editing subcommands, which allow you to
and perform editing operations

•

Methods of cursor manipulation other than those available with
the editing subcommands

•

Subcommand concatenation, which allows you
subcommands on one line

•

Two subcommands to terminate Character Mode

2.4.1

position

the

enter

cursor

several

Editing Subcommands

Editing subcommands are divided into three basic groups:
•

Subcommands that move the cursor, delete, or
specified number of characters, words, or lines

replace

•

The Insert subcommand, which allows
front of the cursor position

text

•

The Substitute subcommand, which allows you to substitute
the next (or previous) occurrence of a string

for

Each of these groups is treated
follow.

individually

you

the

insert

sections

that

2.4.1.1 Subcommands
That
Move
the
Cursor,
Delete,
or
Replace - Subcommands in this group are made up of three fields:
action, repetition count, and unit. The action field specifies what
you want to do; the repetition count field specifies how many times
you want to do it, and in which direction;
and the unit field
specifies whether you want to do it to characters, words, or lines.
The action and repetition count fields are optional, but you must
specify a unit. You cannot separate the fields with spaces or tabs.
Forllllat
[actic>n] [-] [repcount]unit<RET>

2-49

DEC EDITOR (EDT)

action
Represents a 1-letter abbreviation (or a null field)
specifies the editing operation that you wish to perform.

that

~
!"'"""·~

If this field is null, Character Mode moves the cursor the
specified number of units in the buffer, and displays the text if
it has not already been displayed.
If this field is a D (for Delete), Character Mode deletes the
specified number of units, starting at the current cursor
position.
If this field is an R (for Replace), Character Mode first deletes
the specified number of units, then waits for you to insert text
in place of the deleted units. When you finish inserting the
replacement text, enter a <CTRL/Z>. This directs Character Mode
to terminate the insert operation and
wait
for
another
subcommand.
(See Section 2.4.1.2 for a full description of the
Insert subcommand.)
repcount
Represents an integer that specifies the repetition count.
The
repetition count tells Character Mode how many times to perform
the action. If the repetition count is positive, the action
takes place for the specified number of units following the
cursor, including the unit at which the cursor is currently
positioned.
If the repetition count is negative, the action
takes place for the specified number of units preceding the
cursor, not including the unit at which the cursor is currently
positioned.
If you leave this field null, the repetition count defaults to 1,
and the action takes place on the unit at which the cursor is
currently positioned. If you do not enter a minus sign (-) with
the repetition count, the sign defaults to positive.

unit
Repfesents a 1-letter abbreviation that specifies the unit on
which the action is to take place.
The unit can be C (for
character), W (for word), or L (for line).
A character is a single ASCII character, including spaces and
tabs.
If you specify the /NL option with the Change command,
line terminators are also considered single characters and can be
deleted.
(See Section 2.3.1 for a description of the Change
command.)
A word is any string of printing characters and trailing word
terminators.
A word begins at its first character and includes
all characters in the word and all word terminators (spaces
and/or tabs) up to the first character of the next word.
A line begins at the first character of the line and includes all
characters in the line up to (and including) the line terminator.
The line terminator can be a carriage return, line feed, form
feed, or vertical tab.

2-50

" 2ti i

I I2

iiiii4 J

I 4U::: J ii il1411Z¥

DEC EDITOR (EDT)

Examples
D3W

This subcommand deletes three words, beginning with the
which the cursor is currently positioned.

word

to
l;
In this subcommand, the repetition count defaults
therefore, the subcommand deletes the single word at which the
cursor is positioned.
-4W

In this subcommand, the action field is left null;
therefore,
the cursor moves backwards in the buffer by four words, coming to
rest on the first character of the fourth word preceding its
starting position.
DC

This subcommand deletes the single character at which the
is currently positioned.

cursor

DSC

This subcommand deletes the character at which the cursor is
currently positioned and the four characters following that
position, for a total of five characters.

D--sc
This subcommand deletes the character immediately preceding the
cursor position and the four characters preceding that one, for a
total of five. Note that this subcommand does not delete the
character at which the cursor is positioned.

This subcommand deletes the three words immediately preceding the
word in which the cursor is positioned. Note that the word in
which the cursor is positioned is not deleted if the repetition
count is negative.
D2L

This subcommand deletes the line in which the cursor
positioned and the following line, for a total of two lines.

·-....,
2-51

DEC EDITOR (EDT)

D-3L
This subcommand deletes the three lines immediately preceding the
line in which the cursor is positioned. Following the operation,
the cursor comes to rest at the beginning of the line in which it
was originally positioned, that is, the first line following the
deleted lines.
R2C
This subcommand first deletes two characters starting at the
current cursor position, then waits for you to input replacement
text.
When you enter <CTRL/Z>, the replacement
operation
terminates and Character Mode waits for another subcommand.
In practice, when you issue a Replace subcommand, the specified
characters and the remainder of the affected line vanish. You
can then enter the replacement text, including carriage returns
if necessary.
When you enter <CTRL/Z>, the remainder of the
affected line reappears in its proper position following the
replacement text.
R3W
This subcommand first deletes three words, starting with the word
in which the cursor is currently located, then waits for you to
input replacement text. When you enter <CTRL/Z>, the replacement
operation
terminates and Character Mode waits for another
subcommand.
When replacing words, it is important to remember that you must
also replace the word terminator(s). A word includes all spaces
or tabs until the first character of the next word, or the first
line terminator.
2W3C
This subcommand string first moves the cursor two words forward
from the current position, to the first character of the second
word. It then moves the cursor three characters further, to the
fourth character of the word.
This example and the following one
illustrate
subcommand
concatenation. For more information on subcommand concatenation,
see Section 2.4.3.
2L3WD2W
This subcommand string first moves the cursor down two lines to
the beginning of the second line following its original position.
It then moves the cursor three words into the line, to the
beginning of the fourth word. Finally, it deletes two words,
starting at the current cursor position; that is, the fourth and
fifth words of the line.

2-52

:i~•

2i2 !l I 2iii lilSS!i I 2 I

!iiJi

;;

:;z

$bi221

DEC EDITOR (EDT)
Not:es

•

When you are deleting or replacing characters or words,
normally you cannot delete beyond the end or beginning of the
current line. For example, the cursor is two words from the
end of the line, and you issue the subcommand:
DSW
In this situation, Character Mode does not delete the last two
words on the current line and the first three on the next
line, as you might expect. Only the last two words on the
current line are deleted. The situation is the same if you
try to delete or replace characters beyond the end or
beginning of the current line.
The situation changes, however, if you specify the /NL option
when you issue the Change command. The /NL option directs
Character Mode to treat line terminators as single characters
that can be deleted.
If you specified /NL, and you try to
delete beyond the end or beginning of a line, you will
succeed; Character Mode deletes the line terminator and joins
the two lines that the line terminator used to separate.
This distinction becomes important if you wish to delete or
replace all the words or characters between the current cursor
position and the end or beginning of the current line. If you
issued the Change command without the /NL option, you can
simply specify a repetition count that is larger than the
number of words or characters you wish to delete. Character
Mode will delete only to the end or beginning of the line,
depending on whether the repetition count is positive or
negative. If, however, you specified the /NL option, you must
specify a repetition count that exactly malches the number of
words or characters you wish to delete.
If the repetition
count you specify is too large, you will delete the line
terminator and possibly some words in the following or
preceding line.
I:E you specified the /NL option and you delete or replace
characters beyond the end or beginning of a line, remember
that the line terminator counts as a single character and must
be accounted for when you calculate the repetition count.
However, if you are deleting words, you do not have to include
the line terminator in the repetition count, because the line
terminator is treated as part of the last word in the line.

are not allowed between the elements of a subcommand •
• Spaces
If, for example, you attempt to issue the subcommand
D 5 W
Character Mode returns the error message
Illegal subcommand
•

The DELETE key on your terminal can be used directly to delete
characters from the text buffer. <DEL> deletes the character
directly to the left of the cursor.
Thus, a single <DEL>
keystroke is equivalent to the subcommand:

o-c

2-53

DEC EDITOR (EDT)
Use care when deleting a subcommand that you have entered
incorrectly. If you inadvertently delete more characters than
are in the subcommand, you will also delete some characters
from the text buffer.

2.4.1.2 The Insert Subcommand - The Insert subcommand allows you to
insert text at any point in the text buffer. The text can consist of
any combination of characters, including carriage returns and other
line terminators. When you want to terminate the insert operation, a
<CTRL/Z> directs Character Mode to stop accepting text for insertion
and wait for another subcommand.
Format
[loc]I<RET>
loc
Represents a Character Mode subcommand or
combination
of
subcommands that results in a new cursor position.
(Note,
however, that a string search operation must be the last element
entered in a subcommand string; see Section 2.4.3.)
I

Specifies that the text you enter following the <RET> be inserted
immediately preceding the current cursor position. Character
Mode continues to insert text until you enter a <CTRL/Z>.
Notes
•

In practice, the Insert subcommand causes the remainder of the
line in which the cursor is currently positioned to vanish,
leaving the cursor at the position where the insert will
occur.
When you finish typing the insert text and enter a <CTRL/Z>,
the remainder of the line reappears in the proper position.
It is not necessary to type a <RET> before the <CTRL/Z>, as is
the case when inserting in Command Moda. Any carriage returns
that you enter while inserting become part of the insert.
If you position the cursor under the first character of a line
and issue the Insert subcommand, the entire line vanishes.
You can then insert one or more complete lines, including line
terminators.
These lines will go into the text buffer above
the line in which the cursor was originally positioned.
When
you enter a <CTRL/Z>, the line above which the new lines have
been inserted reappears.
If you position the cursor at the end of a line and issue the
Insert subcommand, the resulting insert occurs between the
last character of the line and the line terminator.

•

A long insert in a long line can result in text disappearing
off the right edge of the screen. The text is still in the
buffer, however, and can be recovered by inserting a carriage
return in the line.

2-54

l.iiiiii! i . Sill Lii!ii iiiiii t

iiii I

a :a

;::::::::

SJ 42 2

ti $l...

114

. 14141

DEC EDITOR (EDT)

2.4.1.3 The Substitute Subcommand - The Substitute subcommand works
in much the same way as the Substitute command works in Command Mode,
and follows similar format rules.
It allows you to substitute a
specified string with another string.
Format
[-]S/objstring/repstring[/]

Specifies that the direction of search for the object string
should be toward the top of the buffer, rather than toward the
bottom. If this field is null, the search is toward the bottom
of the buffer.

s
Specifies the Substitute subcommand.

I
Represents the string delimiter. The delimiters can be slashes
or any other printing, nonalphanumeric characters; however, the
delimiters used in a given Substitute operation must match. Note
that the final terminator is optional, as long as you do not
place additional subcommands at the end of the Substitute
subcommand.
(For
a
complete
description
of subcommand
concatenation, see Section 2.4.3.)
objs tr ing
Specifies the object string that is to be replaced with the
replacement string.
The criteria that Character Mode uses to
determine whether two strings match are those established by the
Command Mode Set command (see Section 2.3.15).

"'-''

reps:tring
Specifies the replacement string that is to
string.

replace

the

object

Note~s

•

When you issue the Substitute subcommand, the object string
you specify becomes the last-specified object string. This
means that you can later locate the next (or preceding)
occurrence of the object string by entering paired quote marks
("") or apostrophes (''). See Section 2.4.2.2 for a full
description of Character Mode string searches.

Cursor Manipulation

2.4~2

You can us~~ the editing subcommands presented in Section 2.4.1.l to
move the cursor in the text buffer.
There are three additional
methods of moving the cursor:
•

Subcommands that move the cursor to the beginning or end of
specified unit of text

2-55

DEC EDITOR (EDT)
•

String searches, which move the cursor to the beginning
specified object string

•

Keypad arrows, on terminals that are equipped with them

2.4.2.1 Cursor Subcommands - The cursor manipulation
subcommands
consist of two letters. The first letter is B or E, and specifies the
beginning or end of the unit specified by the second letter.
The
second letter can be w, for word; L, for line; or R, for range. The
range is equivalent to the range that you specified when you issued
the Command Mode Change command.
Table 2-8 summarizes the cursor
~anipulation subcommands.
Table 2-8
Cursor Manipulation Subcommands
Subcommand

Function

Moves the cursor to the beginning of the current line

Moves the cursor to the beginning of the current word

Moves the cursor to the first character in the
specified in the Change command

Moves the cursor to the end of the current line

Moves the cursor to the end of the current word

Moves the cursor to the end of the
specified in the Change command

range

that

was

2.4.2.2 String Searches - String searches move the cursor to a
specified object string, either before or after the beginning cursor
position. The format of a string search request is as follows:
[-] [n] '[objstring] [ •]

Specifies that the search should proceed toward the top of the
text buffer.
If you leave this field null, the search proceeds
toward the bottom of the text buffer.
n

Specifies which occurrence of the object string to
value of n defaults to 1.

locate.

The

Represents the string delimiter.
For string searches, the
apostrophe
(')
and the quote mark (") are legal string
delimiters. The delimiter that you use at the beginning of the
string must match the one you use at the end of the string.

2-56

'•t !iii I !US! i!iiiii iii!

iiii!E.iiiiiiiii

I !lip

ta a

QSSSiittA 42

DEC EDITOR (EDT)
objstr ing
L.

Specifies the object string. Following a successful search, the
cursor is positioned at the first character in the object string.
If the objstring field is left null, the search is made for the
object string that was specified in the most recent string search
operation or Substitute subcommand.
Exam1ples

'BOMBARD'
This example moves the cursor to the first letter of the first
occurrence of the word BOMBARD.
If the cursor is already
positioned at the first letter of BOMBARD, it moves toward the
end of the buffer searching for another occurrence of BOMBARD.
·-2 I FLUGELHORN I
This example moves the cursor to the second occurrence of
FLUGELHORN preceding the starting cursor position.
If the
starting cursor position is on the first letter of an occurrence
of FLUGELHORN, that occurrence does not count in the total.
Howevetr, if the cursor is in the middle of an occurrence of
FLUGELHORN, that occurrence is counted.
I I

This example moves the cursor to the first occurrence of the last
string specified as the object string in a search or substitute
operation. Repeated executions of the same subcommand will move
the cursor to subsequent occurrences of the string in the buffer.
This feature allows you to step through repeated occurrences of a
given object string without reentering the string each time.
HotttS

•

To determine whether two strings match, Character Mode uses
the
criteria specified in a Command Mode Set command.
Specifically, if Exact Case is in effect, both the characters
and their cases must match before a match is declared. If
Exact None (the default) is in effect, only the characters in
the two strings must match.
Sections 2.3.15 and 2.3.16
describe the Set and Show commands, which allow you to
establish and examine the Exact parameter.

•

When Character Mode carries out a string search operation, it
always moves the cursor one character in the direction of the
search before beginning. This means that a search operation
does not find a particular object string if it starts from the
first letter of that object string.

2.4.2.3 B:eypad Arrows - Many terminals are equipped with a numeric
keypad, and some keypads have a set of four directional arrows. These
arrows provide yet another means of moving the cursor.
The two
vertical arrows move the cursor up or down a line each time you press

2-57

DEC EDITOR (EDT)
them, while the two horizontal arrows move the cursor one character to
the left or right. The four arrows are therefore equivalent to the
following cursor manipulation subcommands:
Arrow

Equivalent Subcommand

'
-

2.4.3

-L

-c

Subcommand Concatenation

You can enter two or more subcommands on a single line.
This is
called subcommand concatenation; a group of concatenated subcommands
is called a subcommand string. Subcommand concatenation allows you to
direct Character Mode to perform a series of editing operations
without waiting for each operation to complete before entering the
next subcommand.
When you concatenate subcommands, Character Mode carries out each
subcommand in the order that you enter it. When Character Mode
finishes a given operation, it checks to see if there are more
characters on the subcommand line. If there are, Character Mode scans
the characters until it assembles a complete subcommand or encounters
an error.
If it finds a complete subcommand, it carries it out; if
it finds an error, it returns an error message and ignores the rest of
the subcommand line.
You may, if you wish, separate concatenated subcommands with a space.
However, because the syntax of Character Mode subcommands is so
tightly defined, Character Mode does not require that subcommands be
delimited with spaces or other characters.
There are two limitations on the concatenation of subcommands:
•

You cannot
characters.

enter

subcommand

string

than

•

If your string of subcommands includes a string search, the
string search must be the last subcommand entered. Character
Mode ignores any subcommands entered on a line after a string
search.

longer

There are no other limitations on the subcommands you can string
together.
You can even embed Insert and Replace subcommands in a
subcommand string. If you do so, the <CTRL/Z> you enter to terminate
the insert or replacement sends Character Mode looking for another
subcommand.
In practical terms, however, subcommand concatenation is useful only
up to the point at which it becomes difficult to think that many moves
ahead. Too much subcommand concatenation defeats one of the goals of
Character Mode, which is to provide a fast, intuitive means of editing
within lines. How much concatenation you do will depend on your
expertise in Character Mode and your ability to think ahead.

2-58

!!!$

iii

.I.if I

J 44Uh2iii

ta; U:jiil 4

DEC EDITOR (EDT)

The f:ollowing examples illustrate some subcommand strings that are
often useful.
Some of the examples separate their subcommands with
spaces in order to clarify the example; others do not.
Exam1~les

EL I
This subcommand string directs Character Mode to go to the end of
the current line and insert text.
EL OW
This subcommand string directs Character Mode to go to the end of
the current line and delete the last word on the line.
ER L I
This subcommand string directs Character Mode to go to the end of
the range
(that is, to the last line of the range specified in
the Change command); go down an additional line, to the [EOB]
(End of Buffer) position; and insert text above the [EOB]. Use
this subcommand string to insert text at the end of the range.
If you do not include the L, directing Character Mode to the
[EOB] marking, you insert text above the last line in the range,
instead of below it.
-2LEL-2WRW
This subcommand string directs Character Mode to move the cursor
two lines above its current position; to move to the end of that
line; to back up two words to the third word from the end;
and
to replace that word. It is often easier to count from the end
of the line to a word than from the beginning of the line.
3WEWRC
This subcommand string directs Character Mode to move the cursor
three words beyond the current word; to go to the end of the new
current word; and to replace the last character of that word.

2.4.4

Subcommands to Terminate Character Mode

If you wish to terminate Character Mode and return
issue the subcommand:

Command

Mode,

EX stands for Exit. It terminates Character Mode and returns the
Command Mode asterisk prompt (*). The range that you specified with
the Change command will contain the edits you made while in Character
Mode.
When you start editing in Command Mode, your current line will
be the same as it was when you issued the Exit subcommand.

2-59

DEC EDITOR (EDT)
If you wish to terminate Character Mode and
monitor, issue the subcommand:

return

directly

the

QUIT
Quit behaves like its Command Mode counterpart (see Section 2.3.10).
No output files are generated when you issue the Quit subcommand.

2.5

SUMMARY OF EDT COMMAND MODE COMMANDS
Description

Command Format
C [HANGE]

[range]

Invokes Character Mode.

[/NL]

CO[PY] range-1 %TO range-2 [/Q]
[/SEQ]
[/UN]

Copies the lines in range-1
to a position ahead of the
first line in range-2.

D[ELETE]

Deletes lines from the
buffer.

EX[IT]

[range] [/Q]

[/RE:filespec]

Terminates EDT; writes
contents of the main text
buffer to specified output file.

F [IND] range

Moves the line pointer to
the first line in the range.

INC[LUDE]

[range] /FI:filespec
[/SEQ]
[/UN]

Locates a file and copies
it into a text buffer.

I [NSERT]

[range] [/SEQ]
[/UN]

Inserts text typed at the
terminal in the buffer
ahead of the first line in
the range.

M[OVE] range-1 %TO range-2 [/Q]
[/SEQ]
[/UN]

Transfers the lines in
range-1 to a position
ahead of the first line in
range-2.

PR[INT]

Generates an output file
from the contents of the
range. The output file
contains EDT line numbers as part of the text.

[range] /FI:filespec

Terminates EDT; saves no
edits or text buffers; generates no files.

QUIT

[REPLACE]

[range]

First deletes the lines in
the range, then inserts
text typed at terminal into
buffer in place of deleted
text.

[/SEQ]
[/UN]

2-60

q1;

ii IL

iiii

iii iiiiiiii!.jiiiiiii

::;

ii!

ii!Lii I

2!12421

I4S JSZ 4#1! I

DEC EDITOR (EDT)
Command Format
RES[EQUENCE]

[range]

Description
Assigns new line numbers
to the lines in the range.

[/SEQ]
[/UN]

REST[ORE] /FI:filespec

Locates specified file created by a Save command;
uses the file's contents to
restore the status and
contents of the text buffers.

SA[VE] /FI:filespec

Creates a file that contains the status and contents of the text buffers
currently in use.

CA [SE]
EXACT
SE [T]

Establishes criteria that
other EDT commands
use in their operation;
flags upper-case or lowercase characters; and establishes proper terminal
parameters.

UPPER]
LOWER
[ NONE
CA[SEn
NONE j

HCPY
VTOS
VTSO
TE[RMINAL] VT52
VT55
VT61
LA30
LA36
Displays the values
established by the Set
command, as well as
current buffer status
and software version
information.

SH[OW] [BU [FFERS] ]
C:A[SE]
EXACT
TE [RMINAL]
VE [RS ION]
S[UBSTITUTE]/str-l/str-2/(range]
[/BR]

[/Q]
[/-T]

Changes str-1 to str-2.
If range is specified,
changes all str-ls in the
range. If no range,
changes only the first
str-1 encountered.

S[UBSTITUTE] N[EXT]

Repeats the operation of
the substitute command
that it must immediately
follow.

[T'[YPE]] [range]
or
T[YPE] [range] [/BRief]

Displays the contents of
the range on your terminal.

WR. [ ITE]

Creates an output file from
the contents of the range.

[range] /FI : f i lespec

Executes the EDT commands contained in the
range.

X[EQ] range

2-61

DEC EDITOR (EDT)
2.6

ERROR REPORTING AND ERROR MESSAGES

As you use EDT, you may from time to time make errors in your use of
the commands. EDT provides a set of error messages that inform you of
the nature of the error you have made.
If you are unfamiliar with the operation of EDT, and you need more
information than you get from a single error message, you can type a
question mark {?) in response to the Command Mode prompt that appears
following the error message. In many cases, EDT replies with further
information about the error you have made. In some cases, even more
information can be obtained by typing another question mark. This
feature is available in Command Mode only.
The EDT error messages are listed below alphabetically.
Those
messages that provide further information in response to a question
mark contain that information as well. These messages appear in the
list below as they would on your terminal.
Most of EDT error messages are self-explanatory.
are followed by a brief explanation.

Those that

are

not

An argument is required.
*?

You must specify a valid argument for this command.

Bad option format.
*?

An editor option is of the form /xx.

Bad option value in this context.
*?

The switch option value specified is invalid in context of its
usage.
Bad Range Format.
*?

The range you specified is not legal.
Explanation: You attempted to specify a range in an unacceptable
format.
This error message can often result from mistyping of
commands.

Buffer Specification Conflict.
*?
*?

The command you
specification.

typed

implied

than

one

For instance, this may occur by using "N:M" in the
as "%L".

same

buffer
line

Cannot mix "-" and value in option.
*?

An option cannot have a modifier as well as a value.

2-62

i.Xiliii.!!iii!ii!Ji

.:mmm :::m::: :u:::::::: am::

Ji!

i!iii I

ii!lii

;.:

;a u :a a 22 u:

1124

iii2 )Ul l!IJ j4!i#i I

DEC EDITOR (EDT)

Cannot recognize terminal type.
*?
The terminal type you specified was unrecognizable.
*?
The legal terminal types are HCPY, LA30, LA36, VTOS,
VT52, VT55, VT61.

VT50,

Cannot yet be performed on hard copy devices.
*?
ThE~ CHANGE command wi 11 not work on hard copy devices.
Command I/O error.
Explanation: An I/O error occurred while EDT was trying to
a command line.

read

Destination range must be contiguous.
*?
A MOVE or COPY command can have only one destination.
FATJ!~L

- Ed:itor consistency error.
Explanation: An internal EDT error occurred. The input file
not affected, but no output file is created. EDT terminates.

FATAL - I/O error on work file.
Explanation: EDT encountered an I/O error while trying to read
from or write to its internal work file. The input file is
unaffected, but no output file is generated. EDT terminates.

FATAL - Open error on work file.
Explanation: EDT was unable to open its internal work file.
input file is unaffected, but no output file is generated.
terminates.

The
EDT

FATil\L - Work file consistency error.
Explanation: The editor detected an inconsistency
in
its
internal work file.
This condition can result from a system
problem or an internal EDT error. The input file is unaffected,
but no output file is generated. EDT terminates.

FATAL - work file memory error.
While trying to read from or write to a work
EDT encountered a system memory error.

Explanation~

file,

File name syntax error.
*?
The file name you specified does not have the correct format.

2-63

DEC EDITOR (EDT)

File name table exhausted.
*?
You have explicitly referenced more files
tables can accommodate.
*?
The INCLUDE or RESTORE has exhausted tables
editor.

than

the

internal

editor
to

the

File name wild cards not allowed.
*?
An explicit file must be specified to the editor.
File open error.
*?
The editor is unable to correctly open the requested file.
Illegal command option.
Explanation: You specified a command option that was
for the command you issued.

not

legal

Illegal form for N:M.
Explanation: You gave a range specification in the form N:M that
did not follow syntax rules.

Illegal line number.
*?
A line number must be in the range l to 65535.
Illegal option name modifier.
*?
An option name modifier can consist only of
the option.

"-"

preceding

Illegal string delimiters.
*?
The string delimiter may not be an alphanumeric character.
Illegal subcommand.
Explanation: This error message appears in Character Mode.
subcommand you issued was not in the correct format.

The

Illegal termination of command line.
*?
A line was terminated by other than an end of line or comment.
Illegal text buffer name.
*?
A text buffer name may consist only of from one to six
alphanumeric characters.
*?
A text buffer name must be preceded by either '•' or '%BUF'.

2-64

Pl I

iii! ill! I i

iii!

21 iiiiiiip

;;

;2:::21w:z

ti. !Ullii#iii

DEC EDITOR (EDT)
Input record too big.
*?
The editor was unable to read the input record because of
size.
*?
The input record is longer than 255 characters in length.
*?
The editor treats this condition as an EOF condition on
input file.

its

the

I/O error on source file.

Explanation: EDT encountered a system I/O error while attempting
to read from a file.
"%LAST" has no meaning in this context.
Missing string quote.
*?
A legal string must be surrounded by a pair of matching quote
marks.
*?
A quoted string consists of one or more characters delimited
by "or '
For instance, "ABC" or 'DEF'.
Nested XEQ not yet implemented.
*?
This version of the editor allows no XEQ command nesting.
No destination range.
*?
In MOVE or COPY, a destination range must always exist.
No input file specified.
*?
"INCLUDE" or "RESTORE" requires the /FI switch to specify
input file.

the

Non-contiguous range not allowed.
*?
The CHANGE command will work only on
lines.

range

string

was

contiguous

No output file specified.
*?
The command you specified requires an output file.
No previous string entered.
*?
'' or "" cannot be
specified.

used

2-65

unless

DEC EDITOR (EDT)

No range specification allowed.
* ?
A range specification is _not meaningful in SAVE or RESTORE.

* ?

SAVE and RESTORE only work on the entire state of the edit.

No repetition count allowed.
Explanation: This error message occurs in Character Mode.
You
attempted to specify a repetition count in a subcommand that does
not accept a repetition count, for example, EL.

No room for buffer.
* ?
The number of buffers allowed by the editor has been exceeded.
No room in output file.

~~~P~~v~~~e ~s full,

gener~te

the

The line referenced in the range specification
found.

could

The line may exist
specified.

the

editor

unable

·~

No string-type allowed.
No such file.

* ?

The input file you requested does not exist.

No such line found.

* ?

but

could

not

found

not

the

range

No such string in this range.

The string referenced in the range specification could not
found.

* ?

The string may exist but could
specified.

not

found

the

Not a SAVE file.
* ?
Cannot RESTORE a non-SAVEed file.
* ?
RESTORE can only be used on a file which was generated by
SAVE command.

range

the

No value allowed.
* ?
A value has no meaning for this option.

2-66

~1.i&;:

Ill

!£

ta M 21

DEC EDITOR (EDT)

No value specified.

* ?
* ?

This option requires a value.
An option value consists of a colon followed by the value.

Object-string required with "%ALL".

* ?
* ?

When typing "%ALL", a string must be
ob.ject.

specified

The string specification must follow "%ALL".

Offset must be non-zero.

* ?

A range offset must be non-zero i.e. - it may be +l or -1, but
not +o or -o.

Only one value allowed.

* ?

This option only allows one value to be specified.

Output file error.

* ?

The editor was unable to
error.

generate

the

output

file

without

Range must have at least one line.

* ?

Zero lines cannot be moved or copied.

Ran9e not allowed here.

The command you typed does not allow a range specification.

Ranc.;re required.

'-'

* ?

command
ThE! XEQ
spc:!c i fi cat ion.

always

requires

explicit

range

COPY

command

cannot

Ran9es overlap.

* ?

ThE! range specifications in the MOVE or
overlap.
ThE! source and
common.

destination

ranges

must

have

lines

Repetition count cannot be zero or negative.
Explanation: In a range specification of the form n;i, i
be zero or a negative number.

2-67

cannot

DEC EDITOR (EDT)
RESTORE must be first command issued.
*?
No editing is allowed preceding a RESTORE command.
*?
The RESTORE must be the first command of an editing
nothing may precede it.

session,

String search cannot have a modifier.
Explanation: This error message occurs in
string search in Character Mode cannot
modified by a command.

Character Mode.
A
be combined with or

String too long.
Explanation: This error message occurs in Character Mode.
The
string specified in a string search cannot exceed 62 characters
in length.
"SUBSTITUTE NEXT" is not legal here.
*?
"SUBSTITUTE NEXT" can be used only after "SUBSTITUTE".
*?
"SUBSTITUTE NEXT" has no meaning unless a prior "SUBSTITUTE"
command
has been executed to establish the object and
replacement strings.
The memory internal to ~he editor has overflowed.
*?
The editor's memory is full. No additional text will
Use WRITE if you desire to save what already exits.

fit.

The /QUERY switch cannot be used here.
*?
The XEQ command and /QUERY are incompatible.
The RESTORE command is not allowed in this context.
*?
When you invoked the editor, you gave a file specification.
This specification prohibits subsequent usage of RESTORE.
*?
Input the QUIT command and then invoke the editor again
without any file specification. You can then use the RESTORE
command.
The /SEQ and /UN options are not supported for this command.
*?
These switches are not implemented for EXIT, PRINT, and WRITE.
This feature is not implemented yet.
*?
You are using a feature which is not supported by this version
of EDT.

2-68

i111 I

Iii 211;

:a c

a ;:a e; :

$£!

a :z: u

124 :::;:u :

DEC EDITOR (EDT)

Unrecognized command.
*?

The command you typed is not a legal editor command.

Unrecognized option name.
*?

The option name you specified could not be recognized.

XEQ range non-contiguous.
*?

A range specification in XEQ must always be a contiguous block
of lines.

You must specify a source range.
The MOVE or
specification.

COPY

command

2-69

requires

source

range

"'~

~II fa!&

!i!ilj ii !iii!!$

i!22

I I Lliiit!Siii24 ii ili211 Si!! iii!Pliii!!iiiliiii!iii ;::::I !iiiii4Wiiii ii

CHAPTER 3
LINE TEXT EDITOR (EDI)

EDI is a line-oriented editor that allows you to create and modify
text files. EDI operates on most ASCII text files;
it is frequently
used to create and maintain FORTRAN or MACRO source files.
~DI

accepts over 50 commands that determine its mode of operation and
control its actions on input files, output files, and working text
buffers. The commands fall into the following seven categories:
•

Setup commands - select operating conditions, close
files, select data modes.

and

open

•

Locator commands - control the position of the current line
pointer and thus determine which text line is acted upon.

•

Text modification command - change text lines.

•

Macro commands - define, store, recall, and use
EDI commands.

•

File input/output commands - transfer text to and from
output, and save files.

•

Device output commands - send output to terminal or printer.

•

Close and exit commands - terminate editing operations.

sequences

input,

Commands are categorized in this chapter as Basic EDI Commands
(Section 3.2), EDI Commands:
Function Summary (Section 3.3), EDI
Commands: Detailed Reference Summary (Section 3.4).
Restrictions,
system device considerations, and error messages for these commands
are discussed in Sections 3.5 and 3.6o

3.1

USING EDI

This section gives background information about the RSX-llM/M-PLUS
Line Text Editor that is important for you to know before you read the
command descriptions.

3.1.l

Invoking EDI

You can invoke EDI using any of the methods for invoking a utility
described in Chapter 1. If any format except ">EDI filespec" is used,
EDI issues the following prompting message:
EDI>

3-1

LINE TEXT ~DITOR (EDI)

At this point, you must enter a file specification for the file to
edited.

_,.
I'

Entering File Specifications
Enter file specifications in the following format:
dev: [ufd]filename.filetype;version
The abbreviation "filespec" is used throughout this chapter to
a file specification that you supply.

denote

If the file specification is a new file (that is, the file specified
cannot be found on the specified device), EDI assumes that you wish to
create a new file with the given file name.
EDI then prints the
following comment lines:
[CREATING NEW FILE]
INPUT
and enters input mode.

(EDI control modes are

described

Section

3.1.2.)

If the message FILE DOES NOT EXIST is displayed, it means that the
user file directory corresponding to the specified UIC is nonexistent.
EDI does not accept indirect command file specifications.
If you specify an existing file name, EDI prints:
[OOOnn LINES READ IN]
PAGE O]

*
and waits in edit mode for you to issue the first command.
If the ">EDI filespec" format is used, the prompt message (EDI>) is
not issued and EDI starts up in either input or edit mode, depending
on the file name specified -- input mode if the file name is new, and
edit mode if the file name already exists.
At program startup, after EDI has identified the input file and
created the output file, the program is ready for commands. In edit
mode, the first line available for editing is one line above the top
of the input file or the block buffer. Therefore, you can insert text
at the beginning of the input file or the block buffer by issuing an
INSERT command.
To manipulate the first line of text, on the other
hand, you must perform a NEXT operation to make that line available.

Defaults in File Specifications
EDI uses a default if any of the elements of the file specification,
except input filename, is omitted. In general, EDI processing creates
an output file. When you are modifying an existing file, EDI uses
that file and your modifications to create an output file. When the
edit session is complete, the output file usually has the same file
specification as the input file, except the file system renumbers the
version to one greater than the previous version. The default values
for input and output files are listed in Table 3-1.

3-2

11111

;arm

LINE TEXT EDITOR (EDI)
Table 3-1
EDI Default File Specifications

Element

Default Value
for Input File

Default Value
for Output File

dev:

SYO:

Same as input device

[ufd]

UFO under which EDI
is currently running

Same as input [ufd]

filename

No default--must
be specified

Same as input filename

• f iletype

Null

Same as input file type

;version

Latest version

Latest version+l

3.1.2

Control Modes: Input and Edit

EDI runs in two control modes:
•

Edit mode (command mode)

•

Input mode (text mode)

Edit mode is invoked automatically when you invoke an existing file.
In edit mode, EDI issues an asterisk (*) as a prompt. EDI accepts and
acts upon commands and data strings to open and close files; to bring
in lines of text from an open file; to change, delete, or replace
information in an open file; or to insert single or multiple lines
anywhere in a file.
Input mode is invoked automatically at program startup if you
a nonexistent file.

specify

When in input mode, EDI does not issue an explicit prompt. Lines that
you enter at the terminal are treated as text and are inserted into
the output file. When you complete each input line with a carriage
return, EDI outputs a line feed to the terminal.
To switch from edit mode to input mode, enter the INSERT command
followed by a carriage return.
To return to edit mode, enter a
carriage return as the only character on an input line.
EDI will
issue the * prompt, signifying edit mode.

3.1.3

Text Access Modes

EDI provides two modes you can use to access and manipulate lines of
text in the input file.
(A line is defined as a string of characters
term:lnated by a carriage return.) The two modes are:
•

Line-by-Line Mode -- Allows access to one line of
time; backing up is not allowed.

•

Block Mode -- Allows free access within a block of lines, on a
line-by-line basis.
Backing up within a block is allowed;
backing up to the previous block is not allowed.
3-3

text

LINE TEXT EDITOR (EDI)

Block mode is the default text access mode.
In addition to these two text access modes, EDI provides a way to
process text in terms of "pages." This feature is described under the
heading Processing Text in Pages, in this section.

Line-by-Line Mode

In this mode, a single line is the unit of the input file available
for modification. Line-by-line mode is entered by issuing a BLOCK OFF
command and is terminated by issuing a BLOCK ON command.
The single available line
the "current" line -- is specified by a
pointer, which you can move sequentially through the file, starting
just before the first line in the file. You can manipulate the line
pointer using the locator commands and the text modification and
manipulation commands listed in Tables 3-5 and 3-6.
However, you
cannot easily direct the pointer backward within the file.
When you open a file at the beginning ~f an editing session, you can
specify that the first line be brought into memory and made available
for modification. This line remains in memory until you request that
a new line be brought in. The pointer then moves down the file until
the line you requested is encountered.
That line is brought into
memory and, as the current line, can be modified. When a new line is
brought in, the previous line is written into the output file, as are
all lines that may be passed over in reaching the new current line.
Once the pointer moves past a given line, that line is no longer
accessible unless you enter a TOF or TOP command (described in Section
3.4). TOF causes the input and output files to be closed, and the
output file to become the new input file. TOF also has the effect of
ending line-by-line mode.

Block Mode

In this mode, a portion of the input file is held in a buffer for
editing until you request that the contents of the buffer be added to
the output file.
In block mode you can access lines of text backward as well as forward
within the buffer. Thus, you can back up to a previously edited line
without having to reprocess the entire block or file, and without
having to issue a TOF command.
When you finish editing a block, you can write it out and read in the
next block with the RENEW command.
However, you cannot access a
previously edited block except by using TOF.
EDI buffer space is computed dynamically at run time. The number of
lines initially read into the buffer is computed by using the formula:
buffersize/132

3-4

ill

12221!ii

t I

!4 iii!! 2 I

LINE TEXT EDITOR (EDI)
A block is the number of lines read into the buffer by a RENEW or READ
command. This number is either:
1.

specified by the user by means of the SIZE command
is 38 lines if the SIZE command is not issued),

(default

or
2.

determined by the presence of a form feed at a point in the
text where the number of lines is less than that specified in
the SIZE command (or its default value,
if SIZE was not
issued).

When the current line pointer reaches End-Of-Block, the message
[*EOB*] is displayed and the current line pointer points to the last
line in the block. To move the current line pointer to the top of the
block, use TOP.
Table 3-2 provides a brief
line-by-line and block mode.

summary

the

differences

between

Table 3-2
Line-by-Line vs. Block Mode
Line-by-Line Mode

Block Mode

One line available for
modification at a time.

Entire block of lines available
for modification at a time, on
a line-by-line basis.

Lines can only be
accessed forward through
the file.

Lines can be accessed forward
and backward within a block.

Search commands can be
applied to search the
entire file.

Search commands search only
the block in memory.
To search more data, you must
read in another block.

Regardless of editing mode the line pointer always points to the first
character in the line.

Processing Text in Pages
EDI provides features that allow you to access portions of a text file
by page.
A "page" is a segment of text delimited by form feed
characters (the last page in a file is terminated by the end-of-file
marker}.
Two commands are provided to handle paged text -- FF, which defines a
page boundary by inserting a form feed; and PAGE, which accesses a
page of text.
(The commands PAGE FIND and PAGE LOCATE do not ref er to
form feed-delimited pages -- they are actually global searches.)
EDI handles paged text in block mode. If block mode is not already in
effect, it is entered when you issue a PAGE command.

3-5

LINE TEXT EDITOR (EDI)
If a form feed is encountered in text during a READ or RENEW
operation, the page thus delimited, for purposes of the READ or RENEW,
is interpreted as a block.
The message [PAGE n], issued after a READ or RENEW operation, gives
the value of EDI's page counter. If your text contains no form-feed
characters, the count is zero until the last block in the file is read
into the buffer.
Upon encountering the end-of-file, EDI increments
the page count to 1.

3.1.4

Text Files

The following sections describe how data may be added
the operations performed on output files.

files,

and

Input and Secondary Files
EDI accepts input from:
•

The input terminal (that is, commands and text entries)

•

Files-11 volumes that contain any of the following:
1.

The file to be edited

A secondary file

A save file

A macro f i 1 e

The input file is always preserved. 1 Any system failure, EDI failure,
or lack of space on the output volume does not cause the loss of the
input file. Only the output file is affected. In cases of failure,
the output file is not completely destroyed; it becomes a truncated
version of the input file containing all of the edits to the point of
failure.
In general, the current block buffer is not written to
error of this type occurs.

disk

when

Output Files
The output device defaults to the input device, as do the directory,
filename, and filetype, with the version number incremented by one.
If you wish to change any of these parameters
(except device and
directory), specify a completely new file specification when closing a
file or exiting at the end of an EDI session.

~ To delete the input file, use the CLOSE-AND-DELETE
EXIT-AND-DELETE command; or use PIP.

command

the

3-6

•1 Hs:ou: ma:

111

&!I iii!

L!J

I II

it .I

Pi Mi

LINE TEXT EDITOR (EDI)
3.1.5

Terminal Conventions

RSX-11 and EDI provide terminal keyboard functions
means to:

that

provide

the

•

Delete characters on an input line (MCR function)

•

Delete an entire input line (MCR function)

•

Move the current line pointer forward in a file (EDI function)

•

Move the
function)

•

Terminate an
function)

current
edit

line

pointer

session

Character Erase (RUBOUT or DELETE;

and

backward
pass

file

(EDI

control

MCR

(EDI

CTRL/R)

Typing the RUBOUT key
(marked DELETE on some terminals) deletes
individual characters if used before carriage return is pressed.
During editing operations, RUBOUT does not affect previously prepared
text.
When the RUBOUT key is typed it is echoed first as a backslash (\),
and is followed by the previously typed character. Each successive
RUBOUT typed results in the echo of an earlier typed character.
When
the first non-RUBOUT character is typed, it is echoed as a backslash
(closing the RUBOUT sequence) followed by the typed character.
For
example:
First RUBOUT typed
Second RUBOUT
Third RUBOUT
rFirst non-RUBOUT
MISTKAE\EAK\AKE
For some CRT terminals, RUBOUT (or DELETE) works in a more obvious
way.
Each RUBOUT typed causes the cursor to backspace, erasing the
previous character. Your CRT terminal may work this way if a certain
option was selected when your system was generated.
Another useful system generation option is CTRL/R. If this option was
selected, your system responds to CTRL/R by printing the incomplete
input line. For example, at a hardcopy terminal you enter:
MISTKAE rubout rubout rubout CTRL/R
The echoed result is:
MI STKA.E\EAK
MIST

Line Erase (CTRL/U)
CTRL/U deletes the line being input,
if typed before the line is
terminated with a carriage return. It is typed by holding down the
CTRL key and pressing U. CTRL/U echoes as ~u followed by carriage
return and line feed.

3-7

LINE TEXT EDITOR (EDI)
Carriage Return
The carriage return has the following effects, depending on how it
used:

•

When issued in place of an input file specification,
return causes EDI to terminate.

•

When issued in edit mode, carriage return causes the next line
to be printed. That line becomes the current line.

•

When issued in input mode as the only character in
line, carriage return causes a return to edit mode.

•

When issued alone after an
invokes input mode.

INSERT

command,

carriage

car~iage

input
return

ESCape or Altmode
When EDI is in edit mode, typing ESCape ~r Altmode) causes the
previous text line to be printed. That line becomes the current line.
ESC can be used this way only in block mode, not in line-by-line mode.

CTRL/Z
CTRL/Z causes EDI to terminate. EDI writes the remainder of the input
file into the output file and closes both files before terminating.
Use CTRL/Z to terminate EDI in edit mode, input mode, or in the middle
of an incomplete input line. CTRL/Z erases your last input line if
you enter the command as a line terminator.

3.1.6

EDI Command Conventions

EDI uses asterisks (*) and ellipses ( ••• ) in special ways described in
the following paragraphs.
Also described below is the notation
convention used to define EDI command abbreviations.

Use of Asterisk (*)
The asterisk character, *, can be used in
argument. It evaluates to 32767 (decimal).

place

any

numeric

Example
The following command results in the printing of the remainder of
the block buffer or file.
PRINT *
Use of Ellipsis ( ••• ) in Search Strings
In a number of the EDI commands, you must identify a string of
characters to be located and/or changed. To reduce the necessary
terminal entries, the more advanced user can employ the following
special string constructs. In these special cases, the ellipsis ( ••• )
represents any number of intervening characters.

""
-

; --·1?

3-8

·~. . . . .L•2•a•c::•::. uiii
.. .
::•aa. .:•1:•:1111:•::•:::::•:. . . . . .::.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14.,. . . .,•••, .

LINE TEXT EDITOR (EDI)
Case 1.

stringl.G.string2

Any string that starts with string!,
continues with any number of intervening
characters,
and ends with the first
occurrence of string2.

Case 2 • • • • string

Any string that starts at the beginning
of the current line and ends with the
first occurrence of string.

string •• ~

The first string that starts with string
and ends at the end of the current line.

Case 3.
Case 4.

The entire current line.

Examples
In the following examples, the CHANGE command is used with the
four cases of special string constructs given above.
In each
case the current line reads:
THIS IS A SAMPLE OF SPECIAL STRING CONSTRUCTS.
Case 1.

C /S A ••• E O/S AN EXAMPLE 0
results in
THIS IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS.

Case 2.

C / ••• SPEC/THIS IS AN EXAMPLE OF SPEC
results in
THIS IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS.

Case 3.

C /STRING ••• /EDI STRING CONSTRUCTS.
results in
THIS IS A SAMPLE OF SPECIAL EDI STRING CONSTRUCTS.

Case 4.

C / ••• /EXAMPLES OF SPECIAL EDI CONSTRUCTS.
results in
EXAMPLES OF SPECIAL EDI CONSTRUCTS.

Command Abbreviations
EDI permits the use of abbreviated commands.
Where these shorter
forms are allowed,
the command format specifications represent the
shortest acceptable form in upper-case letters.
Lower-case letters
may
be
entered
optionally.
The following example shows the
abbreviations allowed for the VERIFY command.
The command format
specification is:
Verify
The follow:lng abbreviations are valid for the VERIFY command:

v
VE
VER
VER!
VERIF
VERIFY
3-9

LINE TEXT EDITOR (EDI)
3.2

BASIC EDI COMMANDS

The basic EDI commands listed in Table 3-3 allow you to create a file,
to modify a file by adding, deleting, or changing its contents, and to
exit after the desired operations have. been completed. More detailed
description of each command .follows the table. These commands are the
most important EDI commands. As you become more familiar with EDI
operations,
the additional commands listed in Section 3.3 and
described in Section 3.4 will allow you to use all of EDI'S
capabilities.
Table 3-3
Basic EDI Commands
Command

Command Format

Description

ADD

Add string

Append string to current line.

ADD & PRINT

AP string

Append string to current line,
and print resultant line.

BOTTOM

Bottom

Move the current line pointer
to the bottom of the current
block (in block mode) and to
the bottom of the file
(in
line-by-line mode).

CHANGE

[n]Change /stringl/
string2[/]

Replace
n times

CTRL/Z

Type a control z

Close
files
and
editing
session.

DELETE

Delete [n]
or
Delete [-n]

Delete current line and n-1
lines
if n is (+);delete n
lines preceding current line if
n is
(-).
[-n] operates in
block mode only.

DELETE &
PRINT

DP [n] or DP [-n]

Same
as DELETE, except
current line is printed.

Type the ESC (or ALT)
key

Print previous line, and make
it new current line (block mode
only). Same as NP-1.

EXIT

EX it [f ilespec]

Close files,
rename
file,
and terminate
session.

INSERT

INsert [string]

Enter the string immediately
following the current line. If
no string is specified, EDI
enters input mode.

LOCATE

[n]Locate string

Locate
nth
occurrence
of
string.
In block mode, search
stops at end of current block.

string! with string2
in the current line.
terminate

new

output
editing

(continued on next page)

3-10

ii 12. i i :::SISJ I iii !i!J iiiiiii i i I 2iiii2

ItI

";;

!iii

::;

;a: s;

LINE TEXT EDITOR (EDI)
Table 3-3 (Cont.}
Basic EDI Commands
Command

Command Format

Next [n] or
Next [-n]

Establish new
current line n
lines away from current line.

NEXT & PRINT

NP [n] or NP [-n]

Establish and print new current
line.

Print[n]

Print current line and the next
n-1 lines.
The last printed
line is the new current line.

RENEW

RENew[n]

Write current block to output
file and read new block from
input file (block mode only}.

<RE:TURN>

Carriage return

Print the next line, make it
new current line;
exit from
input mode. Same as NP+l.

RE1~YPE

Retype string

Replace
current
line
with
string; or delete current line
if string is null.

TOP

Top

Move the current line pointer
to the top of the current block
(in block mode} or top of file
(in line-by-line mode}.
TOP
creates. a new version of the
file each time it is invoked in
line-by-line mode.

TOP OF FILE

TOF

Return to top of input file and
save
all
pages
previously
edited.
TOF creates a
new
version of the file each time
it is invoked. TOF reads in a
new block after writing the
previous block to the output
file.

3 .2 .. 1

Description

ADD

This command causes the specified string to be appended to the current
linE!.
Fon1al

Add string

3-11

LINE TEXT EDITOR (EDI)

Example
The following command completes the line HAPPY DAYS ARE HERE
*A AGAIN.
Note that the space after the A is the command terminator.
EDI
will not insert the space into the line. If a space is to
precede AGAIN., the command should be:
A<space><space> AGAIN.

ADD & PRINT

3.2.2

This command performs the same function as
that the new line is printed.

the

ADD

command,

except

following

command

Format
AP string

Example
Using the same line as the ADD command, the
causes the new line to be printed as follows:
*AP AGAIN.
HAPPY DAYS ARE HERE AGAIN.

3.2.3

BOTTOM

BOTTOM moves the current line pointer to the beginning of the last
line of the current block (in block mode), or to the beginning of the
last line of the file (in line-by-line mode). In block mode, the only
processing EDI performs is line pointer positioning. In line-by-line
mode, all the lines are copied from the input file to the output file
until EOF is reached. If VERIFY ON is specified, the last line of the
file block is displayed. Note, however, that if you deleted the last
line before you issued BOTTOM, the pointer will be located past the
text, and thus the last line will not be printed. BOTTOM performs the
same function as END (see Section 3.4.14).

~. .

···· 1

Format
Bottom

Example
*V ON
*BO
THIS IS THE LAST LINE
In this example, the current line pointer is moved to the
of the block buffer and the last line is displayed.

bottom

3-12

l$ll

!iii

:;;

till!

I !IL

ii.;

i.ldli4li J I.iii! I 4 U

LINE TEXT EDITOR (EDI)
3.2 .. 4

CHANGE

This command searches for stringl in the current line and,
if found,
replaces it with string2. If stringl is given but cannot be located
in the current line, EDI prints [NO MATCH] and returns an * prompt.
If stringl is null (not given), string2 is inserted at the beginning
of the line. If string2 is null, stringl is deleted from the current
1 in~:!.
The search for stringl begins at the beginning of the current line and
proceeds across the line until a match is found.
The characters that delimit stringl and string2 are normally slashes
(/) ..
However, any matching characters not contained in the specified
string may be used. The first character following the command is the
beginning delimiter;
the next matching character ends the string.
Thus, characters used as delimiters must not appear in the string
itself. The closing delimiter is optional.
If you precede the command with a number n, the first n occurrences of
stringl are changed to string2. After each replacement of stringl
with string2, scanning restarts at the first character in the line.
This allows you to generate a string of characters as shown in the
example below.
If no match occurs, a [NO MATCH] message is displayed.
Forllllat

[n]Change /stringl/string2[/]
Exa:mple

TO SEPERATE THE THOUGHTS, USE SEPERATE SENTENCES.

'-''

2C/SEPE/SEPA/
TO SEPARATE THE THOUGHTS, USE SEPARATE SENTENCES.

3.2.5

Typing CTRL/Z (holding the ~TRL key down while typing the letter Z)
terminates the editing session. If an output file is open when CTRL/Z
is typed, all remaining lines in the block buffer and the input file
are transferred (in that order) into the output file, all files are
closed, and EDI exits. These actions occur whether EDI is in edit or
input mode.
If EDI is prompting for another file specification when
CTRL/Z is entered, all files are closed (including any open secondary
input file), and EDI exits.
If you enter CTRL/Z as an input line
terminator, that line is erased.

3 .2 .6

DEI.ETE

This command causes lines of text
manner:
1.

deleted

the

following

If n is given and is a positive number, the current line and
n-1 following lines are deleted. The new current line is the
line following the last deleted line.

3-13

LINE TEXT EDITOR (EDI)
2.

If n is given and is a negative number, the current line is
not deleted, but the specified number of lines that precede
it are deleted.
The line pointer remains unchanged.
A
negative value for n can be used only in block mode.

If n is null, the current line is deleted, and the next
becomes the new current line.

line

Format
Delete [n]
or
Delete [-n]
Example
To delete the previous five lines in the block buffer,
following command:

type

the

*D -5

3.2.7

DELETE & PRINT

This command performs the same function as the DELETE command, except
that the new current line is printed when all lines have been deleted.
Format
DP

[n]

or
DP [-n]
If n is not specified, +l is assumed.
be used only in block mode.

A negative value for n can

Example
If the following lines are contained in a file:
THIS IS LINE l
THIS IS LINE 2

i:i~ i~ ti:~ ~

and the line pointer is at the first line, the following
obtains the results shown below:

command

*DP 2

THIS IS LINE 3

3.2.8

<E~Cape>

This command prints the previ?US line in the block (block mode only).
That line becomes the current line. Thus, you can back up through a
block, one line at a time, by typing a series of ESCapes.
Typing
ESCape is equivalent to typing NP-1 (NEXT & PRINT command).

3-14

n11 I

Hill

i I

i!iiSS(

!Ji

IS !llU:

ill!&

LINE TEXT EDITOR (EDI)
3.2.9

EXIT

This command transfers all rema1n1ng lines in the block buffer and
input file (in that order) into the output file, closes the files, and
terminates the editing session. If a file specification is used, the
output file is renamed to the specified filename.
Fornaat

EXit [filespec]
Exanaple

The C<>mmand:
*EX
terminates the editing session without renaming the output
It causes EDI to display:

file.

[EXIT]
The output filename.filetype is the
same
as
the
input
filename.filetype, with a version number one greater than that of
the input file.

3. 2 .• 10

INSERT

This command inserts string immediately following the current line.
The string becomes the new current line. If string is not specified,
EDI enters input mode.
For1nat

Insert [string]
Exa1nple

*I TEXT INSERT IN EDIT MODE

Insert
a
immediately
line.

*I
TEXT INSERT 1 IN INPUT MODE
TEXT INSERT 2 IN INPUT MODE

An I
followed by a carriage
return causes EDI to switch
to input
mode.
A
series
of new lines may be input
following the current line.

ETC.

A carriage
character
causes EDI
mode and
command.

3.2.11

line
of
text
after the current

return as the only
in an input line
to return to edit
to prompt for a new

LOCATE

This command causes a search for the pattern string, beginning at the
line following the current line. The string may occur anywhere in the
line sought. The line pointer is positioned to the line containing
the match. When the line is located, it is printed if VERIFY ON is in
effect.
3-15

LINE TEXT EDITOR (EDI)

LOCATE applies to the block buffer if EDI is in block mode and to
input file if in line-by-line mode.

the

P·ormat

"""

[n] Locate string

Example
The following command can be used to locate the line
ARE HERE AGAIN.

HAPPY

DAYS

*L ppy

EDI searches the file or block buffer and (if VERIFY ON is
specified) prints the line when it is located. The current line
pointer is set to the located line.
If string is not specified, the line following the current line
is considered a match, and the line pointer is positioned there.
If "n" is specified, the nth occurrence of string is located.

3.2.12

This command moves the current lir.e pointer backward and forward in
the file.
A positive number moves the current line pointer n lines
beyond the current line; a negative number moves the current line
pointer backward n lines.
Format
Next [n]
or
Next [-n]
If n is not specified, a value of +l is assumed.
can be used only in the block mode.

negative

Example
In the block mode, the following command moves the
pointer back five lines:

current

line

This command has the same effect as the NEXT command, except that
new current line is printed.

the

*N -5

NEXT & PRINT

3.2.13

Format
NP [n]
or
NP [-n]
The following conventions can be
complete NP command:

used

place

issuing

Pressing the carriage return key is the same as an NP+l command.

3-16

'W'I

ts 2

au:; t

I iii I ii i !ii

LINE TEXT EDITOR (EDI)
Pressing the ESCape (or ALTmode) key while in the block
the same as an NP-1 command.

mode

If n is not specified, then a value of +1 is assumed.
Exam1ple

Assume the following four lines are contained in the file and the
line pointer is at the first line.
LINE 1 OF THE FILE
LINE 2 OF THE FILE
LINE 3 OF THE FILE
LINE 4 OF THE FILE
If the! following command is issued,
printout:

EDI

returns

the

fallowing

*NP 2
LINE 3 OF THE FILE
*
LINE 4 OF THE FILE
* <ESC>
LINE 3 OF THE FILE
* <ESC>
LINE 2 OF THE FILE

3.2.14

This command prints out the current line and the next n-1 lines on the
terminal;
the last line printed becomes the new current line. If it
is not specified, a value of l is assumed.
Fornaat

Print [n]
Exa111tple

The following example illustrates both the
commands:

3-17

and

the

TYPE

LINE TEXT EDITOR (EDI)
Before
File A

File B

Line v

Line A
Q i s the

Line w

Line B
Line c

Line Pointer

Line x

Line D

Line y

Line

*TYPE 5

*PRINT 5

Line A

Line v

Line B

Line w

Line c

Line x

Line D

Line y

Line E

Line

After

3.2.15

File A

File B

Line A

Line v

Line B

Line w

Line c

Line x

Line D

Line y

Line

Line z

RENEW

This command writes the current block buffer into the output file and
reads a new block from the input file. The optional value n is a
repetition count: if you specify n, the process is repeated n times.
The intermediate blocks are written into the output file, and the last
block is left in the block buffer. If n is not specified, a single
RENEW is performed.
This command may be used only in block mode.
Refer to Section 3.1.3 for information on how EDI block buffers are
processed.
Format
RENew [n]

3-18

220 It I I

iiii2 I

iii

iiiii!

ii ii

iii

II i

t 142

ti! 1144 au

LINE TEXT EDITOR (EDI)
Exam;ple

*RENEW 10
Ten consecutive blocks are transferred from the input file to the
block buffer.
The initial contents of the block buffer and the
next nine blocks are transferred to the output file. The current
line pointer points to the first line in the tenth block, which
is currently in the block buffero

3.2.16

In edit mode, this command prints the next line in the file or block
buffer.
That line becomes the current line. Thus, you can scan
through a file or block, one line at a time, by typing a series of
RETURNs. This command is equivalent to NP+l (NEXT & PRINT command).
In input mode, a single carriage return
input mode to edit mode.

3.2.17

causes

EDI

return

from

If string is

not

RETYPE

This command replaces the current line with string.
specified, the line is deleted.
Forniat

Retype [string]
Exa11ttple

*R THIS IS A NEW LINE
The string THIS IS A NEW LINE replaces the current line.

3.2.18

TO:P

TOP sets the current line pointer to the top of the current block
(in
block mode) or to the top of the file (in line-by-line mode). When
the current line pointer is positioned via TOP, you can enter lines
preceding the first line in the block or file.
TOP differs from TOF in the following ways:
line-by-line mode, TOP creates a new file and moves the
• In
current line pointer to the top of the file. Unlike TOF, it
does not cause EDI to return to block mode.
•

In block mode, TOP moves the current line pointer to the top
of the current block and does not create a new output file.
TOF moves the current line pointer to the top of the file and
creates a new output file.

Format

Top

3-19

LINE TEXT EDITOR (EDI)
Example
*TOP
This command directs the current line pointer to the top
current block in block mode.

3.2.19

the

TOP OF FILE (TOF)

This command creates a new version of the file and returns the current
line pointer to the first line of the file. TOF processing copies the
input file into the output file, closes both, then opens the latest
version of the file as the input file. If you issue this command when
in line-by-line mode, EDI switches to block mode after saving the
edited data. The first block is read into the block buffer.
Format
TOF
Example
*TOF
This command writes the previously edited pages into the output
file,
resets the current line pointer to the top of the input
file, and reads the first block into the block buffer.

3.3

EDI COMMANDS: FUNCTION SUMMARY

EDI commands can be arranged by functional similarity;
for example,
all the commands you use to locate a string can be grouped under the
function heading "Locator Commands." This section contains summaries
of the following command categories:

3.3.1

•

Setup commands - select operating conditions, close
files, select data modes.

•

Locator commands - control the position of the current line
pointer, and thus determine which text line is acted upon.

•

Text modification commands - change text lines.

•

Macro commands - define, store, recall, and use
EDI commands.

sequences

•

File input/output commands
input/output, and save files.

•

Device output commands - send output to terminal or printer.

•

Close and exit commands - terminate editing operations.

transfer

text

and

open

of
from

Setup Commands

The setup commands allow you to enable or disable certain special
features of EDI. Among these features are the block and line-by-line
text access modes, already mentioned, and the automatic verification
of LOCATE commands. Setup commands are listed in Table 3-4.
3-20

225U!ISl121$ C II

I I!

Li iiililiiiii

$!lit ii I I ;:m:; JU

LINE TEXT EDITOR (EDI)

Table 3-4
EDI Setup Commands
Command

Format

BLOCK ON/OFF

BLock [ON] or
BLock OFF

Switch text access modes.

CONCATENATION
CHAHACTER

cc [letter]

Change concatenation character
to specified character (default
is &) •

OPEN SECONDARY

OPens filespec

Open specified secondary file.

OUTPUT

ON/OFF

output ON or
output OFF

Continue
or
discontinue
transfer
to
output
file
(line-by-line mode).

SELl~CT

PRIMARY

Reestablish
input file.

SELl~CT

SECONDARY

Select opened secondary file as
input file.

SIZI~

SIZE n

Specify maximum number of lines
to be read into block buffer.

TAB

TAb [ON] or
TAb OFF

Turn
off.

UPP.ER CASE
ON/OFF

UC [ON] or
UC OFF

Enable or disable conversion of
lower-case characters entered
from
terminal to upper-case
characters.

VERIFY

Verify [ON] or
verify OFF

Select
whether locator
and
change commands are verified.

3.3.2

ON/OFF

Description

primary

automatic

file

tabbing

on or

Locator Commands (Line-Pointer Control)

During editing operations, EDI maintains a pointer that identifies the
current line
(that is,
the line to which any subsequent editing
operations refer).
Commands that modify the line pointer's location
are called locator commands;
they are listed in Table 3-5.
The locator commands allow you to:
•

Set the line pointer to either the top or bottom of the
file or block buffer.

input

•

Move the line pointer a specified number of
its current position.

away

from

•

Move the line pointer
string.

given

text

line

lines

containing

In edit mode, the carriage return and ESCape (or ALTmode) keys act to
relocate the line pointer.
A single carriage return moves the pointer
to the next line. A single ESCape moves the line pointer back one
linE! (in block mode only).
In each case the line is printed.

3-21

LINE TEXT EDITOR (EDI)
If VERIFY ON is in effect, the located line is printed after a BOTTOM,
END, FIND, PAGE FIND, PAGE LOCATE, or SEARCH & CHANGE command.
Table 3-5
EDI Locator Commands
Command

Description

Format

BEGIN or
TOP

Begin
Top

Set current line to the line
preceding top line in
file
(line-by-line mode) or block
buffer (block
mode).
Both
commands create copies of the
file each time they are invoked
in
line-by-line
mode.
The
commands are equivalent.

BOTTOM or
END

Bottom
End

Set current line to last line
in file or block buffer.
The
commands are equivalent.

<ESCape>
(or ALTmode)

Type ESC (or ALT)
key

Print previous line and make it
new current line.
(Block Mode
only.)

FIND

[n]Find [string]

Search current block or input
file,
beginning
at
line
following current line for the
nth
occurrence
of
string.
String must begin in column l.
Set line pointer to located
line.

LOCATE

[n]Locate string

Locate
nth
occurrence
of
string.
In block mode, search
stops at end of block.

Next [n]
Next [-n]

Establish new current line n
lines away from current line.

NEXT & PRINT

NP [n] or NP [-n]

Establish and print new current
line.

PAGE
(Block
Mode Only)

PAGe n

Enter block mode. Read page n
into block buffer. If n is less
than current page number, do
TOF first. Pages are delimited
by form feed characters.

PAGE FIND
(Block
Mode Only)

[n]PFind string

Search successive blocks for
the nth occurrence of string.
String must start in column l.

PAGE LOCATE
(Block
Mode Only)

[n] PLocate string

Search successive blocks for
the nth occurrence of string.
String may occur anywhere in
line.

Carriage return

Print the next line, make it
the current line;
exit from
input mode.

SEARCH &
CHANGE

SC /stringl/string2[/] Locate stringl
with string2.

and replace it

3-22

'm111

t SI ii I lit hii!ii i LS 2 I iiiiii .I iiii!JL iii!iiiii

.ii I I.ii

liiii iii! Ziii!L

!ill Jtf I

z;; :a "a

I ii# ii

LINE TEXT EDITOR (EDI)
3.3.3
~

Text Modification and Manipulation Commands

The text modification and manipulation commands enable you
text. Table 3~6 lists these commands.

modify

Table 3-6
EDI Text Modification and Manipulation Commands
Command

Description

Format

ADD

Add string

Append string to
line.

ADD & PRINT

AP string

the
Append
string to
current line and print
resultant line.

CHANGE

[n]Change/stringl/
string2[/]

Replace
stringl
with
string2 in the current
line n times.

DELETE

Delete [n] or
Delete [-n]

Delete
current line and
(+);
n-1 lines if n is
delete n lines preceding
current line if n is(-).
[-n] operates in block
mode only.

DELETE & PRINT

DP [n] or DP [-n]

Same as DELETE except new
current line is printed.

ERASE

ERASE [n]

Erase the current line if
in line-by-line mode.

,.. I
~/

""'

current

Erase the current block
buffer and the next (n-1)
blocks, if in block mode.
FOHM FEED

Insert form feed
into
block
buffer
(used to
delimit a page).

INSERT

Insert string

following
Enter string
current line, or enter
input mode if string is
not specified.

LINE CHANGE

[n]LC /stringl/
string2[/]

Change all occurrences of
string! in current line
(and
n-1
lines)
to
string2.

OVlmLAY

Overlay [n]

Delete n lines,
enter
input mode,
and insert
new line (s) as typed,
in
place
of
original
line (s).
(continued on next page)

3-23

LINE TEXT EDITOR (EDI)
Table 3-6 (Cont.)
EDI Text Modification and Manipulation Commands

'~
I

Command

Description

Format

PASTE

PAste /string 1/
string2[/]

Search
all
remaining
lines in f iel or block
buffer for stringl and
replace with string2.

RETYPE

Retype

Replace the current line
with string;
or delete
the
if
line
current
string is nu 11.

TOP OF FILE

TOF

Return to the top of the
input file and save all
pages previously edited.

UNSAVE

UNSave [f ilespec]

from
Insert all lines
specified file following
current
If
line.
not
f ilespec
is
is
specified, SAVE.TMP
used.

3.3.4

Macro Commands

These commands allow you to define, store, recall, and use macros.
A
macro is a series of EDI commands that, once defined, can be executed
repeatedly using just a few keystrokes. Table 3-7 lists the macro
commands.
Table 3-7
EDI Macro Commands
Command

Format

Description

MACRO

MACRO x definition

Define macro number x. Up to
three macros can be defined.

MACRO CALL

MC all

Retrieve macro
definitions
stored in file MCALL;n.

MACRO EXECUTE

[n]Mx [a]

Execute macro x [n] times,
numeric
while
passing
argument [a].
The value x
may be 1, 2, or 3.

MACRO
IMMEDIATE

[n] <definition>

Define and execute a macro n
times.
Store it as macro
number 1.

3-24

·:1n1 :::

:zut .!!4 es ;zss

I I

i i .:

i4J iii !St 2i!i 41 : 2 ::m n:: :um

LINE TEXT EDITOR (EDI)
3. 3. 5

FilE! Input/Output Commands

Input/output commands control
the movement of text
to and
input/output, and save files.
Table 3-8 lists these commands.

from

Table 3-8
EDI Input/Output Commands
Format

Command

Description

FILE

FILe filespec

Transfer lines from input
file
to both the output file and the
specified file
until a
form
feed
or
end-of-file
is
encountered.
(Line-by-line
mode only.)

REJ~D

REAd

[n]

Read next n blocks of text into
b 1 o ck
bu ff e r •
If
buff e r
is
contains text,
new text
appended to it.

RENEW

RENew

[n]

Write the current block to
the
output file and read new block
from the input file.

SAVE

SAve

[n]

WRITE

Write

3.3.6

Device Output Commands

[filespec]

Save current line and the next
n-1
lines
in the
specified
file.
If filespec
is
not
given,
lines are saved in file
SAVE.TMP.
SAVE
puts
the
temporary file
in the UFD and
on the device of the file you
are editing.
You can override
the default
by specifying a
different device and UFD.
Write contents of block
buffer
to output file and erase block
buffer.

These commands direct output to your terminal or
(CL:).
They are listed in Table 3-90

3.3.7

pseudo-device

CLOSE and EXIT Commands

The CLOSE and EXIT commands terminate EDI operations and write the
remainder of the input file into output file.
Table 3-10 lists these
commands.

3-25

LINE TEXT EDITOR (EDI)
Table 3-9
EDI Device Output Commands
Command

Description

Format

LIST ON TERMINAL

LI st

Print on the terminal all lines
remaining in block buffer (block
file
mode}
or
input
(line-by-line mode}, beginning
at current line.

LIST ON PSEUDODEVICE

Same as LI, except that printing
is performed on pseudo-device
CL:.

Print [n]

Print the current line and the
next
n-1
lines.
The last
printed line is the new current
line.

TYPE

TYpe [n]

Print
next
n
lines.
In
line-by-line mode, identical to
PRINT command. In block mode,
line pointer remains at current
line, unless end-of-block was
reached.

Table 3-10
EDI Close Operation Commands
Command

Format

Description

CLose [filespec]

Transfer rema1n1ng lines
in
block buffer and input file, to
output file and close files.
If file specification is used,
output file is renamed.
EDI>
prompt is issued.

CLOSE SECONDARY

CLOSES

Close secondary file.

CLOSE & DELETE

CDl [f ilespec]

Same as CLOSE, except
input file is deleted.
prompt is issued.

CTRL/Z

Type a control Z

Close files, and terminate edit
session.

EXIT

EX it [f ilespec]

Close files,
file,
and
session.

EXIT & DELETE

EDx [f ilespec]

Transfer remaining
lines
in
block buffer and input file to
output file, and close file.
Rename
file
if
file
specification is given.
Delete
input file and terminate EDI.

KILL

Close input and output files,
delete output file. EDI> prompt
is issued.

that
EDI>

rename
output
terminate
edit

'!'':~

3-26

"r• Ziiiiiii .JC I 2i2 !!!$

;sq:

!!Sit i2!1!!1

iii

I;::

!J1$4iliiil4Jll!IUI It

LINE TEXT EDITOR (EDI)
3.4

EDI COMMANDS: DETAILED REFERENCE SUMMARY

This section lists each EDI command in alphabetical order.
Each
command description comprises the function of the command and the
command format.
Most descriptions include examples
and
usage
information.
The exceptions are the basic commands, which are
described in detail in the preceding section. In this section, only
the function and format of basic commands are described.

3.4.1

ADD

ADD causes the specified string to be appended to the current line.

Forn1at
Add string
For examples and information describing
Section 3.2.1.

how

use

ADD,

refer

except

that

the

new

ADD & PRINT (AP)

3.4~2

ADD & PRINT performs the same function as ADD,
lirn:! is printed.

ForJDat
AP string
For examples and information describing how to use ADD & PRINT,
to Section 3.2.2@

3.4.3

refer

BEGIN

BEGIN sets the current line pointer to the beginning of the file in
line-by-line mode, or to the beginning of the block buffer in block
mode. The current line is one line preceding the top line in the file
or block buffer. Thus, you can insert text at the beginning of a file
or block.
If EDI is in line-by-line mode, BEGIN copies the input file into the
output file, closes both, then opens the latest version of the file.
BEGIN performs the same function as TOP.

Format
Begin

Example

In this example, the current line pointer is moved to the top
the block buffer (block mode is assumed).

3-27

LINE TEXT EDITOR (EDI)
3.4.4

BLOCK ON/OFF

This command allows you to switch between block mode and line-by-line
mode.
When you enter BLOCK ON, block mode becomes active, and the
next block of text is brought into the block buffer. When you enter
BLOCK OFF, the current block being processed is written to the output
file, and line-by-line mode becomes active. The first line from the
next sequential block in the input file becomes the current line.
If you enter an unnecessary BLOCK command (for example, BLOCK ON
EDI is already in block mode}, the command is ignored.
BLOCK ON is the default text access mode.
ON nor OFF is specified.

It is assumed when

when

neither

Format
BLock [ON]
or
BLock OFF
Example
*BLOCK ON
This command causes EDI to switch to block mode.
of text is read into the block buffer.

3.4.5

The next

block

BOTTOM

BOTTOM sets the current line pointer to the beginning of the last line
of the block
(in block mode} or of the input file (in line-by-line
mode}.
Format
Bottom
For examples and information on how to use BOTTOM,
3.2.3.

3.4.6

refer

Section

and,

found,

refer

Section

CHANGE

CHANGE searches for stringl
replaces it with string2.

the

current

line

Format
[n] Change /stringl/string2[/]
For examples and information on how to use CHANGE,
3.2.4.

3.4.7

This command transfers all remaining lines in the block buffer and
input file
(in that order} into the output file, and closes both
files. If a file specification is included, the output file is

3-28

ill.

ill

u:;arn: u

ilti

1111

I ....

IIll

ii . iii!!

221

25 ;:

{JI t i I !Iii.ii . .

LINE TEXT EDITOR (EDI)
renamed to the specified file.
EDI then returns to its initial
command sequence, prompts with EDI>, and waits for you to type another
file specification.
If a secondary file was opened during the editing session and was
closed, it remains open.

not

Fornnat
CLose [file spec]
Exannple

*CL
EDI>
This command closes both input and output files, and EDI
to the initial command sequence.

3.4.8

returns

CLOSE SECONDARY (CLOSES)

Use this command when you have finished extracting text from a
secondary input file.
You must enter CLOSES before you can use
another secondary file as input.

Forn1at
CLOS EB

CLOSE & DELETE (CD)

3.4o9

This command transfers all remaining lines in the block buffer and the
input file
(in that order)
into the output file, and closes both
files.
The input file is then deleted.
If a file
specification is
included,
the output file
is renamed to the specified file.
This
command acts like CLOSE, except that the input file is deleted.
If a secondary file was opened during the editing session and was
closed, it remains open.

\._,)

not

Forrnat
CDl [ :f i lespec]

3.4.10

CONCATENATION CHARACTER (CC)

The concatenation character allows you to give commands on one input
line.
By default,
the concatenation character is &. To reference
text containing an & (for example in LOCATE or CHANGE commands),
you
must change the concatenation character to some other character.
If the CC command is used
character is changed to &.

without

Fonnat
CC [letter]

3-29

argument,

the

concatenation

LINE TEXT EDITOR (EDI)

Example
*CC :
*L A&B:C /A&B/ABC/
CONCATENATION TEST CONTAINING A&B.
CONCATENATION TEST CONTAINING ABC.
*CC

"""
1 ::;...

In this example, the string to be located contains an ampersand.
Therefore,
the concatenation character must be changed to a
different character before EDI can locate the line.
The first command line
character from & to ••

changes

the

default

concatenation

The second command line instructs EDI to locate the string A&B
and change that string A&B to ABC.
(Note:
this line contains
two commands that are concatenated by the new concatenation
character, :.)
The third command line changes the concatenation
to the normal default value, &.

3.4.11

character

back

CTRL/Z

CTRL/Z is an MCR function that terminates the edit session. You enter
CTRL/Z by pressing the CTRL key and the Z character key at the same
time.
For usage information on CTRL/Z, refer to Section 3.2.5.

3.4.12

DELETE

~:··'. ~ ~~ ~

DELETE deletes a specified number of lines from a file.

Format
Delete n
For examples and information on how to use DELETE,
3.2.6.

3.4.13

refer

Section

DELETE & PRINT (DP)

DELETE & PRINT performs the same function as DELETE, except that it
displays the new current line after the specified lines are deleted.

Format
DP n
For examples and information on how to use DELETE &
Section 3.2.7.

PRINT,

refer

3-30

Ill "

as: :::Iiimt: ::;: u:: .: : : :

I II II

ii I I I I

i I Hi!iii$22 IU !iiil$2ji iii5&! ill i &I

LINE TEXT EDITOR (EDI)
3.4.14

ENI>

END sets the current line pointer to the beginning of the last line of
the block or input file. If EDI is in block mode, only line pointer
positioning occurs. In line-by-line mode, all lines are copied from
the input file to the output file until EOF is reached. The last line
in the block or file is displayed if VERIFY ON is in effect.
Note,
hoWE!ver, that if the last line was deleted before issuance of END, the
pointer will be located past the text, and thus the last line will not
be printedo END performs the same function as BOTTOM.
Foniat

End
Exa11!lple

*V ON
*END
THIS IS THE LAST LINE
This command moves the current line pointer to the bottom of
block buffer (block mode is assumed).

3.4.15

the

ERASE

In line-by-line mode, this command erases the current line.
In this
mode n may only be 1. In block mode, this command erases the current
block buffer and the next n-1 blocks. If n is not specified, +l is
assumed.

....,.

Fonnat

ERASE [n]
Exa1mple

*ERASE 5
This command causes the contents of the current block buffer and
the next 4 blocks to be erased. These blocks are not written
into the output file.

3.4.16

This command prints the previous line in the block (block mode only).
That line becomes the current line. Thus, you can back up through a
blc1ck, one line at a time, by typing a series of ESCapes.
Typing
ESCape is equivalent to typing NP-1 (NEXT & ~RINT command).

3 • 4, • l 7

E)CI T

EXIT writes all remaining records to the
files, and terminates the edit session.
Format

EXIT [f ilespec]

3-31

output

file,

closes

the

LINE TEXT EDITOR (EDI)

For examples and information on how to
3.2.9.

Section

This command functions in the same way as the CLOSE & DELETE
except that EDI exits when finished.

command,

3.4.18

use

EXIT,

refer

EXIT & DELETE (ED)

Format
EDx [filespec]
Example
*EDX NEWFILE.DOC
[EXIT]

>
3.4.19

FILE

This command -- legal in line-by-line mode only -- transfers lines
from the input file to both the output file and a specified file,
beginning with the current line, until a form feed character is
encountered as the first character in a line or until end-of-file is
reached. At that time the specified file is closed.
The form feed
character is not included in the specified file. During the transfer,
the original file remains intact {i.e., all lines written to the
specified file are also written to the normal output file, including
the form feed). When the command is complete, the current line in the
input file is one line beyond the form feed.

_.-...
~,,,,.,""ll

BLOCK OFF must be in effect for FILE to work properly.
If the specified file does not already exist, a new file is created.
If the specified file does exist, the latest version of the file
contains the new data.
Format
FILe filespec
Example
*FIL SEC.DAT
EDI writes the contents of the input file, from the current
to the end, into both the output file and the file SEC.DAT.

3.4.20

line

FIND

This command searches the block buffer or input file for a string,
beginning at the line following the current line. The string must
begin in column 1 of the line matched. The line pointer is positioned
at the line containing the match. When the line containing the string
is found, it is printed if VERIFY ON is in effect.
FIND applies to the block buffer if EDI is in block mode
input file if EDI is in line-by-line mode.

and

the

3-32

'!11121

iiij I 2$

;uei

ii:;

Lil

;.: I

iii

I ;

i!IG

ii !iii!!! I 2

Iiiiii!; 4

LINE TEXT EDITOR (EDI)
If a string is not specified, the line following the current line is
considered a match.
If n is specified, the nth occurrence of the
str:ing is found.

ForJRat
[n]Find [string]

Exa1nple

*V ON
*F LOOK
LOOK AT THE FIRST CHARACTER IN THE LINE.
In this example, EDI searches the block buffer (or file) for a
line that begins with LOOK and prints the line when it is found.

3.4.21

FORM FEED (FF)

This command allows you to insert form feeds into the text,
in order
to delimit EDI pages.
The form feed is inserted after the current
line, and the new current line becomes the line containing the form
feed.

Format
FF

Example
*P
THIS IS THE LAST LINE ON THE PAGE
*E'F

In this example, a form feed is inserted into the text
the current line.

3 • 4, • 2 2

following

IM SERT

INSeRT inserts a string immediately following the current
string becomes the current line.

line.

The

Format
Insert [string]
For examples and information on how to use INSERT,

refer

Section

3.2.10.

3 •4 •23

K:C LL

This command returns EDI to the initial command sequence without
retaining the output file. When this command is executed, the input
file is closed, and the output file is deleted.

Foirmat
KILL
3-33

LINE TEXT EDITOR (EDI)

Example
*KILL
EDI>

In this example, the output file is deleted, and EDI displays the
prompt:
EDI>

At this point, you can return control to MCR by means of
or enter a file specification for a file to be edited.

3.4.24

CTRL/Z

LINE CHANGE (LC)

This command is similar to CHANGE, except that all occurrences of
string! in the current line are changed to string2. A numeric value n
preceding the command changes the current line and the next n-1 lines.
If string2 is null, all occurrences of string! are deleted. New lines
are printed if the VERIFY ON command is in effect.
If string! is given but EDI cannot locate the string
line, EDI prints [NO MATCH] and returns an * prompt.

the

current

Format
(n]LC /stringl/string2[/]

Example
If the current line is:
THES ES THE LINE TO BE ESSUED.
The following command would correct the errors:
*V ON
*LC /ES/IS
THIS IS THE LINE TO BE ISSUED

3.4.25

f',

'~.··.
·'~"·

LIST ON TERMINAL (LI)

This command prints on your terminal all remaining lines in the block
buffer (block mode) or all remaining lines in the input file
(line-by-line mode}, beginning at the current line. At the end of the
listing, the current line pointer is repositioned to the top of the
input file or block buffer.
If terminal host synchronization is installed at system generation,
you can control printing functions using CTRL/O, CTRL/S, and CTRL/Q.
To suppress printing at any point, type CTRL/O.
Printing can be
suspended temporarily with CTRL/S, and resumed with CTRL/Q.
Format
LI st

3-34

1111.

!. J iii

UJ!i\i Si ili i

.i . i. ILUU Iiii!J

iii

iii!!

I.iii 4 SE

I i i2 !iii!& I

I 2$.ILUI

;21 4411; : :

LINE TEXT EDITOR (EDI)
Exam];> le

*LI
This command causes all rema1n1n9 lines in the block buffer or
all remaining lines in the input file to be printed on the
terminal.

3.4.26

LIST ON PSEUDO-DEVICE (LP)

This command functions .in the same manner as the LIST ON TERMINAL
command, except that the remaining lines in the block buffer (block
mode) or the remaining lines of the input file (line-by-line mode) are
listed on the pseudo-device CL:. In most systems, CL: is set to the
system line printer.
Form.at

*LP
This command causes all remaining lines in the block buffer or
all remaining lines in the input file to be printed on the
pseudo-device CL:.

3.4.27

LOC:ATE

LOCATE searches for a string beginning at the line following the
current line. The string can occur anywhere in the lines searched.
ForDlat

[n] Locate string
For examples and information on how to use LOCATE,

refer

Section

3.2 .. 11.

3.4.28

MACRO

This command is used to define macros. Space is available for three
macro definitions.
The definition portion can be any legal EDI
command or string of legal EDI commands connected by the concatenation
character.
If a numeric argument is to be passed to the macro at execution time,
a percent sign (%) must be inserted in the macro definition at the
point where the numeric argument is to be substituted. Then the value
passed via the MACRO EXECUTE command replaces the percent sign when
the macro is executed.
A MACRO definition may contain more than one percent sign.
If it
does, the single numeric value given in a MACRO EXECUTE command
replaces each percent sign. However, a macro may not have two or more
independent arguments.

3-35

LINE TEXT EDITOR (EDI)

Format
MACRO x definition
x

Specifies the macro number (1, 2, or 3).

Examples
To find the nth occurrence of the string ABC in the current block
and replace that occurrence and all remaining occurrences within
the block with the string DEF, the following macro could be used:
*MACRO 1 %L ABC&PA /ABC/DEF
The following command executes the macro
tenth and succeeding occurrence of ABC.

and

searches

for

the

*M 1 10
The following macro definition and subsequent invocation could be
used to change all occurrences of the strings ABC and GHI to DEF
and JKL, respectively. The substitution is made in the current
block and the next four blocks (five blocks in all).
*MACRO 1 PA /ABC/DEF/&PA /GHI/JKL/&RENEW
*SM 1

3.4.29

(MACRO command)
(MACRO EXECUTE command)

MACRO CALL (MC)

This command allows you to retrieve up to three macro definitions
previously stored in a file. The macro definitions must contain only
the "definition" portion of the MACRO command. The macro definitions
are stored in successively numbered macros: the first definition
becomes macro 1, etc.
The file used to store the macro definitions must be the latest
version of file MCALL -- that is, MCALL;n. The filetype must be null
or blank. If the macro definitions to be loaded are in a file of
another name, you can use the PIP COPY command, with the /NV switch,
to rename the file. Refer to Chapter 4 for descriptions of PIP
commands.

~
r~

Format
MC all
Strings of concatenated EDI commands can be written as EDI macro
definitions, and up to three EDI macro definitions can be stored in
file MCALL;n. The MC command is used to call the latest version of
file MCALL and move the three definitions into the macro storage area.
Then you can execute the desired macro without having to type the
complete command.
Macro calls may not be nested.
The concatenation character may precede, but not follow, a macro call.

3-36

lC!ZfA i

iii

!i!iii!ij

212 i i $4!

Ip:

LINE TEXT EDITOR (EDI)
Exanaple

*MC
This command retrieves the macro definitions stored in file
where n represents the latest version of the file MCALL.

3.4 .. 30

MCALL;n,

MAC::RO EXECUTE

This command executes macro x n times, while passing it the optional
numE~ric
argument. a.
If a macro numeric argument is defined via the
percent sign (%) in the macro definition, the numeric argument
contained in this command is passed for each execution of the macro.
Before a macro can be executed, it must either have been defined via a
MACRO command, or called via a MACRO CALL command.
Using this command, any one of the three macro definitions stored
the EDI macro storage area can be executed any number of times.

Forrnat

[n]Mx [a]
n

Specifies the number of times the macro is to be executed.

x
Specifies the macro number (1, 2, or 3).
a

Specifies the numeric argument to be passed when the
executed
(ignored if % argument is not present
definition).,

macro is
in macro

Exa1mples

*2Ml
Execute macro number l twice.
*3M2 5
Execute macro number 2 three times, passing the numeric
5 each time the macro is executed.

argument

The example in Section B.3.4 illustrates how to use the EDI macro
commands in editing a file.

3.4.31

MACRO IMMEDIATE

This command defines and executes a macro in one step. The definition
is enclosed within angle brackets and is identical to that of the
MACRO command. The definition is copied into the macro l storage area

3-37

LINE TEXT EDITOR (EDI)
and immediately executed n times. The macro may also be subsequently
executed by entering an Ml command. The command is equivalent to the
two macro commands:
MACRO 1 definition
nMl
Format
n<def inition>
Example

*<L ABC&C /ABC/DEF>
This command causes EDI to search the current block buffer for
the string ABC and, when it locates ABC, to change the string to
DEF. This macro is stored as macro number 1.
The example in Section B.3.3 illustrates the
IMMEDIATE command.

3.4.32

use

the

MACRO

NEXT moves the current line pointer backward and forward in the file.
A positive number moves the current line pointer forward; a negative
current line number moves it backward.
Format
Next [n]
or
Next [-n]
For examples and information on how to
3.2.12.

3.4.33

use

NEXT,

refer

Section

NEXT & PRINT

NEXT & PRINT performs the same function NEXT performs, except that the
new current line is displayed.
Format
NP

[n]

or
NP [-n]
For examples and information on how to use
Section 3.2.13.

3.4.34

& PRINT,

refer

OPEN SECONDARY

This command opens the specified secondary input file.
The primary
input file, if any, remains open. Subsequent text is read from the
primary input file until the secondary input file is selected via the
SELECT SECONDARY command (SS) for input.

3-38

111111

I iii2

iii t i!ii

LINE TEXT EDITOR (EDI)
Forn1at

OPens filespec
Example

*OPENS RICKS.MAC

*·ss
*.READ l
The file RICKS.MAC is opened as a secondary input
selected for input; then the first block is read in.

3 • 4 ,, 3 5

file

and,

OUTPUT ON/OFF

This command, used only in the line-by-line mode, allows you to
continue or discontinue the transfer of text to the output file.
OUTPUT ON is the default condition; it is automatically reestablished
each time a CLOSE command is issued.
FonRat

output ON
or
output OFF
If neither ON or OFF is specified, ON is assumed.
Exa1nple

*BLOCK OFF
*OUTPUT OFF
*N 5
*OUTPUT ON

'-''

This example shows how to bypass five lines of text in the input
file so that these lines are now written into the output file.
The first command sets line-by-line mode.

The second command disables the transfer of text
file.

the

The third command bypasses five consecutive lines
the input file.

text

The fourth command reenables the transfer of text to
file.

3.4.36

the

output
from
output

OVERLAY

This command deletes n lines and replaces them with any number of
lines that you type.
If n is not specified, the current line is
deleted and replaced with the lines typed. When you enter the OVERLAY
command, EDI enters input mode. All text that you type goes into the
file until you enter a carriage return as the only character in an
input line.
For:mat

Overlay [n]
3-39

LINE TEXT EDITOR (EDI)

Example
*O 2

This command deletes two lines and
mode.

3.4.37

causes

EDI

enter

input

PAGE

This command causes EDI to enter block mode, if not already in block
mode, and read page n into the block buffer. A page is delimited by
form feeds. If n is less than the current page number, a TOF command
is performed first.
TOF processing writes the input file to the
output file, closes both files, then opens the latest version of the
file.
If n is greater than the current page number, the necessary number
RENEW commands is executed to read page n into the block buffer.

Format

Example
*PAG 1

[00050 LINES READ
[00050 LINES READ
[00050 LINES READ
[00050 LINES READ
[00017 LINES READ
[PAGE 1]

IN]
IN]
IN]
IN]
IN]

*
This example shows a quick way to get to the last block in a file
that contains no form feed page delimiters. EDI's page count is
not incremented unless it encounters form feed characters or an
end-of-file mark. Thus, in a file without form feeds (i.e., most
files}, EDI renews the block buffer until it encounters an
end-of-file mark. Note that the final block contains 17 lines of
text.

3.4.38

PAGE FIND

This command performs the same function as the FIND command, except
that successive blocks are searched until the nth occurrence of the
string has been found. The contents of the block buffer and the
blocks between the current block and the block in which the nth
occurrence of the string is located are copied into the output file.
The string must begin in column 1 of the matched line.
The line is
printed if VERIFY ON is in effect. This command may be used only in
block mode.
Format
[n]PFind string

3-40

11111;;

I I I I iliiiij!2

.liilll4"4

iii£!

:a:

:u ;u: ;;:;; "II

LINE TEXT EDITOR (EDI)
3. 4. 39

PAG:E LOCATE

This command causes a search of the current block, starting at the
line following the current line, and of successive blocks until the
nth occurrence of the string has been located. Text from the current
block buffer is written into the output file. The string can occur
any place in the lines checked. The line is printed if the VERIFY ON
command is in effect. This command may be used only in block mode.
Formi11t

[n]PLocate string
This command is used in the same manner as the LOCATE command,
except that the specified string can be in a block other than the
current block.
PL leaves the current line pointer at end-of-file
locate string.

3 .4 .·40

cannot

PASTE

This command is identical to the LINE CHANGE command, except that all
lines remaining in the input file or block buffer are searched, and
all occurrences of stringl are replaced with string2. Modified lines
are printed if the VERIFY ON command is in effect. If stringl is
given, but no match is found, then EDI returns an * prompt. When the
command completes, the line pointer is at the top of the buffer or
input file.
Format

PAste /stringl/string2[/]

Exam:ple
If the lines remaining in the block buffer contain the
text:

following

YIGER, YIGER, BURNING BRIGHY
IN YHE FORESYS OF YHE NIGHY
they can be corrected with the following command:

* P/J~/Y/T
If the VERIFY ON command is in effect, all corrected
printed. To discontinue printing, type CTRL/O.

3.4.41

lines

are

PRINT displays the current line and the next n-1 lines
terminal; the last line printed becomes the current line.

the

Format
Print [n]
For examples and information on how to use
3.2.14.

3-41

PRINT,

refer

Section

LINE TEXT EDITOR (EDI)
3.4.42

READ

Thfis combmand r:ads t he ndext.n blocksbofftext ihnto thebl blko(ck) .buf(fer.)
I
a
uf er, t e new
oc s is are
1 ock is a 1 rea y in the
appended to it.

EDI must be in block mode before this command can be executed.
A READ command may not exceed the buffer capacity.
If you issue a
READ that is too large, EDI fills its buffer and then issues the
following message:
[BUFFER CAPACITY EXCEEDED BY)
<offending line>
[LINE DELETED]
You may get this message after issuing a READ n command, where n is 2
or larger, unless you have used the SIZE command to reduce the number
of lines per block below its initial number.
Format

REAd [n]
If n is not specified, a value of l
must be positive.

is assumed.

The value

Example

*SIZE 15
*READ 4
This example reads four 15-line blocks of the input file into the
block buffer.

3.4.43

RENEW

RENEW writes the current block buffer into the output file and reads a
new block from the input file. Renew is used only in block mode.
Format

RENew [n]
For examples and information on how to use

RENEW,

refer

Section

3.2.15.

3.4.44

In edit mode, <RETURN> represents the carriage return that displays
the next line in the file or block buffer. In input mode, entering
the carriage return returns EDI to edit mode. For information on EDI
command modes, refer to Section 3.1.2. For information on <RETURN>,
refer to Section 3.2.16.

3-42

·1111111

Qii .Lil ..

t;aq iiiiii

I ii.iiiiiiiii

II I ii

4111

;:u !Iii::;

LINE TEXT EDITOR (EDI)
3 • 4 • ·4 5

'-"'

RETYPE

RETYPE replaces the current line with string.

Retype [string]
For information on how to use RETYPE, refer to Section 3.2.17.

3 • 4 •.4 6

SAVE

This command causes the current line, and the next n-1 lines, to be
saved in the specified file.
If the file already exists, a new
version is created.
If no file is specified, the save file generated has the name
SAVE.TMP.
SAVE puts the temporary file in the UFO and on the device
of the file you are editing.
The input file or buffer information that is transferred to the SAVE
file remains intact.
The new current line is the last line saved.
The SAVE command does not delete lines in the block buffer or input
file.
Format
SAve [n]

[f ilespec]

Example
You can save and later insert small groups of lines in several
places in an output file by using the SAVE and UNSAVE commands.
For example, a file called EDIT.MAC contains six lines that you
want to insert at several points in another file called HELP.MAC.
The procedure is:
l.

Start an editing session using
file.

Locate the lines to be inserted into HELP.MAC.

Issue a SAVE 6 command.
(This copies the six
be saved into the file SAVE.TMP.)

Issue a KILL command to terminate the editing session.

Start a new editing session using HELP.MAC as the
file.

Locate each place the six lines are to be
issue the UNSAVE command.

inserted

and

Make further edits to the input
EXIT.

desired,

the save file remains on

the

EDI does not delete the save file;
specified volume until deleted.

3-43

EDIT.MAC

file,

the

input

lines

input

LINE TEXT EDITOR (EDI)
3.4.47

SEARCH & CHANGE

This command causes a search for stringl in the block buffer (block
mode) or input file
(line-by-line mode), beginning at the current
line. The string may occur anywhere in the line.
When stringl is
located, it is replaced by string2. The located line becomes the
current line.
If stringl is not specified, EDI prints the error message for illegal
string construction. The new current line is printed if the VERIFY ON
command is in effect. If stringl is given but EDI cannot locate the
string, EDI returns an * prompt, and the line pointer is positioned at
the end-of-file or the bottom of the block buffer.
Format
SC /stringl/string2[/]

Example
If the following incorrect
block:

line

contained

the

current

THES IS THE LINE TO BE ISSUED.
the following command can correct the error:
*V ON
*SC /THES/THIS/
THIS IS THE LINE TO BE ISSUED.
The corrected line is printed since the VERIFY ON command
effect.

3.4.48

SELECT PRIMARY

This command selects the primary file for input.
It allows you to
reestablish the primary input file as the file from which text is
read.
Format
SP

Example
*OPENS SECOND.MAC
*SS
*RENEW 10
*CLOSES
*SP
This example directs EDI to:
1.

Open the secondary file SECOND.MAC.

Select SECOND.MAC as the secondary input file.

Read ten consecutive block buffers from the secondary
input file into the block buffer. The first nine blocks
are automatically transferred to the output file.

3-44

:s;z

f&ZZ; & 4

121

iii

ll!ii!iji I J :::;:::;a; llW

LINE TEXT EDITOR (EDI)

3.4.49

Close the secondary input
file
SECOND.MAC.
The
secondary file need not be closed before the primary
file is reselected for input.

Reselect the primary input file for input.

SELECT SECONDARY

With this command you select the secondary file as the input file.
Format

SS
Example

To add text to the output file from a secondary input file, you
must first open the secondary input file and select it for input.
The use of the SS command is illustrated in the example presented
in the previous section.

3.4.50

'-"1

SUE

This command allows you to specify the maximum number of lines to be
read into the block buffer on a single READ or RENEW command. The
default value for SIZE is
dependent
on
your
exact
system
configuration.
Initially EDI determines how much buffer space it has
and divides that by 132(10}, the maximum line size, to set the number
of lines read in.
In no case can it be less than 38 lines.
(See
discuss ion of Block Mode in Sect ion 3 .1. 3.)
Formiat

SIZE n
Examiple

*SIZE 50
This command conditions EDI to read 50 lines
buffer during a single READ or RENEW command.

3.4.51

into

the

block

TAD ON/OFF

This command turns automatic tabbing on or off.
The automatic tab
feature is useful for MACR0-11 language input. TAB OFF is the default
at the start of an editing session. When TAB ON is in effect, a tab
(equivalent
to eight spaces) is automatically inserted at the
beginning of each input line unless the line either begins with a
label followed by a colon, or contains a semicolon in the first
column.

3-45

LINE TEXT EDITOR (EDI)

Format
TAb [ON]
or
TAb OFF
If neither ON nor OFF is specified when a TAB command is
ON is assumed.

issued,

Example
*TAB ON
*I
; THIS IS A SAMPLE OF TABBING.
THIS LINE GETS A TAB
l: THIS ONE DOESN'T
END
*TAB OFF
*N -3
*P 4
; THIS IS A SAMPLE OF TABBING.
THIS LINE GETS A TAB
l:
THIS ONE DOESN'T
END

3.4.52

TOP

TOP sets the current line pointer to the top of the block buffer (in
block mode) or to the top of the file (in line-by-line mode). In
line-by-line mode, TOP creates a new version of the file.
When the
current line pointer is positioned via TOP, you can insert lines
preceding the first line in the file.

~
T'lliJ

"!:~:.
""

: ...../

Format
Top
For examples and information on how

use

TOP,

refer

Section

3.2.18.

3.4.53

TOP OF FILE (TOF)

TOF returns the current line pointer to the first line of the file and
leaves you in block mode. TOF copies the input file to the output
file, closes both, and opens the latest version of the file as the
input file.
Format
TOF
For examples and information on how

use

TOF,

refer

Section

3.2.19.

3-46

1111111: J

2i I

ii f

I I4

! i2P

LINE TEXT EDITOR (EDI)
3 .4. 54

TYl>E

This command is similar to the PRINT command (Section 3.2.14).
In
line-by-line mode, the two are identical. In block mode, TYPE does
not move the line pointer after displaying the requested text, except
if the end-of-block is encountered. In this case the line pointer
remains at the last line before the end-of-block.
If n is not specified, a value of 1 is assumed.
Format

TYpe [n]
Example

See the example of the PRINT command (Section 3.2.14).

3 .4.,55

UNSAVE

This command retrieves all the lines in a specified file and copies
them after the current line.
If no file is specified, the file
defaults to SAVE.TMP. The new current line pointer is positioned at
the last line retrieved from the file. The file used in this command
can be any text file;
it is often the file created with a SAVE
command.
Fon11at
UNSavi~

[file spec]

Exa111aple

File SEC.DAT;l contains a group of lines to be inserted after the
current
line.
The following command performs the desired
operation.
*UNS SEC.DAT;l
Section B.3.2 contains an
commands.

3 • 4 ,, 5 6

example

using

the

SAVE

and

UNSAVE

UPJ?ER CASE ON/OFF

This command allows you to enter lower-case characters from a terminal
and have them converted to upper-case characters. If UPPER CASE OFF
is :issued, all input characters are accepted as they are entered (no
conversion is performed), except that all EDI commands are converted
to upper-case characters.
(If entered as lower-case characters, EDI
commands are still echoed in lower case.)
Format
UC [ON]
or
UC OFF
If neither ON nor OFF is specified, then ON is assumed.
the default when EDI is started.

3-47

UC ON is

LINE TEXT EDITOR (EDI)

Example

*UC OFF
*I this line is entered in lower case
*UC ON
*I this line is converted to upper case
Assuming that the input terminal is capable of generating
lower-case input, the command in the example above would create
the following lines in the output file.
this line is entered in lower case
THIS LINE IS CONVERTED TO UPPER CASE
However, in both instances, the characters are converted to upper
case before the file is closed.
To create a file containing lower-case characters, use
SET /LOWER-=TI: command and the EDI UC OFF command.

3.4.57

the

MCR

VERIFY ON/OFF

This command controls the display of lines specified by the LOCATE and
CHANGE commands.
Use VERIFY ON to display a line located by the
LOCATE command or to display a line changed by the CHANGE command.
Use VERIFY OFF to inhibit the display of these lines. EDI is in the
VERIFY ON mode at the start of editing.
Format

Verify [ON]
or
Verify OFF
If neither ON nor OFF is specified, ON ls assumed
Example

*V OFF
*L VERIFY
*P
LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON
*N -2
*V ON
*L VERIFY
LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON
In this example, the PRINT command is issued to demonstrate that
the desired line has been located when VERIFY is OFF, but when
the LOCATE command is reissued with VER.IFY ON, EDI automatically
prints the line.

3.4.58

WRITE

This command causes the entire contents of the block buffer to
written into the output file. The block buffer is then erased.

EDI must be in block mode before this command can be executed.

3-48

;u4

iii!!

CiJ

ill

:;::

I jJ

th ;z;;

LINE TEXT EDITOR (EDI)
.Format

Write
Example

*W
*REA 2
In this example, the block buffer is written into the output file
and the block buffer is erased. Then, the next two blocks are
read into the block buffer.

3.5

EDI USAGE NOTES

The
following
points
contain
general
information
involving
restrictions on use of EDI, system device considerations, and general
usage rules.
•

EDI can operate only on Files-11 format files and rejects
other file formats.

•

The output file generated by EDI always resides on the same
device as the input file. The output file cannot be directed
to another device. For example:
To edit a file on DECtape and store
disk, do one of the following:

•

the

resulting

all

file

Transfer the file to disk and perform the editing there.

Edit the file on DECtape and then use PIP to transfer
file to disk.

To use a device other than SYO:, mount it via
command.

the

MCR

the
MOUNT

edit a version
• To
explicitly state

of a file other than the latest one,
the desired version number in the file
specification. This file is opened as the input file;
the
version number of the output file is one greater than the
latest version of the file.

•

Some EDI commands (such as TOF, and TOP when it is used in
line-by-line mode) implicitly generate multiple versions of a
file.
In the execution of such commands, EDI copies the
remainder of the input file into the output file and closes
both of them. It then opens the latest version of the file
and uses it as input. This ensures the editing of the latest
version of the file and provides periodic backup.
To delete
any unwanted versions, use PIP with the /PURGE switch.

•

EDI accepts variable-length input lines up to
long.

132

characters

•

The record type of
variable-length ..

EDI

•

EDI preserves the record attributes of the input file.
For
example,
the FORTRAN carriage control attribute is preserved
in the output file.

output

files

3-49

edited

always

LINE TEXT EDITOR (EDI)
•

Line feed characters may be entered in files but
are
interpreted by EDI as termination characters. You should
avoid using them since they cause unpredictable results when
the file is edited a second time.

~.·

~····r~
...•
I

•

3.6

EDI cannot process a file that contains embedded carriage
control characters, such as PIP directory listings and TKB map
files. To reformat such a file for EDI processing, copy the
file to a DOS-11 volume and then back to your original volume
using FLX. EDI can then process the file.

EDI ERROR MESSAGES

The four classes of EDI error messages are:

• Command level information messages
• File access error messages
• Error messages requiring EDI restart
• Fatal error messages •
The following sections describe all the messages that may be displayed
in each class. If the recovery procedure is not evident, a suggested
user action is given.

3.6.l

Command Level Information Messages

Messages in this class indicate information that is designed to be
helpful to you or to identify errors that were encountered in the
previous command. All messages in this class are enclosed within
square brackets and followed by a prompt for a new command. For
example, the following output occurs if a DELETE command encounters an
end-of-buffer in block mode:
[ *EOB*]

*
The messages in this class follow.

.~
~·~··pT~

[BUFFER CAPACITY EXCEEDED BY]
of fending line
[LINE DELETED]
Explanation: A READ, UNSAVE, INSERT, or OVERLAY command has
exceeded the capacity of the block buffer. The line that caused
the overflow is displayed and deleted.
User Action: If a new file is being created, empty the
with a WRITE command and continue the editing session.

buffer

If an existing file is being edited, it may be possible to
continue via a RENEW or WRITE command. Otherwise, use the CLOSE
command to close the output file and save all edits. Reopen the
output file as the input file and, using the SIZE command, reduce
the number of lines read into each buffer; then, using the PAGE
LOCATE command, search to the position in the file where editing
is to continue.

3-50

JA!iii!

iiiii

14 :. : s:. a;:uam:;::;::u

LINE TEXT EDITOR (EDI)
Occasionally, this message results when you try to open a file
that was not created by EDI. You can overcome this difficulty
via the SIZE command procedures that follow:
1.

Type KILL.

When EDI prompts for a new file specification, enter a
EDI creates a new file and enters
nonexistent filename.
input mode.

Type carriage return to enter edit mode.

Using the SIZE command, reduce the number of lines read
each buffer.

Use the KILL command to abandon the file.

When EDI prompts for a new file specification, enter the name
of the desired file.

into

[CREATING NEW FILE]
INPUT

Explanation: The input file specified in the command does not
exist and EDI has created a new file.
EDI automatically enters
input mode and waits for the input of text lines.
User Action: If you intend to create a new file,
continue
entering new lines as required. Otherwise, enter edit mode by
typing carriage return;
use the KILL command to delete the
undesired
new
file.
When
EDI prompts for a new file
specification, enter the correct file specification.
[ILL CMD]

Explanation: Either EDI does not recognize the command, or you
have entered a command that is not compatible with the current
mode (e.g., a READ command in line-by-line mode).
[ILL NUM]

Explanation: Either you have supplied a non-numeric character
when a numeric is required, or you have given a negative number
when a positive number is required.
[ILL STRING CONST]

Expla.nation: A search string specified in a CHANGE, LC, PASTE,
or SC command does not contain a matching string termination
character {e.g., PASTE /ALPHABETA, instead of PASTE /ALPHA/BETA).
[ILLEGAL IN BLOCK ON MODE]

Explanation: You have tried to execute a command that is illegal
in block mode, such as FILE or OUTPUT ON/OFF.

3-51

LINE TEXT EDITOR (EDI)

[ILLEGAL FILE NAME GIVEN IN CLOSE OR EXIT]
or
[FILE WAS NOT RENAMED]
Explanation: A syntactically incorrect file specification was
given in a CLOSE or EXIT command, the attempt to rename the
output file failed, or the attempt to EXit or Close to rename the
file to another device failed.
User Action:

Use PIP to rename the file, if desired.

[MACRO NOT DEFINED]
Explanation: You have tried to execute a macro with
command, but the specified macro has not been defined.

the

User Action: Use the MACRO command to define the
and then execute it with the M command.

macro

desired

[MACRO NUMERIC ARG UNDEFINED]
Explanation: You have tried to execute a macro without supplying
a numeric argument. The macro definition, however, contains the
% character and thus demands a numeric argument.
User Action: Retype
numeric argument.

the

command,

specifying

the

appropriate

[MCALL FILE DOES NOT EXIST]
Explanation: An MCALL command has been executed to define a
of macros, but the file MCALL cannot be found.

set

User Action: The desired set of macro definitions may exist
under another User File Directory. If this is the case, use PIP
to copy or rename the MCALL file into the current directory.

[NO INPUT FILE OPEN]
Explanation: A PAGE, READ, or RENEW command has been attempted
while a new file is being created (that is, while there is no
input file).
These commands can be executed only when an
existing file is being edited.

[NO MATCH]
Explanation: A CHANGE command has specified
changed that is not in the current line.

string

[OVERLAYING PREVIOUSLY DEFINED MACRO]
Explanation: A MACRO command has resulted in the redefinition of
a previously defined macro. This message lets you know that the
previous definition is no longer in effect.

3-52

.1, 2

;sz

L L

LU. Li. JI!

.. I

I.I I . I . I iii#iiiUllUU ...

LINE TEXT EDITOR (EDI)
[SAVE FI LE DOES NOT EXIST]

Explanation:
located.

The file specified in an UNSAVE command

cannot

User Action: If you provided a file specification, make sure it
is correct.
If you did not give a file specification, this
message means that no previous SAVE command (without file
specification) was issued.
[SECONDARY FILE ALREADY OPEN]

Explanation: You may have tried to open a secondary input file
while another secondary file is still open. Or you may have a
secondary file open when you issue a CLOSE or KILL command, or
when EDI encounters an error and is forced to restart. The
former case represents an error: the latter informs you that you
still have a secondary file open.
User Action: Close the secondary input file using the CLOSES
command, and then open the desired secondary file with the OPENS
command.
[SECONDARY FILE CURRENTLY SELECTED FOR INPUT]

Explanation: A CLOSE or KILL command has been issued, or an
error has caused EDI to restart, when a secondary input file is
open and selected for input.
User Action:

Issue an SP command, then a CLOSES command.

[SYNTAX ERROR]
Explanation~

A command has been entered

that

syntactically

incorrect.
[TOO MANY CHARS]

Explanation: A CHANGE, LC, PASTE, SC, or ADD command has
resulted in a line that contains too many characters. EDI lim1 ts
the length of a line to 132 characters.
User Action:

Retype the line to ensure that the line is valid.

[*BOB*]

Explanation: The beginning-of-buffer has been reached.
The
current line pointer is positioned just before the first line in
the buffer. Thus, new text lines can be entered before the first
line.
[*E:OB*]

The current
Explanation: The end-of-buffer has been reached.
line pointer now points to the end of the buffer. Thus, if new
lines are inserted, they appear after the last text in the
bu ffHr.

3-53

LINE TEXT EDITOR (EDI)
[*EOF*]
Explanation:

The end-of-file has been reached on the input file.

User Action: If the editing session is complete, use the CLOSE
or EXIT command to close the output file. Otherwise, use the TOF
command to return to the first block in the file.

3.6.2

File Access Error Messages

.Messages in this class mean that you have tried to access directories,
files~
or devices that
message is prefixed with:

are

not

present in the host system.

Each

returns

level

and

Explanation: The file name was not accepted by EDI.
The
common error is a file name containing embedded blanks.

most

User Action:
reenter it.

and

EDI -After the message is displayed, EDI
prints an asterisk to request input.

command

The messages in this class follow.
EDI -- BAD FILE NAME

Make sure

that

the

file

name

correct,

EDI -- DEVICE NOT IN SYSTEM
Explanation: You have given a
command, specifying a device
system.

FILE, OPENS, SAVE, or UNSAVE
that does not exist in the host

User Action: Reenter the command line, specifying
available in the system.

only

devices

EDI -- FILE DOES NOT EXIST
Explanation: You have given a FILE or SAVE command, specifying a
user file directory that does not exist on the speaified volume.
NOTE
The rema1n1ng error messages in this
class should not occur and represent
failures in EDI.
If
such
errors
persist, submit a Software Performance
Report.
EDI -- BAD DEVICE NAME
EDI -- DEVICE NOT READY

3-54

: ::s am 2411

;;

)ii

I ;s:a !!&$$

Z.i!A4J

LINE TEXT EDITOR (EDI)
EDI -- FILE ALREADY OPEN

EDI -- RENAME NAME ALREADY IN USE
EDI -- RENAME ON TWO DIFFERENT DEVICES
EDI -- WRrrE ATTEMPT TO LOCKED UNIT

3.6"3

Error Messages Requiring EDI Restart

The error messages described in this section are caused by conditions
that make it impossible for EDI to continue the current editing
session. EDI closes all open files (with the exception of any open
secondary input file),
reinitializes, and then prompts for the next
file to be edited.
As with file access warning messages, each message in
prefixed with:

this

class

EDI
After the appropriate message has been displayed, EDI prompts with:
EDI>

~·

You may terminate the editing session at this point by typing carriage
return or CTRL/Z, or you may continue by entering another file
specification. If a secondary file was open when the error condition
was encountered, it remains open.
The messages in this class follow.
EDI -- BAD RECORD TYPE - FILE NO LONGER USABLE
Explanation: The record type defined in the header block of the
input file (primary input, secondary input, UNSAVE, or MCALL) is
not supported by File Control Services (FCS);
thus, the file
cannot be used for input to EDI.
User Action: The referenced file has been created without using
FCS, or the file structure on the volume is damaged. In the
latter case, verify the file structure with the verification
utility (VFY) to determine the extent of the damage. VFY is
described in Chapter 13.
EDI -- FILE IS ACCESSED FOR WRITE
Explanation: The input file
(primary input, secondary input,
UNSAVE, or MCALL) is currently being written by another task.
User .Action: Wait for the write to complete,
command line.

3-55

then

reenter

the

LINE TEXT EDITOR (EDI)
EDI -- FILE IS LOCKED TO WRITE ACCESS
Explanation: The output file (text output, FILE, or SAVE) is
currently accessed for read by one or more tasks and is locked
against all writers.
User Action: Wait for all readers of the file
reenter the command line.

finish,

then

EDI -- ILLEGAL RECORD ATTRIBUTES - FILE NOT USABLE
Explanation: The record attributes defined in the header block
of the input file
(primary input, secondary input, UNSAVE, or
MCALL) are not supported by FCS; thus, the file cannot be used
for input to EDI.
User Action: The referenced file has been created without using
FCS, or the file structure on the volume is damaged. In the
latter case, run the file structure verification utility (VFY) to
determine the extent of the damage. VFY is described in Chapter
13.
EDI -- PRIMARY FILE NOT PROPERLY CLOSED
Explanation: When the primary input file was last written, a
close check was specified, and the writing task did not properly
close the file (e.g., the task was aborted).
Thus, the file
attributes
were
not
written,
and the file may contain
inconsistent data.
User Action: Exit from EDI by typing carriage return or CTRL/Z.
Run the Peripheral Interchange Program (PIP) and use the /UN
switch to unlock the file. Reinitiate EDI and try to recover the
data in the file.
EDI -- PRIVILEGE VIOLATION
Explanation: A privilege violation occurred during a file access
for one of the following reasons:
1.

The specified volume is not mounted.

The UIC under which EDI is running does not possess
necessary privileges to access the specified directory.

The UIC is not privileged to access the specified file.

the

User Action: If the volume is not mounted, then mount it using
the MCR MOUNT command.
Otherwise, reinitiate EDI under a UIC
that has appropriate access privileges to both the specified
directory and file.
EDI -- RECORD IS TOO LARGE FOR USER BUFFER
Explanation: The input file
(primary input, secondary input,
UNSAVE, or MCALL) being accessed was not created by EDI (or SLP)
and contains records that are too large.
The maximum record
length supported by EDI is 132 bytes.

3-56

211; 411 "j

·'*

Lt .L:.: t n..rs: 22 u:4::2aqa:a.:.

LINE TEXT EDITOR (EDI)
EDI -- SECONDARY FILE NOT PROPERLY CLOSED - NOT USABLE
Explanation: When the secondary input file was last written, a
close check was specified, and the writing task did not properly
close the file (e.g., the task was aborted).
Thus, the file
attributes
were
not
written,
and the file may contain
inconsistent data.
User Action: Run PIP and use the /UN switch to unlock the
Reinitiate EDI and try to recover the data in the file.

file.

EDI -- BAD DIRECTORY SYNTAX
Explanation:

Directory field ([g,m]) is in improper format.
NOTE

The remaining error messages in this
class should not occur and represent
failures in EDI.
If
such
errors
persist, submit a Software Performance
Report.
EDI -- DUPLICATE ENTRY IN DIRECTORY
EDI -- END OF FILE
EDI -- ILLEGAL RECORD ACCESS BITS - FILE NOT USABLE
EDI -- ILLEGAL RECORD NUMBER - FILE NOT USABLE

Fatal Error Messages

3.6.4

'-'/

The fatal error messages represent system and/or hardware conditions
that make it impossible for EDI to continue execution. All files are
closed and EDI terminates its execution.
The output file may be
truncated. Each error message is prefixed with:
EDI -and followed by the exit message:
[EXIT]
on the next line.
The advanced user may work with the following procedures on the
truncated version of an output file to save the editing performed
before the fatal error occurred.
l.

Use PIP to rename the truncated version of the output file to
avoid confusion.

Restart the editing session to the original input file.

3-57

LINE TEXT EDITOR (EDI)
3.

Issue an OPENS command, specifying the renamed
secondary file.

file

the

4. , Issue an SS command to select the secondary file for input.
5.

Issue an ERASE command to erase the first block of the input
file
(unless the truncated output file did not contain the
entire first block).

Issue as many READ 1 and WRITE commands as necessary to reach
the EOF on the secondary file.

Issue an SP command to select the primary file for input.

Issue a CLOSES command to close the secondary file.

Issue a WRITE command to ensure
written into the output file.

that

the

last

block

was

10. Issue as many READ 1 and ERASE commands as necessary to
bypass all input file blocks that are complete in the renamed
file.
11. Continue the normal editing session.
The messages in this class follow.
EDI -- CALLER'S NODES EXHAUSTED
Explanation: System dynamic storage has been depleted, and
insufficient space is available to allocate the control blocks
necessary to open, close, read, or write a file.

,,F

'"""'
,.

User Action: This probably is a system failure, but it could
also represent a transient overload condition. Wait until system
load has diminished and reinitiate EDI.

. i

EDI -- DEVICE FULL
Explanation: Insufficient space exists on the output
extend an output file (text output FILE, or SAVE).

volume

User, Action: Determine which volume is being written. If it is
required that the specified file be written on this volume, then
space must be made available. Use PIP to purge (/PU) or delete
(/DE) unwanted files.
EDI -- FILE HEADER CHECKSUM ERROR
Explanation: An input file
(primary input, secondary input,
UNSAVE, or MCALL) has a header block that does not contain a
proper checksum.

User Action: The file structure on the specified volume is
damaged.
Run the file structure verification utility (VFY) to
determine the extent of the damage. VFY is described in Chapter
13.

3-58

I.I

IJl!i

iii

$ 121

I !j I ii!Z i!i2 j(.121 iil!. 44 21 jl 22

LINE TEXT EDITOR (EDI)
EDI -- FILE HEADER FULL
Explanation: Insufficient retrieval pointer space exists in the
header block to extend an output file (text output, FILE, or
SAVE),,
User Action: Split the file into two or more files
them separately.

and

process

the

device

EDI -- FILE PROCESSOR DEVICE WRITE ERROR
Explanation: This error message may indicate
specified for an output file is write-locked.
User Action:
Unlock the device if
it
Otherwise, a hardware problem may exist.
field service representative.

that

is
write-locked.
Consult the DIGITAL

EDI -- INDEX FILE FULL
Explanation: The file header block is not available to create an
output file
(text output, FILE, or SAVE). When a volume is
initialized, the maximum number of files that may be created on
the volume is established.
Your write request would have
exceeded this maximum.
User Action: Determine which volume is being referenced. If it
is required that the specified file be created on this volume,
then space must be made available. Use PIP to purge (/PU) or
delete (/DE) unwanted files.
NOTE
The following error messages signify
hardware problems. If possible, remove
all important files from the volume.
EDI -- BAD BLOCK ON DEVICE
EDI -- FILE PROCESSOR DEVICE READ ERROR
EDI -- HARDWARE ERROR ON DEVICE
EDI -- PARITY ERROR ON DEVICE
NOTE
The remaining error messages in this
class should not occur and represent
failures in EDI.
EDI -- BAD DIRECTORY FILE
EDI -- BAD PARAMETERS ON A QIO

3-59

LINE TEXT EDITOR (EDI)
EDI

INVALID FUNCTION CODE ON A QIO

EDI

NO BLOCKS LEFT

EDI

REQUEST TERMINATED

EDI

UNEXPECTED ERROR - EDITOR WILL ABORT

EDI -- WRITE ATTRIBUTE DATA FORMAT ERROR
TASK " ••• EDI" TERMINATED

3-60

l!J!iii ;4 J

!A.!4

.I.I

. ! iiiillli i I 1#21 i.iii!IQ!l22& Ji!! U4!iiii$0:111112

'-'

PART 3
FILE MANIPULATION UTILITIES

CHAPTER 4
.PERIPHERAL INTERCHANGE PROGRAM (PIP)

The Peripheral Interchange Program (PIP) is an RSX-11 file utility
program that transfers data files from one standard Files-11 device to
another. PIP also performs file control functions.
Some of the
functions PIP performs are:
•

Copy files from one device to another

•

Delete files

•

Rename files

•

List file directories

•

Set the default device and UIC for PIP operations

•

Unlock files

•

Spool files

You invoke the PIP utility using any of the methods for invoking a
utility described in Chapter 1. You invoke PIP file control functions
by means of switches and subswitches.

4.1

PIP COMMAND STRING

You request PIP functions by entering PIP command strings through the
initiating terminal or by means of an indirect command file.
(Using
indirect command files is described in Chapter 1.) The format of PIP
·command strings differs for each function. Therefore, the command
string formats are described in separate sections.

4 .1.1

PIP Defaults for File Specificatio·n Elements

With the exception of the version number, PIP generally uses the last
value encountered in the command line as the default. That is, PIP
uses values you enter to set defaults, and changes the default when
you
change
the value.
Exceptions to this are noted in the
descriptions of each switch.

4-1

PERIPHERAL INTERCHANGE PROGRAM (PIP)
The following command string sets a new default value
specified on the command file:

for

each

file

>PIP TI.MAC;5,T2,.TSK,;6/LI
Tl.MAC; 5
T2.MAC;5
T2.TSK;5
T2.TSK;6
Table 4-1 summarizes the rules PIP uses to set defaults.
Table 4-1
PIP Default File Specifications
Default Value

Element
dev:

For the first file specification, the unit on which
the syst£m disk is mounted (SY:) or the default that
you specify with /OF (see Section 4.2.2.5).
For
subsequent
file
specifications,
either
you
explicitly specify a new device or PIP assumes the
device from the previous specification.

[ufd]

For the first file specification, your current UIC,
that is, the UIC under which you log on, the UIC you
specify with the MCR SET command, or the default you
specify
with
/DF (see Section 4.2.2.5).
For
subsequent
file
specifications,
either
you
explicitly specify a new ufd or PIP assumes the ufd
from the previous specification.
An
asterisk
(wildcard)
specification is valid (see Section
4.1.3).

filename

For
No default for the first file specification.
subsequent file specifications, the rast filename
that you
explicitly
specified.
An
asterisk
specification is valid (see Section
(wildcard)
4.1.3) •

• filetype

No default for the first file specification.
For
subsequent file specifications, the last file type
explicitly
specified.
An
asterisk
that you
specification is valid (see Section
(wildcard)
4.1.3).

The default for input files is the most recent
version number. The default for output files is the
next higher version number, or version 1 if the file
does not already exist in the output directory. An
exception is the PIP file delete funciton, which
requires an explicit version number or a wildcard
specification.
An explicit version
number
is
defined to be of the form ;n where n is greater than

;version

(n>O).

A version number of ;-1 may be used to specify the
oldest version of a file. A version number of ;O or
; may be specified to signify the most recent
version.
In
certain cases, the asterisk
(or
wildcard) may be specified, as described in Section
4.1.3.

4-2

7 tli!i

I 12 i#i!UW iJ

iiiii iii!

s:::

!if

4iii ; $

.Jii4¥

PERIPHERAL INTERCHANGE PROGRAM (PIP)
4.1.2

PIP Switches and Subswitches

PIP provides several file control switches and subswitches.
A switch
specification consists of a slash (/) followed by a 2- or 3-character
switch name. The switch specification is optionally followed by a
subswitch name separated from the switch name by a slash. The
subswitch name can have arguments that are separated from the
subswitch name by a colon (:).
Each is preceded by a slash.
All but one of the PIP switches operate on
lists
of
file
specifications.
The exception is· the ID switch, which is used by
itself.
Section 4.1.2.l
subswitches.

L~;
.-'

describes

switches

and

Section

4.1.2.2

describes

4.1.2.l Switches - PIP
accepts
some
switches
with
no
file
specification.
However,
when you use a switch in a command line, it
must follow the file or UFD specification.
It cannot come before the
file name,
file
type, version, or UFD of the file on which it is to
operaite.
You may specify switches once
specifications.
For example:

for

list

entire

file

deletes

every

stringl,string2,string3/DE
The DE switch applies to all of the strings.
specified file from its User File Directory.

PIP

You specify switch arguments as octal
(default),
decimal,
or
alphabetic characters, depending on the switch. The sections that
explain the individual PIP switches discuss these values.

4.1.2.2 Subswitches - Subswitches are local. They apply only to the
file specification which immediately precedes them. In the following
example, the New Version subswitch
(/NV)
is applied to the file
ASDG~MAC.
(The NV subswitch is used with the Rename switch, RE.)
PIP>*.SMP=PRT2.QRT,ASDG.MAC/NV,KG.BAC/RE
PIP renames the files PRT2.QRT and KG.SAC,
but they maintain their
associated version numbers.
File ASDG.MAC is also renamed, but the
version number is forced to a number one greater than the latest
version of file ASDG.SMP.
When you explicitly apply a subswitch to a file specification, you
implicitly apply the switch with which the subswitch is associated.
On a command line with more than one file specification, the explicit
subswitch affects only the file to which it is applied. The implicit
switch affects all the files on the command line.

Exam]> le
PIP>FILE1/GR:R/WO,FILE2/GR:RW
This command is equivalent to:
PIP>FILE1/GR:R/WO,FILE2/GR:RW/PR

4-3

PERIPHERAL INTERCHANGE PROGRAM (PIP)
The command results in the following file protection:
a.

FILEl

SYSTEM
MEMBER
GROUP
WORLD

Unchanged
Unchanged
Read access
No access

b. FILE2

SYSTEM
MEMBER
GROUP
WORLD

Unchanged
Unchanged
Read/write access
Unchanged

(For more information on altering the protection level of a file,
Section 4.2.2.14).

4 .1. 3

see

Wildcards

PIP allows you to specify wildcards by means of an asterisk (*)
charqcter in the file specification. The asterisk (*) character in
one or more fields of a file specification stands for "all";
for
example, all files, file types, or versions. However, using wildcards
is restricted in some cases. The following sections describe the uses
of wildcards for input and output files.

4.1.3.l Wildcards in Output File Specifications - Using wildcards in
the output file specifications is restricted. For the following PIP
functions, the output file specification cannot have any wildcards:
•

Copying a single file

•

Concatenating files to a specified file

•

Appending to an existing file

•

Updating (rewriting) an existing file

•

Listing a directory

If you use wildcards in the output file specification for any of the
above functions, the meaning of the command iine would be ambiguous or
imply an infinite number of output files. For example:
PIP>[200,200]*.*;*=TEST.DAT
PIP would try to create an infinite number of files in [200,200]
one single file.

from

When you make copies of several files, the output
be *.*;*or default.

must

specification

For the Rename
(/RE) and Enter
(/EN)
switches,
the
output
specification may have wildcards mixed with specified fields. For
either switch, the equivalent field of the input file specification is
used.
For all cases in which wildcards are allowed in the output file
specification, the wildcard UFO form [*,*] (but not [n,*] or [*,n]) is
used to indicate that the output UFO is to be the same as the input
UFO.

4-4

t 111 I

( i!i

i I

ii ii i!!!iii iii! .Li !.i il ) lib.i i!

PERIPHERAL INTERCHANGE PROGRAM (PIP)
4.1.3.2 Wildcards in
Input
Specifications - PIP
provides
following wildcard features for input file specifications:

the

•

*.*;*means all versions of all files.

•

*.DAT;* means all versions of all files of file type DAT.

•

TEST.*;* means all versions and all types of files named TEST.

•

TES1~.DAT;*

•

*·*means the most recent version of all files.

•

*.DAT means the most recent version of all files of file

means all versions of file TEST.OAT.

type

.OM~.

•

TES1~.*

means the most recent version of
files named TEST.

all

file

types

for

PIP also provides the following wildcard UFO features:

4.2

'-'i

•

[*,*] means all group, member number combinations
377 octal.

•

[nl,*] means all member numbers under group nl.

•

[*,n2] means all group numbers for member n2.

from

PIP COMMAND FUNCTIONS

PIP copies Files-11 files and performs file
Section 4.2.1 describes the copying function
describes the file control functions.

4.2.1

control functions.
and Section 4.2.2

Copying Files-11 Files

To copy Files-11 files, you can enter the
specifying any switches.

PIP

command

line

without

The simplest format for the PIP command line is:
outf i fo=inf i le
outfUe
The output file specification.
If the output file name,
file
type,
and version are either null or *.*;*, the input file name,
file type, and version are preserved (see NV and SU subswitches).
If you enter any portion of the output file specification (file
name, file type, or version), wildcards cannot be used in this
specification.
Similarly,
for a copy command, if you enter any
portion of the output specification, you can enter only one file
as the input file.
inf ile
The input file specification.
If the file name, file
type,
version fields are all null, then *.*;* is the default.

4-5

and

PERIPHERAL INTERCHANGE PROGRAM (PIP)
One switch that you can specify when copying Files-11 files is the
Merge switch.
The Merge switch (/ME) creates a new file from two or
more existing files. PIP assumes /ME when you explicitly specify an
output file, two or more input files, and no switches. Because the
basic copy function and the Merge switch are logically related, the
Merge switch is described here rather than below with the other
switches.
The most general format of the PIP command line is:
outfile=infilel [, infile2, ••• infilen] [[/ME] [/subswitch]]
outfile
The output file specification.
inf ile
The input file specification.
/ME
Specifies the Merge switch.
/subswi tch
Specifies any of the subswitches that you can enter as part of
the basic command line or with the Merge switch. Table 4-2
describes these subswitches. Subswitches can appear in either
the output or input file specification.
If you place the
subswitch in an input file specification, it applies only to that
file.
If
you
place
the subswitch in the output file
specification, it applies to the
entire
list
of
input
specifications.
Examples
1.

PIP>DKl:SAMP.DAT=DK2:TEST.DAT
Copies the latest version of file TEST.DAT
UFD) from DK2: to DKl: as SAMP.DAT.

(in

the

current

PIP>DKl:[*,*]=DKO:[ll,*]
Copies all files from all members in group number 11 of DKO:
to DKl:.
The files are in the same UFD on DKl: that they
were in on DKO:.

PIP>LP:=*.LST
Copies the latest version of all files with a type of .LST in
the current UFD to the line printer. If the Print Spooler is
installed on your system, use the SP switch instead of this
command. The command line using /SP is in the format:
PIP>*.LST/SP

~
I·

4-6

:•a I$

I.I

;;

J 2ii ii! 12 fat

:z :: a: :q:u u;a:;:a;

PERIPHERAL INTERCHANGE·PROGRAM (PIP)
Note:
Transparent spooling
(that is,
PIP>LP:=files)
is
implemented on RSX-llM-PLUS only.
When you specify LP:
as
your output device, the data to be printed is written into an
intermediate file and then the file is given to the Queue
Manager, which handles the spooling.
Making intermediate
files allows you to dismount the volume the files are on
without having to wait until after they have been printed.
4.

P IP>DKl: SAMP .DAT=DK2: TEST. DA'l'; 1,NEW. DAT; 2/ME
Concatenates version 1 of file TEST.DAT and version 2 of file
NEW.DAT from DK2:, generating file SAMP.DAT on DKl:, using
the cur r ent UFD.
1

PIP>DKl:=SY:TESTPROG.MAC,.OBJ
Copies the latest versions of TESTPROG.MAC and TESTPROG.OBJ
from the system device (SY:) to DKl:, using the current UFO
for both SY:
and DKl:.

PIP>DKl:=DKO:*.DAT;*
Copies all versions of all of the files of file type .DAT
the current UFO from DKO:
to DKl:.

PIP>DT0:=[200,10]*.*;*
Copies all files under [200,10] from the
D'I'O : , using the current UFO.

default

device

PIP>DP0:[200,10]=DTO:*.*
Copies all files from OTO:
current
UFO
in the
to
DP 0 : [ 2 0 0 , l 0 ] •
Note that the user must have write access to
(200,10].

'-'

Table 4-2
PIP Copy Command and Merge Subswitches
Subswi tch

'-'·I

Description

/BL:n[.]

Blocks Allocated -- This subswitch specifies the
number
of
contiguous
blocks
(n)
to allocate
initially to the output file.
You can specify n as
either an octal or decimal value (decimal values
must be followed by a decimal point). You use the
/BL:n subswitch when you are copying a contiguous
file and changing its size.

/CO

Contiguous Output -- This subswitch specifies that
the output file be contiguous. When you are copying
contiguous files from magnetic tape
(for example,
task
images), specify both /CO and /BL:n.
You must
specify /BL:n because PIP cannot determine the
length of the input file when it allocates a file.
(PIP allocates file space before the copy operation
is executed.
The length of magnetic tape input
files is on the trailing label of such tapes.)
(continued on next page)

4-7

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 4-2 (Cont.)
PIP Copy Command and Merge Subswitches
Subswi tch
/-CO

~
I

Description

•

Noncontiguous output -- This subswitch specifies
that the output file does not have to be contiguous.

If you do not specify any of the above switches, PIP
defaults to the size and attributes of the input
file.
/FO

Set File Ownership -- This subswitch specifies that
the owner of the input file also owns the output
file.
If you do not specify /FO, the owning UIC of
all new files is the UIC under which PIP is running,
regardless of which directory the files belong to.
You can use this subswitch with both copy and merge
commands.
Examples
l.

If PIP is
command:

running

under

the

UIC

[1,1],

the

DK0:[200,200]=DK1:[200,220]TEST.DAT
creates a new file in the [200,200] directory on
DKO:, but the file is owned by UIC [1,1].
However, the command:
DK0:[200,200]=DK1: [200,220]TEST.DAT/FO
creates a file owned by UIC [200,200]. When you
specify /FO, PIP must be running under a UIC
that has write-access to all output directories.
2.

DKl: [*,*]/FO=DPO: [13,10), [32,10], [34,10]
Copies all the files from the specified input
directories to the corresponding directories on
DKl:.
The
file
owners
are
the
output
directories.

DKl:[*,*]=DK0:[*,10]*.MAC/FO
Copies all the .MAC files from all group numbers
with member 10 to DKl:, preserving the UFO and
setting the file owner for each file to that
UFO.

/SU

Supersede -- This subswitch allows you to copy one
or mor'e input files to a file whose file name, file
type, and version already exist in a User File
Directory.
The existing file is deleted and a new
one is created with the data from the input file(s).
(continued on next page)

4-8

·~:au;

!£! I

Ill!

IJ!ijJ i2i2 $di$ Qii# Ji I

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 4-2 (Cont.)
PIP Copy Command and Merge Subswitches
Subswitch

Description

/SU (Cont. )

The output file's name,
type,
and version number
remain the same, but its file identification number
(File-ID) is different.
Also,
the attributes for
the output file are taken from the first input file
and the number of blocks allocated to the output
file can be different (less than or more than) the
number of blocks allocated to the existing file.

/NV

New Version -- This subswitch forces the output
version number of the file being copied to become
one greater than the latest version of the
file
already
in the output directory.
If the file does
not already exist in the output directory, a version
number of 1 is assigned.
Figure 4-1 shows the
results when you specify /NV.
(Specifying /NV is
not necessary when both the input and output files
are under the same file directory.)

4.2.2

Performing File Control Functions

PIP provides several switches and subswitches for file control
processing.
These switches and subswitches perform such functions as
deleting files, displaying the contents of a User File Directory,
and
specifying file protection values.
You c:an specify two PIP switches, /ID and /LI, on a command line with
no file specifications (that is, they may be entered by themselves).
You can specify only one switch in a command line.
one subswitch can be specified.

However, more than

The values that you specify with the switches and subswitches default
to octal.
You can specify decimal values by adding a decimal point
after the value.
Table 4-3 lists PIP switches and subswitches and summarizes the
functions performed by them. The subswitches are listed with their
respective switches.
(The switches and subswitches are described in
detail following the table.)

4-9

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Directories Before COPY
INPUT DIRECTOR~

OUTPUT DIRECTORY
l in, 1$¥$JJ

RICK.DAT;!

RICK.DAT;2
RICK.DAT;4

[2.0'1, 2-'fl J

Directories After COPY Without /NV Switch Set
(version number preserved)
INPUT DIRECTORY
[ 2,01 , 2,01]

OUTPUT DIRECTORY
[ 1,0,0, 1,0,0]

RICK.DAT;l

RICK.DAT;2
RICK.DAT;4
RICK.DAT;l

The conunand used was:
DKl: ( U),0, 1,0,0) = DK2: [ 2$¥1, 2$¥1] RICK. DAT; l

Directories After COPY With /NV Switch Set
INPUT DI RECTORY
[2$¥1,2$¥1]

OUTPUT DIRECTORY
r in, 1$¥$JJ

RICK.DAT;l

RICK.DAT;2
RICK.DAT;4
RICK.DAT;S

The conunand used was:
DKl: [1,0,0,lnJ = DKl: [2,01,2,0l)RICK.DAT;l/NV
NOTE
The version specified with the /NV subswitch must be explicit or default; no
wild cards allowed.

Figure 4-1

Results of Copy Command With and Without /NV Specified
Table 4-3
PIP Switches and Subswitches

Switch

Subswi tch

Function
Appends file (s) to the end
file.

/AP
/FO

existing

Specifies the file ownership for a file.

/BR

Lists a directory file in brief format
alternate mode for the LI switch).

/BS: n [.]

Defines the blocksize for magnetic tape.

(an

(continued on next page)

4-10

11
•

ii I. I 2111 I Iiiiii I Liii!Z!iiii &Ci14 Uii I iiii!i 2222!!2ili!

2!i

:;; Ia I I .:g;p a

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 4-3 (Cont.)
PIP Switches and Subswitches
Switch

Function

Subswi tch

/CD

Allows the output file to take the creation
date of the input file rather than the date
of transfer.

/DE

Deletes one or more files.
/LD

Lists the deleted files.

/DF

Changes PIP's default device and/or UFD.

/EN

Enters a synonym for a file in
file.
/NV

/EOF[:block:byte]

directory

Forces the version number of a file
greater than the latest version.

Specifies
file.

for

the

end-of-file

pointer

/FI:filenum:seqnum

Accesses a file by its
number (File-ID) .

/FR

Displays the amount of free space on the
specified volume and the largest contiguous
free space on that volume.

/FU [: n [.] ]

Lists a directory file in full format
alternate mode for the LI switch).

/ID

Identifies the version of PIP being used.

/LI

Lists directory files.

/ME

Concatenates two
file.

/NM

file

one

identification

files

into

/BL :n [.]

Allocates a number

/CO

Specifies that
contiguous.

/FO

Specifies the file ownership for a file.

/NV

Forces the version number of a file
greater than the latest version.

/SU

Supersedes (replaces) an existing file.

(an

one

(n) of contiguous blocks.

the

output

file(s)

one

Suppresses certain PIP error messages.
(continued on next page)

4-11

PERIPHERAL INTERCHANGE PROGR~ (PIP)
Table 4-3 (Cont.)
PIP Switches and Subswitches
Switch

Function

Subswitch

Changes the protection status of a file.

/PR
/FO

Specifies the ownership for a file.

/GR[:RWED] Sets the read/write/extend/delete protection
at the group level.
/OW[:RWED] Sets the read/write/extend/delete protection
at the owner level.
/SY[:RWED] Sets the read/write/extend/delete protection
at the system level.
/WO[:RWED] Sets the read/write/extend/delete protection
at the world level.
/PU[:n[.]]

Deletes obsolete version(s) of a file.
/LD

Lists the deleted files.

/RE

Renames a file.

/RM

Removes a file entry from a directory.

/RW

Rewinds a magnetic tape.

/SB

Spans the block boundaries of records
copying from magnetic tape to disk.

when

/SD

Selectively deletes files by prompting
your response before deleting.

for

/SP [ : n [. ] ]

Spools file(s)
printing.

for

/SR

Allows shared reading of a file that has
already been opened for writing by another
user or task.

/TB

Lists the total number of blocks used for a
directory, along with the total number of
blocks allocated and the number of files
in
that directory (an alternate mode for the LI
switch).

/TR

Truncates file(s) to logical end-of-file.

/UF

Creates a User File Directory entry on the
volume to which a file is being transferred.

/UN

Unlocks a file.

/UP

Updates (rewrites) an existing file.
/FO

the

line

printer

Specifies the ownership for a file.

4-12

Ii i I 2J!2 !iiiiii t

I !i $2

:;4

PERIPHERAL INTERCHANGE PROGRAM (PIP)
4.2.2.1 /AP -- Append Switch - The Append switch
{/AP)
opens an
existing file and appends the input file {s) to the end of it. SpecHy
the Append switch in the following format:
outfi.le=infilel [, infile2, ••• infilen]/AP [/FO]
outfile
The output file specification. Wildcard specifications are
allowed in the output file specification. The file type and
record attributes for the output file remain the same after
input file or files have been appended to it. The file name
file type for the output file must be specified explicitly.

not
the
the
and

inf ile
The input file specification.
If the file name, file
version are null, then *.*;* is the default.

type,

and

/AP
The Append switch.
/FO
The Set File Ownership subswitch, which specifies that the owning
UIC of the output file is the same directory to which the input
file belongs.
If you do not specify /FO, the owning UIC of the
output file is unchanged, regardless of which directory the input
files belong to. See Section 4.2.1 for examples of using /FO.

Exa:mple
PIP>I>Kl:FILEl.DAT;l=FILE2.DAT;l,FILE3.DAT;lFILE4.DAT;l/AP
Opens FILEl.DAT;l on DK!:
and appends
the
FILE2.DAT;l, FILE3.DAT;l and FILE4.DAT;l to it.

contents

Note: If the output file is contiguous before the
may not be contiguous afterwards.

appending,

4.2:.2.2 /BS:n -- Block Size Switch - The Block Size switch defines
thei block size for magnetic tapes. This switch allows you to read or
write bigger blocks onto magnetic tape, thereby saving some of the
sps1ce taken by interrecord gaps.
Specify /BS using the following
format:
outfile/BS:n=inf ile
or
outfile=infile/BS:n
out.file
The output file specification.

4-13

PERIPHERAL INTERCHANGE PROGRAM (PIP)
inf ile
The input file specification.
/BS :n [.]
Specifies the Block Size switch where n is an octal
number specifying the number of bytes in a block.
In the
output
of the
actual

decimal

output specification, /BS specifies the block size of the
file.
In the input specification, /BS specifies the block size
input file.
If the block size specified is smaller than the
block size, an I/O error occurs.

4.2.2.3 /CD -- Creation Date Switch - The Creation Date switch (/CD),
used in a file transfer command, allows the output file to take the
date on which the input file was created rather than the date of
transfer.
You cannot use this switch with the Merge switch (/ME).
Specify the CD switch in the following format:
outfile/CD=infile
outfile
The output file specification.
inf ile
The input file specification.
/CD
The Creation Date switch.

.a.i.
~···

11'

Example
DIRECTORY DB1:[200,200]
21-NOV-78 14:02
FILE.DAT;?

12.

6-0CT-78 16: 13

PIP>TEST.DAT/CD=FILE.DAT
DIRECTORY DB1:[200,200]
21-NOV-78 14:05
FILE.DAT;?
TEST.DAT;l

12.
12.

6-0CT-78 16:13
6-0CT-78 16:13

The command creates a new file, TEST.DAT, from FrLE.DAT and gives
it the creation date of FILE.DAT rather than the transfer date.

4.2.2.4 /DB -- Delete Switch - The Delete switch (/DE) deletes files
from a User File Directory.
Optionally, you can specify that the
deleted files be listed on your terminal.
Specify /DE in the
following format:
infilel[,infile2, ••• infilen]/DE[/LD]

4-14

&$2l

!lb

iii

SIS$

;:;;; :a'

PERIPHERAL INTERCHANGE PROGRAM (PIP)
infUe
The input file specification.

\w.!

/DE
The Delete switch.
/LD
The List Deleted files subswitch.
You must specify a version number or a
using the Delete switch.

wildcard

its

place

when

Use a version number of ;-1 to specify the oldest version of a file.
Use a version number of ;O or ;
to specify the most recent version.
Exa1111ples

PIP>TEST.DAT;-1/DE
Deletes the oldest version of file TEST.DAT.

PIP>TEST1.DAT;O,TEST2.DAT;/DE
Deletes the latest version of files TESTl.DAT and TEST2.DAT.

Wildcards in the file name or file type
version of ;-1, ;O, or ;
is specified.

fields

are

illegal

You must issue the file specification because a null file
type, and version do not default to *.*;*.

when

name,

file

The input file specification can take all the usual forms,
including
wildcards
(even in the group, member number [ufd]). The only special
requirement is that the version field must always be explicit or *·
Exa11llples

PIP>TEST.DAT;S/DE
Deletes version 5 of file TEST.DAT
directory on the default device.

the

default

current

PIP>TEST.DAT;l,;2/DE
Deletes versions 1 and 2 of file TEST.DAT
default directory on the default device.

current

the

PIP>*.OBJ;*,*.TMP;*/DE/LD
Deletes all versions of all files of the file type .OBJ and
.TMP from the current default directory on the default
device.
Lists all deleted files of file type .TMP.

PIP>*.OBJ;*/LD,*.TMP;*/DE
Deletes all versions of all files of the file type .OBJ and
.TMP from the current default directory on the default
device.
Lists all deleted files of both file types.

4-15

PERIPHERAL INTERCHANGE PROGRAM (PIP)

4.2.2.5 /DF -- Default Switch - The Default switch (/OF) changes
default device and/or UFO.

the

The usual default device of PIP is SYO:.
The normal default UFO is the UIC under which PIP is currently
running. /DF alters only the default UFO. It does not affect the UIC
under which PIP is running, nor does it circumvent file protection.
Specify /DF in one of the following formats:
dev: [group,member]/OF
or
dev:/DF
or
[group,member]/DF
dev:
If specified, the new default device to be applied to subsequent
PIP command strings. You must specify the device if you do not
specify a UFO.
[group, member]
If specified, the new default UFO to be applied to subsequent PIP
command strings. You must specify a UFO if you do not specify a
device.

~
i

/OF
The Default switch.
Examples
1.

PIP>[27,27]/0F
Sets the default UFO to (27,27].

P IP>OKl: /OF
Sets the default device to OKI:.

PIP>OKl: [27,27]/0F
Sets the default device to
(27 ,27].

OKl:

and

the

default

UFD

4.2.2.6 /EN -- Enter Switch - The Enter switch (/EN) lets you enter a
synonym for a file in a directory or directories on the same device.
This allows the file to be accessed by more than one name.
Also
provided is a subswitch, New Version (/NV), which forces the version
number of the file being entered into the directory to a number one
greater than the latest version of the file. Specify the Enter switch
in the following format:
outfile=infilel[,infile2, ••• infilen]/EN[/NV]
4-16

I !Ji(j

I I iiij

liiilli

iii:;

; bi

;:s;z

PERIPHERAL INTERCHANGE PROGRAM (PIP)

outfi le
The file specification of the new directory entry.
The output
file specification has a special property in that the file name,
file type, or version may be explicit, wildcard (*), or defaulted
(null).
A filename, filetype, or version field that is either
wildcard (*) or default (null) means that the corresponding field
of the input file is to be used.
inf Jlle
The file specification for the input file in the format:
dev: [ufd]filename.filetype;version/sw[/subsw]
If you specify a device in either the input or output file
specification, that device sets the default for the other side.
If you do not specify a device on either the input or output
side, the current default device is assumed to be the default
device. If both the input side and the output side explicitly
reference different devices, PIP signals an error and requests
that the line be reentered.
The default input file specification is * • *·*
I
•
/EN
The Enter switch.
/NV
The New Version subswitch. The NV subswitch may appear on either
side of the equal sign. If it appears on the output side, all of
the files being entered are forced to a version number one
greater than the latest version of the file. If it appears on
the input side, only files that have the NV subswitch appended to
them are forced to a number one greater than the latest version.
Exa1n1ple (see Figure 4-2)

PIP>[l01,10l]TWIG/EN=[200,200]RICK.DAT;l
Before
DIRECTORY [200,200]

DIRECTORY (101,101]
JEN.OBJ;2

RICK.DAT;!

LAU.OBJ;3

Figure 4-2

Sample Directories Before and After Execution of /EN

4-17

PERIPHERAL INTERCHANGE PROGRAM (PIP)
After
DIRECTORY [101,101]

DIRECTORY [200,200]
RICK.DAT;!

JEN.OBJ;2
LAU.OBJ;3
TWIG.DAT;!
NOTE

The directory items for RICK.DAT;! and
TWIG.DAT;! both reference the same file.
Figure 4-2 (Cont.)

Sample Directories Before and After Execution

4.2.2.7 /EOF -- End-of-File Switch - The End-of-File switch
(/EOF)
allows you to specify where the file's end-of-file will be. This
helps in certain situations (for example, system crashes) when a file
contains useful information but its EOF pointers are wrong, preventing
you from obtaining the information.
EOF is an unprotected file attribute. If you are the file owner or
have a system-level UIC, you do not need read- or write-access to read
or change this attribute. If you are group or world to the file
owner's
UIC,
you need read-access to read the attribute and
write-access to change it.
Specify /EOF in the following format:
inf ilel/EOF [:block: byte] [, ••• inf i len/EOF [:block: byte]]
inf ile
The input file specification.
The file specification must be issued because a null
file type, and version do not default to *.*;*.

file

name,

block
The block number where the EOF pointer is to be placed. The EOF
pointer cannot be placed beyond the highest number of blocks
allocated to the file. The block number can be octal or decimal.
byte
The byte location of EOF or the first unused byte of the block.
The byte number can be octal or decimal. The maximum value for
byte is 7 7 7 ( 8) •
If you do not enter either of the values for block and byte, PIP
places EOF at the last byte of the last block allocated to the file.
If you specify a value for either block or byte that is greater than
the maximum value allowed, PIP signals an error.
Note that /EOF is local to each file specification and therefore
not default from left to right.

does

4-18

1
••

-.u:. .u•u. . . . . . . . . . . . . . . !!ILlll
.
. . . .111............................._.. . . ._.......................
,z111111. . . .•a•c:•,•t•t•1•2:11m1

• :. . .

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Exa11~ple

PIP>A.TMP/EOF:l7:253,AA.TMP/EOF
is equivalent to
PIP>A.TMP/EOF:l7:253,AA.TMP/EOF:22:777
where the file AA.TMP has 22 blocks allocated.

4.2.2.8 /FI -- File Identification Switch - The File Identification
switch
(/FI}
allows you to access an existing file by its file
identification number (File-ID}. Specify /FI in the following format:
outfile=/FI:filenum:seqnum
/FI
The File Identification switch.

The file number of the file.
seqnum
The sequence number of the file.
The file identification number of the file is assigned by RSX-11 when
the file
is created.
To find the file identification number of a
file,
use the Full List switch
(/FU}.
/FU displays the file
identification number and other information describing the file.
You can use /FI to create a directory entry for a file.

For example:

FOO.TSK=/FI:301:27/EN
Also, you can copy a file using /FI:
A.B=/FI:301:27
To list the directory file whose identification number is 301,27,
/FI in the format:

use

/FI:301:27/LI

4.2.2.9 /FR -- Free Switch - The Free switch
(/FR}
displays the
amount of available space on a specified volume and the largest
contiguous space on that volume. Specify /FR in the following format:
[dev:] /FR
If you do not specify dev:, PIP defaults to SYO:.
The format of the information from /FR is shown below.
dev:
HAS xxxx.
BLOCKS FREE, yyyy. BLOCKS
LARGE:ST CONTIGUOUS SPACE = nnnn..
BLOCKS

4-19

USED

OUT

zzzz.

PERIPHERAL INTERCHANGE PROGRAM (PIP)
4.2.2.10 /ID
Identify
identifies the version of
following format:

Switch - The
Identify
switch
PIP being used.
Specify /ID

(/ID)
in the

~.···.
~~

/ID
When you specify this switch, the version
input terminal as follows:

number

listed

the

PIP VERSION Mvvee
vv
The version number.
ee
The edit number.

Example
PIP>/ID
PIP VERSION Ml332

4.2.2.11 /LI -- List Switch - The List switch (/LI) lists one or more
files contained in a User File Directory, along with their status
information.
Three alternate mode switches (/BR, /FU, and /TB) allow
you a choice of directory listing formats. Table 4-4 describes these
switches. Specify /LI in the format:
[listfile=]infilel[,infile2, ••• infilen]/LI[/switch]
listfile
The listing file specification in the format:
dev: [ufd]filename.filetype;version
If listfile is not specified, it defaults to TI:.
inf ile
The input file specification in the format:
dev: [ufd]filename.filetype;version
The default for infile is

* *·*
•

•

/LI
The List switch.

This switch lists the following information:

filename.filetype;version

number of blocks used (decimal)

file code:
(null) = noncontiguous
contiguous
c
locked
L

4-20

i!&Qt

;s:;c::p::e

PERIPHERAL INTERCHANGE PROGRAM (PIP)

creation date and time

summary line, which
includes
used/allocated and files printed

the

number

blocks

/switch
The alternate mode switches of the List switch described in Table
4-4.
Table 4-4
List Switches
Switch

Description

/IBR

This switch specifies the brief form of directory
listing. This switch lists only the file name, file
type, and version.

/FU [: n [.] ]

This switch specifies the full directory format.
Because the /FU format involves protected file
attributes, you may need read-access to get a full
directory listing of a file. If you are the file
owner or have a system-level UIC, you do not need
read-access. If you are group or world to the file
owner's UIC, you need read-access to read the
protected attributes of the file.
(To change the
protection level attribute, see Section 4.2.2.14,
below.)
If specified, n is the number of characters per
line.
If not specified, the number defaults to the
buffer size of the output device. This switch lists
the following information:
1.

filename,filetype;version

file identification number in the format:
(file number, file sequence number)

number of blocks used/allocated (decimal)

file code:
(null) = noncontiguous
c = contiguous
L
= locked

creation date and time

owner UIC and file protection in the format:
[ g r o up, me mb e r ]
[system,owner,group,world]
(continued on next page)

4-21

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 4-4 (Cont.)
List Switches
Switch

Description

/FU [: n [.] ]
(Cont. )

These protection fields can contain
R, w, E, or D.

the

values

where:
R

= Read access permitted

w = Write access permitted
E = Extend privilege permitted
D = Delete privilege permitted

/TB

date and time of the last update plus the number
of revisions.

summary line,
which contains the number of
blocks used, the number of blocks allocated, and
the number of files printed.

This switch specifies
following format:
TOTAL OF nnnn./mmmm.

the

summary

line

BLOCKS IN xxxx.

the

Files

where:
nnnn = blocks used
mmmm = blocks allocated
xxxx = number of files

.~.···.-.·

~ff-T~

Figure 4-3 contains sample directory listings in the various formats.
Examples
1.

PIP>/LI
Lists the directory of the current default
(This is equivalent to TI:=*.*;*/LI.)

UIC.

the
all

line printer in full
format
(132-column
of the directories on the current default

Note:
Only RSX-llM-PLUS
Section 4.2.1).

has

transparent

spooling

(see

PIP>TI:=TEST.DAT/FU
Lists on TI:
the full directory listing for
version of TEST.DAT in the current default
directory.

and

PIP>LP:=[*.*]/FU:l32
Lists on
listing),
device.

device

the latest
device and

PIP>JUL13.DIR=[200,200]*.*/LI
Lists the latest version of all files in directory
[200,200]
on the current default device to file JUL13.DIR in the
default directory on the default device.
4-22

II!!

hi I.

I l t; 21

4211

;:sc:::::a441211

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Total Blocks (/TB) Format

STORAGE USED/ALLOCATED FOR DIRECTORY DK2:C200•270l
15-JUL-751 15:46
TOTAL OF 145./150. BLOCKS IN 5. FILES

Brief (/BR) Format

DIRECTORY DK2:C200,270J
CKTST.HAC:f6
I Q1TST • HAC: f 4
I 01TST. TBf(~ f 1
CKTST.TSKf1
CKTST. HAC: f 7

Standard (/LI) Format

DIRECTORY DK2:t200•270J
1:.li-JUL-n5 15:46
Ct<:TST. HAC f 6
ICITST.HAC:f4
IOITST. TS~C f 1

CK:TST • TBK f 1
Ct<:TST. HAG f 7

15-JUL-75 15:39
15-JUL-75 15139
C 15-JUL-75 15:39
C 15-JUL-75 15:40
L 15-JUL-75 15:40

3.
4.
69.
69.

TOTAL OF 145. BLOCKS IN 5. FILES

Full (/FU) Format

DIRECTORY DK2:C200•270l
1 ~i-JUL-75 15: 46
C~CTST • HAC: f 6

<10.10>
C200•270JCRWEDrRWEDrRWEDrRJ
(11r11)
IUTST.HAGf4
C200,270JCRWED•RWEDrRWEDrRJ
( 7 '12)
IUTST • TSIO 1
C200r270lCRWED•RWED,RWEDrRJ
(12r13)
Ct\TST • TSI( f 1
C200,270JCRWED•RWED,RWED,RJ
<13•14)
CtCTST • HAC P7
C200r270JCRWED•RWED,RWEDrRJ

3.13.

15-JUL-75 15139

4.14.

15-JUL-75 15139

69./69 •.

15-JUL-75 15139

69./69.

15-JUL-75 15140

0.15.

L 15-JUL-75 15140

TOTAL OF 145./150. BLOCKS IN 5. FILES
Figure 4-3

Directory Listing Examples

4-23

PERIPHERAL INTERCHANGE PROGRAM (PIP)
5.

PIP>LP:=[ll,*]*.CMD;*/LI
Lists on the line printer all versions of all files with
file type .CMD in all directories in group 11.

the

Note:
Only RSX-llM-PLUS
Section 4.2.1).

(see

has

transparent

spooling

PIP>LP:/BR=[ll,11]*.CMD;*,*.DAT;*,*.MAC;l
Lists on the line printer in brief format all versions of all
files with a file type of .CMD; all versions of all files
with a file type of .DAT; and all files of file type .MAC
with a version number of 1. These files all reside in the
directory [11,11] on the current default device.
Note:
Only RSX-llM-PLUS
Section 4.2.1).

has

transparent

spooling

(see

4.2.2.12 /ME -- Merge Switch - The Merge switch (/ME) creates a
single file from two or more existing files. Merge is used in copying
Files-11 files and is described in Section 4.2.1.

=-1,

4.2.2.13 /NM -- No Message Switch - The No Message switch (/NM)
suppresses the PIP error message, NO SUCH FILES(S), when you are
manipulating files. Specify the NM switch in the following format:
infilel[,infile2, ••• infilen] [/sw]/NM

inf ile

The input file specification.
/sw
Any combination of appropriate switches and subswitches, for
example, the LI, DE, or PU switches and any of their respective
subswitches.
/NM
The No Message switch.
Example

PIP>*.MAC;*,TEST.DAT;l,FILES.OBJ;*/DE/NM
If none of these files exists in the default directory, you will
not get the error message, NO SUCH FILE(S}, when PIP tries to
delete them.

4-24

'II.

Ji)£ $C

ii![ij i !J iii!

I I I Uiiiii

iii iii i

:;::s

::..: lilt

ii $ I ZS!

14 JSIJLij#li

PERIPHERAL INTERCHANGE PROGRAM (PIP)
4.2~2.14
/PR -- Protect Switch - The Protect switch
the facility to set the protection status of a file.
is provided for four categories:

(/PR)
provides
File protect ion

System
Specifies which categories of access the system UICs are allowed
to the file (that is, UICs with group numbers less than or equal
to 10 octal).
OwnE~r

Specifies which
himself.

directory

operation

I/O

User Action: The following responses correspond (by
the conditions listed above.

number)

Write-enable the volume.

Respecify /DO, /RT, or /RS correctly.

No recovery is possible with the volume currently mounted.
Mount a volume that is in the proper format, and retry the
operation.

Retry the operation.

FLX -- FILE ALREADY EXISTS
Explanation: The specified output file
output device.
User Action: Reenter the
corrected file name.

file

already

specification

exists

the

new

specified,

using

FLX -- FILE NOT FOUND
Explanation: The named file does not appear,
the requested directory.
User Action: Retry the operation
directory correctly specified.

with

the

file

and

name

5-18

·11111

iii ill

!!(!!

4 SU 24

FILE TRANSFER PROGRAM (FLX)
FLX -- WARNING --· INPUT FILE OUT OF SEQUENCE
Explanation:
of sequence.

A cassette rnultivolume file is being

accessed

out

User Action: This is a warning message.
The transfer will
continue unless you terminate it by means of the ABORT command.
FLX -- @ FILE NESTING EXCEEDED
Explanationg
specified.

More than one level of indirect

command

file

was

User Actiong Retry the operation with only one level of indirect
command file specified.
FLX -- @ FILE SYNTAX ERROR
Explanation: A syntax error occurred
file specification.

the

User Actions Edit the indirect command file.
the corrected indirect command file.

indirect
Rerun

FLX

command
using

FLX -- FMTD ASCII RECORD FORMAT BAD
or
FLX -- FMTD BINAUY RECORD FORMAT BAD
Explanation: Either the file is corrupted, or the file is not of
the specified type.
User Action: If the file is corrupted, no recovery is possible.
If the file type is incorrect, retry the operation specifying the
correct transfer mode switch.
FLX -- ILLEGAL /BS SIZE -- USE O<N<=512.

AND EVEN

Explanation: An illegal block size was
cassette output.
User Action:

specified

with

/BS

Reenter the command line with a legal block size.

FLX -- INCORRECT # IN/OUT SPECS
Explanationg More than one input or output specification
command was entered where only one is allowed.
User Actionx

Reenter the command line with the proper syntax.

FLX -- INVALID DgVICE
Expl•nation: A device was specified that cannot be used as an
input or output device, for example, trying to read from a line
printer.
User Action:
specified.

Reenter

the

command

5-19

line

with

legal

device

FILE TRANSFER PROGRAM (FLX)
FLX -- INVALID DOS OR RT-11 FILE SPEC
or
FLX -- INVALID RSX FILE SPEC
Explanation: The file specification does not conform to proper
syntax, or the specified operation could not be performed on the
specified device.
User Action:
syntax.

Reenter the

file

specification

with

the

proper

FLX -- INVALID SYNTAX
Explanation: A switch was entered that is not a valid FLX switch
or does not conform to proper syntax.
User Action: Reenter the command
specification.

line

with

correct

switch

...,,,

FLX -- I/O ERROR
Explanation:

One of the following conditions may exist:

•

The specified device is offline.

•

A hardware error occurred (for example, bad tape).

Reenter the
User Action: Ensure that the device is online.
command line. If a hardware error occurred, recovery may not be
possible.

.. ·--· :···-1
...

FLX -- I/O ERROR DELETING LINKED FILE
Explanation: An uncorrectable error occurred while a DOS
file was being deleted.
User Action: No action required;
the
deleted, but the volume may be corrupted.

file

linked

effectively

FLX -- I/O ERROR INITIALIZING DIRECTORY
Explanation:

One of the following conditions may exist:

•

The specified directory is not online.

•

The specified volume is not mounted.

•

A hardware error occurred (for example, bad tape).

User Actiori: Ensure that the device is online and is operable.
Reenter the command line with the required switch specified.

5-20

1111•

2US!

ii(

L$2

iii

FILE TRANSFER PROGRAM (FLX)
FLX -- I/0 ERROR ON COMMAND INPUT
Explan21tion: An unexpected
error
in
command
input
encountered from either an indirect command file, or TI:;
exits.
User Action:

was
FLX

Restart FLX.

FLX -- I/O ERROR ON FLX TEMPORARY FILE
Explanation: FLX encountered an .error condition
with
its
temporary file.
FLX creates a temporary file on SY:
for
operations involving DOS-11 CT, DT, or MT.
This error occurs
when one of the following conditions exists:
•

SY:

is not online and mounted.

•

SY:

is write-locked.

•

A protection violation occurred.

•

A hardware error was encountered.

User Action:
line.

Correct the error condition and reenter the command

FLX -- I/O ERROR ON LIST FILE
Explanation: An error occurred on the output device during a /DI
or /LI sequence.
There is a hardware problem with the output
device (for example, device powered down).
User Action:

Correct the condition.

Reenter the command line.

FLX -- OUTPUT DEVICE FULL
Explanation: The DOS-11 or RT-11 output volume does not
enough space for the output file.
User Action:
command line.

Delete

all

unnecessary

files

and

contain

reenter

the

FLX -- OUTPUT FILE SPEC NOT ALLOWED
Explanation: An output file specification
command that does not allow one.
User Action: Reenter
specification.

the

command

was

entered

output

without

for

file

FLX -- RECORD TOO LARGE
Explanation: FLX detected an input record in a Files-11 transfer
that is larger than the specified or implied record size for the
file, that is, the file is corrupted.
User Action:

The file in question is unusable.

5-21

FILE TRANSFER PROGRAM (FLX)
FLX -- REQUEST TERMINATED -- LAST BLOCK NOT WRITTEN
Explanation: The <CR> reply was given to indicate that no new
volume would be mounted when an end-of-volume was encountered on
cassette output. The block that FLX was attempting to write when
it encountered the end of the cassette has not been written1 the
output file is incomplete.
action

Explanation: The record size specified with /FA, /FB, or /IM
not acceptable. A record size of 512(10) bytes is assumed.

User Action:
required.

This

message

FLX -- WARNING -- SPECIFIED RECORD SIZE BAD, 512.

User Action:

informational1

This is a warning message.

USED

No action is required.

FLX --UNABLE TO ALLOCATE FILE
Explanation: No space is available on
volume for the specified file.

the

User Action:
command line.

files

Delete

all

unnecessary

DOS-11
and

Files-11

reenter

the

FLX -- UNABLE TO OPEN FILE
Explanation: A specified input or output Files-11 file could not
be opened. Possible reasons are:
•

The input file does not exist.

•

The volume is not mounted.

•

A protection violation occurred.

User Action:

~
!
r

Correct the condition and reenter the command line.

FLX -- UNABLE TO OPEN LIST FILE

'i'

Explanation: The list file cannot be opened under the specified
file name and UFD, or the specified device may not be a valid
F iles-11 volume.
User Action: Reenter the command
file name and UFD.

line

specifying

the

correct

FLX -- UNDIAGNOSABLE REQUEST
Explanation:

FLX does not recognize the command line syntax.

User Action:

Reenter the command line with the proper syntax.

5-22

'!l!ICZU!

I Iµ

FILE TRANSFER PROGRAM (FLX)
FLX -- /CO F'ILES FROM INPUT DEVICE NOT ALLOWED UNLESS BL:

SPEC

Explanation: When transferring files from MT, PR, or CT, /CO can
only be specified when /BL is also specified.
User Ac:tion:

Reenter the command line, specifying /BL.

FLX -·- * IN VERSION NUMBER NOT ALLOWED
Explanation: A wildcard was detected in the version number field
of a file specification.
User Ac:tion: Reenter the command line with all
explicitly specified.

5-23

version

numbers

JUI$

ii;

pl#

PART 4
FILE SPOOLING UTILITIES

i\&

I I

mt a

)!iii

CHAPTER 6
PRINT AND QUEUE UTILITY

This chapter is for RSX-llM only.
Users of RSX-llM-PLUS should see
the RSX-llM-PLUS Batch and Queue Operations Manual for corresponding
information.

6.1

INTRODUCTION TO THE PRINT COMMAND AND QUEUE MANAGER

The Print command spools print jobs and places
controlled by the Queue Manager for despooling.

them

queue

The most common use of this command is printing files on the system's
line printer.
Some systems may use a high-speed terminal as a line
printer. There may be more than one output device receiving jobs from
the Queue Manager.
Other likely output devices include paper-tape punches,
electrostatic
plotters,
or magtapes.
Jobs sent to such devices are still called
print jobs because they are sent by the Print command.
In general,
in this chapter,
"to print"
"printer" and "output device," are synonyms.

and

"to

despool,"

and

"Spool" is an acronym for Shared Peripheral Operations On-Line.
Spooling on RSX-llM is gathering output sent to an output device on a
mass-stora9e device - usually a disk ·- to be passed in an orderly
fashion to the output device. Despooling is the orderly transfer of
this output from the mass-storage device to the output deviceo
The Print command requires the presence of the Queue Manager.
installations have the Queue Manager.

Not all

To be sure, check the list of installed tasks (issue the TAL command)
to see if both QMG...
and PRT...
are installed.
If both are
installed, your system includes the Queue Manager.
If only PRT •••
is
installed,
your system has the serial print despooler.
In this case,
you can only use the PIP /SP switch to send files to the line printer.
If neither
is installed; you must use PIP to send files directly to
the line printer with a command in the form PIP LPO:=filespec.
If you
use this command, you have no protection against another user issuing
the same command at the same time, in which case your output and the
other user's may be interspersed on the line printer.
If you have any doubts about the situation at your installation, see
your system management for information. Documentation on the serial
despooler appears
in Appendix C of this manual.
For
further
information on PIP, see Chapter 4 of this manual.

6-1

PRINT AND QUEUE UTILITY

The Print command, in its simplest form,
>PRI f ilespec
places an entry in the file SY: [l,7]QUEUR.SY~. This queue entry has a
unique number and a name based on the first six characters of the file
name. The entry is placed in the default queue PRINT. When the line
printer is free,
the file is despooled by the print processor and
passed by the processor to the line printer and printed.
After
printing, the entry disappears from the queue file in (1,7]. Some or
all of the contents of the queue file can be displayed by using QUE
commands discussed later in this chapter.
The Print command accepts multiple file specifications and wildcards.
Files are despooled in the order given, without interruption, on the
same print processor. With wildcards, the files are despooled in the
order they appear in the UFO, as displayed by a PIP /LI command.
The Print command defines a print job for the Queue Manager.
job can have one or more files in it.

Switches on the Print command can specify many attributes of the print
job. These attributes include the following:
•

Time the spooling is to be done

•

Device to accept spooled output

•

Queue priority of the job

•

Restartability of the job

•

Forms the job is to be printed on

•

Number of lines per page

•

Number of copies of each file to be printed

•

Choice of deletion after spooling

'~
I

Commands to the Queue Manager permit the user to display the queues or
an individual job in a queue or to modify most attributes of a job in
a queue. Users can also hold a job in a queue, release it, or remove
it from a queue.
You do not have to invoke the Queue Manager to get access to it8
The
Print command does this automatically. Commands directly to the Queue
Manager are on one line and start with QUE.
Unlike other RSX-llM
utilities, the Queue Manager does not issue a QUE> prompt. The Queue
Manager can only be accessed through the one-line format.
User
commands to the Queue Manager are described in this chapter. For full
details see Chapter 7 of this manual.
A number of system tasks can create printable output.
The output
includes Task Builder maps, MACR0-11 assembly listings, and listings
from the high-level language compilers. These tasks are accessible
directly from MCR.
These tasks follow their own rules for spooling
output, but when you request that such output be spooled, it will be
handled by the Queue Manager.
You cannot control the despooling of such output directly, as you can
through the Print command, but once the jobs appear in a queue, you
can alter their attributes through the QUE /MOD commands.

6-2

PRINT AND QUEUE UTILITY

If the Queue Manager is not installed and the serial despooler is
installed, system tasks that create printable output work as usual.
If neither the Queue Manager nor the serial despooler is installed,
the map or listing file is created and written on the disk, but is not
printed on the line printer.
You can also use PIP, the Peripheral
print jobs.

Interchange

Program,

queue

The following PIP command:
PIP> NAME.TYP /SP
causies the file NAME.TYP to be queued for despooling. The print
has a name derived from the name of the first file in the job.

job

You cannot control the despooling of such jobs directly, as you can
through the Print command, but once the jobs appear in a queue, you
can alter their attributes through the QUE /MOD command. ·
For information on writing user tasks to
6.5.

6.2

spool

output,

see

Section

PRINT COMMAND FORMAT

The format of the Print command is:
>PRIN1 [[ddnn:]jobname [/jsw]=filespec [/fsw [/fsw]] [,filespec [/fsw]]
1

ddnn:
Specifies the despool device to be used.
jobname
Specifies the name to be given to the print job.
/jsw
Specifies one or more job-related switches

Specifies the file to be spooled, in standard RSX-llM format.
f sw

Specifies one or more file-related switches.
There are defaults for most of these fields:
•

ddnn:

defaults to the PRINT queue.

•

jobname defaults to a name
characters of the file name.

•

filespec defaults are SY:
.LST for the file type.

•

Switch defaults are included in the
Se<::tion 6. 3.

derived

from

for the device,

6-3

command

the

first

six

current

UFO,

and

descriptions

PRINT AND QUEUE UTILITY

6.3

PRINT COMMAND DESCRIPTION

The Print command passes print jobs
despooling, as described in Section 6.1.

the

Queue

Multiple filespecs, separated by commas,
( * ) are also acceptable.

are

acceptable.

Manager

for

Wildcards

A detailed description of each field of the Print command is
below.

provided

ddnn:
Each output device is served by a device-specific queue.
This
queue is named after the device it serves. Thus, LPO: has the
device-specific queue LPQO, TT21:
(if set spooled) has the
device-specific queue TTQ21. To send a print job to a specific
device, include the device name in this field. The Queue Manager
directs the job to the proper queue for that device. If the file
does not exist, the command is rejected.
The device named must be set spooled or the job will not run.
If no device is named, jobs are sent to the default queue PRINT.
job name
Job names can be from one to six alphanumeric characters.
The
job is displayed in the queue under this name. The name also
appears on the job flag page. See Figure 6-1 for the layout of
the job and file flag pages.
If no job name is supplied, the name is derived from the first
six characters of the first file name in the job. If the first
file name in the job is *, then the name PRINT is given to the
job.
Each job also has a queue entry number that is displayed
QUEUE /LI display.

the

/jsw
Job-related switches must be placed to the left of the equals
( = ).
The
is required syntax if you include any job-related
switches.
All switches can be abbreviated to two characters, not counting
any preceding NO or minus
- ) if permitted. Switches can be
listed in any order.
A blank before the slash ( I ) is accepted but not required.
A description of each of the
below.

job-related

switches

provided

/AFter:hh:mm
The job is time-blocked in its queue until after the stated time;
hh can be from 0 to 23; mm can be from 0 to 59.
If this switch is not specified, the job is enqueued
on the present day, that is, immediately.

after

0:00

·~
6-4

iii!

I.I

l"''

PRINT AND QUEUE UTILITY
This switch does not set the time the job will be printed.
It
sets the time after which the job is eligible to be printed.
If
there are other jobs in the queue ahead of it when the specified
time arrives, these jobs are printed before your job.
This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.
/[NO]FLag
If the /FL switch is applied, each file in the job is preceded by
one ()r more file flag pages (depending on how the printer is set
up) in addition to the one or more job flag pages that precede
the entire job.
The default for files
is /NOFLAG.
Only job flag pages are
printed.
Files are printed sequentially, separated only by form
feeds.
A SYSGEN option permits overriding the default and forcing flag
pages.
If this option has been applied, it can be overridden by
setting /NOFLAG.
The job flag pages have the UIC the
under
and the job name printed
characters.

Print command was
on them in large

issued
banner

The file flag pages have the file name and type printed on them
in large banner characters.
See Figure 6-1 for the layout of the
job and file flag pages.
This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.
/PRiority: n
This switch sets the priority of the job in its queue.
can be from 0 through 250.

Priority

The default priority is 50.
The Queue Manager places jobs in the queue according to priority.
Jobs of equal priority appear in the queue in the order they were
submitted. The highest priority job is the first
job processed
when the printer becomes available. Within a group of jobs of
the same priority, the one that has been waiting the longest is
processed first.
This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.

/ff Old
This switch holds the job in its queue until it is released by
the QUE jobname /RElease command. See the examples at the end of
this section.

6-5

PRINT AND QUEUE UTILITY
** RSX•l IM V3,2 **
n.z ••

Ill i!3tl5o789<112 J115& 78'1
ll U3115&789,ll 2l115&789
912311511789111231151>78'1
Ill 23115b7A'lu 12l45b 789

RO•tl"
•• RSX•ttH

l3;ii3,5J~ISt<

•NO PAGE LIMIT

FOllM ll<) • /loORMAL

MAMD~ARE

··o IHPL!fO rnRH FEED

v3,z ••

FURH8

11~01 [303,S)F!$H,S•M1 I

•• RSx•11H v1,2 ••

25•MAY•79
i!S•HAY•7'
i!5•MAV•79
25•MAV•79

131111 lli
131111132
131111132
1314111 Ji!

~
I

Cll [ 11

l'lil01/10il
1111001hl

l333ll

[l[l[I

3l33U

33
33

1!0
II~

0k'

l!hl
03

001111
0111!0

ll
33

[I
[I
[I
II

33
333333
333333

[ ll I [ [

,.,,,,,,,,,,
,,.,,,.,.,,.,,,,,,,,
,,,,.,
,,,,,,.,,,,
,,,,,,,,,

110

""00

111111
11
II
ll

SS
SS
SS

II
11
II
11
II
II
II 1111
111111

FF
,,,.
,,,

u
SS
SS
SS

333333
33333J

SS88SSSS

SS
SS
SS
USS SS

suns

ssussss
ussuas

SS
SS

5555555555
5555555555
55
55
555555
555555
55
55
55
55
55
55
55
55
555555
555555

l JI 1 l I
I II l l I
ll

II
ll
JI

ll
JI

JI
IJ

l JI 111
llllll

Ht<
HM
Ht<
HM
HI<
HM
HM
HM
HM
HH
MM
HM
HHHHHMHl'IHH
MHMHHHHl'IHH
MH
HH
HH
HH
HH
HM
HH
HH
HH
HH
HH
HH

FOR" 10 • "'0RMAI. HARDWARE P'ORMI
NO IMPLIED FORM FEED
L'Bl'll [30315JFISt<,SWH1I

i!S•MAY•7•
25•MAY•79
i!S•MAY•79
i!5•MAY•79

UlllllU
UlllllJ2
IJlllllJ2
IJl4113i!

0801 [303,SI F!St<,SWMI I
~ QPY l OF I
DELETION NOT SPECIFIED

i!5•HAY•79
i!5•MAY•79
i5•MAY•79

131111135
l3111llJ5
13141135

l3111315l'!St-

RSX•ll~ V3o2
RSX•llM V3,2

snsssss

,,,,
33
33

RSX•t IM V3o2

,,,,

33
33
H

** ~SX•llM V3,2 **
** RSX•ll" V],2
**
v3,z ••
** l!SX•llH VJ,2 **

IIIIl I
111111
II
11
II
II
II
II
II
II
II
II
111111
111111

33
33

•• l!SX•11H

1111231151178'1! I "3456789
81UllS6789;.112311S&789
1111234'511789~ 123456 789

,,,,,.,.
,.,.
,.,,
,,,.

ssussss
ssnssss

ssssssss
sssssssa

"12311511789012311511789
812345117891! 12345&789
ll I U11'36 7&9012345678•

""'rf'l'Fl'FF

11000011
01!0000

SSS SSS
SSS SSS

8123115b7890 l23115&7H

,,,,.,.,,,,,,,
,,,.
,,,,.,,
,,,,.,,,.,.,,.,.,,
,,,,,,,.,,.
,.,,

3J
33

(.I~

031!0

Itllll

,,,,,.

Ill•

ti [[ [ (

33
33

""
0000 ""' 0il

33
33
33

110

011

33
33

[I
[l
[l

333333
333333

• NO PAGt LlMIT

IUJllS6'7 .. llUllU7 . .
IUJli5'7lt111:SiSi7H
llUS4U78tllU4Sii7 . .
11U~Sli?it11U4Si7H

111u11s.1n112s11n11t
llU4Sli71911U4Sii7H
llUJ4SOit112J4Si?H

HH
HM
HM
Ml'!
HI'!
HH
HH
HH
HM
HH
HH
HH
'IHHHHHHHHH
HHHHHHHHHM
HM
HH
HM
HH
HH
HH
HM
HH
HM
HI'!
HH
HI<

HS HHS
USHSU

II
SS

SS SS SS
HUSS
SS
SS
SS

ssssssss

uuuss

WW
WW
WW
WW
WW
WW
WW
WW

WW
WW

MM
HH
MM
HM
MHMM
MMMM
MMHH
HHHM
HM
MM
MM
MM
MM
H'I

WW
WW
WW
WW
WW
WW
WW
WW
WW
WW

"'""'"

MM
MM
l'M
HM
MM
MM

""
wwww wwww
wwww
""

wi.ww

111123115678•" 1231151178•
8123115117891! I i!345b789
11112345678914 I i!34Sb789

""
""
""
'"'
""
""
'"',,
"

""'MM
MM
HM
MM
MM
MH

111 I

** ASX•l IH VJ,2 **
** llSX•llH VJ.2 **
u

llSX•llM V3o2

II
II
1111
1111
II
II
II
II
II
II
II
II
111111
111111

0801 [l0l,SJF1SH,SwH1I

COPY l OF I

liELETION "'OT SPECIFIEO

Figure 6-1

25•HAY•79
25•MAY•7'
25•11AY•79

l31lll1l5

UllllllS
131111135

Job Flag Page and File Flag Page

6-6

"a::z

s:::

PRINT AND QUEUE UTILITY
/LEngth:n
This switch sets the number of lines per page. Length can be ~et
from 1 through 65535.
When this switch is applied, the print
processor issues a form feed if one is not encountered within n
lines.
A form feed causes the line printer to move the paper
down to the beginning of the next form.
Form length is
determined by the hardware and the print processor software.
The default is a page of infinite length.
This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.
/FOrm:n
This switch sets the forms setting that an output device must
have to accept the job. Your system manager has information on
which forms used in your installation take which numbers.
If
this switch is set, the job waits until a printer with the
matching forms setting is available.
The default n is O, which is the standard line-printer
most installations.

setup

This switch is used to print jobs on special forms,
checks,
invoices,
or
other
special forms used
installation.

such as
in your

This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.
/[NO]REstart
This switch makes the job restartable
[or not].
If /RE is
specified and the job does not complete its run for some reason,
when the system, or print processor, or Queue Manager is
restarted,
the job is restarted from the beginning of the first
file in the job.
/NOREstart is the default.
If the job's run is interrupted,
it
is restarted at the top of the file that was being despooled at
the time the job was interrupted.
In no case is any job or part of a job lost, but if you
switch, the job will be all in one piece.

set

the

This switch setting can be changed after the job is placed in its
queue by the QUE /MOD command.
filespec[s]
Users can print any file to which they have Read access.
The usual rules on wildcards and defaults apply, except that
default file type is .LST.

the

Multiple filespecs must be separated by commas.
Files cannot be renamed or deleted before they are printed.
Files must have the same name and type, be on the same volume,
and reside in the same directory from the time they are placed in
the queue until they are despooled.

6-7

PRINT AND QUEUE UTILITY
If the files are on a volume on a medium mounted on a private
device, the volume cannot be removed or dismounted before the
files are despooled. If the volume is dismounted, the print job
remains in the queue and the flag pages are printed, with an
error message noting a failure to open the file.
/f sw

File-related switches can follow
line.

any

filespec

the

command

File-related switches are applied to all filespecs that follow
the f ilespec to which they are attached unless overridden. See
the examples at the end of this section.
All switches can be abbreviated as indicated, not counting any NO
or minus ( - ) if permitted.
Switches can be listed in any
order.
/COpies:n
This switch
despooled.

sets

the

number

copies

the

file

If applied to multiple filespecs, each file is printed n times
before any copies of the next file are printed. That is, this
switch does not queue up two copies of the entire job, it only
determines how many copies of each file are to be made.
If you do not specify this switch, the default n is 1.
/[NO]OELete
This switch directs the Queue Manager to delete the file from its
UFO after it is despooled.
NOOELete is the default.
Examples
>PRINT JAM
The most recent version of JAM.LST from the default device
UFO goes in the default queue PRINT taking all defaults.

and

>PRINT /FLAG=PAUL.MAC,ALAN.MAC,TOM.MAC
The files named go to the default queue PRINT as one print job.
They are printed in the order listed. The job name is PAUL. The
name appears on the first flag page along with the UIC the Print
command was issued under. Each individual file is preceded by
file flag pages with the file name, file type, and version
number.
Any command including a job-related switch, such as
FLAG, must include the equals ( = ).
>PRI /FL=PAUL.MAC,ALAN.MAC /C0:2,TOM.MAC
The Print command defines a single print job consisting of one
copy of PAUL.MAC, followed by two copies of ALAN.MAC, and two
copies of TOM.MAC. Each copy of each file is preceded by flag
pages.

6-8

·u11 22122

I Qt!

:; (

Jj411¢1

PRINT AND QUEUE UTILITY
>PRI /FORM:2 /PRIORITY:75=PAYROLL
The job name is PAYROL. It has a priority of 75, but it will not
be
despooled
until
an
output
device
with the proper
forms - paychecks in this case
is available.
The file is
PAYROLL.LST.
>PRI INDEX /AFTER:l6:00=CHAP1.NDX,CHAP2.NDX,CHAP3.NDX,CHAP4.NDX
The job is named INDEX. It is time-blocked in the PRINT queue
until after 4:00 pm. At that time, it is placed in contention
for the pr~nter, but the time it will be printed depends on what
else is in the queue when INDEX is released. This is the
equivalent of issuing the same Print command at exactly 16:00.

6.4

QUEUE MANAGER COMMAND FORMAT

The format of commands to the Queue Manager is
>QUE job-id /switch[:option]
The job identification (job-id) can be either the name assigned to the
job at the time of submission or the unique entry number assigned the
job by the Queue Manager and displayed by the QUE /LI command.
The entry number is displayed in the form
commands in the form JOB:nl:n2.

(nl,n2).

used

Queue Manager commands allow the nonprivileged user to
•

List queue entries in various

•

Modify attributes of jobs after submission

•

Hold jobs in a queue

•

Release held jobs

•

Delete jobs f r~m a queue

format~

All Queue Manager commands are in single-line format.

QUEUE /LIST Command

6.4.1

This command is used to list the queue entries.
Unless you specify
options, or name an output device, only jobs in the default queue
PRINT are displayed.
The display also shows which output devices queues are assigned to.

Forn1at
>QUE job-id /sw[:option]
Switches

Options

/BRief
/LI st
/FUll

:QUE
:ALLQUE
:DEV
:ALLDEV
6-9

PRINT AND QUEUE UTILITY
Job Identification Field
There are three ways you can specify
Details on each are provided below.

the

contents

this

field.

[ddnn: [uic]]jobname
The job name alone is sufficient identification if the job is
from the same UIC you are logged in to and if you have not
specified a device in your Print command. Although the UIC is
optional, the brackets around the UIC must be included if you
include the UIC in the command line. If you wish to display only
entries queued to a particular output device, name the output
device in the command. Each output device has a queue named
after it (device LPO:
has queue LPQO).
When you name the
device, you are specifying the queue whose contents you wish to
display.
/JOB:nl:n2
Note that the display format and
entry
number
are different.
I JOB: nl : n2 •

the command format
Display:
(nl,n2).

for this
Command:

[uic]
This form of job identification displays all jobs in queues
a particular UIC.

from

Switches

/BRief
The brief format displays only the job names, the UIC from which
the Print command was issued, the queue entry number, and the
status of the job.
Jobs can be ACTIVE, HELD, PRINT AFTER
(time-blocked), or waiting.
A blank status field indicates a
waiting job.

~-·

/LI st
The standard format displays job names, the UIC from which the
Print command was issued, the queue entry number, the status of
~~~-job,

and the filespecs of all files necessary to complete the

'1'11

If you have not specified restartability in the Print command,
only
the file being printed and any remaining files are
displayed.
If you have specified restartability, then all files in
are displayed.

the

job

/FUll
The full format displays job names, the UIC from which the Print
command was issued, the queue entry number, the status of the
job, the filespecs of all files necessary to complete the job,
and all attributes of the job, whether set explicitly or by
default.

6-10

il!llZ

PRINT AND QUEUE UTILITY
Opti~ons

:QUE
This is the default.
PRINT.

Displays

entries

the

default

queue

:ALLQUE
Displays all entries in all queues.
:DEV

Displays characteristics of a device.
If you have not specified
a device in the job-identification field of the command line, you
will get an error message.
:ALLDEV
Displays characteristics of all spooled devices.
Examples

>QUE /LIST

** PRINT QUEUES **
PRI.NT => LPO:
[304,303] SCNDIR (20000,126)
DB0:[304,303]SCNDIR.LST;l74
[7,372]
RELABE (2100,130)
DB0:[7,372]RELABEL.FL0;2

ACTIVE ON LPO:

This example displays all the jobs in the default queue PRINT.
The display
assigned.

shows

the

line

printer

which

the

queue

For each job in the queue, the display shows the UIC from which
the Print command was issued, the job name (based on the name of
the first file in the job), a unique queue entry number,
the
status of the job, and the filespecs for all files in the job.
The job named SCNDIR is active, as shown. The job named RELABE
is waiting, as indicated by a blank status field.
Status field
may also show HELD jobs and PRINT AFTER (time-blocked) jobs.
>QUE /LIST:QUE

** PRINT QUEUES **
PRINT => LPO:
[304 ,303] SCNDIR ( 2000 ,126)
DB0:[304,303]SCNDIR.LST;l74
[7,372]
RELABE (2100,130)
DB0:[7,372]RELABEL.FL0;2
This example is the equivalent
option :QUE is the default
queue PRINT are displayed.

6-11

of the
option.

ACTIVE ON LPO:

previous example.
The
Only jobs in the default

PRINT AND QUEUE UTILITY
>QUE LPl: /LIST

** PRINT QUEUES **

~
I.

ACTIVE ON LPl:

LPQl => LPl:
[303 ,5] IZZY ( 2400 ,132)
DB0:[303,5]IZZY.TXT;l

This example displays queue LPQl, which is assigned to printer
LPl:. The user specified this queue by naming the printer in the
QUE /LI command.
>QUE PRTJOB /LIST /FU

** PRINT QUEUES **
PRINT => ( LPl:)
[301,370]PRTJOB (2140,162) FORM:O
PRI:50 LEN:O PAGE:O NORESTART NOFLAG
DB0:[301,370]PRTJOB.TXT;22
COP:l

NODELETE

This example displays in full mode information
named PRTJOB from the default queue PRINT.
The display shows all attributes of the
set or set by default.

job,

about

either

the

job

~
I

explicitly

NOTE
Parentheses around the line printer name
mean that the printer has been stopped
by the Queue Manager at the operator's
request.
>QUE [301,370 /BR

** PRINT QUEUES **
PRINT=> LPO:
[301,370]DUNGEO
[301,370]RUNOFF

ACTIVE ON LPO:
HELD

(2200,116)
(1320,660)

This example displays in brief mode all the jobs
(301,370]
in
the default queue PRINT.
No
displayed.

created under
f ilespecs
are

>QUE /LI :ALL

** PRINT QUEUES **
PRINT => LPO:
[7 ,372] RELABE ( 2100 ,130)
DB0:[7,372]RELABEL.FL0;2
[7,372] LPDRV (2000,134)
DB0:[7,372]LPDRV.MAC;2
LPQO => LPO:
[222,333] CORFIL (2200,136)
DB0:[222,333]CORFIL.COR;4

ACTIVE ON LPO:
HELD
PRINT AFTER 18-DEC-78 17:00

This example displays all the jobs in all the queues.
All jobs
are displayed because there is no job identification given. All
queues are displayed because :ALL is specified.

6-12

d2$11 U22 SQ

!!!!!$ Liii!

Ji iii I .

!Si&liiii

4:;

PRINT AND QUEUE UTILITY
>QUE /FU :ALL

** PRINT QUEUES **
PRINT=> LPO:
[7,372] RELABE (2100,130) FORM:O
ACTIVE ON LPO:
PRI:50 LEN:O NORESTART FLAG
DB0:[7,372]RELABEL.FL0;2 COP:l NODELETE
[7,372] LPDRV (2000,134) FORM:O HELD
PRI:50 LEN:55 PAGE:O NORESTART NOFLAG
DB0:[7,372]LPDRV.MAC;2 COP:SO NODELETE
LPQO => LPO:
[222,333] CORFIL (2200,136) FORM:l PRINT AFTER 18-DEC-78 17:00
PRI:lOO LEN:O PAGE:O RESTART NOFLAG
DB0:[222,333]CORFIL.COR;4 COP:l DELETE
This example displays in full format all the jobs in all the
queues.
All
jobs are displayed because there is no job
identification given. All queues are displayed because :ALL is
specified.
>QUE LP: /LI:DEV

** SPOOLED DEVICES **
LPO:
<= PRINT LPQO
.FORM: 0 FLAG : 1
CURRENT JOB:
[7,2]SYSXTN

(2000,127)

This example displays all
spooled
devices,
shows
queue
assignments to them, and shows the attributes of the devices.
If there is no current job on a device, the current-job line does
not appear.

QUE /MOD Command

6.4.2

This command is used to modify the attributes given to queue entries
by the Print command.
Only the attributes listed here can be
modified.
Form.at
>QUE job-id /MODify /sw
Switches
/AFTER:hh:mm

I [NO] li'LAG
/LEngt.h:n
/PRiol'i ty: n
/FOrm:n
/[NO]REstart

6-13

PRINT AND QUEUE UTILITY
Job Identification Field
There are two ways you can specify
Details on each are provided below.

the

contents

this

field.

'i':_-.

the command format
Display:
(nl,n2).

for this
Command:

Switches
Switches name the attribute to be modified. All sw~tches can be
abbreviated as indicated, not counting any NO or - if permitted.

"'i"i-'-'-

The QUE /FU commands display attribute information.
The Print
command description includes a discussion of the meaning of each
attribute.
/AFter:hh:mm
Modifies the time after which the job is to be despooled.
/[NO]FLag
Modifies the FLAG attributes of the job.
/LEngth:n
Modifies the LENGTH attribute of the job, which is the number
lines to the page.

/PRiority:n
Modifies the queue priority ot the job.
/FOrm:n
Modifies the FORM attribute of the job.
/[NO]REStart
Modifies the RESTART attribute of the job.

6.4.3

QUEUE /HOLD Command

This command holds a job in its queue.

The job will not be despooled.

Format
>QUE job-id /HOLD

6-14

. lllSSSS!iiil

iii!)

;;; a I

PRINT AND QUEUE UTILITY
Job Identification Field

\..I

There are two ways you can specify
Details on each are provided below.

the

contents

this

field.

for this
(nl,n2).

/HOLD
The job is held in its queue. The job remains in its queue, but
is not eligible for processing. The effect is the same as the
/HOLD qualifier to the Print command.
You cannot hold an active job.
being printed.

An active job is a job

currently

Exam:ples
>QUE BIGJOB /HOLD
The job named BIGJOB from the default device and UIC is
the PRINT queue.

held

queue

for

>QUE LP1:[303,5]LILJOB /HOLD
The job named LILJOB from UIC [303,5] is held in
LPl:. This queue is named LPQl.

6 •4 •4

the

QUEUE /RELEASE Command

This command releases held jobs from their queues.
The job to be
released must be marked HELD. You cannot release PRINT AFTER jobs
with this command~ You must use QUE /MOD /AFTER to release such
time-blocked jobs~
Format
>QUE job-id /RELease

6-15

PRINT AND QUEUE UTILITY
Job Identification Field
There are two ways you can specify
Details on each are provided below.

the

contents

this

field.

for this
(nl,n2).

Switch
/RELease
Releases a held job making it eligible for processing.
This is
equivalent to placing the job in its queue. The job must still
wait its turn to be despooled.
Example
>QUE READY /REL
The job named READY from the default device and UIC
from the held state and is eligible for processing.

released

>QUE LATER /REL
QUE -- JOB DOES NOT EXIST
The user attempted to release a PRINT AFTER (time-blocked)
The job exists, but no HELD job of that name exists.

6.4.5

job.

QUEUE /DELETE Command

This command deletes print jobs from queues.
It does not delete files from directories.
the PIP /DE or PRINT /DE command switches.

It has

connection

Format
>QUE job-id /DELETE

6-16

Iu:;

).!

t;UP

PRINT AND QUEUE UTILITY

Job Identification Field
There are two ways you can specify
Details on each are provided below.

the

contents

this

field.

Note that the display format and the command format
entry
number
are
different.
Display:
Command: /JOB:nl:n2.
Switch
/DELETE

Deletes the specified queue entry. If the job is active at the
time the command is issued, the output ceases and the queue entry
is deleted.
Exa1mple

>QUE BADJOB /DELETE
The job named BADJOB from the default device and UIC
from the default queue PRINT.

6.5

deleted

PRINT JOBS QUEUED BY USER TASKS - OUTPUT SPOOLING

There are two means of spooling output from user-written
first is from within the task:
•

Open a file on disk and use PRINT$ macro or .PRINT
using FCS.

tasks.

The

subroutine

Because the line printer (or other output device) is attached and
owned by its despooling task (print processor), you cannot attach and
write logical blocks to the device.
The Write Logical Blocks
operation fails and an Attach operation does not complete. Thus, you
cannot in your user program issue an ALUN$ directive and expect QIOs
to that LUN to work. If you wish to use this procedure, you must set
the device unspooled by deleting the processor. An unspooled device
is not accessible by the Queue Manager.
You cannot control the despooling of jobs queued with the PRINT$ macro
or .PRINT subroutine directly, as you can through the Print command.
Once the jobs appear in a queue, however, you can alter their
attributes through the QUE /MOD command.
The alternate method of spooling output is from outside the task:
•

Open a file on disk and use the Print command on task exit.

This is the only means of spooling output that gives you full
over how, when and where your output is despooled.

6-17

control

PRINT AND QUEUE UTILITY
6.5.l

Opening A File On Disk and Using FCS

Your task should open a file on disk and output to it. The task can
then issue the PRINT$ macro call or call the .PRINT subroutine to
close the file and spool the output.

·~.l

The file is placed in the default queue PRINT.
In FORTRAN, the equivalent is to use DISP= 'PRINT'
CLOSE statement.

your

OPEN

You cannot control the despooling of such output directly, as you can
through the Print command, but once the jobs appear in a queue, you
can alter their attributes through the QUE /MOD commands.
See Chapter 8 of
more information

Manual

for

Your task should open a file on disk, output to it, and close
Once your task exits, despool the file with the Print command.

it.

6.5.2

Reference

Opening A File On Disk and Using the Print Command

""'
.•. I [,

While this is not the simplest method of spooling, it is the only
method that gives you access to the qualifiers on the Print command.
You can accomplish much the same thing using the other method by
waiting until the job is in the queue and then altering its attributes
with the QUE /MOD command.
If you run your task from an indirect command file that includes a
Print command after task exit, the difference between spooling from
within the task or from outside it will probably not be noticeable.

6.6

ERROR MESSAGES

Error messages from the Queue Manager may be preceded by the letters
PRI or QUE, depend1ng on where within the software the error detection
takes place. Here is how they appear on your terminal:
PR!

NO SUCH FILE

QUE

NO FUNCTION SPECIFIED

·~
i

The PRI and QUE identifiers are not used in this section.
When you
receive an error message such as those above, look for the message
portion (NO SUCH FILE or NO FUNCTION SPECIFIED in the examples above).
The message portion of each error message appears in alphabetical
order in this section along with a description of the error that
produced the message and a suggested correction.
If you issue a QUE /LI (or /BR or /FU) and only a prompt is
this means no queue file exists on your system.

returned,

In most cases, the error will be a typing mistake or other syntax
error.
In a few cases, you will be directed to inform your system
manager of the error.

6-18

Si i

I i i !iii! I !$$$ iiiii

PRINT AND QUEUE UTILITY
BAD COMMAND LINE
Explanation:
command.

Invalid MCR line, or invalid syntax in Print or QUE

User Action:

Retype command line.

BAD FILE SP.EC SWITCH VALUE
Explanation:

Bad value for file switch (/CO).

User Action:

Retype command line after checking switch value.

BAD JOB SWITCH VALUE

'-'/

Explanations

Bad value for job switch (/AF, /FO, /LE, /PR).

User Action:

Retype command line after checking switch value •.

BAD MODIFY VALUE
Explanation:

Bad Modify switch value.

User Action:

Retype command line after checking switch value.

BAD SWITCH TYPE
Explanation:

Bad ASCII switch value (QMG, EOF, etc.).

User Action:

Retype command line after checking switch type.

BAD SWITCH VALUE
Explanation:

Bad numeric switch value.

User Action:

Retype command line after checking switch value.

BAD SWITCH FOR FUNCTION
Explanation:
function.

The

switch

specified

not

allowed

for

User Action:

Retype command line after checking switch type.

this

DEVICE/QUEUE DOES NOT EXIST
Explanation:
by QMG.

Command directed to device or queue not

controlled

QUE

/LI:ALLQUE

User Action: QUE /LI:ALLDEV lists all devices.
lists all queues.
DIRECTORY NOT ALLOWED
Explanation:

UIC not allowed on this command.

User Action:

Retype command line without UIC.
6-19

PRINT AND QUEUE UTILITY
ILLEGAL ARGUMENT VALUE
Explanation:

The argument value is not valid.

User Action:

Retype command after checking syntax.

~
I

QMG ERROR ( n)
Explanation:

Command in error or QMG task in error.

User Action: Look up n on list. If QMG task is in error, n will
help pinpoint error. See your system manager. Retype command.
Meaning

63.
68.

69.
71.

72.
73.
84.
91.
9 2.
100.
104.
105.

BAD PROCESSOR NAME
QUEUE MARKED FOR DELETE
PROCESSOR MARKED FOR DELETE
PROCESSOR DIRECTORY FULL
QUEUE AND PROCESSOR NOT SAME TYPE
JOB EXISTS ALREADY.
SPOOLED DEVICE REDIRECTED
INTERMEDIATE DEVICE BUSY - TRY AGAIN
BAD QUEUE NAME
VIRTUAL TERMINALS NOT SUPPORTED
ILLEGAL OR NON-EXISTENT INTERMEDIATE DEVICE
INTERMEDIATE DEVICE NOT MOUNTED

QE.BSN
QE .QMD
QE .SMD
QE.SDF
QE.TYP
QE .JEA
QE.RED
QE. IDB
QE.BQN
QE .NVT
QE. I ID
QE.INM

INVALID FILE SPEC SYNTAX
Explanation:

Invalid syntax in a filespec.

User Action:

Retype command line after correcting f ilespec.

INVALID ENTRY NUMBER
Explanation:

Invalid syntax for entry number.

User Action: Retype command after correcting entry number.
The
display format and the command format for entry number are
different. Display:
(nl,n2). Command: /JOB:nl:n2.
INVALID JOB SYNTAX
Preceded by PR!
Explanation:
•

Invalid syntax in the job field

•

Wildcards in job name

•

Multiple job fields

•

UIC present

•

Bad terminator for job name (
terminators)

User Action:

are

the

only

legal

Retype command line after checking proper syntax.

6-20

!ill

I h iil!i !LU

'C4 ii

lid!

i!i!ilili

iifkl

PRINT AND QUEUE UTILITY
Preceded by QUE
Explanation:
•

Invalid syntax in the command

•

Invalid job name

•

Both job name and entry number specified

•

Neither job name nor entry number specified

User Action:

Retype command line after checking proper syntax.

I/O ERROR ON SY:QUEUE.SYS
Explanation:

Error encountered reading the queue file.

User Action:

See your system manager.

JOB DOES NOT EXIST
Explanation:
current UIC
command.

Specified job does not exist in queue under the
and the status (example, HELD) that you supplied in

User Action: Retype command after checking job
identification with QUE /LI.

status

and

job

identification

not

JOB NAME NOT ALLOWED
Explanation: Job name or other form of
allowed on this command.
User Action:

job

Retype command line after checking proper syntax.

MULTIPLE FUNCTIONS DETECTED
Explanation:

More than one function specified.

User Action:

Retype command line after checking proper syntax.

MUTUALLY EXCLUSIVE SWITCH/VALUE
Explanation:

Function value and switch mutually exclusive.

User Action:

Retype command line after checking proper syntax.

NO E'ILE NAME GIVEN
Explanation:

No file name given in a file spec.

User Action:

Retype command including file name.

6-21

PRINT AND QUEUE UTILITY
NO JOB FIELD GIVEN
Explanation:

The command syntax requires a job field.

User Action:

Retype command line after checking proper syntax.

NO FUNCTION SPECIFIED
Explanation:

No function specified in command line.

User Action:

Retype command line after checking proper syntax.

NO POOL SPACE
Explanation: Dynamic storage region has been exhausted;
the
system is either heavily loaded or there is a system problem.
User Action:

See your system manager.

NO SWITCH(ES) ALLOWED
Explanation:

The command syntax does not allow switches.

User Action:

Retype command line after checking proper syntax.

NO SUCH COMMAND
Explanation:

QMGCLI installed and run under wrong name.

User Action:

See your system manager.

NO SUCH FILE f1lespec
Explanation:
Print command named
message displays filespec given.

nonexistent

file.

User Action: Retype command line after correcting
Default file type for Print command is .LST.

Error
filespec.

NO SWITCHES ALLOWED
Explanation:

Switches not allowed with this command.

User Action:

Retype command line after checking proper syntax.

PRIVILEGED COMMAND
Explanation: Command reserved for privileged users:
/START, /STOP, /SPOOL, /PUBLIC, /NOSPOOL, /NOPUBLIC,
/MODIFY, /HOLD, /RELEASE, /DELETE on another UIC.
User Action:

See your system manager.

6-22

. 'Ill•

Jiiiiii I

iii!j

i i .I I.(

I ii I I

Id i 5ii I ii

a:: u r4 :

PRINT AND QUEUE UTILITY
QUEUE DIRECTORY FULL
Explanation:

All devices and queue slots full in queue.

User Action:

See your system manager.

QUEUE FULL
Explanation:
queued.

The queue file is saturated;

your

job

cannot

User Action:
Enter the command again later, check the queue with
QUE /LI, and see your system manager.
QUEUE/DEVICE NOT ALLOWED
Explanation:
be named.

Command syntax does not allow a queue or device

User Action:

Retype command after checking proper syntax.

QUEUE/DEVICE NOT SPECIFIED
Explanation:
named.

Command syntax requires a queue

device

User Action:

Retype command after checking proper syntax.

QMG MARKED FOR EXIT
Explanation:

Attempt to spool after /STOP:QMG issued.

User Action:

Wait or see your system manager.

REQUEST FAILURE ON PROCESSOR TASK
Explanation:

Device despool task failed to start.

User Action:

See your system manager.

UIC NOT ALLOWED
Explanation:

The command syntax does not include a UIC.

User Action:

Retype after checking proper syntax.

6-23

;a sue

ti$

CHAPTER 7

THE QUEUE MANAGER

This chapter is directed to the system manager or operator who is
setting up and running the Queue Manager on an RSX-llM system.
(For
RSX-llM-PLUS systems, see the RSX-llM-PLUS Batch and Queue Operations
Manual.)
Except where noted,
all commands in this chapter are
pr!Vfieged.
Most systems include the Queue Manager for
the convenience of
multistream line printer spooling.
If not, the serial despooler,
PRT ••• , can be installed instead.
Note that the Queue Manager
includes QMGPRT, which installs as PRT ••• , to intercept output from
the PIP /SP switch and other utilities and system tasks.
The RSX-llM V3.2 Queue Manager consists of three components:
1.

A command line interpreter (CLI) which processes both print
requests and queue access commands as described in Chapter 6
of this manual.
CLI communicates with the Queue Manager by
sending data packets to it describing the print job.

The Queue Manager (QMG), which controls the queueing and
dequeueing of print jobs. QMG communicates with CLI and the
despooler tasks to process print jobs.

The despool prototype task
(LPP).
This task attaches a
device and despools print jobs to it.
A task must be
installed for each device to be used as a despool device with
the task name ddPn, where dd is the generic device name and n
is the unit number. A despool device is a device under the
control of QMG.

"Spool" is an acronym of Shared Peripheral Operations On-Line.
"Spooling" on RSX-llM is gathering output sent to the line printer on
a mass storage device - usually a disk - to be passed in an orderly
fashion to the line printer.
"Despooling" is the orderly transfer
from the mass storage device to the line printer.
CLI takes a Print command and interprets the print request it
specifies.
The information is sent to QMG which creates a print job
consisting of the names of the files to be ·printed and the attributes
of the job.
The print job entry is placed in a print queue kept in
the disk file SYO:[l,7]QUEUE.SYS.
Queues are assigned to despool
devices which are controlled by despool tasks. When a despool device
is idle the Queue Manager selects the next job in the queue(s)
assigned to its device and processes it.
Finally the queue entry is
deleited.

7-1

THE QUEUE MANAGER

This chapter consists of a narrative introduction and review of the
process of setting up the Queue Manager, detailed descriptions of all
commands to the Queue Manager, and a listing of an indirect command
file to be included in the system STARTUP procedure as a reference
example.

7.1

NARRATIVE INTRODUCTION AND REVIEW

Here is the procedure for bringing the Queue Manager into the system.
This can be done interactively, but in most cases it is more
convenient to include it in an indirect command file invoked as part
of the system's STARTUP procedures.
Note that this procedure must be adapted for each installation.
The
example is based on the procedure used for the RSX-llM development
system. QUE setup commands allow considerable flexibility in setting
up the Queue Manager system. Dynamic alteration of the Queue Manager
is also permitted.
1.

Install the Queue Manager.
utility tasks.

It is found with

the

privileged

>INS DBO:QMG /PRI=70
2.

Install the output despooler task.
>INS DSO:LPP /PRI=70
This task installs automatically as LPPO. You must install
this task for each physical device under the direction of the
Queue Manager. This task "owns" the output device and must
have a name based on the name of the device. Thus, the
output despooler for LPl: must be installed under the name
LPPl, using the /TASK= option. There can be up to 15 output
devices controlled by the Queue Manager.

Install PRT •••
>ms QMGPRT
This task installs automatically as PRT...
and is the
interface to PIP and other tasks that use PRINT$ or .PRINT.
The Queue Manager can then accept jobs from the PIP /SP
switch.
(Although this task has the same name as the Serial
Despooler used on previous versions of RSX-llM (and available
on RSX-llM V3.2), it is not the same task. It replaces this
task.)

Install the Print Command
Command Line Interpreter.

Line

Interpreter

and

the

Queue

>INS QMGCLI /TASK= ••• PRI
>INS QMGCLI /TASK= ••• QUE
The same task parses both the PRI and QUE commands
therefore must be installed twice, once under each name.

and

7-2

!!ill!I

211

f4¢

THE QUEUE MANAGER

Start the Queue Manager.
>QUE /START:QMG

\...-1

This command starts the Queue Manager and initializes the
default queue PRINT. It creates the queue file QUEUE.SYS on
SY:[l,7] if it 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 are not
assigned to processors.
(Processors will have to be spooled
ag.ain.)
6.

Spool the processor.
>OUE LP: /SPOOL /FLAG:l /FORM:O
This command creates a queue LPQO and starts the previously
installed despool task LPPO. This task attaches device LPO:
for de~pooling. Queue LPQO is assigned to processor LPPO.
Repeat this step for each output device under control of the
Queue Manager.
The /FORM switch establishes this attribute of the despooler.
This means the despooler accepts jobs initiated by Print
commands with the same FORM attribute given. Jobs with other
FORM attributes remain in the queue until a despooler with
the proper FORM attribute is available.
The /FLAG switch sets the number of flag pages that precede
each job.
If users specify /FLag in their Print commands,
each file in the job will be preceded by this many file flag
pages as well.

Assign queues to processors.
>QUE LP: /ASSIGN:PRINT
This command assigns the default queue PRINT to processor
LPPO.
Normally, only the PRINT. queue has to be assigned.
Device-specific queues are
assigned
to
their
device
despoolers by /SPOOL.
This assignment of device-specific
queues is a default, however, and not a requirement.
A
device-specific queue must exist for every spooled device,
but these queues can be assigned to other devices.
You can assign a queue to more than one processor and you can
assign more than one queue to a processor. You can assign a
device-specific queue to another device if necessary.
For
example, if printer LPO:
is temporarily unavailable, you
could assign LPQO to LPl:.

7-3

THE QUEUE MANAGER
7.2

REFERENCE EXAMPLE

Here is a listing of SY:[l,2]QMGSTART.CMD from the RSX-llM development
system:

INS DBO:QMG /PRI=70
INS DSO:LPP /PRI=70
INS DSO :QMGPRT
INS DSO:QMGCLI /TASK= ••• PRI
INS DSO:QMGCLI /TASK= ••• QUE
QUE /START:QMG
QUE LP: /SPOOL /FLAG:l /FORM:O
QUE LP: /ASSIGN :PRINT

7.3

QUEUE MANAGER COMMAND DESCRIPTIONS

The configuration of the Queue Manager can be controlled
number of special functions applied to the QUE command.

through

The format of the Queue Manager setup commands is:
>QUE ddnn:

/function[:option[s]] [/sw[s]]

ddnn:
Specifies the name of the device affected by the command.
/function
Specifies the function performed by the command.
:option[s]
Specifies one or more options for a function.
/sw[s]
Specifies one or more switches for a function or option.
These commands allow a privileged user to attach or detach devices for
spooling, start and stop devices, assign the default queue to devices
and start and stop the Queue Manager.

7-4

t 4222

lili! ii a:

THE QUEUE MANAGER
7.3.1

STOP

This function suspends a device or stops the Queue Manager.
Form,at
>QUE ddnn: /STOP[:option]
Options
:EOF
:EOJ
>QUE /STOP:QMG
ddnn:
The device name is required with all options except /STO:QMG.
You cannot include a device when stopping the Queue Manager.
Options
If you do not enter an option
immediately. This is a pause.

(null

option)

the

device

stops

:EOF
The device stops at the end of the current file.
: EOJ
The device stops at the end of the current job.
/STO:QMG
The Queue Manager stops at the end of the current job.
All
assignments of queues to devices are broken (deassigned). All
despooler tasks are detached from their devices.
The Queue
Manager stops.
Exam.pl es
>QUE LPO: /STOP
This example stops printing on LPO:. No jobs will be taken from
queues assigned to the device, but jobs can still be added to
queues.
>~UE

LP2: /STO:EOJ

This example stops printing on LP2:
job.

at the

end

the

active

>QUE /STOP :QMG
This E~xample stops the Queue Manager.
the current job is allowed to finish.

7-5

QMG is marked for stop and

THE QUEUE MANAGER
7.3.2

START

This command starts printing on a previously stopped device or starts
the Queue Manager after a STOP. This command counteracts STOP.
Format
>QUE ddnn: /STArt[:option] [/sw]
Options

Switches

:NExt
:TOP
:PAge:n
:BAck:n
:FOrward:n

/FOrm:n
/FLag:n

>QUE /STArt: QMG
ddnn:
A device name is required with all options except /STA:QMG.
cannot include a device when starting the Queue Manager.

You

Options

Option and switch are mutually exclusive fields.
other.

Use one or

the

If you enter nothing (null option), the device
from the point at which printing stopped.
resumes printing after a pause.

starts printing
This, in effect,

:NExt
Printing starts at the top of the next job.
: TOP
Printing starts at the top of the current file.
:PAge:n
Printing starts at page n of the current file.
:BAck:n
Printing starts n pages back from
stopped.

the

point

which

was

Printing starts n pages forward from the point at
stopped.

which

was

: Forward: n

/STA:QMG
This option is entered without ddnn: as it starts Queue Manager
and initializes the default queue PRINT. It creates the file
SY:[l,7]QUEUE.SYS if it is not there. The command also clears
all assignments previously recorded.
If the queue file was
intact, all queues still contain their jobs, but are not assigned
to processors.
(Processors will have to be spooled again.)

7-6

::;a

;;

; :m:;

THE QUEUE MANAGER
Switc::hes

The switch and option fields are mutually exclusive. Use one
the other. You can enter more than one switch, however.

/FOrm:n
This switch resets the forms type of the despooler task from
type set with the SPOOL function

the

This switch resets the flag setting of the despooler task from
the number of flag pages set with the SPOOL function. Print jobs
have n job flag pages preceding the job~ If users specify /FLA
in their Print command, each file in the job will also be
preceded by n file flag pages in addition to the job flag pages.
n can be O, 1, 2, or 3.
If you are using special forms in your printer, you should
n=O so that no flag pages are printed on your special forms.

set

Examples

>QUE LPO: /STA
This example starts LPO:;
stopped.

printing proceeds from

where

was

>QUE LP2: /START:NE
This example starts printing with the next job queued to LP2:.
>QUE LP: /STA /FO:ll
This example starts printing on LPO:
reset to 11.

with

the

FORMS

attribute

Note·s

Page-related options have no effect unless the user
/LEngth:n quantity in the Print command.

specified

If you are restarting a processor to handle special forms types,
you may want to set /FL to 0 to avoid printing banner pages on
your special forms.

7-7

THE QUEUE MANAGER
7.3.3

SPOOL

This function attaches a device for despooling. The command names and
starts a despool task and a queue named after it, and assigns the
queue to the despool task.
Format
>QUE ddnn: /SPool [/sw]

Switches
/FOrm:n
/FLag:n
/External
ddnn:

/SPOOL
ddnn: /SPOOL creates queue ddQn and starts the despool task ddPn
which must be installed previously for device ddn:.
This
attaches device ddnn: for despooling by the despool task ddPn
open to jobs from queue ddQn.

Switches
More than one switch can be used with this function.
/FOrm:n
Sets the device despooler to accept jobs with forms type n.
You can set a despooler to accept more than one forms
the forms definition must be duplicated.
The number n can be anything from 0 to 255.

type,

but

The default is O.

These numbers are to be specified by your users in their Print
commands.
If the right forms are not in an available printer,
then their jobs will be waiting until the printer has been
stopped, the proper forms put in place, and the printer restarted
using the /FORMS: qualifier and the proper value for n in the
START command.
Forms differ by their length and width.
in the forms table.

Both values can

set

Setting width is simply a matter of 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
of a standard length.

forms

are

"Standard 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 <FF>, then it is a
standard length form, and the form feed is a "real," that is,
hardware, form feed.
If the form length cannot be set on the hardware, then it is a
non-standard length.
In this case, the form feed <FF> must be
replaced by an appropriate number of line feeds <LF>.
This is
called a "simulated," that is, software, form feed.

'~
. I ·r~
.... c

7-8

'!ll!lllJ iii $

ll2l

" !

::au ft4

THE QUEUE MANAGER
You should determine which forms are used on your system and
assign each a number.
This number points to a table of form
definitions. The form definitions consist of a single 16-bit
word.
The length is the low-order byte and the width is the
high-order byte. The high bit of the length byte is set when
simulc1ted forms
(forms whose length cannot be set on your
hardware) are needed. This form definition word can be changed
by editing the Task Builder command file for the despooler task.
You must add a global patch statement of the following form:
TKB>GBLPAT=INIT+FRMTBL+n*2:value
where n is the assigned
definition word.

form

number

and

value

the

form

Table 7-1 shows the forms requirements for a hypothetical
installation.
The form names describe different uses that
special forms might be put to, but have no
significance
otherwise.
Table 7-1
Demonstration Forms Settings

'-'··
Form

Assigned n

Accordion
Paychecks
Invoices
Stationery
Mo<>n Diary
Star Log

0
1
2
3
4
5

Width

Length

132
40
80
80
22
112

66
10
66
66
43
113

Standard?

NOTE
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
remaining FORMS:n entries are set to l
line long by 132 columns with simulated
form feeds.
Thus, if
you
specify
FORMS:43, when the printer encounters a
form feed, it counts the number of lines
on the page and subtracts that number
from 43. The printer then outputs 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.

7-9

y
y
y
y

N
N

THE QUEUE MANAGER
/FLag:n
Sets the number of flag pages to precede all jobs printed on the
device.
Note that if you are using special forms, you may want
to set this attribute to 0 to avoid printing banner ~ages on your
special forms.
This also sets the number of file flag pages to
be printed when users specify the /FLAGS switch in their Printer
commands. The default value of n is O.
/EXternal
Specifies that a device is being set spooled that is not
currently part of the local system configuration. Use this
switch when you wish to despool to an applications task, or a
network, or in some other instance of using the Queue Manager for
down-line loading.
Examples
>QUE LPO: /SPOOL
This example attaches LPO:

for despooling.

>QUE LP3: /SP /F0:2
This example attaches LP3:

7.3.4

for despooling with forms set to 2.

UNSPOOL

This function removes a device from despooling.
The device is no
longer assigned to the queue.
The despooler task exits.
The
associated device-specific queue is deleted.
Format
>QUE ddnn: /UNSPool
ddnn: /UNSPool
ddnn:/ UNSPOOL frees a device used in despooling for general use.
The despool task for the device exits but its entries in queues
assigned to it remain in the queue file.
Example
>QUE LPO: /UNSP
This example removes the device LPO:
despooler LPPO and the Queue Manager.

from

active

use

the

ASSIGN

7.3.5

This function creates a path between a queue and despooler.
Format
>QUE ddnn: /ASsign:queuename
ASSIGN is normally used to assign the default queue PRINT to one or
more despooler tasks, but you can assign any queue to any despooler.
7-10

IL!iiiiii

I:;

THE QUEUE MANAGER
Example
>QUE LPO: /AS:PRINT
This example assigns the PRINT queue to LPO:.

Remember that SPOOL automatically assigns a device-specific queue
to its related device.
For example, LPQl is automatically
assigned to LPl:.

7.3.6

DEASSIGN

This function breaks the assignment of a queue to a despooler.
For11nat
>QUE ddnn: /DEAssign:queuename
DEASSIGN eliminates the path between a queue and a despooler, but the
queue still exists with all its jobs. Jobs can be added to the queue,
but none will be dequeued while the queue is not assigned.

7.4

ERROR MESSAGES

Error messages from the Queue Manager may be preceded by the letters
PRI or QUE, depending on where within the software the error detection
takes place. Here is how they appear on your terminal:

'-''

PRI

NO SUCH COMMAND

QUE

DIRECTORY NOT ALLOWED

The PRI and QUE identifiers are not used in this section.
When you
get an error message such as those above, look for the message portion
(NO SUCH COMMAND or DIRECTORY NOT ALLOWED in the examples above). The
message portion of each error message appears in alphabetical order in
this section, along with a description of the error that produced the
message and a suggested correction.
If you issue a QUE /LI (or /BR or /FU) and only a prompt is
this means no queue file exists on your system.
In most cases, the error will be a
err·or.

typing

mistake

returned,

other

syntax

BAD COMMAND LINE
Explanation:

Invalid MCR line or invalid syntax.

User Action:

Retype command line after checking proper syntax.

BAD SPOOL DEVICE TYPE
Explanation:

Only record-oriented devices can be spooled.

User Action:

Check device type.

7-11

THE QUEUE MANAGER
BAD SWITCH TYPE

Explanation:

Bad ASCII switch value.

User Action:
value.

Retype command.line after

checking

proper

switch

spooled

check

list

spooled

DEVICE ALREADY SPOOLED

Explanation:
command.

Specified device

User Action:
devices.

Issue QUE

already

/LI:ALLDEV

DIRECTIVE FAILURE

Description:

Program error.

User Action:

Detect and correct error.

Executive directive failed.

DIRECTORY NOT ALLOWED

Explanation:

UIC included in command that does not accept it.

User Action:

Retype command line after checking proper syntax.

ILLEGAL ARGUMENT VALUE

Explanation:

Bad switch value.

User Action:
value.

Retype command line after

checking

proper

switch

INVALID JOB SYNTAX

Explanation:
•

Invalid syntax in the command

•

Invalid job name

•

Included both job name and job identification

•

Omitted both job name and job identification

User Action:

Retype command line after checking proper syntax.

I/O ERROR ON SYO:QUEUE.SYS

Explanation:

Error encountered in reading queue file.

User Action:

Check SYO:[l,7] for presence of QUEUE.SYS.

7-12

I ii iii&

22#1&

THE QUEUE MANAGER
JOB DOES NOT EXIST
Explanation:

Specified job not found in queue under current UIC.

User Action: Retype command line, including correct UIC
identl f ication.

job

identification

not

JOB NAME NOT ALLOWED
Explanation: Job name or other form of
accepted in this command.
User Action:

job

Retype command line after checking proper syntax.

MULTIPLE FUNCTIONS DETECTED
Explanation:

More than one function specified.

User Action:

Retype command line after checking proper syntax.

MUTUALLY EXCLUSIVE SWITCH/VALUE
Explanation: Command line specified mutually exclusive
value and switch.
User Action:

function

Retype command line after checking proper syntax.

NO FUNCTION SPECIFIED
Explanation:

Command line did not include required function.

User Action:

Retype command line after checking proper syntax.

NO SUCH COMMAND
Explanation:

QMGCLI installed and run under wrong name.

User J\ction:
or ••.. QUE.

Install and run QMGCLI under proper name:

••• PRI,

NO SWITCHES ALLOWED
Explanation:

No switches allowed with this command.

User Action:

Retype command line after checking proper syntax.

PRIVILEGED COMMAND
Explanation: The following functions are privileged:
/START,
/STOP, /SPOOL, /UNSPOOL, /ASSIGN, /DEASSIGN, /MODIFY, /HOLD,
RELEASE, /DELETE jobs from another UIC.
User Action:

Enter command from a privileged terminal.

7-13

THE QUEUE MANAGER
QUEUE/DEVICE NOT ALLOWED

Explanation:
name.

/STOP:QMG or START:QMG command issued

User Action:

Retype command without device name.

with

device

QUEUE/DEVICE NOT SPECIFIED

Explanation: /START, /STOP,
require device name.
User Action:

/UNSPOOL,

/ASSIGN,

and

/DEASSIGN

Retype command with device name.

QMG DID NOT START

Explanation:

/START:QMG did not work.

User Action:
•

Check to see if QMG is installed under name QMG •••

•

Check to see if pool is low.

7-14

!IHI! tq .ii bill

Li!iii

;;::

L ii

2i!

::sur a tu

:mumm ; e

PART 5
VOLUME MAINTENANCE UTILITIES

1:122aa

! "

21 JI

lll:P

CHAPTER 8
DISK VOLUME FORMATTER (FMT)

The Disk Volume Formatter (FMT) utility formats and verifies DB:, DK:,
DM:, DP:, DR: and DY: disk volumes under any RSX-llM, RSX-llM-PLUS,
or !AS operating system which includes diagnostic support in the
Executive.
(Check with your system manager to determine whether your
system includes this feature.)
The disks can be completely formatted (in normal operating mode) or
formatted on an individual sector (or track for DM: volumes) basis
(in manual operating mode).
Formatting in manual operating mode sometimes allows
use of a bad sector or track.

you

recover

the

disk

In general, FMT performs the following tasks:
•

Writes a complete header for each sector of
formatting.

•

Verifies the address contents of each sector header.

• Sets the density for DY:

floppy diskettes •

Lets you specify a maximum
• volume
being formatted.

pack error limit for the disk
FMT terminates processing when the

error limit is reached.
•

8.1

Allows the Bad Block Locator (BAD) task to be run (spawned) if
your system permits spawned tasks.

INITIATING AND TERMINATING FMT

To initiate FMT, enter the appropriate command following
monitor prompt, as explained in Chapter 1 of this manual.

the

system

The general form of the FMT command line is:
>FMT ddn:/[switch l ••• switch m]
where dd: is the abbreviation for the volume you are formatting, n is
the unit number of the volume, and the possible switches are:
/BAD

Runs the Bad Block Locator task (BAD) if it is
on the system.

installed

Note that this switch can only be used with operating
systems that allow spawning of tasks.
RSX-llM and
RSX-llM-PLUS provide spawned tasks as a System Generation
option.
8-1

DISK VOLUME FORMATTER (FMT)
/DENS

Selects high (double) or low (single)
floppy diskettes.

/ERL

Determines the maximum number of errors FMT will allow on
the volume.

/MAN

Enters manual operating mode and formats
track you specify.

/OVR

Overrides or ignores
Sector File (MDBSF) •

/WLT

Rewrites the MDBSF to add bad sectors
operation.

/VE

Verifies that a FMT operation was successfully completed.

/@Y

Informs FMT that it is executing from an
file.
An FMT command in this form
operator intervention in the process.

the

density

the

Manufacturer's

for

RX02

sector

Defined

Bad

during

FMT

found

command
not allow

indir~ct

does

These switches are described in detail in Section 8.4.

8.2

MODES OF FMT OPERATION

FMT allows you to format volumes in two ways: normal operating mode,
which formats an entire volume, and manual operating mode, which
formats the sector (or track on DM: volumes) you specify in response
to FMT prompts.
FMT uses normal operating mode unless you specify
manual mode with a /MAN in the command line.
FMT normally ~etries an operation twice when it encounters an error.
If the operation still fails, FMT flags the sector as bad and displays
the following message:
ERROR WRITING HEADER
If you specify the verify switch with an FMT operation, and FMT
encounters an error, it prints one of the following messages on your
terminal:
ERROR READING HEADER
or
HEADER COMPARE ERROR
FMT then continues the verification operation.

8.2.1

Normal Operating

Mode

When you invoke FMT in normal operating
switch), it prints the following message:

** WARNING - DATA WILL BE LOST ON ddn:
CONTINUE [Y OR N]

mode

(without

the

Manual

After a Y (yes) response, FMT returns the message:
START FORMATTING

8-2

4l!i

::;::

lh!.

ll ! I ti

I!!!P

DISK VOLUME FORMATTER (FMT)
It then performs the formatting functions you specify with switches in
the FMT command. After an N (no} response or a carriage return <CR>,
FMT returns control to the system monitor.
Normal FMT operation varies slightly according to the volume
formatting (see Section 8.3}.

8.2.2

you

are

Manual Operating Mode

If ycrn specify manual operating mode (/MAN}, FMT prints:

** WARNING - DATA WILL BE LOST ON ddn:
CONTINUE [Y OR N]

After a Y (yes} response, FMT returns the message:
ENTERING MANUAL MODE
It then displays the following prompts:
CYLINDER=
TRACK
=
SECTOR
After you enter your response to the prompts, FMT formats the sector
or track you specify. FMT assumes the responses are in decimal unless
they are preceded by a number sign (#}. If you enter a parameter that
is out of range of the volume FMT returns an error message and exits.
Table 8-1 lists the valid ranges for FMT manual mode operations.
FMT manual operating mode works the same on all disk volumes, with one
exception:
On DM:
volumes (RK06 and RK07} FMT formats a specific
track of the volume.
For example:
FMT>DMO:/MAN
This command causes FMT to prompt:

** WARNING - DATA WI LL BE LOST ON OMO:
CONTINUE [Y OR N] Y

ENTERING MANUAL MODE
CYLINDER=
TRACK
FMT then formats the entire track you specified.

8-3

DISK VOLUME FORMATTER (FMT)
Table 8-1
Valid Ranges for Manual FMT Operations
Disk Volumel

Sectors

Tracks

Cylinders

RP02/RPR02

0-9

0-19

0-199

RP03

0-9

0-19

0-399

RP04

0-21

0-18

0-410

RPOS

0-21

0-18

0-410

RP06

0-21

0-18

0-814

RKOS/RKOSF

0-11

0-1

0-199

RK06

0-21

0-2

0-410

RK07

0-21

0-2

0-814

RM02

0-31

0-4

0-822

RM03

0-31

0-4

0-822

1 Note that FMT manual operating mode cannot be used with RX02 floppy
diskettes.

8.3

FMT-SUPPORTED DEVICES

The following sections describe normal FMT operating mode. Table
lists the devices that allow formatting and their abbreviations.

8-2

Table 8-2
FMT-Supported Devices
Device

Abbreviation

RP04 disk pack
RPOS disk pack
RP06 disk pack

DB:
DB:
DB:

RKOS disk cartridge
RKOSF fixed media disk

DK:
DK:

RK06 disk cartridge
RK07 disk cartridge

DM:
OM:

RPR02 disk pack
RP02 disk pack
RP03 disk pack

DP:
DP:
DP:

RM02 disk pack
RM03 disk pack

DR:
DR:

RX02 floppy diskette

DY:

8-4

rn111z

I 4I diiii

124$

$&
.

sq a;

DISK VOLUME FORMATTER (FMT)
The status FMT requires for the devices varies with the operating
system. Table 8-3 lists the status required for devices with RSX-llM,
RSX-llM-Plus, or IAS.
Table 8-3
FMT Device Status

8.3.1

Operating System

Device Status Required
for FMT Operation

RSX-llM-PLUS

Mounted with Foreign
Characteristics

RSX-llM V3.2

Unmounted

!AS

Mounted with Foreign
Characteristics

DB: Devices (RP04/RP05/RP06 Disk Packs)

When FMT formats a DB: volume, it tries to write 22 headers at a time
until it has formatted the entire volume.
If FMT encounters an error,
it attempts to write each header
individually and designates which
headers are bad.
If you specify the Verify switch (/VE), F~T verifies 11 headers at a
time until
it has verified the entire volume.
If FMT encounters an
error, it attempts to verify the headers individually to determine
where the error occurred.
It then reports any bad headers and
continues the operation.

8.3.2

DK: Devices (RKOS Disk Cartridge or RKOSF Fixed Media Disks)

When FMT formats a DK:
volume,
it tries to write each header
individually until
it has formatted the entire volume.
If FMT
encounters an error, it retries each header twice before reporting the
header as bad.

'-'i

If you specify the verify switch (/VE), FMT verifies the headers 12 at
a time, until it has verified the entire volume.
If FMT encounters an
error, it attempts to verify the headers individually to determine
where the error occurred.
It then reports any bad headers and
continues the operation.

8.3.3

DM: Devices (RK06/RK07 Disk Cartridges)

FMT writes DM: headers one track (22 sectors) at a time and sets the
header flags of those sectors marked bad in the MDBSF.
If FMT
encounters errors, it retries the operation twice before it designates
which headers are bad.
If you specify the verify switch (/VE), FMT verifies that each sector
from 0 to 21 is addressable.
It does this by issuing a full 256-word
write, made up of the 2-word address pattern (the sector number and
its complement)
into each sector.
Once the entire track has been
written, each sector is read and the full
256 words of data are

8-5

DISK VOLUME FORMATTER (FMT)
compared with the expected data pattern. If an error occurs during
this operation, FMT reports that sector as bad and continues the
operation.
When FMT writes headers on OM: devices, it sets bad sector flags in
the headers already marked as bad in the MDBSF. If you also specify
the verify switch, FMT indicates whether the bad sector was flagged in
the MDBSF.

8.3.4

DP: Devices (RPR02/RP02/RP03 Disk Packs)

When FMT formats a DP: volume, it tries to write 10 headers at a time
until it has formatted the entire volume. If FMT encounters an error,
it attempts to write each header individually and designates which
headers are bad.
If you specify the Verify switch (/VE), FMT verifies the headers 10 at
a time, until it has verified the entire volume. If FMT encounters an
error, it attempts to verify the headers individually to determine
where the error occurred.
FMT reports that sector as bad and
continues the operation.

8.3.5

DR1 Devices (RM02/RM03 Disk Packs)

When FMT formats a DR: volume, it tries to write 32 headers at a time
until it has formatted the entire volume. If FMT encounters an error,
it attempts to write each header individually and designates which
headers are bad.
If you specify the Verify switch (/VE), FMT verifies the headers 16 at
a time, until it has verified the entire volume. If FMT encounters an
error, it attempts to verify the headers individually to determine
where the error occurred.
It then reports any bad sectors and
continues the operation.
When FMT writes headers on DR: volumes, it sets bad sector flags in
headers already designated as bad by the MDBSF. If the command also
specifies the Verify switch, FMT indicates whether the sector was
marked in the MDBSF.

8.3.6

DY: Devices (RX02 Floppy Diskettes)

You can use FMT to set an RX02 floppy diskette to either high (double)
or low (single) density. If you specify the Verify switch, FMT writes
and reads block O and the last block on the diskette to determine that
the density is correct.
Note that manual operating mode cannot be used with DY:

8.4

devices.

FMT SWITCHES

The following sections describe the switches you can use with FMT
commands.
The descriptions include information on restrictions for
formatting specific devices and default values for the switches, where
appropriate.

8-6

. i2 r I

DISK VOLUME FORMATTER (FMT)

8.4.1

/BAD

The Bad switch spawns the Bad Block Locator task
(BAD}
after FMT
completes an operation.
If BAD is not installed on the system, FMT
prints a warning message on your terminal and exits.
The format for an FMT command, using the BAD switch, is:
FMT>dev:/BAD

8.4.2

/DENS

The Density switch sets DY:
floppy diskettes to either high or low
density.
The default is low density.
(This switch can also use
single and double density as options.)
The formats for an FMT command, using the DENS switch, is:
FMT>DYn:/DENS=HIGH (or DOUBLE)
FMT>DYn:/DENS=LOW (or SINGLE}

8.4.3

/ERL

The Error Limit Switch sets an error limit for the volume you are
formatting~
If the error count reaches this limit, FMT generates an
appropriate message and terminates operation. The default error limit
is 256 err.ors. Any value greater than O or less than or equal to 256
is valid.
The format for an FMT command, using the ERL switch, is:
FMT>d1av: /ERL=n

8.4 .. 4

/MAN

The Manual switch puts FMT in manual operating mode and permits you to
format an individual sector (or track for DM: disk cartridges}.
FMT
assumes cylinder, track, and sector numbers are decimal values unless
they are preceded with a number sign (#}.
In manual operating mode, FMT displays the following prompts:

** WARNING - DATA WILL BE LOST ON DK!:

CONTINUE [YORN]?
ENTERING MANUAL MODE
CYLINDER=
TRACK
SECTOR
OPERATION COMPLETE
The format for an FMT command, using the MAN switch, is:
FMT>dev:/MAN

8-7

DISK VOLUME FORMATTER (FMT)
8.4.5

/OVR

The override switch causes FMT to ignore the Manufacturer's Detected
Bad Sector File (MDBSF) on DM:
and DR: disk volumes. When FMT
writes headers on these disks, it normally sets bad sector flags in
those headers marked bad in the MDBSF. When the verification process
discovers a bad sector, it reports that the sector was marked in the
MDBSF. The Override switch inhibits this operation.
The format for an FMT command, using the OVR switch, is:
FMT>dev:/OVR

8.4.6

/VE

The Verify switch confirms that an FMT operation was successful.
It
does this by reading back the headers and determining that they were
written correctly.
The format for an FMT command, using the VE switch, is:
FMT>dev:/VE

8.4.7

/WLT

The Write Last Track switch, when used with the verify switch on DM:
and DR: volumes, rewrites the MDBSF after an FMT operation to add the
bad sectors that FMT found to the bad sectors already in the MDBSF.
FMT also rewrites each bad sector's header to flag it as a bad sector.
The WLT switch requires a decimal number (n below) which
the volume's pack serial number.

used

The format for an FMT command, using the WLT switch, is:
FMT>dev:/WLT:n

8.4.8

/@Y

If you specify the @Y switch, FMT executes from an indirect command
file.
In this method of operation, FMT will not generate any
operational messages or warnings to your terminal until the operation
is complete and no operator intervention is possible.
The format for an FMT command, using the @Y switch, is:
FMT>dev:/@Y

8.5

FMT MESSAGES

This section describes the messages FMT generates, along with possible
user action in response to the messages.

8-8

••••q11:•••:1•11:•11.11•:•a•••••••••••••••••••••••:•s•••••••••••••s•s•.•:•:•~;111•11111r•

.,11!1•

DISK VOLUME FORMATTER (FMT)
COMMJ.\1ND I/O ERROR
Explanation:
keyboard.

A hardware transmission

User Action:

Reenter the command.

error

occurred

from

the

COMMAND TOO LONG
Explanation:

The command was longer than 80 (10) characters.

User Action:

Enter a shorter command.

DEVICE DOES NOT SUPPORT FORMATTING
Explanation:
of FMT.

A device was specified that does not allow the

User Action:

Determine the correct device and, if FMT
is legal, reenter the command.

use

operation

DEVICE DRIVER MISSING
Explanation:

The disk device driver is not loaded.

User Action: Load the driver (if it is loadable) and reenter the
command, or use a different device in the command line.
DEVICE NOT IN SYSTEM
Explanation: The specified device was not identified as part of
the system during system generation, or the device does not exist
on the system configuration.

User Action: Determine the correct command line with the correct
device abbreviation, and reenter the command.
DEVICE NOT READY
Explanation: The disk volume was not at operating speed when FMT
attempted to access it.

user Action:

Allow the volume
reenter the FMT command.

reach

operating

speed

and

DEVICE OFFI.INE
Explanation:

The device is not in the hardware configuration.

user Action: Determine the correct command line with the correct
device abbreviation and reenter the command.
DEVICE WRITE LOCKED
Explanation:
prohibited.

The volume is write-locked;

User Action:

Write-enable the unit and reenter the FMT command.

8-9

any

write

access

DISK VOLUME FORMATTER (FMT)
DISK IS AN ALIGNMENT CARTRIDGE
Explanation: The device is a factory-created disk used to align
the heads in a disk drive and should not be used for other
purposes.
user Action: Use a disk that is not an alignment
reenter the FMT command.

cartridge

and

ERROR LIMIT EXCEEDED
Explanation: The number of errors FMT found on the disk pack
exceeded either the number of errors specified with the ERL
switch, or the default 256 error limit that FMT sets.
user Action:
used.

Set a higher error limit, if

the

ERL

FMT encountered an error in

reading

switch

was

ERROR READING DATA
Explanation:
disk.

user Action: None required;
continues the verification.

data

from

FMT retries the operation twice and

ERROR READING HEADER
Explanation: FMT encountered an error when it tried
header during a verification operation.
User Action: None required;
continues the verification.

read

FMT retries the operation twice and

ERROR SETTING DISKETTE DENSITY
Explanation: FMT tried to format a DY:
operation failed.
user Action:
the density.

floppy diskette and

the

Check the syntax and reenter the command, resetting

ERROR WRITING DATA
Explanation: FMT encountered an error when it attempted to write
sector headers.
user Action: None required;
continues the verification.

FMT retries the operation twice and

ERROR WRITING HEADER
Explanation:
header.

FMT encountered an error when it tried to

User Action:

None required;

write

FMT retries the operation twice.

8-10

ii I

DISK VOLUME FORMATTER (FMT)
FAILED TO ATTACH DEVICE
Explanation:

FMT could not attach the device to be formatted.

User Action: Determine whether another task has attached the
device.
If so, wait until the task exits, or abort the task and
run FMT again.
FAILED TO READ MANUFACTURER'S BAD SECTOR FILE
Explanation: A disk hardware error occurred while FMT attempted
to read the MDBSF on the last track on the last track of a
device.
User Action:

Reenter the command, including the Override switch.

FATAL HARDWARE ERROR
Explanation: A fatal error
hardware configuration.
User Action:

occurred

somewhere

the

system

Contact the DIGITAL Field Service representative.

HEADER COMPARE ERROR
Explanation: FMT found an error in comparing
expected value during a verification error.
User Action:

None required;

headers

with

the

FMT retries the operation twice.

INVALID SWITCH
Explanation: An illegal switch or a switch not
specified device was used in an FMT command.

for

the

User Action: Reenter command with the override switch (/OVR)
prevent FMT from trying to use the corrupt bad block data.

User Action:

valid

Check the syntax and reenter the command.

MANUFACTUHER'S BAD SECTOR FILE CORRUPT
Explanation: The factory-written bad block data (MDBSF)
last track of the disk is in an unusable format.

MAHKED BAD IN MANUFACTURER'S BAD SECTOR FILE
Explanation: Indicates that bad block information is recorded in
the MDBSF on the disk.
User Action:
only.

None required.

This

8-11

message

for

information

DISK VOLUME FORMATTER (FMT)
PRIVILEGE VIOLATION
Explanation: FMT attempted an operation on
mounted or allocated to another user.

device

that

was

user Action:
Reenter the FMT command, using a device that is not
allocated to another user.
RESPONSE OUT OF RANGE
Explanation: Parameters entered for manual formatting of an
individual sector or track were out of the range of the volume.
User Action:
the command.

Check Table 8-1 for legal

parameters

and

reenter

SYNTAX ERROR
Explanation:

FMT detected a syntax error in the command line.

User Action:
the command.

Determine the correct command

syntax

and

reenter

UNABLE TO RUN BADBLOCK UTILITY
Explanation: A FMT command specified the Bad switch (/BAD), but
BAD could not be spawned. Either the operating system does not
spawn tasks or BAD was not installed.
user Action:

Run the BAD utility separately.

I !'

UNRECOVERABLE ERROR - n
Explanation:

An I/O error (number n) caused FMT to terminate.

User Action:
Reenter the FMT command and if the error
again, try the command, specifying a different device.

occurs

8-12

'111111!

iii

)ii i2I

::::::

; IP

CHAPTER 9
BAD BLOCK LOCATOR UTILITY (BAD)

9.1

INTRODUCTION TO BAD

The Bad Block Locator Utility (BAD) tests disks and DECtapes for the
location and number of bad blocks. BAD then records this bad-block
information on the device. When you use the MCR Initialize Volume
command (IN!) the bad blocks are marked as in-use;.· that is, !NI
allocates the bad blocks to the file [O~O]BADBLK.SYS. Thus, the bad
blocks cannot be allocated to other files. BAD supports any last
track device, as well as vendor-supplied cartridges that do not have a
prerecorded manufacturer's bad-sector file on the last track. You can
use BAD in its task version, which runs at the same time as other
tasks, or in its stand-alone version, which runs -by itself on the
computer. The stand-alone version is preferable if you have a system
with a single disk drive.

9.2

INVOKING BAD

You can invoke the BAD utility as follows:
>BAD dev: [/sw] •••
dev:
Specifies a physical device. The specification consists of two
alphanumeric characters followed by a 2- or 3-digit octal unit
number and colon.
/SW

Specif:ies an optional switch that qualifies the BAD command line.
Multiple BAD switches for a device must be specified on one line.
If you do not specify any switch, BAD begins its pattern checking
of individual blocks.

9.2.l

BAD Switches

Table 9-1 c:ontains a reference list of BAD switches along with a brief
description of each. For a detailed description of BAD switches see
Section 9.S.

9-1

BAD BLOCK LOCATOR UTILITY (BAD)
Table 9-1
BAD Switches
Switch

Function
BAD switches for Task and Stand-Alone Versions

/LI

Lists bad blocks as they are located

/MAN

Prompts you for additional bad blocks

/OVR

Creates bad block
last-track device

/RETRY

Recovers soft errors

/UPDATE

Reads the bad block
prompts for input

descriptor

file

descriptor

file

and

BAD Switches for Stand-Alone Version Only
/CSR=nnnnnn

Alters the CSR address of the device

/VEC=nnn

Alters interrupt vector address of the device

/WCHK

Causes a write check

/NOCHK

Negates /WCHK

9.2.2

BAD And Indirect Files

BAD can access an indirect file that contain a series of
strings in the following manner:

BAD

command

>BAD @BADCMDS.CMD
In this example, BAD is invoked and accesses the file BADCMDS.CMD,
which contains a sequence of BAD command strings. BAD executes the
commands and returns control to MCR. The BAD utility allows nested
command files; one command file can invoke another to a maximum depth
of three.
BAD can also be invoked by an indirect file. Such an indirect file
can contain command strings for more than one utility and is accessed
by entering only the file specification preceded by the at sign:
>@INDIRECT. CMD
The default values for indirect file specifications are:
dev
uic
file name
file type
version

SYO:

The current UIC
No default
.CMD
The latest version of the file

For complete information on how to use indirect files,
RSX-llM/M-PLUS MCR Operations Manual.

refer

the

9-2

I( .I

!. I iiiji

Ji u

, ,

BAD BLOCK LOCATOR UTILITY (BAD)
9.3

PROCESSING BAD BLOCK DATA

This section contains information on how BAD tests the reliability of
disks and DECtapes, formats bad block descriptor entries, and how the
INI command uses bad block information.

9.3.1

Verifying Devices

BAD verifies disks and DECtapes by writing a test pattern onto each of
the blocks on the device, reading the pattern back into· a buffer in
storage, and comparing the blocks in the buffer with those on the
device.
When BAD processes a disk or DECtape, all existing data is
destroyed.
BAD writes the test pattern to several blocks in a single write
operation.
If an error occurs in writing, reading, or comparing any
of these blocks, BAD tests each of the blocks individually. The test
pattern, 165555 and 133333(octal),
is replicated 128(decimal) per
block. If BAD finds no bad blocks during individual testing,
the
error-logging subsystem may still log errors due to long data
transfers.

9.3.l.l BAD and Non-Last Track Devices - As BAD locates bad blocks,
it stores their addresses in a memory buffer. After locating all bad
blocks on a device, BAD records the addresses of the bad blocks on the
last good block of the device. Consecutive bad blocks are recorded as
single entries. There must be at least one good block in the last 256
(decimal) blocks of the volume for BAD to create this file, called the
bad block descriptor file.

'-"

9.3.JL.2 BAD and
Last-Track
Devices - BAD
records
bad
block
information differently on last-track devices, such as the RK06/07,
RLOl/02, and the RM02/03. The last track is divided into two areas,
the Manufacturer's Detected Bad Sector File (MDBSF) and the Software
Detected Bad Sector File (SDBSF).
The MDBSF is created wh~n the
hardware servo/header writer formats the pack. This operation also
sets bits in any header that is marked bad in the MDBSF, and sets the
SDBSI~
to be empty. When you run BAD, entries are made in the SDBSF.
The information contained in the two last-track files is combined to
form [O,O]BADBLK.SYS when you issue the INI Cofllmand.

9.3.2

Format of Bad Block Descriptor Entries

For non-last track devices,
BAD uses the last good block as a
descriptor file for bad blocks. The address of a bad block, or the
first address in a sequence of consecutive bad blocks, is stored as a
double-word entry in the bad block descriptor file. The first word of
this double-word contains two entries:
the high-order byte contains
the number of bad blocks minus 1 and the low order byte contains bits
16 through 23 of the logical block number of a bad block or a range of
bad blocks.
The second word of the double-word contains bits 0
through 15 of that block number.

9-3

BAD BLOCK LOCATOR UTILITY (BAD)
For last-track devices, bad block descriptor entries are also recorded
as a double-word in the SDBSF. Word 1 of the double word contains the
address of the cylinder on which the bad block exists. The high-order
and low-order bytes of word 2 contain, respectively, the track and
sector addresses of the bad block.

9.3.3

The INI Command and BAD

The
Use BAD with the MCR IN! Command to produce a Files-11 volume.
IN! command uses the bad block information to create the file [0,0]
BADBLK.SYS. The BADBLK.SYS file has allocated to it those blocks
found to be bad, thus ensuring that file system does not allocate a
known bad block to a file.
For information on how to use the !NI, refer to the RSX-llM/M-PLUS MCR
Operations Manual.

9.4

USING THE BAD UTILITY

Before BAD can validate a device, that device must be formatted by the
manufacturer, by the FMT utility, or by one of the diagnostic programs
supplied in your distribution kit. These programs are described in
the
RSX-11
Utilities Manual and the RSX-llM/M-PLUS user Mode
Diagnostics Reference Manual, respectively.
In the RSX-llM system, the volume must not be mounted. Issue the
dismount command if the device contains a mounted volume.

MCR

In an RSX-llM~PLUS system, the volume must be mounted as foreign.
The following example illustrates a typical sequence of steps
introducing the disk DKl: to an RSX-llM or RSX-llM-PLUS system.
System

Command

M/M+
M+
M/M+
M/M+
M/M+
M+
M/M+

ALL DKl: <CR>
MOU DKl:/FOR<CR>
FMT DKl:[/sw]<CR>
BAD DKl:[/sw]<CR>
INI DKl: [label] [/sw] <CR>
DMOU DK 1: <CR>
MOU DKl:[label] [/sw]<CR>

for

You may execute BAD while other RSX-11 tasks are executing.

9.4.l

Programming Considerations

This section contains information you should know before you
BAD u t i 1i t y •

use

the

9.4.1.l Use of Block Zero - On bootable disks, block zero contains
the bootstrap block.
If block zero is bad, BAD prints a message
warning the operator not to use the disk for a bootable system image.

9-4

JtiJ

iii!

u usa:

BAD BLOCK LOCATOR UTILITY (BAD)
9.4.1.2 Device Controller Errors - The error-logging subsystem may
record errors even though BAD is not reporting bad blocks. These
errors may be encountered during long data transfers and may originate
with the device controller.

9.4.1.3 Maximum Entries in the BAD Block Descriptor - on non-last
track devices BAD storage allows 102.(decimal) entries of bad block
addresses. On last-track devices BAD allows 126.
entries.
On
non-last track devices, a single BAD entry can address one bad block
or several consecutive bad blocks. If more than the maximum number of
entries is recorded, BAD terminates with an error message.

9.5

9.5.l.
1
"-'

BAD SWITCH DESCRIPTIONS

Switches for both Task and Stand-Alone System Versions Of BAD

/LI
Causes all bad blocks to be printed by number in decimal on your
terminal.
This switch causes bad blocks to be listed as BAD
performs a data pattern check on each block.
Blocks entered
manually which BAD tests as reliable are not listed. This switch
is valid for all devices.
/MAN

Causes BAD to first prompt you for bad block information and to
then perform data pattern checking. Any block that you enter is
included in the bad block descriptor file.
/OVR
Causes BAD to ignore last track information and write a bad block
descriptor file on the last good block before the last track. In
other words, the override switch causes BAD to treat a last-track
device as a non-last track device. If your device has no bad
block file on the last track, or if you suspect the reliability
of the last track, use the override switch before using the MCR
!NI command. The override switch is valid only for last-track
devices.
NOTE
If you use this switch, the /BAD=[OVR]
option for
initializing a volume must
also be used to construct the bad block
file
[O,O]BADBLK.SYS.
See
the
RSX-llM/M-PLUS MCR Operations Manual for
description of the MCR INI command.

9-5

BAD BLOCK LOCATOR UTILITY (BAD)

/RETRY
Causes BAD to attempt a recovery of hardware errors via the
device driver. This also means that soft errors, such as an ECC
correctable error, will be recovered and the block will be marked
as good.
/UPDATE
causes BAD to immediately read the bad block descriptor file and
prompt you for additional bad block input. This switch does not
cause BAD to write pattern checks.
NOTE
Updating the bad block descriptor file
on file structured volumes does not
cause the file [O,O]BADBLK.SYS to be
updated.

9.5.2

The Manual and Update Switches

If you wish to enter bad blocks in manual or
prompt you as follows:

update

mode,

BAD

will

BAD>LBN(S)=
You may then enter bad blocks in the format:
blocknum:number
Where number specifies the number of sequential bad blocks beginning
at the specified block number blocknum. The colon is required when
you specify a sequence of bad blocks in this form. Both blocknum and
number default to decimal values, unless preceded by a number sign (#)
to indicate an octal value. For example:
BAD LBN ( S) = 7 0 • 3
enters the block numbers 70,71, and 72 in
file.

the

bad

block

You can also specify a single bad block.

For example:

descriptor

BAD> LBN ( S) = 3
enters block 3 in the bad block file.
You can use both of
example:

these

BAD>LBN(S)= 100:2,3,

forms

200:100

the

same

command

line.

For

45:1

enters blocks 100, 101, 3, 200 through 299, and 45 in the bad block
file.
You can separate bad block sequences with a space, tab, or
comma.

9-6

'iiQJiiii!iiiii

Ull 2ii

I. I J )

::::m

BAD BLOCK LOCATOR UTILITY (BAD)

When you enter a carriage return in response to the prompt, BAD will
list all the sequences in the bad block descriptor file. For example:
BAD>LBN(S)=
000100:002
000003:001
000200:100
000045:001

BAD>LBN(S)=
The first number in the display represents the beginning block of
sequence; the second number represents the number of bad blocks.
block numbers are listed in decimal.

the
Bad

When a bad block sequence is entered, BAD determines if these bad
blocks are adjacent to an already existing sequence. If you are using
a non-last track device, BAD appends your bad block entry to the
existing sequence. If you are using a last track device, BAD records
individual bad blocks in core memory but lists entries at your
terminal as part of existing bad block sequences.
When you have finished supplying information in manual or update mode,
enter ESCAPE, ALTMODE, or <CTRL/Z> in response to the prompt. The bad
block will then either be rewritten with the new bad block information
if in update mode or pattern checking will start if in manual mode.
Blocks entered manually which BAD tests as reliable are included in
the bad block descriptor file.

Swi t:ches for Stand-Alone Syste10 Version Only

9. 5. 3

/C SR=nnnnnn
nnnnnn is a new CSR address
This switch alters the CSR address of the device so that it
conforms to that of the device in te user's system. /CSR remains
in effect and need not be repeated if more commands are issued.
/VEC=nnn
nnn is a new interrupt vector address
This switch alters the interrupt vector address so that it
conforms to the vector address of the device in the user's
system. /VEC remains in effect if more commands are issued.
/WCHK
This s;witch causes a write check operation to occur after each
write operation. The switch is not available for devices DT, DX,
or DY.
/NOCHK
This i:iwitch negates
default.

/WCHK.

This

9-7

switch

returns

you

the

BAD BLOCK LOCATOR UTILITY (BAD)
Unlike PRESRV and DSC, BAD expects to see all
command line.
For example:

switches

single

BAD>DM3:/0VR/LI/VEC=300/CSR=l74406
locates all bad blocks on DM3, ignores the last track data, lists all
bad blocks, changes the interrupt vector to 300, and changes the CSRss
to 174406. All switches are validated for prop syntax before the
actual bad block detection takes place.

9.6

DEVICES SUPPORTED BY THE STAND-ALONE VERSION

The following devices are supported by the stand-alone version of BAD.
If you have a task version of BAD, your executive will support any
device suitable to your system's configuration.
Mnemonic Type

CSR

Vector

RH11-RP04/05/06 and RH70-RP04/05/06 176700
Disk Pack

254

TU58 DECtape II

175600

300

RFll/RSll Fixed-Head Disk

177460

204

RK11-RK03/05/05F Cartridge Disk

177404

220

RL11/RL01/RL02 Cartridge Disk Pack

174400

160

RK611-RK06/07 Cartridge Disk Pack

177440

210

RPll-C/E RPR02/RP02/03 Disk Pack

176714

3201

RH70/RM03 and RH11/RM02 Disk Pack

176700

340 1

RH11-RS03/04 and RH70-RS03/04

172040

3101

TC11/TU56 DECtape

177342

214

RXll/RXOl Floppy Disk

177170

264

RX211/RX02 Floppy Disk

177170

3501

1 Nonstandard Vector Address

9.7

BAD MESSAGES

This section lists the BAD messages, gives a brief description of the
condition that causes each message, and suggests a response to the
condition.
BAD error messages are arranged alphabetically beginning
with the text following after the device symbol, [ddu:].
BAD -- ddu: BAD BLOCK FILE NOT FOUND
Explanation:
update mode.

The bad block descriptor file could not be read

User Action: You must use the device without updating the
block file, or reformat the device and destroy all data.

bad

9-8

BAD BLOCK LOCATOR UTILITY (BAD)
BAD .-- ddu: BAD BLOCK FILE OVERFLOW
Explanation: BAD detected more than 102 sets of bad blocks. For
last-track devices, the maximum number of bad blocks that can be
recorded is 126. This message usually indicates a device unit
failure.
user Action: Either the volume is bad or the drive requires
maintainance; contact your DIGITAL Field Service Representative.
BAD ·-- ddu: BAD BLOCK FOUND - LBN= nnnnnn.
Explanation: Bad blocks are reported in this format,
is the Logical Block Number (decimal).

where

LBN

User Action: None. This message is informational and applies to
the /LI switch only.
BAD -- ddu: BLOCK 0 BAD - DO NOT USE AS SYSTEM DISK
Explanation: This is a warning message.
a bootstrap block cannot be written
useless as a system disk.

When block zero is bad,
on the disk, making it

User Action: Label the disk to ensure that no
use it as a system disk.

one

attempts

BAD -- COMMAND I/O ERROR
Explanation:
keyboard.

There was a hardware transmission

user Action:

Retype the

error

from

the

command~

BAD -- COMMAND TOO LONG
Explanation:

The command was longer than 80.

User Action:

Retype the

characters.

command~

BAD -- ddu: CSR ADDRESS NOT IN SYSTEM
Explanation: Self-explanatory. This message occurs only in
stand-alone system version of BAD.

the

User Action: Retype the command including the /CSR
the proper value.

with

switch

BAD -- ddu: DEVICE OFFLINE
Explanation:
In the stand-alone version of BAD, the specified
devicE~
is not in the hardware configuration, or the Control
Status Register switch (/CSR) is improperly set.
User Action: Retype the command, setting the /CSR
addresses for the device to the proper addresses.

9-9

and

/VEC

BAD BLOCK LOCATOR UTILITY (BAD)
BAD -- DUPLICATE BLOCK NUMBER -

[numb]

Explanation: The block number sequence you entered is already
present in the bad block file. The value [numb] is the sequence
you entered.
This

User Action: Reenter the command line with another value.
message applies to the /MAN or /UP switch only.
BAD -- ddu: FAILED TO ATTACH
Explanation:
tested.

BAD could not

gain

control

the

unit

User Action: Determine if another task has attached the unit.
If so, wait until the task exists, or abort the task to gain
control of the unit for BAD.
BAD -- ddu: FAILED TO READ MANUFACTURER'S BAD SECTOR FILE
Explanation: A disk-read hardware error occured while attempting
to read the factory-written bad block data on the last-track
device cartridge.
User Action:

Reenter the command with the /OVR switch included.

BAD -- ddu: FAILED TO READ SOFTWARE BAD SECTOR FILE
Explanation: The software-detected bad sector file could not
read in update mode.
User Action:

Reenter the command with the /OVR switch included.

BAD -- ddu: FAILED TO WRITE BAD BLOCK FILE
Explanation: BAD could not write the bad block
condition usually results from a disk write error.

file.

This

User Action: Reenter the command.
disk pack should be discarded.

persists

the

If the problem

BAD -- ddu: FATAL HARDWARE ERROR
Explanation:

Self-explanatory.

User Action:

Contact your DIGITAL Field Service Representative.

BAD -- ddu: HANDLER/DRIVER MISSING
Explanation:

The disk driver is not loaded.

User Action:

Load the disk driver and reenter the command.

9-10

••

!i2$Jllli

;::

#!LI

f Z?U

BAD BLOCK L.OCATOR UTILITY (BAD)

BAD -- ddu: ILLEGAL DEVICE
Explanation:
The device to which bad block
directed does not support a Files-11 structure.
User Action:

processing

You must re-format your device before running BAD.

BAD -- INVALID BLOCK NUMBER -

[numb]

Explanation: You entered an invalid block number sequence.
value [numb] is the sequence.

The

User Action: Type another value and reenter the command
This message applies to the /MAN or /UP switch only.

line.

BAD -- INVALID SWITCH
Explanation:

Self-explanatory

User Action:

Reenter the command with a proper switch.

BAD -- ddu: IS AN ALIGNMENT CARTRIDGE
Explanation: The factory written label on the last track of
last-track device cartridge indicates an alignment cartridge.
User Action:

'-';

Mount and process another cartridge.

BAD -- ddu: NOT IN SYSTEM
Explanation: The requested device was not made part of the
system during system generation, or the device does not exist on
the host configuration.
User Action:

Ensure that you entered the command line correctly.

BAD -- ddu: NOT READY
Explanation: The unit had not reached operating speed
attempted to access it.

when

BAD

User Action: Allow the unit to reach operating speed and reenter
the command line.
BAD -- ddu: MANUFACTURER'S BAD SECTOR FILE CORRUPT
Explanation: The factory-written bad block data in the
track of a last-track device is in an inconsistent format.
user Action:

last

Reenter the command with the /OVR switch included.

BAD -- ddu: PRIVILEGE VIOLATION
Explanation: An operation was attempted for a
mounted or allocated to another user.
User Action:

device

that

was

Mount another device and reenter the command line.

9-11

BAD BLOCK LOCATOR UTILITY (BAD)
BAD -- SYNTAX ERROR

Explanation:

BAD detected a syntax error on the command line.

User Action:
command line.

Determine

the

correct

syntax

and

reenter

the

BAD -- ddu: TOTAL BAD BLOCKS= [n].

Explanation: This is an information message indicating the total
number (in decimal) of bad blocks on the disk.
User Action:

Write the bad blocks count on the disk label.

BAD -- ddu: UNRECOVERABLE ERROR [n]

Explanation: An I/O error caused BAD to terminate.
The
[n] is number of the I/O error returned by the driver.

value

User Action: If the same error
Digital field representative.

persists,

contact

your

local

User Action: Retype the command including the /VEC
the proper value.

switch

with

BAD -- ddu: VECTOR NOT MULTIPLE OF FOUR

Explanation:

Self-explanatory.

BAD -- ddu: WRITE LOCKED

Explanation:

The unit is write-locked.

User Action:

Write-enable the unit and reenter the command line.

9-12

!!Ell SJ!

ii IS ii

I e:;e

CHAPTER 10
BACKUP AND RESTORE UTILITY (BRO)

'-')

The RSX-11 Backup and Restore Utility (BRU)
provides functions
that
allow you to back up and restore Files-11 volumes.
BRU transfers
files from a volume to a backup volume or volumes to ensure that a
copy of the files
is available
in case the original files are
destroyed.
If the original files are destroyed, or if for any other
reason the copy needs to be retrieved, you can restore the back-up
fileis with the BRU command.
Backup and restore operations take place on disk and tape volumes:

• Disk to tape for backup operations
• Tape to disk for restore operations
• Disk to disk for either backup or restore operations
In addition to these basic data transfer functions,
Restore Utility provides command qualifiers to:

10.l

Backup

and

•

Perform backup and restore operations by
date, and time

•

Control disk processing, which provides disk
initialization
features that allow you to enter the locations of bad blocks
on a disk and initialize the disk before a backup or
restore
operation

•

Control tape processing such as
labeling, rewind, and append

•

Verify accurate data transfers

•

Display information such as backup set names and file names

density,

file

the

specification,

length,

ANSI

tape

OVERVIEW OF COMMAND QUALIFIERS AND DEFAULTS

Table 10-1 summarizes the command qualifiers available for backup
restore operations.

10-1

and

BACKUP AllD RESTORE UTILITY (BRU)
Table 10-1
Summary of BRU Command Qualifiers
Command Qualifiers

Default

Options

/APPEND

None

/BACKUP_SET:name

None

/BAD:

[ MANUAL
[ AUTOMATIC
[ OVERRIDE

]
]
]

BAD:AUTOMATIC

Number of
buffers from
the input
disk

/BUFFERS:number

/COMPARE
/CREATED:

[BEFORE:dd-mmm-yy hh:mm:ss]
[AFTER:dd-mmm-yy hh:mm:ss ]

Current date

/DENSITY:number

DENSITY:SOO.

/DIRECTORY

None

/DISPLAY

None

/ERRORS:number

ERRORS:25.

/EXCLUDE

None

/EXTEND:number

Number of
blocks from
the input
disk

/HEADERS:number

Number of
headers from
the input
disk

/INITIALIZE

None

/INVOLUME:name

None

/LENGTH:number

The length of
the output
tape

/MAXIMUM: number

Maximum
number of
files from
the input
disk

/MOUNTED

None
(continued on next page)

10-2

;:;

BACKUP ARD RESTORE UTILITY (BRO)
Table 10-1 (Cont.)
Summary of BRU Command Qualifiers
Command Qualifiers

Options

Default

/NEW_VERSION

None

/NOINITIALIZE

None

/NOPRESEFtVE

None

/NOSUPERSEDE

None

/OUTVOLUME:name

Input disk
volume name

/POSITION:

/PROTECT ION:

[ BEG INN ING ]
[ MIDDLE
]
[ END
]
[block:number ]
(protection value)

Index file
position on
the input
disk
Protection of
the input
disk

SYSTEM:value
OWNER: value
GROUP:value
WORLD: value
/11lEVISED::

[BEFORE:dd-mmm-yy hh:mm:ss]
[AFTER:dd-mmm-yy hh:mm:ss ]

Current date

/HEWIND

None

/SUPERSEDE

/NOSUPERSEDE

/'I'APE_LABEL: label

None

/VERIFY

None

/WINDOWS:value

Number of
mapping
pointers on
input disk

10.Jl.l

Command Qualifiers For Selective Backup And Restore

The command qualifiers described in Table 10-2 allow you to backup or
restore data, using one of the following criteria for file selection:
•

File specification

•

Date and time of creation

•

Date and time of revision

10-3

BACKUP AllD RESTORE UTILITY (BRO)

Table 10-2
Command Qualifiers That Perform Selective Backup and Restore Operations
Qualifier

Options

Explanation

/CREATED

BEFORE:(dd-mmm-yy[hh:mm:ss]) Directs BRU to
AFTER:(dd-mmm-yy[hh:mm:ss]) process files created
before or after a
specified date and/or
time.

/EXCLUDE

Selectively excludes
from a backup or
restore operation all
files specified on
the command line.

/NEWVERSION

Directs BRU to
resolve conflicts
resulting from files
with identical file
specifications by
creating a new
version of the file.
Both versions of the
file are kept on the
output volume.

/NOSUPERSEDE

When files on the
output volume have
file specifications
identical with files
on the input volume,
resolves the conflict
by keeping the file
on the output volume
rather than that on
the input volume.

/REVISED

BEFORE:(dd:mmm:yy[hh:mm:ss]) Directs BRU to
AFTER:(dd:mmm:yy[hh:mm:ss]) process files revised
before or after a
specified date and/or
time.
In restore
operations, restores
files to an existing
disk; resolves file
specification
conflicts by deleting
the old file on the
output disk and
replacing it with the
file being restored
from the input disk.

/SUPERSEDE

10-4

: au a ;u

!IL!

;a;•

BACKUP ARD RESTORE UTILITY (BRU)
The :following qualifiers resolve file specification conflicts when,
during a
restore to an existing disk, a file specification on the
output volume is identical to one for a file being transferred from
the input volume:
•

/NEWVERSION

/SUPERSEDE

•

/NOSUPERSEDE

10.1.2

Command Qualifiers for Controlling Disk Processing

The command qualifiers described in Table 10-3 allow you to control
the way the operating system manages disk data transfer operations.
Table 10-3
Command Qualifiers that Control Disk Processing
Qualifier

Options

Explanation
Directs BRU to initialize
a disk before proceeding
with the data transfer.

/UHTIALIZE

/INVOLUME

name

Specifies the volume label
of the input disk.

/NOINITIALIZE

Specifies that you do not
want
to initialize the
output disk;
it already
has a Files-11 structure
and
is
mounted
as
Files-11.

/MOUNTED

Allows you to back
up
files from a disk that is
mounted as
a
Files-11
volume
(via the MCR MOUNT
command).

/NOP RESERVE

Specifies that you do not
want BRU to preserve file
identifiers.

/OUTVOLUME

10.1.3

name

Specifies the volume label
of the output disk.

Command Qualifiers for Controlling Tape Processing

The qualifiers in Table 10-4 allow you to control backup
tape processing.

10-5

and

restore

BACKUP AllD RESTORE UTILITY (BRO)
Table 10-4
Command Qualifiers That Control Tape Processing
Qualifier

Options

Explanation
Appends new backup data to a tape
with one or more backup sets.

/APPEND
/BACKUP_SET

name

Specifies the name of the backup
set to be placed on tape. Refer
.to Section 10.s.1.

/DENSITY

number

Specifies the data density
which BACKUP writes to tape.

/ERRORS

number

Specifies the number of nonfatal
I/O errors BRU tolerates on tape
reads
before
automatically
terminating execution.

/LENGTH

number

Specifies the length of the output
tape in decimal feet.

/REWIND

/TAPE_ LABEL

10.1.4

Rewinds the first tape of a tape
set before execution of a command
line.
label

Specifies a 6-character ANSI
label.

tape

Command Qualifiers for Verifying the Accuracy of Data Transferred

The command qualifiers in Table 10-5 allow you to detect differences
between data on the input volume and data on the output volume.
Table 10-5
Command Qualifiers That Verify the Accuracy of Data Transfers
Qualifier

Explanation

/COMPARE

Compares the data on the output volume to the data
on the input volume and reports any differences.

/VERIFY

Copies data from the input volume to the output
volume, performs a compare operation, and reports
differences.

10.1.5

Command Qualifiers for Displaying Information About Files Transferred

The command qualifiers listed in Table 10-6 display information
the data being transferred.

about

10-6

':!lllllU ii $J1

iii# iii! Uh I

J$1iiilil!

4422 $

BACKUP AllD RESTORE UTILITY (BRO)
Table 10-6
Command Qualifiers That Provide Information
Qualifier

Explanation

/DISPLAY

Displays at your terminal the UFO
and filename of each file being
backed up.

/DIRECTORY

(such
as
Display
information
backup set names, file names, or
volume number of a tape)
on a
specified tape volume.

10.1.6

Command Qualifiers for Initializing Disks

When you are initializing a disk using the BRU /INITIALIZE qualifier,
you may want to specify various characteristics for the output disk.
The qualifiers in Table 10-7 allow you to set the characteristics.

DISK AND TAPE DEVICE INFORMATION

10.2

You can use the Fast Backup and Restore Utility only on Files-11
volumes. The following sections give a brief overview of the Files-11
format and also present some general disk device information.
For more detailed information on Files-11, refer to the IAS/RSX-11 I/O
Operations Reference Manual.

10.2.l

Files-11 Structures

BRU requires that an input disk be a Files-11 volume. Also, when you
initialize a volume. for Files-11, five control files are created.
These five files are catalogued in the Master File Directory
([O,O]
also called the MFD) :

'-'i

•

The Index File -- identifies the volume to the operating
system as a Files-11 structure contains control data for
accessing all files on the volume. The index file
is listed
in the Master File Directory as INDEXF.SYS.

•

The Storage Bit Map File -- controls the available space on
the volume. This file is listed in the MFD as BITMAP.SYS. It
contains a storage control file, which consists of summary
information for optimizing the allocation of storage.
It also
contains the bit map itself, which lists available blocks of
st<> rage.

The Bad Block File -- is listed in the MFD as BADBLK.SYS.
It
contains all of the bad blocks on the volume. Bad block
processing is discussed in more detail in Section 10.4.2.

•

The Master File Directory
(MFD) -- listed in the MFD as
000000.DIR.
The MFD is the root of the volume directory
structure. It lists both the reserved files that control the
volume structure and user file directories.

10-7

BACKUP ARD RESTORE UTILITY (BRO)
e

The Core Image File -- listed in the MFD as CORIMG.SYS.
file contains the system checkpoint file.

This

The following sections give you background information you need to
efficiently use the BRU command qualifiers for controlling operating
system disk processing operations.
Table 10-7
Initialization Qualifiers
Qualifier

Options

Explanation

/BAD

MANUAL
AUTOMATIC
OVERRIDE

Enters the locations of
bad blocks on volumes.

/BUFFERS

number

Specifies the number of
directory File Control
Blocks
(FCBs)
per
volume kept in memory
by the ACP.

/EXTEND

number

Specifies the number of
blocks to extend a file
when that
file
has
exhausted its allocated
space.

/HEADERS

number

Specifies the number of
file
headars
to
allocate initially to
the index file.

/MAXIMUM

number

Specifies the maximum
number of files that
can be placed on
a
volume.

/POSITION

BEGINNING
MIDDLE
END
BLOCK:number

Specifies the location
of the
index
file,
Master File Directory,
and
the
storage
allocation file on a
disk.

/PROTECT ION

protection value
SYSTEM:value
OWNER:value
GROUP:value
WORLD:value

Specifies the global
protection status of
the disk.

/WINDOWS

number

Specifies the number of
retrieval
pointers
allocated for use with
file windows.

10-8

'i'RI

2!ii 4

:au;: a:

scaa

a a

;;

; 21512

BACKUP Al1D RESTORE UTILITY (BRO)
Table 10-6
Command Qualifiers That Provide Information
Qualifier

Explanation

/DISPLAY

Displays at your terminal the UFD
and filename of each file being
backed up.

/DIRECTORY

(such
as
Display
information
backup set names, file names, or
volume number of a tape)
on a
specified tape volume.

10.1.6

Command Qualifiers for Initia:Uzing Disks

DISK AND TAPE DEVICE INFORMATION

10.2

10.2.1

Files-11 Structures

•

The Storage Bit Map File -- controls the available space on
the volume. This file is listed in the MFD as BITMAP.SYS.
It
contains a storage control file, which consists of summary
information for optimizing the allocation of storage.
It also
contains the bit map itself, which lists available blocks of
storage •

•

The Bad Block File -- is listed in the MFD as BADBLK.SYS.
It
contains all of the bad blocks on the volume. Bad block
processing is discussed in more detail in Section 10.4.2.

•

10-7

BACKUP ARD RESTORE UTILITY (BRU)
•

The Core Image File -- listed in the MFD as CORIMG.SYS.
file contains the system checkpoint file.

This

Options

Explanation

/BAD

MANUAL
AUTOMATIC
OVERRIDE

Enters the locations of
bad blocks on volumes.

/BUFFERS

number

Specifies the number of
directory File Control
Blocks
(FCBs)
per
volume kept in memory
by the ACP.

/EXTEND

number

Specifies the number of
blocks to extend a file
when that
file
has
exhausted its allocated
space.

/HEADERS

number

Specifies the number of
file
headers
to
allocate initially to
the index file.

/MAXIMUM

number

Specifies the maximum
number of files that
can be placed on
a
volume.

/POSITION

BEGINNING
MIDDLE
END
BLOCK:number

Specifies the location
of the
index
file,
Master File Directory,
and
the
storage
allocation file on a
disk.

/PROTECT ION

protection value
SYSTEM:value
OWNER: value
GROUP:value
WORLD: value

Specifies the global
protection status of
the disk.

/WINDOWS

number

Specifies the number of
retrieval
pointers
allocated for use with
file windows.

10-8

i
1

•t•""""'F.-z••··----------------4••··-····i•l

' '!111'••••::•••:•.••&•li!ili

I•.•I

••::•.JJ•ii!•l

•t••l•/1114-SI

BACKUP AllD RESTORE UTILITY (BRU)
10.2.1.l The Index
infc•rmation:
•

File - The

index

file

contains

the

following

Bootstrap Block -- is virtual block number l of the index
file.
If the volume is a PDP-11 system device, this block
contains a bootstrap program that loads the operating system
into memory.
If the volume is not a system device, this block contains a
program that displays a message indicating that the volume
does not have a hardware-bootable system.

•

Home Block -- establishes the specific identity of the volume,
providing such information as the volume name and protection,
maximum number of files allowed on the volume, and volume
ownership information. The home block is virtual block number
2 of the index file.

•

Index File Bit Map -- controls the allocation of file headers
and thus the number of files on the volume. The bit map
contains a bit for each file header allowed on the volume.
Tht~ index file bit map starts at virtual block number 3 of the
index file and continues for the number of blocks necessary to
contain the bit map.

•

File Headers -- comprise the largest part of the index file.
Each file on the volume has a file header, which describes
such attributes as file ownership, creation date and time, and
file protection. The file header contains all the information
necessary for accessing the file.

10.2.2

Disk Volume Labels and Backup Set Names

If you omit the backup set name in a backup operation, BRU uses the
volume label of the input disk as the backup set name of the output
tapE~ •

10.~~.3

Devices Supported for Backup and Restore

Table 10-8 lists all the devices that BRU supports.
Table 10-8
Devices Supported By BRU
Mnemonic

Type

Class

TU58 cassette (DECtape II)

Block-structured

RK6ll/RK06/RK07 cartridge disk

Block-structured

RH11/RP04/RPOS/RP06 and

RH70/RP04/RPOS/RP06 disk
pack

Block-structured

RK 11/RKO 5/RKO SF cartridge
pack

Block-structured
(continued on next page)

10-9

BACKUP AllD RESTORE UTILITY (BRO)
Table 10-8 (Cont.)
Devices Supported By BRU
Mnemonic

Type

Class

RFll/RSll fixed head disk

Block-structured

RLll/RLOl cartridge disk

Block-structured

RP11/RP02/RP03 disk pack

Block-structured

RH70/RM03

Block-structured

RH11/RM02 disk pack
DS

RH11/RS03/RS04 and RH70/RS03

Block-structured

RS04 fixed head disk
DT

TC11/TU56 DECtape

Block-structured

RXll/RXOl Floppy Disk

Block-structured

RX211/RX02 Floppy Disk

Block-structured

RH11/TM02-03/TE16/TU16/TU45/TU77
and RH70/TM02-03/TE16/TU16/TU45
and TU77 9-track magnetic tape

Tape

TMll/TUlO/TElO 7- or 9-track
magnetic tape and TS03 9-track
magnetic tape

Tape

TS04 magnetic tape

Tape

10.3

BACKUP AllD RESTORE COMMAND LIRE DESCRIPTIONS

This section describes the rules for entering command lines for the
Backup and Restore utility. The section includes the definition of
the command line syntax and descriptions of command line parameters,
command qualifiers, and prompts.

10.3.l

Command Line Syntax Definition

The general syntax of the BRU command line is:
BRU /qualifiers indevicel:, ••• [filespec, ••• ] outdevicel:, ••• [filespec, ••• ]

10.3.2

Descriptions of Prompts

Prompts
FROM:
TO:

~
r

INITIALIZE [Y/N]:

~--···

10-10

BACKUP ARD RESTORE UTILITY (BRO)

FROM
Requests that you enter the name(s) of the devices on which the
input volume(s) reside in the form specified in the description
below of the command parameters.
TO
Requests that you enter the name(s) of the output devices in the
form
specified
in
the description below of the command
parameters.
INI'rIALI ZE [ Y/N]
Issued as a precaution to ensure that you want to erase the
output volume.
Enter Y (for YES) if you want to initialize the
volume.

10.3.3

Description of Command Line Parameters

qualifiers
Specifies any of the command qualifiers specified above. If more
than one qualifier is specified, they must be contiguous; that
is, you may not separate the qualifiers with blanks or any other
delimiters. The qualifiers may appear in any order.
You may abbreviate a qualifier
abbreviation. For example:

long

you

use

unique

BRU>/REW/INI/OUT:BACKUP MMO: DKO:
BRU - STARTING TAPE 1 ON MMO:
BRU -- *WARNING*
BOOTABLE SYSTEM

THIS DISK

WILL

NOT

CONTAIN

HARDWARE

BRU - END OF TAPE 1 ON MMO:
BRU - COMPLETED
When a qualifier has options, you must separate the qualifier from the
option by a colon in the form:
/qualifier: option
indi:?vice
Specifies the physical device or devices from which data is
transferred.
For tapes, you may specify more than one input
device. Devices are specified in the form:
DD[uu] ~
where DD represents the device mnemonic and uu represents the
octal unit number associated with that device. The unit number
may be specified as one or two digits; the default unit number
is o. For example, a TU77 tape drive can be referenced as MMOO:,
your
MMO : , MM: , MMO 1 : , MMl:, and so forth, depending on
configuration. The colon is a required delimiter.
When more than one device is specified, the device mnemonics must
be separated by commas.

10-11

BACKUP AllD RESTORE UTILITY (BRO)

fil~spec

Indicates the file specification used to select particular files
or categories of files to be backed up or restored. The filespec
takes the form:
[n,m]filename.filetype;version
You may specify up to 16 filespecs per command line.
Files can be backed up or restored selectively by UFO, filename,
filetype, or version number.
When backing up or restoring
selectively by version number, you must specify either an
explicit version number or no version number at all or a wildcard
(*), which has the same effect as no version number.
BRU does
not support O or -1 as version numbers.
outdevice
Specifies the output device to which data is being transferred.
For tapes, you may specify more than one output device. The
rules are the same as for the "indevice" above.

10.3.3.1 Entering Command Lines with Ro Pile Specifications - When
you enter a command line with no file specification, all the files on
the input volume are copied to the output volume.

10.3.3.2 Wildcards in Input Specifications - The
features are provided for file specifications:

following

wildcard

[*,*] means all group,member combinations.
[nl,*] means all member numbers under group nl.
[*,n2] means all group numbers for member n2.

"""

. . Ir

BRU supports the wildcard (*) in all the elements of a file
BRU
specification:
file name, file type, and version number.
generally follows the RSX-llM rules for use of wildcards, except in
the following two instances:
•

When you omit a file specification element, BRU treats the
omitted element as if it were a wildcard. That is, when you
specify only file name and file type in a file specification,
all version numbers are transferred in the backup or restore
operation.

•

When you specify particular UFOs on a command line, all the
files in those UFOs are transferred in the backup or restore
operation.

10.3.3.3 Continuation Lines - BRU allows you to continue a command
line onto more than one line by using a hyphen (-) as the continuation
character.
On RSX-llM Version 3.2 systems, BRU supports continuation lines only
when invoked as BRU>. BRU does not support continuation lines when
run from an indirect command file or when the command line is entered
on the same line as the one on which BRU is invoked.

10-12

1$11 22122;

;:;

BACKUP ARD RESTORE UTILITY (BRO)

On RSX-llM-PLUS systems BRU
ci rc::umstances.

supports

continuation

lines

under

all

The following examples show continued BRU command lines on RSX-llM and
RSX·-llM-PLUS.

RSX-UM
>RUN BRU
BRU> /REWIND...
BRU>/INVOLUME:BACKUPBRU>/BACKUP SET:25MAY79BRU>/TAPE LABEL:BRU123
FROM:
DKO:
TO:
MMO~
BRU - STARTING TAPE 1 ON MMO:
BRU - END OF TAPE 1 ON MMO:
BRU - COMPLETED
BRU>".z

RSX-UM-PLUS
>BRU /REWINDMCR> /INVOLUME:BACKUPMCR> /BACKUP SET:25MAY79MCR> /TAPE_LABEL:BRU123 DKO:

MMO:

>
10.:3.4

Description of Command Qualifiers

/APPEND
Directs BRU to append a backup set from the input volume
last backup set on the output tape.

the

The output tape may not be a continuation tape in a backup set;
it cannot contain a backup set that is continued on another
volume.
/APPEND causes BRU to skip to the logical end-of-tape before it
writes the new backup set, if the tape was positioned at the
beginning. BRU searches the output volume for the last logical
end-of-fileQ
If the tape is a continuation tape, i.e., not the
first tape of a tape set, BRU displays an error message.
If the last backup set does not end on the tape, BRU displays
error message.

If the tape is not positioned at the beginning, /APPEND will
cause
BRU
to start writing where the tape is currently
positioned. /APPEND/REWIND will cause BRU to rewind the tape and
then space forward until the end of the volume.
/BACKUP_SET:name
Specifies the name of the backup set (refer to Section 10.5.2) to
be placed on tape. Default is the volume name of the disk being
backed up. This name may be up to 12 characters long.

10-13

BACKUP ARD RESTORE UTILITY (BRU)

When applied to an output tape volume, the backup set name
assigns the name of the backup set being placed on the volume.
BRU supports multiple backup sets on a single volume.
If you specify no backup set name for the output volume, BRU uses
the volume name of the input disk to name the backup set.
When applied to an input tape volume, BRU searches the first tape
for the specified backup set name. If you specify no backup set
name with the input volume, BRU restores the first backup set it
finds on the tape.
BRU does not rewind the first tape in a
specify /REWIND.
/BAD:[

[
[

backup

set

unless

you

AUTOMATIC
OVERRIDE
MANUAL

The /BAD qualifier is used with the /INITIALIZE qualifier
tape to disk or disk to disk operations.

during

For complete information on how to use the /BAD qualifiers, refer
to Section 10.4.2, "Using the Bad Block Utility with Backup and
Restore." The following are summary descriptions only.
For last-track devices, AUTOMATIC causes BRU to
use
the
manufacturer-written
bad
block
information
and
the
software-detected bad sector file to create BADBLK.SYS.
For
nonlast-track devices, it uses the software bad block descriptor
block to create BADBLK.SYS.
OVERRIDE applies only to last-track devices,
causing
the
last-track device to appear to be a nonlast-track device. When
OVERRIDE is specified, BRU uses the software bad block descriptor
block to create BADBLK.SYS.
MANUAL specifies that BRU use both the manufacturer-written bad
block information and either the software-detected bad sector
file (for last-track devices) or the bad block descriptor block
(for nonlast-track devices) to create BADBLK.SYS. Also, MANUAL
accepts the addresses of bad blocks entered manually from the
terminal.
/BUFFERS:fcbcount
It specifies the default number of directory File Control Blocks
{FCBs) per volume kept in memory by the ACP when the volume is
mounted. The more FCBs that are kept in memory, the faster that
files contained in heavily used directories are found. The
default value for fcbcount is the same as the default for the
input disk.
The /BUFFERS qualifier is used with the /INITIALIZE
during tape-to-disk or disk-to-disk operations.

qualifier

/COMPARE
Compares the data on the output device with the data on the input
device and reports any differences. No data transfer takes place
during a COMPARE operation. The command string specifying the
COMPARE operation must be identical to that entered when the data
on the output disk or tape was created, with the exception of the
/INITIALIZE and /NOINITIALIZE qualifiers.

10-14

'''~•1111

UL 114

iii!

BACKUP AND RESTORE UTILITY (BRO)
/COMPARE Output: When /COMPARE detects differences, it displays
a warning message at your terminal.
/COMPARE always displays the
device mnemonic on which the difference was detected and the type
of record in which the difference is encountered (a control
record, a header record, or a data record).

If the file is a header file, /COMPARE displays the file-ID for
the file.
If the file
is a data file, /COMPARE displays the
file-ID, the retrieval pointer for the file, and the name of the
file if it is available.
/CREATED:[BEFORE:(dd-mmm-yy [hh:mm:ss])]
[AFTER:(dd-mmm-yy
[hh:mm:ss])]
Backs up or restores files created on
specified date and/or time.

before

after

the

If you specify both a date and a time, the date and time must be
enclosed in parentheses.
If you specify only a date or only a
time, the parentheses are not necessary.
If you specify only a
time, BRU uses today's date as the default.
/DEN:SITY:number
Specifies the density at which BRU writes to tape.
table shows legal values you can specify.

The following

Drive

Default Density

Optional Density

TUlO
TU16
TU45
TU77
TS04

800
800
800
800
1600

None
1600
1600
1600
None

If you specify /DENSITY with /APPEND, you must specify the
density at which the old tape data was written.
For example, if
the tape was first written at a density of 800, you must specify
a density of 800.
If you specify a density other than the
original density, BRU displays a warning message and continues
processing at the correct density.
If you enter an incorrect density for a restore operation,
displays an error message and terminates the operation.

BRU

/DIFtECTORY
Lists backup set names or files on the specified tape volume.
Using /DIRECTORY to Display Backup Set Names:
When specified
with no backup set name, /DIRECTORY lists all the backup sets on
the v<>lume:

BRU /DIRECTORY MMO:
VOLl
VOLl

BACKUP! LABEL!
BACKUP2 LABEL!

12-MAY-79
13-MAY-79

If a continuation tape is mounted when you enter the /DIR
qualifier,
BRU lists the backup sets on that volume, not the
backup sets on the first or previous volumes.
Also, /DIRECTORY
displays continuation tape number.

10-15

BACKUP ARD RESTORE UTILITY (BRU)
Using /DIRECTORY to Display Files:

backup
form:

set,

enter

the

backup

To display the files in a
set name with /DIRECTORY in the

>RUN BRU
BRU>/BACKUP SET:23MAY79A/DIRECTORY MM!:
VOLl.
23MAY79A
CDADOC 23-MAY-79 23:37:11
[000,000]
[303,013]
27DECE.LST;l
2JANA. LST; 1
18JANC.LST;l
4JANA.LST; 2
ASTCRSH.MAC;l
9DECA.LST;2
X.MAC;l
X.OBJ;l
X.TSK; 1
APNDXC. TXT; l
X.MAP;l
[001,054]
RSXllM.STB; 45
[002,054]
RSXllM.STB; 36
[003,054]
27DECE. CDA; l
2JANA. CDA; 1
18JANC.CDA;l
4JANA. CDA; l
5JANZ .CDA; l
19JANB.CDA;l
4JANB.CDA;l
6JAN79 .CDA; l
9DECA. CDA; 1
llJANA. CDA; 1
15JANB.CDA;2
15JANC.CDA;2
llJAND.CDA; 1
llJANA. CDA; 2
15JANA.CDA;l
16JANA. CDA; 1
12JANE.CDA;l
RSXllM.STB; 3
[005,054]
[306,006]
APNDXB.MAC;l
BRU - COMPLETED ON MMl:
BRU>~Z

>BYE

HAVE A GOOD MORNING
If the backup set is not on the tape,
displays a message at your terminal.

BRU

halts

execution

and

/DISPLAY
Prints at your terminal the file name and UFO of each file as the
header for that file is being transferred by BRU.

10-16

4 2!

ICi$i a

BACKUP AltD RESTORE UTILITY (BRO)
/ERROHS:number
lRequests termination of a restore operation after the specified
number of nonfatal tape read errors.
The default number of
errors before termination is 25.
/EXCL!UDE
:Selectively excludes from a backup or restore operation the files
specified on the command line.
/EXTEND: number
Specifies the default number of blocks by which a file can be
extended when that file has exhausted its allocated space. This
value is used by an ACP when the volume is mounted.
The /EXTEND qualifier is used with the /INITIALIZE
during tape to disk or disk to disk operations.

qualifier

/HEADERS:number
Specifies the number of file headers to allocate initially to the
index file. The primary reason for preallocating file headers is
to locate them near the storage bit map file.
(The storage bit
map flle is generally located in the middle of the disk.) Proper
placemE~nt of file headers can help reduce head motion during
I/O
operati.ons.
The /HEADERS qualifier is used with the /INITIALIZE
during tape to disk or disk to disk operations.

qualifier

/INI'I IAL I ZE
1

'-''

Specifies that you want to initialize the output volume during a
tape to disk or disk to disk operation. Initialization places a
Files-11 structure on the disk, including the boot block (in some
cases),
the
home
block,
and such files as INDEXF.SYS,
BADBLKS.SYS, and 000000.DIR.
Along with the INITIALIZE qualifier, you. can specify
the
following qualifiers when you are initializing a disk: BAD,
BUFFERS, EXTEND, MAXIMUM, POSITION, PROTECTION, HEADERS, and
WINDOWS.
If you do not specify any of these qualifiers, BRU
defaults to the characteristics of the input disk.
/NOINITIALIZE specifies that you do not want a Files-11 disk
structure placed on the disk
(one already exists). If you
specify neither /INITIALIZE nor /NOINITIALIZE, BRU prompts at
your terminal to ask whether you want to initialize the disk
being processed.
When restoring a volume containing a disk boot block and a system
that you want to be bootable, ensure that the volume to which you
are restoring is the same as or greater than the size of the
original volume.
Also, the disk controller for the device on
which the output device resides must be compatible with the
device controller on which the original volume was created.
/INVOLUME:name
Specifies the volume label of the input disk or tape.
can b~ up to 12 characters long.

10-17

This

name

BACKUP ARD RESTORE UTILITY (BRO)

For backup or disk-to-disk operations, /INVOLUME directs BRU to
look for the volume label of the input volume in order to verify
that the disk has the correct label. This check ensures that you
do not back up the wrong volume.
For restore operations, /INVOLUME directs BRU to look on the
input tape for the volume label in order to locate the correct
backup set. If BRU cannot locate the label, it displays a
message and terminates the operation.
/LENGTH:number
Specifies the length of the output tape in decimal feet. If the
length specified exceeds the length of the tape, the entire
length of the output tape will be used. In cases where you know
the end of a tape must not be used, you can specify a shorter
length to ensure that you do not write on that part of the tape.
/MAXIMUM:number
Specifies the ~aximum number of files that can be placed on a
volume as determined by the number of file headers on the
volume's index file. The default maximum is the maximum number
of files on the input disk.
The /MAXIMUM qualifier and the
/HEADERS qualifier are particularly useful
when
you
are
initializing an output disk which is different in size from the
input disk.
Refer to section 10.4.5
for
more
detailed
information about using the initialization qualifiers when you
are transferring data between disks of different sizes.
/MOUNTED
Backs up or restores files on volumes that
Files-11 volumes (via the MCR MOUNT command).

are

mounted

BRU does not use Fl lACP (F iles-11) to access files on an input
disk;
rather, it uses logical I/O (QIO functions such as
IO.RLB). BRU first backs up groups of headers, then backs up the
files to which those headers point.
When backing up files from a mounted volume, disk activity
(changes to or deletions of files) at while BRU is running causes
the following results:
•

If the file is being changed while BRU is backing up the
disk, BRU copies only the data that comprises the file at
the time of the transfer; any changes made to the file
after the transfer will not appear on the volume to which
you are backing up.

•

If the file is deleted while BRU is backing up the
the data that comprises the file may be corrupted.

disk,

If the file-ID from the deleted file is reused in a UFO
that BRU has not yet backed up, BRU will back up the new
file (with the previously allocated file-ID) when that file
is encountered.
When restored, this new file (with the
duplicate file-ID) will appear as a synonym for the old
file with the same file-ID.

10-18

!ii

ii;:

ii iii I !j4JUIE

BACKUP ARD RESTORE UTILITY (BRO)

•

I:f the disk is changed (files are deleted or changed) after
BRU generates the directory, the directory on the first
tape of the tape set will not be accurate.
Because BRU
generates the directory for the backup set as its first
processing step, changes to the disk after the directory is
generated will not be reflected in the directory.

In order to back-up and restore files on mounted volumes, BRU
must be built as a privileged task. For operations on unmounted
volumes, BRU need not be a privileged task.
BRU will back up from both mounted and unmounted volumes.
On
RSX-llM-PLUS systems BRU treats a disk that is mounted foreign as
an unmounted disk. BRU does not use the file system in either
case.
However, when you are doing a backup operation from a
mounted volume BRU checks read access privileges of both UFOs and
files against the UIC under which BRU is running.
BRU will restore to both mounted and unmounted volumes.
To
restore to an unmounted volume (or one mounted foreign on an
RSX-llM-PLUS system), specify the /INITIALIZE qualifier
to
initialize the disk to a Files-11 structure. To restore to a
mounted volume, specify /NOINITIALIZE to indicate to BRU that the
disk is mounted and already has a Files-11 structure on it.
/NEWVERSION
Resolves filespec conflicts that occur during restore operations
to an existing disk by creating new versions of the duplicate
files.
/NOINITIALIZE
Sp~cif ies

that you do not want to initialize the disk;
it
already has a Files-11 structure.
The output disk must be
mounted as a Files-11 volume.
You cannot enter any of the
initialization
qualifiers
listed
above
when you specify
/NOINITIALIZE. If you enter any of these qualifiers, BRU issues
an error message.
When you are restoring to a mounted volume (when you have
specified /NOINITIALIZE), BRU uses the file system to access the
output device. Therefore, a restore operation to a mounted
volume is slower than a restore to an unmounted volume.

\.,i

/NOPHESERVE
Specifies that you do not want to preserve file-IDs.
If you
specify /NOPRESERVE, BRU suppresses the warning message that
file-IDs are not being preserved.
When file-IDs are not preserved BRU assigns new file-IDs starting
at 6 and incrementing them sequentially.
/NOSUPERSEDg
When you are restoring to a mounted disk, specifies that when
file specifications on the output disk are identical to those on
the input disk, the file on the input disk is not transferred.
That is, the file on the output disk is not superseded by the
file on the input disk. NOSUPERSEDE is the default.

10-19

BACKUP AllD RESTORE UTILITY (BRO)

/OUTVOLUME:name
Specifies the volume label of the output disk.
up to 12 characters long.

This label can be

For backup operations, the name of the disk volume stored on the
output tape volume is changed to the name specified with the
/OUTVOLUME qualifier.
For restore operations or for disk-to-disk transfers, the name of
the output disk volume is changed to the name specified with the
/OUTVOLUME qualifier.
When you omit /OUTVOLUME, BRU provides the following defaults:
•

When you omit /OUTVOLUME in backup operations, the input
volume name is used as the volume name stored on tape.

disk

•

When you omit /OUTVOLUME in restore operations, the volume
name stored on tape is used as the name of the output disk
volume.

•

When you omit /OUTVOLUME in disk-to-disk transfers, the volume
name of the input volume is used as the volume name of the
output volume.

/POSITION:[ BEGINNING
[ MIDDLE
[ END
[ BLOCK:number
When initializing an output d1sk, specifies the location of the
index file on the volume, usually to minimize access time.
BEGINNING, MIDDLE, and END specify the beginning, middle, and end
of a volume.
BLOCK:number specifies a block number where the
index file is to be placed. The BEGINNING position is generally
used only when a disk contains predominently large contiguous
files.

- 1---r~

When you do not use the /POSITION qualifier, BRU places the index
file in the same location as that on the input volume.
/PROTECTION:( [protection value])
protection values:
SYSTEM:RWED
OWNER:RWED
GROUP:RWED
WORLD:RWED
When initializing an output disk,
specifies
the
default
protection status for all files created on the volume being
initialized. This protection value does not apply to files being
transferred by BRU, but rather to subs~quent files created on
that volume by an ACP when the volume is mounted. The protaction
values ,above are standard for RSX-llM files; however if not
specified, the values are defaulted to the protection values of
the input disk.
/REVISED:[BEFORE:(dd-mmm-yy [hh:mm:ss])]
[AFTER:(dd-mmm-yy [hh:mm:ss])]
Backs up or restores files revised
after the specified date and time.

created

on,

before,

10-20

" $12

$(j

;::;

BACKUP ARD RESTORE UTILITY (BRU)
/REWIND
newinds the first magnetic tape of a tape set before executing
backup or restore operation.

When specified with an input tape, BRU rewinds the first tape
the tape set before searching for backup sets.

When specified with /APPEND, BRU rewinds the first set of the
tape set and then searches for the logical end of the last backup
set on the ~ape before executing the backup operation.
/SUPEHSEDE
Specifies that when file specifications on the output volume are
identical to file specifications on the input volume, the file on
the output volume is deleted and replaced with the file from the
input volume. NOSUPERSEDE is the default.
/TAPE__ LABEL
Specifies the 6-character volume identifier on the ANSI VOL!
label to be placed on a tape during a backup operation or to be
compared with the label on the tape on append and restore
•operations.
This allows you to check that you have mounted the
correct tape.
/VERI:~y

Copies data from the input volume, performs a compare
after the transfer, and reports any differences.

operation

/WINDOWS:value
When initializing an output disk, specifies the default number of
mapping pointers to be allocated for file windows. This value is
used by an ACP when the volume is mounted.
A file window
consists of a number of pointers and is stored in memory when the
file is opened. The default number of mapping pointers is the
same as the default for the input disk.
Choosing a large number of mapping pointers may speed up file
access;
however, a large file window uses up system dynamic
memory (pool space}.
If pool space is more critical than file
access time, choose a smaller number of pointers.
Refer to Appendix F of the IAS/RSX-11
Manual for further information.

10.4

I/O

Operations

Reference

USING BACKUP AND RESTORE

This section contains information on how
functions:

use

the

following

Using the Bad Block Utility (BAD} with BACKUP and RESTORE

Using the Format Utility (FMT} with BACKUP and RESTORE

•

Using BRU to Initialize Disks

•

Restoring Data Selectively

10-21

BRU

BACKUP AND RESTORE UTILITY (BRU)
•

Transferring Data Between Disks of Different Size

•

BRU and File Characteristics

10.4.1

Using the Format Utility with Backup and Restore

The Format (FMT} utility places magnetic sector and timing marks on
disks.
In general, disks need to be formatted only once. However,
you may want to run FMT to ensure that the sector and timing marks are
accurate.
The format for invoking FMT is:
>FMT disk:
Where disk: is the logical name of the disk drive on which your
resides, for example:

pack

>FMT DBO:

10.4.2

Using the Bad Block Utility with Backup and Restore

Once the disk has been formatted, use the Bad Block (BAD)
locate bad blocks on the disk you are initializing.

utility

BAD uses two types of processes for disks: one for last-track devices
and the other for nonlast-track devices. Last-track devices have
manufacturer-written bad block information on the last half of the
last track. Nonlast-track devices have no such information.
BAD does pattern checking on the disk being formatted. That is, BAD
writes a pattern on the tracks of the disk being formatted, reads the
pattern from the disk, and then checks to ensure that the pattern was
read correctly.
For last-track devices, BAD uses the results of this checking, along
with the manufacturer-written bad block information, to create the
software-detected bad sector file, which is also placed on the last
track of the device.

·~

For nonlast-track devices, BAD uses only the results of its pattern
checking to create the bad block descriptor block. This block is then
placed on the last good block on the disk.
BRU uses this bad block information to create BADBLK.SYS, a file
occupying the bad blocks on a disk so that they cannot be used by the
file system.

10.4.2.1 BRU Bad Block Processing - Once you have formatted the disk
with the FMT utility and located the bad blocks using the BAD utility,
you can run BRU to complete initialization of the disk.
If you specify /BAD with the INITIALIZE qualifier, you can use one of
three options:
AUTOMATIC (the default), MANUAL, or OVERRIDE. The
following sections describe how to use these options.

10-22

2J!i

' a !iii :;

:;a;u:::

BACKUP ARD RESTORE UTILITY (BRU)
10.4 .. 2.2 Oi;ing the AUTOMATIC Qualifier - The AUTOMATIC qualifier
specjlf ies that BRU use the existing bad block information on the disk
to create the file BADBLK.SYS. For last-track devices BRU uses the
manuj:acturer-written bad block information and the software bad sector
file..
For nonlast-track devices BRU uses the bad block descriptor
block.

10.4 .. 2.3 Using the OVERRIDE Qualifier - OVERRIDE applies only to
last-track devices.
It makes the disk appear to be a nonlast-track
devic:e.
When yo~ use OVERRIDE with BRU, ensure that the disk you are
processing has previously been processed by the BAD utility with the
BAD /OVR sw:itch specified.
Usin~J

/OVR with BAD makes last-track devices look like nonlast-track
devices by using the last good block before the last track as the bad
bloc~: descriptor block.
/OVR processing includes that last track as
bad data when it creates the bad block descriptor block.

OVERRIDE processing for BRU assumes that the bad block
block written by BAD exists on the disk being processed.

descriptor

10.4 .. 2.4 Using the MANUAL Qualifier - The MANUAL qualifier uses the
manufacturer-written bad block information written on the last track
and E~ither the software-detected bad sector file or the bad block
descriptor block to create BADBLK.SYS. In addition, it accepts the
addresses of bad blocks you enter interactively at your terminal.
If
ther•~
is no software-written bad block information, a message will be
displayed warning that BAD has not processed the disk.
When you specify /BAD:MANUAL, BRU will
issue a prompt at your
terminal.
To enter bad blocks,
respond to the prompt with the
starting logical block number followed by a count of how many
consecutive blocks are bad, in the following format:
LBN :COUNT
This format is compatible with both the BAD and INI utilities.
BRU
interprets both the LBN and the count as decimal numbers. You can
specify the LBN in octal, but you must specify the count in decimal.
To specify an octal value for the LBN, precede it with a #.
When you have finished entering bad blocks, type <RET>
BRU command level.

10.4.3

return

Using Backup and Restore to Initialize Disks

You can use BRU commands in conjunction with the FMT and BAD utilities
to initialize
(format a Files-11 structure on)
a disk.
The BRU
initialization qualifiers provide the same capabilities as those of
the INI utility. Selecting appropriate values for the initialization
qualifiers requires an in-depth knowledge of Files-11. Refer to the
IAS/RSX-11 I/O Operations Reference Manual for details of the Files-11
disk structure. The following example shows the steps involved in
initializing a disk using BRU.

10-23

BACKUP AllD RESTORE.UTILITY (BRO)
RUN $FMT
FMT>DK2:
** WARNING - DATA WILL BE LOST ON DK2: **
CONTINUE? [Y OR N] : Y
START FORMATTING
OPERATION COMPLETE
FMT>"'Z
>BAD DK2:
BAD -- DK2: TOTAL BAD BLOCKS= O.
>RUN BRU
BRU>/INITIALIZE/OUTVOLUME:BACKUP/HEADERS:24/MAXIMUM:45/BAD:BRU>AUTOMATIC/POSITION:END/WINDOWS:3
FROM:
DKl:
TO:
DK2:
BRU -- *WARNING* -- THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM
BRU - COMPLETED
BRU>""Z

>
10.4.4

Selective Transfer of Data

BRU provides functions that allow you to transfer data selectively.
That is, you can select categories of files to be backed up using file
specification elements, date, and time.
For example, you can specify
that only files with the file type .OBJ or with UICs [1,54] be backed
up;
similarly, you can specify that only files created before August
4, 1978 at 2:00 PM be backed up.

10.4.5

Backup and Restore to

Disks of Different Size

BRU allows you to transfer data between disks of different sizes.
However, when you restore a volume containing a boot block, the new
volume is not bootable if the controller for the output device is not
compatible with the device controller on which the volume was created.
BRU prints a warning message.

~
I~ ~

NOTE
When restoring to an existing volume,
BRU will not issue the warning message.
If the new disk is smaller than the original, you may have problems
with the preservation of file-IDs.
In this event you should use some
of the qualifiers described in Section io.3.3 under the /INITIALIZE
qualifier.
If you make the index file smaller, BRU does not preserve
the file-IDs and a message is printed.

10-24

BACKUP ARD RESTORE UTILITY (BRO)
If you are transferring to a larger disk than the original, you must
use the /MAXIMUM and /HEADERS qualifiers to make full use of the
larger disk. If you do not specify a maximum number of files or file
headers, BRU uses the values of the original disk and you will end up
with a large disk that can contain only a small number of files.
Once you have initialized a disk with a maximum number of files, that
maximum cannot be extended. So the value for the /MAXIMUM qualifier
should be carefully chosen.
Refer to the IAS/RSX-11 I/O Operations Reference Manual for a detailed
description of Files-11 structure before choosing values for the
initialization qualifiers.

10.4.6

BRU and File Characteristics

This section explains in detail how
characteristics:
•

Creation and revision dates

•

File headers

•

File synonyms

•

Lost files

BRU

treats

the

following

file

10.4.6.1 Creation and Revision Dates of Files - BRU always preserves
the creation and revision dates of files that it transfers. However,
since BRU creates UFOs during a restore operation to an unmounted
volume the creation date of the UFD is the date on which BRU created
it.

10.4.6.2 File Headers - BRU preserves all characteristics of a
if possible. There are three exceptic>ns:

file,

•

If there is insufficient room on the output volume to restore
the file contiguously, it is restored noncontiguously.

•

The file name is updated on the file's header to match the UFO
entry.

•

The physical end-of-file in the user attribute area is updated
to reflect correctly the file's size.

10.4.6.3
file,s.

File Synonyms - BRU copies file synonyms to tape as separate

If you restore files with synonyms to an unmounted volume and you
preserve file ids, the file synonyms are restored as synonyms.
However, if you do not preserve file ids or you restore to a mounted
volume, file synonyms are restored as separate files.

10-25

BACKUP AND RESTORE UTILITY (BRU)
10.4.6.4 Lost Files - A file that is not contained in any UFO is
known as a lost file. BRU does not find lost files. To find lost
files, use the VFY utility with the /LO qualifier before using BRU to
back up the disk.

10.5

TAPE FORMAT INFORMATION FOR BACKUP AND RESTORE OPERATIONS

Magnetic tapes have ANSI standard tape label formats, as shown in
Figure 10-1.
The items at the beginning of the tape tell the tape
VOLl means
drive what it is reading: BOT means beginning of tape;
beginning of tape information;
and HDRl and HDR2 indicate the
beginning of a backup set.
BOT
VOLl
BOOT
HDRl
HDR2
Control
Record
Boot
Block
Home
Block
Directory
Headers

...
Headers
Data

...

Data
Headers

...

Data

EOFl
EOF2
EQT
Figure 10-1

Standard Tape Format for Magnetic Tapes
10-26

2 J iii$. ii

Qi!

I.I

p:;:

BACKUP AND RESTORE UTILITY (BRU)
10.5.l

Backup Sets

A backup set consists of all the data directed to a volume (or
volumes} during a backup or restore operation. A backup set includes
tape control data (one for each tape volume required}, header records,
and data records.
Physically, more than one backup set may be
contained on a tape, or a backup set can extend over several tapes.
The tape control data is written at the beginning of each backup set.
It contains a control record and on the first tape of a backup set,
the contents of the home block and boot block for the disk volume
being backed up. Directory records are interspersed with UFO records
to identify the owning UFO of the following directory records.
Each
entry in a directory record represents a file to be backed up and is
identical to the file's entry in the UFO that contains it.
The header data consists of an identifying record, UFO records, and
file header records.
The UFO identifier record identifies the UFO
containing the file headers following it.

'-'i

Data records consist of an 80-byte data identification
record
indicating that the records following are data records, and l to 10
data blocks preceded by a 48-byte area containing file identifiers and
retrieval pointers.

10.5.2

Tape Sets

More than one backup set may be contained on a tape, or a backup set
can extend over several tapes. In either case the resulting output is
called a tape set.
A tape set consists of the tape volume or volumes
transferred during a backup operation.

10.5.3

which

data

Multivolume Tape Operations

When you specify a magnetic tape drive as the output device in a BRU
operation, BRU writes the data contents of the input disk to the tape
on the drive. This data transfer often involves more than one reel of
tape and may utilize more than one tape drive.
You may specify multiple on-line tape drives in the following format:
BRU>/BACKUP SET:23MAY79A OMO: MMO:,MMl:
BRU -· STARTING TAPE l ON MMO:
BRU -· END OF TAPE l ON MMO:
BRU -· STARTING TAPE 2 ON MM!:
BRU - END OF TAPE 2 ON MM!:
BRU -· COMPL.ETED
You can specify only one type of drive, either MM or MT, in a single
BRU command. Although you can specify up to eight drives per command,
you can specify an individual tape drive only once.
If the number of tape volumes required exceeds the number of tape
drives available, BRU lets you replace tapes on the specified drive in
round-robin fashion.
10-27

BACKUP AND RESTORE UTILITY (BRO)
10.6

BACKUP AND RESTORE ERROR PROCESSING

This section lists BRU error messages, describes the
message, and suggests actions to correct the errors.

meaning

the

~.=···
...
-1-='.i
=:==

BRU -- *FATAL* -- ALLOCATION FOR SYS FILE EXCEEDS VOLUME LIMIT
Explanation:
A system file (one of the following
files:
INDEXF.SYS, BITMAP.SYS, BADBLK.SYS, 000000.DIR) requires more
space than is available on the output disk.
This will usually
occur if the output disk is smaller than the input disk.
User Action:
You can use the POSITION qualifier to force
allocation to start at the beginning of the disk and/or use the
MAXIMUM and HEADERS qualifiers to reduce the size of INDEXF.SYS.
BRU -- *FATAL* -- AMBIGUOUS KEYWORD
Explanation: A keyword specified with a qualifier is not unique.
For example /POSITION:B could mean either BEGINNING or BLOCK.
User Action: You can abbreviate keywords to the shortest
abbreviation.

unique

BRU -- *FATAL* -- AMBIGUOUS QUALIFIER
Explanation: A qualifier is not unique.
mean either REVISED or REWIND.
User Action: You can
unique abbreviation.
BRU
BRU

*WARNING*
*WARN ING*

abbreviate

For example, /RE

qualifiers

the

could

shortest

APPENDING AT 800 BPI on device:
or
APPENDING AT 1600 BPI on device:

Explanation: The wrong tape density was specified with the
/APPEND switch.
BRU will perform an APPEND only at the density
at which the tape is written.
User Action:

None.

BRU will continue at the correct density.

BRU -- *FATAL* -- ATTACH FAILED on device:
Explanation:

BRU could not attach the specified device.

User Action: Check to see if another task has the
attached, or if the device has a volume mounted on it.

device

BRU -- *WARNING* -- BAD BLOCK DATA ERROR
Explanation: A manually entered bad block
syntax was incorrect.
User Action:

location,

count,

Enter the correct information.

10-28

11~11z

BACKUP AND RESTORE UTILITY (BRU)
BRU -·- *WARNING* -- BAD BLOCK FILE CORRUPT.

DATA IGNORED

Explanation: The bad block file created by BAD contains invalid
data.
Unless you enter the bad blocks manually, BRU will assume
there are no bad blocks.
User Action:

use the /OVERRIDE qualifier to ignore the file.

BRU --- *WARNING* -- BAD BLOCK FILE FULL
Explanation: The manual addition of bad blocks has
more than 102 sets of contiguous bad blocks.
User Action: None.
file will hold.

You cannot enter more bad

resulted

blocks,

than

the

block

that

BRU -- *WARNING* -- BLOCK EXCEEDS VOLUME SIZE
Explanation: You have manually entered
larger than the size of the output disk.
User Action:

bad

Enter the correct block.

BRU ·-- *WARNING* --- BOOT BLOCK IS BAD
Explanation:
BRU cannot write to the output
Therefore the disk will not be hardware bootable.
User Action:
'-'

None.

block.

boot

BRU will continue the operation.

BRU -- *WARNING* -- BOOT BLOCK IS CORRUPT
Explanation: The input disk does not contain a valid boot block.
The output disk will not be hardware bootable.
User A~tion:

None.

BRU will continue the operation.

BRU -- *WARNING* -- BOOT BLOCK READ ERROR

~.·'
~·

Explanation:
block.

An error occurred while BRU was

User Action:

None.

reading

the

boot

BRU will continue the operation.

BRU -- *WARNING* ·-- BOOT BLOCK VERIFY ERROR on device:
Explanation: During a backup operation, the boot block on the
output device did not match the boot block on the input device.
User Action:

None.

BRU will continue with the operation.

10-29

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *WARNING* -- CANNOT RESTORE CONTIGUOUSLY
Explanation:
The output device does
not
contain
enough
contiguous blocks to restore the indicated contiguous file. The
file will be restored noncontiguously.
User Action: You can use the PIP utility to make the file
contiguous again. Use the PIP qualifiers /DE and /TR to reclaim
disk space by deletion or truncation.
BRU -- COMPLETED
Explanation:

The BRU operation is complete.

User Action:

Enter another BRU command or exit.

BRU -- *FATAL* -- CONFLICTING QUALIFIERS
Explanation:
Two or more of the specified qualifiers are
mutually exclusive:
for example, /SUPERSEDE and /NOSUPERSEDE.
User Action:

Retype the command line.

BRU -- *WARNING* -- DATA ID RECORD VERIFY ERROR
Explanation: There was an
80-byte DATA ID record.
User Action:

None.

error

while

BRU

was

verifying

BRU will continue the operation.

BRU -- *WARNING* -- DATA RECORD VERIFY ERROR [UFD]filename.type;version
FILE ID number
LBN number

·~
I
~

---·~:~

Explanation: There was a difference in a data block on input and
output devices.
The file id of the file with the error and the
lbn of the block follow the message.
If a [UFO] is printed with a file name, the UFO is the owner UFO
from the file's header, not the UFO in which the file is
contained.
User Action:

None.

BRU will continue the operation.

BRU -- *WARNING* -- DATA WAS LOST DUE TO IO ERRORS [UFO]
filename. type; version
Explanation: A tape read error resulted in missed data.
files will be restored but may contain erroneous data.

The

If a [UFO] is printed with a file name, the UFO is the owner UFO
from the file's header,
not the UFO in which the file is
contained.
User Action:

None.

BRU will continue the operation.

10-30

it; iU

Ji I S

I 5 I :qc:; t

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- DEVICE CONFLICT
Explanation: Both a tape and a disk drive were specified as part
of the input or output device specification.

User Action:
both.

The device must be either a disk or a tape but
This applies to both input and output specifications.

not

BRU -- *FATAL* -- DEVICE NOT IN SYSTEM
Explanation:
system.

A device was specified that does not exist

User Action:

Correct the device specification.

the

BRU -- *FATAL* -- DEVICE NOT SUPPORTED
Explanation:

The specified device was not a tape or a disk.

User Action:

BRU supports only magnetic tape and disk devices.

BRU -- *FATAL* -- DIRECTIVE ERROR
Explanation:

An internal error has occurred in BRU.

User Action:

Retry the operation.

BRU -- *WARNING* -- DIRECTORY VERIFY ERROR
Explanation: There was a difference in
input and output devices.
User Action:

None.

directory

record

BRU will continue the operation.

BRU -- *FATAL* -- DISK IS AN ALIGNMENT CARTRIDGE
Explanation: The last track identified the disk as an alignment
cartridge, which cannot be initialized as a Files-11 volume.

'-':

User Action:

BRU can be used only on Files-11 volumes.

BRU -- *FATAL* -- DISK READ ERROR
Explanation: An unrecoverable read error occurred on the
disk. This could be caused by an undetected bad block.

output

User Action: Use the BAD utility to locate all bad blocks.
use BRU with the /BAD:AUTOMATIC qualifier.

Then

BRU -- *FATAL* -- DISK WRITE ERROR
Explanation: An unrecoverable write error occurred on the output
disk. This could be caused by an undetected bad block.

User Action:

Use the BAD utility to locate all bad blocks.
use BRU with the /BAD:AUTOMATIC qualifier.

10-31

Then

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- DOUBLY DEFINED QUALIFIER
Explanation: The same qualifier was specified more than once
the command line.
User Action:

Retype the command line correctly.

BRU -- *WARNING* -- DUPLICATE BLOCKS FOUND
Explanation:
block file.

A manually entered bad block was already in the bad

User Action:

None.

BRU will continue the operation.

BRU -- END OF tape number ON device:
Explanation:
tape.

BRU has finished transferring data or

User Action:

None.

verifying

This is an informational message.

BRU -- *FATAL* -- END OF VOLUME ENCOUNTERED.

BACKUP SET NOT FOUND

Explanation: The backup set specified for a restore operation is
not on the tape volume.
User Action:
operation.

Mount

the

correct

tape

volume

and

retry

the

reading

the

BRU -- *FATAL* -- ERROR READING COMMAND FILE
Explanation: An I/O error occurred while
indirect command file.
User Action:

BRU

was

Retry the operation.

BRU -- *WARNING* -- ERROR READING DATA BLOCKS
I/O ERROR CODE-number
FILE ID number
LBN number
or
RECOVERED

~
I t'

......·

Explanation: An I/O error occurred while BRU was reading a data
block from the disk. The file id of the file which contains the
block and the lbn of the block are displayed as well as the I/O
error code. If RECOVERED is printed after the message, the block
was recovered by issuing 1-block reads from the disk.
User Action:

None.

BRU will continue the operation.

BRU -- *WARNING* -- ERROR READING UFO [group,number]
Explanation: An I/O error occurred while BRU was reading a block
from the specified UFD. Any files contained in this block of the
UFO will not be backed up.
User Action: You may retry the operation. If the error
occurs, you can find the files by using the VFY utiltity.

still

10-32

::S;t

BACKUP AND RESTORE UTILITY (BRU)
BRU
'--;

*WARN:CNG* -- ERROR READING UFO HEADER [group,number]
Explanation: An error occurred while BRU was reading the header
<>f the specified UFO. Files in this UFO will not be backed up.
User Action: Retry the operation. If the
use the VFY utility to find the file.

error

still

occurs,

BRU -- *WARNING* -- EQT MARKER ERROR
Explanation: An error occurred while BRU was
writing
verifying the end of tape labels on the output tape.

User Action: On a write error, BRU will rewind the current tape
.and put it off-line. BRU will request that a new tape be mounted
and will rewrite the tape.
On a verify error, BRU will continue.
BRU -- *FATAL* -- ERROR LIMIT EXCEEDED
:Explanation: BRU has reached the specified number of
errors and terminated execution.

tape

User Action: Retry the operation, using a different tape
or after cleaning the tape drive heads.

read
drive,

BRU -- *WARNING* -- EXTENDING INDEX FILE
Explanation: The initial number of file headers was too small.
Either 256 or 16 more headers will be allocated depending on the
number of blocks on the output disk.
User Action:

None.

BRU will continue the operation.

BRU -- *FATAL* -- FAILED TO READ BAD BLOCK FILE
Explanation: BRU was unable to read the
from a last-track output disk.
User Action:
qualifier.

Retry

the

operation,

bad

block

information

using

the

/BAD:OVERRIDE

BRU -·- *WARNING* -- FILE HEADER READ ERROR [group,number] filename.type;version
I/O ERROR CODE-number
Explanation: An I/O error occurred while BRU was reading a
headero That file will not be backed up.
User Action:

None.

file

BRU will continue the operation.

BRU -- *WARNING* -- FILE HEADER VERIFY ERROR [group,number] filename.type;version
Explanation: The file header of the specified file on the output
device is not the same as that on the input device.
User Action:

None.

BRU will continue the operation.

10-33

BACKUP AND RESTORE UTILITY (BRU)
BRU

*WARNING* -- FILE ID AREA VERIFY ERROR
Explanation: The BRU-generated file id area of a data record was
different on the input and output devices.
User Action:

None.

BRU will continue the operation.

BRU -- *FATAL* -- FILE ID EXCEEDS MAXIMUM NUMBER OF FILES
Explanation: You specified a maximum number of files with
MAXIMUM qualifier, which was too small to perserve file ids.
User Action: Specify a larger value with the MAXIMUM
or use a larger output disk.

the

qualifier,

BRU -- *WARNING* -- FILE ID SEQUENCE NUMBER ERROR [UFO] filename.type;version
Explanation:

There are two possible sources of this error:

The sequence number in the file id of a file does not
match the sequence number of the file's entry in the
UFO.

The sequence number of a UFO does not match the sequence
number of the UFD's entry in the MFD.

Therefore, the file or UFO is not valid and will not be copied.
User Action:

None.

BRU will continue the operation.

BRU -- *WARNING* -- FILE IDS WILL NOT BE PRESERVED
Explanation: File ids cannot be preserved because the bitmap on
the output disk is too small.
This is because the value
specified with the MAXIMUM qualifier was too small.
User Action:
None.
preserving file ids.

BRU

will

continue

the

operation,

not

BRU -- *WARNING* -- FILE MARKED FOR DELETE [UFO] filename.type;version
Explanation: The marked-for-delete bit (SC.MDL) of the system
controlled characteristics in the file header was set, indicating
that the file was partially deleted.
The file will not be
copied.
User Action:
BRU -- *WARNING*

None.

BRU will continue the operation.

FILE NOT FOUND [UFO] filename.type;version

Explanation: During a backup operation, the specified file does
not have a header in the index file. The file is not copied.
During a restore operation,
verified on the output disk.
User Action:

BRU

cannot

find

the

file

being

BRU will continue the operation.

10-34

••••:•Jt.•:•&•l bli !li..$•••------------------..-------··•:•32•••••:•t•t•:• •,.,_

!iiilll)ll•••t

BACKUP AND RESTORE UTILITY (BRU)
BRU -·· *FATAT.. * -- HANDLER NOT RESIDENT
J~xplanation:

The device driver for the specified device

not

loaded.
User Action: Load the driver for the specified device, or retype
the command line specifying the correct device name.
BRU -- *WARNING* -- HEADER ID RECORD VERIFY ERROR
Explanation: The header id record on the
different from the one on the input device.
User Action:

None.

output

device

BRU will continue the operation.

BRU -·-*WARNING* -- HEADER READ ERROR [UFD]filename.type;version
I/O ERROR CODE-number
An I/O error occurred while BRU was reading a
header in the index file during a backup operation.

l~xplanation:

file

If this error occurs during a restore operation, it is fatal.
User Action:

None.

BRU -- *FATAL* -- HOME BLOCK READ ERROR
I/O ERROR CODE-number
Explanation: An I/O error occurred while
home block on the input device.
User Action:

BRU

was

reading

the

Retry the operation.

BRU -- *WARNING* -- HOME BLOCK VERIFY ERROR

'-''

.Explanation: The home block on the output
from the home block on the input device.

device

User Action: BRU will continue, but it
retry the operation.

suggested

that

you

Explanation: An unrecoverable I/O error occurred while
writing the home block on the output device.

BRU

was

different

BRU -- *FATAL* -- HOME BLOCK WRITE ERROR

user Action:

Use BAD.

10-35

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- ILLEGAL USE OF DIRECTORY QUALIFIER
Explanation:
1.

The DIRECTORY qualifier was
device.

specified

with

output

The DIRECTORY qualifier
otl)er than tape.

specified

with

device

Initialization qualifiers
directory qualifiers.

was

with

the

User Action: Refer to Section 10.3.3 for a description of
uses of the DIRECTORY qualifier.

valid

were

specified

BRU -- *FATAL* -- INCONSISTENT INITIALIZE QUALIFIERS
Explanation: Qualifiers that initialize the output
specified, but the NOINITIALIZE qualifier was used.
User Action:

disk

were

reading

the

Retype the command line.

BRU -- *FATAL*
INDEX FILE HEADER READ ERROR
I/O ERROR CODE-number
Explanation: An I/O error occurred while BRU
header of the index file on the input disk.
User Action:
BRU -- *FATAL*

was

Retry the operation.
INDEX FILE WRITE ERROR

Explanation: An unrecoverable I/O error occurred while
writing the index file to the output disk.
User Action: Use BAD to identify the bad blocks on the
disk. Then initialize the disk and retry the operation.

BRU

was

output

BRU -- *FATAL* -- INDEXF.SYS IS FULL
Explanation:

The index file cannot map any more file headers.

User Action: Retry the operation, using a larger value with
/MAXIMUM qualifier.

the

BRU -- *FATAL* -- !NIT QUALIFIERS INVALID WHEN OUTPUT IS TAPE
Explanation: The initialize qualifiers may be used only when the
output device is a disk.
User Action:

Retype the command line.

10-36

2 42

&SJ $2

tt Ha

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATA.L* -- INPUT DEVICE EQUALS OUTPUT DEVICE
Explanation:

The input and output devices must be different.

User Action:
Retype
devices for input and

the

command

line,

specifying

command

different

output~

BRU -- *FATAL* -- INPUT LINE TOO LONG
Explanation:
characters.

The

maximum

length

line

256

User Action: You may abbreviate qualifiers and keywords as
as the abbreviations are unambiguous.

long

BRU -- *FATAL* -- INTERNAL ERROR IN BRU

'-':

Explanation: BRU has detected
should not normally occur.

error

within

itself.

User Action:
information.

SPR

with

all

incorrectly

Please

submit

This

pertinent

BRU -- *FATAL* -- INVALID DATE
Explanation:
range.

A date was

specified

User Action:

Specify the correct date.

out

neither

800

nor

BRU -- *FATAL* -- INVALID DENSITY
Explanation:
1600 BPI.

A density was specified that was

User Action:
density.

Retype the command

BRU -- *FATAL*

BRU

specifying

the

correct

indirect

command

file

INVALID FILENAME

Explanation: The name
syntactically correct.
User Action:

line,

the

not

Retype the command line.

*WARNING* -- INVALID TAPE FORMAT
Explanation:
operation.

An invalid tape record was read

User Action:

None.

during

restore

The invalid record will not be restored.

10-37

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- INVALID VALUE
Explanation: A value specified
syntax or is out of range.

for

User Action: Refer to Section 10.3.3
values for the particular qualifier.

qualifier
to

has

determine

illegal

the

valid

BRU -- *WARNING* -- INVALID DATE ON FILE HEADER [UFO] filename.type;version
Explanation: An invalid date was encountered on a
during an incremental backup. The file is copied.
User Action:

None.

file

header

BRU will continue the operation.

BRU -- *FATAL* -- MANUFACTURER BAD BLOCK SECTOR FILE IS CORRUPT
Explanation: BRU was unable to read the
from a last track output disk.
User Action:
qualifier.

Retry

the

operation,

bad

block

information

using

the

/BAD:OVERRIDE

was

reading

BRU -- *FATAL* -- MFD HEADER READ ERROR
Explanation: An I/O error occurred while
header of the Master File Directory.

BRU

the

User Action: Retry the operation. If the header still cannot be
read, the files on the disk are lost and may be recovered using
the VFY utility.

_!l_i·.-·

f'1'--··

BRU -- *WARNING* -- MFD READ ERROR
Explanation: An I/O error occurred while BRU was reading a block
of the MFD. BRU cannot copy the UFOs in that block of the MFD.
User Action: Retry the operation. If the block cannot be
use the VFY utility to recover the lost files.

read,

BRU -- *FATAL* -- MISSING COLON
Explanation: A qualifier keyword that accepts a
followed by a colon.
User Action:

value

was

not

one

level

Retype the command line.

BRU -- *FATAL* -- MORE THAN 1 LEVEL OF INDIRECTION
Explanation: BRU does
indirect command files.
User Action:

not

support

than

Retype the command line.

10-38

11;1111a

2!$

BACKUP AND RESTORE UTILITY (BRU)
BRU -- MOUNT TAPE n ON ddn:
.Explanation: There is no tape on the specified drive or the tape
is not at load point. This message will print every two minutes
until the tape is mounted.
User Action;

Mount the tape specified on the drive specified.

BRU -- MOUNT ANOTHER TAPE
Explanation: BRU is requesting that a new tape be mounted
encountering a fatal tape write error.
User Action:

after

Mount a new tape on the drive.

BRU -- *FATA.L* -- NAME MORE THAN 12 CHARACTERS
Explanation: A name, such as a backup set name, is
12 characters ..
User Action:

longer

than

Specify a name not greater than 12 characters.

BRU -- *WARNING* -- NO BAD BLOCK DATA FILE FOUND
Explanation: The BAD utility has not been run on the output disk
to produce a file of the disk's bad blocks.
User Action: None. BRU will continue the operation.
Refer
Section 10.4 for information on bad block processing by BRU.

BRU -- *WARNING* -- NO FILES FOUND [UIC] filename.type;version
Explanation:
the UF'D or
file.

During a backup operation, BRU found an entry in
MFD that had no corresponding header in the index

During a restore, compare, or verify operation, BRU
the specified file on the output device.
User Action:

cannot

find

BRU ignores the entry.

BRU -- *WARNING* -- NON FATAL QUALIFIER CONFLICTS BEING IGNORED
Explanation: You entered a qualifier that conflicts with
rest of the command line and is nonfatal if ignored.
example!, /REWIND on a disk-to-disk operation.
User Action:

None.

the
For

BRU will continue the operation.

BRU -- *FATAL* -- NON OCTAL NUMBER
Explancation:

A decimal number was used where an octal number was

expecte~d.

User Ac:tion:
number ..

Retry

the

operation,

10-39

using

the

correct

octal

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- NUMBER OF HEADERS EXCEED MAXIMUM NUMBER OF FILES
Explanation: The number of initial file headers must be at least
five less than the maximum number of files in order to account
for the system files.

- I :r

-.•.;-,····-···.···.

User Action: Use the /HEADERS qualifier to specify the number of
initial file headers.
BRU -- *FATAL* -- OUTPUT DISK TOO FRAGMENTED TO RESTORE
Explanation: Internal tables in BRU have overflowed due to
extreme fragmentation of the output disk.
If the output disk was
initialized, then it has an unacceptable number of bad blocks and
should not be used as a backup medium.
User Action:

Use a new disk as the output device.

BRU -- *FATAL* -- OUTPUT VOLUME IS FULL
Explanation: There are no free blocks on the output disk.
This
can occur when the output disk is smaller than the input disk, or
during an append to a tape that is already full.
User Action: If the output disk is too small, do an incremental
backup of only the files you want.
If you wore doing an append
to a tape that is already full, repeat the operation using a new
tape.
BRU -- *FATAL* -- OVERRIDE INVALID WITH NON LAST TRACK DEVICE
Explanation: The OVERRIDE keyword may
output disk is a last-track device.
User Action:

used

only

when

the

Refer to Section 10.4.

BRU -- PLEASE ANSWER YES OR NO
Explanation:

BRU requires a response.

User Action:

Enter YES or NO at your terminal.

BRU -- *FATAL* -- PRIVILEGE VIOLATION
Explanation: The input volume is mounted as a Files-11 structure
but the /MOUNTED qualifier was not entered on the command line.
In copying from a mounted volume, the
access to the specified UFD or file.

user

User Action:
Either dismount the disk or
qualifier on the command line.

did
specify

not
the

have

read

/MOUNTED

10-40

Si$

$& 14

jQ!

BACKUP AND RESTORE UTILITY (BRU)
BRU -·- *FATJ\L* -- RAN OUT OF SPARE FILE IDS
Explanation:
ids.

The output disk is too fragmented to preserve

file

User Action: Retry the
operation
using
the
/NOPRESERVE
qualifier. You may want to use a different output disk.
BRU -- *WARNING* -- RECORD NOT EXPECTED SIZE
Explanation: The record read on the output device
verify or compare operation was not the expected size.
User Action:

None.

during

BRU will continue the operation.

BRU -·- *FATAL* -- REQUIRED INPUT DEVICE MISSING
Explanation: The input device was not specified on
line or in response to the prompt.

the

command

Explanation: The output device was not specified on the
line or in response· to the prompt.

command

User Action:

Retype the command line.

BRU -·- *FATAL* -- REQUIRED OUTPUT DEVICE MISSING

User Action:

Retype the command line.

BRU -- REWIND ERROR ON ddn:
Explana~ion:

An I/O error occurred during a tape rewind.
This
error is fatal if it occurs on the first tape of a tape set or
during a rewind for verify. The error is not fatal if BRU is
rewinding a tape it is finished with.
User Action:

None.

BRU -·- *FATAL* -- SEARCH FOR HOME BLOCK FAILED
Explanation: The home block could not be found on the input
disk. Either the home block is bad or the disk is not Files-11.
User Action:

Check to see that you have the correct disk.

BRU --- *FATAL* -- STACK OVERFLOW IN SORT ROUTINE
Explanation: A stack internal
should not normally occur.
User Action:
information.

Please

submit

BRU

has

SPR

with

10-41

overflowed.
all

This

pertinent

BACKUP AND RESTORE UTILITY (BRU)
BRU -- STARTING TAPE n ON ddn:
Explanation: This message tells you which tape is
to on which drive.
User Action:

None.

being

copied

This is an informational message.

BRU -- STARTING VERIFY PASS
Explanation:
verified.

This

message

tells

you

which

tape

User Action:

None.

This is an informational message.

being

BRU -- *FATAL* -- SYNTAX ERROR
Explanation:

The command line is invalid.

User Action:

Retype the command line.

BRU -- TAPE LABEL ERROR ON ddn:
I/O ERROR CODE -number
Explanation: An I/O error occurred while BRU was reading or
writing a tape label. A write error is fatal; a read error is
not fatal as long as BRU can continue reading the tape.
User Action:
If a write
using a different tape.

error

occurred,

retry

the

operation

BRU -- *WARNING* -- TAPE LABEL VERIFY ERROR
Explanation: A difference was found between the input and output
on a tape label.
User Action:

None.

BRU will continue the operation.

BRU -- *WARNING* -- TAPE NOT AT BOT.

NO REWIND OR APPEND SPECIFIED

Explanation: For a backup operation to tape, BRU will not start
processing a tape that is not a BOT unless the /APPEND qualifier
was specified for BRU.

~
~

User Action: Use the /APPEND qualifier if you want to start
writing at the current tape position. Use the /REWIND qualifier
to position the tape to BOT.
BRU -- *WARNING* -- TAPE OUT OF SEQUENCE.

PLEASE MOUNT CORRECT TAPE

Explanation~

The wrong tape volume was mounted on the tape drive
during a restore from tape operation.
User Action:

Mount the correct tape on the drive.

10-42

4 2&24!

I 12

Ia;

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *WARNING* -- TAPE POSITIONING ERROR.

BACKSPACE FAILED

Explanation: During a backup operation, the tape
positioned properly for a future append operation.
User Actions

was

not

Rewind the tape before attempting to appende

BRU -·- *FATAL* -- TAPE POSITIONING ERROR.
I/O ERROR CODE-number

NO EOV ENCOUNTERED

Explanation: The space files operation to find the end-of-volume
for an append operation failed.
User Actions

Retry the operation.

BRU -·- *WARNING* -- TAPE READ ERROR

'-''

Explanation:

An I/O error occurred while reading a tape.

User Action:

None.

BRU will continue the operation.

BRU -·- *FATAL* -- TAPE TO TAPE NOT SUPPORTED
Explanation:

BRU will not back up a tape to another tape.

User Action:

None.

BRU --- *WARNING* -- TAPE WRITE ERROR
I/O ERROR CODE-number
Explanation: An I/O error occurred while writing to tape.
BRU
will rewind the tape and request that another tape be mounted.
User A9tion: If the error is related to
terminate BRU and start over on another drive.

the

tape

drive,

BRU ··- *WARNING* -·- THIS DISK WI LL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM
Explanation: The output disk
This can be caused by:

will

not

hardware

The input disk not being bootable

The system image not being restored

Restoring to a disk of different size or type
NOTE
This warning will not be issued
restoring to an existing volume.

User Action:

None.

10-43

when

bootable.

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- TOO MANY DEVICES
Explanation: As an input or output device a disk may be
specified only once.
However, up to eight tape drives may
constitute the input or output.
User Action: Retype the command line specifying only one disk or
no more than eight tape drives.
BRU -- *FATAL* -- TOO MANY FILE SPECIFICATIONS
Explanation: More than 16 file specifications were specified
the command line.

User Action: Retype the command line. You may use wildcards
reduce the number of file specifications on the command line.

BRU

*FATAL* -- UFO OR MFD REQUIRES UNSUPPORTED EXTENSION HEADERS
Explanation:
UFOs.

BRU does not support extension headers for MFDs

User Action: This error should not occur.
with all pertinent information.

Please submit an

or
SPR

BRU -- *WARNING* -- UFO RECORD VERIFY ERROR
Explanation: There is a
devices on a UFO record.
User Action:

None.

difference

between

input

and

output

BRU will continue the operation.

BRU -- *FATAL* -- UNKNOWN KEYWORD
Explanation:
BRU.

A keyword was specified that was. not recognized

User Action: Retype the command line.
of valid keywords.

See Table 10-1 for a list

·~
/.f!

BRU -- *FATAL* -- UNKNOWN QUALIFIER
Explanation:
by BRU.

A qualifier was specified that was

User Action: Retype the command line.
of valid qualifiers.

not

recognized

See Table 10-1 for a list

BRU -- *FATAL* -- UNSUPPORTED STRUCTURE LEVEL
Explanation: The file structure level on the input disk
supported by BRU.
User Action:

not

Check to see that you have the correct disk.

10-44

111111111&

ii 4

i id$

ill

U IL

!#A

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *WARNING* -- VBN NOT IN FILE
Explanation: A file id was encountered which is larger than the
maximum file id in the index file. The file is ignored. This
error message will occur if a UFO entry was corrupted on the
input disk.
User Action:

None.

BRU will continue the operation.

BRU -- *FATAL* -- VERIFY LOST
Explanation: During the verify pass of a disk to tape backup,
BRU has lost synchronization between the input and the output.
This is usually caused by tape position being lost or by backing
up from a disk that is mounted and being changed during the
backup operation.
User Action:

Retry the operation.

BRU -- *FA'I'AL* -- VOLUME NOT A BACKUP TAPE
Explanation: The tape mounted for an append or restore operation
was not generated by BRU.
User Action:

Check to see that you have the correct tape.

BRU -- *FA'I'AL* -- VOLUME NOT READY
Explanation:

The device is not on-line.

User Action:

Put the device on-line and retype the command line.

BRU -- *FA'l'AL* -- VOLUME WRITE LOCKED
Explanation:

The output device is not write enabled.

User Action: If the output device is a tape, insert a write
ring. If it is a disk, press the write enable switch on the disk
drive.
BRU -- *FA'l'AL*

WRONG BACKUP SET

Explanation: The backup set name specified with the /BACKUPSET
qualifier does not match the backup set name on the tape.
User Action:
name.
BRU -- *FA'l~AL*

Retry the operation with

the

correct

backup

set

WRONG INPUT VOLUME LABEL

the
with
specified
label
Explanation: The input volume
/INPUTVOLUME qualifier does not match the volume label of the
input device.
User Action:
label ..

Retry the operation with the correct

10-45

input

volume

a 14 a : a

CHAPTER 11

DISK SAVE AltD COMPRESS (DSC)

The Disk Save and Compress (DSC) utility program copies entire
Files-11 disk files either to disk or to tape, and from DSC-created
tape back onto disk.
At the same time, DSC reallocates
and
consolidates the disk data storage area: it concatenates files and
their extensions into contiguous blocks whenever possible, and may
reduce the number of retrieval pointers and file headers required for
the same fi.les on the new disk volume.
DSC copies files that are randomly scattered over a disk volume to a
new volume, without the intervening spaces. This eliminates unused
space between files and cuts down on the time required to access them.
A complete DSC operation is a cycle that begins with data on one disk
and ends with the same data on another disk, in compressed form. The
operation can use
one
command
(for
a
direct
disk-to-disk
transcription) or two commands (for a disk-to-tape and tape-to-disk
transcript ion).
After a DSC copy operation, individual files are written in contiguous
blocks whenever possible, and the blocks available for new files are
located in a contiguous area at the end of the new volume.
DSC reads and writes data to two of its own buffers when it performs
copy or compare operations.
(See Figures 11-1 and 11-2.) Each buffer
normally is large enough to contain four disk blocks and a 16-byte
bufj:er prefix. However, the block factor switch (BL) in a DSC command
line allows you to increase the number of blocks in each buffer, up to
the maximum space available for DSC on your system.

'-'/

In a disk-to-disk copy operation, DSC:
1.

Copies data from disk to a DSC buffer

Copies data from the DSC buff er to another disk

In 4:1 disk-to-tape/tape-to-disk operation
1.

Copies data from disk to a DSC buff er

Writes data from the DSC buff er to tape

Copies data from tape to a DSC buff er

Writes data from the DSC buff er to another disk

You can execute operations 3 and 4, to restore data to
time, as long as the data on the tape is intact.

disk,

any

If the contents of one disk are transferred to a disk with a larger
capacity, the new disk takes on the attributes of the original disk,
except that additional storage space is available.
11-l

DISK SAVE ARD COMPRESS (DSC)

BLOCKS OF DATA

•

__..

-......

• --

DSC
BUFFER 1

---"

......

I
DSC
BUFFER 2

•

DISK INPUT DEVICE

DISK OUTPUT DEVICE

DSC reads 8 (default) or more blocks of data from the disk
input device to two buffers.

•

In disk-to-tape copy operations, DSC writes data from the buffers
to magnetic tape .

•

In disk-to-disk copy operations, DSC writes data from the buffers
to the disk output device.
DSC repeats step 1 and 2 or 3 until it copies the entire input device.

Figure 11-1

Data Transfer for DSC Copy Operation

11-2

!Ill•!

I 12

1 II I

!Si

!iU st

212

DISK SAVE ARD COMPRESS (DSC)

-..

BLOCKS OF DATA

DSC
BUFFER 1

DSC 2
BUFFER

1
I

•

DISK INPUT DEVICE

•

DISK OUTPUT DEVICE

DSC reads 4 blocks of data from the disk input device to a buffer.

•

DSC reads 4 blocks of data from the disk output device to the
second buffer.

•

DSC compares the contents of the two buffers.

DSC prints the differences on your terminal.

DSC repeats steps 1 through 4 until it has compared the entire device.

Figure 11-2

Data Transfer for DSC Compare Operation

11-3

DISK SAVE AND COMPRESS (DSC)
After a disk-to-disk copy operation, you can access the contents of
the file on the new disk directly. However, after a disk-to-tape
operatioin youf cannot access the data on tape directly, becaiuse it is
stored n a ormat recognizable only to DSC. To access th s data, you
must perform a second copy operation and transfer the data to another
disk volume.

......
, ·.
. 11

When DSC copies and compresses a disk containing a saved system (a
task image file created from an RSX-llM or RSX-llM-PLUS system image
by an MCR SAVE command), it moves all task files to different physical
addresses.
However, because the Task Control Block (TCB) entries for
each task contain file identifications rather than Logical Block
Numbers (LBNs), a system can function normally after a SAVE when it is
rebooted. The file identifications will not change.
NOTE
You can copy bootable system
disks
created on RSX-llM versions 3.0 and
higher, IAS versions 2.0 and higher, and
RSX-llM-PLUS.
These disks will retain
their
bootable
characteristics.
However, bootable system disks created
on earlier versions of the operating
systems should not be copied using DSC.
You can also use DSC to recover from hardware malfunctions which have
made a portion of a disk volume unreadable. If the contents of a
block allocated to a data file cause a read error, DSC copies the
garbled contents to the output device and generates a warning message
labeling the garbled data block. You can then access the block and
correct its contents.

11.l

-~.·,·
I r'

DSC-SUPPORTED VOLUMES

You can use DSC with a variety of mass storage devices.
The status
DSC requires for the devices varies with the operating system. DSC
can only access unmounted volumes on RSX-llM systems.
However, IAS
and RSX-llM-PLUS systems require volumes to be mounted with foreign
characteristics. Table 11-1 lists the devices that can be used with
DSC operations.

.~
. · . ·._.·

- lcf

11-4

''i•••••••tl4l..,•:•iiii•Z4••2••t,¥••••••••---------•••••t•::•••••••••t•••••••a•a•••11.•;•G•••a11J

DISK SAVE AllD COMPRESS (.DSC)

Table ll.-1
DSC-Supported Devices
Abbreviation

Type

Class

DD*

TU58 cassette (DECtape II)

Block structured

RK611/RK06/RK07 cartridge
disk

Block structured

RH11/RP04/RP05/RP06 and RH70
RP04/RP05/RP06 disk pack

Block structured

RKll/RKOS/RKOSF cartridge disk

Block structured

OF*

RFll/RSll fixed head disk

Block structured

RL11/RL01/RL02 cartridge
disk

Block structured

RP11/RP02/RP03 disk pack

Block structured

RH11/RH70/RM03/RM02/RP07
disk pack

Block structured

OS*

RH11/RS03/RS04 and RH70/RS03
RS04 fixed-head disk

Block structured

OT*

TC11/TU56 DECtape

Block structured

DX*

RXll/RXOl floppy diskette

Block structured

DY*

RX02 floppy diskette

Block Structured

RH11/TM02-03/TE16/TU16/TU45/TU77
and RH70/TM02-03/TE16/TU16/
TU45 and TU77 9-track magnetic
tape

Tape

TMll/TUlO/TElO 7- or 9-track
magnetic tape and TMAll/
TS03 9-track magnetic tape

Tape

Indicates that the device cannot be used with stand-alone DSC.

Table 11-2 lists the status required for devices used
with each operating system.

11-5

online

DSC

DISK SAVE AND COMPRESS (DSC)

Table 11-2
DSC Device Status
Operating System

Device

Device status required
for DSC operation

RSX-UM-PLUS

Disk

Mounted with foreign
characteristics

Tape

Mounted with foreign
characteristics

Disk

Unmounted

Tape

Unmounted

System disk

Mounted with DCF
characteristics

All other
volumes

Mounted with foreign
characteristics

RSX-UM V3. 2

IAS

11.2

INITIATING AND TERMINATING ONLINE DSC

You can initiate the online version of DSC in any of the ways
explained in Chapter l of this manual. To terminate online DSC, type
(CTRL/Z) •

.~
I F
..

11.3

INITIATING AND TERMINATING STAND-ALONE DSC

You can bootstrap a stand-alone version of DSC (DSCS8.SYS)
from disk
or from tapes supplied with the operating system. The exact method
depends on which operating system you are using.
Under either RSX-llM or RSX-llM-PLUS, you
DSC in one of two ways:
1.

can

bootstrap

stand-alone

Enter the privileged MCR BOOT command as follows:
BOO[T]

[l,50]DSCS8

This command bootstraps DSCS8.SYS from the disk.
2.

Mount a volume containing stand-alone
appropriate beginning bootstrap address.

DSC

and

load

the

Under IAS, you can invoke stand-alone DSC by hardware bootstrapping
volume containing it.

When stand-alone DSC is booted, it displays the message:
RSX-llS V2.2 BL26 DISK SAVE AND COMPRESS UTILITY V3.0
DSCS8>
The prompt indicates that DSC is ready to accept commands.
Terminate stand-alone DSC by halting the processor.

U-6

I. 22iiiiiiii!S 4

2446

came

ijik

DISK SAVE AND COMPRESS (DSC)
11.4

DSC COMMAND FORMAT

Comm4ands for DSC use the format:
DSC>outdev[s]:[filelabel] [/switch]=indev[s]:[filelabel] [/switch]
The parameters of this command format are:

Output Parameters

The physical volume(s) to which data is copied. The format for
outdev:
is AA[nn]:
where AA are the ASCII characters for the
volume abbreviation, [nn] is an optional 1- or 2-digit octal unit
number for the volume, and the colon (:) is a line terminator.
If you omit the volume number, O is the default. DSC uses tape
drives, in the order specified in the command line. If more
tapes are required than specified, DSC accesses the tapes drives
available in round-robin fashione
DSC ignores multiple disk specifications. However, up to eight
tape drives, separated by commas, can be specified as output
devices in an online DSC operation. Stand-alone DSC permits only
two tapes to be used as output devices.
file label

'-'

Identifies the disk volume ID or tape file or tape set DSC
creates in a data transfer. You can specify a file label with
either disk or tape output volumes. If you do not specify a file
label when you create a tape or disk with DSC, the input disk
volume label becomes the output disk volume label or tape file
label.
switch
One or more of the optional switches described in Section 11.5.

Input Parameters
indev:

'-'··

The physical volume(s), in the format AA[nn]:, from which data is
copied (see outdev: above).
file label
Identifies the DSC-created tape file that is being transferred to
disk or compared.
If you do not specify a file label, DSC
transfers the first file it encounters after its current position
on the tape.
DSC ignores the specification of an input file
label when the input volume is a disk.
NOTE
Each file on a DSC-format tape set
contains the entire contents of the disk
it backed up.
switch
One or more· of the optional switches described in Section 11.5.

11-7

DISK SAVE ARD COMPRESS (DSC)
11.5

DSC FILE LABELS, SWITCHES, ARD OPTIOMS

DSC commands can contain file labels and switches. Some switches also
use options to specify values. Table 11-3 summarizes the DSC switches
and options. Note that all of these switches can be used with both
online and stand-alone DSC.
See Table 11-6 for switches available
only for stand-alone DSC.

· · .,

Table 11-3
DSC Switches and Options
Switch

Format

Description

Append

/AP

Bad Block

MAN
/BAD= NOAUTO
MAN :NOAUTO

Block Factor

/BL

Sets the number of 256 word
blocks DSC can include in
each of its buffers.

Compare

/CMP

Compares input and output
volumes for differences.

Density

/DENS=l600
/DENS=800:1600

Overrides the DSC default
storage density for magnetic
tapes of 800 bits per inch.
DENS=l600 creates magnetic
tapes at 1600 bits per inch
density and 800:1600 (the
split density switch)
creates tapes with volume
headers at 800 bits per inch
and the rest of the tape at
1600 bits per inch.

Appends a DSC file to the
first volume of a magnetic
tape set that already
contains a DSC file which is
currently the last file of
the set.
Allows manual entry of
bad block locations; can
supplement, override, or
ignore the disk's own bad
block file.

Note that the DENS=l600
switch is valid with TU16,
TE16, or TU45 drives. The
DENS=800:1600 is valid with
TU16 or TU45 drives when
they are not controlled by
the TM03 formatter.
Rewind

/RW

Rewinds all magnetic tapes
before DSC executes the
current command.

Verify

/VE

Copies data from the input
volume and compares it with
the output volume.

11-8

!22¢3

iii

lfl!Jfi

DISK SAVE AND COMPRESS (DSC)

11.s.1

File Label

The file label identifies the data copied from a disk and stored on
one or more tapes or on another disk. If you do not specify a file
label, DSC uses the volume ID of the input disk volume label as the
output volume label.
The file label can consist of from l to 12 alphanumeric characters.
However, DSC only uses the first 9 characters to identify the file it
creates containing the disk's entire contents. Place the file label
after the device specification and before any switches. Terminate the
file label with one of the following:
•

An option switch

•

An equal sign (indicating the end of the output
command line)

•

A carriage return (indicating the end of the command line)

side

the

For example:
DSC>MM01:,MM02:SYSFILE=DB1:
DSC uses the file label SYSFILE in the command above to identify the
file on tape that contains the data to be copied from the input disk,
DBl:.
You can also use the file label when restoring data from tape to disk.
If you enter a file label as part of the input specification, DSC
searches the first volume for a file with that name.
When it finds
that file, DSC transfers it to the output volume. If, however, you do
not specify an input file label, DSC transfers the first DSC-created
file it locates on the first input volume. In both cases, using the
Rewind switch on the input side of the command causes the tape to be
rewound before the search for the file starts.
If you use a file label as part of the output specification, it will
be used as the file label of the output disk. If you do not specify
an output file label, the output disk will have the same label as the
original disk.
(Even if the disk was copied to tape first, DSC
ignores the file name on the tape and uses the name on the original
disk.)
For examplei:
DSC>DBl:=MM01:,MM02:SYSFILE
In this command, the Rewind switch is not specified on the input side.
Therefore, DSC searches the first volume specified, MMOl:, beginning
at the current position, for a DSC-created file named SYSFILE. If DSC
finds SYSFILE on MMOl:, it completes the data transfer. If, however,
SYSFILE is not found qn the first volume, DSC issues an error message
and terminates the operation.
If you enter the above command without a file label, DSC transfers the
first DSC-created file it finds to DBl: regardless of the file name.
(This file may or may not be SYSFILE.) If you do not specify the
Rewind swi.tch, the tape may or may not be positioned at the beginning
before DSC begins its operation.

11-9

DISK SAVE AND COMPRESS (DSC)
11.5.2

Append Switch

The Append switch (/AP} directs DSC to begin writing a file to the
first specified volume of a tape set that contains only DSC-created
files. If more than one DSC-created file exists on the first volume,
and the last file extends to other volumes, DSC displays an error
message and terminates the operation.
Enter the Append switch as part of the output specification.
The
volume to which files will be appended must be specified as the first
volume of the output side of the command string, as follows:
outdev: [f ilelabel]/AP=indev: [filelabel] [/switch]
When you use the Append switch with the output specification, DSC
searches from the current position on the first specified tape output
volume for the last logical end-of-file (EOF} created by a previous
DSC command.
If the last DSC-created file does not end on that
volume, DSC terminates the operation and issues the following message:
OUTPUT TAPE AAnn:

IS FULL

If the first specified tape output volume contains a portion of a DSC
file that began on a previous volume, DSC terminates the operation and
issues the following error message:
OUTPUT TAPE AAnn:

IS A CONTINUATION TAPE

If DSC locates the end of a file on the tape that began on another
volume, DSC terminates the operation and issues the following error
message:
OUTPUT TAPE AAnn:

IS NOT THE ONLY REEL IN ITS SET

For example:
DSC>MMOl:,MM:SYSFILE/RW/AP=DXl:
This command appends the contents of DXl:
to the last DSC-created
file already present on the first output volume specified, MMOl:. DSC
first rewinds the tape on MMOl: and searches for the last EOF block
on the tape. When it determines that only complete DSC-created files
exist on the volume on MMOl:, DSC appends the new file, SYSFILE, to
the file or files already on the tape. If necessary, DSC extends
SYSFILE to additional volumes. Since the Rewind switch is specified,
the search will not begin until the tape is rewound.
You can only use the Append switch with output tape volumes.
Any
other use of the switch causes DSC to generate a message and terminate
operation.

11.5.3

Bad Block Switch

Use the Bad Block switch (/BAD} with output disk
the way DSC uses bad block information.

volumes

control

Three options for the Bad Block switch allow you to supplement the
output disk bad block file with manually-entered bad block data, to
ignore the bad block file altogether, or to use only manually-entered
bad blocks. The bad block descriptor of the disk is never altered by
DSC.

11-10

iwa•as .ii

!.!

••

.J LIL

14'

DISK SAVE AND COMPRESS (DSC)

The format for the BAD switch and its options are:
/BAD=MAN
/BAD=NOAUTO
/BAD=MAN:NOAUTO
MAN
Allows manual-entry of bad block data, which is included
bad block file created on the disk.

the

NOAUTO
Causes DSC to ignore the bad block descriptor on the disk,
resulting in an empty bad block file during the DSC operation.
Note that in this case DSC will attempt to write in any block it
selects.
MAN:NOAUTO
Causes DSC to enter only manually-entered bad block data in the
bad block file.
Thus, DSC bypasses only manually entered bad
blocks when selecting blocks to write in.
When you specify MAN or MAN:NOAUTO with
responds with the following prompt:

the

Bad

Block

switch,

DSC

DSC issues this prompt after it accepts the original command line
before it transfers any data.

but

DSC>LBN (S) =

Enter the locations of bad blocks following the LBN(S)= prompt.
You
can specify multiple bad block entries on one command line, using
either a space, tab, or comma to separate each entry.
You can also
use separate lines for each entry. Enter bad block data immediately
following the equal sign (=), in the format:
DSC>LBN (S) :::;n: m
n

Is the logical block number (LBN), in octal, of the
block in the group.

\...,··

initial

bad

Is thE! number, in octal, of consecutive blocks contained
groupu If you do not specify m, it defaults to 1.
To specify a decimal number for either m or
after the number.

place

the

period

(.)

After you enter the first group of bad blocks, DSC reissues the
LBN(S)= prompt. At this point, you can enter additional bad blocks by
repeating the above procedure.
To terminate manual bad block entry, enter a carriage return after the
LBN I[ S) = p rc:>mpt.
When you have entered all the bad blocks
process, DSC begins the data transfer.

11-11

and

terminated

the

entry

DISK SAVE AND COMPRESS (DSC)
For example:
DSC>DB1:/BAD=MAN:NOAUTO=MM0l:,MM02:SYSFILE/RW
DSC>LBN (S) =702: 7 ~ 644: 2
DSC>LBN(S)=4057,5001:3
DSC>LBN (S) =C£D
DSC>
DSC restores the output disk, DB!:, from the tape file SYSFILE
contained on MMOl:
and MM02:, skipping only the blocks you entered
manually. In the example above, the following blocks will not be
used:
702
703
704
705
706
707

644
645

4057
5001
5002
5003

710

Compare the above example with the following example:
DSC>DBl:/BAD=NOAUTO=DBO:
This example transfers data to the lowest LBNs on DBl:, regardless
the content of the resident bad block desc~iptor.

11.5.3.l Obtaining Bad Block Information - You can obtain
information in three ways:
·
1.

Running the Bad Block Locator
Chapter 9 of this manual

utility

(BAD),

Running the Field Service stand-alone diagnostic

Running INI[TVOL] with the BAD=[option] switch.

bad

block

described

The BAD utility (number 1 above) automatically provides bad block
information using LBNs, and creates a bad block file that DSC can use.
The Field Service stand-alone diagnostic reads every word in a block
and displays bad block messages on the console terminal.
{This
diagnostic is recommended for the user who wants more comprehensive
testing of a volume).
However, since the output is the physical
address of each bad block, you must convert this address to logical
block numbers before DSC can use it.

11.5.3.2 Conversion To Logical Block Numbers - All
information must identify bad blocks by LBN.

DSC

bad

block

The manufacturer-furnished or diagnostic bad block information usually
identifies bad blocks by physical address {sector-track-cylinder).
Before you enter this information manually for DSC, convert the
physical addresses to LBN, using the following formula:
(((cylinder number*tracks/cylinder)+track number)*sectors/track)+sector number

11-12

a :: a;

iii

p;t

DISK SAVE AND COMPRESS (DSC)

For example, suppose a bad sector of an RP06 (19 tracks per cylinder
and 2:2 sectors per track) has the following physical address:

\.I··

Cylinder Number= 536 (8), 350 (10)
Track Number= 16 (8), 14 (10)
Sector Number = 13 (8), 11 ( 10)
The LBN for the example above is calculated as follows:
(((3500*19.)+14.)*22.)+ll.=146619.

11.5~4

Block Factor Switch

The Block Factor switch (/BL) allows you to set the number of blocks
DSC uses in each of its buffers during I/O operations. The default
DSC block factor is four blocks or the last value specified in a BL
switch.

11.504.1
is:

Using the BL Switch - The format for the Block Factor switch

outdev: [filelabel]/BL=n=indev: [filelabel]/BL=n
The valu~ of n can be any positive integer, decimal or octal, less
than or equal to the maximum block factor available to DSC. This
maximum depends on the amount of memory DSC can access under the
system configuration.
The BL switch can be specified either on the input or output side of a
DSC command line.
If the input volume is tape, DSC determines the block factor from the
label of the input file and ignores specification of the BL
switch.

headE~r

If you specify the BL switch on both sides of a DSC command line with
a disk volume, DSC uses the last value it receives, that is, the one
from the input side of the command. However, if you specify the BL
switch only on the output side of a command, DSC uses that value.
DSC requires 2020(8) bytes of memory for each additional block of
buffer space you specify. If the BL switch in a DSC command requires
more memory than DSC has available, DSC displays the message BAD
BLOCKING FACTOR and exits.
For 1example:
DSC>DBl:/BL=ll=DBO:
In this example, DSC attempts to increase the number of blocks in each
of its buffers to 11. DSC requires an additional 16160(8) bytes of
memory for the expansion (7 additional blocks times 2020(8) bytes).
If DSC does not have access to 16160(8) additional bytes of memory
your system, it will display the error message.

If the expansion succeeds, DSC reads and writes 11 blocks of data at
one time during an I/O operation instead of 4. This decreases the
time required for DSC operations.

11-13

DISK SAVE AND COMPRESS (DSC)
Once DSC has expanded its buffers in response to a new value of /BL,
that value becomes the default value. DSC does not reduce its task
image size if a command is executed at a lower block factor.
However,
if you specify a lower block factor in a subsequent command, DSC will
create that volume at the lower factor.

11.5.4.2 System-Dependent Requirements for BL Switch - Table 11-4
describes the memory requirements for buffer expansion with RSX-llM or
RSX-llM-PLUS operating systems. Online DSC on a mapped system (llM or
llM-PLUS)
expands automatically if memory is available.
(See RSX-llM
or RSX-llM-PLUS System Generation and Management Guide for details of
building DSC with additional memory.)
Table 11-4
Operating System Limits for DSC Block Factor
Operating System

Default
Blocking
Factor

Maximum
DSC
Size

Maximum
Blocking
Factor

RSX-llM/M-PLUS
Mapped Systems

32K words

36(10)

RSX-llM
Unmapped Systemsl

20K words

10(10)

1 On unmapped RSX-llM systems the DSC task must be rebuilt
additional memory for the block factor to be increased.

with

NOTE
If you create DSC tapes on an RSX-llM or
RSX-llM-PLUS
system,
at a blocking
factor greater than 10, they will be
unusable on unmapped RSX-llM systems
which can only use DSC tasks of 28K
words.

11.S.S

compare Switch

The Compare switch (/CMP) directs DSC to compare the contents of two
disks or a disk and a tape set. Multiple tape specifications are
valid, but multiple disks are not.
If the input volume in a compare
operation is tape, use the Compare switch on the input side of the DSC
command line.
If both input and output volumes are disk, you can use
the Compare switch on the output side of the command line. The
compare switch performs only comparison operations;
no copy operation
is involved.
To perform both a copy and compare
switch (see Section 11.5.8).

operation,

use

the

DSC

Verify

Specify the Compare switch as follows:
outdev: [filelabel]/CMP=indev: [filelabel]

11-14

i~·=

di!!

ii.

t !l 3i I

1!iii

;q:a...

DISK SAVE AND COMPRESS (DSC)

\.,I

When DSC detects an end-of-volume (EOV) on any reel or end-of-file
(EOF) on other than the first reel of a tape set, the CMP switch
causes DSC to rewind and unload the current volume and resume
compa1rison with the next volume, until it detects an EOF.
When DSC finds a difference between the volumes it is comparing, it
displays a warning on your terminal. This warning lists the output
volume number, file identification, and the Virtual Block Number {VBN)
where the difference was found. DSC then continues the comparison~
When DSC begins a comparison involving tape, it first positions the
specified or implied file as described in Section 11.5.7. DSC
positions a single volume tape at the end of the current file when the
comparison ends.
Each reel of a tape set is rewound and unloaded as
the operation on it is completed. DSC then resumes the comparison,
using the next volume of the set.

11.5.6

Density Switch

The Density switch, with its two options, allows you to override the
DSC default storage density of 800 bits per inch for TU16, TE16, TU77,
and TU45 tape drives.
The following two sections discuss these
switches.
Although you can use other tape drives with DSC, only the
above-mentioned drives can support the Density switch.
With TE16
drives, you can use the DENS=l600 switch, but you cannot use the split
density switch. In addition, tape drives controlled by a TM03 cannot
use the split density switch.

'-''

You do not have to specify a Density switch when a tape is the input
in a DSC command. DSC determines the density of all input tapes by
first reading the tape at 800 bits per inch and, if that fails, then
reading at 1600 bits per inch.
If you specify a density switch with
message and halts the operation.

disk,

DSC

issues

error

If you specify a density switch with tape drives other than those
above~,
DSC ignores the switch and does not alter the default 800 bits
per inch density. Note that TS04 drives write all tapes at 1600 bits
per inch. Therefore, it is not necessary to specify a density switch
with DSC commands that use TS04's.

1600 Bits per Inch Switch - The 1600 Bits per Inch Density
switch directs the TU16, TE16, TU77, or TU45 drive to operate as an
output volume at a density of 1600 bits per inch.
The drive then
writes all volumes in the tape set at that density. For example:
11.5~6.l

DSC>MM01:,MM02:SYSFILE/RW/AP/DENS=l600=DB1:
In this example, MMOl:
dens Hy.

and MM02:, are written at 1600 bits

per

inch

ll.So6.2 Split
Density
Switch - The
Split
Density
switch
(/DENS=800:1600) directs the TU16 or TU45 drives {using the TM02 tape
formatter) to write the entire tape set, except for the first two

11-15

DISK SAVE AND COMPRESS (DSC)
blocks on each volume, at 1600 bits per inch. The first block on each
volume contains header information and the second block is a dummy
boot block that displays the following error message if an attempt is
made to boot the volume:
THIS VOLUME DOES NOT CONTAIN A BOOTABLE SYSTEM
In the following example, DSC records the first two blocks of the
first volume at 800 bits per inch and the remainder of each volume at
1600 bits per inch.
DSC>MM01:,MM02:SYSFILE/RW/DENS=800:1600=DB1:
NOTE
Tapes created using the Split
switch violate ANSI standards.

11.5.7

Density

Rewind Switch

The Rewind switch (/RW) directs DSC to rewind all volumes in a tape
set before performing any other DSC operation, such as a copy or a
compare. You can use it to rewind either input or output volumes (see
Table 11-6).
If you enter the RW switch as part of the input specification, DSC
rewinds all of the tapes before the DSC operation begins. If you
specify a file label with the RW switch, DSC rewinds the tapes and
searches for the file you specified from the Beginning of Tape (BOT)
on the first volume.
If you do not specify a file label, DSC transfers the first
DSC-created file it encounters on the first volume. After one volume
of a tape set has been copied, DSC rewinds it and places it off line.
If, however, the current file ends on the first or only tape of a set,
the tape is positioned to read the next file on the input tape.
The
RW switch only rewinds tapes at the beginning of a DSC operation.
If you enter the RW switch as part of the output specification, DSC
begins by writing or comparing data from the beginning of the rewound
output tape. Thus, in a copy operation, DSC overwrites any data
previously stored on that tape, unless the Append switch is included
in the command.
If you do not en~er the RW switch with the output specification, and
the first volume is not positioned at BOT, DSC begins its operation
after the first DSC-created EOF it reads.
If the tape is positioned at BOT, DSC overwrites it from there unless
you specified the AP switch. If the file extends beyond the first
volume of a tape set, that volume and all subsequent volumes are
rewound and unloaded as they are filled. Otherwise, the tape is left
at EOF to append another file to the first volume of the set. If DSC
finds an EOV during its search for the last EOF, the command is
aborted and DSC issues an error message.
Table 11-5 summarizes the use of the Rewind switch
operations and with and without a file label.

11-16

with

various

DSC

~
- I

DISK SAVE AND COMPRESS (DSC)
Table 11-5
Commands Using DSC Rewind Switch

'w··

Switch

Specification

File Label

Action

Input/Output

With/without

Rewinds first tape
before copy
operation begins.

Input

With

DSC searches for
specified file
from the beginning
of the first tape
volume.

Input

Without

DSC transfers the
first file it
encounters on the
first volume.

Output

File labels
specified when
tape is output
volume are
ignored when
the tape is
restored to
disk.

DSC writes data,
starting at the
beginning of the
first tape volume.

No
Rewind
Switch

Output

DSC writes data,
beginning after
the first
end-of-file block
it encounters.
(If tape is
already at BOT,
DSC starts there.)
During copy
operations to
multiple tapes,
DSC rewinds the
tape as it is
filled, and takes
it offline.

The RW switch can be used only with magnetic tapes.
with any other volume, DSC prints an error message.

you

use

An example of the use of the Rewind switch follows:
DSC>MMOl:SYSFILE/RW=DBl:
DSC rewinds the volume on drive MMOl:
and overwrites any data on the
tape.
The contents of DBl:
are written to a single file identified
as SYSFILE. DSC does not rewind the tape when the operation is
finished unless the file extends to another volume.
If the file does
extend, DSC rewinds and unloads the filled tape.
DSC ensures that
subsequent tapes are at the beginning of tape before using them for
read or write operations. Each subsequent volume, including the last
one in the tape set, is rewound and unloaded when it is filled.
11-17

DISK SAVE AND COMPRESS (DSC)
The following example shows the restoration of a DSC-created file:
DSC>DBl:=MM02:,MMOl:SYSFILE/RW
In this example, DSC restores a volume {DBl:) using a tape created by
a previous DSC operation. DSC rewinds the first volume (on MM02:) and
searches for a previously created DSC file labeled SYSFILE.
If the
file is found, DSC transcribes it. If it is not found on MM02:, DSC
issues a message and terminates the operation. DSC will not go on to
MMOl:
if the file does not begin on MM02:. Each volume of the tape
set is rewound and unloaded when the data it contains has been copied
or compared.

·""'I··
~:::r

NOTE
When you refer to tapes for the first
time since your system was booted, you
must use the Rewind switch. If you do
not use the switch, the tape driver will
return an error.

11.5.8

Verify Switch

The Verify switch {/VE) entered as part of the output specification
directs DSC to perform a copy operation followed by a compare
operation to verify that the two volumes are the same.
{DSC does not
allow you to specify either the Verify or Compare switch if both input
and output volumes are tape.)
If either the input or output volume is tape, the Verify operation
takes place at the end of the Copy operation for each volume. In
other words, DSC writes MMOl: and compares MMOl:; writes MM02:
and
compares MM02:, until the entire DSC operation is complete. In a
disk-to-disk DSC operation, the Verify operation begins when the Copy
operation is finished.
You specify the Verify switch as follows:
outdev: [filelabel]/VE=indev: [filelabel] [/switch]
If you do not specify a file label for a tape set, the
causes DSC to begin copying the first volume of the set.

switch

When DSC detects EOV or EOF on any volume of a tape set during a copy
operation, it repositions the input volume to the beginning of the
current file and begins the verify operation.
During a verify operation, if DSC detects EOV on any volume, or EOF on
other than the first volume of a tape set, it rewinds and unloads the
tape when the operation is complete. After an EOV, the copy operation
resumes, using the next volume from the beginning of the tape.
NOTE
If you specify a tape as one of the
volumes, DSC requires extra time after
the copy operation to rewind the tape
and search for the current file before
it begins to verify.

11-18

I . iii! fQCS

DISK SAVE AND COMPRESS

11. 6

(DSC)

DSC OE•ERATION OVERVIEW

DSC initially accesses the first primary file header and writes the
blocks mapped by its retrieval pointers to the output volume.
DSC
then checks the primary file header to determine whether it points to
any extension headers.
If extension headers exist, DSC transcribes
them and the blocks they map until the entire file, with all of its
extensions, has been written to the output volume.
Only then does DSC
access the next primary file header in the index file.
For example:
DSC> DBl: =DB2:

~:J
In this example, DSC copies all the files on DBl:
to DB2:.
'\______./

When DSC copies file extensions
it updates the output retrieval
pointers and file linkages involved in the transfer as required. This
not only involves collapsing retrieval pointers, but also may reduce
the number of file extensions required if enough retrieval pointers
are e~liminated.

'-'.•

As a result of a copy operation, each primary file header is followed
by all of its extensions.
Volumes created in a Merge mode copy
operation have complete files written to contiguous blocks
(except
where blocks have been flagged as bad in earlier operations on the
volume).
DSC writes data, beginning at the lowest LBN possible on the
disk.
If an input file is contiguous, DSC will search for an area on the
output volume with enough contiguous blocks to contain the file.
If
no such area exists,
DSC will
issue an appropriate message and
terminate the copy operation.
If an input file is not contiguous,
contiguous sections as possible,
available on the output volume.

11. 7

data
is allocated in as few
in the first unoccupied blocks

STAND·-ALONE DSC

Stand-alone DSC (DSCS8.SYS) does not support all the features of the
online version.
DECtapes, floppy diskettes, DF/DS fixed-head disks,
and TU58 cassettes cannot be used with stand-alone DSC.
However,
in
data transfer operations,
stand-alone DSC uses all of the switches
described in Section 11.5.
When you run stand-alone DSC without any of
below the following default values apply:

the

switches

described

•

Logical unit numbers of devices are limited to 0 and 1

•

Only two input or output volumes can be specified per command

•

One controller is supported for each device type

•

Nonstandard vector addresses are generated for RM03, RP02, and
RP03 disk volumes,
and TUlO/TElO, and TS03 magnetic tape
drives

You can overcome some of these limitations by using four switches,
listed in Table 11-6. These switches change the standard DSC default
values to the values your system requires.
However, the switches can
only be used with stand-alone DSC.

11-19

DISK SAVE ARD COMPRESS (DSC)
Table 11-6
Stand-Alone DSC Switches
Format

Switch

Description

/CSR=xxxx

Control Status
Register switch

Alters control status
addresses for specific
device types

/TM02=x

TM02/TM03 Formatter
switch

Alters the physical
unit formatter

/UNIT=x

Unit switch

Specifies the physical
unit that a LUN accesses

/VEC=xxx

Vector Address
switch

Alters the vector
address of a unit

The four switches supplied with stand-alone DSC can appear together in
a single command line to alter the appropriate values of a single
device or device type. However, you can only alter values for one
device type,
or generate one data transfer operation, in a single
stand-alone DSC command line.
Therefore, when you use these switches, you must enter at least two
command lines;
one to specify the switches with a device or device
type, and one to initiate the DSC data transfer operation.
NOTE
Once you use the switches, DSC uses them
in all subsequent commands until you
either specify new switches in a new
command or terminate DSC.
The general format for a stand-alone DSC command with switches is:
DSCS8> AAnn:/switchl=x ••• /switchn=y
AAnn:
The device identifier and unit number
switchl through switchn
One or more of the stand-alone
11.7.l through 11.7.4

switches

described

Sections

x,y
The value you assign to the switch

11.7.l

Control Status Register Switch

Use the Control Status Register switch
(/CSR)
to alter the device
Control Status Register addresses generated by stand-alone DSC so that
they conform to the addresses required by your system.

11-20

J¢ 3 iiii!L)

S$b

SLU4il 2211

DISK SAVE AND COMPRESS (DSC)
Table 11-7 displays the CSR and
supported by stand-alone DSC.

vector

addresses

the

devices

Table 11-7
System-Generated CSR and Vector Addresses
Device Type

CSR

Vector

DB:

176700

254

DK:

177404

220

DL:

174400

160

OM:

177440

210

DP:

176714

300*

DR:

176700

320*

MM:

172440

224

MT:

172522

320*

* Indicates nonstandard vector address.
The following example illustrates the correct use of the CSR switch:
DSCS8>MM1:/CSR=l60546
DSCS8>DBO:/CSR=l60646
In this example, the system using DSC has the CSR addresses of the
MMl:
tape drive and the DBO: disk drive set to 160546 and 160646,
respectively. After you enter these values, you can enter another
DSCS8 command line to initiate a copy and/or compare operation.
Neither of the commands that use the CSR switch in the example cause a
copy operation to begin.
'-'

If a DSC operation involves multiple devices of the
specify the CSR once for each device type.

11.7.2

same

type,

only

TM02 Switch

The TM02 switch
(/TM02) alters the physical unit number of the
TM02/TM03 formatter on the RH controller from the value generated by
stand-alone DSC to the value required by your system.
Stand-alone DSC assigns a physical unit number of O to the TM02/TM03
formatter on the RH controller.
You can change this to any octal
digit from 1 to 7 for each MM: device.
For example:
DSCS8>MM1:/TM02=1
This command alters the TM02/TM03 position on the RH controller from O
(the generated value) to 1 for MMl:. The TM02 switch alters only the
device you specify.
If another MM:
device requires an altered

11-21

DISK SAVE AND COMPRESS (DSC)
assignment,
which is the usual case, specify the new device and its
assignment in a separate command. The TM02 switch only works with MM:
devices;
it cannot be specified with an MT:
or disk device.

11.7~3

Unit Switch

You can use the Unit switch (UNITS=) to ~hange the unit numbers DSC
accepts for device specifications.
Stand-alone DSC is generated with,
and accepts only, two logical unit numbers, 0 and 1. In addition, the
unit numbers used in the command string cannot be changed. These
constraints can be amended somewhat with the UNITS= switch.
The
numbers O and 1 must still be specified in the command line, and the
number of devices cannot be increased.
However,
DSC can access
devices with physical numbers other than 0 and 1. For example:
DSCS8>DPO:/UNIT=5
After you enter the above command and a command line that references
DPO:, the disk actually accessed is the disk assigned as physical unit
5. If DP!:
also requires a physical unit change, it will have to be
specified in another command.

11.7.4

Vector Address Switch (/VEC=)

The Vector Address switch (/VEC=) switch changes the stand-alone DSC
vector addresses to the addresses required by your system.
Each unit
of the device type is accessed by the specified vector address.
For
example:
DSCS8>DB1:/VEC=320
After you enter the above command, all DB:
with a vector address of 320.
Stand-alone
conflicting
contains:

devices will

accessed

DSC uses nonstandard vector
addresses
to
resolve
unit configurations. These conflicts occur when a system

•

A TU16 drive and TElO/TUlO drive or
drive

TU16

drive

and

•

Any combination of RP02/03, RP04,05/06, and RM02/03
an RP02 disk and an RP04 disk).

TS03

tsuch

For example, before you can reference TElO, TUlO, or TS03 tapes,
you
must use the VEC switch to alter the DSC vector setting of 320 to the
correct value for your system.
DSCS8>MT1:/VEC=224
After you enter this command, all MT devices will be accessed with a
vector address of 224 (instead of the DSC-generated vector address of
3 20).
If the VEC switch is not used to alter the DSC setting, DSC waits for
a
response from the incorrect vector address. This response never
comes.

11-22

/$ii

DISK SAVE AllD COMPRESS (DSC)

11.8

DSC OPERATION

As outlined in the beginning of this chapter, DSC's complete data
transfer process consists of either a direct disk-to-disk operation or
a two-step, disk-to-tape/tape-to-disk operation. DSC reads and writes
data to and from its own internal buffers during these operations.
The following sections describe DSC's operation in each of these
transfers.

11.8.l

data

Data Transfer from Disk

After you enter a DSC command specifying a copy operation from a disk,
DSC scans the input disk to ensure that it is in Files-11 format. DSC
begins by copying an approximation of the disk index file.
Because
this file is updated to reflect the status and location of blocks as
they are allocated on the new disk, the index file bit map, the
storage bit map file, and the bad block file are not transcribed
exactly: DSC transcribes only the data necessary for the construction
of these files on the new disk. However, the index file bit map still
reflects the maximum number of files on the input disk.
DSC accesses the input volume index file's index of active file
headers in numerical order to locate the next active primary file
header. DSC transfers that header, the blocks it maps, and all
extension headers and related blocks that are part of the file, to the
output medium. It then accesses the next active primary file header
from the index file. DSC continues this operation, each time writing
a complete file, until it has transferred all the active files.
DSC accesses and transcribes only the blocks allocated to active
files.
It ignores unallocated blocks interspersed throughout the
input disk. This results in contiguous data blocks on the output
disk, following the copied files.
If DSC accesses a file that contains bad data, DSC transcribes
whatever it reads from the block. When DSC restores the file to disk,
it writes the block's contents as it originally read them.
The
logical block still contains garbled data, but the new physical block
can be accessed and its contents corrected.
A message identifying
these bad areas is displayed on the console terminal.
In summary, to transfer data from a disk, DSC:
1.

Verifies that the disk is online, and in Files-11 format

Transcribes disk index files, updated for their new status

Reads the data to a DSC buffer

11.8.2

Data Transfer to Tape

When the output volume in a DSC operation is tape, DSC writes the
contents of the input disk to a tape on the drive you specify. This
data transfer usually involves multiple reels of tape (a tape set) and
multiple tape drives.
The tapes that DSC creates serve as a back-up of the disk's contents.
You can only use DSC-created tapes by copying them back to a disk
volume and restoring the disk's contents to their original form.

11-23

DISK SAVE AND COMPRESS (DSC)
Although the tapes contain many individual files from the input
volume, DSC treats the tapes as if they contained a single file
a
file of the disk's entire contents.
When DSC begins writing the volume's contents to tape, it allows
writing to more than one volume. The first block DSC writes to tape
is a header that contains the volume name (obtained from the file
label) and the relative volume number. This header identifies the
tape set and the volume's place within that set. It ensures that when
DSC begins to restore the disk it will load each volume in the tape
set in order.
After the header, the tape set includes the data required to
reconstruct directory files, maps and pointers, and the actu~l files
copies from the disk.
NOTE
When the disk is restored, the directory
files are at the beginning of the disk,
regardless of their position on the
original disk.
To initiate the write-to-tape operation, first ensure that the tape
devices are online.
You can specify multiple tape drives in the
following way:
DSC>AAnn(O) :,AAnn(l) :, ••• AAnn(7): [filelabel]=indev:
An example of a command in this format is:
DSC>MMO:,MM1:,MM4:,MM2:SYSFILE=DB1:
You have the option of entering a file label in this command after
specifying the last device.
You can specify only one type of tape
drive, either MM: or MT: or MS:, in a single DSC command.
Although
you can specify up to eight drives on each side of the command line
(two drives in the stand-alone version) you can specify
each
individual drive only once.
If the number of volumes in the tape set exceeds the number of tape
drives available, DSC uses volumes on the specified drives in
round-robin fashion.
Using the above example,
the
order
of
replacement would be
MMO:

MMl:

MM4:

MM2:

MMO:

MMl:

MM4:

MM2:

until an end-of-file is reached.
In summary, to transfer data to tape, DSC:
l.

Verifies that the first or only
online and write-enabled

volume

tape

set

Verifies that subsequent volumes of a tape set are at
Tape
(BOT),
online when required, and
Beginning
of
write-enabled

3. Transcribes data from a DSC buffer to the tape

11-24

!i"

i••••••u111¥•J•:1a•z.-@••a•••••••·--------•••llll•••••••••••a•.:•:•s••t•tt•:•. •::•::•1••;•£&•21:

111111111111t•.

DISK SAVE AND C.OMPRESS (DSC)

11.8 .. 3
~

Data T.ransfer from Tape

DSC can only use the tapes it creates to (l) reconstruct a disk or (2)
perfc>rm compare and verify operations.
When you mount the tapes and specify tape drives as input devices, DSC
sequentially accesses and writes the tape contents to the output
volume. As it transfers the data, DSC creates and updates directory
files.
Tape drives specified as input devices must be online. The volumes in
the tape set must be referenced in the correct order in the command
line.
If you specify a file label, DSC transfers only the contents of the
file
identified by that label.
If you do not specify a file label,
DSC transfers only the first DSC-created file
it encounters on the
first volume of a set.
In summary, to transfer data from tape, DSC:
l.

Verifies that the tape drives are online

Accesses the volumes in a tape set in round-robin order

Creates directory files

Reads the data into a DSC buffer

ll.8u4

Data Transfer to Disk

DSC's operation is not complete
transfer is restored to disk.

until

the

data

involved

the

To receive input, a disk must be online. Any disk iarge enough to
contain all the input data can be specified as the output volume in a
data transfer to disk.
The disk should have an up-to-date bad block descriptor, or have bad
block data entered in a DSC command with the BAD switch. This ensures
that the data written on the disk will be accessible. You can update
the bad block descriptor before a DSC operation by running the BAD
utiHty.
After identifying the bad blocks on the output disk, DSC examines that
volume to ensure that it has enough free blocks to contain all the
data being transferred.
DSC compares the number of blocks being
transferred from the input volume(s) with the number of blocks
available on the output volume. DSC issues an error message and exits
if too few blocks are available.
DSC begins constructing index and storage bit map files when it begins
transcribing files.
DSC updates the file headers to reflect the
location of the files on the new disk.
This updating is required
because blocks that were previously scattered are now copied to a
contiguous set of blocks, beginning at the lowest LBNs available on
the disk. DSC will write the primary file header and its contents and
associated file extension headers and the extensions they map,
as a
unit to a contiguous series of blocks. Note that the output disk
contains an index file of the same size as the original disk. This is
especially important when the contents of a large disk (such as an
RP04) are restored to a smaller disk (such as an RKOS) or vice versa.

11-25

DISK SAVE AND COMPRESS (DSC)
Compression of files in this manner is beneficial when a file header's
retrieval pointers are almost used up. Because DSC rearranges a disk
so that contiguous blocks are allocated to a single data file, the
number of retrieval pointers required to map the location and length
of the file contents can be significantly reduced.
DSC can also
reduce the number of file extensions and extension headers.
Note that when DSC writes to a disk, it begins writing data into the
lowest block possible. Free blocks generally have higher LBNs and are
in a contiguous section of the disk.
The data presently on the disk is overwritten by the new data.
Therefore, you cannot use DSC to transfer the contents of several
small disks to a single large disk. Each copy operation eliminates
whatever previously occupied the disk.
In summary, to transfer data to a disk, DSC:

11.9

Verifies that the disk is online.

Verifies that the disk has an up-to-date bad block descriptor
or that bad blocks are specified manually (through the
/BAD=NOAUTO switch). Displays a warning message if no bad
block information is available and the BAD switch was not
specified.

Verifies that the disk has enough free blocks to contain
the data to be transferred.

all

Creates index and directory files (in the first part
disk).

the

Writes the data from a buffer.

DSC MESSAGES

DSC notifies you of fatal error conditions as well as less serious
conditions that could cause difficulties in DSC operations. Each
message generated by DSC has the prefix DSC--, and each is identified
by a numeric code.
DSC messages are printed on your terminal in either a long or a short
form:
online DSC prints the long form and stand-alone DSC prints the
short form. You can determine the meaning of the short form message
from the number provided with the message. The text accompanying the
long form message of that number explains the error.
For example, specifying a tape in the wrong
following message in long form from DSC:
FATAL *** 17 OUTPUT TAPE MMl:
The same error generates
stand-alone DSC:
FATAL

the

following

the

short

form

letter

codes

used

message

*** 17 - MMl

11-26

generates

NOT ANSI FORMAT

Table 11-8 is a quick reference to the single
General messages and in I/O messages.

rQUj

format

.. I

~~·.·....
"'····.···

DISK $AVE AllD COMPRESS (DSC)
Table 11-8
General Error and I/O Error Message Codes
T'ype of
Code

Symbol

G:eneral
Error
Miessage

Code A
Code B
Code C
Code D
Code E
Code F

Failed to read storage map header
Input data out of phase
Nondata block encountered
Input file out of phase
File attributes out of phase
File header out of phase

I/O
E:rror
Message

Reading index file bit map
Reading index file header
Reading storage bit map
Reading boot or home block
Reading file header
Input (or output device)
Writing index file bit map
Writing storage bit map header
Reading input device
In input tape labels
Reading file attributes
Reading file header
Reading index file data
Reading summary data
Writing file header

Meaning

E
F
G

H
I
J
K
L
M
N
0

11.9.1

DSC Messages: Text, Explanation, and Corrective Action

The following are the messages DSC can return.
1

UNDEFINED ERROR
Ex1>lanation:
error.

DSC

encountered

unidentifiable

User Action: First, retry the operation.
submit a Software Performance Report.
2

CONFLICTING DEV.

TYPES

Explanation:

illegal

combination

internal

If error

persists,

device

types

was

spc~cified.

User Action:
Check for typographical errors in
device
abbreviations:
make sure that the disks and tape drives are
not specified on the same side of the command string.
3

MIXED TAPE TYPES
Explanation:
Two different types
specified in the command string.
User Action:
tape drive.

tape

drives

were

Reenter the command, specifying only one type of

11-27

DISK SAVE ARD COMPRESS (DSC)
4

ILLEGAL SWITCH
Explanations The command string was entered
that cannot be used with that command.
User Action:
specified.

Reenter the command with only

with

correct

switch
switches

FILE LABEL TOO LONG
Explanation:
A file label consisting
alphanumeric characters was specified.
User Action:

than

Retry the operation with a shorter file label.

SYNTAX ERROR

Explanation:

An error occurred in the command string format.

User Action:

Reenter the command in the right order.

DUP.

DEV.

NAME;

Explanation:
the command.

The same device was entered more

than

once

User Action:
once.

Reenter the command, specifying each device only

TOO MANY DEV'S

Explanation: More than the legal number
specified on one side of the command line.
User Action: Reenter the command,
eight devices per side.
9

DEV.

XXn:

specifying

devices

were

than

NOT IN SYSTEM

Explanation: The specified device is not present
configuration of the operating system being used.

the

User Action: Check the device identifier that was entered
the command string. Reenter the command.

DEV.

XXn:

NOT FILES-11

Explanation: The specified input device is not formatted as a
FILES-11 device.
User Action: Check the input device to ensure it is
desired, and reenter the command.

the

one

11-28

!!Siii¢

DISK SAVE ARD COMPRESS (DSC)
11

BAD BLOCK SYNTAX ERROR

Explanations

A syntax error occurred when bad block data
manually entered.

User Actions

Check the command that was entered, and

was

reenter

it.
12

BAD BLOCK COUNT TOO LARGE

Explanations

Too many bad blocks were manually entered

single group.

User Action:

Check the blocks being entered.
If possible,
enter several small groups instead of one large group.

BAD BLOCK CLUSTER OUT OF RANGE

Explanation:

A manually entered bad block
blocks does not exist on the output disk.

bad

entered,

and

not

the

point

and

The specified tape is full, and files cannot
appended to it.

User Action:

Check the numbers of
reenter the command.

OU'.rPUT TAPE XXn:

the

group

blocks

NOT AT BOT

Explanation:

The specified continuation tape is
Beginning of Tape (BOT).

User Action:

Remount or reset the
reenter the command.

ou·rPUT TAPE XXn:

tape

load

FULL

Explanation:
User Action:

Change the output tape, and reenter a command to
begin a new tape set.

OUTPUT TAPE XXn:

NOT ONLY REEL IN SET

Explanation:

The Append switch was used with a tape that
not the first tape of a set created by DSC.

was

User Action:

command

(see

Explanation:

switch

was

User Action:

the

Change

tapes,

and

reenter

the

message 15).
17

TAPE XXn:

NOT ANSI FORMAT
OUTPUT TAPE

If device is an output tape, the AP
specified and tape is not in ANSI format.

Reenter the command and either omit
switch to write the specified tape or change tapes.

11-29

DISK SAVE AND COMPRESS (DSC)
INPUT TAPE
Explanation: If device is an input tape, the tape is not in
the correct format for a DSC operation (that is, the tape was
not created by DSC).
User Action: Check the tape
Reenter the command.
18

OUTPUT TAPE XXn:

and

change

it,

necessary.

NOT DSC TAPE

Explanation: An Append switch was specified with a tape
was not created by DSC.
User Action: Reenter the command and either omit
switch or change to a DSC-created tape.
19

TAPE XXn:

the

that
Append

A CONTINUATION TAPE

Explanation: If device is an input tape, the tape was mounted
out of sequence is not the first of a set.
User Action: Reenter the command, and specify input tapes
the proper order.
21

FAILED TO FIND HOME BLOCK
Explanation: DSC failed to find the home block on the input
disk.
Either the disk is bad, the home block is bad, or the
disk is not in FILES-11 format.
User Action: Check the disk in question,
possible, and reenter the command.

FILE STRUCTURE LEVEL ON xxn~

change

drives

NOT SUPPORTED

Explanation: The device is not a Files-11 Structure Level One
disk, and, therefore, cannot be used.
User Action:
23

Replace the device and retry the operation.

I/O ERROR A ON XXn:
(Additional error information)

Explanation: The I/O error indicated explains why
file bitmap on the device could not be read.

the

index

User Action: Retry the operation after correcting
of the error on the device if possible.

the

cause

I/O ERROR B ON XXn:
(Additional error information)
Explanation: The I/O error indicated explains why the index
file header on the device could not be read. The specified
file is lost.
User Action: Retry the operation after correcting
of the error on the device if possible.

the

-~
,-!,

cause

11-30

li!r•u: !!

2 41

J I

p;z:

DISK SAVE ARD COMPRESS (.DSC)
25

CODE A
Explanation: The file header for the
cannot be read.

storage

bit

User Action: The disk is unusable and, therefore,
copied. Replace the disk and reenter the command.
26

map

file

cannot

I/O ERROR C ON XXn:
(Additional error information)
Explanation: The I/O error indicated explains the error
occurred when DSC read the specified file.
User Action:

that

Retry the operation.

I/O ERROR D ON XXn:
(Additional error information)
Explanation: The I/O error indicated explains the read error
that occurred when DSC read the home or boot block of the
disk.
User Action:

Retry the operation on a new drive.

I/O ERROR E ON XXn:
file id
(Additional error information)
Explanation: The I/O error indicated explains the error
occurred when DSC read the specified file header.
User Action:

that

Retry the operation.

INPUT DEVICE XXn:

fileid, Y, Y NOT PRESENT

Explanation: The specified file does not have a file
in the index file;
therefore, the file is not copied.

header

User Action:
This is a warning only.
If desired,
operation can be retried on a different disk drive.
33

INPUT DEVICE XXn:

file id Y, y IS DELETED

Explanation: The specified file was partially deleted on
input disk and was not copied.
User Action:
34

This is a warning only.

INPUT DEVICE XXn:

the

No action is required.

FILE ID Y, Y UNSUPPORTED STRUCTURE LEVEL

Explanation: The specified input disk is
Structure Level One disk and cannot be used.
User Action:

the

not

FILES-11

Replace the disk and retry the operation.

11-31

DISK SAVE AND COMPRESS (DSC)

INPUT DEVICE XXn:

FILE ID Y, Y FILE NUMBER CHECK

Explanation: An incorrect file header
causing the specified file to be lost.
User Action:

from

disk,
....

header

contents

caused

the

Retry the operation.

INPUT DEVICE XXn:

FILE ID Y, Y SEQUENCE NUMBER CHECK

Explanation:

The sequence number is incorrect.

User Action:

Retry the operation and/or replace the disk.

INPUT DEVICE XXn:

FILE ID Y, Y SEGMENT NUMBER CHECK

Explanation: The linkage connecting file segments was broken;
the specified file is lost.
User Action:

Retry the operation.

DIRECTIVE ERROR error number
Explanation: An internal error occurred, usually
of a system overload.
User Action:

the

result

Retry the operation.

I/O ERROR F
(Additional error information)
Explanation:
The I/O error indicated explains that
an
uncorrectable read/write error occurred on the specified input
or output device.
User Action: This message is a warning only.
No action is
requi~ed
unless another error message is displayed.
If
another error message is displayed, correct the cause of the
error and reenter the command.

·····''··

,...

• . .

FILE ID, Y, Y FILE HEADER CHECKSUM ERROR

Explanation:
Incorrect file
specified file to be lost.

read

Retry the operation.

INPUT DEVICE XXn:

User Action:

was

I/O ERROR I on XXn:
File ID Y, Y VBN Z, Z
(Additional error information)
Explanation: An I/O error occurred, which resulted in bad
data being read from the specified virtual block number of the
indicated file on the indicated device.
User Action: This a warning message only. You should examine
the block specified to determine the extent of the error.

11-32

DISK SAVE ARD COMPRESS (DSC)
42

VERIFICATION ERROR ON XXn:
FILE ID Y, Y, Y virtual block number

z, z

Explanation:

The input and output devices
verification operation did not match.

specified

User Action:· This is a warning message only.
is necessary.

No user

for

action

BAD DATA BLOCK ON XXn:
FILE ID, Y, Y, Y VBN Z, Z

Explanation:

A parity error occurred when DSC copied the
contents of a block from a disk. The block specified on the
output disk contains erroneous data.
the data
User Actions When the copy operation is completed,
contained in the specified block should be examined and
corrected.
44

MOUNT REEL x ON XXn:

Explanation:

AND HIT RETURN

This is an instruction only.

User Action:
Mount the volume number requested on the
specified tape drive and enter a carriage return when ready.
45

STARTING VERIFY PASS

Explanation:

The copy operation is complete and DSC is
beginning the verify operation (specified with the VE switch).

User Action: This is an informational message only.
action is required.
46

user

RESUME COPYING

Explanation:

The verify pass (specified with the VE switch)
is complete,
and DSC is continuing the copy operation (if
there is more material to copy).

User Action: This is an informational message only.
action is required.
47

XXn:

IS WRITE LOCKED.

Explanation:

user

INSERT WRITE RING AND HIT RETURN.

The indicated device is write-locked.

User Action: Make sure the device is the
write-enable it, and enter a carriage return.
48

INPUT FILE ON XXn:

one

you

want,

WILL BE RESYNCHRONIZED

Explanation:

The tape position was lost while DSC was reading
the input tape. The file specified in the message, as well as
some subsequent files,
may be lost.
DSC
may
display
additional error messages.

User Action:

Retry the operation from the beginning.
11-.33

DISK SAVE AND COMPRESS (DSC)

OUTPUT DEVICE XXn:
FILE ID Y, Y, Y

FULL

Explanation: The specified device cannot accommodate the
indicated contiguous file in a contiguous set of blocks~ This
may mean that there is an inconsistency in the input tapes.
User Action:
output disk.

Reenter the command,

OUTPUT FILE HEADER FULL ON XXn:

using

less

fragmented

x, FILE ID Y, Y, Y

Explanation: Too many bad blocks on the output disk have
caused the generation of more retrieval pointers than can be
stored in the header(s) of the file. The copy operation on
the specified file is aborted and DSC copies the next file to
the input volume.
User Action: After DSC completes the copy operation, use PIP
to delete the unusable file on the output volume and to copy
the file from the input volume to the output volume.

If the original operation included the Verify switch, this
error will cause many errors to be flagged during the verify
operation. To avoid this, abort the DSC operation and reenter
the command without /VE.
Then go through the procedure
outlined above. After you copy the invalid file with PIP, you
can use DSC with the Compare switch to verify the new disk.
51

OUTPUT FILE HEADER ON XXn:

Explanation: Space for the specified
allocated. The file is lost.

file

Retry

User Action:
required.

NOT MAPPED - FILE ID Y, Y, Y

the

operation;

header
new

disk

was

not

may

I/O ERROR G ON XXn:
(Additional error information)
Explanation: The I/O error indicated explains the error
occurred while DSC was writing the Index File Bitmap.
User Action:

that

Retry the operation.

FAILED TO READ FILE EXTENSION HEADER ON XXn:

FILE ID Y, Y, Y

Explanation: When copying from the input disk, DSC searched
for an extension header, but did not find one. The remainder
of the specified file was lost. A problem may exist with the
input disk, or a preceding I/O error may have caused an
inconsistency.
User Action:

Retry the operation.

11-34

2 I II

I JU

;we::

DISK·SAVE AND COMPRESS (DSC)
54

FAILED TO ALLOCATE HOME BLOCK
Explanation:
The home block cannot be created on
specified disk device because it has too many bad blocks.
User Action:

Replace the disk and reenter the command.

INDEX FILE ALLOCATION FAILURE
Explanation:
Too many bad blocks
allocation for the specified file.
User. Action:

the

exist

the

allow

Replace the disk, and reenter the command.

OUTPUT DISK XXn:

IS NOT BOOTABLE

Explanation:
tape is bad.

Logical block number O of the specified disk

User Action:

This is a warning only.

No action is required.

INVJ\LID BAD BLOCK DATA
Explanation:
invalid.

The

bad

block

data

the

output

disk

User Action: Run the BAD utility on the disk and manually
enter bad block data, or reenter the command specifying
another disk.
58

BAD BLOCK FILE FULL
Explanation:

Too many bad blocks exist on the output disk.

User Action:

Replace the disk, and retry the command.

NO BAD BLOCK DATA FOUND
Explanation:
output disk.

No bad

block

data

exists

for

the

specified

User Action: If bad block data is not desired, ignore the
message.
Otherwise, run the BAD program on the disk;
manually enter bad block data; or reenter the command, using
a new disk.
60

OUTPUT DEVICE XXn:

IS A DIAGNOSTIC PACK.

DO NOT USE IT!

Explanation: The specified output disk is a diagnostic
and cannot be used.
User Action:
command.

Mount

new

output

11-35

disk,

and

reenter

pack,
the

DISK SAVE AllD COMPRESS (DSC)
61

CODE B ON XXn:
FILE ID Y, Y, Y VBN Z, Z
Explanation: The tape position was lost when DSC read
virtual block number specified. Some data may be lost.

the

User

Determine the extent of the
error.
If
Action:
necessary, try the tape on another drive, or create another
tape.

CODE C ON XXn:
FILE ID Y, Y, Y VBN

Explanation: The tape position was lost when DSC read the
data file specified. Data beyond the VBN mentioned is lost.

User Action:

Recreate the tape, or retry the operation
different tape drive.

CODE D ON XXn:
FILE ID Y, Y, Y EXPECTED P, P, P FOUND Y

Explanation: The tape position was lost while DSC read the
tape specified in the message. All of "Y, Y, Y" and some of
"P, P, P" are lost.

User Action:

Retry the entire operation.

FAILED TO MAP OUTPUT FILE ON XXn:
FILE ID P, P, P VBN Z, Z

Explanation: An inconsistency occurred when DSC was writing
the specified file to output disk. The file header did not
specify the correct number of virtual blocks required to write
the file and the file is lost.

User Action:
65

Retry the operation.

OUTPUT DISK XXn:

IS TOO SMALL -- nn BLOCKS NEEDED

Explanation:
The output disk is not
accommodate the data to be transferred.

User Action:

large

enough

Retry the operation, specifying a larger

output

disk.
66

I/O ERROR C ON XXn:
(Additional error information}
Explanation: The I/O error indicated explains the error
occurred while DSC was reading the storage bitmap.

User Action:

that

Retry the operation.

11-36

::u as:

)iii I

DISK SAVE ARD COMPRESS (DSC)
67

I/O ERROR H ON XXn:

Explanations The message that follows explains the I/O error
that occurred while DSC was writing the header of the storage
bitmap file.
User Action:
68

Retry the operation.

I/O ERROR J ON XXn:
(Additional error information)

Explanation: The I/O error indicated explains the error that
occurred when DSC was reading the tape labels on the specified
device.
User Action:
69

Retry the operation on a different tape drive.

INPUT TAPE ON XXn:

MUST BE AT BOT

Explanation: The specified tape must be at Beginning of Tape
(BOT).
This message is also displayed during a Verify
operation, to indicate that the current volume is rewinding to
enable the verify pass.
User Action: If /VE was not specified,
remount at BOT.
70

check

tape

and

WRONG INPUT TAPE ON XXn:
EXPECTING file id, FOUND file id

Explanation:

The input tapes were specified out of sequence.

User Action: Check the tapes, and. reenter
order after receiving mount instructions.
71

the

.CODE E ON XXn:

AFTER FILE ID Y, Y,

them

proper

Explanations This is the result of a read error from tape.
When trying to read an attribute block, DSC accessed some
other block. The file following the file specified in the
error message is lost.
User Action:
72

Retry the operation.

I/O ERROR K ON XXn:
AFTER FILE ID Y, Y, Y
(Additional error information)

Explanation: The message that follows explains the I/O error
that occurred while DSC was reading the attributes of the
specified file.
User Action:

Retry the operation.

11-37

DISK SAVE AND COMPRESS (DSC)
I/O ERROR L ON XXn:
AFTER FILE ID Y, Y, Y
(Additional error information)

Explanations The message that follows explains the I/O error
that occurred while DSC was reading the file header from tape.
User Actions
74

Retry the operation.

INPUT TAPE XXn:

RESYNCHRONIZED AT FILE ID Y, Y, Y

Explanations The tape position has been recovered.
preceding the file specified was lost.

Some data

This message is usually received with one or more error
messages, all indicating that the input tape was either read
incorrectly or recorded badly.
User Actions
reinitiated.

The tape should be re-created and the

operation

TAPE FILE filelabel NOT FOUND

Explanation: The input tape specified does
file identified as "filelabel."

not

contain

the

User Action: Check the file label and the tape, reenter the
command when the correct tape and file label are specified.
76

EXPECTED EXTENSTION HEADER NOT PRESENT ON XXn:

FILE ID Y,

Explanation: A required file extension header
found on the tape being read.

could

not

User Action: If the error message was preceded by one or more
I/O warning messages, the operation should be retried. If
not, the input tape is bad and should be regenerated.
CODE FON XXn:

AFTER FILE ID Y, Y, Y

Explanation: This is the result of a read error from tape.
When trying to read a file header, DSC accessed some other
block type. The file following the file specified in the
error message is lost.
User Action:
78

Retry the operation.

I/O ERROR M ON XXn:
(Additional error information)

Explanation: The message following the device
why the Index File data could not be read.
User Action:

name

explains

Retry the operation.

11-38

22$

ssa

DISK SAVE AllD COMPRESS (DSC)
79

INDEX FILE DATA NOT PRESENT
Explanation: When reading the input tape, DSC accessed a file
oth4H than the index file,
due to a tape error or an I/O
error.

User Action:
diff~rent

Re-create the tape, or retry the same tape on
tape drive.

I/O ERROR N ON XXn:
(Additional error information)
Explanation: The message explains the I/O error that occurred
while DSC was restoring the index and storage bitmap files
from the specified input tape.

User Action:

Retry the operation,

using

different

input

tape drive.
81

VOLUME SUMMARY DATA NOT PRESENT
Explanation: Either DSC did not create the input tape or
tape contains incomplete data.

Use:r Action:
82

the

Check the tape and reenter the command.

I/O ERROR 0 ON XXn: - FILE ID Y, Y, Y
(Additional error information)
Explanation: The message explains the I/O error that occurred
while DSC was writing the specified file header.

User Action:
83

Retry the operation.

BAD BLOCKING FACTOR
Explanation; The specified blocking factor is too
the current operating system.

User Action:

large

for

Specify a smaller blocking factor and repeat the

command.

11.9.2

DSC I/O Messages

In online and both stand-alone versions of DSC, errors identified as
I/O errors are accompanied by one or more of the following messages
which explain the type of I/O error that occurred.
*BAD BLOCK NUMBER
Explanation: The block does not
internal DSC error has occurred.

exist

the

disk;

*BAD BLOCK ON DEVICE
Explanation: A bad area was encountered on the device,
resulting in a block that cannot be read or written without
error.

11-39

DISK SAVE AND COMPRESS (DSC)

BLOCK CHECK OR CRC CHECK

Explanation: A parity error occurred indicating that bad data
may have been transferred.
User Action:

Retry the operation.

DATA OVERRUN

Explanation: A physical block on
than were requested.

tape

contains

bytes

*DEVICE NOT READY

Explanation:

The device is not ready or not up to speed.

DEVICE OFFLINE

Explanation:

The device is not in the system.

User Action: Check the device, the device specification
the command string, and reenter the command.

.~
..

I r

DEVICE WRITE LOCKED

Explanation:

The disk drive is write locked.

User Action:
command.

Write enable the

disk

drive

and

reenter

the

END OF FILE DETECTED

Explanation:

The tape position was lost.

User Action:

Retry the operation.

END OF TAPE DETECTED

Explanation:

The tape position was lost.

User Action:

Retry the operation.

END OF VOLUME DETECTED

Explanation:

The tape position was lost.

User Action:

Retry the operation.

FATAL HARDWARE ERROR

Explanation:

A hardware malfunction occurred.

User Action: Retry the operation:
field service.

if the error repeats, call

HANDLER NOT RESIDENT

Explanation:

The device driver (handler) was not loaded.

User Action:
operation.

Load the appropriate device driver and retry the

11-40

hh!U!ii

I!!

.4"' Si

DISK SAVE. AllD COMPRESS (DSC)
INSUFFICIENT POOL SPACE
Explanation:

The operating system is overloaded.

User Action:

Retry the operation.

PARITY ERROR ON DEVICE
Explanation:

An uncorrectable read error occurred.

User Action:

Retry the operation.

PRIVILEGE VIOLATION
Explan~tion:

A device was mounted as Files-11 or is allocated
to a different user.

User Action:
RSX·-llM/M-PLUS
operation.

Users:

Dismount

the

disk

IAS Users: Dismount the disk, mount it as
and retry the operation.

and
a

retry

foreign

the
device

ERROR CODE IS <driver code>
Explanation:
occurred.

I/O

error

which

DSC

cannot

error

code

and

translate
retry

the

Explanation: Tapes on drives have not been rewound since
system was booted.

the

Use:r Action:
Translate
operation, if possible.

the

ILLEGAL FUNCTION

User Action:
DSC command.

11. 9 .• 3
~;

Rewind the tapes, using the Rewind switch

versions

Stand-Alone DSC Messages

The j:ollowing messages appear only with the
DSC.

stand-alone

ILLEGAL VECTOR ADDRESS
Explanation:

An illegal vector address was specified.

User Action: Correct the vector specification and reenter the
command.
Vector addresses must be a multiple of 4 and less
than or equal to 374(8).
INVALID CSR ADDRESS
Explanation: A system trap occurred when
address was referenced.
Use.r Action:

the

specified

Correct the address and reenter the command.

11-41

CSR

DISK SAVE AND COMPRESS (DSC)
INVALID TM02 ASSIGNMENT
Explanation: The TM02 switch applies only to TU16/TE16/TU45
tapes and cannot specify an assignment greater than seven.
User Action:

·~.#?\..·.

Correct the error and reenter the command.

SPECIFIED UNIT NUMBER EXCEEDS MAX.

OF 1

Explanation: The stand-alone version of DSC does
unit numbers greater than 1.
User Action: Correct the error and
Specify the Unit switch if required.

reenter

not
the

accept
command.

11-42

•..

·~ 1•1••••••••••z•t•••••••••••--••-••••••••••••••••••••••••••a•;•a,,.a

CHAPTER 12
VOLUME PRESERVATION UTILITY (PRESRV)

12.1

INTRODUCTION TO PRESRV

The PDP-11 Volume Preservation Utility (PRESRV) is a stand-alone
program that allows you to create copies of volumes. PRESRV copies
volumes to and from the following device types:
•

Disks (only those specifically indicated in Table 12-4)

•

Magnetic tapes

•

DECtapes

•

Cassette tapes

PRESRV is most often used to preserve a system disk or master disk for
backup purposes, usually on magnetic tape or another disk. Unlike BRU
and DSC, PHESRV copies bad blocks. Tapes used by PRESRV to restore a
disk must be the result of a PRESRV copy from disk.

'-'I

PRESRV creates copies in three formats:

• Files-11

• Logical tape
• Image
F iles-11 format saves only those blocl(S that have
them.

'-'I

data

allocated

Logical tape format creates real or quasi-magnetic tape output.
Logical tape format also puts a copy of PRESRV on the backup volume,
so PRESRV can subsequently be bootstrapped from that volume.
Image mode

format

saves

all

blocks

the

disk,

regardless

allocation~

12.1.l

Files-11 Format

Files-11 format is a file structure that applies only to disks and
DECtapes.
When PRESRV is copying in Files-11 format, only blocks
containing user data or Files-11 control information, called allocated
blocks, are saved. Allocated blocks of the input volume are copied to
identical output blocks of the output volume, and the remaining blocks
of
the
output
volume
remain unchanged.
Normally disks are
read/writtErn in Files-11 mode except as described below.

12-1

VOLUME PRESERVATION UTILITY (PRESRV)
Input: To override a Files-11 format, specify the /TP switch for a
logical tape for~at or the /IM switch for an image mode read. The /TP
and /IM switches are described in Sections 12.3.2.2 and 12.3.2.3,
respectively.
If the input and output devices are of an identical device type and
neither a switch nor a file name are specified (DKO:=DKl:}, PRESRV
performs an image mode copy.
Image mode is described in Section
12.1.3.
Output: If the input is in logical tape format, and the output device
is a disk, the resulting output will be in Files-11 format. However,
the /TP switch may be used to override this default (see Section
12.3.2.2).
If the input and output devices are of the identical
device type and you do not specify a switch or a file name, PRESRV
defaults to an image mode copy. To override this default, specify
either /TP or /FI for output in logical tape or Files-11 format,
respectively.
If the input is a disk in Files-11 format and the output is a disk of
a different device type, the output disk will be written in logical
tape format (DP:NAME[/TP=DK:). In this case only a file name is
required.
If you wish output in Files-11 format, specify /FI on the
output side of the command line to override the logical tape default
(DP : /FI =DK : } •
NOTE
When the output volume is in Files-11
format and is larger than the input
volume, the Files-11 control information
copied on the output volume makes it
appear that the output volume has the
same number of blocks as the input
volume. This means that copying a small
disk to a large disk (for example, an RK
to an RP) in Files-11 format results in
a loss of capacity on the larger volume.
Conversely, when the input volume is
larger
than the output volume
(for
example, an RP to an RK), the copy may
fail if an attempt is made to copy to
blocks that do not exist on the smaller
volume.
A Files-11 copy from disk or DECtape is limited to a single input
volume per copy command. Similarly, a Files-11 copy to an output disk
or DECtape is also limited to a single output volume per copy command.

12.1.2

Logical Tape Format

PRESRV writes information in logical tape format or magnetic tapes and
cassettes when the input device is a disk. PRESRV also writes in
logical tape format when the input and output devices are different
types of disks. When the input and output disks are of the same type,
PRESRV defaults to an image mode copy unless you specify the /TP
switch to copy in logical tape format.
When a logical tape copy is to be produced, the output side of the
command string must include a file name, to identify the file created
by the copy operation.
12-2

·1~111-

I ii I

Ill

VOLUME PRESERVATION UTILITY (PRESRV)
When the input volume is magnetic tape or cassette, PRESRV assumes
logical tape format by default, unless the copy is to be made to a
device of the same type as the input device. When the input volume is
either disk or DECtape, logical tape format is recognized only when
the /TP switch is specified on the input side of the command string.
Otherwise, the input is assumed to be Files-11.
The following examples illustrate the concepts discussed above.
PRE>MTO:URFILE=DPO:
I

In this example, DPO: is read in Files-11 mode (/TP was not specified
on input).
The information is written on MTO: in logical tape
format, as a file named URFILE. The output can occupy more than one
magtape volume.
PRE>DTO:FILA=DKO:
In this example, DKO: is read in Files-11 format. The information is
recorded on DTO: in logical tape format, as a file named FILA. FILA
can occupy more than one DECtape.
NOTE
A logical tape copy (disk or magnetic
tape) can occupy more than a single
volume. A logical tape copy on magnetic
tape can also contain copies of more
than one disk. However, a new copy of a
disk volume can not begin on any magtape
volume other that the first.

12.l.3

Image Format

Image format is used to copy all physical blocks of
volume, regardless of content, to an output volume.

single

input

Image format transfers occur if the input and output devices are the
same type and no other copy format is in effect. In other words, no
format switches (for example, /FI or /TP) are specified, and no file
name
is specified on the output side of the command string.
(Specifying a file name on the output side of the command string
implies logical tape format.) For example:
PRE>MTO:=MTl:
NOTE
When executing an image format copy
between
two magtape devices, PRESRV
checks to ensure that both devices are
on-line before beginning the copy. If
these checks fail, the operation will be
aborted with the message
DEVICE OFFLINE

12-3

VOLUME PRESERVATION UTILITY (PRESRV)

When EOT is sensed from the output tape, PRE sets up a counter to
permit five additional blocks to be written on the output tape.
However, each time an EOF is sensed on the input tape, the counter is
reset to allow an additional five blocks to be written on the output
tape following the EOF block.
After writing five blocks beyond EOT on output, or after EOF has been
sensed on input and the output tape is already beyond EOT, PRE will
issue a fatal error message and prompt for a new command:
FATAL ERROR ON OUTPUT DEVICE
PRE>
In some cases, it may be desirable to force a transfer in image format
from disk or DECtape to a device of a different type. To do this,
specify the /IM switch on the input side of the command string.
For
example:
PRE)MTO:TOMl=DKO:/IM
As a result of this command, a logical tape file named TOMl is created
on MTO:. TOMl contains all the physical blocks of DKO:.
NOTES

12.2

This type of command is limited to
one input volume.

just

It is illegal to specify the /IM
for magnetic tape input.

switch

PRESRV OPERATING PROCEDURES

Because PRESRV is a stand-alone program, it is convenient to bootstrap
a preserved volume to get PRESRV into memory. When PRESRV copies in
logical tape format, it places the following information on the first
output volume:
a label block, a bootstrap block, and an image of
PRESRV. After the bootstrap operation, the tape is positioned between
the image of PRESRV and the data to be preserved. See Figure 12-1.
NOTE
When the output device is a magnetic
tape
and the first copy is to be
created, the tape must be on-line and at
load point (BOT} for a valid bootstrap.
Otherwise, PRESRV will write a dummy
bootstrap and the tape will not be
boot able.
Bootstrapping the first volume of a logical tape brings into memory a
stand-alone system with a running version of PRESRV.
(See the CAUTION
in Section 12.2.1.} You can then type a command string to perform any
desired PRESRV function.

I 'i

12-4

C!i! 212!$

sq: :um: : :: : ca

ii. ii

:u::u

VOLUME PRESERVATION UTILITY (PRESRV)

LABEL BLOCK

800 BPI

BOOTSTRAP BLOCK

800 BPI

PRESRV IMAGE

800 or
1600 BPI

DATA

End of File
Indicator

1256 words

LABEL BLOCK

1256 words

xx words

DUMMY BOOTSTRAP
BLOCK

800
or
1600
BPI

DATA

LEOT
or
EOV

EOF

800 BPI

800
BPI

multiple
labels are
allowed on
first volume

I
SUBSEQUENT
VOLUME(S)

DUMMY BOOTSTRAP
BLOCK

'-'.·

800 or
1600 BPI

Logical
End of Tape

End of
Volume

DATA

EOF

EOV
FIRST VOLUME

Figure 12-1

Logical Tape Format

12-5

Only one label
allowed on subsequent volumes.
(Must be continuation of file
started on first
volume.)

VOLUME PRESERVATION UTILITY (PRESRV)

To create a volume from which PRESRV can be bootstrapped, specify a
copy operation from one type of device to another type of device. For
example:
PRE>DTO:PRESRV=DKl:
The copy operation can be stopped before it is complete, because the
necessary bootstrap information will have been copied into the first
few blocks of the resulting logical tape.

12.2.1

Bootstrap Procedure

To run PRESRV, mount the device to be copied and bootstrap the device
on which PRESRV is recorded. Bootstrapping is accomplished by either
setting the correct address in the console register, loading the
address, and then depressing the START switch; or using the RSX-llM
BOO command (on an RSX-llM system). The BOO command begins a software
bootstrap operation.
There are many different methods of initiating
operation, each of which is system depe.ndent.
For
details
documentation.

bootstrap

procedures,

hardware

consult

your

bootstrap
system

When PRESRV is bootstrapped, it displays an identification message
the form:

RSX-115 Vxx
VOLUME PRESERVATION PROGRAM- Vyy
FOR HELP TYPE /HE
nn. BLOCKS AVAILABLE FOR BUFFERING

""'
. I -t

PRE>
PRESRV is built as a task running under the RSX-115 Executive and thus
displays the version of the stand-alone executive in use, the version
number of PRESRV, and the number of 256-word blocks (nn.) available
for buffering.
You must use the number of blocks available for
buffering (displayed in the identification message) to determine if a
given PRESRV media copy has sufficient buffering space.
If the total space required for input, output and verification
(optional) buffers is greater than nn. blocks, PRESRV responds with
the following message:
INSUFFICIENT BUFFER SPACE
Change the blocking factor(s) and retry the operation.
The number of blocks available for buffering should be kept in mind
when using the blocking switch (/BL) described in Section 12.3.2.4.
An error message is issued if the combined blocking factors for the
input and output volumes exceed the number of blocks available.

12-6

as 2!2ll;

f4 as

VOLUME PRESERVATION UTILITY (PRESRV)

CAUTION
PRESRV contains predefined
CSR
and
vector addresses for devices. If these
addresses differ from those established
in
your system, or if your system
includes TU16 9-track magtapes (instead
of TUlO-type tapes) or RP04/06 disks
(instead of RP02/03 disks) you must
modify
PRESRV's
standard
device
information. See Section 12.3.5 for a
summary
of PRESRV's CSR and vector
addresses.
To tailor PRESRV to conform
to
a
specific system, bootstrap the standard
version of PRESRV into memory and then
use the /CSR, /VEC, and /TM02 switches,
described
in
Sections
12.3.5.1,
12.3.5.3, and 12.3.5.4 respectively, as
required. Then create a logical tape
copy, which will contain the modified
bootable version of PRESRV tailored to
your system's configuration.
The following example shows how
to
modify in memory the vector address of
an RP04 disk pack to 254.
The vector
address applies to both DBO: and DBl:,
and to
any
other
DB-type
device
reassigned later to either DBO: or DBl:
by means of the /UNIT switch
(see
Section 12.3.5.2).
CSR and TM02 values can
similar fashion.

changed

PRE>DBO:/VEC=254
The next example shows how to create a
bootable image of the above modified
version of PRESRV.
PRE>DTO:ABBA/TP=DKO:
NOTE
This copy operation need not run to
completion, because the first few blocks
on DTO: are sufficient to bootstrap the
tailored version of PRESRV into memory.

12.2.2

Tape Handling

PRESRV supports forms of multifile volumes and multivolume files on
magnetic tape, cassettes, DECtape, and disk. Table 12-1 indicates the
permissible combinations of files and volumes in logical tape format.

12-7

VOLUME PRESERVATION UTILITY (PRESRV)
Table 12-1
Legal Multifile/Volume Format in Logical Tape
Magtape/Cassette

DECtape/Disk

Multiple files on first
volume only. Last file
can extend to second
and succeeding volumes.

One file only, which can
extend to second and
succeeding volumes.

Each file on a magnetic tape or cassette is terminated with an
end-of-file
(EOF) tape mark. A file copied in logical tape format is
prefixed with a file label that identifies the file.
NOTE
Regardless of the device type, PRESRV
records
within
each
file
enough
information to restore
a
disk
in
FILES-11 format and to recognize the end
of the file.

12.2.2.1 Logical Tape Input from Magnetic Tape or Cassette - PRESRV
determines where to begin reading a tape as follows:
If a file label is specified, PRESRV rewinds the input tape and
searches for the file label. If a file label is not specified, PRESRV
assumes that the tape is correctly positioned to read the first file
or next file
(or file segment) of a volume set. To read the first
file of a volume set, without specifying its file label, position the
first volume to Beginning-of-Tape (BOT).
After processing any file, PRESRV positions the tape to read the
file of a set.

When PRESRV reaches the end of a tape volume by sensing two successi~e
EOF tape marks it requests that the next input volume be mounted.
When you mount the next volume, PRESRV assumes the volume is
positioned at BOT. You are responsible for correctly positioning the
tape to BOT, and for assigning the same unit number as the preceding
volume.

12.2.2.2 Logical Tape Output to Magnetic Tape - To write the first
copy of a set to magnetic tape or cassette, position the volume at
BOT. If output is to be stored on two or more volumes of a set, the
first volume mounted must be the first volume of the set.
After a copy operation is finished, PRESRV positions the tape to
record a new file on the current volume by writing two EOF marks and
then backspacing over the second EOF mark. An exception occurs when
the copy ends on a volume that is not the first volume. In this case
only, the backspace does not happen: any file added at that point is
inaccessible to PRESRV.
In the normal process of recording a new
file, PRESRV overwrites the second EOF indicator that marks the
current end of volume.

12-8

1:~111=

Hi it

a; 4¥

"' f4""

VOLUME PRESERVATION UTILITY (PRESRV)
When .PRESRV reaches the end of an output volume, it prints a message
requesting that the next output volume be mounted. PRESRV checks to
ensure that the new tape is at BOT. If npt at BOT, the mount message
is repeated until it is. You must ensure that the volume is correctly
positioned, and assigned the same unit number as the preceding volume.
Time may be saved by pre-mounting magnetic tapes
in the following way:

(except

cassettes),

Pre-mount the next volume on a different unit, and assign it
a different unit number than the current volume's unit
number. Make sure it is positioned to the load point (BOT).

When PRESRV prints the request to mount the next
switch the unit numbers of the old and new volumes.

The old volume can now be rewound as PRESRV processes the new
volume.

volume,

For ciutput to magnetic tape, PRESRV assumes that the volume is
correctly positioned at Beginning of Tape (BOT) initially and after
the EOF tape mark subsequently.
On input from magnetic tape, PRESRV functions differently depending on
whether a file label is specified in the command line. If a file
label is specified, the input volume is rewound and searched for the
named f ileu If no file label is specified, the next file on the tape
is re!ad.
A file can extend across a volume boundary, but no new files can begin
on the second or subsequent volume of a multivolume file.
NOTE
Be sure that tapes are rewound when
PRESRV requests that a new volume be
mounted. All tapes must be mounted, and
assigned the same unit number.

12.2,.3

Disk and DECtape Handling

PRESHV processes disks and DECtapes
sections.

described

the

following

12.2.3.l Input from Disk and DECtape - When disk or DECtape input is
in logical tape format, PRESRV processes as many volumes as necessary
to copy the complete input file. However, when the input disk or
DECtape is in Files-11 or image format, PRESRV processes only a single
input volume.

12.2.3.2 Output to Disk and DECtape ·· PRESRV can record only one file
on a disk or DECtape output volume, regardless of format. This
restriction exists because the first access to a disk or DECtape is to
logical block O.
However, PRESRV can create a single logical tape
copy that extends over more than one volume.

12-9

VOLUME PRESERVATION UTILITY (PRESRV)
When the output volume is disk or DECtape, and Files-11 or image
format is specified or implied, PRESRV prints an error message if more
than one volume is needed.
NOTE
Disks and DECtapes can be pre-mounted by
following
the
general
guidelines
suggested in Section 12.2.2, above.

12.3

PRESRV COMMAND LINE AND SWITCHES

The PRESRV command line has the following format:
outdev: [label]/switchl ••• /switchn=indev: [label]/switchl ••• /switchn
outdev and indev
Specify the physical devices on which the output and input
volumes are mounted, for example, DKO: or DTl:. The device name
consists of two ASCII characters followed by an optional 1- or
2-digit octal unit number 0 through 7. If the unit number is
omitted, O is assumed. The unit number is always O or 1.
The
/UNIT switch must be used to reference units other than 0 or 1.
label
Specifies a label for the file when a volume is written as a
logical tape.
It is used to identify files on logical tapes.
See Section 12.2.2.
The label can consist of up to nine
alphanumeric characters.
A label must be specified when the
output is a logical tape. It is optional for input.
The label
parameter is applicable only for files on a logical tape.

""
. IT

switch
Specifi~s an ASCII name identifying the
switch
Option switches are summarized in Table 12-2.

option

desired.

Table 12-2
Summary of PRESRV Switches
Category
List

Switch

Function

/HE

Causes a summary of PRES RV commands,
switches, and defaults to be printed on
the terminal.

/LI

Causes a list of all files on a
tape
volume
to be printed
terminal.

logical
on the

(continued on next page)

12-10

rw._u 22

I! I

122

a ;;:•

VOLUME PRESERVATION UTILITY (PRESRV)
Table 12-2 (Cont.)
Summary of PRESRV Switches
CatE~gory

Format

Switch

Function

/FI

On input, indicates Files-11 format for
reading a disk volume overriding implied
Image Modeu On output, overrides the
/TP default or implied /IM.

/IM

Indicates image mode;
that is, transfer
all physical blocks of an input disk.
Never used with tape. /IM is used only
on the input side, overriding default
Files-11 mode.

/TP

Indicates a logical tape format output
volume
(which overrides the default
image mode when
device
types
are
identical)o
/TP also overrides the
default Files-11 mode on an input disk.

/BL:nnn

Specifies a blocking factor for I/O
operationso
Octal is assumed; decimal
is indicated by a trailing period (.).
This value applies only to the side of
the command in which it is specified.
If /BL is not specified,
the default
blocking factor is used.
(See Section
12.3.2.4.)

Administrative

/ER

Indicates that the PRESRV operation is
to be terminated if an I/O error occurs.

/RW

Causes a cassette or magnetic
tape
volume
(either input or output) to be
rewound
at
completion
of
PRESRV
operation.
NOTE
PRESRV rewinds only the last volume
of a multi-volume set when it is
completely finished.
Intermediate
volumes must be rewound by the user.

Magnetic

Tc~pe

/VE

Causes the output volume to be
after it is written.

verified

/20

Indicates a recording density of 200 bpi
for
7-track tape.
(Image transfers
only.)
(continued on next page)

12-11

VOLUME PRESERVATION UTILITY (PRESRV)
Table 12-2 (Cont.)
Summary of PRESRV Switches
Category
Magnetic Tape
(Cont.)

Stand-alone
PRES RV

Switch

Function

/55

Indicates a recording density of 556 bpi
for 7-track tape.
(Image
transfers
only.)

/80

Indicates a recording density of 800 bpi
for
7-track tape.
(Image transfers
only.)

/PE

Indicates a recording density of 1600
bpi
(phase encoded). Can be used only
for TE16, TU16, TU45, and TU77 tape
drives.
If /PE is not specified, a
density of 800 bpi is assumed.
Do not
specify /PE for the TM03 formatter.

/CSR

Changes the control status register
a device type.

/UNIT

Sets the physical unit number of either
PRESRV unit O or l to a value from 2
through 7.

/VEC

Changes the interrupt vector address for
a device type.

/TM02

Sets the unit number of the TM02/TM03
formatter on an RH controller for a
specific TU16 magnetic tape unit.

for

·"1'

NOTE
/CSR, /UNIT, /VEC, and /TM02 can all
specified in the same command.

/TIM

Specifies the correct time of
the system.

day

/BO

Causes PRESRV to bootstrap the
from the specified device.

system

NOTE
Only Physical Unit 0 may be booted
with this command if the device is a
disk.
/FO

Indicates that PRESRV is to
output disk pack.

format

the

PRESRV options are specified by means of switches included in the
command string or by stand-alone switches. Switches fall into five
categories according to the functions they perform.

12-12

14•

VOLUME PRESERVATION UTILITY (PRESRV)
u

List switches

•

Format and blocking switches

•

Administrative switches

•

Magnetic tape switches

•

Stand-alone PRESRV switches

12.3.l

List Switches (/BE and /LI)

The list switches are entered one at a time in response to the prompt
(PRE>).
Each switch is processed immediately by PRESRV. /HE obtains
a printed summary of PRESRV commands, switches, and defaults.
/LI
obtains a list of all files of a logical tape volume. If the set
consists of more than a single volume, each of the volumes must be
listed separatelyti
When the designated device is a magtape or
cassette, the /LI switch causes an automatic rewind,
followed by a
listing of the file label and a description of all the files on that
volumie. On magnetic tape, if the two EOF tape marks indicating End of
Information
are sensed before physical EOT, PRESRV performs a
backspace. If the current volume is the first of the set, the tape is
then positioned so that a new file may be added.
The formats of the /HE and /LI switches follow.
PRE>/HE
PRE>dev:/LI

dev:
Indicates the device and unit
mounted.

number

which

the

volume

NOTE:
The /LI switch references only a single
volume.
Since all files contained in a
set of volumes begin on the first volume
of a tape set, listing the first volume
lists all of the files
in the set.
Subsequent volumes will list only their
contents.

12.3.2

Format and Blocking Switches

Format switches specify the format of the input
Three switches specify format.

and

output

Switch

Function

/FI
/IM

Specifies Files-11 format.
Specifies that a disk or DECtape volume is to
in image format.
Specifies logical tape format.

/TP

The /BL switch indicates the blocking factor.

12-13

volumes.

read

VOLUME PRESERVATION UTILITY (PRESRV)

If format switches are not included in the command line,
the following default values:

PRESRV

uses

For the input portion of the command line, tape devices (magnetic and
cassette tape) default to logical tape format, while Files-11 devices
(disk and DECtape) default to Files-11 format.
For the output portion of the command line,
used by default.

logical

tape

format

There are two exceptions:
1.

If the input and output devices have the same device type and
ho format switches are included in the command line, the
transfer is in image mode. The output volume will be an
exact image of the input volume, regardless of the format of
the input volume. Only a single volume will be copied.

If the input volume is being read in logical tape format, and
output is to disk or DECtape, the data portion of the input
file is written into the logical blocks corresponding to the
blocks the data occupied on the volume from which it was
originally copied. Output is limited to a single output
volume.

Default blocking factors are provided with the description of the
switch in Section 3.2.4. Each block is 256 (decimal) words.

"i\

/BL

12.3.2.1 Files-11 Format Switch (/FI) - The Files-11 format switch
(/FI) can be used on either the input or the output side of the
command line.
On the input side, /FI indicates that the input Files-11 volume is to
be read in Files-11 format, overriding a default image-mode transfer.
Only allocated blocks will be transferred.
The /FI switch is particularly useful for input volumes if an image or
logical tape transfer fails due to an unreadable block on a Files-11
device that is being preserved. Because Files-11 transfers result in
copying allocated blocks only, use of the /FI switch results in a
successful transfer if the unreadable block is not allocated.
NOTE
If the input volume is not in Files-11
format,
PRESRV
generates
an error
message.
On the output side, /FI indicates that the output Files-11 volume is
to be written in Files-11 format, overriding a default logical tape
format or implied image mode transfer.
Examples

PRE>DKO:/FI=DKl:/FI
Use of the /FI switches overrides the default for this case, which
an image transfer. A Files-11 copy of DKl: is produced on DKO:.

12-14

z 22 sa

iiliiiiii Lid

it Qt

! II

ICf t

VOLUME PRESERVATION UTILITY (PRESRV)
PRE>DKO:STEVE/TP=DKl:
In this case, DKO: will contain the file labeled STEVE, in logical
tape format.
STEVE will contain only blocks that were allocated on
DK!: •
PRE>DKO:/FI=DT:
Use of the /FI switch indicates that the transfer is to result in DKO:
containing a Files-11 copy of the information on DECtape. The default
for the output for this case is logical tape format.
Using the /FI
switch in this manner is not recommended, because the resulting copy
limits the capacity of DKO:
to 578 blocks (the capacity of the
DECtape).

12.3 .• 2.2

Logical Tape Format Switch (/TP) - The logical

tape

format

switch (/TP) indicates the following:
1.

The input volume is to be read in logical tape format, or

The output volume is to be written in logical tape format.

When the PRESRV input is in logical tape format, the following message
is printed on the terminal.
MOUNT INPUT VOLUME nn AND TYPE <CR>
Mount the physical volume and then press the RETURN key to continue
the PRESRV operation. If the volume is already mounted and correctly
positioned, press RETURN only.

'-''

When the PRESRV output is in logical
message is printed on the terminal.

tape

format,

the

following

MOUNT OUTPUT VOLUME nn AND TYPE <CR>
The user response is the same as in the case of the MOUNT INPUT VOLUME
message.
NOTE
Never use /TP to request that a tape be
read or written in logical tape format
(the fact that the device is a tape
implies logical tape} unless input and
output are both magtapes
NOTE
When
PRESRV
displays
the
message
requesting that a tape be mounted and
the user types <CR> in response, PRESRV
will check to ensure that the tape is,
in fact, on-line. If that check fails,
the message and the subsequent check
will be repeated until the check is
successful.

12-15

VOLUME PRESERVATION UTILITY (PRESRV)
Examples
PRE>DKO:LAB/TP=DKl:
is read in Files-11 mode and is to be preserved in
The volume in DK!:
logical tape format in File LAB on DKO:. Use of the /TP switch
overrides the default (which is an image transfer in this case because
device types are identical). A label must be specified for the copy
file.
PRE>DKl:=DKO:LAB/TP
or
PRE>DKl:=DKO:/TP
The file LAB on DKO:
is in logical tape format, if it is the copy
file created in the previous example. DKO: is now restored on DK!:
in Files-11 mode.
NOTE
When the output format is to be logical
tape and the output device is a disk,
that disk must be physical drive O.

12.3.2.3 Image Mode Switch (/IM) - The image mode switch overrides
the Files-11 default in copying disk-structured volumes. By using the
/IM switch, an operator can copy any disk that is formatted compatibly
with DIGITAL's hardware.
In image mode, every block on the input
volume is copied to the output file.
The image mode switch can also be used to override the Files-11
default, as shown in the first of the following examples. This allows
a logical tape to be used to restore a disk that was originally in any
format compatible with DIGITAL hardware.

Examples
PRE>MTO:AFIL=DPO:/IM
Copy from disk to tape.
PRE>DPO:=MTO:AFIL
Restore disk from tape.

12.3.2.4 Blocking Switch
indicates the following:

(/BL:nn) - The

blocking

switch

(/BL:nn)

The blocking factor to be used when reading a disk or DECtape
volume.

The blocking factor to be used when creating a
or disk or DECtape output volume.

logical

tape

Specify the blocking switch to save time. Use the blocking switch to
request that the specified number of 256-word blocks be read as a unit
from a disk or DECtape, or be written as a unit to either a disk or
DECtape, or be written in logical tape format.

12-16

li!lliiiii

ii $

2i2

4 ill I l

VOLUME PRESERVATION UTILITY (PRESRV)
Note, however, that the label of a logical tape specifies the blocking
factor that was used when the file was created. The /BL switch cannot
be used to override that value when the file is used as input.

\.I

The block in9 switch has the fol lowing :format:
/BL:nn (octal)
or
/BL: nn.. (decima 1)
nn
Indicates the number of 256.-word segments to be written as a
physical block on tape or to be read from or written to disk to
fill or empty the corresponding PRESRV buffer. The value of nn
is limited by the number of blocks available, which is printed
(in decimal) on the terminal when PRESRV is initiated.
/BL can be used on both sides
values need not be identical.

command

line.

The

associated

Each device has a default blocking factor that is used when no
blocking switch is specified and if the buffer space is available to
perform the default blocking. The defaults are shown in Table 12-3.
Table 12-3
Default Blocking Factors
~-·~--·--..,.---------T---------~---,.~--------------------------------~-------

Device

Formatl

Default Block
Size2

Max. Block Capacity
(Dec ima 1)

DK
DF
DP
DS

BS
BS
BS
BS

12.

4800 (RK05 Cartridge Disk)
1024 per platter (RSll Fixed Head Disk)
40000 (RP02), 80000 (RP03) Disk Packs
1024 (RS03) , 2048 (RS04) Fixed
Head Disks
578 (TC11/TUS6) DECtape
167200 (RP04 Disk Pack)
variable TElO or TS03 Magtape
Variable TE16, TUll, TU45, or
TU77
Magtape
variable TA11/TU60 Cassette
494 (RXll/RXOl) Floppy Disk

DT
DB
MT
MM

10.
8.
2.
22.
l.
1.

CT
DX

LT
BS

1.
6.

~---~--_..--~--------~--------~-'-~-------~------~----~------------------'

l BS - Block Structured
LT - Logical Tape

2 Decimal point indicates decimal value.
The defaults provided in Table 12-3 can be overridden by
following means:

any

the

For disks and DECtape, the /BL switch can be used with the
input or output file specifier to establish a blocking
fa<::tor.

For. logical tape output, the /BL
establish the blocking factor.

12-17

switch

can

used

VOLUME PRESERVATION UTILITY (PRESRV)
3.

For magnetic tape image transfers, PRESRV calculates
blocking factor that uses all available buffering space.

NOTES
1.

The /BL switch has no effect when
the input device is a logical tape.
The blocking factor is the same as
that used when the tape was created.

The blocking factor used for disk
type devices should be a submultiple
of the number of blocks on the
volume (for example, 4800 for RK)
when copying in image mode.

Refer to Section 12.4 for the blocking calculations used to match
available buffering space to blocking specifications for a file.
Example
PRE>DKO:/BL:20.=MTO:
Twenty 256-word blocks are transferred in each I/O operation.
Forty
blocks must be available for use in blocking (assuming that the tape
was created with /BL:20).

12.3.3

Administrative Switches

Three administrative switches are provided.
Switch

Function

/ER
/RW
/VE

Aborts the operation if an I/O error occurs.
Rewinds a tape after PRESRV completes.
Compares the output volume(s) created by PRESRV with
volume(s) submitted as input to a copy operation.

the

12.3.3.l Abort on I/O Error Switch (/ER) - If the abort on I/O error
switch
(/ER) is attached to a file specifier, an unrecoverable I/O
error causes the termination of the current PRESRV operation.
After
issuing an error message, PRESRV prints
PRE>
and is ready to accept another command.
The /ER switch applies to either input or output file specifiers.
example:

For

PRE>DKl: /ER=DKO:
If a write error occurs and the /ER switch has
PRESRV responds with the following message:

not

been

specified,

VOLUME FAULTY - "R" TO RETRY, "C" TO CONTINUE>
Type C to continue or R to retry the operation.

12-18

2224

iii

4l I

VOLUME PRESERVATION UTILITY (PRESRV)
NOTE
If you type the ALTMODE key when PRESRV
is ready to accept input, the current
operation is aborted.

12.3.3.2 Rewind at Completion Switch (/RW) - The rewind at completion
switch
(/RW) applies to magnetic tape and cassette tape volumes. It
indicates that the ~olume is to be rewound after PRESRV has completed
the specified transfer.
The /RW switch applies to input and output file specifiers.
NOTE
Only the last volume of a multivolume
input or output set is rewound.

12.3.3.3 Verification Switch (/VE) - The verification switch
(/VE)
causes PRESRV to verify the copy operation. For example, PRESRV
compares the output device to the input device to make sure there are
no differences.
When the verification
following message:

operation

begins,

PRESRV

responds

with

the

**BEGIN VERIFICATION**
This will cause a second pass over the input and output media so that
every block written is read back and compared with the corresponding
block on the input device. When verification is requested, twice the
number of output buffers are needed. The /VE switch may appear on
either side of the command string. For example:
PRE>DKl:/VE=DKO:
PRE>DKl:=DKO:/VE
If the verification is successful, PRESRV prints
PRE>
and will accept another command.
If the comparison fails, PRESRV prints the following error message:
VERIFICATION ERROR m,nnnnnn
The number printed is the octal logical block number on the output
device where the error was detected, where "nnnnnn" is the low-order
word and "m" is the high-order word of the two-word LBN number. Thus
5,031275
indicates LBN 340669 (the last LBN on an RP06).
abort the operation.

12-19

Retry,

continue,

VOLUME PRESERVATION UTILITY (PRESRV)
If the volume to be verified is faulty,
PRESRV responds with
following error message whenever a verification error occurs:

the

VOLUME FAULTY - "R" TO RETRY, "C" TO CONTINUE>
Type R to retry or C to continue the operation.
NOTE
If the user types the ALTMODE key when
PRESRV is ready to accept input, the
current operation is aborted.

12.3.4

Magnetic Tape Switches

Four switches are provided to specify
default
recording density is 800 bpi.
recorded in core dump format.
Switch

Function

/20
/55
/80
/PE

Specifies
Specifies
Specifies
Specifies

magnetic tape options.
The
Seven-channel tapes are always

200 bpi for 7-track tape.
556 bpi for 7-track tape.
800 bpi for 7-track tape.
1600 bpi (phase encoded) for TU16 tape.
NOTES

File labels,
bootstraps,
and
system
images are always written at 800 bpi on
logical tapes.
Therefore, logical tapes
written with the /PE switch must be
copied /PE specified on both sides of
the command.
For example:
PRE>MMl:/PE=MMO:/PE

Logical tapes written on a 7-track drive
are bootable only on a 7-track drive.
Logical tapes written on a 9-track drive
are bootable only on a 9-track drive.

12.3.4.1 200 bpi Switch (/20) - The 200 bpi switch
(/20)
indicates
either that an input magnetic tape volume has been recorded at 200
bits per inch, or that an output magnetic tape volume is to be
recorded at 200 bits per inch. The tape drive must be 7-track and an
image copy must be performed. Thus:
PRE>MT0:/20/VE=MTl:/20
produces and verifies an exact copy of MT!:

on MTO:

at 200 bpi.

12.3.4.2 556 bpi Switch (/55) - The 556 bpi switch
(/55)
indicates
either that the input magnetic tape volume has been recorded at 556
bits per inch, or that the output magnetic tape volume
is to be
recorded at 556 bits per inch.
The tape drive must be 7-track and an
image copy must be performed.

12-20

1
'

•a••••••z•a•,••..••••••••-------•••••11111;~••••••••••••••••••1114111l4•

11111

VOLUME PRESERVATION UTILITY (PRESRV)
12.3 .. 4.3 800 bpi switch (/80) - The 800 bpi switch
(/80)
indicates
either that an input magnetic tape volume has been recarded at 800
bits per inch or that an output magnetic tape volume is to be recorded
at 800 bits per inch.
This switch can be specified for image
transfers on 7-track magnetic tape only.

12. 3 .. 4. 4 Phase Encoded Switch (/PE) - The phase encoded switch
(/PE)
indicates either that an input magnetic tape volume is recorded at
1600 bits per inch (phase encoded) or that an output magnetic tape
volume is to be recorded at 1600 bits per inch. The volume must be
mounted on a TU16 (or equivalent) drive.
NOTE
This switch cannot be used with logical
tapes if a TM03 formatter is involved.

12 .3. 5

Stand-Alone PRESRV Switches

Once a logical tape is booted into memory, PRESRV is running.
Seven
stand-alone switches are available with PRESRV. Four of the switches
specify physical device address information.
Switch

Function

/CSR
/UNIT
/VEC
/TM02

Specifies a control status register.
Sets the unit number for a device to 2 through 7.
Specifies an interrupt vector for a device.
Specifies the unit number of a TM02 formatter on the RH
controller.

These four switches can appear together,
in any combination,
in a
single command line. This has no effect on their stand-alone status;
that is, the action specified by each switch is executed before
another command is accepted.
PRESHV is distributed with the control
vector addresses shown in Table 12-4.

status

(CSR)

and

Two units (0 and l) are generated for each device type.
If the generated CSR or vector address does not correspond to the
actual hardware configuration in use, the /CSR and /VEC switches can
be used to correct values generated by PRESRV (see Sections 12.3.5.l
and 12.3.5.3).
The three remaining stand-alone switches are listed below.
Switch

Function

/TIM

Sets the current time and date.

/BO

Boots a monitor from a specified
completion of PRESRV operations.

/FO

Causes PRESRV to format a disk.

12-21

device

following

VOLUME PRESERVATION UTILITY (PRESRV)
Table 12-4
CSR and Vector Addresses
Device

CSR

Vectorl

CT
DB
OF
DK
DP
OS
OT
MM
MT
DX

177500
176700
177460
177404
176714
172040
177342
172440
172522
177170

260
300*
204
220
254
310*
214
320*
224
264

1 An asterisk (*) indicates that this is not a normal vector.

12.3.5.1 Control Status Register Switch (/CSR) - The control status
register switch
(/CSR) specifies the correct CSR for a device type.
The switch is typed in response to the PRE> prompt and has the
following format.
dev:/CSR=nnnnnn
dev
Specifies the device name and logical unit number of
whose CSR is to be changed.

the

device

nnnnnn
Specifies the octal address of the CSR used by the device.
The new CSR applies to all devices of the
specified in the command.

same

type

the

device

12.3.5.2 Physical Unit Number Switch (/UNIT) - The physical unit
number switch
(/UNIT)
allows the user to copy to or from a device
designated as a unit other than unit 0 or 1 of that device type. Type
the /UNIT switch in response to the PRE> prompt, in the following
format:
dev:/UNIT=n
dev
Specifies the device name and unit number (0 or 1).
n

Specifies the unit number of the same device type that will be
referenced each time "dev"
(as specified above) appears in a
command line.

12-22

iii)

14 2 jQU41 I

VOLUME PRESERVATION UTILITY (PRESRV)
For e.Kample:
JPRE> DBl: /UNIT==3
causes the RP04 assigned as unit 3 to
appears in a command.
The /UNIT switch can also
switch, to reference MM2:
peripherals.

be used in
through MM7:

referenced

each

time

DBl

conjunction with the /TM02
on systems with mixed MASSBUS

12.3.5.3 Vector Address Switch (/VEC) - The vector address switch
(/VEC) changes the interrupt vector for a device type. The switch is
typed in response to the PRE> prompt. It has the following format:
dev:/VEC=nnnnnn
dev
Specifies the device name and unit number for
address is to be changed.

which

the

vector

nnnnnn
Specifies the new octal vector address.
NOTE
When a tape created by online PRESRV is
bootstrapped, if the vector address is
incorrect, the first command
issued
after the prompt should be to set the
appropriate
vector
address;
for
example:
PRE>MMO:/VEC=224
The new vector address applies
devices of the specifi•d type.

~·

all

12.3 .. 5.4 Set TM02 Unit Number Switch (/TM02) - The /TM02 switch
changes the unit number of the TM02/TM03 formatter for a TE16, TU16,
TU45, or TU77 attached to an RHll or RH70 controller.
The TM02
formatter for the tape is normally unit O.
The j:orma t is:
dev:/TM02=n
dev
Specifies the device whose TM02/TM03 formatter position on the RH
Controller is to be changed.
n

Specifies the unit number to which the TM02/TM03 formatter is
be changed.

12-23

VOLUME PRESERVATION UTILITY (PRESRV)
Example
PRE>MMO: /TM02=2

The new TM02 value
command.

applies

only

the

device

specified

the

12.3.5.5 Time Switch (/TIM) - The time switch (/TIM) sets the time of
day for the PRESRV system.
It is typed in response to the PRE> prompt
and has the following format:
/TIM=mm/dd/yy hh:mm:ss
mm
Specifies the month.
dd
Specifies the day of the month.
yy
Specifies the year.
hh
Specifies hours.
mm
Specifies minutes.

- I "T
"""'
···

If present, specifies seconds.
All values are in decimal (no decimal point is specified).
12.3.5.6 BOOT Switch (/BO) - The PRESRV program is a stand-alone
program that runs
independently of any other system. When PRESRV
prompts, the user may bootstrap a monitor from a specified device by
using the bootstrap (/BO) switch.
For example:
PRE> DKO: /BO
system monitor identification
The above command string causes a monitor to be read from DKO:
and
loaded into memory. The /BO switch is a stand-alone switch and must
be typed as a separate command. Only unit 0 of the specified device
type can be bootstrapped in this way, unless the device to be booted
is a tape.

12.3.5.7 Format Disk Switch (/FO) - RK05, RP02, RP03, RP04, RP05, and
RP06 disks delivered from the factory must be prepared to store data
before they can be used.
This preparation process is
called
"formatting", and consists of writing sector identification timing and
information on the disk.
PRESRV performs this operation in response
to the /FO switch.

12-24

i!!Z

:;:

qqas

VOLUME PRESERVATION UTILITY (PRESRV)

Formatting can be specified as a separate operation or in conjunction
with a copy operation. If a copy operation has been specified, the
format pass is made before the copy is made. The /FO switch can be
specified only on the output side of the command string.

Examples
PRE> DKO: /FO
PRE>DPO:/FO/VE=MTO:DISK
When formatting starts, the message

** BEGIN FORMATTING **
is displaye~d.

When formatting has been completed, the message

** END FORMATTING **
is di splayE!d.
Before RP02 or RP03 disks can be formatted, formatting must be enabled
with the format enable switch on the RPll controller. This switch is
located in the third bay from the bottom on the controller. The front
cover must be removed to expose the switch. PRESRV prompts the user
to enable and disable formatting at the proper times with the
following messages:
ENABLE FORMATTING WITH SWITCH ON CONTROLLER. TYPE CR WHEN READY>
DISABLE FORMATTING WITH SWITCH' ON CONTROLLER. TYPE CR WHEN READY>
When the switch is set properly, press the RETURN key to
to continue~.

tell

Once a disk is formatted,
it requires
control information has been destroyed.

unless

12.4

reformatting

PRESRV
the

COMPUTING THE NUMBER OF BLOCKS REQUIRED FOR BUFFERING

When PRESRV is initiated, it prints at the terminal the maximum number
of 256-word blocks available for buffering.
(This number is a decimal
number.) These blocks are required for data transfer and verification
operations.
The user must refer to the number (nn.) to determine
whether a given media copy has sufficient buffering space.
The space required depends on blocking factors and use of the
verification switch.
Default block sizes for devices supported by
PRESRV are provided in Table 12-3.
The maximum number of buffer
blocks depends on the memory size of the system.
The examples below illustrate the method for determining the bloc~s
required for PRESRV copy operations. The method is to establish the
total number of blocks required for input, output, and verification.

12-25

VOLUME PRESERVATION UTILITY (PRESRV)
Example 1
PRE>MTO:ABC=DKO:
Thirteen blocks are required to create a logical tape file
(labeled
ABC) on magtape unit O, from an RK disk, using default blocking
factors.
Blocks Required

Operation
Input
Output
Verification
Total

12.
l.

(DK default block size)
(MT default block size)
(no verification specified)

13.

Example 2
PRE>MTO:DEF/BL:l2.=DKO
Twenty-four blocks are required to create a logical tape file (labeled
DEF) on magtape unit o. The default blocking factor is used for the
input device, while physical blocks of 3072 words each are written to
MTO:
(12 x 256). This results in fewer blocks on MTO:, and requires
less execution time because the number of tape write operations is
reduced.
The blocking factor (12, decimal) will be recorded in file DEF's
label.
Operation
Input
Output
Verification
Total

file

Blocks Required
12.
12.
O
24.

(DK default block size)
(blocking factor specified for MTO:)
(no verification specified)

Example 3
PRE>DKO:=MTO:XYZ
Twelve blocks, plus the record size of file XYZ, are required to copy
file XYZ from MTO:
to unit DKO: and to have DKO: formatted as a
logical tape.
Operation
Input
Output
Verification
Total

Blocks Required
Record size specified in file XYZ's label
12.
(DK default block size)
0

12.

plus record size of file XYZ.

Example 4
PRE>MTO:IJK/VE/BL:l2=DKO:/BL:4
Twenty-eight blocks are required to create the file
tape MTO: from DKO: with verification specified.
Operation
Input
Output
Verification
Total

IJK

logical

Blocks Required
4.
(specified block size DK)
12.
(specified block size MT)
12.
(re-read block from MT)
28.

12-26

u au

VOLUME PRESERVATION UTILITY (PRESRV)

Example 5
PRE>DKO:/VE=MTO:IJK
Twenty-four blocks, plus the record size of file IJK, are required
copy file IJK from MTO: to DKO:, with verification specified.
Operation

Blocks Req u i red

Input
Output
Verification
Total

Record size of file IJK
12.
(DK default block size)
12.
(Re-read block from DKO:)
24. plus record size of file IJK.

Example 6
PRE> MMO: =MMl:
The above command results in an image copy. The image copy uses all
available memory buffer space in creating blocks on the output volume.
If any input record is too large, the transfer is aborted.
If
verification is specified, half of the available memory buffer space
is used to form blocks for the output volume.
The other half is
required for verification.

12.5

PRESRV ERROR MESSAGES

As it executes, PRESRV checks to determine the success of the
operation. If an error is detected, PRESRV prints one of the messages
listied below.
BITMAP FILE HDR READ ERROR

Explanation: An attempt has been made to perform a copy in
Files-11 mode, but the input volume is not in Files-11 format or
is not ready ..
User Action:
switch.

Retype the command using

either

the

/IM

/TP

were

specified

the

CONFLICTING SWITCHES

Explanation: Two conflicting switches
command string. For example, /TP/FI.
User Action:

Specify the correct switch(es).

DEVICE NOT FORMATTABLE

Explanation: The specified device is not accepted by PRESRV.
Devices accepted by PRESRV for formatting are RK03/05, RP02/03,
RP04, RPOS, and RP06.
User Action:

Specify the correct device mnemonic.

12-27

VOLUME PRESERVATION UTILITY (PRESRV)
DEVICE OFFLINE
Explanation: The specified device is not in the configuration
hardware, the Control Status Register (/CSR} switch is improperly
set, or the device is not on-line.
User Action: Set the /CSR and vector (/VEC} addresses for the
device to the proper addresses or put the device on-line. Retype
the command.
DICTIONARY READ ERROR
Explanation: An error occurred in reading a dictionary
bitmap equivalent} from logical tape.
User Action:

(storage

Retry or abort the operation.

DRIVE NOT READY
Explanation:

The specified drive is not ready or up to speed.

User Action:
command.

Wait until

the

drive

ready

and

retype

the

Explanation: An error occurred in input to the terminal or
z ( '"'z} was illegally typed.

CTRL

ERROR IN READING COMMAND

User Action:

Retype the command.

EXPECTED EOF NOT FOUND
Explanation: An End-Of-File (EOF) mark was read from the input
volume but not from the output volume during the verification of
a tape image copy.
User Action:

Retry the operation.

FATAL ERROR ON INPUT DEVICE
Explanation: An error occurred while reading
during a tape image copy.
User Action:

the

input

volume

Retry the operation.

FATAL ERROR ON OUTPUT DEVICE
Explanation: An error occurred while reading
output volume during a tape image copy.

writing

the

User Action: Make sure the output device isn't
Retry the operation.

write-protected.

or
Explanation: An uncorrectable error occurred while formatting
disk. This error usually indicates a media or hardware error.
User Action:

Reformat the disk.

12-28

s: a

z:;

I ii

VOLUME PRESERVATION UTILITY (PRESRV)
HOME BLOCK READ ERROR
Explanation: An attempt has been made to perform a copy in
Files-11 mode, but the input volume is not in Files-11 format or
is not ready.
User Action: Wait until
command using the /IM
transf'er mode.

the device is
or /TP switch

ready or retype the
to specify the proper

ILLEGAL BLOCK COUNT
Explanation: The number of blocks specified with the switch is O
or is too large for the available buffer space.
User Action: Retry with valid block count.
default block sizes).

(See Table 12-3

for

INPUT DEVICE ERROR m, nnnnnn
Explanation: An error occurred while attempting to read data.
The octal logical block number listed is the location where the
error occurred.
The LBN is expressed as a 19-bit binary
representation (m,nnnnnn). See the verification error message in
Section 12.3.3.3.
User Action:
INPUT VOLUME nn.

None.
OUT OF SEQUENCE

Explanation: The number of the input volume does not
number of the required volume.
User Action:

match

the

Mount the proper volume and proceed.

INSUFFICIENT BUFFER SPACE
Explanation: A record on an input tape is too large for the
available buffer space.
More blocks than are available in the
buffer are needed to complete the copy operation.
User Action:
block sizes.

Abort;

or retry the operation specifying different

LABEL OR BOOTSTRAP WRITE ERROR
Explanation: An error occurred while writing the initial part of
a loglcal tape.
User Action:

Retry or abort the operation.

LUN ASSIGNMENT ERROR
Explanation: Device or lo~ical unit (LUN) combination specified
in the command string is not supported by the current PRESRV
system or is not a valid device for PRESRV operations.
User Action: Determine the status of the device and type the
proper command. You may be able to redirect the PRESRV operation
to another unit by means of the /UNIT switch (Section 12.3.5.2).

12-29

VOLUME PRESERVATION UTILITY (PRESRV)
NO SUCH FILE
Explanation: File named in the command string was not found on a
logical tape, or a magnetic tape was at End-Of-Volume (EOF) for
input.
User Action:

Retype the command using a proper file label.

OUTPUT DEVICE ERROR m, nnnnnn
Explanation: An error occurred while reading or writing data.
The number printed is the.octal logical block number where the
error was detected. The LBN is expressed as a 19-bit binary
representation (m,nnnnnn). See the verification error message in
Section 12.3.3.3.
User Action:

Retry, continue or abort the operation.

OUTPUT VOLUME OVERFLOW
Explanation: Input has
(Files-11) can hold.
User Action:
Try
blocking factor.

blocks

alternate

the

that

transfer

output

format.

volume

Check

the

*** nnn: -- SELECT ERROR
Explanation:

Device nnn:

is off-line.

User Action:

Put device on line.

STORAGE BITMAP FILE READ ERROR
Explanation: An attempt has been made to perform a copy in
Files-11 mode, but the input volume is not in Files-11 format or
is not ready.
User Action: Wait until the device is ready or retype
command specifying the proper transfer mode (/IM or /TP).

the

SYNTAX ERROR
Explanation:

The command string was not a valid command.

User Action:

Retype the command string correctly.

TAPE LABEL READ ERROR
Explanation: An error occurred
label record.
User Action:

while

reading

logical

tape

Retry or abort the operation.

TAPE WAS WRITTEN FOR dd
Explanation: This is a warning message, not an error message.
The Files-11 volume being restored from a logical tape is not of
the same type as the one from which the tape was originally made.
The new volume is given the bitmap of the old volume. The
characters dd identify the intended Files-11 device.
User Action:

None.

12-30

a ea ts;

I it

I::; I

VOLUME PRESERVATION UTILITY (PRESRV)
TRANSFER SPECIFICATION MODE ERROR
Explanation: An inconsistency appears in the command string.
For example, a magnetic tape has a /FI switch associated with it.
User Action:

Retype an acceptable command.

VERIFICATION ERROR nnnnnnn
Explanation: The data read back from the output volume does not
match what was written. The number printed is the octal logical
block number on the output device where the error was detected.
User Action: Retry, continue or abort the operation.
If retry
is specified, PRESRV performs the entire operation from the
beginning.
VOLUME FAULTY -

"R" TO RETRY, "C" TO CONTINUE

Explanation: An I/O error was detected during a copy
or a verification error occurred.

operation;

User Action: Type R to retry the operation from the beginning.
Type C to continue from the point at which the error occurred.

\..-·

12-31

iiiii

. II

;z;a

CHAPTER 13
FILE STRUCTURE VERIFICATION UTILITY (VFY)

13.l

INTRODUCTION TO VFY

The File Structur• verification Utility
ability to:

program

provides

the

•

Check the readability and validity of a file-structured volume
(default function).

•

Print out the number of available blocks on a
volume (/FR) •

•

Search for files that exist in the index file but that do not
exist in any directory, that is, files which are "lost" in the
sense that they cannot be accessed by file name (/LO).
(See
the
IAS/RSX-11
I/O
oeerations Reference Manual for a
description of the index file~}

all files in the index
• List
filename, and owner (/LI) •

'-''

(VFY)

file-structured

file

ID,

•

Mark as "used" all the blocks that appear to be available
are actually allocated to a file (/UP).

but

•

Rebuild the storage allocation bit map so that it
reflects the information in the index file (/RE).

•

Restore files that are marked for delete (/DE).

•

Perform a read check on every
file-structured volume (/RC).

file,

showing

allocated

the

block

properly

There should be no other activity on the volume while VFY is
executing.
In particular, activities which create new files, extend
existing files, or delete files should not be attempted while VFY is
executing a function.
VFY must not be aborted while a /UP, /RE, or /DE switch is being
processed.
Aborting VFY while it is in the process of modifying the
storage allocation or index files may seriously endanger the integrity
of that volume.

13-1

FILE STRUCTURE VERIFICATION UTILITY (VFY)
13.2

VFY COMMAND STRING

All VFY functions are invoked by entering a VFY command string through
the initiating terminal.
The VFY command string is formatted as
follows:
listfile,scratchdev=indev/switch
or
indev/switch

(This is a short form of TI:,indev=indev/switch)

list:file
Specifies the output listing file in the following format:
dev: [ufd]filename.filetype;ver
scratchdev
Specifies the device on which the scratch file produced by VFY is
to be written. This parameter is in the following format:
dev:
The scratch file is used by VFY during the verification scan and
during the lost file scan. It is created but not entered in a
directory. Therefore, it is transparent to the user.
The
scratch file is automatically deleted upon termination of the VFY
program.
If the system disk is faulty or full, use this parameter to force
the scratch file to another device. The scratch file should
always be assigned to another volume. The scratch file is not
used for the /FR and /LI switches.
indev
Specifies the volume to be verified.
following format:

This parameter

the

dev:
/switch
Specifies the function to be performed.
following format:

This parameter is in the

/sw
The VFY switches are described in detail in Section 13.3.
VFY normally operates in a read-only mode, assuming that the scratch
file, if required, is on another device. VFY requires write access
under the following conditions:
1.

If the /UP or /RE switch is used, VFY requires write
to the storage allocation map ([O,O]BITMAP.SYS).

access

If the /DE switch is specified, VFY requires write access
the index file ([O,O]INDEXF.SYS).

If the /LO switch is specified and lost files are found,
requires write access to the [1,3] User File Directory.

VFY

13-2

l''~W ...

u: i!ij

iii!

FILE STRUCTURE VE.RIFICATIOH UTILITY (VFY)

VFY may be run under any UIC if only read access is required.
write access is required, VFY must run under a system UIC.

If write access to the volume index or bit map files is required for
the desired operation, the user must mount the volume using the
/UNLOCK swHch.
Default file specifiers for VFY command line elements
Table 13-1..

are

listed

Table 13-1
VFY Default File Specifiers
Element:
dev:

Default Value
Output listing device
TI:
Scratch file device
SYO:
Volume to be verified
SYO:

[ufd]

The UIC under which VFY is currently running.

filename

No default - must be specified.

• filetype

No default - must be specified •

; ver

Latest version plus 1.

'--·

13.3

'-'i

VFY SWITCHES

VFY functic>ns are specified in the form of switches appended to the
VFY command string. Command switches and functions are summarized in
Table 13-2 ..

13-3

FILE STRUCTURE VERIFICATION UTILITY (VFY)

Table 13-2
VFY Functions and Switches
Function

Switch

Delete

/DE

Reset
indicators.

Free

/FR

Print out the available
on a volume.

List

/LI

List entire index file by file
identification.

Lost

/LO

Scan entire file
structure
looking for files which are
not in any directory.

Read Check

/RC

Check entire volume to see if
every block of every file can
be read.

Rebuild

/RE

Recover blocks which appear to
be
allocated
but are not
contained in a file.

Update

/UP

Allocate blocks which appear
to be available but have been
allocated to a file.

Validity Check

Default

Check readability and validity
of
the
volume mounted on
specified device.

13.3.1

Purpose
marked-for-delete
space

Validity Check

Validity Check (no switch) checks the readability and validity of the
volume mounted on the specified device. This function entails reading
all the file headers in the index file and ensuring that all the disk
blocks referenced in the map area of each file header are marked as
allocated to that file in the volume bit map.
Requirements for running the validity check:
1.

The volume to be checked
structured volume.

must

The volume may be write-protected if:
a.

It is not the system volume;

The required scratch file
file-structured volume.

mounted

directed

Files-11

another

A validity check is specified in the following form:
listfile,scratch dev=indev <CR>
or
indev <CR>

13-4

a u

$Pl

'iii

CL $lliilf 4

FILE STRUCTURE VERIFICATION UTILITY (VFY)
Exa11tple
>VFY DRO:
CONSISTENCY CHECK OF INDEX AND BITMAP ON ORO:
INDEX INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680.
BITMAP INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680.

File Error Reporting - As VFY verifies a volume, error
conditions are reported. All errors for a given file are preceded by
a file identification line that identifies the file in error.
This
line is formatted as follows:

13.3.1.1

FILE ID nn,mm filename.filetype;version OWNER [g,m]
nn,mm
Represents the unique file identification number assigned to
file by the system at file-creation time.

the

Represents the file name •
• filetype
Represents the file type (for example, .OBJ for object file).
;version
Represents the version number of the file.
[g 'm]

Represents the UIC that owns the file.
This file identification line is
following messages:

followed

one

the

I/O ERROR READING FILE HEADER-ERROR CODE -32
Explanation:
VFY failed to read the file header for the
specified file ID. The device is not mounted or is off-line, or
the hardware has failed.
BAD FILE HEADER
Explanation: Software checks on the validity of the file
indicate that the header has been corrupted.

header

MULTIPLE ALLOCATION n,m
Explanation: The specified (double precision) logical block
number is allocated to more than one file. If this error occurs,
a second pass is automatically taken which will indicate all
files that share each multiply-allocated block. The second pass
is taken after all file headers have been checked (see Section
13.3 .. 1.3).

13-5

FILE STRUCTURE VERIFICATION UTILITY (VFY)
BLOCK IS MARKED FREE n,m
Explanation: The specified logical block number is allocated to
the indicated file but is not marked as allocated in the storage
allocation map (see Section 13.3.1.4).
BAD BLOCK NUMBER n,m
Explanation: The specified block number was found in the header
for this file but is illegal for the device (out of range). This
indicates a corrupted file header.
FILE IS MARKED FOR DELETE
Explanation: A system failure occurred while the specified file
was being deleted. The deletion was not completed and the file
header still exists (see Section 13.3.1.2).
HEADER MAP OUT OF SYNC
Explanation: VFY detected an error in the header map area
also indicates a corrupted file header.
The last error message for the file is followed by a summary line
that file, as follows:
SUMMARY:

MULT=nn,

FREE=nn~

which
for

BAD=nn.

MULT
Specifies the number of multiple block allocations.
FREE
Specifies the number of blocks marked free that should have
allocated.

been

Specifies the number
header.

file

BAD
of

bad

retrieval

pointers

the

If the output for VFY is directed to a terminal device, and you do not
wish to see all the error messages for a given file, entering <CTRL/O>
terminates the listing of all further error messages for that file,
that is, all messages but the summary line.

~.···--: 1--:',
..

13.3.l.2 Files Marked-for-Delete - If a file has been marked for
delete but the deletion process was not completed, you can either
restore the file, if you still need it, or you can delete the file to
recover the space it was occupying. This situation only occurs when
the system crashes during file processing.
•

Restoring a File
To restore a file marked-for-delete, the disk volume must be
mounted using the MCR Mount command with the /UNL switch
specifi~d.
For example:
>MOU DKO:/UNL

13-6

2 h 122!1)

44u:

FILE STRUCTURE VERIFICATION UTILITY (VFY)
Then, run VFY specifying the /DE switch to reset
the
marked-for-delete indicators in file headers. Once the delete
indicator has been reset, run VFY specifying the /LO switch to
scan the entire file structure.
The deletion process may have proceeded partially and a
portion at the end of the file may be missing. This condition
can be detected by a directory listing obtained using the PIP
/FU switch.

• Deleting a File
Files that are marked-for-delete can be deleted directly with
PIP, once their unique File ID has been obtained via a
validity check. The File ID appears as the first entry in the
file identification line which precedes each list of file
errors (see Section 13.3.1.1).
The
following
example
illustrates how the File ID is used with PIP to delete a file:
>PIP /FI:l2:20/DE
In this example, the file with File ID 12,20 is deleted
the system device. PIP issues the error message:

from

PIP -- FAILED TO MARK FILE FOR DELETE-NO SUCH FILE
since the file system denies the existence of files already
marked-for-delete; however, the file is completely deleted.
Once! files have been restored or deleted, run VFY with the /RE switch
specified to assure the consistency of the volume's storage allocation
bit map.

13.3.1.3 Deletion of
Multiply-Allocated
Blodks - If
the
file
structure contains multiply-allocated blocks, it is necessary to
dele!te files until there are no more such blocks. An automatic rescan
of the volume identifies which files share which blocks. This rescan
lists the first as well as subsequent
files
containing
the
multiply-allocated blocks.
Using this information, you can then
determine which, if any, of the files can be saved and delete the
rest, using the PIP delete function.

'-'i

Be careful when deleting files containing multiply-allocated blocks.
Afte!r the files have been deleted, VFY should be run once again to
ensure that all of the files containing multiply-allocated blocks have
been delet~~d.

13.3.1.4 Elimination
of
Free
Blocks - Once
there
are
no
multiply-allocated blocks, the next concern is the elimination of
blocks that are marked Free in the storage allocation bit map but are
actually allocated to a file. To cause these blocks to be reallocated
in the storage allocation bit map, rerun the validity check specifying
the /UP switch.
This allocates all blocks that should have been
marked as allocated. See Section 13.3.8 for a description of the /UP
switch.

13-7

FILE STRUCTURE VERIFICATION UTILITY (VFY)
Once there are no multiply-allocated blocks and no blocks marked free
that are actually in use, the file structure is safe for writing new
files and extending existing files.
However, if there were such
errors, there may be files which have had data blocks overwritten as
the result of multiple allocation.

13.3.1.5 Recovering Lost Blocks - To determine whether any blocks
have been lost on a file-structured volume, examine the last two lines
of output from the validity check. The last two lines of output give
the free space on the volume. The first line of the two tells how
much room is available according to the index file
(that is, the
number of blocks that are not in use by any file in the index file).
The last line specifies how much room is available according to the
storage allocation bit map. Assuming there are no other errors, these
two figures should agree. If the index file indicates that more
blocks are free than the storage allocation bit map, then those blocks
are "lost" in the sense that they appear to be allocated, but no file
contains them. Lost blocks can be recovered by rerunning the validity
check specifying the /RE switch. See Section 13.3.7 for a description
of the /RE switch.

13.3.2

Delete Switch (/DE)

The Delete switch (/DE) resets the marked-for-delete indicators in the
file header area of files that were marked for deletion but never
actually deleted. The Delete switch is specified in the following
form:
listfile,scratchdev=indev/DE
or
indev/DE
The volume must be mounted with the /UNL switch.
VFY must be running under a system UIC.

13.3.3

Free Switch (/FR)

The Free switch (/FR) displays the available space on a specified
volume. The Free switch is specified in the following form:
listfile=indev/FR
or
indev/FR
Free switch output is the following message:
dev: HAS nnnn.

BLOCKS FREE, nnnn.

BLOCKS USED OUT OF nnnn.

13-8

!'i•• Ji! I i l l !IU

!2l;

I I ii

,.,.,

FILE STRUCTURE VERIFICATION UTILITY (VFY)
13.3o4

List Switch (/LI)

The List switch
(/LI)
lists the entire index
file
by
file
identification.
The output for each file specifies the file number,
file sequence number, file name, and owner.
A typical index file
listing is illustrated in-Figure 13-1. The List switch is specified
in the following form:
listfile,scratchdev=indev/LI
or
indev/LI
VFY> DK: /LI
LISTING OF INDEX ON DKO:
FILE
FILE
FILE
FILE
li'ILE
li'ILE
F'ILE
f 'ILE
F'ILE
F'ILE
F'ILE
F'ILE
1

ID 000001,000001 INDEX1'~. SYS; 1
ID 000002,000002 BITMAP.SYS;l
ID 000003,000003 BADBLK.SYS;l
ID 000004,000004 000000 .DIR; 1
ID 000005,000005 CORIMG.SYS;l
ID 000006,000006 001001.DIR; l
ID 000007,000007 001002.DIR;l
ID 000010,000010 EXEMC~MLB;l
ID 000011,000011 RSXMAC.SML;l
ID 000012,000012 NODES.TBL;l
ID 000013,000036 QIOSYM.MSG; 311
ID 000014,000037 F4PCOM.MSG;l

Figure 13-1

13.3.5

OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER
OWNER

[1,1]
[1,1]
[l, l]
[ 1, 11
[1,1]
[l,l]
[1,2]
[l,l]
[1,1]
[1,1]
[1,2]
[1,2]

VFY Listing Sample Using the /LI Switch

Lost Switch (/LO)

The Lost switch (/LO) scans the entire file structure looking for
files which are not in any directory and, thus, are lost in that they
cannot be referenced by file name. A list of the files
is produced,
and if the "lost file directory" [1,3] exists on that volume, all the
f ilE~S will be entered in that directory. The Lost switch is specified
in the following form:
listfile,scratchdev=indev/LO
or
indev/LO

13.3.6

Read Check Switch (/RC)

The Read Check switch (/RC) checks to ensure that every block of every
file on a specified volume can be read. The Read Check switch is
specified in the following form:
listfile=indev/RC[:n]
or
indev/RC [: n]

13-9

FILE STRUCTURE VERIFICATION UTILITY (VFY)
The optional parameter [:n] is the blocking factor which indicates the
number of file blocks to be read at a time. The default value is the
maximum number of blocks available in VFY's buffer area.
Since the Read Check function is a read-only operation, the volume can
be write-protected.
The buffer area available may be increased by installing VFY in a
larger partition. Five blocks are available when VFY is installed in
an SK partition, and four blocks are added for each lK increment.
For the fastest possible read check, the maximum block factor should
be used. Whenever an error is encountered, each block of the portion
in error is reread individually to determine which data block{s)
cannot be read.
When an error is detected, a file identification line is listed in the
following format:
FILE ID nn,nn filename.typ;ver.

blocks used/blocks allocated

Following this line, an error message is listed. If a blocking factor
other than 1 is in use, an error message in the following form will be
issued:
ERROR STARTING AT VBN nl,n2 LBN nl,n2 - ERROR CODE -n
Following the first error message, there should be one or more error
messages indicating the exact block{s) in error. The second error
message line{s) will be in the following form:
ERROR AT VBN nl,n2 LBN nl,n2 - ERROR CODE -n

""'
:: j1'

If an ERROR STARTING AT line is displayed without one or more ERROR AT
lines, a multiblock read operation on the selected device has failed,
but the data blocks appear to be individually readable.
If the VBN of the unreadable block listed in the ERROR AT line is
beyond the block-used-count, the data portion of the file is readable.
The negative number printed after the ERROR CODE message is usually -4
to indicate a device parity error. Other error codes are contained in
Appendix I of the IAS/RSX-11 I/O Operations Reference Manual.

13.3.7

Rebuild Switch (/RE)

The Rebuild switch {/RE) recovers lost blocks, that is, blocks that
appear to be allocated but which are not contained in any file. The
Rebuild switch is specified in the form:
listfile,scratchdev=indev/RE
or
indev/RE
Multiply-allocated blocks must be removed
structure before the rebuild can be run.

{deleted)

from

the

file

The volume being updated must be write-enabled.
VFY must be running under a system UIC.

13-10

! $ ;:

n;: :: t

U!i iii

a 122.

qap:.

FILE STRUCTURE VERIFICATION UTILITY (VFY)
The scratch file should be on another volume. If this is impossible,
the volume must be dismounted immediately after VFY terminates.
(Failure to do this may result in partial updating of the storage
allocation bit map.) Then the volume should be mounted again, and the
scratch filE! must be deleted manually. VFY issues a detailed message
in this case~, specifying the name of the scratch file to be deleted.

13.3.8

Update Switch (/UP)

The Update switch (/UP) allocates all blocks
available but are actually allocated to a file.
specified in the following form:

that appear to be
The Update switch is

listfile,scratchdev=indev/UP
or
indev/UP
'-''

Files with multiply-allocated blocks must be
structure bE!fore the update can be run.

deleted

from

the

file

The volume being updated must be write-enabled.
VFY must be running under a system UIC.
The scratch file should be on another volume. If this is impossible,
the volume must be dismounted immediately after VFY termin~tes.
(Failure to do this may result in partial updating of the storage
allocation bit map.) Then the volume should be mounted again, and the
scratch file must be deleted manually. VFY issues a detailed message
in this case specifying the name of the scratch file to be deleted.
The message is:
VFY

TO COMPLETE THE STORAGE MAP UPDATE
IMMEDIATELY.
THEN
MOUNT
IT
AND
FILE~
[ufd] filespec

13.4

VFY ERROR MESSAGES

DISMOUNT THE
VOLUME
DELETE THE FOLLOWING

VFY -·- COMMAND SYNTAX ERROR
Explanation: The command entered does
syntax rules.

User Ac:tion:
specif:led.

not

Reenter the command line with

conform
the

command

correct

syntax

VFY -- FAILED TO ALLOCATE SPACE FOR TEMP FILE
Explancttion:
is full.

The volume specified for the temporary scratch file

User Action:
VFY.

Use PIP to delete all unnecessary files

13-11

and

rerun

FILE STRUCTURE VERIFICATION UTILITY (VFY)
VFY -- FAILED TO ATTACH DEVICE
or
VFY -- FAILED TO DETACH DEVICE
or
VFY -- ILLEGAL DEVICE
Explanation:
device.

The file

User Action:
specified.

Reenter the command line with

VFY

specifier

entered

contains
the

illegal

correct

device

FAILED TO CLOSE DIRECTORY FILE (See I/O ERROR messages).

VFY -- FAILED TO ENTER FILE
Explanation:

One of the following conditions may exist:

•

VFY is not running under a system UIC.

•

The device is not on-line.

•

The device is not mounted.

•

The hardware has failed.

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.
VFY

FAILED TO OPEN DIRECTORY FILE (See OPEN FAILURE error messages)

VFY -- ILLEGAL SWITCH
Explanation: The switch specified is not a valid VFY switch or a
valid switch is used illegally.
User Action:
specified.

Reenter the command line with

the

correct

switch

VFY -- I/O ERROR ON INPUT FILE
or
VFY -- I/O ERROR ON OUTPUT FILE
or
VFY -- I/O ERROR READING DIRECTORY FILE
or

13-12

I S

!IS!.

I I !ii

144 '

FILE STRUCTURE VERIFICATION UTILITY (VFY)
VFY -- FAILED TO CLOSE DIRECTORY FILE
Explanation:

One of the following conditions may exist:

•

The device is not on-line.

•

The device is not mounted.

•

The hardware has failed.

user Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.
VFY -- NO DYNAMIC MEMORY AVAILABLE - PARTITION TOO SMALL
Explanation:

VFY does not have enough buffer space to run.

User Action:

Run VFY in a larger partition (SK minimum).

VFY -- OPEN FAILURE ON BIT MAP
or
VFY -- OPEN FAILURE ON INDEX FILE
or
VFY -- OPEN FAILURE ON LISTING FILE
or
VFY -- OPEN FAILURE ON TEMPORARY FILE
or
VFY -- FAILED TO OPEN DIRECTORY FILE
Explanation:

One of the following conditions may exist:

•

VFY is not running under a system UIC, but should be.

•

The named file does not exist in specified directory.

•

The volume is not mounted •

•

The specified file directory does not exist.

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.
VFY -- THEY ARE STILL LOST, COULD NOT FIND DIRECTORY
Explanation:

UFO [1,3] did not exist on the volume.

User Action:
volume.

Use the MCR UFO command to enter UFO [1,3]

13-13

the

PILE STRUCTURE VERIFICATION UTILITY (VPY)
13.5

YPY ERROR CODES (IAS SYSTEM ONLY)

If VFY cannot access the message file,
following format:

errors

are

reported

the

VFY -- ERROR CODE nn.
where:
nn.

is one of the error codes contained in Table 13-3.

Refer to Section
actions.

13.4

for

error

descriptions

and

suggested

user

Table 13-3
VFY Error Codes
Error
Codes
1
2
3
4
5
6
7
8
9
10
11

Corresponding VFY Error Message
ILLEGAL DEVICE
OPEN FAILURE ON BIT MAP
OPEN FAILURE ON TEMPORARY FILE
FAILED TO ALLOCATE SPACE FOR TEMP FILE
FAILED TO DETACH DEVICE
FAILED TO ATTACH DEVICE
COMMAND SYNTAX ERROR
I/O ERROR ON INPUT FILE
I/O ERROR ON OUTPUT FILE
ILLEGAL SWITCH
OPEN FAILURE ON LISTING FILE
OPEN FAILURE ON INDEX FILE
NO DYNAMIC MEMORY AVAILABLE - PARTITION TOO SMALL

13-14

!i!Xi2$1

; jj j

2i ii

4I if

PART 6
PROGRAMMING UTILITIES

·.~

JU I

!St

CHAPTER 14
LIBRARIAN UTILITY PROGRAM (LBR)

14.l

INTRODUCTION TO LBR

The Librarian Utility Program (LBR) allows you to create, update,
modi.fy, list, and maintain object, macro, and universal library files.
A library file is a direct access file which usually contains modules
of the samE~ type. Library files are organized for rapid access by the
Task Builder, MACR0-11 Assembler, and the Universal Library Access
($ULA) system library routine (see the IAS/RSX-11 System Library
Routines Manual, Appendix B.)
LBR and library files, in conjunction with the MACR0-11 Assembler, the
Task Builder, and the $ULA system routine, provide fast entry-point
search time, easy update with minimal copying of entire files, and the
ability to handle multiple module types.
Library files contain two directory tables:
an entry point table
(EPT) that contains entry point names (global symbols), and a module
name~ table (MNT) that contains module names.
Both the EPT and MNT are
alphabetically ordered. The EPT applies only to object libraries.
Object module names are derived from .TITLE directives, while entry
point names are derived from defined global symbols. Once an entry
point is located, its associated module can be accessed directly.
Macro module names are derived from .MACRO
point names are not applicable.

directives;

macro

entry

Universal module names are derived from file names at insert time;
universal entry point names are not applicable.
A module of a
universal library can be accessed by the $ULA Routine, found in the
IAS1~SX-ll
System Library Routines Reference Manual. You may use a
universal library to contain modules inserted from any kind of file.
You can invoke LBR using any of the methods
described in Chapter 1.

14.2

for

invoking

utility

LBR COMMAND STRING

LBR accepts command strings in the following general format:
outfile[,listfile]=infilel[,infile2, ••• infilen]
LBR allows only one level of indirect command file nesting for RSX-llM
and RSX-llM-PLUS. For a complete description of file specifiers, see
Chapter 1.

14-1

LIBRARIAll UTILITY PROGRAM (LBR)
14.3

DEFAULTS IN LBR FILE SPECIFIERS

Defaults in LBR file specifiers are described in Table 14-1.
Table 14-1
Defaults in LBR File Specifiers
Specifier
dev:

Default
Output File
SYO:
Listing File
The device which was specified for the output
file;
otherwise, the default for the output
file.
Input File
For the first input file specifier, SYO:.
For the subsequent input file specifiers, the
device specified in the previous input file
specifier; otherwise, the default for the
previous input file specifier.

[ufd]

Output File
The UIC under which LBR is currently running.

Listing File
The UFO which was specified for the output
file;
otherwise, the default for the output
file specifier.
Input File
For the first input file specifier,. the
under which LBR is currently running.

., I,,,

UIC

For the subsequent input file specifiers, the
UFO specified in the previous input file
specifier; otherwise, the default for the
previous input file specifier.
filename

No default.

Must be specified.

.type

Output File
Depends on the default in effect (see Section
14.6.4), except when the /CO or /CR switch is
specified (see Sections 14.6.l or 14.6.~,
respectively).
Listing File
.LST
Input File
Refer to the descriptions of /CO
14.6.1),
/IN
(Section 14.6.8),
(Section 14.6.11) switches.

(Section
and /RP

(continued on next page)

14-2

14 21 ii

Ji Ui

,ii

iiiL !J

1'4"'

LIBRARIAll UTILITY PROGRAM (LBR)
Table 14-1 (Cont.)
Defaults in LBR File Specifiers
r--·------------.--------------~----~-~----------------------~------~-,

Speci f iE!r

Default

;ver

Latest version of the file, or latest version plus 1
for the output file when the /CO, /CR, OR /EX switches
are specified.

/switch

Output File
/IN (Insert)
List File
/SP/LI (spool and list module names)
Input File
None.

14.4

LBR SWITCHES

LBR uses switches appended to file specifiers to invoke functions.
These
switches are summarized in Table 14-2.
For a detailed
description of each LBR switch, see Section 14.6.
Table 14-2
LBR Switches
Option

Function

Switch

t--·------------~---1----------+------------------------------~--~----------1

Compress

/CO

Compress a library file.

Create

/CR

Create a library file.

Delete

/DE

Delete a library module and all of
entry points.

Default

/DF

Specify the default library file type.

Delete Global

/DG

Delete a library module entry point.

Entry Pc1int

/EP

Include entry point elements
library entry point table.

the

/-EP

Exclude entry point elements
library entry point table.

the

Extract

/EX

Extract (read) one or more modules from
a library file and write them into a
specified output file.

Insert

/IN

Insert a module.

its

(continued on next page)

14-3

LIBRARIAN UTILITY PROGRAM (LBR)

Table 14-2 (Cont.)
LBR Switches
Option
List

Switch

Function

/LI

List module names.

/LE

List module
points.

names

and

module

entry

/FU

List module
description.

names

and

full

module

Modify Header

/MH

Modify a universal module header.

Replace

/RP

Replace a module.

/-RP

Do not replace a module.

/SP

Spool the listing for printing.

/-SP

Do not spool the listing.

Selective Search

/SS

Set selective
module header.

Squeeze

/SZ

Reduce the size of macro source.

1-sz

Do not reduce size of a specific
source.

Spool

14.5

attribute

macro

FORMAT OF LIBRARY FILES

A library file consists of a library header, an entry point table, a
module name table, the library modules and their headers, and
(usually) free space. The entry point table has zero length for macro
libraries and universal libraries. Figure 14-1 illustrates object and
macro library file format and Figure 14-2 illustrates universal
library file format.

14.5.1

Library Header

The header section is a full block in which the first 24.
words are
used to describe the current status of the library. Its contents are
updated as the library is modified, so LBR can access the information
it needs to perform its functions (Insert, Compress, and so on). The
24th word in the library header is the default insert file type for
universal libraries and is undefined for macro and object libraries.
See Figure 14-3.

14.5.2

Entry Point Table

The entry point table consists of 4-word elements containing an entry
point name (words 0-1), and a pointer to the module header of the
module where the entry point is defined (words 2-3). See Figure 14-4.

14-4

11
1!. . . :

12 . :

zwas " a :a: s.12;

; 222!

;z:;:

LIBRARIAN UTILITY PROGRAM (LBR)
This table is searched when a library module is referenced by one of
its entry points. The table is sequenced in order of ascending entry
point names. The entry point table is not used for macro or universal
library fi.les.

14.5.3

Module Name Table

The module name table is searched when the library module is
referenced by its module name, rather than by one of its entry points.
It is made up of 4-word elements; a module name (words 0-1) and a
pointer to the module header (words 2-3). See Figure 14-5. The
module name table is sequenced in order of ascending module names.

14.5.4

Module Header

Each module starts with a header of 8 words for object and macro
modules and 32. words for universal modules, identifying the type and
status of the m6dule, its length (number of words), and so forth; see
Figure 14-6, and Figure 14-7.
In object modules, the low-order bit of the attributes byte is set if
the module has the selective search attribute.
Also, in object
modules, the 2 words of type-dependent information contain the module
identification defined by the .IDENT directive at assembly time. In
mac:ro modules, these 2 words are undefined.
For universal modules type dependent identification
the file type ~nd version number of the input file.

is derived from
See Figure 14-7.

Universal libraries allow module header changes (optional
information) via the /MH switch.

descriptive

Library
Header

FixedLength
Records

Entry Point
Table
Block
boundaries
Module Name
Table
~

VariableLength
Records

Module 1 Header
Module 1

...
Module N Header
l

Module N
Available Space

Figure 14-1

General Format for Object and Macro Library Files
14-5

LIBRARIAll UTILITY PROGRAM (LBR)
FixedLength
Records

Library
Header
Entry Point
Table
Module Name
Table

VariableLength
Records

Block
boundaries

Module 1 Header
Unused Space
Module 1

Unused Space
Module 2 Header
Unused Space
Module 2

Unused Space
Module N Header
Unused Space
Module N

Available space

NOTE
All universal module headers and the
first record of each universal module
will start on a block boundary.

Figure 14-2 Universal Library File Format

14-6

11•2a

!IS

asp a

;z ii I

l I

I14

LIBRARIAN UTILITY PROGRAM (LBR)
OFFSET

'-'

WORD

0
2

LIBRARY TYPE
l
LBR (LIBRARIAN) VERSION

NON ZERO ID

(. IDENT ~"ORMAT)

YEAR

""'J

DATE AND

MONTH

TIME LAST

DAY

INSERT

HOUR

MINUTE

SECOND

22
24

EPT STARTING RELATIVE BLOCK

NO. EPT ENTRIES ALLOCATED

NO. EPT ENTRIES AVAILABLE

'-'

\...,·

J SIZE EPT ENTR's

RESERVED

SIZE MNT ENTR'S

MNT STARTING REL BLOCK

NO. MNT ENTRIES ALLOCATED

NO. MNT ENTRIES AVAILABLE

LOGICALLY DELETED

AVAILABLE (BYTES)

CONTIGUOUS SPACE

AVAILABLE (BYTES)

NEXT INSERT RELATIVE BLOCK

START BYTE WITHIN BLOCK

UNIVERSAL DEFAULT INSERT TYPE

(UNDEFINED FOR MACRO AND OBJECT LIBRARIES)
Figure 14-3

Contents of Library Header

14-7

LIBRARIAN UTILITY PROGRAM (LBR)
WORD

GLOBAL SYMBOL

NAME (RADSO)

2
3

Figure 14-4

WORD

ADDRESS OF
MODULE
HEADER

RELATIVE BLK.
BYTE IN BLOCK

Format of Entry Point Table Element

MODULE NAME

(RADSO)

2
3

Figure 14-5

ADDRESS OF
MODULE
HEADER

RELATIVE BLK.
BYTE IN BLOCK

Format of Module Name Table Element

OFFSET FROM
START OF
MODULE HEADER
0

ATTRIBUTES

STATUS

SIZE OF

MODULE (BYTES)

6
10

DATE
MODULE
INSERTED

YEAR
MONTH
DAY

12
14

TYPE DEPENDENT

INFORMATION

Figure 14-6

O=NORMAL MODULE
!=DELETED MODULE

Module Header Format for Object and Macro Libraries

14-8

i4JJ

aa; a

I $.!Qi iii

211

I :a;

LIBRARIAN UTILITY PROGRAM (LBR)
OFFSET
START
MODULE

'--'

FROM
OF
HEADER

\._,.J

ATTRIBUTES

SIZE OF

MODULE (BYTES)

STATUS

DATE

YEAR

MODULE

MONTH

INSERTED

DAY

I DENT

'-''

OPTIONAL

INFO

OPTIONAL

INFO

OPTIONAL

INFO

OPTIONAL

INFO

\.,
4

40
42
44

Figure 14-7

USER
FILE
ATTRIBUTES

..
.

Module Header Format for Universal Libraries

14-9

LIBRARIAN UTILITY PROGRAM (LBR)

14.6

LBR SWITCHES

This section provides a detailed description of each LBR switch.

14.6.l

Compress Switch (/CO)

Use the Compress switch to physically delete all logically deleted
records, putting all free space at the end of the file, and making the
free space available for new library module inserts.
Additionally,
the library table specification may be altered for the resulting
library. LBR accomplishes this by creating a new file that is a
compressed copy of the old library file. The old library file is not
deleted after the new file is created.
The /CO switch can be appended only to the output file specifier.
format for specifying the Compress switch is:

The

outfile/CO:size:ept:mnt • infile
outfile
Specifies the file that is to become the compressed version of
the input file. Default type is .OLB if input file is an object
library, .MLB if input file is a macro library, or .ULB if the
input file is a universal library.
/CO
Specifies the Compress switch.
:size
Specifies the size of the new library file in 256(10)-word
blocks. The size of the old library file is the default size.
:ept
Specifies the number of entry point table (EPT) entries to
allocate.
If the value specified is not a multiple of 64(10),
the next highest multiple of 64(10) is used. The number of EPTs
in the old library file is the default value. This parameter is
always forced to zero for macro libraries
and
universal
libraries. Maximum number of entries is 4096(10).
: mnt
Specifies the number of module name table (MNT) entries to
allocate.
If the value specified is not a multiple of 64(10),
the next highest multiple of 64(10) is used. The number of MNTs
in the old library file is the default value. Maximum number of
entries is 4096(10).
inf ile
Specifies the library file to be compressed. Default file type
is .OLB for object libraries, .MLB for macro libraries, and .ULB
for universal libraries.
The actual default file type is
determined by the current default library filetype (see Section
14.6.4).

14-10

ii iii ii!L

Jilli!!

. (

LIBRARIAN UTILITY PROGRAM (LBR)
Example
ILBR> RICK LIB/CO: 100.: 128.: 6 4. =SHE II.A. OLB
In this example, file SHEILA.OLB is compressed, and
RICKLIB.OLB, is created with the following attributes:

new

file,

size = 100(10) blocks
ept = 128(10) entry points
mnt = 64(10) module names
The new file, RICKLIB.OLB, receives a version number that is l version
greater than the latest version for the file.
Both files, RICKLIB.OLB
directory file on SYO:.

14.6.2

and

SHEILA.OLB,

reside

the

default

Create Switch (/CR)

Use the Create switch to allocate a contiguous library file on a
direct access device (for example, a disk).
It initializes the
library file header, the entry point table, and the module name table.
The /CR switch can be appended only to the output file
The format for specifying the Create switch is:

specification.

outfile/CR:size:ept:mnt:libtype:infiletype
outfile
Specifies the library file being created. The default file type
is .OLB if an object library is being created, .MLB if a macro
library is being created~ or .ULB if a universal library is being
created.
/CR
Specifies the Create switch.

Specifies the size of the library file in disk (256-word) blocks.
The default size is 100(10) blocks.
: ept
Specifies the number of entry point table (EPT) entries to
allocate.
The default value is 512(10) for object libraries.
This parameter is always forced to O for macro libraries and
universal libraries. Maximum number of entries is 4096(10).
: mnt
Specifies the number of
allocate.
The default
entries is 4096(10).

module name table
value is 256(10).

14-11

(MNT) entries to
Maximum number of

LIBRARIAN UTILITY PROGRAM (LBR)
: 1i btype
~

Specifies the type of library to be created.
Acceptable values
are OBJ for object libraries, MAC for macro libraries, and UNI
for universal libraries. The default is the last value specified
or implied with the /DF switch (see Section 14.6.4), or OBJ if
/DF has not been specified.

~-1~

:infiletype
Specifies the default input file type for the created universal
library.
If this value is not specified the default input file
type for universal libraries is .UNI. This value is not defined
for object or macro libraries.
If the values specified for ept and mnt are not multiples of 64(10),
EPT and MNT are automatically filled out to the next disk block
boundary.
Example

LBR>RICKLIB/CR: :·128.: 64.: OBJ=SHEILA,LAURA,JENNY
In this example, a combination of functions is performed. First, the
library file RICKLIB.OLB is created in the default directory on SYO:.
RICKLIB has the following attributes:
size = 100(10) blocks (default size)
ept
128(10) entry points
mnt = 64(10) module names
type = .OBJ
Second, object modules from the input files SHEILA.OBJ, LAURA.OBJ, and
JENNY.OBJ, which reside in the default directory on SYO:, are inserted
into the newly created library file. Insert is the default switch for
input files {see Section 14.6.8).

14.6.3

~
~·- ",.

Delete Switch (/DE)

Use the Delete switch to delete library modules and their associated
entry points {global symbols) from a library file. Up to 15 library
modules and their associated entry points can be deleted with one
delete command.
When LBR begins processing the /DE switch,
message on the initiating terminal: ·

prints

the

following

MODULES DELETED:
As modules are logically deleted from the library file, the module
name is printed on the initiating terminal. See the example at the
end of this section.
If a specified library module is not contained in the library file, a
message is printed on the initiating terminal, and the processing of
the current command is terminated. This message is as follows:
LBR -- *FATAL*-NO MODULE NAMED "name"
The /DE switch can be appended only to the library file specifier.

14-12

Jti

I ! $!i! H;:t

!)! ;

£2

Si! ¢4E

LIBRARlAN UTILITY PROGRAM (LBR)
When LBR deletes a module from a
library file,
the module is not
physically removed from the file, but is marked for deletion.
This
means that, although the module is no longer accessible,
the file
space that the module once occupied is not available for use (unless
the deleted module
is the last module which was inserted).
To
physically remove the module from the file and make the freed space
available for use, you must compress the library (see Section 14.6.1).
The form for specifying the Delete switch is:
outfile/DE:modulel[:module2 ••• :modulen]
outfile
Specifies the library file.
/DE
Specifies the Delete switch.
: module
Specifies the name of the module to be deleted.

Example
LBR>RICKLIB/DE:SHEILA:LAURA:JENNY
MODULES DELETED:
SHEILA
LAURA
JENNY
In this example, the modules SHEILA, LAURA,
and JENNY and their
associated entry points are deleted from the latest version of library
file SYO:RICKLIB.OLB.

14.6.4

Default Switch (/DF)

Use the Default switch to specify the default library file type.
Acceptable values are OBJ for object libraries,
MAC for macro
libraries, and UNI for universal libraries.
When a default library
file type is not specified by the /OF switch, .OBJ is the default
library file type.
Specifying a default value:

Sets the default file type argument
(/CR) •

Provides a file type default value of .MLB for
macro
libraries,
.ULB for universal libraries, and .OLB for object
libraries when opening an output (library)
file,
except
in
the cases of /CO and /CR. When /CO is specified, the default
applies to the library input file.
When /CR is specified,
the default file type is .OLB if an object library is being
created, .ULB if a universal library is being created,
or
.MLB if a macro library is being created. The /OF switch
only affects the name of the file to be opened;
thereafter,
the library header record information is used to determine
the type of library file being processed.
14-13

for

the

Create

switch

LIBRARIAN UTILITY PROGRAM (LBR)
The /DF switch can be issued alone or appended to a library
specifier. The form for specifying the Default switch is:

file

outfile/DF:filetype...
or
/DF: file type
out file
Specifies the library file.
/DF
Specifies the Default switch.
file type
Specifies the default library file type: OBJ for object library
files, MAC for macro library files, and UNI for universal library
files.
If a value other than OBJ, ULB, or MAC is specified, the
default library type will be set to object libraries,
following message will be displayed:

current
and the

LBR -- *FATAL*-INVALID LIBRARY TYPE SPECIFIED

Examples
LBR>/DF:MAC
LBR>RICKLIB=inf ile
File RICKLIB.MLB is opened for insertion.
LBR>/DF:MAC
LBR>RICKLIB/DF:OBJ=inf ile
File RICKLIB.OLB is opened for insertion.
LBR>/DF:MAC
LBR>RICKLIB/CR
Macro library RICKLIB.MLB is created.
LBR>/DF:MAC
LBR>RICKLIB/CR::::OBJ
Object library RICKLIB.OLB is created.
LBR>/DF
LBR>TEMP/CO=RICKLIB
RICKLIB.OLB is opened for compression. If RICKLIB.OLB is an object
library, the file TEMP.OLB is created to receive the compressed
output. If RICKLIB.OLB is a macro library (a nonstandard use of the
type .OLB), the file TEMP.MLB is created.
LBR>/DF:OBJ
LBR>TEMP/CO=RICKLIB.MLB
Assuming that file RICKLIB.MLB is a macro library, the macro
file TEMP.MLB is created to receive the compressed output.

library

14-14

:::

I ii

14"

LIBRARIAN UTILITY PROGRAM (LBR)
LBR>/DF': UN I
LBR>RICHLIB=TEST

~ile RICHLIB.ULB is opened for insertion.

14.6.5

Delete Global Switch (/DG)

Use the Deleite Global switch to delete a specified entry point (glo.bal
symbol)
from the EPT.
Up to 15 entry points may be deleted with one
command. This command does not affect the object module which
contains the actual symbol definition.
You may wish to delete an
entry point if'a module to be inserted has the same entry point.
When LBR be9ins processing the /DG switch,
message on the initiating terminal:

prints

the

following

ENTRY POINTS DELETED:
As entry points are deleted from the library file, t~e entry point is
printed on the initiating terminal. See the example at the end of
this section.
If a specified entry point is not contained in the EPT, a message
is
printed on the initiating terminal, and the processing of the current
command is terminated. This message is as follows:
LBR -- *FATAL* - NO ENTRY POINT NAMED "name"
The /DG switch can only be appended to the library file specifier.
The format for specifying the Delete Global switch is:
outfile/DG:globall[:global2 ••• :globaln]
outfllle
Specifies the library file.
/DG
Specifies the Delete Global switch.
global
Specifies the name of the entry point to be deleted.
Exam1~le

LBR>RICKLIB/DG:SHEILA:LAURA:JENNY
ENTRY POINTS DELETED:
SHEILA
LAURA
JENNY
In this example, the entry points SHEILA, LAURA, and JENNY are deleted
from the latest version of the library file named SYO:RICKLIB.OLB.

14-15

LIBRARIAN UTILITY PROGRAM (LBR)
14.6.6

Entry Point Switch (/EP)

Use the Entry Point switch to control (include or exclude) the
placement of global symbols in a library entry point table. The Entry
Point switch can be specified in either a positive or negative form:
/EP
/-EP
/NOEP

Include entry points in the entry point table.
Do not include entry points in the entry point table.
Do-not include entry points in the entry point table.

The positive form (/EP) causes all entry points in a module or modules
to qe entered in the library entry point table.
Either negative form (/-EP or /NOEP} provides for a module to be
included in a library while excluding the entry points in that module
from being entered in the library entry point table.
/EP is the LBR default; if the switch is not specified,
points are entered into the library entry point table.

all

entry

The Entry Point switch has no effect on macro or universal libraries.
The format for specifying the Entry Point switch is:
outfile[ /EP ]=infile, ••• infilen
[/-EP ]
[/NOEP]
or
outfile=infile[ /EP] [, ••• infilen[/EP ]]
[-/EP ]
[-/EP]
[/NOEP]
[/NOEP]
outfile
Specifies the output file.
When the entry point switch is
applied to this file specification, LBR assumes each of the input
files contains modules for which entry points are to be either
included or excluded.
inf ile
Specifies an input file. When the Entry Point switch is applied
to an input file specification, LBR assumes only the input files
to which the switch is applied contain modules for which entry
points are to be either included or excluded.
/-EP is useful for including modules which contain duplicate entry
point names in the same library. /-EP provides the means for entering
a module in the library without having its entry points included in
the library entry point table.
/-EP is also useful in the case where the Task Builder uses only
module names to search for modules in an object module library. In
this case, entries in the library entry point table are not required.
/-EP can be used to exclude entry points from being entered in the
library entry point table.
Depending on whether the Entry Point switch is applied to the output
specifier or to an input specifier, it has either a global or local
effect.

14-16

UIS$ $!I

iii

#ii

12 jJ

ill

;4 $.

LIBRARIAN UTILITY PROGRAM (LBR)

\....J

When applied to the output file specifier, the Entry Point switch has
a global effect. That is, LBR either includes all entry points in the
entry point table or excludes all entry points from being entered in
the entry point table.
When applied to an input file specifier, the Entry Point switch has a
local effect. That is, LBR eith~r includes entry points in the entry
point table or excludes entries from being entered in the entry point
table for only those modules to which the switch is applied.
The positive and negative forms of the switch may be applied to both
the output and input file specifiers. For example, the effect of /EP
applied to the output file can be overridden by applying /-EP to a
specific input file.
Entry points in an object module are not affected by the Entry Point
switch;
the Entry Point switch permits you to either include or
exclude entries in the library entry point table.

14.6.7

Extract Switch (/EX)

Use the Extract switch to extract (read) one or more modules from an
object or macro library file and write them into a specified output
file~
If more than one module is extracted, the modules are
concatenated in the output file. The extract operation has no effect
on the library file from which the modules are extracted;
that file
remains intact.
Up to eight modules may be specified in one extract
operation for object and macro libraries; however, only one module
may be specified in one extract operation for a universal library.
For object and macro libraries, if no modules are specified on
command
line,
all
modules in the library are extracted
concatenated in the output file in alphabetical order.
For universal libraries, RMS fields cannot be extracted
oriented device, such as a terminal.
The /EX switch may be applied only
format for specifying /EX is:

input

file

specifiers.

the
and

record
The

outfile=infile/EX[:modulenamel ••• :modulenamen]
outfile
Specifies the file into which extracted modules are to be stored.
The default file type for this file is .OBJ if the input modules
are object modules; the default file type is .MAC if the input
modules are macro modules.
If the library is a universal
library, the outfile retains the infile type of the module
extracted.
(However, you are allowed to extract only one
universal library module at a time.)
infile
Specifies the library file from which the modules are to be
extracted. The default file type for this file is .ULB, .OLB, or
.MLB, depending on the current default library type.
/EX
Specifies the Extract switch.

14-17

LIBRARIAN UTILITY PROGRAM (LBR)

modulename
Specifies the name
library.

the

module

extracted

from

the

_!"'·---.
_ _ ___ ._
~==-

, -~,

Examples

LBR>DRIVERS=RSXllM/EX:DXDRV:DKDRV:TTDRV
The object modules DXDRV, DKDRV,
written into the file DRIVERS.OBJ.

and

TTDRV

are

concatenated

and

LBR>TI:=[l,l]RSXMAC.SML/EX:QIO$S
The macro QIO$S is written to the issuing terminal.
LBR>TEST.OBS=TEST/EX
All of the modules in the library TEST.OLB are written into
TEST.OBS in alphabetical order.

14.6.8

the

file

Insert Switch (/IN) for Object and Macro Libraries

Use the Insert switch to insert library modules into a library file.
Any number of input files can be specified. For object libraries and
macro libraries, each input file can contain
any
number
of
concatenated input modules.
For macro libraries, only first-level
macro definitions are extracted from the input files.
All text
outside
of the first-level macro definitions is ignored.
LBR
recognizes only upper-case characters in macro directives.
(See
Insert Switches for Universal Libraries, Section 14.6.8.1.) The /IN
switch is the default library file option, and can be appended only to
the library file specifier.
If you attempt to insert an input module which already exists in the
library file, the following message is printed on the initiating
terminal:
LBR -- *FATAL* DUPLICATE MODULE NAME "name" IN filename
Likewise, if you attempt to insert a module and a module contains an
entry point that duplicates one that is already in the EPT, the
following message is printed on the initiating terminal:
LBR -- *FATAL* DUPLICATE ENTRY POINT "name" IN filename
The format for specifying the Insert switch is:
outfile[/IN]=infilel[,infile2, ••• infilen]
outf ile
Specifies the library file into which the input modules are to be
inserted.
The default file type depends on the current default
(see Section 14.6.4). It is .OLB if the current default is
object libraries, .MLB if the current default is macro libraries.
/IN
Specifies the Insert switch.

14-18

e: a

2.1

I:;

LIBRARIAN UTILITY PROGRAM (LBR)

inf ile
Specifies the input file containing modules to be inserted into
the library file. The default file type is .OBJ if outfile is an
object library and .MAC if outfile is a macro library.
Example

LBR>RICKLIB/IN=SHEILA,LAURA,JENNY
In this example, the modules contained in the latest versions of files
SHEILA, LAURA, and JENNY, which reside in the default directory on
SYO:, are inserted into the latest version of the library file
RIC~:LIB,
which also resides in the default directory on SYO:. The
default filetype for files SHEILA, LAURA, and JENNY is .OBJ if RICKLIB
is an object module library, or .MAC if RICKLIB is a macro library.
14.6.8.l Insert Switch (/IN) for Universal Libraries - The Insert
switch works basically the same for univer~al libraries as it does for
object libraries and macro libraries. However, when inserting a file
into a universal library, the /IN switch is normally applied to the
input file"
Furthermore, the user can specify module name and
descriptive information as switch values in the command line. Also,
LBR copies input file attributes to the module header.
The high block indicator (F.HIBK of the file's FOB) and the end of
file indicator (F.EFBK of the file's FOB) are included in the input
file's user file attributes. LBR makes the high block indicator equal
to the end of file indicator in the module header. This means that
when a module is extracted to a file, that file will have as many
blocks allocated as used.
The Insert switch format for universal libraries is:
outfile=infile/IN:name:op:op:op:op
outf ile
Specifies the universal library into which the file infile is
be inserted.

inf ile
Specifies the input file to be inserted into outfile.
The
default for the file type is the value indicated at the universal
library's creation time.
(See Section 14.6.2.)
/IN
Specifies the Insert switch.
:name
Optionally specifies the module name (up
to
6
Radix-SO
characters)"
The default is the first 6 characters of the input
file name.
: op
Specifies optional descriptive information (up to 6 Radix-SO
characters) to be stored in the module header. The default is
null. If only part of the information set is specified, all
preceding colons must be supplied.

14-19

LIBRARIAN UTILITY PROGRAM (LBR)
Example
LBR>RICKLIB.ULB=JOE.TXT/IN:MODl:THIS:IS:JAN2:TEXT
In this example, LBR inserts JOE.TXT into the universal library
RICKLIB.ULB as MOD!. "THIS", "IS", "JAN2", and "TEXT" are stored in
the module header.
You can insert JOE.TXT without the Insert switch and its values. As a
result, all the information normally specified by the switch values
defaults as described above.

14.6.9

List Switches (/LI, /LE, /FU)

Use the List switches to produce a printed listing of the contents of
a library file.
Three switches allow you to select the type of
listing desired. These switches are as follows:
/LI

Produces a listing of the names of all modules
library file.

the

/LE

Produces a listing of the names of all modules in
library file and their corresponding entry points.

the

/FU

Produces a listing of the names of all modules in the
library file and gives a full module description for
each:
that is, size,
date
of
insertion,
and
module-dependent
information.
Appendix B contains
sample listings of all three types of library listing.

These switches can be appended only to the output
the list file specifier.

file

specifier

it need not be specified when a
The /LI switch is the default value;
listing file has been specified or when any other List switch is
included in the command.
The format for specifying List switches is:
outfile[,listfile]/switch(es)
outfile
Specifies the library file whose contents is to be listed.
listfile
Optionally specifies the listing file.
If not
listing is directed to the initiating terminal.

specified,

the

/switch(es)
Specifies the list option(s) selected.

Examples
LBR> RICK LIB/LI
In this example, a listing of the names of all the modules contained
in file SYO:RICKLIB.OLB is printed on the initiating terminal.

14-20

2 " 222

LIBRARIAN UTILITY PROGRAM (LBR)
LBR>RICKLIB/LE
In this example, a listing of the names of all the modules and their
entry points
(contained in file SYO:RICKLIB.OLB) is printed on the
initiating terminal.
LBR>RI CK LIB/FU
In this example, a listing of the names of all the modules, and a full
description of each module contained in file SYO:RICKLIB.OLB, is
printed on the initiating terminal.
LBR>DKl: [200,200]RICKLIB,LP.LST:/LE/FU
In this example LBR creates file LP.LST in directory [200,200] on DKl:
with a listing of all the module names, their entry points, and a full
description of each module for file RICKLIB.

14. 6 .1 O

Modify Header Switch (/MB)

The Modify Header switch pertains only to universal libraries and
allows the user to modify the optional user-specified information in
the module header.
The format of the switch is:
outfile/MH:module:op:op:op:op
outJEi le
Specifies an output file for the
type defaults to .ULB.

universal

library.

The

file

/MH
Specifies the Modify Header switch.
:module
Specifies the name of the module whose descriptive information is
to be modified.
:op
Specifies the optional user information (up to 6 Radix-50
characters) to be stored in the module header. The default is
null and indicates that the corresponding information field is
not to be changed. Also, entering a pound sign (#) clears the
corresponding information field.
Exa:mple

The optional descriptive information for module A of RICKLIB.ULB is:
"MODA II "FCHCD" "OF" "FCH II
The LBR command is:
LBR>RICKLIB/MH:A:FCHTS:#::

14-21

LIBRARIAN UTI.LITY PROGRAM (LBR)

The optional descriptive information for Module A in file
changed to:
"FCHTS"

14.6.11

RICKLIB

"OF" "FCH II

Replace Switch (/RP)

Use the Replace switch to replace modules in a library file with input
modules of the same name. Any number of input files are allowed, and
each file can contain any number of concatenated input modules.
For ma~ro libraries, only first-level macro definitions are extracted
from the replacement files. LBR recognizes only upper-case characters
in macro directives.
When a match occurs on a module name, the existing module is logically
deleted, and all of its entries are removed from the EPT.
As each module in the library file is replaced, a message is printed
on the initiating terminal. This message, which contains the name of
the module being replaced, is as follows:
MODULE "name" REPLACED
If the module to be replaced does not exist in the library file, LBR
assumes that the input module is to be inserted and automatically
inserts it without printing a message.
The /RP switch can be specified in either of the following formats:
•

Global format - The /RP switch is appended to the library file
specifier, and all of the input files are assumed to contain
replacement modules.

•

Local format - The /RP switch is appended to an input file
specifier, and only the file to which the /RP switch is
appended is considered to contain replacement modules.

Global Format

outfile/RP=infilel[,infile2, ••• infilen]
outfile
Specifies the library file. The default type depends on the
current default (see Section 14.6.4). It is .OLB if the current
default is object libraries, or .MLB if the current default is
macro libraries.
/RP
Specifies the Replace switch.
inf ile
Specifies the input file that contains replacement modules for
the library file.
The default type is .OBJ if outfile is an
object library, or .MAC if it is a macro library.
This format of the /RP switch allows you to specify a list of input
files without having to append the /RP switch to each of them. To
override the global function for a particular input file (that is, to

14-22

4 22iii4 24

iii

LIBRARIAN UTILITY PROGRAM (LBR)
instruct LBR to process a particular file in a list as a file
containing modules to be inserted but not replaced), append /-RP or
/NORI? to the desired input file specifier.

Local Format
outfile=infilel [/RP][, infile2 [/RP], ••• infilen [/RP]]
outfile
Specifies the library file. The local format default is the same
as the global format default described above.
inf ile
Specifies the input file which will replace modules in the output
library file@ The local format default is the same as the global
format default described above.
/RP
Specifies the Replace switch. Appending the /RP switch to an
input file specifier constitutes the local format of the switch.
This overrides the LBR default
(Insert) and instructs LBR to
treat the module(s) contained in the specified file as modules to
be replaced.

Examples
The files used in the following four examples, and the modules
contained within each file, are depicted in Figure 14-8. For the
examples, these files are assumed to reside in the default directory
on the default device, and the initial state of the library file is
assumed to be as shown in Figure 14-8.
1.

LBR>RICKLIB/RP=SHEILA,LAURA,JENNY
MODULE
MODULE
MODULE
MODULE
MODULE

"SHEILA" REPLACED
"LAURAl" REPLACED
"LAURA2" REPLACED
"JENNYl" REPLACED
"JENNY2" REPLACED

In this example, the global format for the /RP switch is used. Object
modules from the input files SHEILA, LAURA, and JENNY replace modules
by the samH names in the 1i brary file named RICK LIB and modules JENNY3
and LAURA3 are inserted.
The resulting library file is shown in
Figure 14-9.
2.

LBR>RICKLIB=CHRIS,SHEILA/RP
MODULE "SHEILA" REPLACED

In this example, the local format of the /RP switch is used.
The
object module SHEILA from file SHEILA is replaced in the library file
RICKLIB. The object modules in the file CHRIS are inserted in the
library file.
(See Insert switch in Section 14.4.8.) The resulting
library file is shown in Figure 14-10.

14-23

LIBRARIAN UTILITY PROGRAM (LBR)

LBR>RICKLIB/RP=SHEILA,LAURA,JENNY,CHRIS/-RP
MODULE
MODULE
MODULE
MODULE
MODULE

"SHEILA II REPLACED
"LAURAl" REPLACED
"LAURA2" REPLACED
"JENNYl" REPLACED
"JENNY2" REPLACED

In this example, the /-RP switch is used to override the global format
of the command. Object modules in files SHEILA, LAURA, and JENNY are
processed as modules to be replaced, and file CHRIS is processed as a
file which contains modules to be inserted. The resulting library
file is shown in Figure 14-11.
4.

LBR>RICKLIB/RP=SHEILA,LAURA/-RP,JENNY
MODULE "SHEILA" REPLACED
LBR -- *FATAL* -- DUPLICATE MODULE "LAURAl" IN LAURA.OBJ;!

In this example, only module SHEILA from file SHEILA was replaced.
The user specified that the modules in file LAURA not be replaced
(/-RP), but inserted. One of the modules contained in file LAURA
duplicated an already existing module in file RICKLIB (see Figure
14-8). Therefore, LBR issued the fatal error message and terminated
the processing of the current command.

Output
Library File
File Name

RICKLIB.OLB:l
JENNY!

Input Files
SHEILA.OBJ:!

LAURA.OBJ:!

JENNY.OBJ:!

CHRIS. OBJ: 1

SHEILA

LAURA!

JENNY!

CHRIS!
CHRIS2

Object

JENNY2

LAURA2

JENNY2

Modules

LAURA!

LAURA3

JENNY3

LAURA2
SHEILA

Figure 14-8

Sample Files Used in LBR Examples 1-4

14-24

111111•

£t

$!$

a::

LIBRARIAN UTILITY PROGRAM (LBR)

RICKLIB.OLB;l

\..,l
JENNY!
JENNY2
JENNY3

LAURA!
LAURA2
LAURA3

SHEILA
*These modules did not exist on the
library file prior to the execution of
this example, but they did exist on the
input files.
LBR, therefore, assumed
that they were to be inserted.
Since
LBR handled these modules as a normal
insert, no message was printed on the
input terminal.
Figure 14-9

Output Library File After Execution of Example 1

RICKLIB.OLB;l
CHRISl

CHRIS2

JENNYl
JENNY2
LAURA!
LAURA2

*
*This module replaced
**These modules inserted
Figure 14-10

Output Library File After Execution of Example 2

14-25

LIBRARIAN UTILITY PROGRAM (LBR)

RICKLIB.OLB;l
CHRIS!

CHRIS2

JENNY!
JENNY2
JENNY3

LAURA!
LAURA2
LAURA3

SHEILA
*These modules were inserted by default.
**These modules were specified to be
inserted. Had a module of the same name
been present, a fatal error message
would have been issued. See Example 4
above.
Figure 14-11

Output Library File After Execution of Example 3

·~

14.6.11.1 Replace Switch (/RP) for Universal Libraries - Use the /RP
switch for universal libraries in the same way as for macro and object
libraries. In addition, you can specify the same values for the
Replace switch as for the Insert switch for universal libraries.
(See
Section 14.6.8.1). However, you can specify the /RP switch with
either the infile or the outflle.
(See the example below}.
The global Replace switch format for universal libraries is:
outfile/RP:name:op:op:op:op=infile[,infile2, •••• infilen]
The local Replace switch format for universal libraries is:
outfile=infile/RP:name:op:op:op:op[,infile2 •••• infilen]
outfile
Specifies the universal library file.
inf ile
Specifies the input file which will replace modules in the
library file.
The default for the file type is the value
indicated at the universal library's creation time.
(See Section
14.6.2).
/RP
Specifies the Replace switch.

14-26

p;mz

LIBRARIAN UTILITY PROGRAM (LBR)

: name
Optionally specifies the module name to be replaced (up to 6
Radix-SO characters). The default is the first six characters of
the inf ile name.
: op
Specifies optional descriptive information (up to 6 Radix-SO
characters) to be stored in the module header. The default is
null. If only part of the information set is specified all
preceding colons must be suppliedo
Exam1»le

LBR)TEXT.ULB=DEBBIE.TXT/RP::THIS:IS:JAN3:UPDATE
MODULE "DEBBIE" REPLACED
In this example, LBR replaces the DEBBIE module in the universal
library TEXT.ULB with an updated module from file DEBBIE.TXT. The
date of replacement is specified by the user optional information and
inserted in the module header.
Note that the optional name is
omitted.
The initial state of the library file is shown in Figure
resulting library file is shown in Figure 14-13.

File Name
Modules

Output
Library File

Input Files

TEXT.ULB;l

DEBBIE.TXT

14-12.

The

DEBBIE
BERNrn

Figure 14-12 Sample Files for Universal Library Replace Example

TEXT.ULB;l
DEBBIE
BERNIE

*The module DEBBIE was replaced.
If a
different inf ile were specified, that
file would become module DEBBIE and
occupy the same location in TEXT.ULB.
Figure 14-13 Output Library File After Execution of
Universal Library Replace Example

14.6Dl2

Spool Switch (/SP)

The Spool switch is the list file default switch. Whether the switch
is specified or not, the results are the same, that is, the listing
file is spooled to the line printer.

14-27

LIBRARIAN UTILITY PROGRAM (LBR)

After the listing file is created, a request is made to the print
spooler task to print the spooled file;
printing is performed
asynchronously (see Appendix C for a description of the spooler task).
The automatic printing of the listing file can be inhibited by
specifying a minus sign (-) or the letters NO between the slash (/)
and the SP in the spool switch (/-SP or /NOSP).
This causes the
listing file to be created, but the request to the print spooler task
is not issued. Therefore, the file is not automatically printed.
The /SP switch can only be appended to the list file specifier.
The format for specifying the Spool switch is:
out f i 1e , 1 i st f i 1e [ISP] o r [I -s P]
outf i 1-e
Specifies the library file.
listfile
Specifies the listing file.
/SP or /-SP
Specifies the Spool switch.
Example

LBR>RICKLIB/DE:SHEILA,RICKLST/-SP
In this example, the following occurs:
1.

The module SHEILA and its associated entry points are deleted
from the library file SY:RICKLIB.

The listing of the contents of the resulting library file
RICKLIB is written to the list file SY:RICKLST.LST. Since
the /-SP switch is specified, the file is not automatically
printed.

14.6.13

Selective Search Switch (/SS)

Use the Selective Search switch to set the selective search attribute
bit in the module header of object modules as they are inserted into
an object library. The switch has no effect when applied to modules
being inserted into a macro library. The switch may be specified only
on input files for insertion or replacement operations, and it affects
all modules in the input file to which it is applied.
Object modules with the selective search attribute are given special
treatment by the Task Builder. Global symbols defined in modules with
the selective search attribute are only included in the Task Builder's
symbol table if they are previously referenced by other modules.
Thus, only referenced symbols will be listed with the module in the
Task Builder memory allocation file, thereby reducing task build time.
The /SS switch should only be applied to object files whose modules
contain only absolute (not relocatable) symbol definitions. See the
RSX-llM/M-PLUS Task Builder Manual for more information.

14-28

404 iii

ii'*

LIBRARIAN UTILITY PROGRAM (LBR)
The format for specifying the Selective Search switch is:
outfile=infilel/SS[,infile2[/SS], ••• infilen[/SS]]
outf ile
Specifies the library file.
inf i le
Specifies the input file that contains modules to be
searchE!d.

selectively

/SS
Specifies the Selective Search switch.

14. 6 .14

Squeeze Switch (/SZ)

Use the Squeeze switch to reduce the size of macro definitions by
eliminating all trailing blanks and tabs, blank lines, and comments
from macro text. The /SZ switch is used to conserve memory in the
MACR0-11 Assembler and to reduce the size of macro library files. The
Squeeze switch has no effect on object libraries or universal
libra1ries.
The /SZ switch can be specified in either of the following formats:
•

Global format - The /SZ switch is appended to the library file
specifier, and all of the input files are assumed to contain
modules to be squeezed.

•

Local format - The /SZ switch is appended to an input file
specifier, and only the file to which the /SZ switch is
appended is considered to contain modules to be squeezed.

Globa1l Format

outfile/SZ=infilel[,infile2, ••• infilen]
outfi.le
Specifies the library file.
/SZ
Specifies the Squeeze switch.
inf ile
Specifies the input file that contains modules
during insertion into the library file.

squeezed

Use this format of the /SZ switch to specify a list of input files
without having to append the /SZ switch to each of them. To override
the global function for a particular input file (that is, to instruct
LBR to process a particular file in a list as a file containing
modules to be inserted but not squeezed), append /-SZ or /NOSZ to the
desired input file specifier.

14-29

LIBRARIAll UTILITY PROGRAM (LBR)

Local Format
outfile=infilel/SZ[,infile2[/SZ], ••• infilen[/SZ]]
out file
Specifies the library file.
inf ile
Specifies the file that contains modules to
insertion into the library file.

squeezed

during

/SZ
Specifies the Squeeze switch.
LBR uses the following algorithm on each line to be squeezed and
inserts the resulting line into the library file:
1.

The line is examined for the rightmost semicolon (;).

If a semicolon is located, it is
trailing characters in the line.

All trailing blanks and tabs in the line are deleted.

If the resulting line is null, nothing is transferred to
library file.

deleted,

along

with

then

all

i-~

the

If the line contains a semicolon embedded in meaningful (non-comment)
text and you want comments squeezed, code a dummy comment for that
line. /SZ uses only this rightmost comment during squeeze processing.

Example
Figure 14-14 illustrates the use of the LBR /SZ switch.
A file
containing input text to be squeezed is illustrated, along with the
text actually inserted into the library file after the squeeze
operation has been completed.

14-30

u!( :::

;::

45\

LIBRARIAN UTILITY PROGRAM (LBR)
BEFORE BEING SQUEEZED
.MACRO

MOVSTR RX,RY,?I.BL

•***

- ·- NOTE :
BOTH ARGUMENTS MUST BE REGISTERS

LBL:

MOVB
BNE
DEC

(RX)+, (RY)+
LBL
RY

;MOVE A CHARACTER
;CONTINUE UNTIL NULL SEEN
;BACKUP OUTPUT PTR TO NULL

;END OF MOVSTR
.ENDM
AFTER BEING SQUEEZED

,• ***'
;

LBL:

'-'/'

.MACRO MOVSTR RX,RY,?LBL
- - NOTE :
BOTH ARGUMENTS MUST BE REGISTERS
MOVB
(RX)+,(RY)+
BNE
LBL
DEC
RY
.ENDM
Figure 14-14 MACRO Listing Before
and After Running LBR with /SZ Switch

14.7

COMBINING LIBRARY FUNCTIONS

Two or more library functions may be requested in the same command
line.
The only exceptions are that /CO cannot be requested with
anything else except /LI, and /CR and /DE cannot be specified in the
same command linee
Functions are performed in the following order:
2.
3.
4.

/DF
/CR
/DE
/DG
/MH

6.
7.
8.
9.

/IN, /RP, /SS, /SZ, /EP
/CO
/EX
/LI, /LE, /FU, /SP

Example
LBR>FILE/DE:XYZ:$A,LP.LST:/LE/FU=MODX,MODY/RP
Functions are performed in order, as:
1.

Delete modules XYZ and $A.

Insert all modules from MODX and replace duplicate modules of
MODY.

P reduce a listing of the resultant library file on the line
printer with full module descriptions and all entry points.

14-31

LIBRARIAN UTILITY PROGRAM (LBR)

14.8

LBR RESTRICTIONS

The following restrictions apply when using LBR:
•

Limit of 65,536(10) words per module.

•

Limit of 65,536(10) blocks per library.

should be allocated
• Tables
Expanding table allocations

to maximum anticipated size.
requires using Compress to copy

the entire file.
•

A fatal error results if an attempt is made to insert a module
into a library that contains a module with a different name
from, but with the same entry point as, the inserted module.
For further information, refer to the discussion of the /IN
switch in Section 14.6.8.

•

The use of wildcards in file specifiers is not allowed (that
is, forms such as *.OBJ, where the * indicates all modules
with type .OBJ).

There must be enough space in the library's tables for both the
modules being replaced and their replacements, since the new modules
are entered and the old modules are logically but not physically
deleted.

14.9

LBR ERROR MESSAGES

There are two types of LBR error messages:

diagnostic and fatal.

Diagnostic error messages describe a condition that exists that
requires consideration, but the nature of the condition does not
warrant termination of the command. Diagnostic messages are issued to
TI:, in the format:
LBR -- *DIAG* - message
Fatal error messages describe a condition that exists that caused LBR
to terminate the processing of a command. When this occurs, LBR
returns to the highest level of command input. For example, if the
command is entered in response to the MCR prompt, that is,
>LBR command
then, LBR issues the fatal error message and exits. If, however,
command is entered in response to the LBR prompt, that is,

the

LBR>command
LBR issues the fatal error message and reprompts.
Fatal error messages are issued to TI:, in the format:
LBR -- *FATAL* - message
If a fatal error occurs during the processing of an indirect command
file, the command file is closed, the fatal error message - followed
by the command line in error - is issued to TI:, and LBR returns to
the highest level of command input.

14-32

Ult 5 Cl $

4 Li

221 I

JUBRARIAN UTILITY PROGRAM (LBR)
14.9.l

Effect of Fatal Errors on Library Files

The status of a library file after fatal errors is:

During the deletion process, the library is rewritten prior
to the printing of the individual module-/entry-point-deleted
messages ..

During the replacement process, the library is rewritten
prior to the printing of the individual module-replaced
messages ..

During the insert process, the library is rewritten after the
insertion of all modules in each individual input file, that
is, between input files.

LBR

BAD LIBRARY HEADER

the

LBR Error Messages

leave

In general, output
indeterminate state.

14.9.2

errors

library

Explanation: Either the file is not a library file or
is corrupted ..

the

file

command

line

User Action:
•

If the file is not a library file, reenter the
with a proper library file specified.

•

If the file is a proper library file, the user should run the
file structure verification utility (VFY) against the volume
to determine if it is corrupted (see Chapter 13).

•

If the volume is corrupted, it must be
it can be used.

reconstructed

before

LBR -- CANNOT MODIFY HEADER

\....-··

Explanation: An attempt was made to modify the module header of
a module in an object library or macro library. No change is
made to the module header.
User Action: Reenter the command line, specifying a module in
universal library.

14-33

LIBRARIAN UTILITY PROGRAM (LBR)

LBR -- COMMAND I/O ERROR
Explanation:

One of the following conditions may exist:

•

A problem exists on the physical
cycled up).

device

(for

•

The file is corrupted or the format is
example, record length exceeds 132 bytes).

example,

not

incorrect

(for

User Action: Determine which of the above conditions caused
the message and correct that condition. Reenter the command
line.

LBR -- COMMAND SYNTAX ERROR
command line
Explanation: A command was entered in a
conform to syntax rules.
User Action:

format

that

does

not

Reenter the command line, using the correct syntax.

LBR -- DUPLICATE ENTRY POINT NAME "name" IN filename
Explanation: An attempt has been made to insert a module into a
library file when both contain an identically-named entry point.
User Action: Determine if the specified input file is
correct file.
If not, reenter the command line, specifying
correct input file. If the input file is the correct file,
user may delete the duplicate entry point from the library
reenter the command line.

the
the
the
and

LBR -- DUPLICATE MODULE NAME "name" IN filename
Explanation:
An attempt has been made to insert (without
replacement) a module into a library that already contains a
module with the specified name.
User Action: Determine if the specified input file is the
correct file.
If the input file is correct, decide whether to
delete the duplicate module from the library file and insert the
new one, or replace the duplicate module by rerunning LBR with
the /RP switch appended to the input file specifier.

LBR -- EPT OR MNT EXCEEDED IN filename
Explanation: The EPT or MNT table limit has been reached
the execution of an Insert or Replace command.
User Action: Copy the library, increasing the table
the Compress switch. Reenter the command line.

during

space

via

14-34

L!S

!iii

LIBRARIAN UTILITY PROGRAM (LBR)

LBR -- EPT OR MN'l' SPACE EXCEEDED IN COMPRESS
Explanation: An EPT or MNT table size was specified for the
output library file that is not large enough to contain the EPT
or MNT entrjes used in the input library file.
User Action: Reenter the command line with a larger EPT
table size specified.

MNT

LBR -- ERROR IN LIBRARY TABLES, FILE filename
Explanation:
file.

The library file is corrupted or is not

library

User Action: If the file is corrupted, no recovery is possible;
the file must be reconstructed. If the file is not a library
file, reenter the command line with the correct library file
specified.

LBR -- EXACTLY ONE INPUT FILE MUST APPEAR WITH /CO
Explanation: No file or more than one
specified when using the /CO switch.
User Action:
specified.

input

library

Reenter the command line with only one

file

was

input

file

LBR -- FATAL COMPRESS ERROR
Explanation: The input library file is corrupted
library file.
User Action: No recovery is possible.
be reconstructed.

not

The file in question must

LBR -- GET TIME FAILED
Explanation: This error occurs when LBR attempts to execute a
Get Time Parameters directive and fails. The error is caused by
a system malfunction.
User Action: Reenter the command line. If the problem persists,
submit a Software Performance Report along with the related
console dialogue and any other pertinent information.

LBR -- ILLEGAL DEVICE/VOLUME
command line
Explanation: Device specifier entered does not conform to syntax
rules.
A device specifier consists of 2 ASCII characters,
followed by one or two optional octal digits.
User Action: Reenter the command line with
syntax specified.

14-35

the

correct

device

LIBRARIAN UTILITY PROGRAM (LBR)

LBR -- ILLEGAL DIRECTORY
command line
Explanation: UFO entered does not conform to syntax rules.
UFO
syntax consists of a left square bracket, followed by one to
three octal digits, a comma, one to three octal digits, and
terminated by a right square bracket.
User Action:
syntax.

Reenter the

command

line

with

the

correct

UFO

LBR -- ILLEGAL FILENAME
command line
Explanation:

One of the following was entered:

•

A file specifier that contains a wildcard.

•

A file specifier that contains
file type.

User Action:

neither

file name

nor

read

Reenter the command line correctly.

LBR -- ILLEGAL GET COMMAND LINE ERROR CODE
Explanation: The system, for some reason, is unable
command line. This is an internal system failure.

User Action: Reenter the command line. If the problem persists,
submit a Software Performance Report along with the related
console dialogue and any other pertinent information.

LBR -- ILLEGAL SWITCH
command line
Explanation: A non-LBR switch was specified or
was specified in an invalid context.
User Action: Reenter the command line with
specification.

the

legal

switch

correct

switch

LBR -- ILLEGAL SWITCH COMBINATION
Explanation:
combination.

Switches were entered that cannot
See Section 14.7.

User Action: Reenter the command line, specifying
in the proper sequence.

executed
the

switches

LBR -- INDIRECT COMMAND SYNTAX ERROR
command line
Explanation: An indirect file was specified
does not conform to syntax rules.
User Action:

format

that

Reenter the command line with the correct syntax.

14-36

''-•ll••••t•U•••tll..i••••••••••••••••••••••t ••••••••••••••t••••-.i;;..:•

•&4,.

LIBRARIAN UTILITY PROGRAM (LBR)

LBR -- INDIRECT FILE DEPTH EXCEEDED
command line
Explanation: An attempt has been made to
indirect command files.
User Action: Rerun the job
command file.

with

only

exceed
one

level

one

level

indirect

LBR -- INDIRECT FILE OPEN FAILURE
command line
exist

Explanation: The requested indirect command file does not
as specified. One of the following conditions may exist:

•
•
\..,i

•
•
•
•

The user directory area is protected against access •
A problem exists on the physical device (for example,
cycled down).

device

The volume is not mounted •
The specified file directory does not exist •
The file does not exist as specified •
Insufficient dynamic memory in Executive •

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.
LBR -- INPUT ERROR ON filename
Explanation: The file system, while attempting to process an
input file, has detected an error. A problem exists with the
physical device (for example, the device cycled down}.
User Action:

Reenter the command line.

LBR -- INSUFFICIENT DYNAMIC MEMORY TO CONTINUE
Explanation:

The partition in which LBR is running is too small.

User Action: Remove the task (LBR), install it in a larger
partition, and reenter the command line.
(See the MCR RUN /INC
command description in the RSX-llM/M-PLUS MCR Operations Manual.)
LBR -- INVALID EPT AND/OR MNT SPECIFICATION
Explanation: An EPT or MNT value
entered in a /CR or /CO switch.
User Action:
specified.

greater

Reenter the command line

14-37

with

than

4096(10)

the

correct

was
value

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- INVALID MODULE FORMAT, insertion module
Explanation: An attempt was made to insert a macro
an object library.

module

into

User Action: Determine if an object file was to be inserted into
an object library.
If so, reenter the command line with the
correct object file. If a macro library was to receive the
insertion, reenter the command line with the correct macro
library.
LBR -- INVALID FORMAT, INPUT FILE filename
Explanation: The format of the specified input file is not the
standard format for a macro source or object file, or the input
file is corrupted.
User Action: Reenter the command line
file specified.

with

the

correct

input

LBR -- INVALID OPERATION FOR OBJECT AND MACRO LIBRARIES
Explanation: Module header information was supplied for an
object library or macro library in an Insert or Replace command.
User Action: No action required. The command will
as if the information had not been supplied.

executed

LBR -- INVALID LIBRARY TYPE SPECIFIED
Explanation: An il1egal library type was specified when using
the Create or Default switch. The values OBJ, MAC, and UNI are
the only valid specifications. See Sections 14.6.2 and 14.6.4.
User Action:
specified.

Reenter the command line

with

OBJ,

MAC,

UNI

LBR -- INVALID NAME -- "name"
Explantion: A module name that contains a non-Radix-SO character
has been specified for deletion, insertion, or replacemant of a
module in a universal library or in a macro module, or a module
name has been specified for modification of a universal module
header. Radix-SO characters consist of the letters A through z,
the numbers O through 9, and the special characters period (.)
and dollar sign ($).
User Action:

Reenter the command line with a valid name.

LBR -- INVALID RADSO CHARACTER IN "character string"
Explanation: A character supplied as part of information when
using the Insert, Replace, or Modify Header switch for a
universal library is not a Radix-SO character.
User Action: Determine which character of
switch value is not a Radix-SO character.
character in place of the invalid character.

the corresponding
Reenter a Radix-50

14-38

l••.t••4•&••.---------------------·llm•••••••••••lllllllli•:a•••:•. .

~--••t•Sllll

llljlll4f-'

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- I/O ERROR ON INPUT FILE filename
Explanation: A read error has occurred on an input file.
the following conditions may exist:
•

A problem exists on the physical
cycled up).

device

(for

•

The file is corrupted or the format is wrong
exceeds 132 bytes).

One of

example,
(record

not

length

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter that command line.
LBR -- LIBRARY FILE SPECIFICATION MISSING
Explanation:
library file.

command

was

entered

User Action:
specHied.

Reenter the command

specifying

the

library

file

Explanation:
When
LBR
begins
processing
commands,
automatically creates a work file and marks it for delete.
some reason, this marking for delete failed.

it
For

line

without
with

the

LBR -- MARK FOR DELETE FAILURE ON LBR WORK FILE

The w<>rk file constitutes a lost file, because it does not appear
in any file directory.

\._,·

User Action: The file may be deleted by running
structure verification utility (VFY) (see Chapter 13).

the

file

LBR -- MULTIPLE MODULE EXTRACTIONS NOT PERMITTED FOR UNV MODULES
Explanation: An attempt was made to extract more than one module
from
a universal library.
The first module specified is
extracted but others are ignored.
User Action:
extra<::tion.

Reenter

the

command

line

for

each

additional

LBR -- NO ENTRY POINT NAMED "name"
Explanation: The entry
specified library file.

point

deleted

not

the

User Action: Determine if the entry point is misspelled or if
the wrong library file is specified. Reenter the command line
with the entry point correctly specified.

14-39

LIBRARIAN UTILITY PROGRAM (LBR)
LBR

NO MODULE NAMED "module"

Explanation: The module to be deleted is not
library file.

the

specified

User Action: Determine if the module name is misspelled or if
the wrong library file is specified. Reenter the command line
with the module name correctly specified.
LBR -- OPEN FAILURE ON FILE filename

Explanation: The file system, while attempting to open a file,
One of the following conditions may
has detected an error.
exist:
•

The user directory area is protected against an open.

•

A problem exists on the physical device (for example,
cycled down).

•
•

The volume is not mounted •

•

The file does not exist as specified.

•

Insufficient contiguous space to allocate
(Compress and Create only).

•

Insufficient dynamic memory in Executive.

device

The specified file directory does not exist •

the

library

file

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter that command line.
LBR -- OPEN FAILURE ON LBR WORK FILE

Explanation: The file system, while attempting to open the LBR
work file, has detected an error. The LBR work file is created
on the volume from which LBR was installed. One of the following
conditions may exist:
•

The volume is full.

•

The device is write-protected •

•

A problem exists with the physical device.

•

Insufficient dynamic memory in Executive.

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.

14-40

t ii 4

Id 3iS! 1J&!H !;

ii I

2 JS

40;

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- OUTPUT ERROR ON filename
Explanation: A write error has occurred on the output file.
of the following conditions may exist:
•

The volume is full.

•

The device is write-protected~

•

The hardware has failed.

One

User Action: If the volume is full, delete all unnecessary files
and rerun LBR.
If the device is write-protected, write-enable
the device, and reenter the command line. If the hardware has
failed, swap devices and reenter the command line or wait until
the device is repaired and rerun LBR.
LBR -- POSITIONING ERROR ON filename
Explanation:

The device is write-locked.

User Action: If the device is write-locked, write-enable it
reenter the command line.

and

LBR -·- RMS l!"'I LES CANNOT BE EXTRACTED TO RECORD ORIENTED DEVICE
Explanation: An attempt was made to extract to a record-oriented
device a module inserted from a non-sequential RMS file. This is
a fatal error message.
User Action: Extract the file to a disk and
conversion to make an RMS sequential file.

then

use

RMS

LBR ··- TOO MANY OUTPUT FI LES SPEC! FIED
Explanation: More than two output
makes the following assumptions:

files

were

specified;

LBR

•

The first output file specified is the output library file.

•

The second output file specified is the listing file.

•

The third through n files specified to the left of the
sign are ignored.

User Action: No action is required.
extra file(s) were not specifiede

equal

LBR continues as though the

LBR -- VIRTUAL STORAGE REQUIREMENTS EXCEED 65536 WORDS
Explanation: This error may occur with maximum size libraries in
conjunction with a single command line which logically deletes a
large number of modules and entry points, and continues to
replace them with an equally large number of modules and entry
points having highly dissimilar names.
Normally, this message
indicates some sort of internal system error.
User Action: Rerun the job, but divide the complicated command
line into several smaller command lines that do the same
operations.

14-41

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- WORK FILE I/O ERROR

Explanation: A write error has occurred on the
One of the following conditions may exist:
•

The volume is full.

•

The device is write-protected.

•

The hardware has failed.

LBR

work

file.

User Action: If the volume is full, delete all unnecessary files
and rerun.
If the device is write-protected, write enable the
device, and reenter the command line.
If the hardware has
failed, swap devices and retry the command, or wait until the
device is repaired and rerun LBR.

14-42

LU 2 I I

pre:

CHAPTER 15
FILE DUMP UTILITY (DMP)

15.l

INTRODUCTION TO DMP

The F:ile Dump utility (DMP) program produces a printed listing of the
contents of a file or volume. The listing can be directed to any
suitable output device
line printer, terminal, magnetic tape,
DECtape, or disk. DMP runs in two modes, file mode and device mode.

\.,J

DMP nc:>rmally handles physical records of up to 2048 bytes in length.
If a physical record is larger than 2048 bytes, use the following
procedure:
:>RUN $DMP /INC=n
where n is at least equal to the number of words in the record minus
1024.
The value of n is interpreted as an octal number unless it is
followed by a decimal point.
DMP can be invoked using any of the methods described in Chapter 1.

15.1.l

File Mode

In file mode, one input file is specified and all, or a specified
range
(see /BL:n~m) of virtual blocks of the named file is dumped.
The input device must be a Files-11 structured volume and must be
mounted via the MCR Mount command. M-PLUS users must mount the volume
via the MCR Mount/Foriegn command.
(For a description of MOUNT, see
the RSX-llM/M-PLUS MCR Operations Manual.)

"'-"'

A virtual block refers to a block of data in a file.

Virtual blocks
n, where n is the total

are numbered sequentially from l through
number of virtual blocks in the file.

15.1.2

Device Mode

In device mode, only the input device is specified, and a specified
range
(/BL:n:m) of logical blocks is dumped. The /BL:n:m switch is a
required parameter.
A logical block refers to an actual 512-byte block on disk and
DECtape, and physical records on magnetic tape and cassette. Logical
blocks are numbered from 0 to n-1, where n is the total number of
logical blocks on the device.

When DMP is in device mode, the volume
mounted via the MCR Mount command.

15-1

dumped

must

not

FILE DUMP UTILITY (DMP)
15.2

DMP COMMAND STRING

Enter DMP command strings in the following format:
[outfile] [/sw] [/sw ••• ] [=infile] [/sw] [/sw ••• ]
outfile
Specifies the output file. If the output file name and file type
are null, DMP creates the file DMPFIL.DMP. Later defaults for
DMPFIL.DMP will take the version number n+l.
/sw
Specifies one of the switches listed in Section 15.3.
Unless
otherwise indicated in a switch description, all switches can be
applied either to the input file or to the output file with equal
effect.
inf ile
~.··.,

Specifies the input file. The equal sign and the input file name
and file type are required; DMP does not provide a default for
either the file name or type.
The input file version number
defaults to the latest version.

For a complete description of file specifications see Section 1.3.

15.3

DMP SWITCHES

DMP switch specifications consist of a slash (/} followed by a switch
name, optionally followed by a value, which is separated from the
switch by a colon (:}. DMP functions are implemented by means of the
switches described in Table 15-1.

. ' ··r

Table 15-1
DMP Switches
Description

Switch
Default

Word mode octal dump.

/AS

Specifies that the data should be dumped in
ASCII mode.
The control characters (0-37}
are printed as ~, followed by the alphabetic
character corresponding to the character code
plus 100. For example, bell
(code 7) is
printed
as
~G
(code 107).
Lower case
characters
(140-177} are printed
as
%,
followed by the corresponding upper case
character (character code minus 40).
(continued on next page}

15-2

1~tzaa

i!Jiiiii ii iii I i!i!L! ; ii

124 "

2 SS

a au

FILE DUMP UTILITY (DMP)
Table 15-1 (Cont.)
DMP Switches
Switch

Description

~··~--------------~---t---------------------~--------------------~---------t

/BA:n:m

Specifies a 2-word base block address,
where
n = high-order base block address (octal),
and m =low-order base block address (octal).
When specified, all future block numbers will
be added to this value to obtain an effective
block number.
This switch
is useful for
specifying block numbers that exceed 16 bits.
For example:
DMP>/BA:l:O
specifies that all future block numbers
be relative to 65536(10) (200000(8)).

will

DMP>/BA:O:O
clears the base address.
When the /BA switch appears
in a command
line,
no blocks are dumped;
the only result
of the command is to set the base address.
/BL:: n: m

Specifies the range of blocks to be dumped,
where n is the first block and m is the last
block.
In file mode only, the /BL switch
is
not
required.
If /BL is not specified, DMP
will dump all blocks of the specified file,
relative to the current address.
If the /BL:n:m switch is specified in file
mode,
it specifies the
range of virtual
blocks to be dumped.
If the /BL:n:m switch
is specified as /BL:O
in file mode,
no
virtual blocks are dumped.
This is useful
for dumping only the header portion of the
f i l e (see /HD) •
The /BL:n:m switch is a required parameter in
device mode.
When used in device mode, it
specifies the range of logical blocks to be
dumped.
Magnetic tapes and cassettes, when dumped in
device mode, are always dumped starting with
the current tape position;
that
is,
the
values given with the /BL switch are ignored.
The switch values are used, however, to label
the
pages of the dump listing,
and to
determine the number of blocks to dump.
When
a switch value of /BL:n:m is specified, m-n+l
blocks are dumped, starting at the current
tape position.

/BY

Specifies that the data should be
byte octal format.

dumped

(continued on next page)

15-3

FILE DUMP UTILITY (DMP)
Table 15-1 (Cont.)
DMP Switches
Switch

Description

/DC

Specifies that the data should be
decimal word format.

/DENS:n

Specifies the density of a
TU16
input
magnetic tape when DMP is in device mode
only. The value for n can be 800 or 1600.

dumped

DMP does not automatically determine the
density of an input tape.
If the /DENS
switch is not specified in a DMP command, DMP
attempts to read an input tape at the density
currently set in the tape controller.
(See
the RSX-llM/M-PLUS MCR Operations Manual for
a description of the MCR Mount command and
its /DENS switch).
/FI:file-number:
sequence-number

The
file
number,
used as input
identifier, can be used instead of a
name as a file identifiar.

file
file

/HD[:F or :U]

This switch is an optional parameter to be
used in file mode.
If specified, /HD causes
the file header as well as the specified
portion of the file to be dumped.
In addition, this switch has two options.
"F", the default, causes a Files-11 formatted
dump of the header.
"U"
specifies
an
unformatted octal dump.
An octal dump also
occurs when DMP is used on non-Files-11
headers.
If you want only the header
file to be dumped, specify:

portion

the

/HD/BL:O
The file header is described in Appendix F of
the
IAS/RSX-11
I/O Operations Reference
Manual.
This switch formats data blocks which have
Files-11 header structure.
Other blocks are
output as an unformatted octal dump.
Example:
DMP>

HEAD.LST=[O,O]INDEXF.SYS/HF

This example generates a dump of
the
index
file INDEXF.SYS and formats all the headers
in the file.
(continued on next page)

15-4

''•A

21:

!$! 12! !$ 5 t I ii

ill

FILE DUMP UTILITY (DMP)
Table 15-1 (Cont.)
DMP Switches
Description

Switch
/HX

Specifies that the data
be
dumped
in
hexadecimal
byte
format.
Note that a
hexadecimal dump reads from right to left.

/ID

Causes DMP's version to be identified.
This
switch may be specified on a line by itself
at any time.
Example:
DMP> /ID
DMP--DMP VERSION M0006.05
Logical block;
specifies that only
the
starting block number and a contiguous or
noncontiguous indication for the file should
be displayed.

/Ll3

Example:
DMP>TI:=DKO:RICKSFILE.DAT;3/LB
START!N~ BLOCK NUMBER = 0,135163 C
File RICKSFILEGDAT, version 3 is a contiguous
file starting at block number 0,135163.
(See
/BA:n:m for block number description.)
dumped

/LW

Specifies that the data
be
hexadecimal double-word format.

/MD [: n]

Memory dump;
allows control of line numbers.
Line numbers are normally reset to zero
whenever a block boundary
is crossed.
The
/MD
[:n]
switch allows lines to be numbered
sequentially for the full extent of the file;
that is, the line numbers are not reset when
block boundaries are crossed.
The optional
value
(:n)
specifies the value of the first
line number.
The default
is o.
The /MD
switch is used with the output file.

/RS

Specifies that data
format words.

/RC

Specifies that data be dumped a record at a
time
(rather than a block at a time). The
data format is determined by setting one of
the format switches, /AS, /DC, /HX, /LW, /RS,
or /WD. The largest record DMP can process
is limited by the amount of space available
to the DMP task;
512
(decimal)
bytes are
allocated in the task image.
To increase the
amount of space available,
use the
MCR
Install command /INC switch.
For example, to
dump a file with 1024-byte records, /INC=256.
(at least) must be specified.

dumped

Radix-50

_______ ____ _________·--------------··-··-·--·,,

__._

(continued on next

15-5

pag~}

FILE DUMP UTILITY (DMP)
Table 15-1 (Cont.)
DMP Switches
Switch

Description

/RW

Causes DMP to issue rewind command before
referencing a specified tape. This switch
may be specified at any time to reposistion a
tape at the load point (BOT).

/SP

Causes the dump output file to be spooled to
the line printer.
/SP may only be specified
on the output file specification;
it is
illegal on the input file specification.
Spooled files may be deleted after printing.

/WD

Specifies that the data
hexadecimal word format.

15.4

dumped

specified

specifying

the

correct

DMP ERROR MESSAGES

DMP -- BAD DEVICE NAME
Explanation:
An invalid device name
specification.

User Action:

was

Reenter the command line,

file

device.
DMP -- BLOCK SWITCH REQUIRED IN LOGICAL BLOCK MODE
Explanation:

Self-e~planatory

User Action:

Reenter

the

-- /BL switch must be specified.

command

line

with

the

/BL

file

cannot

located

switch

specified.
DMP -- CANNOT FIND INPUT FILE
Explanation:
The requested
specified directory.

User Action:

the

Reenter the command with the correct file name

and

UIC specified.
DMP -- COMMAND SYNTAX ERROR
Explanation: A command was entered in a
conform to syntax rules.

User Action:

format

that

does

not

Reenter the command line with the correct syntax.

DMP -- FAILED TO ASSIGN LUN
Explanation: An
specification.

User Action:

illegal

device

was

entered

Reenter the command line with

the

in
correct

file
device

specified.

15-6

!l!IAA

:Si

44''

FILE DUMP UTILITY (DMP)
DMP -- FAILED TO READ ATTRIBUTES
Explanation: You attempted to access a file for
not have read access privileges.
User Action:
Rerun DMP
privileges to the file.

under

UIC

which

which
has

you

read

did

access

DMP -- ILLEGAL DENSITY VALUE
Explanation: A value other than 800.
the DMP /DENS switch.
User Action:

or 1600.

was specified in

Reenter the /DENS switch with the proper value.

DMP -- ILLEGAL SWITCH
Explanation: You specified a switch that
is not a
switch, or used a legal switch in an invalid manner.
User Action:
specified.
1
'-'

Reenter the command line with

the

valid

correct

DMP

switch

DMP -- ILLEGAL VALUE ON /HD SWITCH
Explanation:
switch.

You entered an option other than F or U for the /HD

User Action:
specified.

Reenter the command line with

the

correct

option

DMP -- I/O ERROR ON INPUT FILE

'-''

or
DMP -- I/O ERROR ON OUTPUT FILE
Explanation:

One of the followlng conditions exists:

•

A problem exists on the physical device (for example,
cycled down).

•

File is corrupted or the format is incorrect.

•

Output volume is full •

User Action:
Determine which condition caused the
correct that condition.
Reenter the command line.

device

message

and

DMP -- NO INPUT FILE SPECIFIED
Explanation:
A command line
specification.
User Action:
specified.

Reenter

the

was

'entered

command

15-7

line

with

input

file

with

input

file

FILE DUMP UTILITY (DMP)
DMP -- NO LISTS OR WILD CARDS ALLOWED
Explanation: Either a command with more than one input or output
file name was entered, or a wildcard was entered as a file
specification.
User Action: Reenter the command line with only one
specification and one output file specification.
specifications are allowed.

input file
No wildcard

DMP -- OPEN FAILURE ON INDIRECT FILE
exist

Explanation: The requested indirect command file does not
as specified. One of the following conditions may exist:
•

The file is protected against access.

•

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.

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

device

message

and

DMP -- OPEN FAILURE ON INPUT FILE
or
DMP -- OPEN FAILURE ON OUTPUT FILE
Explanation:

One of the following conditions may exist:

•

The file is protected against access.

•

The named file does not exist in the specified directory.

•

The volume is not mounted.

•

The specified file directory does not exist.

•

A problem exists on the physical device (for example,
eye led down) •

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

device

message

and

15-8

'1,~·-

Cl5! l Ji !

i!2

;;s:e

PART 7
PRC>GRAM MAINTENANCE UTILITIES

ii $

I14

u
CHAPTER 16

THE FILE COMPARE UTILITY (CMP)

The File Compare Utility (CMP) compares two ASCII text
files.
The
files are compared line by line to determine whether parallel records
are identical. Using CMP, you can perform the following
file-compare
functions:
•

Generate a listing showing the differences between the two
files.
Each difference is listed as a pair;
first, the lines
from the first file that are being compared to lines in the
second file, then the lines from the second file.

•

Generate a listing in the form of one list,
marked by change bars.

•

Generate output suitable for input to the SLP utility.
This
output contains the SLP commands and input required to make
the first input file identical to the second input file.
(For
more information on SLP, see Chapter 17.)

with

differences

CMP provides switches that allow you to control compare processing.
Using these switches, you can control comparison of blanks, tabs,
form-feeds, and comments.
You can also control line numbering and the
number of lines required for CMP to consider that a match is made
between lines in the two files.
The format for specifying the CMP command line is:
outfile[/sw ••• ]=infilel,infile2

\..,:

outf ile
The file specification for the output file.
This file can be in
one of three formats, depending on the switch you specify on the
command line. The file name of this file must be specified. The
default file type is .LST.
/sw •••
Switches that you apply to the output file specification.
Some
of the switches can be negated and some are mutually exclusive.
Section 16.1 contains this information.
infilel
The input file specification for the file
to be compared to
infile2
(described below).
The file name of this file must be
specified. The default file type is .MAC.

16-1

THE FILE COMPARE UTILITY (CMP)
inf ile2
The file specification for the input file to be compared to
infilel (above). The file name for this file must be specified.
The default file type is .MAC.
You can invoke CMP using any of the methods
described in Chapter l.

16.l

for

invoking

utility

CMP SWITCHES

This section lists the CMP switches, describes the function of each
one, and gives the default setting for each one. You specify switches
on the output side of the command line.
/BL
/-BL

Specifies that blank lines in both files be included in
compare processing. If this switch is specified in the form
/-BL, blank lines are not included in compare processing;
/-BL is the default setting.

/CB
/-CB

Specifies that CMP list infile2 with change bars, in the
form of exclamation marks (1), to denote which lines do not
have a corresponding line in infilel. /-CB is the default
switch.
You can change the change bar character from the exclamation
mark to any character you wish by means of the VB switch,
described below.
When a section of lines in infilel has been deleted in
infile2 (the output listing file), the first line not
deleted is marked.

/CO
/-CO

Specifies that CMP include comments (that is, text preceded
by a semicolon) in compare processing. /CO is the default
for this switch.

/DI
/-DI

Specifies that CMP print the differences between the two
files (rather than marking the lines in infile2).
/DI is the default for this switch.
/CB and /DI are mutually exclusive switches.
both, /CB overrides /DI.

If you specify

/FF
/-FF

Specifies that CMP include records consisting of a single
form-feed character in compare processing.
/-FF is the
default for this switch.

/LI:n

Specifies that a number (n) of lines must be identical
before CMP recognizes a match. If you do not specify this
switch, CMP searches for three identical lines to match.
When it encounters a match, CMP prints all the preceding
nonmatching lines, along with the first line of the matched
sequence of lines to help you find the location in the code
where the match occurred.

/LN
/-LN

Specifies that lines in the output file be preceded by
their line number. Line numbers are incremented by one for
each record read, including blank lines. /LN is the default
switch. If you specify /SL (below), /LN is unnecessary.

16-2

a :a; a

!JUL

THE FILE COMPARE UTILITY (CMP)
/MB

Specifies that CMP include all blank and tab characters in a
line in compare processing.
If you specify /-MB, CMP
interprets any sequence of blank and/or tab characters as a
single blank character. However, all spaces arid tabs are
printed in the output listing. /MB is the default switch.

/-MlB

/SL[:au]

Directs CMP to generate an output file suitable for use as
SLP command input. When you specify /SL, CMP generates the
SLP command input necessary to make inf ilel identical to
infile2.
If a 1- to 8-character alphanumeric symbol is
included (:au), an audit trail is specified for SLP input.
Section 16.2.3, below, gives an example of how CMP generates
SLP command input.
(For information on how SLP processes
source files, refer to Chapter 17.)

/SP [ :n]
/-SP

Specifies that the output file be spooled on the line
printer. You can optionally specify the number (in octal or
decimal)
of files to be spooled. /-SP is the default value
for this switch. This switch applies only if you have the
Print Spooler task
(RSX-llM)
or the Queue Manager system
(RSX-llM/M-PLUS) installed.

/TB
/-TB

Specifies that CMP include all trailing blanks on a line
in compare processing.
If you specify /-TB, CMP ignores all
blanks following the last nonblank character on a line.
When you specify /-CO and /-TB together, blanks that precede
a semicolon
(;)
are considered trailing blanks and are
ignored. /TB is the default value for this switch.

/VB:nnn

Specifies an octal character code for use as a change bar.
You use this switch with the CB switch.
The value nnn
specifies the octal character code.
For example, you can
specify /VB:174 for a vertical bar
(if your printer is
capable of printing the vertical bar character)&

Summary of CMP Default Switch Settings
CMP default switch settings are:
/-BL
/-CB
/CO
/DI
/-FF
/LI:3
/LN
/MB
/-SL
/-SP
/TB
/VB: 041

Do not compare blanks.
Do not generate change bars.
Compare comments.
List only the differences between the two files.
Do not compare form-feed characters.
Find three identical lines before a match can occur.
Generate numbered lines.
Compare all blanks and tab characters.
Do not generate an output file suitable for use as SLP
command input.
Do not spool the output file.
Compare all trailing blanks.
Set the exclamation mark (ASCII 041) as the change bar
character.
Used with /CB.

16-3

THE FILE COMPARE UTILITY (CMP)
FORMATS OF CMP OUTPUT FILES

16.2

CMP uses the two input files you specify on the command line to create
an output file.
CMP compares each line in inf ilel to its sequential
counterpart in infile2. When there are differences between the two
files, CMP displays those differences in one of three output formats:
•

Differences format

(default)

(/DI)

•

Change bar format

(/CB)

•

SLP Command Input Format (/SL)

This section gives an example of each of these formats.
In all of the
examples in the subsequent sections, the following files are used as
input files infilel and infile2:

16.2.l

inf ilel

infile2

TESTl.DAT

TEST2.DAT

LINE!
LINE2
LINE3
LINE4
LINES
1234S
23456
34S67
LINE9
LINElO
LINEll
EXTRA

LINE!
LINE2
LINE3
LINE4
LINES
4S678
S6789
67891
LINE9
LINElO
LIN Ell
EXTRA
EXTRA
EXTRA
EXTRA

Differences Format

If you enter a command line and do not specify any switches, CMP lists
the differences between the two files.
The differences are listed in
pairs;
first, the lines from infilel that do not have counterparts in
inf ile2 are listed,
then the lines from inf ile2 that do not have
counterparts in infilel are listed. Each set of lines is terminated
by the first line (or set of lines) for which a match is successful.
The following example shows the two lists along with the CMP command
used to generate them. The input files are TESTl.DAT and TEST2.DAT,
which are shown in the preceding section.
There are two sets of
differences separated by a long line of asterisks.
(When there are
several sets of differences, CMP separates each set from the next set
by the long line of asterisks.) The short line of asterisks separates
the pair of differences that comprise the set.

16-4

iii I I

I ;

j¥¥

THE FILE COMPARE UTILITY (CMP)

*********************************************
1)

TESTl.DAT;l
6
7
8
9

12345
23456
34567
LINE9

*****************
2)

TEST2 .DAT; l

6
7
8
9

45678
56789
67891
LINE9

*********************************************
l)

TEST! .DAT; l

*****************
2)

TEST2.DAT;l
EXTRA
14
EXTRA
15
EXTRA
13

2 DIFFERENCES FOUND
TESTDIF.DAT=TEST1.DAT,TEST2.DAT
Note that because /LI:n was not specified,
the number of
lines
required for a match defaults to 3. Thus, CMP found two differences.

16~2.2

Change Bar Format

You use the CB switch to generate a listing
that show the differences between two files.
infile2 is the listing you want generated.

containing change bars
In the CMP command line,

The following example shows change bars applied to lines from two
files that do not match line for line.
The command line shown at the
bottom of the listing directed CMP to generate the listing.
l
2
3

4
5

6
7

8
9
10
11
12

13
14

LIN El
LINE2
LINE3
LINE4
LINES

45678
56789
67891
LINE9
LINElO
LINEll
EXTRA
EXTRA
EXTRA
EXTRA

2 DIFFERENCES FOUND
TESTDIF.DAT=TEST1.DAT,TEST2.DAT/CB
Notice that the change bar is applied to the first
(line 9, above).

16-5

line

match

THE FILE COMPARE UTILITY (CMP)
16.2.3

SLP Command Input Format

Use the SL[:au] switch to generate a file containing records to. be
used as SLP command input.
/SL directs CMP to generate the SLP edit
command lines and input lines required to make inf ilel identical to
infile2.
However, you must enter the command line with SLP command input.
CMP
does not generate this command line.
For a complete description of
the SLP utility, refer to Chapter 17 in this manual.
·
The following example shows the format of output generated using
SL switch. The output file is generated with the CMP command:

the

TESTDIF.DAT/SL:BLSOOl=TESTl.DAT,TEST2.CMP
-6,8,/;BLSOOl/
45678
56789
67891
-12,,/;BLSOOl/
EXTRA
EXTRA
EXTRA

16.3

CMP MESSAGES

This section lists the CMP error messages, gives a brief description
of the condition that causes each message, and suggests a response to
the condition.

""
' IT

CMP -- n DIFFERENCES FOUND
Explanation:

CMP found n differences between the two files.

User Action:

This is an informational message.

CMP -- COMMAND SYNTAX ERROR
Explanation: CMP
specification.

found

error

the

command

line

User Action: Check the syntax of the command line specification
and reenter the command line using the correct syntax.
CMP -- ERROR READING INPUT FILE
Explanation:
input file.

An I/O error occurred

User Action:

Retry the command.

while

CMP

was

reading

16-6

"' 22.1

THE FILE COMPARE UTILITY (CMP)
CMP -- ERROR WRI'l'ING OUTPUT FI LE
Explanation:
output file.

An I/O error occurred while

CMP

was

User Action: The output device may be full or bad.
then retry the command.

writing

the

Check

this,

CMP -- ILLEGAL /LI VALUE
Explanation: You specified a negative value for
lihes required for a match.

the

User Action:
specified.

legal

Explanation: An illegal switch or switch value
the command line.

was

entered

User Action:
Reenter the
switch value.

legal

switch

Reenter

the

command

line

with

number

value

CMP -- ILLEGAL SWITCH OR SWITCH VALUE

command

using

the

CMP -- OPEN FAILURE ON INPUT FILE #1
Explanation:

CMP could not open the first input file.

User Action:
Ensure that
specification for the file.

you correctly entered
Reenter the command.

the

file

the

file

the

file

CMP -- OPEN FAILURE ON INPUT FILE #2
Explanation:

CMP could not open the second input file.

User Action:
Ensure that
specification for the file.

you correctly entered
Reenter the command.

CMP -- OPEN FAILURE ON OUTPUT FILE
Explanation:

CMP could not open the specified file.

User Action:
Ensure that
specification for the file.

you correctly entered
Reenter the command.

CMP -- TOO MANY DIFFERENCES FOR AVAILABLE CORE
Explanation: The files were too dissimilar for CMP
the differences in memory.

fit

all

User Action:
Rerun CMP using the /INC=n switch,
or remove and
reinstall CMP with a larger increment.
(For information on using
/INC=n, see the RSX-llM/M-PLUS MCR Operations Manual.)

16-7

.,,
.

!!Sb

CHAPTER 17
SOURCE LANGUAGE INPUT PROGRAM (SLP)

The Source Language Input Program (SLP) is a utility program used for
source file maintenance. SLP maintenance is usually performed on the
latest version of the source file, ensuring that the file contains th~
most recent updates and corrections. The optional audit trail in the
output files allows you to keep a record of these changes.
SLP functions are invoked by means of edit command
switches. SLP edit command statements allow you to:

statements

•

Update (delete, replace, add) lines in an existing file

•

Create source files

•

Run indirect files containing SLP edit commands

and

Input to SLP is an input file that you want updated and command input
consisting of text lines and edit command lines that specify the
update operations to be performed. To locate lines to be changed, SLP
uses locators that you specify as line numbers or character strings.
Command input can come directly from your terminal or from an indirect
command f il.e containing commands and input lines to be inserted into
the file.
SLP accepts data from any RSX-llM/M-PLUS file-structured
device.
SLP output is a listing file and an updated input file.
SLP provides
an optional audit trail that helps you keep track of the updat~ status
of each line in the file.
If an audit trail is not suppressed, it is
shown in the listing and permanently applied to the output file.

'-''

You can control SLP processing using SLP control switches.
These
switches allow you td create or suppress audit trails, specify the
length and beginning position of the audit trails,
calculate the
checksum value for the edit commands, generate a double-spaced
listing, and spool files to a file-structured volume.
You can invoke SLP by all but one of the methods for
invoking a
utility described in Chapter 1. You cannot include a command line on
the same line on which you invoke SLP. That is, you cannot type SLP
files:pec.
Also, after you invoke SLP,
specifying TI:
as your output file
specification is not recommended because SLP displays the input file
while you are editing it. When you are done editing, you do not have
a copy of the output file and the input file is the same as before you
began editing.

17-1

SOURCE LANGUAGE INPUT PROGRAM (SLP)
17.1

SLP INPUT AND OUTPUT FILES

SLP requires two types of input, an input file and command input. The
input file is the source file you want to update using SLP. Command
input consists of SLP edit commands and, optionally, new lines of text
to be placed in the file.
SLP output consists of an output file and a listing file.
The output
file is the updated input file.
The listing file is a copy of the
output file with line numbers added. Both show the changes SLP makes
to the file.

17.1.1

The Input File

The input file is the file to be updated by SLP. It can contain as
many lines of text as are required. When SLP processes the input
file, it makes the changes specified by SLP edit ,commands.
If an
audit trail is generated, it notes these changes in the output files.

17.1.2

Command Input

SLP uses command input to update files.
Command input can be entered
interactively after you invoke the SLP utility or indirectly by means
of indirect command files.
You enter command input to SLP in two modes:
command mode and edit
mode.
After it is invoked, SLP is in command mode, in which it
expects the first line entered to be the command line defining the
files to be processed. When SLP accepts this line, it initializes the
files you want processed.
Once these files are initialized, SLP
enters edit mode,
in which it interprets the lines you enter as SLP
edit commands or new input lines.
You terminate command input with a single slash as the first character
of an edit command line.
The following example shows the general form of command input:
MYFILE.MAC;2/CS/AU:55:10,MYFILE.LST;l/-SP=MYFILE.MAC;l
- 3 , , /; BJ 0 0 7 I

INSERT THIS LINE AFTER LINE 3
-4,4
DELETE LINE 4 AND REPLACE IT WITH THIS LINE

I
NOTE
Numeric values
given
for
switches
default to octal. Decimal values must
be followed by a period
(.).
The
default position for the audit trail is
80(10) and its default length is 14(10)
characters.
(See Section 17.4.2 for
more information about the audit trail.)
The first line is the command line, on which SLP expects to find
definitions for the output file, the listing file, and the input file.
The next four lines comprise the SLP edit commands and input lines.

17-2

1141!C

!IO&!lb 21

44,

:; as

. ;4sas

SOURCE LANGUAGE INPUT PROGRAM (SLP)

Note that the input and output files in the example above have the
same file name and file type; only the versions are different. To
ensure that the correct files are processed, specify the version
numbers explicitly when you enter the SLP utility command line.
Wildcards cannot be used in any of the file specifications.
You can also have the checksum value for the edit commands calculated.
Specify the checksum switch with either the input or output file
specification in the format:
/CS [: n]

The checksum value is calculated
excllLlding:

for

ali

SLP

edit

command

•

The command line specifying the input and output files

•

Comments in the edit command lines

lines,

spaces and/or tabs between characters included in the
• Any
checksum calculation and those characters excluded from the

'-'''

calculation
•

The second comma and anything following it in an edit
line (that is, audit trail and/or comment)

command

•

Comment delimiter (specified by first character of the last
audit trail string before the delimiter) and any characters
following it in an input line, whether or not it is being used
in the line as a delimiter

The value is then reported in a message on your terminal.
If you
specify a value for the checksum and it is not the same as the
calculated checksum, you will get a diagnostic error message.
(The
messages are described below in Section 17.5.)

17.1.3

The SLP Listing File

The SLP listing file shows the updates made to the source file.
Each
line in the listing file is numbered. Updates are marked by means of
the audit trail if one has been generated.
The examples given
throughout the chapter contain samples of listing files.

17.1.4

The SLP Output File

The SLP output file is the updated input file.
All of the updates
specified by means of command input are inserted in this file. The
audit trail, if specified, is applied to lines changed by the update.
The audit trail is included in the output file. The numbers generated
by SLP for the listing file do not appear in the output file.

17-3

SOURCE LANGUAGE INPUT PROGRAM (SLP)
17.2

HOW SLP PROCESSES FILES

Figure 17-1 shows how SLP processes files
following command line and edit commands:

when

receives

the

MYFILE.MAC;2/AU:55:10,MYFILE.LST/-SP=MYFILE.MAC;l
-3
INSERT THIS LINE AFTER LINE 3
-4,4
DELETE LINE 4 AND REPLACE IT WITH THIS LINE

Input File

Listing File

MYFILE.MAC;1

Command Input
From Primary
Input Device

MYFI LE.LST;1

SLP
Processor

Output File

From Indirect File
INFILE.SLP;l

MYFILE.MAC;2

@LJ
Figure 17-1

Input Files and Output Files Used During SLP Processing

This is the input file (MYFILE.MAC;l) before SLP processes the files:
ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN
EIGHT
NINE
TEN

17-4

4 Ji LUZ:

iii

I ;

; '1 ii

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The following is the listing file (MYFILE.LST;l)
processing of these files:
1.
2.

3.
4.
5.

6.
7.
8.
9.
10.
11.

resulting

ONE
TWO
THREE
INSERT THIS LINE AFTER LINE 3
DELETE LINE 4 AND REPLACE IT WITH THIS LINE
FIVE
SIX
SEVEN
EIGHT
NINE
TEN

from

SLP

;**NEW**
;**NEW**
;**-1

The audit trail shows the new lines (;**NEW**) and indicates where
lines have been removed (;**-1).
(The audit trails ;**NEW** and ;**-n
are automatically generated by SLP if you have not suppressed audit
trail generation or if you have not specified another audit trail
string.) In this case, a line has been added after line 3, and line 4
has been deleted and a new line added in its place.
As shown in Figute 17-1, SLP processes ari input file using command
input.
When processing begins, SLP writes each line from the input
file into the output file until it reaches a line to be modified, as
requested in the command input.
When SLP reaches a line to be
modified, it makes the indicated modification, notes the change by
means of the audit trail if the trail has been generated, and then
continues writing lines to the output file, in sequence, until another
command is encountered or until end of file is reached.

17.3

USING SLP

This section describes how to:
•

Specify the SLP edit command

•

Update files using the SLP edit command

•

Enter SLP commands interactively
files

•

Create a source file using SLP

17.3.l

and

means

indirect

Specifying SLP Edit Commands

The SLP edit commands provide the means to update source files by
adding, deleting, and replacing lines in a file. You enter SLP edit
commands after invoking SLP and specifying an edit command line.

17-5

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The general format of the SLP edit command line is as follows:
-[locator!] [,locator2] [,/audittrail/] [; comment]
inputline

- (dash)
Specifies that this is a SLP edit command line.
locator!
A line locator that causes SLP to move the current line pointer
to a specified line. If you specify only locator!, the current
line pointer is moved to that line and SLP reads the next line in
the command input file. This field can be specified using any of
the locator forms described below.
locator2
A line locator that defines a range of lines (that is, the range
beginning with locator! and ending with locator2, inclusive) to
be deleted or replaced. This field can be specified using any of
the locator forms described below.
/audi ttrail/
A character string used to keep track of the update status of
each line in the file.
The string must be enclosed within
slashes (/). It consists of a comment delimiter as the first
character and then a text string.
The semicolon (;) is the
initial delimiter for audit trails automatically generated by SLP
(;**NEW**
and ;**-n).
The comment delimiter specified in
audittrail (usually a semicolon) is the new delimiter for all
subsequent audit trails until redefined by a later audittrail.
inputline
A line of new text to be inserted into the file immediately
following the current line. You can enter as many input lines as
required.

comment
A line of text (delimited by a semicolon) at the end of the SLP
edit command line that appears only in the command input file.
All fields in the SLP edit command line are positional and commas must
be specified.
The locator fields can take one of the following forms:
-/string/[+n]
-/string ••• string/[+n]
-number[+n]
- • [ +n]

17-6

4 II

!l!i I

iSZ:

SOURCE LANGUAGE INPUT PROGRAM (SLP)
string
A string of ASCII characters. SLP locates the line in which
string exists and moves the current line pointer to that line.
If the locator is specified in the form /string .•• string/, SLP
locates the line in which the two character strings delimit a
larger character string abbreviated by an ellipsis ( ••• ).
numb~~r

A decimal line number to which the current line pointer is to be
moved. The largest line number that can be specified is 9999.
n

A decimal value used as an offset from the line specified by the
locator. You cannot use +n by itself. It must be specified with
a number or string locator, or a period. SLP moves the current
line pointer n lines beyond the line specified in the locator
field •
• (pe.r iod)
The current line.
Although the values for number and n are taken as
that all other SLP values are octal by default.

decimal,

remember

All forms of the line locator can be specified interchangeably in
SLP edit command line.

'--1'

17.3.2

the

Entering SLP Edit Commands

Once you have invoked SLP, you can enter SLP
interactively or by means of indirect command files.

edit

commands

In both cases, the first command you must enter is the command
defining the files to be processed during this SLP session.

line

This section gives examples of how to use both methods of entering SLP
commands.
The following file, BASE.MAC;!, is used as
examples in this section:
AAAA
2222
BBBB
4444

cc cc
6666
DODD
8888

9999
TEN

17-7

the

input

file

for

the

SOURCE LANGUAGE INPUT PROGRAM (SLP)
17.3.2.l Entering SLP Commands Interactively - To alter
file interactively, first invoke SLP:

the

example

>SLP
SLP responds to this command with the prompt:
SLP>
Once you have entered the SLP command mode, SLP does not display
prompts.
The first line you enter must always be the cdmmand line to
tell SLP the files you want processed during this session:
BASE.MAC;2/AU:48./TR,BASE.LST=BASE.MAC;l
Then you enter the edit commands and input lines:
-3

INSERT THIS LINE AFTER LINE 3
-4,4
DELETE LINE 4 AND REPLACE IT WITH THIS LINE
-6,,/;JMOlO/
INSERT THIS LINE AFTER LINE 6 WITH A NEW AUDIT TRAIL VALUE
I
Enter only the SLP edit commands and the new input lines.
When you
have entered all the corrections, enter the slash (/) to terminate the
edit session. SLP processes the files and returns control to you with
the prompt:
SLP>
This returns SLP to command mode. You can then enter the command line
and begin another editing session.

~
~,

The listing file resulting from SLP processing appears as follows:
1.

2.
3.
4.
5.
6.
7.
8?
9.
10.
11.
12.

AAAA
2222
BBBB
INSERT THIS LINE AFTER LINE 3
DELETE LINE 4 AND REPLACE IT WITH THIS LINE

cc cc

;**NEW**
;**NEW**
;**-1

6666

INSERT THIS LINE AFTER LINE 6 WITH A NEW AUDIT T;JMOlO
DODD
8888
9999

TEN

The TR switch (/TR in the command line) records the truncation of
lines by the audit trail. In the listing file, a question mark (?)
replaces the period (.) in the line number of the lines that were
truncated.
It is possible that audit-trail strings in the input file
will be truncated by the new audit-trail string although the commands
or text strings will not be truncated.
17.3.2.2 Entering SLP Commands Using Indirect Command Files - You can
enter the same commands using an indirect command file.
In this example, the SLP edit commands are contained in the indirect
command file, BASE.SLP.
You invoke SLP and SLP responds with the
prompt:

SLP>
17-8

2 ii!

' d l

SiJ I

Lf U¥

SOURCE LANGUAGE INPUT PROGRAM (SLP)

\...,.)

You then enter the file specification for the indirect command file
containing the command line,
the SLP edit commands, and the input
lines:
@BASE.SLP
SLP processes the files just as if you entered the commands and
lines interactively, returning control to you with the prompt:

input

SLP>
You can also specify SLP @BASE.SLP.
The output listing resulting from indirect command file processing is
exactly like the output listing resulting from the same changes made
interactive!ly.
Indirect command files can be nested to a maximum level of 3.
This
permits indirect command files to reference a standard editing file
when SLP is invoked with an indirect command file reference at the
monitor level.

17.3.2.3 Using SLP Operators - In addition, you can enter certain
special characters called operators, which perform specific functions.
Table 17-1 lists the operators and the function each performs.
Enter
operators, in edit mode, as the first character of an input line.
Table 17-1
SLP Operators
Operator

Function
SLP interprets the dash as the first character
SLP edit command.

SLP interprets the backslash as a command to suppress
audit-trail processing.

SLP interprets the percent sign
reenable audit-trail processing.

command

SLP interprets the at sign as a command to invoke
indirect file for SLP processing.

SLP interprets the slash as a command to terminate
the SLP edit session, and then return to SLP command
mode.

SLP interprets the less-than character as an escape
character.
Escape characters are characters that
enable you to enter characters in the input file that
SLP otherwise would interpret as operators. For
example, </ hides the slash character from SLP,
thereby enabling you to enter the slash into the
output file without terminating the SLP editing
session.
The less-than character can be used with
all SLP operators.

17-9

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP allows you to enter lines sequentially. Once past a given line in
the file, you cannot return the line pointer to that line. To return
the line pointer to that line, you must begin another SLP editing
session.
To close the file and terminate the editing session, use the slash (/)
operator.

17.3.3

Updating Source Files Using SLP

This section describes the procedure for generating a numbered listing
for use in editing source files by line number. The section also
describes how to use SLP to add, delete, and replace lines in a file.

17.3.3.1 Generating a Numbered Listing - SLP processes input by
number.
However, line numbers appear only in the listing file~
are not written to the output file.

line
they

To use SLP effectively, you should use a numbered listing when you
prepare command input. To generate a numbered listing, first invoke
SLP, then enter the command line in the format:
, listf ile=inf ile

I
In this format, listfile is the name you assign to the listing file
SLP produces and infile is the name of the input file whose lines are
to be numbered. The slash (/) terminates the edit mode. For example,
suppose the input file is:
ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN
EIGHT
NINE
TEN
SLP processes each line to generate a numbered listing file:
1.
2.
3.

4.
5.
6.

7.
8.
9.
10.

ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN
EIGHT
NINE
TEN

17-10

••••••:•11••1•lllllt•••••••••&•••••••••••••••t•t..•••••••••••••••••111141111s":;:•:

11 11

1'"'

SOURCE LANGUAGE INPUT PROGRAM (SLP)
17.3.3.2 Adding Lines to a File - The three SLP edit command
for adding lines to a file are:

formats

-locator!
inputline

o:r
-locator!,,
input.line

or
locatorl,,/audittrail/
inputline

See above for the descriptions of these terms.
The following example shows how to add lines to
file consists of the following lines:

file.

The

input

ABC
DEF
GHI
KLM
123456789
456
789
CBA
XYZ

987
The command input consists of the following commands and text lines:
MYFILE.MAC~2/AU:50,LISTING=MYFILE.MAC~l

-/123/
INSERT THIS LINE AFTER LINE 5

I
SLP processing generates the following listing file:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

ABC
DEF
GHI
KLM
123456789
INSERT THIS LINE AFTER LINE 5
456
789
CBA

:**NEW**

XYZ

987

SLP has numbered the lines and applied an audit trail to the line
following line 5, where SLP found the first occurrence of the string
123.
17-11

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The next example uses the
command lines:

same

input

file

and

the

following

new

MYFILE.MAC;2/AU:50,LISTING=MYFILE.MAC;l
-/DEF/+2
THIS IS NEW TEXT

I
SLP processing generates the following listing file:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

ABC
DEF
GHI
KLM
THIS IS NEW TEXT
123456789
456
789
CBA
XYZ
987

;**NEW**

Again, SLP has numbered the lines and this time the new input line is
inserted two lines beyond the line containing the first occurrence of
the string DEF.

17.3.3.3 Deleting Lines from a File - The SLP edit command format for
deleting lines from a file is:
- [locator 1] , [locator 2] , [/audit trail/] [;

comment]

In this format, locatorl and locator2 can be any of the forms of the
locator fields described in Section 17.3.1; locatorl specifies the
line where SLP is to begin deleting lines;
locator2 specifies the
last line to be deleted. SLP deletes all lines from locatorl through
locator2, inclusive.
The following example shows how to delete lines from a file using SLP.
The input file consists of the following lines:
ABC
DEF
GHI
KLM
123456789
456
789
CBA
XYZ
987
The command input for this example is:
MYFILE.MAC;2/AU:50,LISTING=MYFILE.MAC;l
-/123 ••• 789/,/XYZ/

17-12

I¥

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP processing generates the following listing file:
L

2 ..

'--'

3 ..

4.
5.

ABC
DEF
GHI
KLM
987

;**-5

In this example, the ellipsis ( ••• ) abbreviates the larger string
123 i56789.
Assuming the two strings bracket a larger string, SLP
searches for the first occurrence of the string 123 and then the first
occurrence on the same line of the string 789, in this case the string
123456789. SLP begins deleting lines at this line and continues
deleting lines until it deletes the last line of the given range,
specified here by the string XYZ. SLP applies the audit-trail count
of the lines it deleted to the next line from the input file.
1

Using the same input file as used in the example above, this example
shows how to delete a single line using the period locator. The
command input for this example is:
MYFILE.MAC;2/AU:50,LISTING=MYFILE.MAC;l
-/DEF/,.

I
SLP processing generates the following listing:
1.
2.

ABC
GHI

3..

K:LM

4.
5.
6..
7..

123456789
456
789
CBA
XYZ
987

8..

;**-1

SLP moves the current line pointer to the line containing the string
DEF and then finds the period as the second locator field. Since the
second locator field is specified as the current line, SLP deletes the
current line.

17.3.3.4 Replacing Lines in a File - A replacement is the deletion of
old text followed by the insertion of new text. The number of lines
delE~ted need not match the number of lines added.
To replace lines in
a file, use the same SLP edit command format as used in the delete
command. The first line locator field specifies the first line to be
deleted.
The second line locator field defines the last line in the
range to be deleted and where the new text is to be inserted.
For
example:
-4,. +4

This command instructs SLP to move the line pointer to line
replace line 4 and the next four lines with new input lines.

17-13

and

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The following example shows how to delete lines from a file and
replace them with new lines. The input file consists of the following
lines:
ABC
DEF
GHI
123456789
BCN
CRB
BUR
The command input is:
MYFILE.MAC;2/AU:50,LISTING=MYFILE.MAC;l
-2,.+l
NEW LINE 2
NEW LINE 3

I
SLP processing generates the following listing file:
ABC
NEW LINE 2
NEW LINE 3
123456789
BCN
CRB
BUR

2.
3.
4.
5.
6.
7.

17.3.4

;**NEW**
;**NEW**
;**-2

Creating Source Files Using SLP

Using SLP to create source files is possible, but not recommended.
SLP does not have an intraline editing mode, and you cannot return to
a line once you have passed it. The interactive editors, EDI and EDT,
are better for creating source files.
To create source files using SLP, invoke SLP
line in the format:

and

enter

the

command

outfile/-AU[/sw] [,listfile] [/sw]=primary input device: [/sw]
outfile
The file specification for the output file.
is SYO:.

The

default

device

/-AU
Specifies that an audit trail is not to be generated. Otherwise,
you will get the ;**NEW** audit trail on every line of the output
files.
listfile
The file specification for the listing file (optional).
primary input device:
Specifies that input for the file being created is coming
this device, for example, a terminal or a card reader.

from

17-14

!£

/4=•

SOURCE LANGUAGE INPUT PROGRAM (SLP)
/sw
Specifies any optional SLP switches you want set.
The default device for output files is SYO::
for input files, the
default device is your primary input device. For listing files, the
default device is implied by the output file specification.
The
following file specification cr~ates a new file called MYFILE.MAC from
the terminal and puts it on SYO:.
MYFILE.MAC/-AU=TI:
Once you have entered the file specification, SLP accepts each line as
a variable-length record of up to 132(10) characters. Trailing blanks
and tabs on input lines are deleted. SLP expects input to the file to
come~
from the primary input device. End the SLP session with a slash
(/) and then a CTRL/Z.

1 7 • ~~

CONTROLLING SLP

The SLP switches allow you to calculate the checksum value for the
edit commands and to control the generation and format of the listinq
file and the output file.

17.4.1

SLP Switches

The procedure SLP uses to calculate the checksum value
commands is described above in Section 17.1.2.

for

the

edit

SLP output consists of two files -- a listing file and the output
file, which is the modified version of the original input file. You
can control the audit trail and print options associated with the two
files using the SLP switches.
The effects of SLP switches are the same whether you apply them to
input or output files (except for the SP switch, which you can specify
only with the listing file). Table 17-2 lists the SLP switches and
gives a brief description of the functions each performs.

\..,''

17-15

SOURCE LANGUAGE INPUT PROGRAM (SLP)
Table 17-2
SLP Switches
Switch

Function

/AU
/-AU

Allows you to generate an audit trail or suppress
audit trail generation,
and specify the beginning
field and length of the audit trai1.
/AU is the
default value.

/BF
/-BF

Right-justifies the audit trail by inserting spaces
instead of tabs at the end of text information.
/BF
is the default value.

/CM[:n]

Deletes audit trails and any trailing spaces or tabs,
and truncates the text at a specified horizontal
position. The value given for the beginning position
of the audit trail is the default value for this
switch.

/CS[:n]

Calculates the checksum value for the edit commands.
If you do not specify n, SLP reports the value in a
message on your terminal.
If you do specify n and
the checksum value that SLP calculates is not the
same as the one you specified, SLP displays a
diagnostic error message.

/DB
/-DB

Generates the listing file in double-space
/-DB is the default value.

/SP
/-SP

Spools the listing file to the printer.
/SP is the
default value. This switch applies only if you have
the
print spooler task
(RSX-llM)
or the queue
management system (RSX-llM/M-PLUS) on your system.

/TR

Reports truncation of lines by the audit trail.
If
line truncation occurs, you will get a diagnostic
error message. There is no default value for
this
switch.

format.

In the listing file, a question mark (?) replaces the
period
(.) in the line number of the lines that were
truncated.

17.4.2

Controlling the Audit Trail

The [-]AU switch allows you to generate, suppress, and set the
and contents of the audit trail.

length

To suppress generation of the audit trail, specify the /-AU switch
either the input or output file specification.
For example, either command line below generates an output
no audit trail:
DKl:MYFILE.MAC;3/-AU,LP.LST:=MYFILE.MAC;2
DKl:MYFILE.MAC;3,LP.LST:=MYFILE.MAC;2/-AU

17-16

file

in
with

SOURCE LANGUAGE INPUT PROGRAM (SLP)
By default, SLP automatically generates an audit trail;

that is, you
need not explicitly specify /AU in your command line (unless you want
to specify the beginning position and length of the audit trail).

LP.LST will be spooled automatically.

17.4.3

Setting the Position and Length of the Audit Trail

You can set the beginning position of the audit trail and
of the audit trail using the AU switch in the format:

the

length

/AU:position:length
position
A number, less than or equal to 132(10), designating the
beginning character position of the audit trail on the line. SLP
rounds this value to the next highest tab stop (a multiple of 8).
The default value for position is 80(10).
\._,,

length
The length of the audit trail.
8(10)
characters;
no more
specif:ied.

The default value for length
than 14(10) characters may

is
be

The E~xample below shows how to specify the beginning position
length of the audit trail. The input file for this example is:

and

ONE
TWO
THREE
FOUR
FIVE
The command input is:
MYFILE.MAC;2/AU:30.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;l
-2,.+l,/;CHANGEOOl/
NEW LINE 2
NEW LINE 3

I
The listing file resulting from SLP processing is:
1.
2.
3.
4.
5.

17.4.4

ONE
NEW LINE 2
NEW LINE 3
FOUR
FIVE

;CHANGEOOl
;CHANGEOOl
;**-2

Changing the Value of the Audit Trail

To change the value of the audit trail, specify:
-[locatorl], [locator2],/;new value/

17-17

SOURCE LANGUAGE INPUT PROGRAM (SLP)
Audit trail values can change whenever and wherever you want them
For example,

to.

.-.
t"".14;

MYFILE.MAC;2/AU:48.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;l
-3

INSERT THIS LINE AFTER LINE 3
-4,4
DELETE LINE 4 AND REPLACE IT WITH THIS LINE
-6,,/;JMOlO/
INSERT THIS LINE AFTER LINE 6 WITH A NEW AUDIT TRAIL VALUE
-9,,/;BJ008/
INSERT THIS LINE AFTER LINE 9 WITH ANOTHER NEW AUDIT TRAIL VALUE

I
The listing file resulting from SLP processing appears as follows:
1.
2.

3.
4.

5.
6.
7.
8?
9.
10.

AAAA
2222
BBBB
INSERT THIS LINE AFTER LINE 3
DELETE LINE 4 AND REPLACE IT WITH THIS LINE

cc cc

6666
INSERT THIS LINE AFTER LINE 6 WITH A NEW AUDIT T;JMOlO
DDDD
8888
9999
INSERT THIS LINE AFTER LINE 9 WITH ANOTHER NEW A;BJ008
TEN

11.

12?
13.

17.4.5

;**NEW**
;**NEW**
;**-1

Temporarily Suppressing the Audit Trail

You can temporarily suppress the generation of the audit trail by
using the backslash (\) operator. You can then reenable audit-trail
processing with the percent sign (%) operator.
(You cannot enable
audit trail processing with this operator if you have specified /-AU
in the SLP command line.)
Both operators are entered in the command input. The backslash (\) is
specified in column l of the line that precedes those commands and/or
input files for which you do not want audit-trail processing.
The
percent sign (%) is specified in column l of the line that precedes
the lines for which you do want processing. For example:
BAK.MAC;26/AU/-BF=BAK.MAC;25

-2,2

.!DENT
-23,23
; VERSION 0 5 • 0 3
-37,,
J. MATTHEWS
JMOll

/05.03/

ll-JAN-79
CORRECT OUT-OF-BOUNDS CONDITION FOR INPUT-BUFFER
SIZE

-106,106,/;JMOll/
CMP
#132.,R3
BLT
30$

IS INPUT-BUFFER SIZE IN RANGE?
IF LT, NO

I
17-18

~···ii

ij(Q

a 1+

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The lines between the backslash (\) and the percent sign (%) are not
affected by audit-trail processing. The lines following the percent
sign (%) are affected.

\._,,··
17.4.6

Deleting the Audit Trail

The CM switch allows you to delete audit trails and trailing spaces
and tabs from a file. The CM switch applied to the output or input
file specification accepts a numeric argument that specifies the
beginning position of an audit trail or other text string to be
deleted. The default for this argument is the position argument given
for the
AU switch (or its default, decimal 80). This value is
rounded to the next highest tab stop before use.
When processing an input line, SLP first truncates the text to the
next highest tab stop after the position specified, and then deletes
any trailing spaces or tabs. The remaining text is copied to the
output file.
The

CM switch is specified in the form:
/CM: [position]

position
A number designating the beginning character
audit trail (or other text) to be deleted.

position

the

For example:
SLP>SLPR11.MAC;l2/CM:ll9.=SLPR11.MAC;ll

I
In this case, the input lines are truncated to a length of 120(10)
characters.
The specified length is rounded up to the next highest
tab stop (decimal 120) and the audit trail begins at column 121(10).
Trailing spaces and tabs are deleted before each line is copied to the
output file.
In the next example, SLP truncates input lines to the default position
of the audit trail, column 80(10).
SLP>SLPR11.MAC;l2=SLPR11.MAC;ll/CM

I
17.5

SLP M:E$SAGES

SLP messages are divided into two groups: information and error. The
messages and suggested responses are given below. Section 17.5.1
describes the information message and Section 17.5.2 describes the
error messa9es.

17-19

SOURCE LANGUAGE INPUT PROGRAM (SLP)
17.5.1

SLP Information Message

SLP

COMMAND FILE CHECKSUM IS ######
Explanation: By specifying /CS in the command
requested SLP to calculate the checksum value
commands.
User Action: This message is
action is required.

17.5.2

for

your

information

line,
you
for the edit
only.

SLP Error Messages

SLP error messages are issued in two formats:
•

SLP followed by two dashes, the type of error message, and the
error message.
If applicable,
the command line or command
line segment that caused the message is printed on the next
line. For example:
SLP -- *FATAL*-ILLEGAL SWITCH
SHIRLEY.MAC:2

•

SLP followed by two dashes, the type of error message,
the
error message, and the name of the file with which the error
is associated. For example:
SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename

This section lists the error messages SLP can issue.
Following each
message is an explanation of the error and recommended user action to
correct the error. Note that all but two of the SLP error messages
are fatal.
The two exceptions are diagnostic messages, which are
described at the end of this section.
SLP -- *FATAL*-COMMAND SYNTAX ERROR
command line
Explanation: The command line format did not conform to
rules. Open files were closed and SLP was reinitialized.
User Action:

syntax

Reenter the command line.

SLP -- *FATAL*-ILLEGAL DEVICE NAME
command line
Explanation: The device specified was not a legal device.
files were closed and SLP was reinitialized.
User Action:

Open

Reenter the command line.

SLP -- *FATAL*-ILLEGAL DIRECTORY
command line segment
Explanation: The directory was not legally
files were closed and SLP was reinitialized.
User Action:

specified~

Open

Reenter the command line.

17-20

nu• ; t

U 2$ I

22 &!ii I

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP

*FATAL*-ILLEGAL ERROR/SEVERITY CODE pl p2 p3
Explanation:
program.

This error message indicates an error

the

SLP

If the error persists,
User Action: Reenter the command line.
submit a Software Performance Report along with the related
console dialogue and any other related information, such as
programs or listings.
SLP -- *FATAL*-ILLEGAL FILE NAME
command line segment
Explanation:
A file specification was greater than
30(8)
characters in length or contained a wildcard
(that is, an
asterisk in place of a file specification element).
Open files
were closed and SLP was reinitialized.
User Action:
\..,)

Reenter the command line.

SLP ··- *FATAL*-ILLEGAL GET COMMAND LINE ERROR
Explanation: The system was unable to read a command line. This
indicates an internal system failure or an error in the SLP
program.
User Ac:tion: Reenter the command line.
If the error persists,
submit a Software Performance Report along with the related
console dialogue and any other pertinent information.
SLP -- *FATAL*-ILLEGAL SWITCH
command line segment
Explanation: The switch was not a valid SLP switch or a leqal
switch was used in an invalid manner. Open files were closed and
SLP was reinitialized.
User Ac:tion:
specified.

Reenter the command line with

the

correct

switch

SLP -- *FATAL*-INDIRECT COMMAND SYNTAX ERROR
command linH
Explanation: The command line format specified for the indirect
command file did not conform to syntax rules. Open files are
closed and SLP was reinitialized.
User Action:

Reenter the command line.

SLP -- *FATAL*-INDIRECT FILE DEPTH EXCEEDED
command 1 inE~
Explanation:
More than three levels of
indirection
were
specified in an indirect command file. Open files were closed
and SLP was reinitialized.
User Action:
line.

Correct the command file and

17-21

reenter

the

command

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP -- *FATAL*-I/O ERROR COMMAND INPUT FILE
or
SLP -- *FATAL*-I/O ERROR COMMAND OUTPUT FILE
or
SLP -- *FATAL*-I/O ERROR CORRECTION INPUT FILE filename
or
SLP -- *FATAL*-I/O ERROR LINE LISTING FILE filename
or
SLP

*FATAL*-I/O ERROR SOURCE OUTPUT FILE filename
Explanation:

One of the following conditions may exist:

•

A problem exists on the physical device (for example, the disk
is not spinning).

•

The length of the command line was greater than the
number of characters.
·

•

The file is corrupted or the format is incorrect.

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

specified

message

and

SLP -- *FATAL*-INDIRECT FILE OPEN FAILURE
command line
or
SLP -- *FATAL*-OPEN FAILURE CORRECTION INPUT FILE filename
or
SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename
or
SLP

*FATAL*-OPEN FAILURE SOURCE OUTPUT FILE filename
Explanation:

One of the following conditions may exist:

•

The file is protected against an access.

•

A problem exists with the physical device
device was not online).

•

The volume is not mounted.

•

The specified file directory does not exist.

•

The named file does not exist in the specified directory.

•

The available Executive dynamic memory is insufficient for the
operation.

(for

example,

the

17-22

lutQ

SOURCE LANGUAGE INPUT PROGRAM (SLP)
These errors cause
reinitialized.

open

files

closed

and

message

and

contained

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

SLP

SLP -- *FATAL*-LINE NUMBER ERROR
command line
Explanation:
The
command
line
printed
illegally-specified numeric line locator.

User Action: Terminate the SLP edit session and refer to the
rules for specifying numeric line locators in Section 17.3.1.
Correct the error and reenter the command line.
SLP -- *FATAL*-PREMATURE EOF CORRECTION INPUT FILE filename
Explanation: An out-of-range line locator was specified in a
for example, -1000 was
correction file or from the terminal~
specified for an 800-line file.
User Action:
•

Terminate the current editing session.

•

Restart the editing session, entering the correct line number.

SLP -- *FATAL*-PREMATURE EOF COMMAND INPUT FILE
Explanation: This is caused by not terminating SLP command input
with a slash (/) or by inadvertently typing CTRL/Z at the
terminal, which sends an end-of-file to SLP before the slash
(/)
character is read. SLP prints SLP>, indicating that a new file
specification is expected.
User Action: Restart the editing session at the point where
CTRL/Z was typed.

the

SLP -- *DIAG*-ERROR IN COMMAND FILE f ilespec CHECKSUM
Explanation: An incorrect value was specified for the command
file checksum.
If you ente"r the edit command lines directly from
the te!rminal, the command file in the error message is CMI.CMD.
Thus, the error message reads:
SLP --· *DIAG* - ERROR IN COMMAND FILE CMI.CMD CHECKSUM
User Action: This is a warning message only.
The specified
output: file is still created, although possibly not as intended.

17-23

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP -- *DIAG*-n LINES TRUNCATED BY AUDIT TRAIL
command line
Explanation:

Line truncation by the audit trail was detected.

User Action:
This is an informational message only.
The
specified output file is still created.
(In the listing file, a
question mark (?) replaces the period (.) in the line number of
the lines that were truncated. It is possible that audit-trail
strings from the input file will be truncated by the new
audit-trail string although text strings will not be truncated.)
Determine where the truncation(s) occurred. If necessary, modify
the command file so that it contains commands that do not cause
truncation.

17-24

•

"-'I
CHAPTER 18

OBJECT MODULE PATCH UTILITY (PAT)

The Object Module Patch Utility (PAT) allows you to update, or
code in a relocatable binary object module.

patch,

Input to PAT is two files, an input file and a correction file.
The
input file consists of one or more concatenated object modules.
You
can correct only one of these object modules with a single execution
of PAT. The correction file consists of object code that, when linked
by the Task Builder, either overlays or is appended to the
input
object module.
Unlike the Task Builder and ZAP patching options, P~T
allows you to increase the size of the object module because the
changes are applied before the module is linked by the Task Builder.
PAT uses the correction file,
which contains corrections and/or
additional instructions,
to update the object module.
Correction
input is prepared in source form and then assembled by the MACR0-11
assembler.
Output from PAT is the updated input file.
You invoke PAT using any of the methods for
invoking a utility
described in Chapter 1. PAT can be used interactively or by means of
indirect command files.
If you use indirect command files, PAT allows
a maximum nesting level of 2.
Using PAT to update a file involves several steps.
First, you create
the correction file using a text editor. Once created, the correction
file must be assembled to produce an object module.
The correction
file and the input file
(both in object module format) are then
submitted to PAT for processing.
Finally, the updated input object
module is submitted to the Task Builder to resolve global symbols and
to create an executable task.
Figure 18-1 shows the processing steps
involved in generating an updated task file using PAT •

18-1

OBJECT MODULE PATCH UTILITY (PAT)
CORRECT.SAC

TEXT
EDITOR

>LJ
>LJ

Generate a correction file using
the Text Editor.

CORRECT.SAC

LJ
LJ
LJ

~·
.

CORRECT.OBJ

Execute the assembler (or compiler)
to generate an object module
version of the file.

CORRECT.OBJ

MYFILE.OBJ

>LJ

Execute PAT using as input the
correction file and the module to
be updated.

MYFILE.TSK

4.
TASK
BUILDER

Figure 18-1

Execute the Task Builder to
resolve new addresses and
generate an executable task.

->LJ

Processing Steps Required to Update a
Module Using PAT

SPECIFYING THE PAT COMMAND STRING

18.1

Specify the PAT command string in the following format:
[outfile]=infile[/CS[:number]],correctfile[/CS: [number]]
outfile
The file specification for the output file.
If
specify an output file, PAT does not generate one.

you

not

inf ile
The file specification for the input file.
one or more concatenated object modules.

This file can contain

correctf ile
The file
contains
file.

This file
specification for the correction file.
the updates being applied to one module in the input

18-2

"111••

Lu: a

~·

OBJECT MODULE PATCH UTILITY (PAT)
/CS[:number]
Specifies the Checksum switch.
This switch directs PAT to
calculate the checksum for all the binary data that constitutes
the module. PAT displays this checksum in octal.
(Refer to
Section 18.2.4 for
information on how to use /CS.) You can
optionally specify an octal number with /CS.
Then, after PAT
calculates the checksum value, it compares that value with the
number you specified. If the values are not the same, PAT
informs you with an error message.

HOW PAT APPLIES UPDATES

18.2

This section describes the PAT input and correction files,
gives
information on how to create the correction file, and gives examples
of how PAT applies the corrections to a module.

18.2.1

The Input File

The input file is the file to be updated;
it is the base for the
output file.
The input file must be in object module format. When
PAT executes, the correction file is applied to one of the object
modules in the file.
PAT assumes a file type of .OBJ for the input
file.
If you use a file type other than .OBJ, you must specify it
explicitly in the command line.

18.2.2

The Correction File

The correction file contains the patches to be applied to the input
file.
Like the input file, the correction file has a default file
type of .OBJ. If you use any other file type.
you must specify it
explicitly in the command line.
As shown above in Figure 18-1, the first step in using PAT to update
an object file is to generate the correction file.
Use any text
editor to create this source file, which is usually in the following
format:
• TITLE: inputname
• IDEN'l~ upda tenum
input line
input line

inputname
The name of the module to be corrected by the PAT update.
You
must specify inputname to be the same as the name of the module
that you are updating.
updatenum
Any value acceptable to the MACR0-11 .!DENT assembler directive.
Generally, this value reflects the updated version of the file
being processed by PAT (as shown in the examples given in Section
18.2.3).

18-3

OBJECT .MODULE PATCH UTILITY (PAT)
NOTE
The .!DENT assembler directive is a
required part of the correction file.
Failure to include a .!DENT directive in
the file produces unusable output.
inputline
Lines of input to be used to correct and update the input file.
Once you have created the source version of the correction file,
you
assemble it to produce an object module that can be processed by PAT.
During PAT execution, new global symbols defined in the correction
file are added to the module's symbol table. A symbol definition that
is already being used in the input file can be superseded by the
definition in the correction file.
For a symbol definition to be
superseded, both definitions must be either relocatable or ab'solute.
A duplicate program section supersedes the previous
provided:

program

section,

•

Both have the same relocatability attribute (ABS or REL)

•

Both are defined with the same directive

(.PSECT or .CSECT)

If PAT encounters duplicate program section names,
the
length
attribute for the program section is set to the length of the longer
program section, and a new program section is appended to the module.
If you specify a transfer address, it supersedes the transfer
of the module being patched.

18.2.3

address

How PAT and the Task Builder Update Object Modules

The examples in the following sections show an input file and a
correction file (both in object module format) to be processed by PAT
and the Task Builder, along with a source-like representation of how
the output file looks once PAT and the Task Builder complete
processing. Two techniques are described, one for overlaying lines in
a module and the other for adding a subroutine to a module.

18.2.3.1 Overlaying Lines in a Module - The first example illustrates
a technique for overlaying lines in a module using a patch file.
First, PAT appends the correction file to the input file.
Then,
the
Task Builder generates a task image from the patched object modules.
The input file for this example is:
.TITLE
• !DENT

ABC
/01/

MOV
CALL
RETURN
.END

A,C
XYZ

ABC::

18-4

'!iliJ ii

4il

if 24

OBJECT MODULE PATCH UTILITY (PAT)
To add the instruction ADD A,B after the CALL instruction, you can use
the following patch in the correction file:
.TITLE ABC
• !DENT /01. 01/
.=.+12
ADD
REr.rURN
.END

A,B

You use the MACR0-11 assembler to assemble the correction file.
After
assembly, PAT processes the resulting obj~ct module and the input
object module.
The result of PAT processing appears as follows:
.TITLE
• !DENT

ABC
/01.01/

MOV
CALL

A,C
XYZ

ABC::
RE~ruRN

'-';

.=ABC
.=.+12
ADD
RETURN
.END

A,B

You then use the Task Builder to produce the patched object module as
a task image.
This task image looks the same as the source code would
have looked if it had originally been written as follows:
.TITLE
• !DENT

ABC
/01. 0 l/

MOV
CALL
ADD

A,C
XYZ
A,B

ABC:::

RE~ruRN

.END
PAT uses the .=.+12 in the program counter field to determine where to
begin overlaying instructions in the program.
It overlays the RETURN
instruction with the patch code:
ADD
RE'rURN

A,B

18.2.3~2

Adding a Subroutine to a Module - The second
example
illustrates a technique for adding a subroutine to an object module.
A patch often requires that more than a few lines be added to correct
the file.
A convenient technique for adding new code is to append it
to the end of the module as a subroutine. That way, you insert a CALL
instruction to the subroutine at an appropriate location. The CALL
instruction directs the program to branch to the new code,
execute
that code, and then return to inline processing.

18-5

OBJECT MODULE PATCH UTILITY (PAT)
The input file for the example is:
.TITLE
• IDENT

ABC
/01/

ABC::
MOV
CALL
MOV
RETURN

A,B
XYZ

C,RO

.END
The correction file for this example is:
.TITLE
• IDENT
CALL
NOP
.PSECT

ABC
/01.01/
PATCH

MOV
MOV
ASL
RETURN
.END

A,B
D,RO
RO

PATCH

PATCH:

PAT merges the correction file with the input file, as in the first
example.
The Task Builder then processes the files and produces a
task image that looks the same as the source file would have looked if
it had originally been written as follows:
.TITLE
• IDENT

ABC
/01.01/

CALL
NOP
CALL
MOV
RETURN

PATCH
XYZ

.PSECT

PATCH

MOV
MOV
ASL
RETURN
.END

A,B
D,RO
RO

ABC::

C,RO

PATCH:

1n this example, the CALL
PATCH and NOP instructions overlay the
3-word MOV A,B instruction.
(The NOP is included because this is a
case where a 2-word instruction replaces a 3-word instruction and NOP
is required to maintain alignment.)
The Task Builder allocates
additional storage for .PSECT PATCH, writes the specified code into
this program section, and binds the CALL instruction to the first
address in this section. The MOV A,B instruction,
replaced by the
CALL PATCH instruction, is the first instruction executed by the PATCH
subroutine.

18-6

ii .I DUS

f'I UM

OBJECT MODULE PATCH UTILITY (PAT)
18.2.4

Determining and Validating the Contents of a File

You use the Checksum switch
(/CS)
to determine or validate the
contents of a module.
The switch directs PAT to calculate the
checksum (in octal) for all the binary data that constitutes the
module and then inform you of the checksum by means of a diagnostic
message.
To determine the checksum of a file, enter the PAT command line with
the CS switch applied to that file's specification.
For example:
=MYFILE/CS,CORRECT.POB
The command directs PAT to calculate the checksum for the input
MYFILE~
PAT then responds with the message:

file,

INPUT MODULE CHECKSUM IS checksum
PAT generates a similar message when you request the checksum for
correction file.
For example:

the

=MYFILE,CORRECT.POB/CS
Aft~!r calculating the checksum for the correction file,
with the message:

PAT

responds

CORRECTION INPUT FILE CHECKSUM IS checksum
If you specify /CS:number to validate the size of a file,
PAT
calculates the checksum for the file and then compares that checksum
with the value you specified as number.
If the two values do not
match,
PAT displays the following message to report the checksum
err<>r:
ERROR IN FILE filename CHECKSUM
For example, you might specify:
=MYFILE,CORRECT.POB/CS:432163
When PAT calculates the checksum for the correction file,
is different.
PAT then displays the message:

the

number

ERROR IN FILE CORRECT.PCB CHECKSUM
Checksum processing always results in an octal, nonzero value.

18.3

PATCIB MESSAGES

PAT generates messages that state checksum values and messages that
describe error conditions.
For checksum values and nonfatal error
messages, PAT prefixes the messages with:
PAT -·- *DIAG*-error message
For messages the describe errors that caused
uses the pref ix:
PAT -- *FATAL*-error message

18-7

PAT

terminate,

PAT

OBJECT MODULE PATCH UTILITY (PAT)
The messages described below are grouped according to message type, as
follows:

• Lnformation messages
• Command line errors
• File specification errors
• Input/output errors
• Errors in file contents or format
• Internal software error
• Storage allocation error
18.3.1

Information Messages

The following messages describe results of checksum processing.
CORRECTION INPUT FILE CHECKSUM IS checksum
file
Explanation: When you specify /CS in the correction
specification, PAT informs you of the file's checksum value. The
value is given in octal.
User Action:

No response necessary.

INPUT MODULE CHECKSUM IS checksum
file
Explanation: When you
specify
/CS
in
the
input
specification, PAT informs you of the file's checksum value. The
value is given in octal.
User Action:

18.3.2

No response necessary.

Command Line Errors

The following errors result from failure to adhere to the command line
syntax rules.
COMMAND LINE ERROR command line
Explanation: The system standard command line processor
detected an error in the command line.
User Action:

(.GCML)

Reenter the command line using the correct syntax.

COMMAND SYNTAX ERROR command line
Explanation:

The command line contained a syntax error.

User Action:

Reenter the command line using the correct syntax.

18-8

OBJECT MODULE PATCH UTILITY (PAT)
ILLEGAL INDIRECT FILE SPECIFICATION command line
Explanation: You used an indirect command
that contains one of the following errors:

file

specification

•

A syntax error

•

A specification for a nonexistent indirect command file

User Action: Check for file specification syntax errors or
ensure that the specified file is contained in the specified User
File Directory. Reenter the command line.
MAXIMUM INDIRECT FILE DEPTH EXCEEDED command line
Explanation: In the command line, you specified an indirect
command file that exceeds the maximum nesting level of 2 that is
permitted by PAT.
User Action: Reorder your files so that they do not exceed PAT's
nesting limit.
~·

18.3.3

File Specification Errors

The following messages are caused by errors in the
input or output files or related file switches.

specification

CORRECTION INPUT FILE MISSING command line
Explanation:

The mandatory correction file was not specified.

User Action:
file.

Reenter the command line specifying the

correction

ILLEGAL DEVICE/VOLUME SPECIFIED device name
Explanation: The device or volume name specification contained a
syntax error.

'--'·'

User Action: Check the rules for specifying devices and volumes,
then reenter the command line.
ILLEGAL DIRECTORY SPECIFICATION directory name
Explanation:
error.

The

directory

specification

User Action: Check the rules
reenter the command line.

for

contained

specifying

syntax

directory

and

ILLEGAL FILE SPECIFICATION filename
Explanation:

The file specification contained a syntax error.

User Action: Reenter the command line using the
for the file specification.

18-9

correct

syntax

OBJECT MODULE PATCH UTILITY (PAT)
ILLEGAL SWITCH SPECIFIED filename
Explanation: An unrecognized
specified with the file.

switch

User Action: Check the rules
reenter the command line.

for

value

was

switch

and

associated

with

switch

specifying

the

INVALID FILE SPECIFIED filename
Explanation: The specification for filename is
one of the following error conditions:
•

Nonexistent device

•

Nonexistent directory
the directory in
the
filename
specification does not exist on the specified device (or on
the default device if no device was specified)

User Action: Reenter the command
device or directory.

line

specifying

the

correct

MULTIPLE OUTPUT FILES SPECIFIED command line
Explanation:

PAT accepts only one output file specification.

User Action:
file.

Reenter the command line specifying only one output

REQUIRED INPUT FILE MISSING command line
Explanation: The mandatory input file was not specified
command line.
User Action:

the

Reenter the command line specifying an input file.

TOO MANY INPUT FILES SPECIFIED command line
Explanation: Too many input files were specified in the command
line.
PAT
accepts
only
the input and correction file
specifications.
User Action:
files.

Reenter the command

line

specifying

the

correct

UNABLE TO FIND FILE filename
Explanation: PAT
correction file.

could

not

locate

the

specified

input

User Action: Check the directory to ensure that the file exists.
Reenter the command line.

1''
18-10

"''a

I ii

I I 424

OBJECT MODULE PATCH UTILITY (PAT)
18. 3. 4
~i:

In~•ut/Output

Errors

The error messages listed below are caused by
PAT was peI·forming I/O to the specified file.
ERROR DURING CLOSE:

FILE:

faults

detected

while

filename

Explanation: This error is most likely to occur while PAT is
attempting to write the remaining data into the output file
before de-accessing it. The most likely causes of this error are
the following conditions:
•

The device is full

•

The device is write-locked

•

A hardware error occurred

User Action: Perform the appropriate corrective action and
reenter the command line:
if the device is full, delete all
unnecessary files;
if the device is write-locked, write-enable
it;
if the problem is a hardware error, contact your DIGITAL
Field Service representative.
ERROR POSITIONING FILE filename
Explanation:
end-of:-f ile.

PAT

attempted

position

the

file

beyond

User Action: Submit a Software Performance Report along with the
relatE~d console dialogue and any other pertinent information.
I/O ERROR ON INPUT FILE filename
Explanation: An error was detected while PAT was attempting to
read the specified input file. The principal cause of this error
is a device hardware error.
User Action:

Reenter the command.

I/O ERROR ON OUTPUT FILE filename
Explanation: An error occurred while PAT attempted to write into
the named output file. The most likely causes of this error are
the following conditions:
•

The device is full

•

The device is write-locked

•

A device hardware error occurred

18-11

OBJECT MODULE PATCH UTILITY (PAT)
18.3.5

Errors in File Contents or Format

The following errors represent inconsistencies detected by PAT in
format or contents of the input or correction files.

the

""
~·

ERROR IN FILE filename CHECKSUM

I :r

Explanation: The checksum that PAT calculated for the named file
does not match the one that you specified with /CS:number.
User Action: Ensure that you specified the correct checksum. If
the checksum is correct, then you specified an invalid version of
the file. Rerun PAT specifying the correct version of the file.
FILE filename HAS ILLEGAL FORMAT
Explanation: The format of the named file is not compatible with
the object files produced by the standard DIGITAL language
processors or accepted by the Task Builder. The principal causes
are:
•

Truncated input file

•

Input file that consists of text

User Action: Ensure that the file is in the correct
resubmit it for PAT processing.

format

and

INCOMPATIBLE REFERENCE TO GLOBAL SYMBOL symbol name
Explanation: The correction file contains a global symbol whose
attributes do not match one or more of the following input file
symbol attributes:
•

Definition or reference

•

Relocatable or absolute

User Action:
attributes.
processing.

Update the correction file by modifying the symbol
Reassemble the file and resubmit it for PAT

INCOMPATIBLE REFERENCE TO PROGRAM SECTION section name
Explanation: The correction file contains a section name whose
attributes do not match one or both of the following input file
section attributes:
•

Relocatable or absolute

•

Defined with the same directive (.PSECT or .CSECT}

User Action: Update the correction file by modifying the section
attribute or changing the section type. Reassemble the file and
resubmit it to PAT for processing.

18-12

111aa

Sb!

OBJECT MODULE PATCB UTILITY (PAT)
UNABLE TO LOCATE MODULE module name
Explanation: PAT could not find the module name that was
specified in the correction file in the file of concatenated
input modules.
User Action: Update the input file specification to include
missing module. Reenter the command line.

18.3.6

the

Internal Software Error

This error reflects internal software error conditions.
ILLEGAL ERROR-SEVERITY CODE error data
Explanation: An error message
parameter, has been generated.

call,

containing

illegal

User Actionx
If these messages persist,
submit a Software
Performance Report along with related console dialogue and any
other pertinent information.

18.3.7

Storage Allocation Error

The following error message indicates that not enough task memory
available for storing global symbol and program section data.

was

NO DYNAMIC STORAGE AVAILABLE storage-l.isthead
Explanation: Not enough contiguous task memory was available
satisfy a tequest for the allocation of storage.
PAT displays the contents of the 2-word dynamic storage
in octal.

listhead

User Action: If possible, PAT should be reinstalled with a
larger
increment
or
in
a
bigger partition.
(See the
RSX-llM/M-PLUS MCR Operations Manual.)

18-13

i2 !i I

14•

CHAPTER 19
TASK/FILE PATCH PROGRAM (ZAP)

The Task/File Patch Program (ZAP) allows you to directly examine and
modify files on a Files-11 volume.
Using ZAP, you can patch data
files or task images interactively without reassembling and rebuilding
the task.
ZAP performs many of the functions performed by the RSX-11 On-Line
a knowledge of ODT is
Debugging Technique program
(ODT).
Thus,
helpful in using ZAP. See the IAS/RSX-11 ODT Reference Manual for
information on ODT.
ZAP provides the following features:
•

Command line switches that allow you to access specific words
and bytes in a file, modify locations in a task image, list
the disk block and address boundaries for each overlay segment
in a task disk image, and open a file in read-only mode

•

A set of internal
Registers

•

Single-character commands that,
in combination with other
command line elements, allow you to display, open, close, and
manipulate the values in task images and data files

registers

that

include

eight

Relocation

Except in read-only mode, the results of ZAP commands are permanent.
Thus:,
the safest way to use ZAP is with a hard-copy terminal, so you
have a record of the changes you make.
Although the ZAP utility functions are relatively straightforward to
use,
patching locations in a task image requires knowing how to use
the memory allocation file (or map) generated by the Task Builder as
well as the listings generated by MACR0-11. These maps and listings
provide information you need to access the locations whose contents
you want to change.
For information on Task Builder maps, see the
RSX-· llM/M-PLUS Task Builder Manual.
For information on MACR0-11
listings, see the IAS/RSX-11 MACR0-11 Reference Manual.

19.1

INVOKING AND TERMINATING ZAP

You cannot include a command line on the same line on which you invoke
ZAP~
That is, you cannot type ZAP filespec.

19-1

TASK/FILE PATCH PROGRAM (ZAP)
To invoke ZAP, you enter only the utility name, followed by a carriage
return, and wait for ZAP to prompt you.
Then, enter the file
specification for the file you want to change.
You enter the file
specification in the format:
dev: [group,member]filename.filetype;version[/sw ••• ]
the

file

This command exits

from

The default file type is .TSK.
After
you
specification, ZAP prompts with an underscore (_).
You terminate ZAP by entering the X command.
ZAP and returns control to MCR.

enter

Section 19.2 describes the ZAP switches and their functions.

19.2

ZAP SWITCHES

Switches set the mode in which ZAP operates. There are three modes:
task image (default) and absolute, both of which are addressing modes,
and read-only. The modes and their switches are described below:
•

Task image mode is the default mode for ZAP.
In this mode,
addresses in ZAP command lines refer to addresses in the task
image file as they are shown in the Task Builder map for the
file.
(ZAP processing is identical to ODT run-time processing
in this case.)

•

When you specify absolute mode (/AB), ZAP processes the
addresses you e'nter in ZAP command lines as absolute byte
addresses within the file. You should specify /AB for files
that are not in task image format, but you can also specify
the switch for files that are.

•

When you specify read-only mode (/RO), ZAP opens the file in
read-only mode.
That is, you can execute ZAP functions that
change the contents of locations, but these changes are not
permanent.
When ZAP exits, the original values in the task
image file are restored.

In addition, you can specify /LI in task image and read-only modes
(but not in absolute mode). This switch displays the starting disk
block and address boundaries for each overlay segment in the file in
the format:
ssssss:

aaaaaa-bbbbbb

ssssss:
The starting block in octal.
aaaaaa
The lower address boundary in octal.
bbbbbb
The upper address boundary in octal.

19-2

TASK/FILE PATCH PROGRAM (ZAP)
19.3

ADDRESSING LOCATIONS IN A TASK IMAGE

To address locations in a task image,
ZAP provides two addressing
mode:s and a set of internal registers, which include eight Relocation
Registers.
This section first introduces the concept of relocation
biases and the use of the Relocation Registers, then explains the
addressing modes.

19.3.1

Relocation Biases

When MACR0-11 generates a relocatable object module, the base address
of each program section of the module is 000000. In the assembly
listing, all locations in the program section are shown relative to
this base addresso
The Task Builder links program sections to other program sections by
mapping the relative addresses applied by the assembler to the
physical addresses in memory (for unmapped systems)
or to virtual
addresses (for mapped systems).
Many values within the resulting task image are biased by a constant
whose value is the absolute base address of the program section after
the section has been relocated.
This bias is called the relocation
bias for the program section.
ZAP's eight Relocation Registers, OR through 7R, are generally set to
the relocation biases of the modules to be examined. This allows you
to refer to a location in a module by the same relative address that
appears in the MACR0-11 listing.
The addressing modes help you
calculate the relocation biases.

19.3.2

ZAP Addressing Modes: Absolute and Task Image

The two modes for addressing locations in a task image are absolute
mode and task image mode.
Task image mode is the default mode for
ZAP.
You can examine locations in a file in either absolute or task image
mode using the RO switch.
/RO allows you to open and temporarily
change the contents of locations. When ZAP exits, the file
is still
in its original form.
If you specify /LI to display block/segment information,
task image mode after the information is displayed.

ZAP

19.3.2.1 Using the Absolute Addressing Mode - To use ZAP in absolute
mode, enter /AB with the file specification after you invoke ZAP.
In absolute mode, ZAP interprets the first address in the file you are
changing as segment l, location 000000. All other addresses you enter
are interpreted using this address as the base location.
Absolute
mode allows you to access all the bytes in a file as well as the label
and header blocks of a task disk image.
However,
to modify a task
disk image in absolute mode, you must know the disk layout of the task
disk image. Generally, this mode is practical only for data files or
for task image files that are not overlaid.

v
19-3

TASK/FILE PATCH PROGRAM (ZAP)

19.3.2.2 Using the Task Image Addressing Mode - In task image mode,
ZAP allows you to address locations using the block number and
relative offset listed in the Task Builder map. Task image mode is
useful for changing locations in a file constructed of overlay
segments because the Task Builder and ZAP perform the calculations
necessary to relate the task's disk structure to its run-time memory
structure.

.,,.,_:
.... -" ····.·
-

The Task Builder adds blocks containing system information to the
beginning of a task image file.
The map generated by the Task Builder
gives you the starting block and byte offset of the file you want to
change.
~n

task i~age mode, ZAP allows you to address locations in a task
image using the block number and byte offset listed in the Task
Builder map and addresses that MACR0-11 prints in an assembler output
listing.
The following excerpts from a MACR0-11 listing and a map
generated by the Task Builder show how to use ZAP in task image mode.
The following lines represent assembled instructions from
source listing:
71
72
73
74
75
76
77

000574
000602
000604
000610
000614
000620
000624

032767
001002
000167
016700
016000
010067
032760

OOOOOOG OOOOOOG
000406
OOOOOOG
OOOOOOG
177534
OOOOOOG OOOOOOG

2$:

BIT
BNE
JMP
MOV
MOV
MOV
BIT

MACR0-11

#FE.MUP,$FMASK
2$
30$
$TKTCB,RO
T.UCB(RO),RO
RO,UCB
#U2.HLD,U.CW2(RO)

The following excerpt from a Task Builder map gives the information
you need to address locations in the task image file as they appear in
the above MACR0-11 listing:
R/W MEM
DISK BLK

LIMITS: 120000 123023 003024 01556.
LIMITS: 000002 000005 000004 000-04.

MEMORY ALLOCATION SYNOPSIS:
TITLE !DENT

SECTION
BLK.: (RW,I,LCL,REL,CON)
$$RESL:(RW,I,LCL,REL,CON)

120232
120232
122476
123000

002546
002244
000064
000024

01382.
01188.
00052.
00020.

MYFILE
FMTDV

01
01

FILE
MCR.OLB;l
MCR.OLB;l

Using information in the map above, you can determine the block number
and byte offset for the beginning of the file you want to change. The
disk-block-limits line lists block 2 as the block where the code
segment begins.
The synopsis lists byte offset 120232 as the
beginning of the file,
MYFILE.
To address location 574 in the
MACR0-11 listing in task image mode, specify the command:
2:120232+574/<CR>
ZAP responds by opening the location and displaying its contents:
002:121026/ 032767

19-4

lilll•

225 2

Lilt i i I

TASK/FILE PATCH PROGRAM (ZAP)
THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS

19.4

ZAP commands perform functions that allow you to
the contents of locations in a task image
comprise combinations of the following elements:
•

Commands

•

Internal registers

•

Arithmetic operators

•

Command line element separators

•

The current location symbol

•

Location-specifier formats

examine and modify
file.
Command lines

The command elements can be combined with each other to perform
multiple functions. The function of a given command line depends not
only on which elements you use,
but also on the position of one
element in relation to the next.
The following sections describe the ZAP
Sections 19.5 and 19.6 describe how to
elements to execute ZAP functions.

19.4.l

command line elements.
combine the command line

ZAP Commands

There are three types of ZAP commands:
•

Open/close location commands

•

General-purpose commands

•

Carriage return

19.4.1.l Open/Close Location Commands - Open/close location commands
are nonalphanumeric ASCII characters that direct ZAP to perform a
sequence of functions.
Open/close commands specify two general
sequences of operations:
•

Open a location, display its contents, and store the
in the Quantity Register (see Section 19.4.2)

contents

•

Close the location after (optionally) modifying
another location as specified by the command

and

Section 19.5 describes the format for specifying
commands.

open/close

open

location

19.4.1.2 General-Purpose
Commands - ZAP
provides
six
single-character, general-purpose commands.
You use these commands
for calculating displacements, verifying location contents,
and
exiting from ZAP. You can enter some of the commands on the command
line with no other parameters. Section 19.6 describes the format for
specifying these commands.

19-5

TASK/FILE PATCH PROGRAM (ZAP)
19.4.l.3 Carriage Return - Unless there is another value or command
on the line,
the carriage return closes the current location as
modified and opens the next sequential location.
Unlike ODT, ZAP
commands take effect only after you enter a carriage return.

19.4.2

ZAP Internal Registers

ZAP internal registers are fixed storage locations that ZAP uses as
registers.
These registers contain values set by both you and ZAP.
ZAP provides the following internal registers:
•

Relocation Registers 0 through 7
(OR through 7R).
These
registers provide a means for indexing into a module to change
the contents of locations in the module.
You load the
registers with the base address of the modules that have been
relocated by the Task Builder.

•

The Constant Register (C). You set this register to contain a
16-bit value, which can be specified as an expression.

•

The Format Register (F).

•

The Quantity Register (Q).
ZAP sets the value in the register
to be the last value displayed at your terminal.

This register controls the format of
the displayed address.
If the value of the F Register is O
(the init~al value), ZAP displays addresses relative to the
largest value of any Relocation Register whose value is less
than or equal to the address to be displayed.
If the value of
the Format Register is not O, ZAP displays addresses in
absolute format.

To access the contents of the registers, specify
preceding the register when you enter a command.

a dollar sign
For example:

($)

$C/
This command directs ZAP to display
Register.
(The slash,
/,
is an
19-3.)

19.4.3

the contents of the Constant
open command, described in Table

ZAP Arithmetic Operators

Operators are single-character command line elements that define an
arithmetic operation in a command line expression. Generally, ZAP
evaluates these expressions as addresses.
Table 19-1 describes the
operators.
You use the operators in expressions in command lines.
For example,
rather than manually adding all the displacements listed in the Task
Builder map, you can specify a location using the following notation:
2:120000+170/
This method for calculating such a displacement
accurate than doing it manually.

faster

and

19-6

I I

0 21 I I

hill

!! h I

l'i\

TASK/FILE PATCH PROGRAM (ZAP)
Table 19-1
ZAP Arithmetic Operators
Operator

Function

Adds a value to another value.
Used in an expression
that ZAP then evaluates to be a command line element.

Used in an
Subtracts a value from another value.
expression that ZAP then evaluates to be a command
line element.

Multiplies a value by 50 ( 8) and adds
it
Used to form a Radix-50 string.
value.

another

The following example shows how to use the asterisk
(*)
to form
Radix-50 strings.
(Section 19.4.4 explains the use of the colon and
comma;
the percent sign, %, is an open command,
described in Table
19-3.)

0,40/<CR>
002:0,000040/

000000

O*l<CR>
-/<CR>
002:0,000040/

000001

l* 33<CR>
-/<CR>
002:0,000040/

000103

%<CR>
002:0,000040%

19.4.4

ZAP Command Line Element Separators

ZAP provides separators to delimit one command line element from
another.
Different separators are required depending on the type of
ZAP command being executed.
Table 19-2
ZAP Command Line Element Separators
Se!parator

Function
Separates a Relocation Register
another command line element.

specification

from

Separates an address from an internal
register
specification.
Used in expressions that set values
for Relocation Registers.
Separates a block number base value from an offset
into the block.
Used in most of the references to
locations in a file.

19-7

TASK/FILE PATCH PROGRAM (ZAP)
19.4.5

The Current Location Symbol

In command line expressions that ZAP evaluates as addresses, a
(.) represents the last open location.

period

ZAP Command Line Location-Specifier Formats

19.4.6

ZAP has three formats for specifying locations in a command line.
Each provides ~ means of indexing into the task image file.
The
formats are:
•

Byte off set

•

Block number:byte offset

•

Relocation register, byte offset

19.4.6.l
follows:

Byte Offset Format - You specify the byte offset

format

location
If you are using ZAP in absolute moda,
ZAP
interprets
this
specification as a byte offset from block l, location 000000. If you
are using ZAP in task image mode, ZAP interprets this specification as
a byte offset from block O, location 000000.
This format is generally useful only when you are using ZAP in
absolute mode. For example, the following ZAP command opens absolute
location 664:
664/<CR>

19.4.6.2 Block Number:Byte Offset Format - This format allows you to
specify a byte offset from a specific block in the task image file.
Specify the format as follows:
blocknum:byteoffset
You can use this format for addressing locations whether
enter /AB with the file specification.

not

The Task Builder prints
segments:

overlay

R/W MEM
DISK BLK

LIMITS:
LIMITS:

map

that

gives

information

you

120000 123023 003024 01556.
000002 060005 000004 00004.

MEMORY ALLOCATION SYNOPSIS:
SECTION
• BLK.: (RW,I ,LCL,REL,CON)
$$RESL:(RW,I,LCL,REL,CON)

TITLE
120232
120232
122476
123000

002546
002244
000064
000024

01382.
01188. MYFILE
00052. FMTDV
00020.

!DENT
01
01

FILE
MCR.OLB;l
MCR.OLB;l

19-8

lllAE $iii

t t Si

14*

TASK/FILE PATCH PROGRAM (ZAP)
In task image mode, ZAP allows you to enter the block number and byte
offset displayed in the Task Builder map. In the example above, the
disk-block-limits line shows MYFILE beginning on block 2.
The
synopsis shows that MYFILE has an offset of 120232.

19.4.6.3 Relocation Register:Byte Offset Format - This format allows
you to load a Relocation Register with the value of a location. The
value is then used as a relocation bias. You specify this format for
addressing locations in a task image file as follows:
relocreg,byteoffset
Specify relocreg in the form nR, where n is the number of the
Relocation Register. You can then address byte offsets from the value
loaded in the Relocation Register. For example:
2:120232;3R<CR>
3,574/<CR>
The first command sets the value of Relocation Register 3, then the
second command opens the location that is 574 bytes offset from block
(segment ) 2 , 1o cation l 2 0 2 3 2 •

19.5

USING ZAP OPEN/CLOSE COMMANDS

This section is an overview of how to use the ZAP open/close commands,
which allow you to open locations in a task image file, modify those
locations, and close the locations.
Table 19-3 summarizes the open/close commands.
Table 19-3
ZAP Open/Close Commands
Character

Function

Designation

I---·

Slash

Opens
displays
its
a
location,
contents in octal, and stores the
the
contents of the location
in
( Q) •
Quantity
Register
If
the
location is odd, it is opened as a
byte.

Quotation marks

Opens
displays
the
a
location,
contents of the location as two ASCII
characters, and stores the contents of
the location in the Quantity Register
(Q) •

Percent sign

Opens a
displays
the
location,
contents of the location in Radix-50
format, and stores the contents of the
location in the Quantity Register ( Q) •
(continued on next page)

19-9

TASK/FILE PATCH PROGRAM (ZAP)

Table 19-3 (Cont.)
ZAP Open/Close Commands
Character

Designation

Function

Backslash

Opens a location as a byte, displays
the contents of the location in octal,
and stores the
contents
of
the
location in the Quantity Register (Q).

Apostrophe

Opens
a
location,
displays
the
contents as one ASCII character, and
stores the contents of the location in
the Quantity Register (Q).

Circumflex or
Up-arrow

Closes the currently open location as
modified and opens
the
preceding
location.

Underscore or
Back-arrow

Closes the currently open location as
modified, uses the contents of the
location as an offset from the current
location
value,
and
opens
that
location.

At sign

Closes the currently open location as
modified, uses the contents of the
location as an absolute address, and
opens that location.

Right angle
bracket

Closes the currently open location as
modified, interprets the
low-order
byte of the contents of the location
as the relative branch offset and
opens
the target location of the
branch.

Left angle
bracket

Closes the currently open location as
modified, returns to the location from
which the last series of underscore
( ) , at sign (@), and/or right angle
bracket (>) commands began, and opens
the next sequential location.

19.S.l

Opening Locations in a Task Image File

Use any of the five ZAP open commands -- slash (/), quotation marks
("), percent sign (%), backslash (\), or apostrophe (') -- to open a
location in a task image file. The format in which ZAP displays the
contents of the open location depends on which operator you use.
Once you open a location in a given format,
ZAP displays in that
format any other locations you open. For example, if you enter the
percent sign (%) command, the contents of the open location are
displayed in Radix-SO format.
If you enter consecutive carriage
returns, consecutive locations are displayed in Radix-SO format until
you change the format by entering a different special-character open
command.

19-10

$ ' 22

I a;

TASK/FILE PATCH PROGRAM (ZAP)
19.5.2

Changing the Contents of a Location

When you open a location with a special-character open command, you
can change the contents of that location by entering the new value and
a carriage returne The following example is a sequence of commands
and ZAP responses that shows how to open a location, change the value
of the location, and close the location.
<CR>
002:120000/ 000000
44444<CR>
-./<CR>
002:120000/ 44444
The first command
( ) displays the contents
(000000)
of a word
location.
The contents are changed by entering the value 44444, and
then the location is closed as modified by entering a carriage return.
The slash (/) followed by a carriage return displays the new contents
of the location (last line of example). The slash indicates that word
locations are being opened and their contents displayed in octal
format.

19.5.3

Closing Task Image Locations

ZAP has five special-character commands for closing a
location in a
task image.
(The carriage return also closes locations.) The close
commands perform three functions:
•

Close the current location

•

Direct ZAP to another location. (such as the preceding location
or a location refered to by the current location)

•

Open the new location

The following sections give examples of how each command works.

19.5.3.l Close a Location and Open the Preceding Location - Use the
circumflex
(A)
or up-arrow
Ct) command (depending on the type of
terminal you are using) to close the current location, to direct ZAP
to the preceding location,
and to open that location. The ASCII
representation of both the circumflex and up-arrow is 136(8).
The
following sequence of ZAP commands and responses shows how this
command works:
2:120100/<CR>
002:120100/ 000000
<CR>
002:120102/ 000111
<CR>
002:120104/ 000222
<CR>
002:120106/ 000333
"'<CR>
002:120104/ 000222
The carriage return closes the first three open locations and then
opens the next location. The circumflex closes location 120106 and
directs ZAP to open the preceding location, 120104.

19-11

TASK/FILE PATCH PROGRAM (ZAP)

Close a Location and Open a Location at an Offset from the
Location Counter - Use the underscore ( ) or back-arrow <-> command to
close the current location, to direct ZAP to use the contents of the
current location as an offset from the current location, and to open
that location. The ASCII representation of both the underscore and
back-arrow is 137(8).
The following sequence of ZAP commands and
responses shows how this command works:

19.5.3.2

2:120100/<CR>
002:120100/ 000000
<CR>
002:120102/ 111111
<CR·>
002:120104/ 222222
<CR>
002:120106/ 000022
<CR>
002:120132/ 123456
The carriage return closes the first three ope~ locations.
The
underscore closes location 120106, directs ZAP to use the contents
(22) of the current location as the offset from the current location
(120110), and then opens that offset location (120132).

19.5.3.3 Close a Location and Open a Location Offset from the Value
of the Just-Closed Location - Use the at sign (@) command to close a
location, to direct ZAP to use the contents of the just-closed
location as the absolute address of a location, and to open that
location. The following sequence of ZAP commands and responses shows
how this command works:
2:120100/<CR>
002:120100/ 000000
<CR>
002:120102/ 111111
<CR>
002:120104/ 120114
@<CR>
002:120114/ 114114
The carriage return closes the first three open locations.
The at
sign closes 120104, directs ZAP to use the contents (120114) of that
location as the absolute address of the next location to open, and
then opens that location.

Close a Location and Open the Target Location of a Branch
Instruction - Use the right angle bracket (>) command to close the
current location, to direct ZAP to use the low-order byte of the
contents of the just-closed location as a branch offset, and then to
open that location.
The following sequence of ZAP commands and
responses shows how this command works:
19.5.3.4

2:120100/<CR>
002:120100/ 005000
<CR>
002:120102/ 005301
<CR>
002:120104/ 001020
><CR>
002:120146/ 052712

19-12

I I.

I ii

!2 ! 2 !!! $! &

.ii

Ziiiii

;412

TASK/FILE PATCH PROGRAM (ZAP)

'--"

The carriage return closes the first three open locations.
The right
angle~
bracket command closes location 120104, directs ZAP to use the
low-order byte of its contents (020) as the branch offset for the
addre!SS of the next location (120146), and then opens that location.

19.5.3.5

Close a Location and Open the Location Where the Current
of Commands Began - Use the left angle bracket (<) command to
close the current location;
to direct ZAP to the location where the
current series of underscore
( ),
at sign (@), and/or right angle
bracket (>) commands began;
and tlien to open that location.
The
following sequence of ZAP commands and responses shows how this
commaind works:

SeriE~s

1202;0R<CR>
:·o,
0/ <CR>
002:0,000010/ 005212
l

<CR>
002:0,005224/
><CR>
002:0,005266/
@<CR>
002:0,000000/
«CR>
002:0,000012/

'-'

001020
000000
000000
000430

The underscore command directs ZAP to location 005224.
The right
anglE~
bracket command directs ZAP to location 005266, and the at sign
command directs ZAP to location 000000.
The left angle bracket
command then directs ZAP to location 000012, which is the next
sequential address after the location where the sequence of commands
began.

19.6

USING ZAP GENERAL-PURPOSE COMMANDS

This section explains the functions of ZAP general-purpose commands
and shows the formats for specifying them. Table 19-4 describes the
commands.
(Table 19-4 is on the following page.)

19.6~1

Exit from ZAP

Use the X command to terminate ZAP and then return control to MCR.
Specify the X command in the format:

x
The underscore

19.6.2

(_) is the ZAP prompt.

Compute an Offset and Store It in the Quantity Register

Use the K command to compute the offset between the value of the
near~~st
(less than or equal to) Relocation Register and the currently
open location, to display the offset value, and to store it in the
Quantity Register (Q).

19-13

TASK/FILE PATCH PROGRAM (ZAP)
Table 19-4
ZAP General-Purpose Commands
Command

Function

Exits from ZAP, returns to MCR

Computes the offset between the value of the nearest
(less than or equal to) Relocation Register and the
currently open location, displays the offset value,
and stores it in the Quantity Register (Q)

Displays the jump and branch displacements
current location to a target location

from

the

Displays in octal the value of the expression to
left of the equal sign

the

Verifies the contents of the current location

Sets the value of a Relocation Register

You can enter the K command in the following formats:
K

Calculates the displacement in bytes from the address of the
last open location and the value of the Relocation Register
whose contents are closest to but less than the value of
that address

Calculates the displacement in bytes
location and Relocation Register n

a;nK

Calculates the displacement between address a and Relocation
Register n

from

the

last

open

ZAP responds to the K command by displaying the Relocation Register it
used and the offset value it computed in the format:
=reg,offset
The following example shows how to use the K command:
_2:1172;0R<CR>
_2 :1232;1R<CR>
_2:1202/<CR>
002:000020/ 000111
_K<CR>
=0,000010
_O ,100 · lK<CR>
=1,000 640

19.6.3

Display the Branch and Jump Displacements from the Current Location

Use the O command to display the branch and jump displacements from
the current location to a target location. A branch displacement is
the low-order byte of a branch instruction which, when executed,
branches to the target location. A jump displacement is the offset
between the o~~n location and the target location.
The
jump
displacement is used in the second word of a jump instruction if the
instruction uses relative addressing.

19-14

m ess

I I

ayes

TASK/FILE PATCH PROGRAM (ZAP)
You can enter the 0 command in the following formats:

Displays the
jump and branch ~isplacements from
current location to the target of the branch (a)

a;rO

Displays the jump and branch displacements from location a
to target location r

the

The following example shows how to use the O command:
0,4534/<CR>
0,4534/ 1234
45660<CR>
-000030> 000014
-4534;45660<CR>
-000030> 000014
The first number (000030)
is the jump displacement,
number (000014) is the branch displacement.

\.....;'

19.6.4

the

second

Display the Value of an Expression

Use the equal sign command (=) to display (in octal) the value of an
expression to the left of the equal sign.
Specify the equal sign command in the format:
expression=
The following example shows how to use the equal sign command:
2:30/<CR>
002:000030/ 000000
.+177756=<CR>
000006

19.6o5

Verify the Contents of a Location

Use the V command to verify that a
value.

location

contains

specified

Specify the V command in the format:
contentsV
You use V to ensure that, before you have ZAP change them,
the
contents being changed are what they should be. The V command is
mainly useful in indirect command files because ZAP reports the
error and exits if the contents do not match.
That way, the
contents are not changed incorrectly.
The following example shows how to use the V command;
if you were
using an indirect command file, you would include this sequence of
ZAP commands in it.
0,1200
6V
10

19-15

TASK/FILE PATCH PROGRAM (ZAP)
ZAP opens the location that is 1200 offset from the value of
Relocation Register 0 and ensures that the value contained at the
location is 6. If so, ZAP changes the 6 to 10. If the value is not
6, ZAP terminates.

19.6.6

""
' IT

Set The Value For A Relocation Register

Use the R command to specify the value for a Relocation Register.
As explained above in Sections 19.3 and 19.4.2, ZAP uses these
registers to index into a module so that you can change the contents
of locations in the module.
Specify the R command in the format:
nR
The variable n is the number of the Relocation Register
7).

19.7

through

ZAP ERROR MESSAGES

This section lists the messages generated by ZAP, explains the
condition that causes each message, and suggests a response to the
message.
ZAP -- ADDRESS NOT WITHIN SEGMENT
Explanation: The address specified was not within the
segment specified.

overlay

User Action: Reenter the command using the correct address
overlay segment number.

ZAP -- CANNOT BE USED IN BYTE MODE
Explanation:
bracket
(>)
as a byte.

The at sign (@), underscore ( ), and right angle
commands cannot be used when a location is opened

User Action:
If the location is
location as a word.

even

address,

open

the

ZAP -- ERROR IN FILE SPECIFICATION
Explanation:

The file specification was entered incorrectly.

User Action:

Check the file specification and reenter it.

ZAP -- ERROR ON COMMAND INPUT
Explanation: An I/O error occurred while a command
read. This could be a hardware error.

was

being

User Action: Ensure that the hardware is functioning properly.
If it is, retry the command.
If not, call your Field Service
representative.

19-16

n•:

ULQ

;;a

TASK/FILE PATCH PROGRAM (ZAP)
ZAP -- I/O ERROR ON TASK IMAGE FILE
Explcmation: An I/O error occurred while the file being
modi 1:ied was being read or written.
This could be a hardware
error.

User Action:

Ensure that the hardware is functioning properly.
is, retry the command.
If not, call your Field Service
repn~sentat i ve.

ZAP -- NO OPEN LOCATION
Explcmation:
location.

You

attempted

modify

data

closed

User Action:

Open the location to perform the modification.

ZAP -- NO SUCH INTERNAL REGISTER
Explanation: The character following a dollar sign was
valid specification for the internal register.
User Action:
Reenter
the
command
specification for the internal register.

using

the

not

correct

ZAP -- NO SUCH RELOCATION REGISTER
Explanation:
Register.

An invalid number was specified for a

Relocation

User Action: Relocation Registers are numbered 0 through 7.
Any other numbers are
illegal.
Reenter the command using a
valid Relocation Register number.
ZAP --· NO SUCH SEGMENT
Explanation:
The starting disk block was not the start of
segment in the task disk image.
User Action:
add rE~SS.

Reenter the command using the correct disk

any
block

ZAP-- NOT A TASK IMAGE OR NO TASK HEADER
Explanation: An error occurred while the segment description
tables were being constructed.
Possibly, the file is not a
task image, /AB was not specified,
or the task
image is
defective.
User Action: Terminate the ZAP session, and try
with /AB specified.

invoking

ZAP

Explanation: You entered a command that is recognized by
but not implemented.

ZAP,

ZAP -- NOT IMPLEMENTED

User Action:

Ensure that you entered the command correctly.

19-17

TASK/FILE PATCH PROGRAM (ZAP)
ZAP -- OPEN FAILURE FOR TASK IMAGE FILE
Explanation: The file to be modified could not be opened.
Possibly, the file does not exist, the file is locked, the
device is not mounted, or you do not have write-access to the
file.
User Action: Check the file specifier for errors;
ensure that
the volume is properly mounted; or use PIP to check your file
access privileges (see Chapter 4).
ZAP -- SEGMENT TABLE OVERFLOW
Explanation: ZAP does not have enough room in its partition to
construct a segment table.
User Action: Install ZAP in a larger partition, or install ZAP
using a larger /INC value.
(See the RSX-llM/M-PLUS MCR
Operations Manual for information on /INC.)
ZAP -- TOO MANY ARGUMENTS
Explanation: You entered more arguments on
than are allowed.

the

command

User Action:
- syntax.

using

the

Reenter

the

command

line

correct

ZAP -- UNRECOGNIZED COMMAND
Explanation:

ZAP did not recognize the command as entered.

User Action: Check the syntax of the command you are trying to
execute and reenter the command using the correct syntax.
ZAP -- VERIFY FAILURE
Explanation: The command for verification (V) determined that
the contents of a location did not match the expected value.
ZAP terminates.
User Action: If applicable, check for errors in the indirect
command file.
Ensure that the contents of the file are what
they should be. Locate the cause of the error and ret(y the
command. Ensure that you are correcting the right file or file
version.

19-18

;;

APPENDIXES

-.,

: , ,,,

Wllll!C

3¢

v
APPENDIX A

COMMANDS AND SWITCHES

A.l

INTRODUCTION

This appendix presents a summary of the commands and/or switches used
by the RSX-11 utilities described in this manual.
Each of the
in number,
to the
numbered sections of this appendix corresponds,
chapter discussing that utility.
For example, Chapter 4 and Section
A.4 both deal with PIP.
Commands and switches are presented alphabetically within the sections
of this appendix,
regardless of their presentation in the various
chapters.

A.2

EDT COMMAND SUMMARY

Change [range]

[/NL]

Invokes Character Mode.
[/Q]

copy range-! %TO range-2 [/SEQ]

[/UN]
Copies the lines in range l to a position ahead of the first line
in range 2.
Del~:ite

[range]

[/Q]

Deletes lines from the buffer.
EXit [/RE:filespec]
Terminates EDT;
writes contents
specified output file.

the

main

text

buffer

Find range
Moves the line pointer to the first line in the range.
INClude [range) /FI:filespec [/SEQ]

[/UN]

Locates a file and copies it into a text buffer.
Ins~~rt

[range]

[/SEQ]

[/UN]
Inserts text typed at a terminal in the buffer ahead of the first
line in the range.

A-1

COMMANDS AND SWITCHES

[/Q]

Move range-1 %TO range-2 [/SEQ]
[/UN]
Transfers the lines in range l to a position ahead of
line in range 2.

the

first

Generates an output file from the contents of the range.
output file contains EDT line numbers as part of the text.

The

Terminates EDT;
files.

generates

First deletes the lines in the range, then inserts text typed
the terminal into the buffer in place of the deleted text.

PRint [range] /FI:filespec

QUIT

Replace [range]

saves no edits or text

buffers;

[/SEQ]
[/UN]

RESequence [range]

[/SEQ]
[/UN]

Assigns new line numbers to the lines in the range.
RESTore /FI:filespec
Locates the specified file created by a Save command;
uses the
file's contents to restore the status and contents of the text
buffers.
SAve /FI:filespec
Creates a file that contains the status and contents of the
buffers currently in use.
CASE
EXACT

l
l

text

UPPER
LOWER
NONE

{ CASE}
NONE

SET
TErminal

HCPY
VTOS
VTSO
VT52
VT55
VT61
LA30
LA36

Establishes criteria that other EDT commands use in their
operation;
flags
uppercase or lowercase characters;
and
establishes proper terminal parameters.

A-2

I~·-

COMMANDS AND SWITCHES

SHow

Buffers
CAse
EXACT
TErminal
VE rs ion

Displays the values established by the Set command, as
current buffer status and software version information.

well

[range]
Substitute/str-l/str-2/[/BR]
[/Q]
[/-T]

Changes string 1 to string 2. If range is specified, changes all
If no range, changes only the first
string ls in the range.
string 1 encountered.
Sub:sti tute Next
Repeats the operation of the
immediately follow.

Substitute

command

that

must

typ1e [range]
or
[Type] [range] [/BRief]
Displays the contents of the range on your terminal.
WRite [range] /FI:filespec
Creates an output file from the contents of the range.
Xeq range
Executes the EDT commands contained in the range.

A.3

EDI COMMAND SUMMARY

Add (string)
Adds the text specified by string to the end of the current line.
AP (string)
Same as ADD, except that the new current line is printed.
Begin
Sets the current line pointer to the top of the block
input file.

buffer

BLock[ON] or [OFF]
Switches text

access modes.

BO[TTOM]
Sets the current line pointer to the bottom of
input file.

A-3

block

COMMANDS AND SWITCHES
[n]Change /stringl/string2[/]
Searches for string! in the current line and replaces it with the
text specified in string2. The integer n allows you tb change
the first n occurrences of string! to string2.
CLose file spec
Transfers the remaining lines in the block buffer and the
input
file into the output file, then closes both the input file and
the output file.
CLOSES
Closes secondary input file and begins selecting lines
primary input file.

from

the

COL [f ilespec]
Same as the CLOSE command, except that the input file is deleted.
CC [character]
Changes the command concatenation
character (the default is&).

character

the

specified

causes

immediate

CTRL/Z
Same as EXIT if in Edit mode;
exit of EDI.

otherwise,

Delete [n] or [-n]
Deletes the current and next n-1 lines,
if n is positive;
deletes n lines preceding the current line, but not the current
line, if n is negative.

DP [n] or [-n]
Same as DELETE, except that the new current line is printed out.
End
Same as the BOTTOM command.
ERASE [n]
Erases the entire block buffer, the current line, and the next
blocks.

EXit [filespec]
Same as CLOSE command, except that, when files
exits.

are

closed,

EDI

output

file,

and

EDx [f ilespec]
Exits from the editing session,
deletes the input file.

closes

the

A-4

:; at s a;:

COMMANDS AND SWITCHES

FF
Inserts a form feed into the block buffer after the current line.
FI le~ f ilespec
Transfers lines from the input file
filespec.
[n]E~ind

the

specified

[st.ring)

Finds the line starting with string or, if n
nth line starting with string.
Inse~rt

file

specified,

the

[string]

Inserts string immediately following the current line.
is null, EDI enters Input mode.

If string

KILL
Terminates this editing session;
closes
files;
and deletes the output file.

the

input

and

output

[n]LC /stringl/string2
Same as CHANGE, except that all occurrences
current line are changed to string2.

string!

the

Prints on the user terminal all lines in the block buffer or all
remaining lines in the input file, starting with current line.
LP
Lists the text in the block buffer or input file
device CL:, starting with the current line.

the

pseudo

[n]Locate string
Searches the block buffer for string or, if n is
nth occurrence of string.

specified,

the

MAcro x definition
Defines macro x to be definition.
MCall
Retrieves macros from the latest version of file MCALL;n.
[n]Mx [a]
Executes macro
argument a.

for

executions,

passing

the

numeric

[n]<definition>
Allows you to define and execute a macro n times in one step.

A-5

COMMANDS AND SWITCHES
Next [n] or [-n]
Establishes a new current line plus or minus
current line.

lines

from

the

current

line

NP [ n] or [ -n]
Same as Next
printed.

command,

except

that

the

new

OPens f ilespec
Opens the secondary input file.
output [ON] or [OFF]
Turns the output on or off.
Overlay [n]
Deletes the current line and the next n-1 lines, and enters Input
mode.
PAGe [n]
Enters block mode, if not already in block mode, and reads page n
into the block buffer.
[n]PFind (string}
Identical to FIND command, except that it searches successive
block buffers until the nth occurrence of string is found.

[n]PLocate (string)
Same as LOCATE command, except that successive block buffers
searched for the value specified by string.

are

PAste /stringl/string2
Same as the LINE CHANGE command, except that all lines in the
remainder of the block buffer or input file are searched for
stringl. Wherever found, stringl is replaced with string2.
Print [n]
Prints the current line, and the next n-1 lines, on the terminal.
The last line printed becomes the current line.
REAd [n]
Reads the next n pages into the block buffer.
RENew [n]
Writes the current buffer and
specified, repeats n-1 times.

reads

the

If string

next.

Retype (string)
Replaces the current line wit~ the text of string.
null, the line is deleted.

A-6

iii

I ii

21"5

COMMANDS AND SWITCHES
SAve [n] [f :llespec]
Saves the current line, and the
specified by filespec.

n-1

lines,

the

file

SC /stringl/string2
Searches for string!, in the block buffer or input file starting
with the line following the current line. When stringl is found,
replaces all occurrences in the line with string2.
SP
Selects the primary input file.
SS
Selects the secondary input file.
SIZE n
Specifies the maximum number of lines to be read into
buffer on a single read operation.

the

block

and

saves

Same as PRINT command, except that the current line pointer
not change unless EOB is reached.

does

TAb [ON] or [OFF]
Turns automatic tabbing on or off.
Top
Same as BEGIN command.
TOF
Returns to the top of the input file, in block
all pages previously edited.
TYpE!

mode,

[n]

UNSave [f ilespec]
Retrieves the lines that were previously saved on filespec
inserts them immediately following the current line.

and

UC ![ON] or [OFF]
Turns uppercase conversion on or off.
Verify [ON] or [OFF]
Displays or suppresses display of lines located or changed.
Write
Writes the current block to
contents of the buffer.

the

A-7

output

file,

and

erases

the

COMMANDS AND SWITCHES
A.4

PIP COMMAND SUMMARY

outfile[/FO]=infilel [,infile2, ••• ,infilen]/AP[/FO]
Opens an existing file (outfile) and appends the input
onto the end of it.
{/FO is the File Owner switch.)

flle(s)

outfile[/BS:n]=infilel[/BS:n] [, ••• ,infilen[/BS:n]]
Defines block s1zes for 7- and 9-track magnetic tape.
outfile[/switch]=infilel[,infile2, ••• ,infilen] [/switch]
Creates a copy of a file on the same or another
can be:
/BL: n [.]
/CO
/-CO
/FO
/NV
/SU

Switch

device.

Block allocated
Contiguous output
Output may be noncontiguous
File Owner
New Version
Supersede

outfile/CD=infile
Gives the output file the creation date of the input file rather
than the date of transfer.
(This switch cannot be used with the
Merge switch, /ME.)
dev: [group,member]/DF
Changes the default device and/or UFD.
infilel[,infile2, ••• ,infilen]/DE[/LD]
Deletes files.
(/LD is the List Deleted files subswitch.) See
the sections on Delete and Purge in Chapter 4 for a complete
description of the List Deleted files subswitch.
outfile=infilel[,infile2, ••• ,infilen]/EN[/NV]
Enters a synonym for a file in a directory with an option to
force the version number of outf ile to one greater than the
latest version for the file.
(/NV is the New Version switch.)
inf ilel/EOF [:block: byte] [, ••• inf ilen/EOF [:block: byte]]
Specifies the end-of-file pointer

for a file.

outfile=/FI:filenum:seqnum
Accesses a file by its file identification number.

A-8

li I

iii

Ji Li I

;;us

COMMANDS AND SWITCHES
dev:/FR
Prints out the available space on
contiguous space on that volume.

'-"'

volume

and

the

largest

/ID
Causes the version of PIP currently in use to be displayed on the
termi nc1l.
[listfile]=infilel[, ••• ,infilen]/LI
Lists one or more directories with an option to specify directory
listing formats
([listfile] defaults to TI:
if not specified).
In place of /LI, you can specify one of the alternate mode
swi tchE~s:
/BR
/FU [ :n]
/TB

Brief format
Full format
Total blocks format

infilel[,infile2, ••• infilen]/sw/NM
Deletes certain PIP error messages, for exampie, NO SUCH FILE(S);
/sw can be /LI
(List directory),
/DE (Delete files), or /PU
(Purge files), or any of their respective subswitches.
inf ilel/PR [/SY [: RWED] [/OW [: RWED] ] [/GR [: RWED] ] [/WO [: RWED] ] [/FO]
Alters file protection.
/SY
/OW
/GR
/WO

The switches are:

system access rights
owner access rights
group access rights
world access rights

:/RWED -- read, write, extend, delete privilege
/FO -- File Owner subswitch
infilel [, infile2, ••• , infilen]/PU [ :n] [/LD]
Deletes a specified range of obsolete versions of a file.
(Never
deletes
latest
version.)
(/LD is the List Deleted files
subswi tch.)
infilel[,infile2, ••• ,infilen]/RM
Removes an entry from a directory file.

(Opposite of ENTER.)

outfile=infilel[,infile2, ••• ,infilen]/RE[/NV]
Changes the name of a file with an option to force the version
number of outfile to one greater than the latest version for the
file.
(/NV is the New Version switch.)

A-9

COMMANDS AND SWITCHES
outfile[/RW]=infile[/RW]
Rewinds a tape.
outdsk:outfile/SB=inmag:infile
File copied to disk from magnetic tape may have records
block boundaries.
(/SB is the default.)

crossing

infilel[,infile2, ••• infilen]/SD
Prompts for user response before deleting files.
outfile=infile/SR
Allows shared reading of a file that has already been opened
writing.

for

c-~----~,
.. \
-

infilel[,infile2, ••• ,infilen]/SP[:n]

....
j

Specifies a list of files to be printed
(n is the number of
copies).
This switch applies only if you have the serial
despooler task
(RSX-llM)
or the
queue
management
system
(RSX-llM/M-PLUS) installed.
infilel[,infile2, ••• infilen]/TR
Truncates file(s)

to logical end-of-fila.

outfile/UF[/FO]=infile, ••• ,infilen
Creates a User File Directory entry on a volume.
infilel[,infile2, ••• ,infilen]/UN
Unlocks a file that was locked as a resuLt
closed.

being

improperly

the

beginning,

,.,!

outfile=infilel[,infile2, ••• ,infilen]/UP[/FO]
Opens existing file (infile) and writes it, from
into outfile.
(/FO is the File Owner switch.)

FLX COMMAND SUMMARY

A.5

The FLX commands generally have the form:
outfile=infilel[,infile2, ••• ,infilen]/switch

A-10

;

!ii&

£!

;;••

COMMANDS AND SWITCHES

/switch can be:
/BL:n
Indicates the number of contiguous blocks to be allocated to
output file.

the

/BS:n
Specifies the block size for cassette tape output.
/CO
Indicates that the output file is to be contiguous.

/DE
Deletes files from a DOS-11 or RT-11 volume.
/DI
causes a directory listing of DOS-11 or RT-11 volumes;
or RSX-11 cassette tape volumes to be listed.

or DOS-11

/DNS:n
Specifies either an 800- or 1600-bpi density for the volume.
/DO
Identifies the file as a DOS-11 formatted file.
/FA:n
Specifies formatted ASCII.
/FB:n
Specifies formatted binary.
/FC
Indicates that FORTRAN carriage control
used.

conventions

are

number

/ID
Requests the current version number of FLX.
/IM:n
Specifies Image mode (n is in decimal bytes).
/LI
Same a1s DI.
/NU:n
Used with /ZE and /RT switches;
directory blocks to allocate.

A-11

specifies

the

COMMANDS AND SWITCHES
/RS
Indicates that file is a Files-11 formatted file.
/RT
Indicates that file is an RT-11 formatted file.
/RW and /-RW
Specifies whether the tape will rewind before FLX
next command.

processes

the

/SP
Indicates that the converted file is to be spooled by means of
the serial despooler (RSX-llM) or the queue management system
(RSX...,. llM/M-PLUS) •
/UI
~~~~~a~~~e~hat the output file is to have the

same

UIC

the

Initializes DOS-11 and RT-11 volumes and cassettes for DOS-11
RSX-11 files.

/VE

Verifies after write (for cassette only).
/ZE

A.6

PRINT AND QUE COMMAND SUMMARY

•

)

until

after

COMMANDS AND SWITCHES
/swi.tch can be:
/BL::n
Indicates the number of contiguous blocks to be allocated to
output file.

the

/BS::n
Specifies the block size for cassette tape output.
/CO
Indicates that the output file is to be contiguous.
/DE

Deletes files from a DOS-11 or RT-11 volume.
/DI
Causes a directory listing of DOS-11 or RT-11 volumes;
or RSX-11 cassette tape volumes to be listed.

or DOS-11

/DNS::n
Specifies either an 800- or 1600-bpi density for the volume.
/DO
Identifies the file as a DOS-11 formatted file.
/FA:n
Specifies formatted ASCII.
/FB:n
Specifies formatted binary.
/FC
Indicates that FORTRAN carriage control
used.

conventions

are

number

/ID

Requests the current version number of FLX.
/IM:n
Specifies Image mode (n is in decimal bytes).
/LI
Same as DI.
/NU:n
Used with /ZE and /RT switches;
directory blocks to allocate.

A-11

specifies

the

processes

the

/SP
Indicates that the converted file is to be spooled by means of
the serial despooler (RSX-llM)
or the queu~ management system
(RSX~llM/M-PLUS).

/UI
Indicates that the output file is to have the
input file.

same

UIC

the

Initializes DOS-11 and RT-11 volumes and cassettes for DOS-11
RSX-11 files.

/VE

Verifies after write (for cassette only).
/ZE

A.6

PRINT AND QUE COMMAND SUMMARY

The format of the PRint command is:
>PRint [ [ddnn:] jobname /jsw=] filespec [/fsw [/fsw]] [, filespec [/fsw]]
/jsw can be one of the following:
/AFter:hh:mm
Specifies that the job is time-blocked in its queue until after
the stated time;
hh can be from 0 to 23; mm can be from 0 to
59.
/[NO]FLag
Specifies that each file in the job is preceded by
file flag pages. The default is /NOFLAG.

one

/FOrm:n
Sets the forms setting that an output device must have to accept
the job.
The default for n is O, which is the standard line
printer setup in most installations.

A-12

!it IE S

COMMANDS ARD SWITCHES
/HOld
Holds the job in its queue
jobname /RELease command.

until

released

the

QUE

/LEngth:n
Sets the number of lines per page.
Length can be set
through 6553~. The default is a page of infinite length.

from

/PRiority:n
Sets the priority of the job in its queue.
Priority can be from
O through 250.
Highest priority jobs run first.
The default
priority is 50.
/[NO]REstart
Makes the job restartable or not.
If /RE is specified and the
job does not complete its run for some reason, when the system or
print processor or Queue Manager
is restarted,
the
job is
restarted from the beginning of the first file in the job.
/NOREstart is the default.
/fsw can be one of the following:
/COpies:n
Sets the number of copies of
default for n is l.

the

file

despooled.

The

/[NO]DELete
Directs the Queue Manager to delete the file from its
it is despooled.
/NODELete is the default.

UFD

after

The format of the QUE command is:
>QUE job-ID /function [/sw]
/function can be one of the following:
/BRief [:option]
Displays only the job names, the UIC from which the Print command
was issued, the queue entry number, and the status of the job.
/FU LL [ : option]
Displays job names, the UIC from which the Print command was
issued,
the queue entry number, the status of the job, the file
specifications of all files necessary to complete the
job,
and
all attributes of the job, whether set explicitly or by default.
/List [:option]
Displays job names, the UIC from which the Print command was
issued,
the queue entry number, the status of the job, and the
file specifications of all files necessary to complete the
job.
This is the standard format.

A-13

COMMANDS AND SWITCHES
:option can be one of the following:
~

:QUE
Displays entries in the default queue PRINT.
option.

This is the default

:ALLQUE
Displays all entries in all queues.
:DEV

Displays characteristics of a device. If you have not specified
a device in the job-ID field of the command line, you will get an
error message.
:ALLDEV
Displays characteristics of all spooled devices.
/DELete
Deletes the specified queue entry. If the job is active at the
time the command is issued, the output ceases and the queue entry
is deleted.
/HOld
Holds job in its queue. The job remains in its queue, but is not
eligible for processing.
The effect is the same as with the
/HOLD qualifier to the Print command. You cannot hold an active
job.
(An active job is a job currently being printed.)
/MODify /sw
Modifies the attributes given to queue
command. /sw is one of the following:

entries

the

/AFter:hh:mm
Modifies the time after which the job is to be despooled.
/[NO]FLag
Modifies the FLAG attribute of the job
/FOrm:n
Modifies the FORM attribute of the job.
/LEngth:n
Modifies the LENGTH attribute of the job, which is the number
lines per page.

/PRiori ty: n
Modifies the queue priority of the job.

A-14

·r"1•~t\~12••r:•••••••••••••••------•••••mt11•••22••••••••••••••t•1•t•c•:::•:•t•:.:-

COMMANDS AND SWITCHES

/[NO]REStart
Modifies the RESTART attribute of the job.
/RELease
Releases a held job, making it eligible for processing.

A.7

QUEUE MANAGER COMMAND SUMMARY

The following forms of the QUEue command are privileged.
The format of the Queue Manager setup commands is:
>QUE ddnn:/function[:option[s]] [/sw[s]]
/function can be one of the

following~

/ASsign:queuename
Normally, assigns the default queue PRINT to one or more
despooler tasks, but you can assign any queue to any despooler.
/DEAssign:queuename
Eliminates the path between a queue and a despooler,
but the
queue still exists with all its jobs. Jobs can be added to the
queue, but none will be dequeued while the queue is not assigned.
/SPool/sw
Creates queue ddQn and starts the despool task ddPn which must be
installed previously for device ddn. This attaches device ddnn:
for despooling by the despool task ddPn which is open to jobs
from queue ddQn.
/sw is one or more of the followingo
/FLag:n
Sets the number of flag pages to precede all jobs printed on the
device.
Note that if you are using special forms, you may want
to set this attribute to 0 to avoid printing banner pages on your
special forms.
This also sets the number of file flag pages to
be printed when users specify the FLAGS switch in their Print
commands.
/FOrm:n
Sets the device despooler to accept jobs with forms type n.
default for n is O;
it can be between 0 and 255, inclusive.

The

/STArt[:option] or [/sw]
If you do not enter an option or switch,
the device starts
printing from the point at which printing stopped. This, in
effect, resumes printing after a pause. Option and switch are
mutually exclusive fields;
that is, you can only use one or the
other.

A-15

COMMANDS AND SWITCHES

:option can be one of the following:
:BAck:n
Printing starts n pages back from
stopped.

the

point

which

was

Printing starts n pages forward from the point at
stopped.

which

was

: Forward: n

:NExt
Printing starts at the top of the next job.
:PAge:n
Printing starts at page n of the current file.
:QMG

Starts the Queue Manager and initializes the default queue PRINT.
It creates the file SY:[l,7]QUEUE.SYS if it is not there.
If the
queue file was intact, all queues still contain their jobs,
but
are not assigned to processors.
(Processors will have to be
spooled again.)
:TOP
Printing starts at the top of the current file.
/sw can be one or more of the following:
/FLag:n
Resets the flag setting of the despooler task from the number of
flag pages set with SPOOL. The value for n can be O, 1, 2, or 3.
/FOrm:n
Resets the forms type of the despooler task
with SPOOL.

from

the

type

set

/STOp [:option]
Stops the device immediately if you do
:option can be one of the following:

not

specify

option.

: EOF
Device stops at the end of the current file.
: EOJ
Device stops at the end of the current job.
:QMG
The Queue Manager stops at the end of the current job.
All
assignments of queues to devices are broken (deassigned). All
despooler tasks are detached from their devices.
The Queue
Manager stops.

A-16

I iii &I

COMMANDS AND SWITCHES
/UN:SPool
Frees a device used in despooling for general use.
The despool
task for the device exits but its entries in queues assigned to
it remain in the general file.

A.8

PMT COMMAND SUMMARY

The general format of a FMT command line is:
FMT dev: [/switchl ••• /switchn]
/switch can be one or more of the following:
/BAD
Note that
Runs the Bad BLock Locator task if it is installed.
this switch can only be used with operating systems that allow
spawning of tasks.
All RSX-llM-PLUS and IAS systems permit
spawned tasks and RSX-llM systems permit spawned tasks if the
option was included at system generation.
/DENS
Selects high
diskettes.

(double) or low (single)

density

for

RX02

floppy

/ERL
Determines the maximum number of errors FMT
volume.

will

allow

the

/MAN
Enters manual mode and formats the sector or track you specify.
/OVR
Overrides or ignores the manufacturer's
(MDBSF) •

bad

block

sector

file

/VE
Verifies that FMT operation was successfully completed.
/WLT
Rewrites the MDBSF.

/@Y
Informs FMT that it is executing from an indirect command
and does not allow operator intervention in the process.

A-17

file

COMMANDS AND SWITCHES
A... 9

BAD COMMAND SUMMARY

The format for executing BAD is:
dev:/swl ••• /swn
/sw can be one or more of the following:
/CSR=nnnnnn
Alters the CSR address of the device to conform to CSR address of
user's system (stand-alone version of BAD only).
/LI

Causes all
terminal.

bad

block

numbers

printed

the

user's

/MAN
Allows the user to enter bad blocks.
/NOWCHK
Negates the effect of /WCHK.
/OVR
Causes BAD to ignore the last track of a last-track device.
/UPDATE
Reads bad blocks and prompts for user entries.
/VEC=nnn
Alters the interrupt vector address of the device to conform to
the
vector
address
of the device in the user"s system
(stand-alone version of BAD only).
/WCHK
Causes a write-check operation to take place after each write
operation (stand-alone version of BAD only).
Not valid for
devices DX, DL, or DT.

A.10

BRO COMMAND SUMMARY

The format for executing BRU is:
[/qualifiers] indevl:, ••• [filespec, ••• ] outdevl:, ••• [filespec, ••• ]
/qualifiers can be one or more of the following:
/APPEND
Appends new back-up data to a tape with one or more back-up sets.

A-18

2 21

!. !Ql

COMMANDS AND SWITCHES
BACKUP_SE'.r: name
Specifies the name of the back-up set to be placed on tape.
/BJ\D

MANUAL ~
AUTOMATIC
[ OVEHRIDE
Enters the locations of bad blocks on volumes.
BAD:AUTOMATIC.

The

default

Specifies the number of directory File Control Blocks (FCBs)
volume kept by the ACP.

per

/BUFFERS:number

/COMPARE
Compares the data on the output volume to the data on
volume and reports any differences.

the

input

:: dd-mmm-yy
:: (h h : mm: s s )
~ (dd-mmm-yy hh:mm:ss)
~BEFORE:dd-mmm-yy

/CREATED :BEFORE:(hh:mm:ss)
~BEFORE(dd-mmm-yy
~AFTER:dd-mmm-yy
~AFTER:(hh:mm:ss)
~AFTER: (dd-mmm-yy

hh:mm:ss)
hh:mm:ss)

Directs BRU to process files created at or before or after a
specified date and/or time.
If you do not specify a date or
time, BRU defaults to the current date and time.
/DE:NSITY: number
Specifies the data density at which
default is /DENSITY:800.

BRU

writes

tape.

The

names,

each

file

/DIRECTORY.
Displays information (such as back-up set names, file
volume number of a tape)' on a specified tape volume.
/DISPLAY
Displays at your terminal the UFO and
bein9 backed up.

file

name

/EHRORS:number
Specifies the number of nonfatal I/O errors BRU tolerates on tape
reads; before automatically terminating execution. The default is
25(10) errors.
/EXCLUDE
Excludes selectively from a back-up
files specified on the command line.

A-19

restore

operation

all

COMMANDS AND SWITCHES
/EXTEND:number
Specifies the number of blocks by which to extend
that file has exhausted its allocated space.

file

when

/HEADERS:number
Specifies the number of file headers to allocate initially to the
index file.
/INITIALIZE
Directs BRU to initialize a disk before proceeding with the
transfer.

data

/INVOLUME:name
Specifies the volume label of the input disk.
/LENGTH:number
Specifies the length of the output tape in decimal feet.
/MAXIMUM:number
Specifies the maximum number of files that can
volume.

placed

Allows you to back up files from a disk that is mounted
Files-11 volume (by means of the MCR command MOUNT).

/MOUNTED

/NEW_ VERSION
Directs BRU to resolve conflicts resulting from files with
identical file specifications by creating a new version of the
file.
Both versions are kept on the output volume.
/NOINITIALIZE
Specifies that you do not want BRU to initialize the output disk;
it already has a Files-11 structure and is mounted as a Files-11
volume.
/NOPRESERVE
Specifies that you do not want BRU to preserve file identifiers.
/NOSUPERSEDE
Resolves the conflict of files on the output volume having file
specifications identical to files on the input volume by keeping
the file on the output volume rather than the one on the
input
volume.
(The default is /NOSUPERSEDE.)
/OUTVOLUME:name
Specifies the volume label of the output disk.

A-20

ca:;

ts! .I

l
!

COMMANDS AND SWITCHES

BEGINNING
/POSITION: MIDDLE
END
BLOCK:number

Specifies the location of the index file,
the Master
Directory, and the storage allocation file on a disk.

File

/PlilOTECTION:1~~i:~~:~~~e1
GROUP:value
WORLD:value

Specifies the global default protection status of
on a disk after it has been mounted.

files

created

:dd-mmm-yy
: (hh:mm: ss)
: (dd-mmm-yy hh:mm:ss)
:BEFORE:dd-mmm-yy
/RE:VISED :BEFORE: (hh:mm:ss}
:BEFORE:(dd-mmm-yy hh:mm:ss)
:AFTER:dd-mmm-yy
:AFTER: (hh:mm:ss)
:AFTER: (dd-mmm-yy hh:mm:ss)
Directs BRU to process files revised at or before or after a
specified date and/or time.
If you do not specify a date or
time, BRU defaults to the current date and time.
/REWIND
Rewinds the first tape of
command line.

tape

set

before

execution

/SUPERSEDE:
Restores files to an existing disk;
resolves file specification
conflicts by deleting the old file on the output disk and
replacing it with the file being restored from the input disk.
(The default is /NOSUPERSEDE.)
/TAPE_LABEL:label
Specifies a 6-character ANSI volume
the tape volume.

identifier

for

identifying

/VERIFY
Copies data from the input volume to the output volume,
the volumes, and reports differences.

compares

/WINDOWS:number
Specifies for the output disk the default number of retrieval
pointers allocated for use with file windows. The default number
is specified when the disk is initialized.

A-21

COMMANDS AND SWITCHES
A.11

DSC COMMAND SUMMARY

The format for executing DSC is:
outdev: [label] [/switch]=indev: [label] [/switch]
/switch can be one or more of the following:
/AP
Appends a DSC file to a magnetic tape that already contains a DSC
file.
/BAD=

MAN
NOAUTO
MAN:NOAUTO

Allows manual entry of bad block locations;
can supplement,
override, or ignore the disk's own bad block descriptor.
/BL
Sets the number of
buffers.

blocks

DSC

will

provide

each

its

/CMP
Compares an input file and an output file for differences.
/CSR=xxxx
Alters control status addresses for specific device types.
/DENS=l600
/DENS=800:1600
Overrides the DSC default storage density for magnetic tapes of
800 bits per inch; the first form of the switch creates magnetic
tapes at 1600 bits per inch density; the second form (the split
density qualifier) creates magnetic tapes with volume header
information at 800 bits per inch and the rest of the tape at 1600
bits per inch.
/RW

Rewinds all
command.

magnetic

tapes

before

execution

the

current

/TM02=x
Alters the physical unit formatter.
/UNIT=x
Specifies the physical unit that a LUN accesses.
/VE
Copies data from the input volume and compares it with the output
volume following the data transfer.
/VEC=xxx
Alters the vector address of a unit.

A-22

SJ I

!SS

COMMANDS AND SWITCHES

A.12:

PRESRV COMMAND SUMMARY

The format for executing PRESRV is:
outdev: [label]/switchl ••• /switchn=indev: [label]/switchl ••• /switchn
/switch can be one or more of the following:
/BO
Bootstraps the system from the specified device (unit 0 only).
/BL:nnn
Specifies a blocking factor for I/O.
nnn.

Octal is

the

default

for

/CSFl
Changes ihe control status register for a device.
/ER
Indicates that the PRESRV operation is to be terminated if an I/O
error occurs.
/FI
On input, indicates Files-11 format for reading a volume, which
overrides implied image mode (/IM). On output, overrides logical
tape format (/TP) or implied image mode (/IM).
/FO
Indicates that PRESRV is to format the output volume.
/HE

Displays a summary ot PRESRV commands, switches, and defaults.
/IM
Indicates image mode:
input volume.

a transfer of all physical

blocks

/LI
Displays a list of all files on a logical tape.
Magnetic tape switches:
/20~

/55, /80, /PE
Indicate recording
respectively.

densities

200,

556,

/RW

Rewinds a cassette or magnetic tape.
/TIM
Specifies the correct time of day to the system.

A-23

800,

and

1600,

COMMANDS AND SWITCHES
/TM02
Sets the unit number of the TM02 formatter on the
for a specific TU16 magnetic tape unit.

controller

/TP

Specifies that an output volume be in logical tape format.
also overrides the default Files-11 mode on an input volume.

/TP

/VE
Verifies the output volume after file transfer.
/VEC
Changes the interrupt vector address for a device.

A.13

VFY COMMAND SUMMARY

listfile,scratchdev=indev/DE
or
indev/DE
Resets the marked-for-delete indicators in the file header area
of those files marked for deletion, but never actually deleted.
listfile=indev/FR
or
indev/FR
Prints out the available space on a volume.
listfile,scratchdev=indev/LI
or
indev/LI
Lists the entire index file by file identification.
listfile,scratchdev=indev/LO
or
:indev/LO
Scans the entire file structure looking for files that are not in
any directory.
listfile=indev/RC[:n]
or
indev /RC [: n]
Checks that every block of every file on the specified volume can
be read.

~
i

A-24

II l

;;

COMMANDS AND SWITCHES

listfile,scratchdev=indev/RE
or
indev/RE
Recovers blocks that
contained in any file.

appear

allocated,

but

are

not

are

actually

listfile,scratchdev=indev/UP
or
indev/UP
Allocates blocks that appear to be av~ilable,
allocated to a file.

A.14

but

LBR COMMAND SUMMARY

outfile/CO:size:ept:mnt:=infile
Creates a new library file and transfers contents, but physically
deletes logically deleted records in the file and puts all free
space at the end of the file.
outfile/CR~size:ept:mnt:type

Allocates a contiguous library file on a direct access device.
outfile/DE:modulel[:module-2: ••• :module-n]
DeletE!S library modules and their associated entry points from
file.
outfile/DF:type •••
or
/DF:: type
Specifies default library file type.
outfile/DG:globall[:global2: ••• :globaln]
Deletes specified library module entry points from a file.
outfile[/EP]=infile, ••• ,infilen
or
outfile=infile[/EP], ••• ,infilen[/EP]
Includes or excludes entries in the entry point table.
outfile=infile/EX[:modulename: ••• modulenamen]
Reads a module from a library;

writes it to an output file.

outfile/IN=infilel[,infile2, ••• ,infilen]
Inserts library modules into a library file.

A-25

COMMANDS AND SWITCHES

outfile[,listfile]/switch(es)
Lists all modules in the library file plus additional information
depending on which form of the switch you use:
/LI

Lists all modules in the library file

/LE

Lists all modules in the library
entry points

/FU

Lists all modules in the library file and provides a
date of
full
module
description including size,
insertion, and version

file

and

all

their

outfile/RP=infilel[,infile2, ••• ,infilen]
or
outfile=infilel/RP[,infile2[/RP], ••• ,infilen[/RP]]
Inserts, and in certain cases,
library file.

replaces

library

modules

outfile,listfile/SP
Spools the listing file out for printing.
This switch applies
or the queue
only if the serial despooler task
(RSX-llM)
management system (RSX-llM/M-PLUS) is installed.
outfile=infilel/SS[,infile2[/SS], ••• ,infilen[/SS]]
Sets the selective search attribute
header.

bit

the

object

outfile/SZ=infilel[,infile2, ••• ,infilen]
or
outfile=infilel/SZ[,infile2[/SZ], ••• ,infilen[/SZ]]
Reduces the size of macro sources by removing comments.

ir.. • 15

DMP COMMAND SUMMARY

The format for executing DMP is:
outfile=infile/switch
/switch can be one of the following:
/AS
Specifies that data be dumped in ASCII mode.
/BA:n:m
Specifies a base block address.
/BL:n:m
Specifies the first and last logical blocks to be dumped.

A-26

1~ I ii

4f'¥2

module

COMMAllDS AHD SWITCHES
/BY

Specifies that data be dumped in byte octal format.
/DC
Dumps in decimal format.
/DENS:n
Specifies density of a TU16 input magnetic tape when
device mode only.

DMP

/HD

Includes the file header in the data dumped.
/HX

Specifies that data be dumped in hexadecimal byte format.

/ID
Causes the current version of DMP to be printed on the listing.
/LB
Causes starting (logical) block number and a contiguous
noncontiguous indication for the file to be printed.

/LW
Specifies that data be dumped in hexadecimal double-word format.

/MD[:n]
Contrc>ls line number sequencing during a memory image dump.
/RC
Dumps one record at a time in the specified format.
/RW
Issues a rewind command to the tape driver before referencing a
specij:ied tape. /RW can be used at any time to reposition a tape
at the load point (BOT).
/RS
Dumps in Radix-SO format.
/SP
Spools the dump file to the line printer.
This switch applies
only :if you have the serial despooler task (RSX-llM) or the queue
management system (RSX-llM/M-PLUS) installed.
/WD
Specifies that data be dumped in hexadecimal word format.

A-27

COMMANDS AND SWITCHES
CMP COMMAND SUMMARY

A.16

The CMP command takes the following form:
outfile [/sw ••• ]=infilel[/sw ••• ],infile2[/sw ••• ]
/sw can be any one of the following:
/BL and /-BL
Specifies that blank lines in both files be included in compare
processing.
If specified in the form /-BL, blank lines are not
included in compare processing; /-BL is the default setting.
/CB and /-CB
Specifies that CMP list inf ile2 with change bars, in the form of
exclamation marks (!), applied to each line that does not have a
corresponding line in infilel. /-CB is the default switch.
You can change the change bar character from the exclamation mark
to any character you wish by means of the VB switch, described
below.
When a section of lines in infilel has been deleted in infile2
(the output listing file), the first line not deleted is marked.

/CO and /-CO
Specifies that CMP include comments (that is, text preceded by a
semicolon)
in compare processing.
/CO is the default for this
switch.
/DI and /-DI
Specifies that CMP print the differences between
(rather than marking the lines in infile2).

the

two

files

/DI is the default for this switch.
/CB and /DI are mutually exclusive
specified, /CB overrides /DI.

switches.

both

are

/FF and /-FF
Specifies that CMP
form-feed character
for this switch.

include records consisting of a single
in compare processing.
/-FF is the default

/LI:n
Specifies that a number (n) of lines must be identical before CMP
recognizes a match.
If you do not specify this switch, CMP
searches for three identical lines to match.
When it encounters a match, CMP prints ali the preceding
nonmatching lines,
along with the first line of the matched
sequence of lines to help you find the location in the code where
the match occurred.

A-28

•••••11•:••2111•••z•:•••••••t•u••••·--------•••••-.•••••••••••••••-

:•+•1

COMMANDS AND SWITCHES
/LN and /-·LN
Specifies that lines in the output file be preceded by their line
number.
Line numbers are incremented by one for each record
read, including blank lines. /LN is the default for this switch.
If you specify /SL (below), /LN is unnecessary.
/MB and /-·MB
Specifies that CMP include all blank and tab characters in a line
in compare processing. If you specify /-MB, CMP interprets any
sequence of blank and/or tab characters as a single blank
character in compare processing. However, all spaces and tabs
are printed in the output listing. /MB is the default switch.
/SL [:au]
Directs CMP to generate an output file suitable for use as SLP
command input.
When you specify /SL, CMP generates the SLP
command input necessary to make infilel identical to infile2. If
a 1- to a-character alphanumeric symbol is included (:au), an
audit trail is specified for SLP input.
/SP[:n] and /-SP
Specifies that the output file be spooled on the line printer.
You can optionally specify the number (in octal or decimal) of
files to be spooled. /-SP is the default value for this switch.
This switch applies only if you have the serial despooler task
(RSX-llM)
or
the queue management system (RSX-llM/M-PLUS)
installed.
/TB and /-'rB
Specifies that CMP include all trailing blanks on a line in
compare processing. If you specify /-TB, CMP ignores all blanks
following the last nonblank character on a line.
When you
specify /-CO and /-TB together, blanks that precede a semicolon
(;) are considered trailing blanks and are ignored. /TB is the
default.
/VB:nnn
Specifies an octal character code for use as a change bar.
You
use this switch with the CB switch. The value nnn specifies the
octal character code. For example, you can specify /VB:174 for a
vertical bar (if your printer is capable of printing the vertical
bar character).

A.17

SLP C:OMMAND SUMMARY

The SLP utility has only one command:
outfile[/switch,listfile/SP or/-SP]=infile[/switch]
/switch can be any one of the following:
/AU and·/-AU
Enables and disables the editing audit trail, which indicates the
changes made during the most recent editing session.

A-29

COMMANDS AND SWITCHES
/BF and /-BF
Enables and disables blank fill when
produced.

audit

trail

being

/CM:n
Deletes audit trail, and trailing spaces and
line position n.

tabs

beginning

/CS[:n]
Calculates the checksum value of the edit commands.
/DB and /-DB
Enables and disables double-spaced listing.
/SP and /-SP
Enables and disables the spooling of listing files to a file
structured volume.
This switch applies only if the serial
despooler task
(RSX-llM) or the
queue
management
system
(RSX-llM/M-PLUS) is installed.
/TR
Specifies that a diagnostic error message occur
truncated by the audit trail.

A.18

when

lines

are

PAT COMMAND SUMMARY

The format for specifying execution of PAT is:
[outfile]=infile[/CS[:number]],correctfile[/CS[:number]]
The CS switch provides the facility
specified module.

A.19

compute

the

checksum

ZAP COMMAND SUMMARY

ZAP provides the following commands:

Open/Close Command

(slash)
Opens a location, displays its contents in octal, and stores the
contents of the location in the Quantity Register (Q).
If the
location is odd, it is opened as a byte.

" (quotation marks)
Opens a locationi displays the contents of the location as two
ASCII characters, and stores the contents of the location in the
Quantity Register (Q). ·

A-30

COMMANDS AND SWITCHES
% (]percent sign)
Opens a location, displays the contents of the location in
Radix-SO format,
and stores the contents of the location in the
Quantity Register (Q).
\

(backslash)
Opens a location as a byte, displays the contents of the location
in octal, and stores the contents of the location in the Quantity
Register (Q).

(i:ipostrophe)
Opens a location, displays the contents as one ASCII character,
and stores the contents of the location in the Quantity Register
( Q) •

"' o:r t

(circumflex or up arrow)

Closes the currently open location
preceding location.

modified

and

opens

the

(underscore)
Closes the currently open location as modified, uses the contents
of the location as an offset from the current location value and
opens that location.
@

(at sign)
Closes the currently open location as modified, uses the contents
of the location as an absolute address, and opens that location.

> (right angle bracket)
Closes the currently open location as modified,
interprets the
low-order byte of the location as the relative branch offset and
opens the target location of the branch.

< (left angle bracket)
Closes the currently open location as modified,
returns to the
location from which the last series of underscore ( ), at sign
(@), and/or right angle bracket (>) commands began, and opens the
next sequential location.

General-Purpose Commands

x
Exits from ZAP, returns to MCR.

A-31

COMMANDS AND SWITCHES
K

Computes the offset between the value of the nearest (less than
or equal to) Relocation Register and the currently open location,
displays the offset value, and stores it into the Quantity
Register (Q).

~
~

Displays the jump and branch
location to a target location.

displacements

from

the

current

Displays in octal the value of the expression to the left of
equal sign.

the

v
Verifies the contents of the current location.

Sets the value of a Relocation Register.

A-32

·~
'"'

APPENDIX B
LBR, EDI AND DMP EXAMPLES
B.l
B .1.1

SAMPLE LISTINGS FOR LBR LIST SWITCHES (OBJECT LIBRARY)
List; Modale Names
LBR> MAC, LP :

or
LBR> MAC , LP : /LI
r.>IRE.CTO~Y nF FILE. MAC.:.l')LRJ\
08J~CT MOOULf LlR~ARY CQFATEO

~Y•
L8Q Y~~2V~
22•SEP•74 AT tlsbts50
~NT ~NT~IES ALLOCATEDI 64; AVAILAijL~t 20
FPT ENT~IES bLLOCATtDI h4~J bVAILABLES Q2
~ILE SPACE AVAJLASLEr ~~~15 ~OROS

LAST INSERT

OCCUR~FO

ASl.MT

ASSEM
C:NIHL

C:ODHO
f)A TOR
ENFh)S

EN"LN
~~NOPS
DP~S

FLOAT
GETLN
(;MA~G

TNr:J L

INT FL
'.[ Nl"IF L

l~AREL
l.ISTC

LSTNI;
MAC~n
MAr.~S

MCALL
1'4LI13S
MSCD~

l\IORCT
P~OCSl
P~OPC

PROSW
PST
~EAO

REPT
~OLHI'

HSDAT
RSEXEC

B-1

LBR, EDI AND DMP EXAMPLES

R5U~P

9ECfl1
SETl>T~
SE Tl)N

SF.Tl MM
RETMlt

SPACE
STMNT
SVMBL
lllOROR
w~ IT E

B. l. 2

List Module Names and Full Module Information

LBR>MAC,LP:/FU
or
LBR>MAC,LP:/LI/FU
~I~Er.To~v nF FILE MAC,OL~;t
OBJECT ~ODLlLE LIRWA~V CMEArEn ~v: LB~ VX~2VM
LAST JNS~RT OCCUR~tO 22•StP-14 AT 11:51t50
~NT ENTRIE~ ALLOCATEOI 64J AVAILAALEI 2~
~PT ENTRIES ALLOCATF.Ot b4~J AVAILABLEt 9~
FILt SPAC! AVATLABL~I ~~~1~ wu~os

AS r. t-11

SIZEIV.~0264

TNSt~TEDtl7•JUL•74

ID~NTIV'2

ASSEM
CNn-rL
COOHO

SilE10"17489

TNSERH:Ot 1•Al.IG•74

I DE. N T c ~ 5 ~1

SIZF.i0~727

tNSERTEDslt•JUL•74

~I ZE s '"~92J

TN~ERTE0:17•JUL•74

DATO~

SlZUliH~414

tNS~~TF.Dr17•JUL•74

TOENTatll4
IDENT&V'lf)
IDF.NT1rn

EN~OS

SilEs0"'248

tNSERTfDt1•AUG•7d

F.NnLN

~lZE.

~('11'12

ENr)PS

SIZE
SIZE.

!ilt'16~

INSE~TFD1Jt•JUL•74
TNSE~TED 17•JUL•74

IOfNTa~b
IDE~T 104

YN~F.RTF.D 3t•JUL•74
INSERTFO 17•JUL-74
JNS~~TfD 17-JUL•74
INSEqTED 17•JUL•74

IDENTs06

FXP~S

FLOAT

'11t~i 1

~ETl.M

SIZE 0"'"'3o
S I Z E vl ~ Cl 1 ~

GM A MG

SIZE VIP129_,

J~FIL

SIZE ~P1941
SIZE 0V1493
SIZE 0096~

TNJFL

TNOFL
LABEL
LIS TC
LST'IG

SllE

SIZE

004ri'~
0~294

TNSE~TF.O

9·5~P·14

IDENT1lA6

Il>ENT102

IOENTl0b
JOENTJCi11
IM:.NT112

INSERTED 3l•JUL•74 tl>FNT 10!1
IC)ENT HH
lN~ERTFO 9•SFP•74
INSERTED 1•AUG•74 IDENT1~4
INSERTEO 17-JUL•74 IDENTS04
INSERTED 17•JUL•74 IOENTco.17
INSERTED 17~JUL•74 JOF.NTc~n
INSERTED 9•SEP•74 ll)ENTl~9
lNSE.RTFD 31•JUL•74 IDE>..!Tt"'l
llJENTJ~*l
INSERT-ED J1•JUL•74
TNSERTFOtJt•JUL•74 tDnJT10R

M.\CRO

S1Ht"'2l56b
SlH ~e~19

MAC~S

SIZE

~to4fd

t.1CALL
Mt.I t3 S

~IZE

1'10264

MSCD~

SI2E
SIZE

(.i084J

NDRCT

SIZE'

V1n~B

INSE~TEDsJ1•JUL•74

IOENTIPl2

PROCSJ
PRl"IPC
PROS"'

~llE

'10216

JNSEQTEOt17•JUL•74

TDENT101

SIZE '108~5

INSE~TEusl7•JUL-74

IOENT:rn

SIZE: l-iel2!H4

INSERTEOt17•JUL•74

UlE "11307
SIZE ~~198

JNSE~TEDt17•JUL•74

IDE NT a 03
IOENTl04

PST
READ

0V!tH~7

ROLHD
RS04,.T
~SF. >tEC

~06Ab

JNSERTEOt17•JUL•74
JNSEQTED131•JUL•14
JNSERTJ;011•AllG•74

SllE 0"J74

TNSE~TFOt17•JUL•74

R!5UNP

'H lE

REPT

SIZE tJltll413

SIZE

SIZE ~!?1974
~ C'Jl t7

JNSERTED11•AUG•74
JNS~RTF~117•JUL•14

B-2

JDENTty,1
IOFNT1'111
IDENT1~5
IOENTs~6

Il"IE"NT:l7M
lDF.NTC01

LBR, EDI AND DMP EXAMPLES

SF::C TR

SlZEU!0551

INS~RTE011•AUG•74

SETOlt-t

SilE100U6
~ IZE 100f>70

JNSF.RTF.Dtl7•JUL•74
JNSEQTEDaJt•JUL•74

SETON

SETI MM
~ETM)(

SPACE
STMNT
SVMJ;L
4'40ROe

WRITE
B.1.3

sue: rn0292

SIZErn0131
S lZ E HHl"4.d 9
SJZE1~~31fl

St1Ernt'l7J2

SIZEIA111U1
S lZE"l 001 A9

lDE.NTrnA
IDENT1Qt2
tDENTH'16

IN~EQTEDt17·JUL•74

INSERTED117•JUL•74
INSERTf0:22•SEP•74
INSERTE0117•JUL•74
tNSE~TED117•JUL•74
IN~~qTEOa17•JUL•74
TNSt~TEDll7•JUL•74

I DENT 1 "'2
IDENTl01

JDE'.NT104
HJF.NT I ~J

IOENT10'4
IDF.~TUl2

IDENTt01

Li.st Module Names, Full Module Information and Module Entry
Points (Global Symbols)
LBR>MAC,LP:/FU/LE
or
LBR>MAC,LP:/LI/FU/LE
OlRECTORV OF FILE MAC,OLRJt
O~JECT ~OOULE llBRARV CR£ATEO BVI
L~R V~02VM
LAST I~SF.RT OCCU~RF.D 2'.•SEP•74 AT tlt~115~
MNT ~NTRtES ALLOCATEDI 64J AVAtLA8LE1 2~
EPT ENT~lES ALLOCATEDa 64~J AVAILABLEt 92
FILE SPACE A~AILASLEI 00015 WORDS

** MOOIJLE I AS GMT
ASGMT
u

ASSEM

CNOTOP

•• MOOUL.E1C:ODHO
CPXSTL
PCROLL

INSIZE

PCRTaL

MODULEIOATOR

CLSALL

SIZEt~092J

ObJDMP
RLDOMP

EDTTOP

F.NA~L

B-3

IFF

MACPt

tFT

INSERTEOs17•JUL•74

OAJINI
RLOPNT

SilEt~0414

LC8ITS

JNSERTEDIJ1·J~L·74

FNOC

MODULEIENBDS

EDTBAS

EORITS

~IZEt~0727

tOENT
u

IOENT102

ASGMTF'

MODULE t CNDTL

CN06AS

INSERTE01t7•JUL•74

MOOULEaASSEM
ALLOCi

SlZEt~~264

ORJLOC
STCOOE

OBJPNT
TSTRLO

tNSERTEDrl7•JUL•74

XCTPAS

XCTPRG

IDENT1~4

IFTF
IDENT1~6

ORJSFC
ZAPCPX

IDENT101

PC~CNT

LBR, EDI AND DMP EXAMPLES

•• MQOULEIE'.NOLN
ENOLIN

E~RRT~

•• MODULEIENDPS
ENDPl

••

SIZE:.t00812
E~RCNT

INSERTE01Jt•JUL•74

LINt:WF

MODULEIEXP~S

SIZE Hill {1;16~

lNSERTE0117•JUL•7c1

lDENTaQl4

SilEr~t211

INSERTED131•JUL•74

I t)~NT: Ol6

AB SER~

ABSF.XP

ABSTRM

~ELTRM

RELTST

TF ~M

ABSTST

GLRt.XP

GL8TRM

SIZEJ~~~J~

JNSERTEDt17•JUL·7~

lDENf 1~2

•• MOOULEIGETl..N

SlH.111'~67~

lNSERTE~t17•JUL•74

TOF.NTS05

••

FFCNT

GET LIN

GMARG

GMA~GF

C:MLMJ
OPNSRC

MOOULE1I~IFL
S~CNAM

LSTNA~

OBJNAM

•• MOOULE1LAAEL
LABEL

LPPCNT

SIZEt0~9c11

C:MLM4
OPSWTt

PAGEXT

PAGNUM

1N~~RTE019•SEP•74

·~

SE:CJEND

JDENT112

CMLM')

CSI~2

CSIM5

FINPt

I~PM1

OPS~T2

OUTERM

OUT Mt

STKMt

soPswT

SIZE n~~49J

INSE~TE01Jt•JUL-74

SIZEUH'l961d

INSERTE019•SEP•74

IDENTnH

SIZE a 0041'!'1

INSERTfDl1•AUG•74

IDENTH1A

SIZE.100284

INSERTED117~JUL•74

IDENT104

tNSERTED117•JuL•74

IOENT107

I OE NT It'll

UNOFL

LABELF

•• MOOULEILISTC
LCTBAS

LI NNIJM
RMAF(G

RELF.XP

SIN I FL

•• MOOULEsJNOFL

LC TT OP

•• MOOuL.E1LSTNG

LI ST

PAGE

SlZE 100566

l::~LF

LI NPPG

L~TDEV

LSTREr.l

PAG~NE

PUT1<8L

PUTL.IN

PUT LP

SE TB YT

SET PF~

•• MoDULE I MAC"Mo

SIZEU2019

PF0
SETPF1

1NSERTE0117•JUL•74

PF1

PU Tl<.13

SETWDB

SE hRO

IOE~Hl013

ALTSAV
tHSEOT

ASCII

ASC IZ

BASCPX

IHSl>MA

~ASLTFi

RA SC ND
BASLSY

BASCOD

~USLCD

BAS MU

FUS~AR

FUS~EG

f:USSAT

BASSEC

RA~SRC

RASSST

FUSSTK

8ASMAC
BASSlllT

B-4

EXP~

•• M0DULl£1FL0AT

CMLM2
OPE NCH

oz;; :4 ::

LSTFHIF

ENDP2

•• MOOULEtINFlL

LINE.ND

IOENT&~6

SASOUM
l:\ASPST

BASSYM

·~

LBR, EDI AND DMP EXAMPLES

'-'

ALIOI

BYTMOO

C:~DROL

COOROL.
ERRMNE

EOT
F.RR,L

ERR,O
FLAGS

ERR,B
ERR,P
IMPPAS

tRPC

LCOROI...

LI SROL

LSV~OL

MU~OI.

ME')(IT

MOOE
PASS

MOVBVT
PSTROL

NL.IST
REGBAS
RS.COD
RS,MAA
RS, SST

E~Hf,M

OVSTMT

~OLTOP

RS,C~lO

i:fS,Lt8

RS,LSY

RS~~F.G

ROLSIZ
QS,LCD
RS,SAT

RS.SEC

R~.SRC

R50ABS

~5~DOT

SA Tf~nt.

~AVREG

SEC~OL

S lZCOO

SJZCPX

SIZDM~

SIZEOT

SIZMAB
SI ZS Tl<
SVMROL
TOPLCD
TOPS AT

SUMAC

SIZOUM
SIZPST

SlZSST

SVMBFG
TOPE OT
TOPRF.:G
VALUE:
XMIT5

SIZSWT

wQ~D

SVMROL
TOPLIB
TOPSFC
)(Cf LIN

XMIT6

XMIT7

MODllLF.t~AC~S

CL.CSEC

F.~R,O

CLCNAM
EOTROL
ERR,E

ERR,Q

ER~,R

E~R,T

I MP PAT
MARROL

IMPURE
MACP2
OPCERR
REGTOP
RS,OMA
RS,MAC
RS,SWT
SE.TXPR

l t.1PUqT
MACP2F
OPCLAS

Cl.CMH
OUMROL

000

REGROL
RS,CPX
RS,MA~

RS,STI<
SEC TO~

SIZSVM
TOPCNO
TOPLSV
TOPSRC

S~C:~OL

TOPSST

StZLCO
SIZSAT
SSTROL
TOPCPX
TOPMAA
TOPS Tl<

XHI10

XMIT 1

XMIT2

SIZE1~1~411

SI ZQEG

TOP COD
TOP~AA

tN~ERTED19•SEP•74

fNDLOA

GflBLk

t-1ACR

t-1.ACROC

PROMCF

PROMT

SE.TMAC

WC IMT

.,,. MOOULEsMCALL

MACfrnF

~T,t-1AC

SIZLIB

S IZSEC
ST KROL
TOPIH1A
TO~MAC

TOPSWT
XMITJ

E~OFLG

ERR,I

~ELLVL

rlS,OUM

RS.PST
R51SYM
SIZCND
SIZLSV
StZSRC
SwTROL
TOPDUM
TOPP ST
TQPSVM
XMlT4

1 DE~IT I ~Q
MT,MAX

SIZE.1~0264

INSE~TEOIJ1•JUL•74

tOENTHH

SllE:t~~8'717

INSERTEDt31•JUL•74

lDE.NTSli'J6

P~OMA

MCALL

MOOULEaMLlBS
CPVMAC

FINSML.

•• MOOUL.E:~SCDR
ENO

'-'

F.RR,A.

DSAtiL

EQR,Z

SlZMAA

CL.C:LOC

ER~,U

M.ACROL

••

Cl.CF GS
OMAHOL

ERR,N
E'VEN

OVMAC:R
ROLRAS
RS,EDT

\-I

CHRPNT
CPXROL.
EHR,

MODULE I ND~C T
NARG

ERRM

NCHR

GE.TFID

INISML.

SlZEeid"'84J
GLOBL

INSERTE01J1•JUL•14

P~INT

SIZEt~02!58

INSERTE0t17•JUL•74

IDE.NTl01

DSMSI<

FNAODR

ENMSI<

PAMSI<

PROCSI,

SPMSI<

OPCL0~

OPCUHr

TITl..E

NTVPE:

DSADDH
NL.MSI<

AEXP

SE THOR

IDENT11n

SIZEHH'J216

OPCL07

SB TTL

IDENTs08

INSERTEDIJ1•JUL•74

MODULE I PROCS I

•• MQDlJLEIPROPC

Sr1LFOB

SIZEt01l1865

OPCLOl1
OPCL09

LIA DOR

LIM SK

INSERTED117~JUL~74

OPCL02
OPCL 10

B-5

OPCl.03
P~OPC

OPCL.~4

MLMSK

Nl.AODR

IDENT11f'2

OPCL.05

O?CL06

LBR, EDI AND DMP EXAMPLES

•• MODULEIPROSW
PRl')SW

swTRAS

•• MODULE I PST
DFLCNO

SS TB AS

SST TOP

•• MODULEtREAO
••

IOF.NT103

tNSERTEDtl7•JUL•74

IOENTl04

""'

DFLGSM
WROSVM

OFLGEV

DFLMAC

DFLS"1C

PSTSAS

SIZEt0'11198

INSERTEOtl7•JUL•74

IDENTl01

SIZE1~1i'47J

I~SERTEDIJ1•JUL•74

IDENTa01

PS TT OP

$Rf AO

MOOUL..El~EPT

ENDMAC

YNSERTED117•JUL•74

SW TT OP

SIZE t 01307

esYTOP

GETVBN

SI ZE.100258

MPUSH

I~P

•• MOOULEIQOLHO

i;E., T

S l ZE I '1~685

JNS~QTED1l•AUG•74

LSFLAG
ROLUPD

LSGBAS
SCAN

LSRCH

IOEt...Tt05

LSVijt<N
SEAHCH

MSRCH

APPEND

INSERT

OSRCH

ROLNOX

•• MOOUL.F.1

~Sr,A T

~IZEt~t'-'374

C:'JULVl.

r.t.if)MI-. X

CN0~1SK

(.'IL) tlW Ml)

CtHJ(.1'tl

l.~Aul.-

t. tJ J. l\q I

UH~~ 6 )(

£0MASI<
F.XMFLG
LCLVL

EDMCSI
GMAf.'NT
LCMCSI

F.;:>,GRI.

EO,LSA

ED• RF. c;

Et..iDVEC

LBL.E.t..ID

LCBE~L

LC.~IN

EDMAAK
GMAbLK
LC MA St<
LC,CNO

ED.AMA

LC,MEB
MACLVL

LC.SEQ

LC.SRC

~AC

NAM

MACNXT

LC SAVE
LC,LO
L.C.SYM
MA(':TXT

LCENOL
LC SB AK
LC,MC
LC,TTM
MSAARG

MS SEND

MSl-\LC;H

MSF\MRP

MSf.\PRP

SMLLVL

S"CNUM

STAFi!S

STLBUF

LS~FGS

SCAN~

SSRCH

ZAP

•• "400IJLEa~SEX~C

Lc.cnM

SIZEa~0974

CMIBUF

'DEF MC

CLOSRC
FOBTBL.

TO!.EnF

lQ,E:R~

JO.NNU

n~J~UF'

nHJF'tl.

RUFT~L

MACLDG

SRCCLO

SRCMRK

TNSERTED117•JUL•74

FOR1

SRCPNT

LCSAVL
LC.LOC
LC.TOC
MAC~RT

MSHTXT
TTLRRK

MSR TV P

IO,OPN
PASSSW
SRCSAV

GETFLG

CONT
GETPLl

PURGMC
TSTSTI<

REST RT
VBNSAV

CNTTBL

Io.our

LC FLAG

LC.

LClNIT

LCeBEX

LC.MD
Ll8NUM
MSBBLK
PRGlDN

LCeME
MACGSB
MSBCNT
PQGTTL

TTLBUF

tNSe~TEOtl•AUG•/4

C"1LBLK
FOR2

Jl">FNTt~6

JO, TTY

IDENTl17M
CSlBLK
HORTTL
LOA MAC
RLDBUF
SLIMJT

DAT TIM
lOFTBL
L.SlFlL.

·""

SPSAV

!il.STVZ

SSWTCH

** MOOuLEIQ5UMP

s1Ze•id"'t17

lNSERTEDtl7•JuL•74

IOENTl~l

SIZE11t1~051

lNSERTED1l•AUG•74

1DENTl04

SAT TOP

SEC I NI

A50UNP

•• MODULE I SEC TR
A SECT

C1lEC T

LIMIT

PSE'CT

54 TEUS

~
B-6

;~l

LBR, EDI AND DMP EXAMPLES

•• MOOULEISETDJR

SJH.l"A126

INSERTED117•JUL•74

IDENT102

SJlfl00b70

INSfRTEot31•JUL•74

IoENTt06

SIZE t0CIJ292

tNSERTEDt11•JUL•74

lOENTt02

SlZE101iJ131

tNSERTEOs17•JUL•74

lDENT1~1

SIZE 10"'449

lNSEQTEDt22•SEP•74

JOENT104

SETO t R

•• ,.,OoULEISEToN
SETON

SET TIM

•• MOOULEISETJMM
Sf.TOSP

~ET IMM

•• MODULEaSETMX
SET MAX

•• MODULE a SPACE
M~!l<UIJT

QEMMAC

SHFMSB

•• t100UL.E1STMNT

SQZSTK

SIH.t~v.113\~

lNSERTEDt17•JUL•74

IOE"ITs~J

SIZE.IWH'l732

YNSERTE0117•JUL•74

IOENT104

SlMNT

•• MOOULEsSVMBL
A~GCNT

CT, NUM

ntv

GSARG
TSTARG

••

ARGPNT
CT,PC

CHSCAN
CT,PCX

D~lC

DNC:F

Cl,SMC
EXPFLG

GSARGF

MllL

MUI. ~5~

C TTBL

CT.ALP
CT,SP
GETCHR
SET CH~

CT.COM
CT,SPT
GETNR

CT, E::OL
CT, HB

C'T •LC
CVTNUM

GETR5~

GETSVM

SElN~

5E T F<5ft'

spsv~1

TSHHS0

MOOl.JLEsl!JO~l)B

SIH.10~141

INStRTEOs17•JUL•14

tOENTt~2

SJZFt~V'lR9

!NSE"TED111•JUL•74

IDENTa01

RVTE

•• MODULE 1.-iM I H
St.ICMO

B.. 1.4

h~IlE

L:lst Module Names and Module Entry Points (Global Symbols)
LBR>MAC , LP : /LE

or
LBR>MAC,LP:/LI/LE

nF FTLE MAC,0LRJ1

DIRECTO~V
OR.J~CT MOOULE

LASl

IN~ERT

LlR!o'AlolV CRf.AH.I" AV:

occu~~ED

22•SEP•74

B-7

LBR V)(l'12VM
11:5115~

LBR, EDI AND DMP EXAMPLES

MNT F.NT~TES 'LLOCATEDI 641 AVAILABLE• 20
EPT ENT"'IE~ ALLOCAH.DI 64U ~VAILABLEI 9~
FILE SPACE AVAILARLE I l.'llMH !5 WORDS

-I

•• MODULE'cASGMT
ASGMT

ASGMTF

•• MODIJLEIASSEM
At.Lacs

ASSE'M

CLSALL

EO~lTS

LCRITS

MACPt

XCTPAS

>CCTPRG

F.NDC

JFF

JFT

JFTF

IIF

•• MOOULEtCNOTL
CNDfUS

CNDTCIP

•• MOOULE1COO!oiD
CPXSTL

TNSIZE

PC ROLL

PC~T~L

OBJDMP
RLl)OMP

08JINI

RAD!"

iUrHH~

~L,,PNT

ORJLOC
STCOOE

OR.JPN T
TSTWLD

OBJ SEC

PC RC NT

ZAPCPlt

•• MQOl.ILE I DA TOR
ALl<B

...

tOENT

MODULEIENBDS
F.OT~AS

EDT TOP

ENA BL

•• MOOULEIENDLN
ENDLIN

••

EIH~RTS

F..~QCNT

Ll NBUF

LINE NO

LSTBUF

~OOULEIE:NOPS
E~DPt

ENOP2

•• MODULE sExPi:.is
U.iSE.R~

ABSEXP

ARSTRM

REL TR~

~fl TST

THIM

ABSTST

EXPQ

GLREXP

Gt.~HH1

LPPCNT

PAGEXT

PAGNIJM

Sf QENO

~ELEXP

•• MOOULEtFLOAT
•• MODLJl.Ear.ETLN
FFCNT

GE TLI N

Ll N~Jl.IM

B-8

111

;a hill II I ::umm I

121

LBR, EDI AND DMP EXAMPLES

\..I
GMARG

Gti1•1o1GF

QMARG

•• MnOULF. S 1 NF' ll
CMLM:?
nPENCH

CMLMJ

CMLH4

C:~LM5

CSl "1;»

CS I Mb

FINPl

OPNSMC

OPSwT1

OPS~T2

OU TERM

OUTM1

STl<Mt

INPMl
SOPSWT

•• MODULP.:IINJFL
S~CN4M

SIN I FL

•• MODULE: tt..JOFL
LSTNAM

'-'

08JNAM

'lNO,:"L

•• MODLJLE'.tLAREL
LA REL

L.ASE.LF

•• MODULEll.JSTC
LCTBAS

'-''

••

l.CTTOP

Ll~T

PAr.t

LSTDF.V
PUTLP

LST"IF•~

PAG~NE

PF~

SET PF~

SET PF 1

PF1
SETwog

PUT KR

SETBYT

BASCOO

EU SC PX

BA$l)MA

~ASDUM

FUSMAA

R4~MAB

FUS MAC

FU SP ST

~ASSWl

CLCNAM

IHSSYM
CLCSEC
ENOFLG
ERR,J
F.RH,T

MOOUL~Zl.STNG

Clo(l.F
fJUTt<l3L

LI NPPG
PLITLJN

SETWRL>

•• MOOULE1"4ACRO
\.,,J

\-1'

ALTSAV

ASC IT

ASClZ

FUSEDT

~Asu;o

RASLJA

RASREG

BASSH
RYT MOO

RASSF.:C

RA SC NO
AASLSY
RASSRC

CH~P~IT

CL.r.FGS

8ASSST
CLCLOC

CP~~OL

OM~~OL

f'ISA9L

F.:OT

COD~OL
E~R~NE'.

BASSTK
CLCMAX
OUMRClL

FRR.

E~R.A

F'~R.R

e:R~.D

F.FH<,E

ERR,L

RL,.1< w

CN,,ROL

EOTRl"IL

E'R~,M

Ewr:l, N

E~~.Q

E.RR.~

lf.Q~.

FVEN

ERR,O
FLAGS

E'Q~.P

F.RQ,U

IMPPA~

I~PC

LCDROL

LI~ROL

LSY~OL

MAA~OL

IMPURE
MACP2

MOVl:iVT
PSTROL

NL I ST
REGt;AS
RS,COD

IMPPAT
MAAROL
ODO
REG~OL

REG TOP
RS,OMA
RS,MAC
RS,SWT

MAC~OL

~PIT

MODE

OV~ACf.c

,,VSTt-1T

PAS~

ROL8AS
RS,EDT

ROLS!l
QS,LCO

ROLTf'IP
PS,LlF.:t

~S.~F.G

RS.SAT

R5~A~S

~~Vl'DOT
~IZCPX

~S.~AA

~S,MAH

PS.SF.C

RS,CNO
QS.LSY
QS,SRC

RS.SST

R$,5Tk

SATROL

SAVRE"G

SECQOL.

SIZDM.\

SIZOUM
S IZPS T
SIZSYM

SIZEDT

SI ZLI 8

SlZREG

SEC TO~
SI ZLCO
SIZSAT

S~C~OL

SST~OL

SHO~OL

TOPL.SY
TUPSRC

TOP CM
TOPMAA
TOP SST

TOPCPX
TOPMAB

TOP OMA
TOPt.1AC

TOPS·TK

Tl1PSWT

)(MtT0

)(MIT 1

)(MJT2

SIZCOD
SI ZMAA

SIZMAB

SIZMAC

SilS9T

9J2STI<

SJZSWT

SYM8EG
TOPE:. OT

~n"'~"L

TOPRF.G

SYMBOL
TOPLCO
TOPSAT

VALUE

wQRO

)(MJT5

)(~f"'T6

RS,CPX

OPCE~R

TOPLtR
TOP SEC

)(CTLTN

TOPC~D

)(MJT7

B-9

SETXP~

~TZSF.C

XMITJ

IMPURT

MACP2F
OPCL.AS

RELLVL
RS1r>UM

RS.PST
RS1SVM

SI ZCND
StZLSY
SIZSRC
swTROL
T QPl)Ut-4

TOPPST
TQPSYM
XMIU

LBR, EDI AND DMP EXAMPLES

•• MODIJLEr'1AC~~
PRM1CF

••

P~OMT

StTMAC

WCJMT

GET FI D

INJSML

SMLFOJi

GLO~L

P~JNT

SS TTL

MOOlJL~rMCALL

MCALL

••

"100llLE:r~LI8~

CPVMAC

FtNSML

•• Mt)OULEtMSCDR
ENO

F.~~OR

SE THOR

TITLE

"'
l

•• MC'IOULE1NOQCT
NARG

~CH~

NTVPF.

•• MOOULE•P~OCSI
DSADl)R
Nl..t-'SI<

DSMSI<
?A "'451<

EN~OI")~

ENMSI<

PROCSI

SPMSI<

LIA DDR

LIMSI<

ML.t-"SI<

NL ADD~

OPCl.AJ
PR()PC

OPCL~.d

OPCL05

OPCL06

""'

•• MODIJLF.tPQOJJC
AE)tp

OPCLOlli

('IPCLi.'11

OPC~02

OPCL~7

'1PCL08

OPCL'~9

OPCL10

•• Mnr>ULE I

P~Oh

PROSW

SjtjlBAS

S~ Tl OP

""-

•• MODULE•"ST
RS VT OP
SSHtAS

••

DFLCND
~ST TOP

DFLGRM

OFLGEV

DFL~UC

DFLSt-1C

PSTt.U~

PST TOP

LSGcUS

LSRCH

SCAN

SCA~W

LSY8KN
SEARCH

MSMCM
SSRCH

Wi-lOSYM

MQOULEP~EAD
GET\l~N

UEAI')

•• MClDIJLEIQEPT
F.ND1'4AC

JQP

~PUSH

~EPT

LSRFr.S
ROLNnX

t.SFL.AG
ROLUPO

•• ~ODIJL.Et~OL.1-10
APPENO

I NSF.RT

OSRCH

ZAP
B-10

OU:

LBR, EDI AND DMP EXAMPLES

Mt.H>UL~ I QSDAT

MAC~HH

MSRAPG

~S8?RP

MSB TX T

ST u~s

STLBUF

TTLSRK

MSIHYP
TTLBUF

CMLt3LI<

CNOMF>l
F.'OMCSI

EO.AM4

E>O'IFLG

GMAkLK

r;MAPNT

LSLENO

LCL.VL
LC,13IN

LC MAS~
Lc.cND

LC MC SI
LC.C0"4

LC.SF.Ctl

LC.S~C

MACLVL

MAC NAM

MACN'ICT

LC.LI)
LC,SYM
MACf)(T

MS~ENO

MS~LGH

MSBMRP

SML.L.VL

S~CNlJM

CNf'M~K

t.CSAVE

LC,MC
LC• TTM

CRAOU
ED • ..,EG

EOINtT

LCFL.AG

LCINIT
LCeBEX

t.C •

c1..os;c

TO HOF

tO,t~R

MACLDG
SRCCLO

OSJRUF

r.:MIBUF
FDBl
ro.NNU
ORJFIL

SRCM~I(

S~CPNT

S~CSAV

GETFLG
IO,OUT
PURGMC
TSTSTK

Lit-11T

PSE'CT

SA TSU

SHFMSB

SQZSTt<

~UFTBL

LC.MO
LIRNUM

LCeME

MSfViLK
PRGIDN

MSBCNT

FDBT~L

FOR2

IO,OPM
PASSS~

Ct..ITTRL

CONT

DA TTIM
IOFTBL.

GETPLI
VRNSAV

CSl8LI<
.-Cf>RTTL
LOA MAC
RLOBUF
Sl.I MIT

SATTnP

SEC IN I

fO,TTY
REST~T

.'liSwTCH

•• MODULE:1Q5UNP
R!)0UNP
u

'-'

MOOULEtSECTR
A SECT

••

CSECT

MODULEtSETOJ~

SETO IR
•• MOOULEtSETON

SETON

'-"

••

SE.TTIM

MODUL.Es~f.TIMM

SETDSP

SE TIM~

•• MODULE1SETM)C

SETMAX

** MCIOULE1SPACF.
MM I< OUT
u

E~DVE'C

MACGSB

pqGTTL

~OOULEs~SE~FC

nEFMC

\..,1

CONCNT
EO.LSS
LCENOL
LCS8At<

CNDLVL.
E'DM~AI<

LC.MER

••

CNDWRD
EO.GBL
LCBE<9L
LCSAVL
LCel.OC
LC.TOC:

A~GIMA.X

F.:OMASK

r:1EMMAC

MOOULEISTMNT

STMNT

B-11

LSTFIL
S?h'V

SL.STVZ

LBR, EDI AND DMP EXAMPLES

•• MnDULEISVMBL
DIV

ARGPNT
CT,PC
DNC

GSARG

GSAr.IGF

TSTARG

TSTR!Hi

Ar.IGCNT
CT,NU~

CHSCAN

rT, PC x

r. TT 8L
c1,s~c

DNCF

F.X PF' LG

MUL

~ULR50

•• MOOULEIWOROB
~VTE

SQCMO

B-12

CT.ALP
Cl,SP
GETCMM
SETCHR

cr.cnM

CT. F.: OL
Cl. Uf:t

r.1.u~

r:T,SPT
GETN~

GE.T~f)0

GETSVM

SET NB

~El~51ii

SElSVM

C v hlJM

LBR, EDI AND DMP EXAMPLES

B.2
B.2.1

SAMPLE LISTING POR LBR LIST SWITCHES (MACRO LIBRARY)
List Module Names
LBR> MAC, LP :

or
LBR>MAC,LP:LI

OlR!CTO~Y 0, ,l~! !•EMCeM~lll
MAC~O Ll8RAAV C~IATID 8VI
LIR

Vk03,•
LAST lNSE~T O~CUAREO 2•JUN•7! AT 17116121
MNT ENTRIES A LOCAT(OI 641 AVAlLAAL!I 52
!PT ENTRIES A ~OC•TfOI 01 AVAI~ABLEI 0
,IL! SPACE AVAlLABL!t 00780 ~OROS
U00'5
CLK on

CUCDFS
CVCOFS
OEVO"'S

!MBOFS

FllD'S

HORDF5

H~'oosrs

PC:80FS

PKT O'S
TC!BDFS

B-13

LBR, EDI AND DMP EXAMPLES

B.2.2

List Module Names and Full Module Information
LBR>MAC,LP:/LE/FU

or•
LBR>MAC,LP:/LI/LE/FU

DIA!CTORV 0' '11.E EMEMC,MLB•l
MACRO LIBRARY CREAT!~ BVI LBR VX0J,~
LAST I~SERT occv~~EO 2•JUN•75 AT 1111e12e
MNT ENTRIES ALLOCATED•
AVAILABLE• e2
!PT ENTRIES ALLOCATEOI 0' AVAILABLEI 0
'IL! SP4C~ AVAlLABL!I 00789 WORDS

e••

** MOOULE1ABODFS

SIZE100201

IN8ERTED12•JUN•15

•• MOOUL.EICLKOFS

SIZE100240

l~SERTfDl2•JUN•75

** MODULEtCUCDFS

SIZEt~0J'6

I~SERTED12•JUNe75

•• MODULE:tCVCOFS SIZE I 01d601

1NSERTE012•JUN•75

•• M001Jl.E1D!'VOFS

sue:1~101,

lNSERTfD12•JUN•7e

•• MOOUl.EtEMBOFS

SIZE 100299

1NSERTiOt2•JUN•75

•• MOOUl..EIFttOFS SIZE

1 liH~!3~

INSFRTED12•JUN•75

** MODUL.EIMOROFS

StZE100321

INS!RTED12•JUN"75

•• MOOUl.EIHWOl'>FS

SIZE 100368

lNSfRTEOl2•JUN•15

** MOOUl..f IPCBOFS

SIZE 100221

lNSERTf012•JUN•1!

MOOUl..EIPl<TOF$

SI Z! 100233

I~SERTED12•JUN•l8

•• MODUl.E1TCBO,S

SIZU1!0•39

INl!RT!Dl2•JUN•18

B-14

$112

I if!£

I (

LBR, EDI AND DMP EXAMPLES

B .. 31

'-''

SAMPLE EDITING OPERATIONS

Four sample editing operations are included in this section to
illustrate how the various EDI commands can be used. In the first
example, a file is edited using a few basic EDI commands. The second
exaimple, illustrates the use of the SAVE, UNSAVE and PASTE commands.
In the second example, two save files are generated, modified, and
appended to the original file. Any closed file may be appended to or
inserted within an open file in the same manner shown in the second
exaimple. The third example illustrates how an immediate macro command
can be defined and executed in a single step.
The last example
illustrates how a file containing errors can be edited using the macro
commands.

B-15

B.3.1

File Editing Sample

File PRTBLD.CMD is opened for editing. A PRINT * command
is issued to print the contents of the file. The following
errors are detected:

>EDI PRTBLD.CMD
[PAGE
1)
*p *
COMMAND FILE TO BUILD
PRNT SYMBIONT
FOR RSX-llM MAXXED SYSTEM

1 - PRNT should be PRINT.
2 - MAXXED should be MAPPED.

;

[l,54)PRT/MM/-CP,LP:=PRTBLD/MP

3 - /CP should have been used instead of /-CP.

;

; OPTIONS

.....I

°'

4 - INPUT should be appended to the line containing
the word OPTIONS.

STACK=40
PAR=PARK:O:lOOOO
UNITS=4
TASK=PRT •••
ASG=C0:2,LP:3
PRI=60
UC=[lO,l)

t:"'

°'

...~

5 - PARK should be PAR4K.

tSJ

t-1

=
0

6 - UC should be UIC.

SPECIFY
SPECIFY FLAG WHICH CONTROLS
FILE DELETION AFTER PRINTING

7 - The line containing

SPECIFY should be deleted.

tSJ

3:
tO

TO ENABLE DELETION USE

t:"'
tSJ

GBLPAT=PRT;$DELET:l
TO INHIBIT DELETION USE

8 - The comment line containing the format used to inhibit
deletion is missing.
9 - ENARBLED should be ENABLED •

DEFAULT FROM ASSEMBLY IS
FILE DELETION ENARBLED

GBLPAT=PRT:$DELET
I
[*EOB*)

)

-~;

10 - A :1 should be appended to the line following
the word $DELET.
The end of buffer is reached and EDI causes the EOB message
to be printed.

)

J
.

}

)

c:/

•TOP
[PAGE

*PL PRNT
; PRNT SYMBIONT
*C/RN/RIN/
; PRINT SYMBIONT

to
I

.....

-.J

; FOR RSX-llM MAXXED SYSTEM
*C/XX/PP/
; FOR RSX-llM MAPPED SYSTEM
*NP 3
[l,54]PRT/MM/-CP,LP:=PRTBLD/MP
*C,/-CP,/CP,
[l,54]PRT/MM/CP,LP:=PRTBLD/MP
*PL PAR=
PAR=PARK:O:lOOOO
*C/RK/R4K/
PAR=PAR4K:O:l0000
*NP -3
; OPTIONS
*AP INPUT
; OPTIONS INPUT
*PL UC
UC=[lO,l]
*C/UC/UIC/
UIC=[lO,l]

(

A TOP command is issued to move the line pointer to top of
file and editing is started.
1 - A PAGE LOCATE command is issued to locate the first
line in error and the line is printed automatically.
A CHANGE command is issued to correct the line
and the correc.ted line is displayed automatically.
2 - A carriage return is entered following the prompt to
move the line pointer and print the next line in error.
A CHANGE command is issued to correct the line and the
corrected line is displayed automatically.
3 - A NEXT PRINT 3 command is issued to locate the
next line in error and the line is printed. A CHANGE
command is issued to correct the 1 ine and the corrected
line is displayed automatically.
4 - A PAGE LOCATE command is issued to locate the next
line in error and the line is printed automatically. A
CHANGE command is issued to correct the line and the
corrected line is displayed automatically.
5 - A line in error was bypassed by mistake; therefore, a
NEXT PRINT -3 command is issued to back the line
pointer up. An ADD AND PRINT command is used to correct
·the line
6 - A PAGE LOCATE command is used to located the next line
in error and the line is printed automatically.
A CHANGE command is issued to correct the line and
the corrected line is displayed automatically.

t"'

tZJ

1-1

~
0

i.,,
tZJ

r>c:

!;
.,,
t"'

tZJ

-----

7 - The line pointer is moved down two lines via the
carriage return option to locate the next line in
error. A DELETE AND PRINT command is issued to delete
the line containing ; SPECIFY and print the
next line.

*
I

; SPECIFY
*DP
; SPECIFY FLAG WHICH CONTROLS
*PL !NH
; TO INHIBIT DELETION USE
*I

8 - A PAGE LOCATE command is issued to locate the
point in the file where the new comment lines
are to be inserted. EDI is switched to the Input
mode, two lines are entered, and EDI is switched
back to Edit mode by entering a carriage return as
the first character in the line.
9 - A PAGE LOCATE command is issued to locate the next
line in error. A CHANGE command is issued to
correct the spelling error. The line is displayed
automatically.

GBLPAT=PRT:$DELET:O
*PL RB
; FILE DELETION ENARBLED
*C/R//
; FILE DELETION ENABLED

*
i
*GBLPAT=PRT:$DELET

tJ:I
(X)

...~

till

10 - The line pointer is moved down two lines using two

"
~
"
"
t-1

carriage returns to locate the last line in error.
An ADD AND PRINT command is issued to append
:1 following the word $DELET.

*AP : 1
GBLPAT=PRT:$DELET:l
*TOF
[PAGE
l]

......

t'1
tJ:I

The necessary corrections are complete so the line
pointer is moved to the top of the file via a TOF command.

3
tO

till

3
tO
t'1

till
Ol

_,;)

)

(

*P *

A PRINT * command is issued to print the comolete
file with all corrections
-

COMMAND FILE TO BUILD
PRINT SYMBIONT
; FOR RSX-llM MAPPED-SYSTEM

.
I

[l,54]PRT/MM/CP,LP:=PRTBLD/MP
;

; OPTIONS INPUT

STACK=40
PAR=PAR4K:0:10000
UNITS=4
TASK=PRT •••
ASG=C0:2,LP:3
PRI=60
UIC=[lO,l]

tot

Dll
0
M

t
".,,fi

SPECIFY FLAG WHICH CONTROLS
FILE DELETION AFTER PRINTING

°'....I
'°

.,,,.,

. TO ENABLE DELETION USE

tlll

GBLPAT=PRT:$DELET:l

"'=

TO INHIBIT DELETION USE

tot

{I)

GBLPAT=PRT:$DELET:O

DEFAULT FROM ASSEMBLY IS
FILE DELETION ENABLED

GBLPAT=PRT:$DELET:l
I
[*EOB*]
*EX
[EXIT]

An EXIT connnand is issued to close the file and
terminate the editing session.

---j;

B.3.2

D:J
I

t-..)

SAVE and UNSAVE Example

*LI
THIS IS LINE 1 PAGE 1
THIS IS LINE 2 PAGE 1
THIS IS LINE 3 PAGE 1
THIS IS LINE 4 PAGE 1
THIS IS LINE 5 PAGE 1
[*EOB*]
*T
*SA 5 SAVI.DAT

The file to be used in this example is
printed via a LIST command.

*T
*SA 5 SAV2.DAT
*CL
EDI>SAVl. DAT
l]
[PAGE
*LI
THIS IS LINE 1 PAGE 1
THIS IS LINE 2 PAGE 1
THIS IS LINE 3 PAGE 1
THIS IS LINE 4 PAGE 1
THIS IS LINE 5 PAGE 1
[*EOB*]

The line pointer is returned to the top.
A second SAVE command is used to generate
a second saved file. The primary input file is closed.
The first save file is opened and a
LIST command is used to display the file.

*PA/PAGE l/PAGE 2/
THIS IS LINE 1 PAGE 2
THIS IS LINE 2 PAGE 2
THIS IS LINE 3 PAGE 2
THIS IS LINE 4 PAGE 2
THIS IS LINE 5 PAGE 2
*CL

A PASTE command is used to change
PAGE 1 to PAGE 2 in all lines.

The line pointer is returned to the top.
A SAVE command is used to save the
five lines in a separate file.
t:1

"'
~

tiil
0
1-1

tO
tiil

>
3:

&;
tll

The first save file is closed.

(

EDI>SAV2. DAT
rn,.,...n
trnu.c.

I\)

(

The second save file is opened.

*LI
THIS IS LINE 1 PAGE 1
THIS IS LINE 2 PAGE 1
THIS IS LINE 3 PAGE l
THIS IS LINE 4 PAGE 1
THIS IS LINE 5 PAGE 1
[*EOB*]

The LIST command is used to display
the contents of the file.

*PA/PAGE l/PAGE 3/
THIS IS LINE 1 PAGE
THIS IS LINE 2 PAGE
THIS IS LINE 3 PAGE
THIS IS LINE 4 PAGE
THIS IS LINE 5 PAGE

A PASTE command is used to change
PAGE 1 to PAGE 3 in all lines.

EDI >START. DAT
[PAGE
l]

°'

J. J

.*CL

.....

3
3
3
3
3

tot
to

The second save file is closed.
The original input file is opened again.

l'r.I

t:I
....

t:I
t:I
3
t'd

l'r.I

:a3

""tot
l'r.I

~
~

*BO
THIS IS LINE 5 PAGE 1
*UNS SAVI.DAT
*UNS SAV2.DAT
*T
*LI
THIS IS LINE 1 PAGE 1
THIS IS LINE 2 PAGE 1
THIS IS.LINE 3 PAGE 1
THIS IS LINE 4 PAGE 1
THIS IS LINE 5 PAGE 1
THIS IS LINE 1 PAGE 2
THIS IS LINE 2 PAGE 2
THIS IS LINE 3 PAGE 2
THIS IS LINE 4 PAGE 2
THIS IS LINE 5 PAGE 2
THIS IS LINE 1 PAGE 3
THIS IS LINE 2 PAGE 3
THIS IS LINE 3 PAGE 3
THIS IS LINE 4 PAGE 3
THIS IS LINE 5 PAGE ~
[*EOB*]
*EX
[EXIT]

The last line in the file is located.
Two UNSAVE commands are used to
append the two save files to the
original input file.
A LIST command is used to
display the contents of the
combined file.

~
~

=
s
0
0

~
~

E
~
~
~

)

(
B.3.3

"'w

ABC IN LINE N - ABC
[*EOB*]
*4<F ABC&C/ABC/DEF/>
ABC IN LINE 1 - ABC
DEF IN LINE 1 - ABC
ABC IN LINE 2 - ABC
DEF IN LINE 2 - ABC
ABC IN LINE 3 - ABC
DEF IN LINE 3 - ABC
ABC IN LINE 4 - ABC
DEF IN LINE 4 - ABC

(

Use of Immediate Macro Command

*LI
ABC IN LINE l - ABC
ABC IN LINE 2 - ABC
ABC IN LINE 3 - ABC
ABC IN LINE 4 - ABC
ABC IN LINE 5 - ABC

O:I

(

A LIST command is issued to print
the file used in this example.

t'1

The immediate macro is defined
and executed to .find the first
four lines which start with ABC
and change the first occurrence
of the string ABC to DEF.
The FIND command causes the line
to be printed before the change.
The CHANGE command causes
the line to be printed after
the change.

°'

._~

ti;I

'....='

=
'='
'='
•
'ti
ti;I
~

)ii

'ti
t'1

ll!I

tll

B.3.4

Use of Macro Commands
The LIST command is used to print the
file and the file is checked for errors.
The following errors are located.

*LI

°'

THIS LITTLE FILE HAS
MANY CONNON ETTORS SO
WE CAN SHOW YOU ROW
YHE MACRO CONNANDS CAN
BE USED.
FIRST, YHE DESIRED MACRO
MUST BE DEFINED; YHE LINE
POINTER IS MOVED TO A LINE
WITH AN ETTOR; AND YHEN, YHE
MACRO EXECUTE CONNAND
IS ISSUED TO COTTECT YHE
ETTOR
[*EOB*]
"MACRO 1 C/NN/MM/
*MACRO 2 SC/TT/RR/
*MACRO 3 PA/YHE/THE/

I\..)

1. The string NN is used in place
of MM (see macro 1).
2. The string TT is used in place
of RR (see macro 2).
3. The string YHE is used in place

tot

of THE (see macro 3) •

ti!!

....

The three macro definitions which will
correct the errors are typed.

Macro 3 is used to change all YHE
strings to THE.

*M3

THE MACRO CONNANDS CAN.
FIRST, THE DESIRED MACRO
MUST BE DEFINED; THE LINE
WITH AN ETTOR; AND THEN, THE
IS ISSUED TO COTTECT THE
"NP2
MANY CONNON ETTORS SO
"Ml
MANY COMMON ETTORS SO
"12
MANY COMMON ERRORS SO

ttj

tll:I

I><

=
ttj

tot

NP2 is used to locate a line with errors.

ti!!

Ml is used to change NN to MM.
M2 is used to change TT to RR.

}

)

('
*NP2
THE MACRO CONNANDS CAN

•1
THE MACRO COMMANDS CAN
*M2

(

NP2 is used to locate the next line in error.
Ml is used to change NN to MM.
M2 is used to locate the next TT strino
and change it to RR.
-

WITH AN ERROR; AND THEN, THE
*_)

MACRO EXECUTE CONNAND

A carriage return is used here to locate the next line
in error.

MACRO EXECUTE COMMAND

Ml is used to change NN to MM.

IS ISSUED TO CORRECT THE

M2 is used to locate the next TT string and
change it to RR.
M2 is used to locate the last error in the
file and correct it.
After all lines have been corrected, the
file is printed using the LIST command.

•2
•2

ERROR
~
~I

tcJ
I

U'1

THIS LITTLE FILE HAS
MANY COMMON ERRORS SO
WE CAN SHOW YOU HOW
THE MACRO COMMANDS CAN
BE USED.
FIRST, THE DESIRED MACRO
MUST BE DEFINED; THE LINE
POINTER IS MOVED TO A LINE
WITH AN ERROR; AND THEN, THE
MACRO EXECUTE COMMAND
IS ISSUED TO CORRECT THE
ERROR.
[*EOB*]

t""

ti'

tlJ

t:7

....
~
t:7

t:7
3:
"'O
tlJ

=
3:

"'O
t""
tlJ

LBR, EDI AND DMP EXAMPLES

B.4

SAMPLE DMP LISTINGS

B.4.1

Use of /LB Switch

DMP>TI:=SY:BIGMAC.TSK/LB
STARTING BLOCK NUMBER = 0,135163 c
DMP>TI:=SY:SYSGEN.CMD/LB
STARTING BLOCK NUMBER = 13 ,{3JJ16{36
B.4.2

"Standard" Command Line

This conunand will dump virtual blocks 1 and 2 in SYSGEN.CMD in
ASCII mode.
~LP:=SY:SYSGEN.CMD/AS/BL:l:2

DUMP OF DP01[200,200]SVSGEN,CMD•15 •FILE ID 7157,3511.16,0
VIRTUAL BLOCK 0,00A~01 • SIZE 512, BVTE'S

000420

, •• •• , s s ...
•• s' •• s '
,. T u
s s
s
T
u
c
,
...
,
s
v
••
•• u
• •
u
...u
p
E
s
s
•
s
•
u•
• •A ....
w
c
T
,c c s ss Tw R•- y D Ts T s
' s "A •• •• •o •• s •E T
u I c
,
s
5
l
••
•
--·L x •• •• •
•• l' s
,..

0HIH•0

000000
000020
000040
000060
000100
000120
000140
000160
000200
000220
000240
000a60

0003H
IH03Z0
000340

001360
HUH

001460
0H5H

0HJ520
000540
IHJ5U
HH00
H0H0
H0b40
QJH&H

000700
100120
01210740

IH07U

••A
T
E

iii •

T
R

iip
1
M l

B L E
E ""A
y
R E
M
A
< ••
A
N
R
N
H l
H

E
t<

[

-6ili

N
E

t-1

ilif

N
f

"'A
E

I
E

p ilif iiG

0
)(

8
0
8
G
I

L.
y

R
N

1-1

I<
N

N
... I

K
D

M
0

t»1

R
L

I
I
I

••A c• •
B
F T
E ·Q •• •
T s K
AW ....
c
M
J
s' *
••
l
• I
•
p
T s
M A c
l
8
I' T
,,., ,. A •• •• .... • D E
D E
I
*
I. E
l
L' E T E
' s F R' ••0 M, ...I
s' y s G E N s
A s T
... I
v I R G I N
0
N 0 T E
F
F

l
p
I
B
p

l
D

A
I

c •z
G
I

D
H

T
I.

0
I.
L

s s

K
fl'

... x'
l

G
G

N
N

l
l
!

s T
v e:

.-1 •1

"""

""N

E
f'
f
I

l
T

""'G

0
N

p
K

D E

E
E
!

•• 5 ..... '

T
E
l

R 0
-1 •1

p
R
T

w l

M
A

~
B-26

411

LBR, EDI AND DMP EXAMPLES

DUMF• OF

HHIHI
HIH21
HH4B

HHU

'-'

100100
HU20
HU40
000160
00UHI
Hlc!20
00QH!40
0H~!b0

HUH
100~•20

HU40
0HJJIU

'-'

HQHtH
IHJQJttZ0
HQJtt40
0Htl60
0H~illl0
000~•20
H0~i40

H0!iU

HHH

00(/Jet20
Hr.'Ut40
0HIEt60

DPB1t211,~ee]SVSGEN,CMD115. ~ILE

T
E
D
.,.A
l

H
H

D
T H
T
E T
p

....0 E su •p• •• •ss0 ...
T

• sc

ra ]
M D

)(

• s

R
AN
•p

iii'. p

B
I

)(

' * *• c•

I
E
E

M
0

)(

F
I

I
0

• c
•
I* u

•• s Ex T
iltp ...
, 2
l .. s •• p J
D E
I
c

E
D

t< •s
D
B J

M
0

H .. s
0

s
R

E
l
R

!
!

A
E

T
c ••
s )(

••• Ip

A
I
D

' ' • l

c
s •)(

••

p
I

[

J
0
I
1

p
E
D

...

••l "Rs ••E Tp I I u sI cy •s' T' *B1 • , A1
"cc •' * I cD E •R* ••I D EI ...p •• R, ...s 7 ••M
!
w E
R u
T
0 w
p

[

M
N

s v s
s
T 0
E c u T
u R E s
N
T
U'

000720
0011'40
l!HiU

""E

N
0

• I

L
E

y
N

'
L
"
w •
G
E
I

A
y

G
M

u
T

E
0

N
E
E
N
N

A
D
A

I
A

D
T
T
y
0

c
s

T
0

E
0
N
H

s T
T

)(

N
G
M

0
T

... , v
D E

T
A

B-27

I
M

H0i'H

XD 7157,3514611

VIRTUAL BLOCK 0,011012 • SUE 512, BYTES

E
R

-·
•

I
D
E

•1

•

R
R

I
M

...

N •

R
E
F
I

H
M

E
f

0
R

T- H E

' •xf

R
1

t<
0
E

s s e:

s ....

u•

)(

"I
l

LBR, EDI AND DMP EXAMPLES

B.4.3

Dump Only the Header from SYSGEN.CMD

DMP>LP:=SY:SYSGEN.CMD/HD/BL:~:~

DMP>

DUMP OF OP01[212101200]SVSGEN,CMD,15 • FILE ID 71571351010
FILE MEADER
(7157, 35140)
SVSGEN.CMDS 15
[200, 20"] [RWEO, RWED, RWE01 R]
000000
000020

000040
0000b121
000100
000120
000140
0001b0

000200
000i!20
0002ttB
0002b0
000300
000320
000340
0003b0

H0400
0001.t20
0210U40
000460
000500

H0520

000540
H05o0
000600
G!J0H20
Hl0b't0

0006b0
000700
000720

H.10140
OH/H!J'7b0
B.4.4

1,110.

11•0CT•74 11148

027027 007157 111351 'fb 00040\ l l'J0200 1UH0 12100000 001002
000077 00000121 0H012 000000
000u0 1'300000 000000 00001iJA
aab22t> 000000 012314 000015
030464 032461 030462 030462
034064 032461 00012100 0H0flot
000000 001401 146000 H2HA
044306 000900 000000 0000A0
000000 000000 090000 00000"
e0ro000 1?100000 000000 00000'11
000000 1300000 000000 0000"1il
900000 D00000 e000H 0000AUI
01!0000 000000 000000 0000PIA
000000 "00000 000000 0100000
a00000 0001cHHI 000000 0000Aot
0~0000 000000 000000 00001.'1111
130~000 000000 0000021 00000'11
000000 000000 000000 00000(19
000~00 000000 0000H 0000elf't
000000 13''.10000 00D0C!l0 0000A'1J
0t'J0000 0000130 000000 0000CJtOJ
rl00000 0000(?10 000000 000000
000000 000000 000000 0000PIA
000000 000000 "100000 0000Pt"'
'100000 B00000 000000 000000
000000 000000 000000 00000"'
000000 00000121 000000 0HHPJ
000000 LHl0000 000000 0000PI"'
000000 '1!000Cl0 000000 00H~PJ
000000 000000 00001210 00000A
000000 IH0000 000000 0000PIUI
000000 000000 000000 0000AA

000010
000000
000001
047461
0Hl000

HHH 000000 000000

HHH H0000 075273
03121461 041517 0335i!4

052103 032G!Jb7 030461
000000 000000 000000

001Uo H0H0 044156 H141HJ
000000 000000 01210000
HHH 000000 000000
000000 000000 000000
H012100 000000 H00H
HH00 00000121 00000121
000000 000000 00000eJ
00000121 000000 000000
000000 000000 000000
000000 000000 000000
000000 0HH0 000000

000100

000000
IH0HJ0

'1JHH0
000000
000000
00121000
000000
000000
000000

000000 000000 000000 000000
000000 000000 000000 000H0
000000 000000 000000 00000QJ
000000 000000 000000 000000
2100000 0000H 000000 000000
01210000 Hfa-000 000000 000000
H0H10 0001'cl00 00000121 000000
000000 000000 000000 000000
000000 000000 000000 0·000210
000000 001HH 0210000 000001
0000210 00000J 00000B 000000
000000 0002100 0000013 000000
H0000 000000 000000 000000
000000 000000 0H000 12100000
H0000 01210000 000000 10~212

Use of /BA Switch

The first command sets the base block address to 2, the next command
causes virtual blocks 3 and 4 to be dumped.
DMP> /BA:~: 2
DMP>LP:=SYSGEN.CMD/BY/BL:l:2
DMP>

~
B-28

!I~

£)$

I I

LBR, EDI AND DMP EXAMPLES

DU!~P

0H000
0H020
01'H040

HH60

'-'

\...-1

00"100
0Ht20
01'Ht40
01Hl60
121H200
e'H220
00"240
09"260
0H3HI
0H320
HJU40
00"360
0H400
0H420

IHH9440
00"4H
0H500
L'JH520

0H540
HG15Hl

0Hl600
0Ht620
HQl640

'-'

•FILE 10 715713514610
VIRTUAL BLOCK 0100AA03 • SIZE 512, BYTES

OF DP01[2001200]SYSGEN.CMDJ15

0Htob0
0H700
0Ht720
fJHJ740
0Ht7o0

""0

116 107
UT 116 0/f 0 101 A40 115 101 Ul 110 111 116 105 040
1127 111 U4 110 040 115 117 t22 105 040 124 110 101 116 12140 0U
ei&6 113 040 127 117 122 104 Ul 072 000 073 011 131 U 7 125 040
115 101 U1 040 107 105 U4 '1140 101 123 123 us 115 102 114 U1
040 114 111 123 124 111 116 107 123 040 117 116 114 131 1214121 111
106 04121 131 117 125 040 104 t 11 122 us 103 124 040 124 110 105
040 124 117 073 000 073 r.u 1 124 110 105 040 114 111 116 105
040 120 122 111 116 124 105 t22 040 050 114 120 060 072 051 040
117 122 040 101 116 117 124 110 105 122 040 104 1 t1 123 113 2156
l(J40 040 124 110 105 122 U5 '1140 111 123 0421 11 I> 117 124 040 040
a1~0 103 062 000 073 011 105 \16 117 125 107 110 040 123 120 Ut
!Bl 105 040 111 116 040 124 110 105 040 123 117 125 122 U3 11215
a4e 104 111 lZ3 113 LM0 124 117 040 113 105 105 120 040 101 114
1:14 0lf 0 124 11111 105 CM0 12131 f1100 073 011 101 123 123 105 115 U2
U4 131 040 114 111 123 124 111 116 107 040 Ub 111 114 105 123
0~56 073 iHH 000 073 105 U0 U0 122 125 1U 040 044 123 UT 11&
0U 000 073 101 063 000 073 "140 UJ1 1C!4 040 1.24 lUJ 111 123 040
116 101 115 105 040
040 12a
120 117 111 116 124 040 127
1\5 102 114 131 040 103 117 115
1i~4 110 1B5 040 101 123 123
11?11 116 U4 040 106 111 114 105 040 046 000 073 040 101 116
040 102 125 111
1134 040 124 110 105 040 123 131 U3 U4 105
U4 104 ~M0 103 117 115 115 101 116 104 040 106 111 114 105 1140
124 117 020 000 056 111 106 106 040 101 040 073 011 133 0(>1 061
0!)4 062 060 135 020 000 056 111 106 121.t 040 101 040 073 011 133
061 eu 054 0ft2 064 135 001 l'J00 073 125 057 000 056 11 t i06 10&
101 040 120 111 120 040 133 0U 061 051.t 062 060 135 057 122
056 103 115 10'+ 073 052 054 122
us 075 122 123 130 101 123
1;?3 130 U2 114 10'4 056 103 115 U" 073 05Z 011 057 000 056 111
Uo 124 040 101 040 120 111 t20 040 133 061 061 054 062 064 135
0~)7 122 105 075 12&? 123 130 101 123 115 056 U3 115 104 073 12152
0~)4 122 1Z3 130 102 114 104 05& 103 115 104 073 052 000 077 H0
~~;6 101 1Z3 113 040 132 040 104 111 104 040 131 117 125 040 101

us
us

0' "

B-29

LBR, EDI AND DMP EXAMPLES

DUMP OP DPBt[2001Z0121JSYSGEN.CMDJ15 •FILE ID 715713514610
VIRTU•L BLOCK' 121, 000004 • SlZf 512, BYTES

HHH
0000Z0

000040
000060
000100
000120
000140
100160
000200
00022121

·000240
H02b0

000300
000320
2100340
0003&0

H0"f00
HJrlJ420
000440

H01.fb0

010500

0H520
000540
IHl05(,0
100600
H0t»20

000640
HIU»60
101700

000120
0011740
000160

1lb 123 127 us 122 140 124 1U 105 040 123 131 123 U7 105 11 (t
040 121 125 us 123 124 111 117 116 U3 040 124 117 040 131 117
125 122 04121 123 Ul 124 111 123 106 Ul 103 t 24 111 117 116 040

02e 000 056 111 106 124 040 132 040 12156 107 117 124 117 040
069 ldbeJ 001 000 ian 111 074 IHJ0 073 040 127 U5 041 127 111
114 rolf0 105 130 111 124 040 116 117 127 040 123 117 041 124
040 115 101 131 040 122 105 123 124
1B1 124 "40 131 117
122 124 049 124 110 111 123 ot40 103 117 115 115 101 116 104
lBb 111 114 105 0b7 009 073 "140 106 122 117 115 040 124 110
e1.10 102 10s 101 111 116 116 111 1t6 107 056 040 124 110 111
040 127 111 114 114 040 101 114 114 117 127 040 101 040 103
105 101 llb 040 1Z5 120 040 117 10& 04121 124 110 105 122 070
S73 040 104 111 123 1U 040 OH 116 1'!14 040 101 040 116 105
040 122 125 11& 040 117 106 "'"" 123 107 11& 040 124 117 eJ40
105 114 us 103 124 01.10 124 110 U5 040 120 12e! 11 '7 120 U5
1214121 Uf> 117 1ZC?
""" 117 120 124 111 117 116 123 022 00121 073 05b
001 000 013
131 117 125 122 040 123 131 123 124 105 115
a12 b00 es& 101 111 124 117 A40 0U 060 0b0 0b0 006 00,a 056
260 060 072 073 037 000 073 "140 11b 117 127 040 127 105 040
t'J40 124 110 105 "'40 105 130 U5
l23 123 105 115 102 114
125 124 111 126 105 01.10 001 "100 073 124 027 000 056 111 106
040 101 040 123 105 124 040 "157 125 111 103 075 133 061 061
062 060 135 000 027 000 056 111 106 124 040 101 041 li!3 105
073 013
040 057 125 111 103 075 133 Abl 0U 054 062 064

114
110

101

eJ40

105
123
114
eJH
127

123
122
040

040

a: I

061
Ul

106
054
124
000

115 101 103 040 100 122 123 130 101 123 us 000 001 0H 073 11216
~62 00121 ~73 040 116 117 127 A40 127 105 040 102 125 111 11 q 104
040 1za 110 105 040 103 111 Ub U3 101 12'1 105 116 Ul 124 11215
1B4 840 117 102 112 105 103 124 040 115 117 U4 125 U4 105 040
106 111 114 105 024 000 073 A40 106 117 122 04121 124 110 105 040
105 130 1~5 103 125 124 111 126 105 056 0211 000 2173 104 024 000
120 1\1 120 040 122 123 130 0(> 1 0b1 115 05& 117 1B2 123 075 052
056 117 102 112 026 000 120 111 120 040 056 117 102 112 057 122

B-30

APPENDIX C
RSX-llM SERIAL DESPOOLER TASK

The RSX-llM 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, a task directs the
output intended for the 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-llM
Queue Manager and its associated despooler. See Chapters 6 and 7 of
this manual for more information.

C.l

RECEIVE QUEUE OPERATION

The standard method of placing a user file
in the serial despooler
receive queue
(and requesting its execution) is via the PRINT$ macro
call, which is described in the IAS/RSX-11 I/O Operations Reference
~al.
Files are spooled in this same manner by the RSX-11 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 C-1.

'-"

C.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
carriage control (that is, standard, embedded, and FORTRAN).

C.3

TASK-BUILD INFORMATION

The serial despooler task must be built during an RSX-llM system
generation because the task image file (PRT.TSK) is not distributed on
the standard 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
automatic delete feature.
(Note also, that a nondeleting despooler
can be made to delete, if the data block mentioned in Section C.l and
shown in Figure C-1 has a negative value in word 7.) When the serial
despooler
is built without automatic delete,
spooled files are

C-1

RSX-llM SERIAL DESPOOLER TASK
retained after printing.
If the system has a deleting
despooler, all.spooled files are deleted after printing.
See the RSX-llM System Generation and Management
system generation information.

Guide

for

serial
detailed

WORD
1

File name

RADIX-SO

File type in RADIX-50

File version (binary)

Device name in ASCII

Unit number (binary)

File ID

10
11

Directory ID

13
Figure C-1

PRT Send Data Buff er Format

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

C.4

PRT ERROR MESSAGES

All error messages issued by PRT are sent to the console terminal
pseudo-device CO:. The error messages have the following format:

via

PRT -- text
In all but the receive failure error, the messages supply information
that identifies the sender task and the file in question. All PRT
errors are fatal; upon error detection, printing of the input file is
terminated, and a cleanup/restart procedure is entered.

C-2

RSX-11.M SERIAL DESPOOLER TASK

'-1'

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
condjltion.
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.
NO DJWICE NAME - SENDER: task FILE: filename.typ;ver
Exp1anation:
name.

The dequeued print request did not contain a device

NO FILE ID - SENDER: task FILE: filename.typ;ver
Explanation:
ID.

\.-1

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 conditions may exist:

The file
is
privileges.

A problem exists on the physical
device cycled down).

The volume is not mounted.

The specified file directory does not exist.

The named
directory.

The file is already deleted.

protected

file

does

against

not

exist

access
device

(for

the

One of the
for

read

example,

specified

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.

C-3

RSX-llM SERIAL DESPOOLER TASK

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 conditions may exist:

A problem exists on the physical
device cycled down).

device

(for

example,

Length of the text line is greater than 132 bytes.

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.

C-4

lines.

APPENDIX D

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR

CRF, the RSX-11 cross-reference processor, is an independent task that
produces cross-reference listings for the MACR0-11 and Task Builder
task:s. CRF is invoked by the /CR switch on the MACR0-11 or Task
Builder
command line.
Once execution is complete, CRF builds
cross-reference listings using the execution-time symbol tables built
by those tasks.
Two cross-reference listings are built for the Task Builder, one
listing
the modules that reference global symbols during task
execution and another that shows the modules contained in a given
overlay segment.
Four cross-ref~rence listings are produced for the MACR0-11 task, each
showing a page and line number reference to a type of symbol
referenced during execution of the MACR0-11 assembler.
This appendix describes how CRF processes data and shows the formats
of files CRF uses during that processing. Also, CRF error messages
are listed.
For information on how to invoke CRF via the MACR0-11 command line,
ref er to the IAS/RSX-11 MACR0-11 Reference Manual. For information on
how to invoke CRF via the Task Builder command line, refer to the
RSX-llM/M-PLUS Task Builder Manual.

D.l

HOW CRF PROCESSES DATA

When the /CR switch is specified on the MACR0-11 or Task Builder
command line, those tasks perform additional processing before passing
control to the CRF
proces~or.
This
section
describes
how
cross-reference listings are generated in two phases. The first phase
consists of the processing steps performed by MACR0-11 or Task
Builder;
the second phase consists of processing steps performed by
CRF. Figure D-1 is an overview showing the processing steps performed
in each phase, along with input and output files used.

D.1 .1

MACll0-11/Task Builder Processing

The first steps to produce cross-reference listings are performed by
MACR0-11 or Task Builder.
These processors generate three files
duri.ng exeeution: an object file
(file.OBJ) or task image file
(file.TSK)u a listing file (file.LST or file.MAP), and a CRF symbol
table f i 1e (f i 1e • CRF ) •
The object file or task image file is directed
device and does not affect CRF processing.
D-1

appropriate

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR
OUTPUT

PROCESS

INPUT

Execute MACR0·11 or Ta1k Builder.
Direct OBJ and LST files to appropriate__._ ____,
devices; copy CRF file to SYO:.

Command Line

~
~'-----~

Construct SEND packet.

filename.filetype

SEND Packet

Execute CREF.
Generate cross-reference entries and
append them to the LST file.

------- ------ . . .

Figure D-1

DeleteCRFfile.

How MACR0-11, Task Builder, and CRF Generate
Cross-Reference Listings

The listing file consists of text information generated during the
execution of the processors, for example, the listing of the source
code in an assembler language program. If the output device for the
listing file is sequential or record-oriented, as in the case of LP:,
a temporary listing file is created on SYO:.
The CRF symbol table file consists of symbol tables built during
MACR0-11 or Task Builder execution. These tables are used by CRF to
generate cross-reference listings.
The task originating the request for cross-reference processing then
constructs a SEND packet using information contained in the listing
file and the filename and filetype specified on the command line. The
SEND packet contains enough data to identify the symbol table file and
the listing file. CRF receives the packet and uses it to locate the
symbol table file and listing file produced by MACR0-11 or Task
Builder.
The formats of the symbol table file and the SEND packet are shown
Figures D-2 and D-3.

If spooling is requested and the output device is a random-access
device, the spooling flag in the SEND packet is set. CRF then passes
the listing file to the print spooler for printing.

D-2

QR I

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR
D.1.2

CRF Processing

The SEND packet contains pointers to the CRF symbol table file and the
listing file.
CRF uses the information in the listing file and the
SEND packet to construct a file specification to use to open the
symbol table file for processing:
symbol
symbol
symbol
symbol
device

table file name = text filename
table filetype = CRF
table version
contents of SEND packet word 11
table
and unit
= listing file device and unit

CRF then generates the requested cross-references and appends them to
the listing file.
When all cross-references have been generated, CRF
deletes file.CRF.

D.2

THE CRF SYMBOL TABLE FILE

The CRF symbol table file
is a series of contiguous 5-word data
records preceded by a 9-word header record, as shown in Figure D-2.
The symbol table file is assumed to reside on the same device and have
the same name as the input listing file, except that the file has a
filetype of CRF, that is:
filename.CRF
The header record contains the name of the originating task
in
two-word RADIX-50 format, followed by a number value assigned by the
system to identify the task.
This value allows CRF to locate the
internal tables CRF uses to format output.
The next five words define
the creation date of the symbol table file.
The last word contains
the flags
that define the output format.
Bit zero of the flag word
controls the width of the listing. When this bit is set to zero,
the
listing is generated in 132-column format.
When this bit is set to
one, the listing is generated in 80-column format.
The remaining records in the symbol table file are data records.
The
first two words of a data record comprise the symbol name in RADIX-50
format.
The symbol value is an octal quantity associated with the
symbol name.
The second two words comprise the reference identifier,
which is used as the cross-reference value.
In the case of global
symbols,
this value is the module name in RADIX-50 format.
In the
case of MACR0-11 cross-references, the value is the page and line
number of the reference.
The last word of the data record comprises
the attribute flag byte and the format number byte.
The attribute flag byte contains the bits describing the attributes of
the
reference.
These flags cause the special characters and
abbreviations to be displayed with the reference. A pound sign
(#)
means that the reference is the place where the symbol is defined. An
asterisk (*) means that there is a destructive reference to the symbol
(that is, its contents are changed).
If there is nothing in front of
the reference, it means that there is a nondestructive reference to
the symbol (that is, its contents are read).
The format number byte defines the format of the output.
The format
number
is used by CRF to locate a set of internal tables which define
the listing format associated with the entry.
The
type
of
cross-reference and the set of symbols associated with the flags byte
is determined by the format number.
Use of the format byte permits
several types of cross-reference output to be generated by a single
originating task.
D-3

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR
Header Record
Name of Originating Task

-----------------1
Name of Originating Task (Cont.)

Two
RADIX-50
Words

Originating Task Identifier
Year
CREF
Symbol
Table
File

Month
Day
Hour

Header
Record

Minute
Flag Byte

Data Record 1
Data Record 2

Data Record
Symbol Name

---------------1
Symbol Name (Cont.)

Two
RADIX-50
Words

Reference Identifier

Data Record n

Reference Identifier (Cont.)
Format Number

Attributes

Data
Records
to
EOF

Figure D-2

D.3

Format of the CRF Symbol Table File

THE CRF SEND PACKET

The CRF SEND packet is a block of data that contains control
information created by the Task Builder or MACR0-11 for use by CRF.
This control information enables CRF to locate the symbol table file
and the listing or memory allocation output file.
The SEND packet consists of 16 words, as described

Figure D-3.

Words 1 and 2 of the SEND packet contain the name of the sending task.
Words 2 through 4 contain the filename of the output listing file in
RADIX-SO format.
Word 5 contains the f iletype of the output listing
file.
Word 6 contains the version number of the output listing file.
Words 7 through 11 contain the directory identifier. Word 12 contains
the device name of the device on which the output listing file
resides. The first byte of word 13 is a flag byte used by CRF for
output processing. When this bit is set to 1, the output listing file
is spooled of fline when CRF completes processing. The second byte of
word 13 specifies the unit on which the listing output file resides.
Word 14 contains the symbol table file version number.
Word 15
contains the device name of the output device. The first byte of word
16 is reserved.
The second byte of word 16 is the unit number of the
output device.

D-4

11=

iii'

tu¥¥ I

CRF--TBE RSX-11 CROSS-REFERENCE PROCESSOR

Originating Task Name

Two
RADIX-50
} Words

Originating Task Name (Cont.)

'-'

Text Filename

Text Filename (Cont.)

Filetype

File Version

Directory Identifier

Directory Identifier (Cont.)

Device Name

Unit

Symbol Table File Version

Target Device Name

Reserved

Figure D-3

D.4

Flags

}

Three
RADIX-50
Words

Unit

Format of the CRF SEND Packet

CRF ERROR MESSAGES

The following error messages are output by the Cross Reference
Each message is preceded by one of the following prefixes:
CRF
CRF

Task.

*DIAG* - name of originating task - MESSAGE
*FATAL* - name of originating task - MESSAGE

CRF INPUT FILE filename HAS ILLEGAL FORMAT
Explanation: This error is caused by a
originating task.
The symbol table
processing contains no data.

software error
file submitt~d

in the
for CRF

User Action: Submit a Software Performance Report along with the
related console dialogue and any other pertinent information.

D-5

CRF--TBE RSX-11 CROSS-REFERENCE PROCESSOR

FAILED TO DELETE FILE filename
Explanation: CRF was unable to delete the specified file for one
of the following reasons:

•
•

CRF did not have deletion privileges for the UFO under which
the file resides.
The device was not write-enabled or ready to perform I/O.

User Action: Initialize the device appropriately and ensure that
the UFO has owner-delete privileges.

FILE filename NOT FOUND
Explanation: File filename could not be located;
probably deleted before CRF could process it.
User
Action:
Rerun
cross-reference output.
completes processing.

the
Do

the

file

was

task
to
produce
appropriate
not delete any files until CRF

ILLEGAL ERROR/SEVERITY CODE data
Explanation: This error indicates a CRF software malfunction;
CRF has called its error message processor with an illegal
parameter.
User Action: Submit a Software Performance Report containing a
copy of the message as printed. Correct any user errors and
rerun the initiating task.

INPUT FROM UNKNOWN TASK
Explanation:
Cross-reference processing
originating task is not supported by CRF.

requested

the

User Action: Delete the request for CRF processing and rerun the
originating task.

I/O ERROR ON FILE filename
Explanation: An error has been encountered while reading or
writing the specified file.
A possible hardware problem is
indicated;
or the device may have insufficient space
to
accommodate the CRF output file.
User Action: Isolate the problem and take corrective action.
Rerun MACRO or TKB to produce the cross-reference output.

INVALID OUTPUT FORMAT SPECIFIED
Explanation: This message indicates an inconsistency in the data
file submitted for CRF processing.
User Action: Submit a Software Performance Report along with the
related console dialogue and any other pertinent information.

D-6

CRF--THE Rsx~11 CROSS-REFERENCE PROCESSOR
NO DYNAMIC STORAGE AVAILABLE
Expl~nation:

storage
task.

The Cross-Reference task requires more working
than is available within the area of memory owned by the

User Action: If possible,
with a larger increment.

install CRF in a larger

partition

NO VIRTUAL MEMORY STORAGE AVAILABLE

Explanation:

The Cross-Reference
requirements exceed 65,536 words.

processor

work

User Action:

No recovery is possible from this
possible, install the task in a larger partition.

file

storage

error.

for

OPEN FAILURE ON FILE filename

Explanation:

CRF was unable to open the named file
the following reasons:

•
•
•
•
•

one

The device was not ready to perform I/O.
The device was not write-enabled.
A Files-11 device was not mounted.
CRF did not have extend or delete privileges for the UFO under
which the file resides.
The file was deleted before it could be processed by CRF.

User Action:

Isolate the problem,
take appropriate corrective
action, and rerun the task to obtain cross-reference output.

SYMBOL TABLE SEARCH STACK OVERFLOW

Explanation:

This error is a CRF software error.

User Action:

Submit a Software Performance Report along with the
related console dialogue and any other pertinent information.

UNABLE TO OPEN WORKFILE

Explanation:
•
•

Possible causes are:

Workfile device not mounted.
Workfile device write protected.

The workf ile device is assigned to LUN
device from which CRF was installed~

User Action:

and

normally

the

Retry the command after ensuring that the device is
mounted and write-enabled.

D-7

CRF--THE RSX-11 CROSS-REFERENCE PROCESSOR
WORK FILE I/O ERROR
Explanation:
error while
causes are:
•
•

The Cross Reference Processor encountered an I/O
reading or writing data on its workfile. Possible

~."
.~

Device full.
Hardware error.

User Action: If the device capacity has been exceeded, delete
unnecessary files to make space available. Also, REASSIGN CRF
LUN7 to another Files-11 device.

D-8

111 2

;s::zu::

INDEX
Switches and Subswitches

I£- P\U automatically generated,
16-17
/[-);~U default value, 17-16
/[-],~U explanation, 17-16
I[-] ,~u form.at for setting
length-position, 17-17
/[-]AU in controlling audit
trail, 17-16
/[-J,1\.U in creating source files,
17-14
I [-] .1\U in deleting audit trail,
17-19
%ALL, 2-19
%AND, 2-17
%BEFORE, 2-17
%BEGIN, 2-15
%BUF:FER, 2-12, 2-17
%END, 2-15
%FOR, 2-17
%LAST, 2-15
%REST, 2-17
%THRU, 2-17
%WHOLE, 2-1.7
& (ampersand), EDI use of, 3-21,
3-30
*(asterisk), EDI use of, 3-8
/-AU, 17-14, 17-16 to 17-17
/-CO, 4-8
• • • (ellipsis) , EDI use of, 3-8
/20, 12-12, 12-20
/55, 12-12, 12-20
/80, 12-12, 12-21
: ALL,QUE, QUE/LI , 6-11
:ALLDEV, QUE/LI, 6-11
:DEV, QUE/LI, 6-11
: QUE. I 6-11
@YI 8-2
[EOB] I 2-11
/[NO]DELETE, PRINT, 6-8
/[NO]FLAG, PRINT, 6-5
/[NO]FLAG, QUE/MOD, 6-14
/[NO]RESTART, PRINT, 6-7, 6-14
/AB, 19-2 to 19-3
/AF'I ER:, PRINT, 6-4 to 6-5
/AF'I'ER:hh:mm, QUE/MOD, 6-14
AP, 11-8, 11-10
/AP, 4-10, 4-13
/APPEND, 10-13, 10-21
/APPEND, with REWIND, 10-21
/AS, 15-2
/ASSIGN, QUE, 7-11
/AU, 17-16, 17-17
/BA, 15-3
/BACKUP SE~r, 10-13 to 10-14
/BACKUP SE~[', used with DIRECTORY
to display files, 10-16
1

BAD, 8-1, 8-7, 11-8, 11-12
/BAD, 10-14
/BF, 17-16
BL, 11-8, 11-13 to 11-14
/BL, 12-6, 12-16, 15-3, 16-2
/BL:n, 5-6
/BL:N[.], 4-7, 4-11
/BO, 12-12, 12-21, 12-24
/BR, 4-10, 4-20 to 4-21, 4-24
/BRIEF, QUE, 6-10
/BS:n, 5-6
/BS:N[.], 4-7, 4-lo, 4-13 to 4-14
/BUFFERS, 10-14
/BY, 15-3
/CB, 16-2
/CD, 4-11, 4-14
/CM[:], default for, 17-16,
17-19
CMP, 11-8, 11-14 to 11-15
/CO, 4-7, 4-11, 5-6, 14-10, 16-2
/COMPARE, 10-14
/COPIES:n, PRINT, 6-8
/CR, 14-11
/CREATED, 10-15
/CS, 18-3, 18-7
/CS[:N], 17-3, 17-16
/CSR, 12-12, 12-21, 12-22
/DB, 17-16
DB:, 8-5
/DC, 15-4
/DE, 4-11, 4-14 to 4-15, 5-6,
5-10, 5-11, 13-4, 13-8, 14-12
/DEASSIGN, QUE, 7-11
/DELETE, QUE, 6-16 to 6-17
DENS, 8-2, 8-7
/DENS, 15-4
DENS=800:1600, 11-8, 11-15 to
11-16
/DENSITY, 10-15
/OF, 4-2, 4-11, 4-16, 14-13
/DG, 14-15
/DI, 5-7, 5-8, 5-10, 16-2
/DIRECTORY, 10-15
/DISPLAY, 10-16
DK:, 8-5
OM: I 8-5
/DNS:n, 5-7
/DO, 5-2, 5-3 to 5-4
DP:, 8-6
DR:, 8-6
DY:, 8-6
/EN, 4-4, 4-11, 4-16 to 4-17
/EOF[:BLOCK:BYTE] I 4-11, 4-17
to 4-19
/EP, 14-16
/ER, 12-11, 12-18

Index-1

INDEX
Switches and Subswitches
ERL, 8-2, 8-7
/ERRORS, 10-17
/EX, 14-17
/EXCLUDE, 10-17
/EXTEND, 10-17
/FA:n, 5-4 to 5-5
/FB:n, 5-5
/FC, 5-7
/FF, 16-2
/FI, 12-11, 12-14
/FI:FILENUM:SEQNUM, 4-11, 4-19
/FLAG, QUE/SPOOL, 7-3, 7-7, 7-10
/FO, 4-8, 4-10, 12-11, 12-21,
12-24
/FORM, QUE/SPOOL, 7-3, 7-7
/FORM:n, PRINT, 6-7
/FORM:, QUE/MOD, 6-14
/FR, 4-11, 4-19, 13-4, 13-8
/FU, 14-20
/FU[:N[.]], 4-11, 4-21 to 4-22
/FULL, QUE, 6-10
/GR[:RWED], 4-12, 4-26
/HD, 15-4
/HE, 12-10, 12-13
/HEADERS, 10-17
/HF, 15-4
/HOLD, QUE, 6-5
/HOLD, QUE/MOD, 6-14 to 6-15
/HX, 15-5
/ID, 4-9, 4-11, 4-20, 5-7, 5-8,
5-10
/IM, 12-11, 12-13, 12-16
/IM:n, 5-5
/IN, 14-18, 14-19
/INITIALIZE, 10-17
/INVOLUME, 10-17
/LB, 15-5
/LD, 4-11, 4-15, 4-28
/LE, 14-20
/LENGTH, 10-18
/LENGTH:n, PRINT, 6-7
/LENGTH:n, QUE/MOD, 6-14
/LI, 4-9, 4-11, 4-20 to 4-24,
5-7, 5-8, 5-10, 12-10,
12-13, 13-4, 13-9, 14-20,
16-2, 19-2, 19-3
/LIST, QUE, 6-9 to 6-13
/LN, 16-2
/LO, 13-4, 13-9
/LW, 15-5
MAN, 8-2, 8-7
/MAXIMUM, 10-18
/MB, 16-3
/MD, 15-5
/ME, 4-6, 4-11, 4-24
/MH, 14-21
/MODIFY, QUE, 6-13 to 6-14, 6-18
/MOUNTED, 10-18

/NEWVERSION, 10-19
/NM, 4-11, 4-24
/NOPRESERVE, 10-19
/NOINITIALIZE, 10-19
/NOSUPERSEDE, 10-19
/NV, 4-9, 4-11
/NV:n, 5-7, 5-12
/OUTVOLUME, 10-20
OVR, 8-2, 8-8
/OW[:RWED], 4-12, 4-26
/PE, 12-12, 12-20, 12-21
/POSITION, 10-20
/PR, 4-12, 4-25 to 4-27
· .PRINT subroutine, 6-7, 6-17
to 6-18
PRINT$ macro, 6-17 to 6-18
/PRIORITY:n, PRINT, 6-5
/PRIORITY:n, QUE/MOD, 6-14
/PROTECTION, 10-20
/PU[:N[.]), 4-12, 4-27 to 4-28
/RS, 15-5
/RC, 13-4, 13-9, 15-5
/RE, 6-7, 13-4, 13-10
PIP, 4-12, 4-28 to 4-30
/RELEASE, QUE, 6-15 to
6-16
/REVISED, 10-20
/REWIND, 10-21
/RM, 4-12, 4-30 to 4-31
/RO, 19-2 to 19-3
/RP, 14-22, 14-26
/RS, 5-2, 5-3 to 5-4
/RT, 5-2, 5-3 to 5-4
RW, 11-8, 11-16 to 11-18
/RW, 5-7, 12-11, 12-18, 12-19,
15-6
PIP, 4-12, 4-31 to 4-32
/SB, 4-12, 4-32
/SD, 4-12, 4-32 to 4-33
/SL, 16-3
/SP, 5-7, 14-27, 15-5, 16-3,
17-15, 17-16
/SP, PIP, 6-1
/SP [ :N [.]] , 4-12, 4-33 to
4-34
/SPOOL, QUE, 7-8 to 7-10
/SR, 4-12, 4-34
/SS, 14-28
/START, QUE, 7-6
/STOP, QUE, 7-5
/SU, 4-8 to 4-9, 4-11
/SUPERSEDE, 10-21
/SY[:RWED], 4-12, 4-26
/SZ, 14-29
/TAPE LABEL, 10-21
/TB, l6-3
PIP I 4-12, 4-22
/TIM, 12-12, 12-21, 12-24

Index-2

;t; I I\' i T

; 2 ;: 2

INDEX

Switches and Subswitches
/TM02, 12-12, 12-21, 12-23

/TP, 12-11, 12-13, 12-15
/TR, 17-8, 17-16
PIP, 4-12, 4-35
/UF, 4-12, 4-35 to 4-36
/UN, 4-12, 4-36 to 4-37
/UNI'I1 , 12-1~!, 1"2-21, 12-22
/UNSF 00L, QUE, 7 -10
/UP, 13-4, 13-11
PIP, 4-12v 4-37 to 4-38
/VB, 16-3
1

VE, 8-2, 11-8, 11-18
/VE, 5-7, 8-6, 12-11, 12-18,
12-19
/VEC, 12-12, 12-21, 12-23
/VERIFY, 10-21
/VI, 5-7

/WO, 15-5
/WINDOWS, 10-21
WLT, 8-2

/WO[:RWED], 4-12, 4-26
/ZE, 5-7, 5-10, 5-11 to 5-12

Index-3

,.
I

!iii

.I 22;; U

INDEX

A
Abbreviations of EDI commands,
3-9
ADD command, EDI, 3-10 to 3-11,
3-23, 3-27
ADD and PRINT command, EDI,
3-10, 3-12, 3-23, 3-27
Adding subroutines to an object
module, PAT, 18-5
Address modifications, PRESRV,
12-7
Address, PRESRV,
CSR, 12-7, 12-22
predefined, 12-7
vector, 12-7, 12-22
Addressing locations in a file,
ZAP, 19-3
Administrative switches, PRESRV,
12-11, 12-18
Allocating contiguous library
files, LBR, 14-11
Ampe!rsand character, EDI, 3-21,
3-30
ANSI,
tape labE:d format, BRU, 10-26
volume labels, BRU, 10-21,
10-26
AP command,, EDI, 3-10, 3-12,
3-23, 3-27
Append switch, 4-10, 4-13
ASCII mode switch, DMP, 15-2
ASCII strings, 1-6
Asseimbler,
Zll~P use with MACR0-11, 19-1
Aste!risks,
usage of, EDI, 3-8
Attribute,
setting selective search,
LBR, 14-28
Audit trail, 17-1 to 17-19
Audit trail, SLP,
changing value of, 17-17 to
17-18
comments, 17-6
delimiter for, 17-6
controlling of, 17-16
defaults, 17-2, 17-16, 17-19
deleting lines, 17-12
EDI command for, 17-12
deletion of, 17-16, 17-19
delimiters in, 17-6
e:>1:amples of use, 17-5
explanation of, 17-16
gemerated, automatically, 17-5,
17-17
generation of, 17-2, 17-16

Audit trail (Cont.)
listing file,
result from processing, 17-8
listing file, switch default
value, 17-16
reenabling of, 17-9, 17-18
replacing lines, 17-12
right justifying, 17-16
setting length, 17-16 to 17-17
showing updates, 17-3, 17-5
source files,
creating, 17-14
specification of, 17-6
suppression of, 17-1, 17-9,
17-16
switches, 17-1, 17-16
temporary suppression of, 17-18,
17-19
truncation, 17-8, 17-16
Automatic option, BRU,
BAD:, 10-23

B
Back up and restore, BRU,
selective, 10-3 to 10-5
to different size disks, 10-24
Back up commands, EDT, 2-1
Restore, 2-37
Save, 2-38
Back up set names, BRU,
and disk volume labels, 10-9
default, 10-13
input tape volume, 10-14
output tape volume, 10-14
specifying, 10-13
using directory to display,
10-15
Back up set, BRU, 10-27
Back-up and Restore Utility, 1-3
Bad Sector File,
manufacturer's, 9-3
BAD,
and indirect files, 9-2
BAD block data,
processing, 9-3
BAD messages, 9-8, 9-11
BAD sector file,
manufacturer's and software,
9-3, 9-4
BAD switches, 9-2
BAD utility,
using the, 9-4 to 9-5
BAD,
block zero,
use of, 9-4

Index-5

INDEX

BAD (Cont.)
command, INI, 9-4
default file specifications,
values for indirect, 9-2
descriptor entries,
format of, 9-3
descriptor,
maximum entries in, 9-5
devices,
non-last track, 9-3
error messages,
listing of, 9-8, 9-11
error,
device controller, 9-5
indirect files and, 9-2
invoking, 9-1
last-track devices, 9-3
non-last track devices, 9-3
stand-alone version,
devices supported by, 9-8
switches,
description of, 9-5 to 9-7
description, 9-5 to 9-7
list of, 9-2
manual and update, 9-6 to 9-7
stand-alone system version
only, 9-7 to 9-8
task and stand-alone, 9-6
task version, 9-1
verifying devices, 9-3
Base block address switch, DMP,
15-3
Basic commands, EDI,
summarized, 3-10
BEGIN command, EDI, 3-22, 3-27
Block buffer, EDI, 3-4
BLOCK command, EDI, 3-28
Block mode, EDI, 3-4
Block Size switch, PIP, 4-10,
4-13
Block Zero,
use of, 9-4
:Block, PRESRV,
bootstrap, 12-4, 12-5
label, 12-4, 12-5
Blocking factor, PRESRV,
default, 12-17
overriding default, 12-17
Blocking requirements, PRESRV, 12-25
Blocking switches, PRESRV,
12-13, 12-16
Blocks (to be dumped) switch,
DMP, 15-3
Blocks copied, PRESRV, 12-1
Blocks, VFY,
deleting multiply-allocated,
13-8
eliminating free, 13-8
recovering lost, 13-8

Blocksize, PIP,
switch, 4-7, 4-10, 4-13
Bootstrap block, PRESRV, 12.-4,
12-5
Bootstrap operation, PRESRV,
12-6
Bootstrap procedure, PRESRV,
12-6
Bootstrapping monitor, PRESRV,
12-24
BOTTOM command, EDI, 3-10,
3-12, 3-22, 3-28
BRU,
bad block file, 10-7
BAD utility, using with, 10-22
BAD: automatic option, 10-23
BAD: override option, 10-23
command line syntax, 10-10
command qualifiers, 10-2 to
10-21
continuation lines, 10-12 to
10-13
core image file, 10-8
error messages, 10-28
file creation dates, 10-25
manual option,
BAD:, 10-23
override option,
BAD:, 10-23
prompts, 10-10
tape format, 10-26
tape operations,
multivolume, 10-27
volume labels,
ANSI, 10-21, 10-26
disk, 10-9, 10-14
disk default, 10-20
disk input, 10-17
disk output, 10-20
tape, 10-21
volumes,
existing, 10-24
backing up from mounted,
10-18
restoring to mounted, 10-19
Buffer requirements, 12-6,
12-25
Buffer,
EDI block, 3-4
Buffers, EDT,
alternate, 2-12
copying files into, 2-26
creating, 2-12
current, 2-12
deleting lines from, 2-23
displaying status of, 2-40
inserting lines into, 2-28
MAIN, 2-11
naming, 2-12

Index-6

INDEX

Buffers, EDT (Cont.)
recreating contents of, 2-37
replacing lines in, 2-34
saving contents of, 2-12,
2-32, 2-38, 2-45
specification of, 2-11
Byte (octal format) switch,
DMP, 15-3

c
Capacity loss, PRESRV,
disk, 12-·2
Carriage return,
EDI usage, 3-8, 3-11, 3-19,
3-42
CC conunand, EDI, 3-21, 3-29
CD conunand, EDI, 3-26, 3-29
CHANGE command, EDI, 3-10,
3-13, 3-23, 3-28
Change, EDT, 2-21
Character mode, EDT, 2-1, 2-48
invoking, 2-21, 2-48
terminating, 2-59
Checksum processing in PAT, 18-7
Checksum, SLP,
calculation of, 17-3, 17-16
/CS[:n], 17-3, 17-16
me~ssages v 17-16
switchesv
allowing, 17-15
CLI, QUE, 7-1
CLOSE and DELETE conunand, EDI,
3-26, 3-29
CLOSE and BXIT conunands, EDI,
sununary, 3-2 5
CLOSE conunand, EDI, 3-26, 3-28
CLOSE SECONDARY conunand, EDI,
3-26, 3-29
CLOSES command, EDI, 3-26, 3-29
CMP,
conunand format, 16-1
comparing ASCII text files,
16-1
controlling comparison of,
blank lines, 16-2
comments, 16-2
form fE:~eds, 16-2
trailing blanks, 16-3
denoting differences, 16-2
formats,
change bar, 16-5
differences, 16-4
output file, 16-4
SLP command input, 16-6
generating input for SLP
with, 16-3
invoking, 16-2

Index-7

CMP (Cont.)
listing differences in files
with, 16-1
messages, 16-6
numbering lines, 16-2
printing differences, 16-2
specifying change bar format,
16-3
specifying number of lines
for a match, 16-2
spooling output, 16-3
switches, 16-2 to 16-3
default settings, 16-3
Codes,
PIP protection, 5-12
Combining LBR functions, 14-31
Conunand conventions, EDI, 3-8
Conunand files,
using indirect, 1-9
Conunand ·format,
for CMP, 16-1
for DSC, 11-7
for FLX, 5-2
defaults, 5-2 to 5-3
for PAT, 18-2
for ZAP, 19-2
Conunand functions for PIP, 4-5
Conunand line for ZAP,
separators sununarized, 19-7
Conunand line format, PRESRV,
12-10
Conunand line interpreter (CLI),
QUE, 7-1
Conunand line syntax., BRU, 10-10
Conunand lines,
entering for RSX-11, 1-4
entering, 1-4 to 1-5
Conunand Mode, EDT, 2-1
conunand descriptions, 2-20
conunands,
sununary of, 2-60
prompts, 2-2, 2-3
Conunand qualifiers, BRU,
10-2 to 10-21
Conunand string,
EDT, 2-4
options, 2-19
PIP, 4-1
Conunands,
device output sununary, EDI,
3-26
EDT,
abbreviating, 2-20
back up, 2-1
Change, 2-21, 2-48, 2-50,
2-53
Character Mode.
See Subconunands
Copy, 2-22

INDEX

Commands (Cont.)
Delete, 2-23
Execute, 2-46
executing sequence of, 2-46
Exit, 2-25
Find, 2-25
I/O, 2-1
Include, 2-26
Insert, 2-28
Move, 2-30
options to, 2-19
Print, 2-32
Quit, 2-33
Replace, 2-34
Resequence, 2-35
Restore, 2-37
Save, 2-38
Set, 2-38
Show, 2-40
Substitute, 2-42
summarized, 2-5 to 2-10, 2-60
Type, 2-25, 2-44
Write, 2-45
entering interactively, SLP,
edit commands, 17-7 to 17-8
input, 17-2
functionally arranged summary
of, EDI, 3-20
line pointer control, EDI,
3-21
lines, SLP,
add to, 17-11
delete from, 17-12
replace, 17-13
macro,
summary of, EDI, 3-24
QUE, 6-2
SLP edit, 17-2, 17-8
terminating edit sessions,
17-10
text modification, EDI, 3-23
ZAP,
carriage return, 19-6
general-purpose, 19-5
location, open/close, 19-5
Comparing files, CMP,
ASCII text, 16-1
controlling comparisons in,
16-2 to 16-3
Compress switch, LBR, 14-10
Compressing LBR files, 14-10
Concatenation character,
command, EDI, 3-21, 3-29
Continuation lines, BRU, 10-12
to 10-13
on RSX-llM, 10-12
on RSX-llM-PLUS, 10-13
Control functions, PIP,
performing, 4-9

Control modes, EDI, 3-3
Copy formats, PRESRV, 12-1
Copy,
EDT, 2-22
PRESRV,
DECTAPE, 12-2, 12-3
disk, 12-2, 12-3
image, 12-2 to 12-3, 12-27
logical tape, 12-2 to 12-3
Core image file, BRU, 10-8
Create switch, LBR, 14-11
Creation dates, BRU, file,
10-25
CSR addresses, PRESRV, 12-7,
12-22
CSR modification, PRESRV, 12-22
CTRL/U, EDI, 3-7
CTRL/Z, EDI, 3-8, 3-10, 3-13,
3-26, 3-30
Current buffer, EDT, 2-12
Current line, EDT, 2-12
Cursor, EDT,
moving, 2-49, 2-55

D
Data transfer, DSC,
compare operation, 11-3
copy distribution, 11-2
from disk, 11-23
from tape, 11-25
to disk, 11-25 to 11-26
to tape, 11-23 to 11-24
DB: devic~s, FMT, 8-5
DCL, 1-8
invoking, 1-8
invoking utility from, 1-8
returning control, 1-8
Decimal (word format) switch,
DMP, 15-3
DECTAPE copy, PRESRV, 12-2 to
12-3
DECTAPE operating procedures,
PRESRV, 12-9
Default blocking factor,
PRESRV,
overriding, 12-17
Default formats, PRESRV, 12-17
Default switch, LBR, 14-13
Default,
EDI,
file specifications, 3-2
LBR,
file specifications, 14-2
library filetype, 14-12
PIP,
switch, 4-11, 4-15
utility file specification,
1-6

··~
Index-8

INDEX

Def a.ult (Ccmt.)
va.lues for indirect command
files, 1-10
va.lues for BAD indirect file
specifications, 9-2
VF'Y,
file specifications, 13-3
Defaults,
EDT file specification, 2-3
FI,X,
command line, 5-2 to 5-3
direction transfer, 5-4
directory entries, 5-12
file blocksize for
cassettes, 5-13
file names,
paper tape, 5-16
Files-11 volumes, 5-2
format transfers,
paper tape, 5-16
switches, 5-3 to 5-5
volume formats, 5-3 to 5-4
PIP,
element specifications,
4-1 to 4-2
new value, 4-2
rules summarized, 4-2
DELBTE and PRINT command, EDI,
3-10, 3-14, 3-23, 3-30
DELl~TE command, EDI, 3-10, 3-13,
3-23, 3-30
Delete global switch, LBR,
14-15
DELl~TE key, EDT,
use of, 2-53
DelE~te switch,
LBR, 14-12
Vl?Y, 13-8
Delete, EDT, 2-23
Delete files, FLX,
/DE, 5-6
Deleting files, FLX,
DOS-11, 5-10
R~r-11, 5-11
Del1eting,
EDI,
lines from files, 3-30
L:BR,
entry point from Entry
Point Table, 14-12
from library files, 14-12
global symbols from an
Entry Point Table, 14-12
library modules, 14-12
logica.lly deleted records,
14-10
VFY,
files marked-for-delete, 13-6
multiply allocated blocks,
13-7

Delimiters,
EDT,
string search, 2-14, 2-56
Substitute command, 2-42
Substitute subcommand, 2-55
SLP,
audit trail, 17-6
comment, 17-3
initial audit trail, 17-6
redefining of, 17-6
Description,
switches, BAD, 9-5 to 9-7
Descriptor entries,
format of, BAD, 9-3
Despool prototype task, QUE,
7-1
Despooling,
defined, 6-1
Dev:, 1-5
Device controller errors, BAD,
9-5
Device mode, DMP, 15-1
Device output commands, EDI,
3-25
Device specification, 1-5
Device status, DSC, 11-6
Device supported by standalone version, BAD, 9-8
Device types, PRESRV, 12-1
Device, PRESRV,
speci~ication of, 12-10
verifying, 9-3
Qevice-specific queues, 6-4
Devices supported by BRU, 10-9
to 10-10
Devices,
BRU,
last-track, 10-22
non last-track, 10-22
FLX, 5-1 to 5-2
DOS-11, 5-1
Files-11, 5-2
RT-11, 5-2
non-last track, BAD, 9-3
specification of, PRESRV,
12-10
Diagnostic support, FMT, 8-1
Differences, CMP,
format, 16-4
listing, CMP, 16-1
Directories, FLX,
/DI, 5-7
DOS-11, 5-8
/LI, 5-7
RT-11, 5-10
Directory Manipulation, FLX,
DOS-11 volumes, 5-8
initializing volumes, 5-10
deleting files, 5-10

Index-9

INDEX

Directory Manipulation (Cont.)
displaying directory
listings, 5-8 to 5-9
mounting, 5-8
RT-11,
deleting, 5-11
displaying directory
listings, 5-10
initializing, 5-11 to 5-12
mounting, 5-8
specifying extra words per
disk entry, 5-12
volumes, 5-10
Disk capacity loss, PRESRV, 12-2
Disk copy, PRESRV, 12-2 to 12-3
Disk formatting, PRESRV, 12-24
to 12-25
Disk operating procedures,
PRESRV, 12-9
Disk Save and Compress, 1-3
Disk Volume Formatter, see FMT
Disks, BRU,
different sizes, 10-24, 10-25
initialization of, 10-8,
10-23 to 10-24
initializing using, 10-8, 10-23
DK: devices, FMT, 8-5
DM: devices, FMT, 8-5 to 8-6
DMP (File Dump Utility)
error messages, 15-6
identify current version of,
15-5
switches, 15-2 to 15-6
DP command, EDI, 3-10, 3-14,
3-23·, 3-30
DP: devices, FMT, 8-6
DR: devices, FMT, 8-6
DSC,
operation, 11-1 to 11-23
disk to disk, 11-1
disk to tape, 11-1
tape to disk, 11-1
.switches,
append, 11-8, 11-10
bad block man:noauto, 11-11
bad block noauto, 11-11
bad block, 11-8, 11-10,
11-12
block factor, 11-13
compare, 11-14
control status reg., 11-20
density, 11-15 to 11-16
rewind, 11-16 to 11-18
system-dependency for, 11-14
system-limits for, 11-14
TM02, 11-21
unit, 11-22
using format, 11-13
vector address, 11-22
verify, 11-18 to 11-19

Dumps, DMP,
hexadecimal format, 15-5 to
15-6
numbering lines in, 15-5
one record at a time, 15-5
RADIX-SO format, 15-5

E
EDI (Line Text Editor),
basic commands,
summarized, 3-10
block buffer, 3-4
carriage return,
use of, 3-8
CLOSE and EXIT commands
summary, 3-25
CLOSE commands, 3-28
command abbreviations, 3-9
command conventions, 3-8
commands,
ADD, 3-10 to 3-11, 3-23,
3-27
ADD and PRINT, 3-10, 3-12,
3-23, 3-27
AP, 3-10, 3-12, 3-23, 3-27
BEGIN, 3-22, 3-27
BLOCK, 3-28
BOTTOM, 3-10, 3-12, 3-22,
3-28
cc' 3-21, 3-29
CD , 3-2 6 , 3 - 2 9
CHANGE, 3-10, 3-13, 3-23,
3-28
CLOSE and DELETE, 3-26,
3-29
CLOSE SECONDARY, 3-26, 3-29
CLOSE, 3-26, 2-28
CLOSES, 3-26, 3-29
CONCATENATION CHARACTER,
3-21, 3-29
DELETE and PRINT, 3-10,
3-14, 3-23, 3-30
DELETE, 3-10, 3-13, 3-30
DP, 3-10, 3-14, 3-23, 3-30
ED, 3-32
END, 3-31
ERASE, 3-23, 3-31
escape-key, 3-10, 3-14,
3-31
EXIT and DELETE, 3-26, 3-32
EXIT, 3-10, 3-15, 3-26, 3-31
FF I 3-5' 3-33
FILE, 3-25, 3-32
FIND, 3-22, 3-32
FORM FEED, 3-23, 3-33
INSERT, 3-3, 3-10, 3-15,
3-23, 3-33
KILL, 3-26, 3-33

Index-10

INDEX

'-''

EDI (Line Text Editor} (Cont.)
LC, 3-34
LI, 3-35
LINE CHANGE, 3-23, 3-34
LIST ON PSEUDO-DEVICE, 3-26,
3-35
LIST ON TERMINAL, 3-26, 3-34
LOCATE, 3-10, 3-15, 3-22,
3-35
LP, 3-35
M, 3-36
MACRO CALL, 3-24, 3-36
MACRO BXECUTE, 3-24, 3-37
MACRO IMMEDIATE, 3-24, 3-37
MACRO, 3-35
MC, 3-36
NEXT and PRINT, 3-11, 3-16,
3-22, 3-38
NEXT, 3-11, 3-16, 3-22,
3-38
NP, 3-11, 3-22, 3-38
OPEN SBCONDARY, 3-21, 3-38
OPENS, 3-38
OUTPUT ON/OFF, 3-21, 3-39
OVERLAY, 3-23, 3-38
PAGE FIND, 3-5, 3-22, 3-40
PAGE LOCATE, 3-5, 3-22, 3-41
PAGE, 3-5, 3-22, 3-40
PASTE, 3-24, 3-41
PF, 3-40
PL, 3-41
PRINT, 3-11, 3-17, 3-26,
3-41
READ, 3-5 to 3-6, 3-25,
3-42
RENEW, 3-5 to 3-6, 3-11,
3-18, 3-25, 3-42
RETURN·-KEY, 3-11, 3-42
RETYPE, 3-11, 3-19, 3-24,
3-43
SAVE, 3-25, 3-43
SC, 3-44
SEARCH and CHANGE, 3-22,
3-44
SELECT PRIMARY, 3-21, 3-44
SELECT SECONDARY, 3-21,
3-45
SIZE, 3-21, 3-45
SP, 3-44
SS, 3-45
TAB, 3·-21, 3-45
TOF, 3-4, 3-20, 3-24, 3-46
TOP OF FILE, 3-11, 3-20,
3-24, 3-46
TOP, 3-4, 3-11, 3-19, 3-46
TYPE, 3-26, 3-47
UC, 3-47
UNSAVE, 3-24, 3-47

EDI {Line Text Editor) {Cont.)
UPPER CASE, 3-21, 3-47
VERIFY ON/OFF, 3-21, 3-48
WRITE, 3-25, 3-49
control modes, 3-3
CTRL/Z, 3-10
device output commands
summary, 3-26
ellipsis,
use of, 3-8
entering file specifications,
3-2
error messages, 3-50
functionally arranged summary
of commands, 3-20
line pointer control commands,
3-21
macro commands summary, 3-24
terminal conventions, 3-7
text modification commands,
3-23
usage notes, 3-49
use of asterisks, 3-8
Edit command statement, SLP,
adding lines format, 17-11
as command input, 17-2
calculating checksum for,
17-3
comments in, 17-12
creating source files format,
17-14
deleting lines format, 17-12
fields, 17-6 to 17-7
first character, 17-9
general format, 17-6
locator forms, 17-6 to 17-7
replacing lines format, 17-13
specification of, 17-5
Edit mode, EDI, 3-3
Editing,
utilities for, 1-1 to 1-2
Editor,
oreating source files with
. SLP, 17-14
DEC standard, 1-2
line text, 1-2
EDT,
command descriptions, 2-20
command string, 2-4
command summary, 2-5 to 2-10,
2-60
displaying version number of,
2-40
error messages, 2-62
error reporting, 2-62
invoking, 2-2
options, 2-19

Index-11

INDEX

EDT (Cont.)
summarized, 2-1
terminating, 2-25, 2-33
Element, LBR,
in an Entry Point Table, 14-4
Eliminating free blocks, VFY,
13-7
Ellipsis,
EDI usage, 3-8
End of file switch, 4-11, 4-17
to 4-19
END conunand, EDI, 3-31
Enter, switch, 4-4, 4-11, 4-16
to 4-17
Entries,
maximum in descriptor, 9-5
Entry point switch, LBR, 14-16
Entry point table, LBR,
deleting an element of, 14-15
excluding an entry, 14-16
including an entry, 14-16
ERASE conunand, EDI, 3-23, 3-31
Erasing a line, EDI, 3-7
Error codes, PIP, 4-47
EI.·ror messages,
BRU, 10-28
CMP, 16-6
DMP, 15-6
EDI, 3-50
EDT, 2-62
FLX, 5-16
LBR, 14-33
listing of BAD, 9-8, 9-11
PAT, 18-7
PIP, 4-38
PRESRV, 12-27
PRI, 6-18 to 6-23
QUE, 6-18 to 6-23
Queue Manager, 7-11
VFY, 13-11
ZAP, 19-16
Error reporting,
VFY validity check, 13-4
EI.·:ror,
device controller, 9-5
DSC,
code, 11-41
fatal hardware, 11-40
on device, parity, 11-41
Escape key, EDI, 3-10, 3-14,
3-31
EXIT and DELETE conunand, EDI,
3-26, 3-32
EXIT command, EDI, 3-10, 3-15,
3-26, 3-31
Exit, EDT, 2-25
Extract a module from a library
file, LBR, 14-13

Extract swi~ch, LBR, 14-17

F
FCS (File Control Services),
6-17 to 6-18
FF conunand, EDI, 3-5, 3-33
File Compare utility, 1-4
File Control Services (FCS),
6-17 to 6-18
File creation dates, BRU, 10-25
File Dump utility, 1-4
File flag pages, QUE, 6-5
File headers, BRU, 10-25
File identification, VFY,
listing, 13-9
File label, PRESRV,
specification of, 12-8 to
12-10
File labels, DSC, 11-8, 11-9
switches/options, 11-8
File manipulation utilities, 1-1
File mode, DMP, 15-1
File name requirement, PRESRV,
12-2
File name, PRESRV, 12-2
File names, FLX,
cassettes, 5-13
paper tape, 5-16
File specifications,
BRU,
conflicting, 10-5
on conunand line, 10-12
wildcards in, 10-12
EDI,
defaults, 3-2
entering, 3-2
File Spooling utilities, 1-1
File Structure Verification
utility, 1-4
File synonyms, BRU, 10-25
File type specification, 1-5
separation of, 1-6
FILE conunand, EDI, 3-25, 3-32
File,
creation dates, BRU, 10-25
examining contents of, 19-10
modifying contents of a, ZAP,
19-11
ownership switch, PIP, 4-8,
4-10 to 4-13, 4-37
storage bit map, BRU, 10-7
verifying contents of a task
image with ZAP, 19-15
File-ids, BRU,
preservation, 10-19, 10-25
File-related switches, QUE, 6-8

Index-12

~!£!4tl

& I

INDEX

'-''

Files,
BRU,
preservation of creation
dates, 10-25 to 10-26
lost, 10-26
:synonyms, 10-25
EDT,
creating using, 2-1, 2-4,
2-25, 2-32, 2-45
editing, 2-1, 2-4
input, 2-2
output, 2-2
SAVE command, created by,
2-38
LB:R,
compressing, 14-10
library, format of, 14-1
PRESRV I
:multivolume, 12-8
SLP,
adding lines to, 17-11
deleting lines from, 17-12
indirect command, 17-1 to
17-2
initialization of, 17-2
input, 17-1 to 17-2
output, 17-1 to 17-3,
17-8 to 17-9
processing of, 17-4 to 17-5,
17-9 to 17-10
replacing lines in, 17-13
source, 17-1 to 17-2,
17-10 I 17-14
specifying in command line,
17-7
swi tche!s, 17-1
variable-length records in,
17-14
VF'Y,
ensuring readability, 13-10
lost, rebuilding, 13-11
lost, recovering, 13-8
Fileis-11 format, PRESRV, 12-1,
12-9 to 12-10, 12-13 to 12-14
Fileis-11 structures, BRU, 10-7
Fileis-11 files,
copying, 4-5
Filespec, (lUE, 6-7 to 6-8
FIND command, EDI, 3-22, 3-32
Find, EDT, 2-25
FMT messagE~s, 8-8 to 8-12
command :r/o error, 8-9
command too long, 8-9
device driver missing, 8-9
de~vice not in system, 8-9
device not ready, 8-9
device offline, 8-9
device write locked, 8-9

FMT messages (Cont.)
device-unsupported formatting,
8-9
disk as alignment cartridge,
8-10
error limit exceeded, 8-10
error reading data, 8-10
error reading header, 8-10
failed to attach device, 8-11
failed to read manufacturer's
bad sector file, 8-11
fatal hardware error, 8-11
header compare error, 8-11
invalid switch, 8-11
manufacturer's bad sector file
corrupt, 8-11
marked bad in manufacturer's
bad sector file, 8-11
privilege violation, 8-12
response out of range, 8-12
setting diskette density, 8-10
syntax error, 8-12
unable to run bad block
utility, 8-12
unrecoverable error-n, 8-12
writing data, 8-10
writi~g header, 8-10
FMT,
switches, 8-1, 8-2, 8-4, 8-6
to 8-8
utility,
using with BRU, 10-22
f,orm definitions, 7-9
FORM FEED command, EDI, 3-23,
3-33
Form, QUE/SPOOL, 7-8 to 7-9
Form feE;?d, EDI,
as t~xt page delimiter, 3-5
Format'of library files, LBR,
14-4
Format switches, PRESRV, 12-13
Format,
entering file specifications,
1-5
FLX, 5-1 to 5-13
cassette, 5-13
command line, 5-2
defaults for volume, 5-3 to
5-4
switches for volume, 5-3
PRESRV,
command line, 12-10
files-11, 12-1, 12-9 to
12-11, 12-13 to 12-14
image mode, 12-1, 12-11,
12-14
image, 12-3, 12-9 to 12-10,
12-13

Index-13

INDEX

Format (Cont.)
logical tape, 12-1 to 12-2,
12-5, 12-8, 12-11, 12-13,
12-15
Formats, ZAP,
location specifier, 19-8
Formatter,
disk volume, 1-3
Formatting,
FLX, 5-1 to 5-11
DOS-11 volume, 5-10
Files-11 volume, 5-3
RT-11 volume, 5-11
switches for, 5-3
volume, 5-3 to 5-4
PRESRV,
disk, 12-24 to 12-25
Free blocks, VFY,
eliminating, 13-8
Free storage, VFY,
displaying, 13-9
Free switch, VFY, 13-9
Full description listing switch,
LBR, 14-20
Functions,
FLX, 5-1
LBR,
combining, 14-31
SLP, 17-1
adding lines, 17-11
audit-trail processing,
17-9
deleting lines, 17-12
invoking indirect command
files, 17-9
replacing lines, 17-18
returning to command mode,
17-9
switches, 17-16
terminating edit session,
17-9, 17-15

G
General tasks, FMT, 8-1
Global symbols, LBR,
deleting from LBR Entry Point
Table, 14-12
deleting from library files,
14-12

H
Header switch, DMP, 15-4
Header, LBR,
library, 14-4, 14-7
Hexadecimal switch, DMP,
byte format, 15-4
double word format, 15-5
word format, 15-5

Identify switch, DMP, 15-5
Image copy, PRESRV, 12-2 to
12-3, 12-27
Image format, PRESRV, 12-3,
12-9 to 12-10, 12-13
Image mode format, PRESRV, 12-1,
12-11, 12-14
Image, PRESRV, 12-3
Include, EDT, 2-26
Index file, BRU, 10-7, 10-9,
10-20
Indirect command files,
FLX, 5-2
SLP,
edit commands, entering,
17-7, 17-8
file specification, 17-9
for edit commands, 17-2
invoking, 17-9
nesting (maximum level),
17-9
using, 1-9 to 1-10
INI command, 9-4
Initializing disks using BRU,
10-8, 10-23
Initializing volumes, FLX, 5-2,
5-8, 5-12
Initializing volumes, FLX,
DOS-11, 5-10
RT-11, 5-11 to 5-12
Initializing, LBR,
entry point table, 14-11
library file header, 14-11
library files, 14-11
module name table, 14-11
Initiating and terminating FMT,
8-1
Input file, EDI,
primary, 3-6
Input mode, EDI, 3-3
Input parameters, DSC, 11-7
Input Program,
Source Language, 1-4
Input,
PRESRV,
logical tape, 12-8
tape, 12-9
SLP, 17-1 to 17-2
commands, 17-1 to 17-2
file, 17-1 to 17-2
Input/output commands, EDI,
summary, 3-25
INSERT command, EDI, 3-3, 3-10,
3-15, 3-23, 3-33
Insert, EDT, 2-28
Installed utilities,
invoking, 1-7

Index-14

INDEX

Installed Utilities (Cont.)
passing control to, 1-8
returning control to DCL, 1-8
returning control to MCR, 1-8
using indirect command files
with, l·-9
Invoking BAD, 9-1
Invoking installed utilities,
JL-7

from DCL, 1-8
from MCR, 1-8
Invoking RSX-11 utilities, 1-6
from DCL, 1-6
from MCR, 1-6
Invoking uninstalled utilities,
JL-9

J
Job j:lag pages, QUE, 6-5
Job name, QUE, 6-15 to 6-17
Job names, 6-4
QUE, 6-4
Job-related switches, QUE,
6-4

K
Keyp<;i.d arrows , EDT,
USE:! Of 1 2-57
KILL command, EDI, 3-26, 3-33

L
Label block, PRESRV, 12-4 to 12-5
Last·.. track devices, BAD, 9-3
LBR Entry Point Table,
including an entry in an,
14-16
LBR,
default file specification
•alements, 14-2
error messages, 14-33
filetype, 14-12
functions,
combining, 14-31
restrictions, 14-32
switches, 14-3 to 14-4,
14-10 to 14-13
LC command, EDI, 3-34
Leader format switch, DMP, 15-4
LI command, EDI, 3-35
Librarian Utility Program, 1-4
Library Entry Point Table, 14-4
Library file, LBR,
inserting modules in a, 14-18
Library files,
allocating, 14-11
compressing, 14-10

Library files (Cont.)
deleting global symbols from,
14-12
entry points,
listing, 14-20
extracting a module, 14-13
format of, 14-4
full description and listing
of module, 14-20
initializing, 14-11
inserting module, 14-9, 14-18
listing module and entry points
in, 14-16
listing modules in, 14-20
macro and object, 14-1,
14-5, 14-20
replacing module in, 14-26
squeezing, 14-29
.
universal, 14-1, 14-5, 14-21
Library header, LBR, 14-5
contents, 14-7
Library module, LBR,
deleting, 14-13
Line numbers, EDT, 2-13
default, 2-13
reassigning, 2-35
sequencing, 2-13
Line pointer control commands,
EDI, 3-21
Line pointer, EDT,
moving, 2-25
LINE CHANGE command, EDI, 3-23,
3-34
Line, EDT,
current, 2-12
definition of, 2-50
Line-by-line mode, EDI, 3-4
Lines,
DMP,
numbering in a dump, 15-5
EDT,
changing characters in, 2-42
deleting, 2-23
displaying, 2-44
inserting, 2-28
replacing, 2-34
transferring, 2-22, 2-30
LIST switch, VFY, 13-9
List entry points switch, LBR,
14-20
List switches,
LBR, 14-20
PRESRV, 12-10, 12-13
LIST ON PSEUDO DEVICE command,
EDI, 3-26, 3-34
LIST ON TERMINAL command, EDI,
3-26, 3-34
Listing files, LBR,
spooling, 14-27

Index-15

INDEX

LOCATE command, EDI, 3-10,
3-15, 3-22, 3-35
Locating, VFY,
lost files, 13-9
Locator commands, EDI,
summarized, 3-21
I,ocator,
bad block, 1-3
Locators, SLP, 17-1, 17-6 to
17-7, 17-13
Logical block switch, DMP, 15-5
Logical tape copy, PRESRV, 12-2
to 12-3
Logical tape format, PRESRV,
12-1 to 12-2, 12-5, 12-8,
12-11, 12-13, 12-15
Logical tape input, PRESRV,
12-8
Logical tape output, PRESRV,
12-8
Lost files switch, VFY, 13-10
Lost blocks, VFY,
recovering, 13-8
Lost files,
handling with BRU, 10-26
LPP, QUE, 7-1

M
command, EDI, 3-36
.MAC file type, LBR, 14-13
.MACRO CALL command, ED I , 3-2 4 ,
3-36
:MACRO command , ED I , 3-3 5
:MACRO EXECUTE command, EDI,
3-24, 3-37
MACRO IMMEDIATE command, EDI,
3-24, 3-37
Magnetic tape switches, PRESRV,
12-12, 12-20
Manager,
Queue, 1-3
Manual and update switches, 9-6
to 9-7
Manual operating mode, FMT, 8-3
to 8-4
Manual option, BRU,
BAD:, 10-23
Marked-for-delete indicator,
VFY,
resetting, 13-8
Marked-for-delete,
VFY files, 13-6
Master file directory, BRU, 10-7
MC command, EDI, 3-36
MCR MOUNT command, DMP, 15-1
MCR,
invoking utilities from and
returning control to, 1-8
.M

MCR (Cont.)
MOUNT/FOREIGN command,
use of with DMP, 15-1
Memory dump switch, DMP, 15-5
Messages~ See also Error messages
DSC; 11-26 to 11-39
corrective action for, 11-27
to 11-39
explanation of, 11-27 to
11-39
I/O, 11-39 to 11-41
specified unit number
exceeds max. of 1, 11-42
stand-alone, 11-41 to 11-42
text of, 11-27 to 11-39
error,
BRU, 10-28
DMP, 15-6
LBR, 14-33
PRESRV, 12-27
Queue Manager, 7-11
VFY, 13-11
FMT, 8-8 to 8-12
SLP,
checksum, 17-3
diagnostic error (/CS), 17-3
error, 17-20 to 17-24
general information on, 17-19
information, 17-20
MLB file type, LBR, 14-13
Mode,
DMP,
device, 15-1
file, 15-1
EDI,
block, 3-4
edit, 3-3
input, 3-3
line-by-line, 3-4
Modes,
EDI,
control, 3-3
text access, 3-3
SLP, 17-2
command, 17-2, 17-8
edit, 17-2, 17-8
returning to command, 17-9
ZAP,
absolute addressing, 19-3
addressing, 19-3
default addressing, 19-3
read-only, 19-3
switches for specifying,
19-2
task image addressing, 19-4
Modification, PRESRV,
address, 12-27
CSR, 12-22

Index-16

a..•n•t•••

'·~r. ." ". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

INDEX

ModHied PRJ~SRV,
bootstrapping, 12-7
. version of, 12-7
Modify headE~r switch, LBR, 14-21
Module headE~r, LBR,
library, 14-5
Module name table, LBR,
library, JL4-5
Module, LBR.,
deleting, 14-12
listing, 14-20
Monitor, PRBSRV,
bootstrapping, 12-24
MOUN'I' FOREIGN command, MCR,
USE! with DMP, 15-1
MOUN'I' command, MCR,
use1 with DMP, 15-1
Move, EDT, 2-30
Multi.file volumes, PRESRV, 12-8
Multi.ply-allocated blocks, VFY,
deleting via, 13-8
Multi.volume files, PRESRV, 12-8
Multi.volume tape operations,
BRU, 10-·27

N
NEXT AND PRINT command, EDI,
3-11, 3-16, 3-22, 3-38
NEXT command, EDI,. 3-11, 3-16,
3-22, 3-·38
No Message switch, PIP, 4-11,
4-24
Normal operating mode, FMT, 8-2
to 8-3
NP command, EDI, 3-11, 3-22,
3-38
Numbering lines in a dump, DMP,
15-5

0
OBJ file type, LBR, 14-13
Object and macro libraries,
insert switch for, LBR, 14-18
Object modules, PAT,
adding subroutines to, 18-5
overlaying lines in, 18-4
patching, 18-1
validating contents of, 18-7
ODT, ZAP,
use with, 19-1
OLB file type, LBR, 14-13
Online, DSC,
initiating, 11-6
terminating, 11-6
OPEN SECONDARY command, EDI, 3-21,
3-38
OPENS command, EDI, 3-38

Operating modes, FMT,
manual, 8-3 to 8-4
normal, 8-2 to 8-3
Operating procedures, PRESRV,
12-3
DECTAPE, 12-9
disk, 12-9
tape, 12-9
Operation overview, DSC, 11-19
Operators,
SLP, 17-9
backslash (\), 17-18 to
17-19
functions of, 17-9
percent sign (%) addressing
audit trail, 17-18 to
17-19
ZAP, 19-6 to 19-7
Options, EDT, 2-4, 2-19, 2-20
Output despooler, QUE, 7-2
Output device, QUE, 6-10
Output file, EDT, 2-2
creating, 2-2, 2-25
renaming, 2-25
Output files, SLP, 17-1 to 17-2
double space format for listing
(/DB) , 17-16
listing, 17-1 to 17-3, 17-8
to 17-10
updated input, 17-2 to 17-3
Output parameters, DSC, 11-7
Output spooling, QUE, 6-17 to
6-18
OUTPUT ON/OFF command, EDI,
3-21, 3-39
Output, PRESRV,
logical tape, 12-8
tape, 12-9
OVERLAY command, EDI, 3-23, 3-39
Overlaying lines, PAT,
in an object module, 18-4
Overlaying segments, ZAP,
changing locations in, 19-4
displaying boundaries of, 19-2
Override option, BRU,
BAD:, 10-23
Overriding default blocking
factor, PRESRV, 12-17

p
Page, EDI,
text defined, 3-5
Page length, QUE, 6-7
PAGE command, EDI, 3-5, 3-22,
3-40
PAGE FIND command, EDI, 3-5,
3-22, 3-40

Index-17

INDEX

PAGE LOCATE command, EDI, 3-5,
3-22, 3-41
Pages of text, EDI,
processing, 3-5
Paper tape support, FLX, 5-15
to 5-16
default for input, 5-16
defaults,
format transfer, 5-15
file names, 5-16
transfer mode switches, 5-15
transferring between, 5-16
Parameters, EDT,
Case, 2-39
displaying, 2-40
establishing, 2-38
Exact, 2-39, 2-57
Terminal, 2-39, 2-49
PASTE command, EDI, 3-24, 3-41
PAT, (Object Module Patch
Program), 18-1 to 18-13
adding subroutines to a
module,
example of, 18-5
checksum processing,
examples of, 18-7
command format, 18-2
command line error, 18-8
correction file, 18-3
errors,
command line, 18-8
file specification, 18-9
format, file content, 18-12
input/output, 18-11
internal software, 18-13
storage allocation, 18-13
files,
validating contents of, 18-7
global symbols,
processing of, 18-4
indirect command files, 18-1
information, 18-8
input file, 18-3
input to, 18-1
invoking, 18-1
MACR0-11 assembler with, 18-1,
18-5
messages, 18-7
output from, 18-1
overiaying lines in a module,
example of, 18-4
program sections,
processing of, 18-4
steps in using, 18-1
switch, 18-3
Task Builder with, 18-4
transfer addresses,
processing of, 18-4

Patching,
PAT,
relocatable object modules,
18-1
ZAP,
task image files, 19-1
PF command, EDI, 3-40
PIP,
uses of, 6-3
PL command, EDI, 3-41
Positioning, PRESRV,
tape, 12-9
Predefined addresses, PRESRV,
12-7
Premounting tapes, PRESRV, 12-9
Preservation utility, 1-4
PRESRV image, 12-3
PRESRV,
modified version of, 12-7
bootstrapping, 12-7
switch,
administrative, 12-11, 12-18
blocking, 12-13, 12-16
format, 12-13
list, 12-10, 12-13
magnetic tape, 12-12, 12-20
specification of, 12-10
stand-alone, 12-12, 12-21
summary of, 12-10
PRI, QUE, 7-2
Primary input file, EDI, 3-6
PRINT command and CLI, QUE, 7-1
PRINT command fields,
described, 6-4 to 6-9
PRINT command format, 6-3
Print error messages, QUE, 6-18
to 6-23
PRINT command,
EDI, 3-11, 3-17, 3-26, 3-41
uses of, 6-1
Print,
EDT, 2-32
QUE, 7-3
PRINT$ macro, 6-17
Procedure, PRESRV,
bootstrap, 12-6
Procedures, PRESRV,
DECTAPE operating, 12-9
operating disk, 12-9
operating tape, 12-9
operating, 12-3
Processing of files, SLP, 17-4
Program maintenance utilities,
1-4
Programming utilities, 1-4
Prompt,
EDT,
Command Mode, 2-2, 2-3
SLP, 17-8 to 17-9

Index-18

as;

INDEX

Prompt:s, BRU, 10-10
Protect, PIP,
switch, 4-12, 4-25 to 4-27
Protection codes, FLX, 5-9
PRT, QUE, 7-1, Appendix C
QUE, 7-2
Purge, PIP, switch, 4-12, 4-27
to 4-28

Q
QMG,
PRI, 6-1
QUE, 6-1, 6-9, 7-1
QUE conunands, 6-2, 7-4
QUE /ASSIGN, 7-10
QUE /Dl~ASSIGN, 7-11
QUE /D:~LE.TE, 6-16 to 6-17
QUE /HOLD, 6-14 to 6-15
QUE /LIST, 6-9
job identification field,
6-10
options, 6-11 to 6-13
switiches, 6-10
QUE /MODIFY, 6-13 to 6-14, 6-18
QUE /RELEASE, 6-15 to 6-16
QUE /SPOOL, 7-8
QUE /S'rART, 7-6
QUE /S 1rOP, 7-5
QUE /UNSPOOL, 7-10
Queue Manager, 1-3, 6-1, 7-1
corrunand descriptions, 6-9
to 6-19, 7-4 to 7-11
components, 7-1
error messages, 6-18 to 6-22,
7-11 to 7-14
priority, 6-5
setting up, 7-2 to 7-4
spooling output from tasks,
6-17 to 6-18
Quit, EDT, 2-·33

R
RADIX-50 format, DMP,
dumping in, 15-5
Range, EDT, 2-4, 2-10
compound li.ne, 2-17
default, 2-·10
inclusive line, 2-18
single line, 2-15
specification, 2-10
variable line, 2-16
Read check switch, VFY, 13-10
READ command, EDI, 3-5 to 3-6,
3-25, 3-42
Rebuild switc:h, VFY, 13-10
Rebuilding lost files, VFY, 13-10

Record control switch, DMP, 15-5
Records, LBR,
compressing, 14-10
Recovering lost blocks, VFY,
13-8
Registers, ZAP,
accessing contents of, 19-6
internal, 19-6
relocation, 19-3
Relocation biases, ZAP, 19-3
Remove, PIP,
switch, 4-12, 4-30
Rename, PIP,
switch, 4-3 to 4-4, 4-12,
4-28 to 4-30
RENEW command, EDI, 3-5 to 3-6,
3-11, 3-18, 3-25, 3-42
Replace switch, LBR, 14-22
for universal libraries, 14-26
Replace, EDT, 2-34
Replacing lines in a source
file, SLP, 17-13
format for, 17-13
locator fields, 17-13
Requirements, PRESRV,
blocking, 12-25
buffer, 12-6, 12-25
file name, 12-2
Resequence, EDT, 2-35
Restore, EDT, 2-37
Restoring files marked-fordelete, VFY, 13-7
Restrictions, LBR, 14-32
RETURN command, EDI, 3-11, 3-42
RETYPE command, EDI, 3-11, 3-19,
3-24, 3-43
Rewind switch, ·DMP, 15-6
Rewind, PIP,
switch, 4-12 4-31 to 4-32
RSX-llM and RSX-llM-PLUS
utilities, 1-1
entering command lines for,
1-4 to 1-5
entering file specifications
for, 1-5 to 1-6
invoking, 1-6
programs, 1-1 to 1-4 ,
RUBOUT character, EDI, 3-7

s
SAVE command, EDI, 3-25, 3-43
Save, EDT, 2-38
SC command, EDI, 3-44
SEARCH AND CHANGE command, EDI,
3-22, 3-44
Secondary input file, EDI, 3-6

Index-19

INDEX

SELECT PRIMARY conunand, EDI,
3-21, 3-44
SELECT SECONDARY conunand, EDI,
3-21, 3-45
Selective delete, PIP,
switch, 4-12, 4-32 to 4-33
Selective search attribute,
LBR,
setting, 14-28
Selective search switch, LBR,
14-28
Serial despooler, QUE, 7-1 to
7-2
Set, EDT, 2-38
Case, 2-40
Exact, 2-40
Terminal, 2-40
Setup conunands,
EDI,
sununarized, 3-21
queue manager, 7-2 to 7-4
Shared read, PIP,
switch, 4-12, 4-34
Show, EDT, 2-40
SIZE conunand, EDI, 3-21, 3-45
SLP,
generating input for with
CMP, 16-6
Source files, SLP,
creating, 17-1, 17-14
input to, 17-1 to 17-2
maintenance of, 17-1
trailing blanks - tabs in,
17-15, 17-19
updating, 17-10
SP conunand, EDI, 3-44
Span blocks switch, PIP, 4-12,
4-32
Specification,
entering file, 1-5
Specify switches, BAD, 9-1
Spool switch,
DMP, 15-6
LBR, 14-27
PIP, 14-12, 14-33 to 14-34
Spooling output, QUE, 6-17 to
6-18
Spooling,
CMP output, 16-3
defined, 6-1, 7-1
DMP output, 15-6
file, 1-2
LBR listing files to the
printer, 14-27
Squeeze library files, LBR,
14-29
Squeeze switch, LBR, 14-29
SS command, EDI, 3-45

Stand-alone switches, PRESRV,
12-12, 12-21
Stand-alone system version only,
switches, 9-1, 9-7 to 9-8
Stand-alone, DSC,
initiating and terminating,
11-6
switches, 11-20
Standard format, QUE, 6-10
Standard length, QUE, 7-8
STARTUP procedure and queue
manager, 7-2 to 7-3
Storage bit map file, BRU, 10-7
String searches, EDT, 2-14,
2-56
delimiters for, 2-14, 2-56
Subcommands, EDT, 2-48
concatenation of, 2-58
cursor manipulation, 2-56
editing, 2-49
Exit, 2-59
Insert, 2-54
Quit, 2-60
Substitute, 2-55
Substitute, EDT, 2-42
Next, 2-42
Subswitch specification,
example of, 1-6
Supported devices,
DSC, 11-5
FMT,
allow formatting, 8-4
DB:, 8-5
DK:, 8-5
DM:, 8-5
DP:, 8-6
DR:, 8-6
DY:, 8-6
required status, 8-5
Switches,
description of, 9-5 to 9-7
FLX,
defaults, 5-3 to 5-8
file transfer, 5-3
format, 5-2 to 5-3
paper tape transfer mode,
5-15
FMT, 8-1, 8-2, 8-6 to 8-8
forms of, 1-6
manual and update, BAD, 9-6
to 9-7
PRESRV,
summary of, 12-10
SLP, 17-1
calculating checksum, 17-1,
17-15
control, 17-1, 17-15
manipulating audit trails,
17-1

~~-

Index-20

ij LU T

t !!i ¢

INDEX

Switches (Cont.)
manipulating files, 17-1,
17-15
values/defaults, 17-2, 17-16
specifying, BAD, 9-1
Stand-alone system version,
JBAD, 9-7 to 9-8
ta:sk and stand-alone, BAD, 9-5
to 9-6
valid specifications for, 1-6
ZAJP, 19-2

T
TA11/TU60 cassette support,
FLX, 5-12
file formats, 5-13
input files, 5-14 to 5-15
multivolume cassette formats,
S-13
output files, 5-13 to 5-14
TAB ON/OFF command, EDI, 3-21,
3-45
Tape copy, PRESRV,
logical, 12-2 to 12-3
Tape format,
ANSI,
BRU, 10·-2 6
logical tape format, PRESRV,
12-1 to 12-2, 12-5, 12-8,
12-11 to 12-13, 12-15
Tape input, PRESRV,
logrical, 12-8
Tape operating procedures,
PRESRV, 12-9
Tape operations, BRU,
multivolume, 10-27
Tape output, PRESRV, 12-9
log·ical, 12-8
Tape posi ticming, PRESRV, 12-9
Tape set, BRU, 10-27
Tape switche!s, PRESRV,
magnetic, 12-12, 12-20
Tape, PRESRV,
premounting, 12-9
Task builder, ZAP,
use with, 19-1
Task version, BAD, 9-1
Task/File Patch Program (ZAP) ,
19-1 to 19-16
Task/file, 1-4
TEST file, EDI, 3-6
Text access modes, EDI, 3-3
Text buffers, EDT. See Buffers
Text files, EDT,
creating, 2-1, 2-4, 2-32
editing, 2-1, 2-4
Text :modification commands, EDI,
3-23

Text page, EDI,
defined, 3-5
Text, EDI,
processing pages of, 3-5
Text truncation, SLP,
(/CM) I 17-16, 17-19
Text, EDT,
changing characters of, 2-42,
2-55
deleting, 2-23 2-49
displaying, 2-44, 2-49
inserting, 2-28, 2-54
replacing, 2-34, 2-49
transferring, 2-22, 2-30
TOF command, EDI, 3-4, 3-20,
3-24, 3-46
TOP command, EDI, 3-4, 3-11,
3-19, 3-46
TOP OF FILE command, EDI, 3-11,
3-20, 3-24, 3-46
Truncate, PIP,
switch, 4-12, 4-35
TYPE command, EDI, 3-26, 3-47
Type, EDT, 2-44

u
UC command, EDI, 3-47
UIC, 1-5
QUE, 6-10, 6-14, 6-15 to 6-17
Uninstalled utilities,
invoking, 1-9
prompt for, 1-9
running from DCL, 1-9
running from MCR, 1-9
Universal libraries, LBR,
insert switch for, 14-19
Unlock, PIP,
switch, 4-12, 4-36 to 4-37
UNSAVE command, EDI, 3-24,
3-47
Update switch, VFY, 13-11
Update switches, BAD,
manual, 9-6 to 9-7
Update,
PIP,
switch, 4-12, 4-37 to 4-38
SLP,
source files, 17-10
Updating,
relocatable object modules,
PAT, 18-1
task image files, ZAP, 19-1
UPPER CASE ON/OFF command, EDI,
3-21, 3-47
Usage notes, EDI, 3-49
User file directory, PIP,
switch, 4-12, 4-35

Index-21

INDEX

Utility programs, 1-1
Utility,
invoking and passing control
to, 1-8

v
Validating contents, PAT,
files, 18-7
Validity check, VFY, 13-4
error reporting, 13-5
files market-for-delete, 13-6
Values, SLP,
defaults, 17-7
switches, 17-7
VERIFY ON/OFF command, EDI,
3-21, 3-48
Version numbers, FLX,
cassettes, 5-13
Version, 1-6
VFY {File Structure Verification
Utility),
command string described, 13-2
error messages, 13-12
switches, 13-4, 13-9 to 13-11
validity check, 13-4
Video terminals, EDT, 2-48
delete key functions, 2-53
keypad arrow function, 2-57
Volume labels, BRU,
ANSI, 10-21, 10-26
disk default, 10-20
disk input, 10-17
disk output, 10-20
disk, 10-9, 10-14
tape, 10-21
Volume maintenance utilities,
1-1
Volumes,
BRU,
backing up from mounted,
10-18
existing, 10-24
restoring to mounted, 10-19
FLX, 5-1
default {Files-11), 5-2
DOS-11, 5-1
Files-11, 5-1
initializing, 5-2, 5-10,
5-11
mounting, 5-2, 5-8, 5-10
RT-11, 5-1
PRESRV,
multifile, 12-8

w
Wildcards,
BRU,
supported by, 10-12

Wildcards {Cont.)
FLX, 5-3
PIP, 4-2, 4-4 to 4-5, 4-15,
4-28 to 4-29, 4-39, 4-44
restrictions of, 4-4
specifying, 4-4
uses of, 4-4 to 4-5
SLP, 17-3
Word, EDT,
definition of, 2-50
WRITE command, EDI, 3-25, 3-49
Write, EDT, 2-45

x
XEQ, EDT, 2-46

z
ZAP,
addressing locations, 19-3
addressing modes, 19-3
absolute, 19-3
default, 19-3
switches for specifying,
19-2
task image, 19-4
arithmetic functions and
operators, 19-6 to 19-7
carriage return, 19-6
changing contents of a
location,
command functions, 19-11
closing locations in a file,
examples of, 19-11 to 19-13
command format, 19-2
commands,
open/close location
functions, 19-5
summarized, 19-3
displaying boundaries of an
overlay segment, 19-2
error messages, 19-16
exiting from, 19-4
functions,
examples of general purpose,
19-14 to 19-16
general purpose, 19-13 to
19-16
invoking, 19-2
location,
verifying the contents of a,
19-15
location-specifier formats,
block number: byte offset,
19-8
byte offset, 19-8
relocation register~ byte
offset, 19-9
modes, 19-2

Index-22

t''•. . . . . . . . . . . . . . . . . ._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ___

INDEX

ZAP (Cont.)
absolute, 19-3
default, 19-3
read-only, 19-3
switches for specifying, 19-2
task image, 19-4
opening locations in a file,
19-10
overlay segments,
changing locations in, 19-4
patching Files-11 files, 19-1
prompt, 19-2
registers,
accessing contents of, 19-6

ZAP (Cont.)
=unctions, 19-6
internal, 19-6
relocation, 19-3
relocation biases, 19-3
switches, 19-2 to 19-3
terminating, 19-2, 19-14
using MACR0-11 listings with,
example of, 19-4
using MACR0-11 with, 19-1
using ODT with, 19-1
using Task Builder with, 19-1
using TKB map with,
example of, 19-4

Index-23

''f'

i ·

RSX-11 Utilities Manual
AA-H268A-TC

READER'S. COMMENTS

NOTE:

'l'his form is fo.r document comments only. DIGITAL will
use comments submitted on this form at the company's
discretion. If you require a written reply and are
E~ligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
:f:orm.

Did you find this manual understandable, usable, and well-organized?
PlE~ase make suggestions for improvement.

u .
Cl>

..,,

::e
C>

c
0

"6
..._

Did you find errors in this manual?
paige number.

If so, specify the error and the

:::>

0
Cl>

0::

Pl.ease indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify>~~~~~~~~~~~~~~~~~~~

Street
City

- - - - - - - - - - - - S t a t e - - - - - - - Zip Code _______
or
Country

Do Not Tear - Fold Here and Tape -

-L

-----~
No Postage
Necessary
if Mailed in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

--·

RT/C SOFTWARE PUBLICATIONS TW/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS 01876

~
I

·~
-

DoNotTear-FoldHere

-I
I

I
I

2$1

I 2