Digital PDFs

AA-FD13A-TC

July 1985

507 pages

Original

19MB

Document:	RSX-11M/M-PLUS Utilities Manual
Order Number:	AA-FD13A-TC
Revision:	0
Pages:	507
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.2_Jul85/AA-FD13A-TC_RSX-11M_M-PLUS_Utilities_Manual_198507.pdf

OCR Text

RSX-11 M/M-PLUS
Utilities Manual
Order No. AA-FD13A- TC
Includes Update Pages

RSX-11 M/M-PLUS
Utilities Manual
Order No. AA-FD13A-TC
Includes Update Pages

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

digital equipment corporation · maynard, massachusetts'

First Printing, December
Revised, November
Updated, April
Revised, July

1979
1981
1983
1985

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a
license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
Copyright

The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-lo
DECSYSTEM-20
DEC US
DECwriter

DIBOL
EduSystem
!AS
MAS SB US
MicroPDP-11
Micro/RSTS
Micro/RSX
PDP

PDT
RSTS
RSX
UNIBUS
VAX
VMS
VT

~nmno~n

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

800-258-1710

In New Hampshire, Alaska, and Hawaii call 603-884-6660
In Canada call 613-234-7726 (Ottawa-Hull)
800-267-6215 (all other Canadian)

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

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

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

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

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

ZK2945

CONTENTS
Page
PREFACE

SUMMARY OF TECHNICAL CHANGES

xix

CHAPTER 1

INTRODUCTION

RSX-llM/M-PLUS UTILITY PROGRAMS
• 1-1
Line Text Editor (EDI) • • • •
• • 1-2
Peripheral Interchange Program (PIP)
• 1-2
File Transfer Utility Program (FLX)
• • • •
1-2
Disk Volume Formatter Utility (FMT)
• • • 1-2
Bad Block Locator Utility (BAD)
• • • 1-2
Backup and Restore Utility (BRU) • • • • • • • • 1-3
Disk Save and Compress Utility Program (DSC) • • 1-3
File Structure Verification Utility (VFY)
• • • 1-3
Librarian Utility Program (LBR)
• • • • • • 1-3
File Dump Utility (DMP)
• • • • • • •
• • 1-3
File Compare Utility (CMP) • • • • •
• • • 1-3
Source Language Input Program (SLP)
• • 1-3
Object Module Patch Utility (PAT)
• • • • • • • 1-3
Task/File Patch Program (ZAP)
• • • • • • 1-4
COMMAND LINES • • • • • • • • •
• • 1-4
FILE SPECIFICATIONS • • • • •
• • 1-4
INVOKING THE UTILITIES • • • •
• • 1-6
Invoking Installed Utilities • • • • • • • • • • 1-7
Invoking a Utility and Returning Control to
MCR
• • • • • • • • • • • • • • • •
• 1-7
Invoking a Utility and Returning Control to
1.4.1.2

1.1
1.1.l
1.1. 2
1.1.3
1.1.4
1.1.5
1.1.6
1.1. 7
1.1.8
1.1.9
1.1.10
1.1. l l
1.1.12
1.1.13
1.1.14
1. 2
1.3
1.4
1. 4 .1
1.4.1.1

DC L

•

• 1-8

Invoking and Passing Control to a Utility
1-8
1.4.1.3
1. 4. 2
Invoking Uninstalled Utilities • •
• • 1-9
USING INDIRECT COMMAND FILES • • • • • • • • • • • 1-9
1.5
CHAPTER 2

LINE TEXT EDITOR (EDI)

2.1
USING EDI
• • • • • • • • • • • • • •
2 .1.1
Invoking EDI •
• •••••••••••••
2.1.1.1
Entering File Specifications • • •
• ••
Defaults in File Specifications
•••
2.1.1.2
2 .1. 2
Control Modes: Edit and Input • • • •
• •
Text Access Modes
• • • •
2.1. 3
2.1.3.1
Line-by-Line Mode
• • • •
• •
2.1.3.2
Block Mode • • • • • • • • • • • • •
• • •
2.1.3.3
Processing Text in Pages • •
• • • • • • •
2 .1. 4
Text Files • • • • • • • • • •
2.1.4.1
Input and Secondary Files
• • • • •
Output Files • • • • • • •
• •••••
2.1.4.2
2 .1. 5
Terminal Conventions • • • • •
• •••••
Character Erase (DELETE or RUBOUT • • • • • •
2.1.5.1
2.1.5.2
Line Erase (CTRL/U)
• • • •
•
2.1.5.3
The RETURN Key • • • • • • • • • •
• • •

iii

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

April 1983

CONTENTS
Page
2.1.5.4
2.1.5.5
2 .1.6
2.1.6.1
2.1.6.2
2.1.6.3
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.2.9
2.2.10
2.2.11
2.2.12
2.2.13
2.2.14
2.2.15
2.2.16
2.2.17
2.2.18
2.2.19
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.3.6
2.3.7
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.4.6
2.4.7
2.4.8
2.4.9
2.4.10
2.4.11
2.4.12
2.4.13
2.4.14
2.4.15
2.4.16
2.4.17
2.4.18
2.4.19
2.4.20
2.4.21
2.4.22
2.4.23
2.4.24
2.4.25
2.4.26
2.4.27
2.4.28
2.4.29

Terminating the Previous Text Line (ESCape or
ALTmode)
• 2-7
Terminating EDI (CTRL/Z)
• 2-8
EDI Command Conventions
• 2-8
Use of Asterisk {*)
• 2-8
Use of Ellipsis { ••• ) in Search Strings
• 2-8
Command Abbreviations
• 2-9
BASIC EDI COMMANDS •
• 2-9
ADD
2-11
ADD & PRINT
2-12
BOTTOM •
2-12
CHANGE •
2-12
CTRL/Z •
2-13
DELETE •
2-13
DELETE & PRINT •
2-14
The ESCape Key •
2-14
EXIT •
2-14
INSERT •
2-15
LOCATE •
2-15
NEXT •
2-16
NEXT & PRINT •
2-16
PRINT
2-17
RENEW
2-19
The RETURN Key •
2-19
RETYPE •
2-19
TOF
2-19
TOP
2-20
EDI COMMANDS: FUNCTION SUMMARY •
2-20
Setup Commands •
2-21
Locator Commands (Line-Pointer Control)
2-22
Text Modification and Manipulation Commands
2-23
Macro Commands •
2-25
File Input/Output Commands •
2-25
Device Output Commands •
2-26
CLOSE and EXIT Commands
2-27
EDI COMMANDS: DETAILED REFERENCE SUMMARY •
2-27
ADD
2-27
ADD & PRINT (AP)
2-28
BEGIN
2-28
BLOCK ON/OFF •
2-28
BOTTOM •
2-29
CHANGE •
2-29
CLOSE
2-29
CLOSE SECONDARY (CLOSES)
2-30
CLOSE & DELETE {CD)
2-30
CONCATENATION CHARACTER (CC)
2-30
CTRL/Z •
2-31
DELETE •
2-31
DELETE & PRINT (DP)
2-31
END
2-31
ERASE
2-32
The ESCape Key •
2-32
EXIT •
2-32
EXIT & DELETE {ED)
2-32
FILE •
2-33
FIND •
2-33
FORM FEED (FF)
2-34
INSERT •
2-34
KILL •
2-34
LINE CHANGE (LC)
2-35
LIST ON TERMINAL (LI)
2-35
LIST ON PSEUDO DEVICE (LP)
2-36
LOCATE •
2-36
MACRO
2-36
MACRO CALL (MC)
2-37
iv

CONTENTS
Page
2.4.30
2.4.31
2.4.32
2.4.33
2.4.34
2.4.35
2.4.36
2.4.37
2.4.38
2.4.39
2.4.40
2.4.41
2.4.42
2.4.43
2.4.44
2.4.45
2.4.46
2.4.47
2.4.48
2.4.49
2.4.50
2.4.51
2.4.52
2.4.53
2.4.54
2.4.55
2.4.56
2.4.57
2.4.58
2.5
2.6
2.6.1
2.6.2
2.6.3
2.6.4
2.7
2.7.1
2.7.2
2.7.3
2.7.4
CHAPTER 3

MACRO EXECUTE
MACRO IMMEDIATE
NEXT • • • • •
NEXT & PRINT •
OPEN SECONDARY •
OUTPUT ON/OFF
OVERLAY
PAGE • • • • •
PAGE FIND
PAGE LOCATE
PASTE
PRINT
READ •
• • • •
RENEW • • • • • • • • •
The RETURN Key •
RETYPE
SAVE •
SEARCH & CHANGE
SELECT PRIMARY •
SELECT SECONDARY • • • • •
SIZE • • • • • • •
TAB ON/OFF • • • • • • • •
TOP • • • • • • •
TOP OF FILE (TOF)
TYPE • • • • • • •
UNSAVE • • • • • • •
UPPER CASE ON/OFF • • • •
VERIFY ON/OFF
WRITE • • • • • •
EDI USAGE NOTES
• • • • •
SAMPLE EDITING OPERATIONS
• • • •
File Editing Sample • • • • •
SAVE and UNSAVE Sample •
•
Use of MACRO IMMEDIATE Command •
Use of Macro Commands • • • •
EDI ERROR MESSAGES • • • • • • • • •
Command Level Information Messages •
File Access Error Messages •
Error Messages Requiring EDI Restart • •
Fatal Error Messages • • • • • • • •

2-38
2-38
2-39
2-39
2-39
2-40
2-40
2-41
2-41
2-41
2-42
2-42
2-42
2-43
2-43
2-43
2-44
2-44
2-45
2-46
2-46
2-46
2-47
2-47
2-47
2-48
2-48
2-49
2-49
2-50
2-51
2-51
2-53
2-55
2-55
2-56
2-57
2-60
2-61
2-64

PERIPHERAL INTERCHANGE PROGRAM (PIP)

3.1
PIP COMMAND LINE •
• • • •
• • • • • • • 3-1
PIP Defaults for File Specification Elements • • 3-1
3 .1.1
3 .1. 2
PIP Switches and Subswitches •
• • • • • • • 3-3
Switches • • • • • • • • • • • • • • • • • • • 3-5
3.1.2.1
3.1.2.2
Subswitches • • • • • • • • • • • • • •
• 3-6
Wildcards
• • • • • • • • • • • • • •
• 3-7
3 .1. 3
Wildcards in Output File Specifications
• 3-7
3.1.3.1
Wildcards in Input Specifications
• • • • 3-8
3.1.3.2
3.2
PIP COMMAND FUNCTIONS • • • • • • • •
• 3-8
Copying Files-11 Files • • • • • •
• 3-8
3.2.1
Performing File Control Functions
• • • • 3-14
3.2.2
/AP -- Append Switch • • • •
3-14
3.2.2.1
/BS:n -- Block Size Switch •
• • • • 3-15
3.2.2.2
/CD
Creation Date Switch
3-16
3.2.2.3
/DD
Default Date Switch
3-16
3.2.2.4
/DE -- Delete Switch • • • •
3-17
3.2.2.5
3.2.2.6
/DF -- Default Switch
• • • •
3-18
/EN -- Enter Switch • • • •
3-19
3.2.2.7
3.2.2.8
/EOF -- End-of-File Switch •
3-21
EX -- File Exclusion Switch • • • • • •
3-21
3.2.2.9
3.2.2.10
/FI -- File Identification Switch
3-22

CONTENTS
Page

. . . . .. .. .. . . . . . 3-23
3-23
. . . . 3-24
...
3-28
....
3-28
3-29
..
. . . . . 3-31
3-33
.. .. .. . . . . . .. .. . . 3-35
3-36
3-37
3-37
3-38
. . . . ..
3-39
.
.
3-40
.
.
..
3-40
3-41
3-42
.....
. . . . . 3-42
3-43
. . . . . . . . . . . . . . 3-53

Free Switch
/FR
3.2.2.11
Identify Switch
3.2.2.12
/ID
List Switch
3.2.2.13
/LI
Merge Switch
3.2.2.14
/ME
No Message Switch
3.2.2.15
/NM
Protect Switch
3.2.2.16
/PR
Purge Switch
3.2.2.17
/PU
Rename Switch
3.2.2.18
/RE
Remove Switch
3.2.2.19
/RM
Rewind Switch
3.2.2.20
/RW
Span Blocks Switch
3.2.2.21
/SB
Selective Delete Switch
/SD
3.2.2.22
Spool Switch
3.2.2.23
/SP
Shared Reading Switch
3.2.2.24
/SR
Today Default Switch
/TD
3.2.2.25
Truncate Switch
/TR
3.2.2.26
User File Directory Switch
3.2.2.27
/UF
Unlock Switch
3.2.2.28
/UN
Update Switch
3.2.2.29
/UP
PIP ERROR MESSAGES
3.3
PIP ERROR CODES
3.4
CHAPTER 4
4.1
4.2
4.2.l
4.2.2
4.2.3
4.3
4.3.l
4.3.2
4.3.3
4.4
4.4.1
4.4.2
4.4.3
4.5
4.5.1
4.5.2
4.5.3
4.6
4.7
4.8
CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.4
5.5

FILE TRANSFER PROGRAM (FLX)
FLX COMMAND FORMAT • • • •
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 • • • •
FORTRAN DIRECT ACCESS FILES
FLX ERROR MESSAGES • • • • • •

• 4-2
• 4-3
• 4-4
4-4

• 4-6
• 4-8
• 4-8
4-10
4-10
4-10
4-10
4-12
4-12
4-13
4-14
4-14
4-15
4-15
4-16
4-17

DISK VOLUME FORMATTER (FMT)
INITIATING AND TERMINATING FMT
5-1
MODES OF FMT OPERATION • • •
5-2
Normal Operating Mode
5-3
Manual Operating Mode
• • • • •
5-3
FMT SUPPORTED DISK VOLUMES
• • • • • • • • • • 5-5
DB~-type Devices (RP04/RP05/RP06 Disk Packs) • • 5-5
DK:-type Devices (RK05 Disk Cartridge or RK05F
Fixed Media Disks) • • • • • • • • • • • • • • • 5-6
DL:-type Devices (RL01/RL02 Disk Cartridges) • • 5-6
DM:-type Devices (RK06/RK07 Disk Cartridges) • • 5-6
DP:-type Devices (RPR02/RP02/RP03 Disk Packs)
• 5-6
DR:-type Devices (RM02/RM03/RM05/RM80 Disk
Packs) • • • • •
• • • • • • •
• • • 5-7
DY:-type Devices (RX02 Floppy Disks)
5-7
FMT SWITCH DESCRIPTIONS
• 5-7
FMT M.ESSAGES • • • •
• • • • 5-10
vi

CONTENTS
Page
CHAPTER 6

6.1
6.2
6.3
6.4
6.4.1
6.4.1.1
6.4.1.2
6.4.2
6.4.3
6.5
6.5.1
6.5.1.1
6.5.1.2

6.6
6.6.1
6.6.2
6.6.3
6.7
6.8
CHAPTER 7

BAD BLOCK LOCATOR UTILITY (BAD)
BAD COMMAND FORMAT • • • • • • •
• • • •
6-1
BAD SWITCHES • • • • • • • • • •
• 6-1
BAD AND INDIRECT COMMAND FILES
• 6-2
PROCESSING BAD BLOCK DATA
• 6-3
verifying Devices
• • • • • •
• • • 6-3
BAD and Non-Last-Track Devices • • • • • • • • 6-3
BAD and Last-Track Devices •
• 6-3
Format of Bad Block Descriptor Entries • •
• 6-4
The INI Command and BAD
• • • •
• 6-4
USING BAD • • • • • • • • •
• 6-4
Programming Considerations •
• 6-5
Use of Block Zero
• • • • •
• 6-5
Device Controller Errors • •
• • • •
• 6-5
BAD SWITCH DESCRIPTIONS
• • • • • • • • • • • 6-5
Switches for Both Task and Stand-Alone Versions
of BAD •
• • • • •
• • • • • • • • • • • 6-5
The /MANUAL, /ALLOCATE and /UPDATE Switches:
Examples • • • • • • • • • • • • • • • • • • • • 6-7
Switches for Stand-Alone System Version Only • • 6-8
DEVICES SUPPORTED BY BAD •
• • • • •
• 6-9
BAD MESSAGES • • • • • • •
• • • • • • • • 6-10
BACKUP AND RESTORE UTILITY (BRU)

ON-LINE BRU DISK AND TAPE DEVICE INFORMATION
7.1
Backup Sets
• • • • • • • • •
7 .1.1
Tape Sets and Disk Sets
• • • • •
7 .1. 2
Tape and Disk Backup Operations
7.1.2.1
Full and Selective Backup Operation
7.1.2.2
7.1.2.3
Conventional Backup Operation
Image Backup to Disk Operation • •
• • •
7.1.2.4
Multivolume Tape and Disk Operations •
7 .1.3
Supported Devices
7 .1. 4
7.2
COMMAND LINES
• • • • • • • • • • • • • •
Command Line Syntax • • • • • • • • •
• •
7.2.1
7.2.2
Command Line Parameters
• • • • • • • • • • •
Wildcards in Input Specifications
7.2.2.1
7.2.2.2
Continuation Lines • • • • • • • •
SUMMARY OF COMMAND QUALIFIERS, OPTIONS, AND
7.3
DEFAULTS • • • • • • • • • • • • • •
Command Qualifier Functions
7.3.1
7.4
DESCRIPTIONS OF COMMAND QUALIFIERS •
STAND-ALONE BRU • • • • • • • • • • • • • •
7.5
7.5.1
Locating and Booting Stand-Alone BRU • • • • •
ON-LINE BRU BAD BLOCK PROCESSING • • •
7.6
7.6.1
Using the AUTOMATIC Option • • •
Using the OVERRIDE Option
7.6.2
7.6.3
Using the MANUAL Option • • • •
USING BRU TO COPY DISKS CONTAINING SYSTEM IMAGES
7.7
7.7.1
Copying an Unsaved (Virgin) System • • •
Copying a Saved System • • • • • • • • •
7.7.2
Copying to a Smaller Disk • • • • • • •
7.7.2.1
Copying to a Different Controller Type •
7.7.2.2
7.8
BRU FILE TREATMENT • • • • • • •
Creation and Revision Dates of Files • • • • •
7.8.1
7.8.2
File Headers •
File Synonyms • • • •
7.8.3
Lost Files • •
7.8.4
EXAMPLES •
7.9
7.10
MESSAGES • •

vii

• 7-1
• 7-3
7-3
• 7-3
• 7-3
• 7-4
• 7-4
• 7-4
• 7-5
• 7-:5
• 7-6
• 7-6
• 7-7
• 7-8
• 7-8
7-11
7-12
7-22
7-23
7-24
7-25
7-25
7-25
7-26
7-26
7-26

I
I

7-26
7-26
7-26
7-27
7-27
7-27
7-27
7-27
7-34

April 1983

I
I

CONTENTS
Page
CHAPTER 8

DISK SAVE AND COMPRESS {DSC)

8.1
DSC-SUPPORTED VOLUMES
• 8-4
INITIATING AND TERMINATING ON-LINE DSC
8.2
• • • • 8-5
8.3
INITIATING AND TERMINATING STAND-ALONE DSC •
• 8-5
8.4
DSC COMMAND FORMAT • • • •
• • • • • • • • • • 8-5
8.5
DSC FILE LABELS, SWITCHES, AND OPTIONS • • • • • • 8-6
8.5.1
File Label • • • • • • •
• • • • 8-8
8.5.2
/Append Switch • • • • •
• • • •
• • 8-9
/Bad Block Switch
• • • •
• 8-9
8.5.3
8.5.3.1
Obtaining Bad Block Information • • • • • • 8-12
Conversion to Logical Block Numbers • • • • 8-12
8.5.3.2
8.5.4
/Block Factor Switch • • • • • • • • • •
8-12
8.5.4.1
Using the /BL Switch • • • • • • • • • • • • 8-12
8.5.4.2
System-Dependent Requirements for /BL Switch 8-13
8.5.5
/Compare Switch
8-14
8.5.6
/Density Switch
• • • • • • 8-14
8.5.6.1
1600 bpi Option
8-15
8.5.6.2
Split Density Option •
8-15
8.5.7
/Rewind Switch • • • • • • • •
• • • • • • 8-15
8.5.8
/Verify Switch • • • •
• • • • • • • 8-18
8.6
DSC OPERATION OVERVIEW •
• • • • • • 8-19
8.7
STAND-ALONE DSC - DSCSYS.SYS • •
8-19
8.7.1
/Control Status Register Switch • • • •
8-21
8.7.2
/TM02 Switch • • • • • • • • • • • •
8-22
8.7.3
/Unit Switch • • • • • • • •
• • • •
8-22
8.7.4
/Vector Address Switch • •
• • • • 8-23
STAND-ALONE DSC - DSC64K.SYS
• • • • 8-23
8.8
8.9
DSC DATA TRANSFERS • • • • •
8-24
Data Transfer from Disk
8-25
8.9.1
8.9.2
Data Transfer to Tape • • • •
• • • • • 8-25
Data Transfer from Tape • • • • • • • •
8-26
8.9.3
8.9.4
Data Transfer to Disk • • • •
• • • • • 8-27
8.10
DSC MESSAGES • • • • • • •
8-28
8.10.1
DSC General Messages • • • • • • •
8-29
8.10.2
DSC I/O Messages • • • • • • • • •
• • • • 8-42
8.10.3
Stand-Alone DSC Messages •
• • • • • • 8-44
CHAPTER 9

FILE STRUCTURE VERIFICATION UTILITY {VFY)

9.1
VFY COMMAND FORMAT • •
• • • • • • • • • • • • 9-2
9.2
VFY MODE OF OPERATION
• • • • • • • • 9-3
9.3
VFY VALIDITY CHECK • •
• • • • •
• • • • 9-3
9.4
VFY SWITCHES • • • • • •
• • • • • 9-3
9.4.i
Delete Switch {/DE)
• • • • • • •
• • • • 9-4
9.4.2
Directory Validation Switch {/DV)
• • • • 9-5
9.4.3
Free Switch {/FR)
•
• • • • • • • 9-5
9.4.4
Header Delete Switch {/HD) • • • •
• • • • 9-5
9.4.5
List Switch {/LI)
• • • •
• • • • 9-6
9.4.6
Lost Switch {/LO)
•
• • • • 9-6
9.4.7
Read Check ~witch {/RC)
• • • • • • • • • 9-7
9.4.8
Rebuild Switch (/RE) • •
• • • 9-7
9.4.9
Update Switch {/UP)
• 9-8
FILE ERROR REPORTING • • • • • • • • • • • • • • • 9-8
9.5
9.5.1
Files Marked-for-Delete • • • • • •
• •• 9-9
Restoring a File Marked-for-Delete
9-10
9.5.1.1
9.5.1.2
Delet~ng
a
File
Marked-for-Delete
9-10
Deletio~ of Bad File Headers • • • • • •
9-10
9.5.2
9.5.3
Deleti¢n of Multiply-Allocated Blocks
• • • • 9-10
Elimination of Free Blocks •
• • • • • 9-11
9.5.4
9.5.5
Recovering Lost Blocks • • • • •
9-11
9.6
VFY ER~OR MESSAGES • • • • • • • •
9-11

viii

CONTENTS
Page
CHAPTER 10
10.1
10.1.1
10.1.2
10.1.3
10.1.4
10.2
10.3
10.4
10.5
10.5.1
10.5.2
10.5.3
10.5.4
10.5.5
10.5.6
10.5.7
10.5.8
10.5.9
10.5.10
10.5.11
10.5.12
10.5.13
10.5.14
10.5.15
10.5.16
10.6
10.7
10.7.1
10.7.2
CHAPTER 11
11.1
11. 2
11.3
11.4
11.5
11.5.1
11. 5. 2
11.5.3
11.6
CHAPTER 12
12.1
12.2
12.2.1
12.2.2
12.2.3
12.3
CHAPTER 13
13.1
13.1.1
13.1.2
13.1.3
13.1.4

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

10-2
10-2
10-2
10-2
10-2
10-8
10-8
10-8
10-9
10-10
10-12
10-13
10-14
10-15
10-16
10-18
10-19
10-20
10-21
10-22
10-23
10-27
10-29
10-29
10-30
10-32
10-33
10-33
10-34

(DMP)

FILE MODE
• • • • • •
DEVICE MODE • • • • • • • • •
DMP COMMAND FORMAT •
DMP SWITCHES • • • • • • • • •
DMP EXAMPLES • • • • • • •
A Multiple Format Dump
A Record Dump
A Header Dump
DMP ERROR MESSAGES • • •

• • • •
• • • • • •
•
• •

11-1
11-2
11-2
11-3
11-8
11-8
11-10
11-10
11-12

THE FILE COMPARE UTILITY (CMP)
CMP SWITCHES • • • • • •
FORMATS OF CMP OUTPUT FILES
Differences Format • • • • •
Change Bar Format
SLP Command Input Format • •
CMP MESSAGES • • • • • • •

12-2
12-4
12-5
12-5
12-6
12-6

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP INPUT AND OUTPUT FILES
The Input File • • •
Command Input
• •
The SLP Listing File •
The SLP Output File • •
ix

• •
• •••
• •
• •

13-2
13-2
13-2
13-3
13-3

CONTENTS
Page

13-4
HOW SLP PROCESSES FILES • • • •
13.2
13.3
13-5
USING SLP • • • • • • •
• • • •
Specifying SLP Edit Commands •
13-5
13.3.1
13.3.2
Entering SLP Edit Commands • •
13-7
Entering SLP Commands Interactively
13-7
13.3.2.1
13.3.2.2
Entering SLP Commands Using Indirect
Command Files • • • • • • • • •
13-8
Using SLP Operators • • • • •
13-9
13.3.2.3
Updating Source Files With SLP •
• • • • • 13-9
13.3.3
Generating a Numbered Listing • • • • •
13-9
13.3.3.1
Adding Lines to a File • • • •
• • • • • 13-10
13.3.3.2
13.3.3.3
Deleting Lines from a File • •
• 13-12
Replacing Lines in a File
• • • •
• 13-13
13.3.3.4
13.3.4
Creating Source Files Using SLP
13-14
CONTROLLING SLP • • • • • • • • • •
13-14
13.4
13.4.1
SLP Switches • • • • • • • • • •
• 13-14
Controlling the Audit Trail
• • • • • 13-16
13.4.2
Setting the Position and Length of the Audit
13.4.3
Trail
• • • • • • • • • • • • • •
• • 13-17
Changing the Value of the Audit Trail
• 13-17
13.4.4
Temporarily Suppressing the Audit Trail • • • 13-18
13o4e5
13.4.6
Deleting the Audit Trail •
13-19
SLP MESSAGES • • • • • • •
• 13-20
13.5
13.5.1
SLP Information Message
• • 13-20
SLP Error Messages • • •
• • • • • • 13-20
13.5.2
CHAPTER 14

-OBJECT MODULE PATCH UTILITY (PAT)

SPECIFYING THE PAT COMMAND LINE
HOW PAT APPLIES UPDATES
• • • •
The Input Fi le • • •
The Correction File
• • • •
•
How PAT and the Task Builder Update Object
Modules • • • • • • • • • • • • • • • • •
Overlaying Lines in a Module • • • •
14.2.3.1
14.2.3.2
Adding a Subroutine to a Module • •
Determining and Validating the Contents of
14.2.4
Fi 1 e • • • • • • • •
• •
PAT MESSAGES • • • • •
• • • •
14.3
14.3.1
Information Messages • • • • • • • • •
Command Line Errors • • • •
14.3.2
File Specification Errors
14.3.3
Input/Output Errors
14.3.4
Errors in File Contents or Format
14.3.5
•
Internal Software Error
•
14.3.6
Storage Allocation Error • • • • • •
14.3.7

14-1
14-3
14-3
14-3

14.1
14.2
14.2.1
14.2.2
14.2.3

CHAPTER 15

I
I

• •
a

14-4
14-4
14-5

14-6
14-7
14-8
14-8
14-9
• 14-10
• • 14-11
• • 14-13
• 14-13
• •

TASK/FILE PATCH PROGRAM (ZAP)

15.1
ZAP OPERATING MODES AND SWITCHES
15-2
The List Switch (/LI)
••••
15-2
15.1.1
15.1.1.1
The /LI
Switch and
Regular Task Image
15-3
Files
........... .
15.1.1.2
The /LI Switch and
Multiuser
Task
Image
Files • • • • • • • • • • • • •
15-3
15.1.1.3
The /LI Switch and Resident Libraries
15-3
15.1.1.4
The /LI Switch and I- and D-Space Tasks
15-3
15.2
ADDRESSING LOCATIONS IN FILES • • • • •
15-4
15.2.1
Relocation Biases • • • • • • • • • • •
15-4
15.2.2
ZAP Addressing Modes • • • • • • • • • • •
15-4
15.2.2.1
Using the Task Image Addressing Mode •
15-5
15.2.2.2
Using the Absolute Addressing Mode
15-5
15.3
INVOKING AND TERMINATING ZAP • • • • • • •
15-5

April 1983

CONTENTS
Page
15.3.1
Using Indirect Command Files with ZAP • • • • 15-6
15.4
THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS • 15-6
15.4.1
ZAP Commands • • • • • • • • • • •
15-7
15.4.1.1
Open/Close Location Commands • •
15-7
15.4.1.2
General
Purpose
Commands
• • • • • 15-7
15.4.1.3
RETURN Key • • • • • •
15-7
15.4.2
ZAP Internal Registers • • • • • •
15-8
15.4.3
ZAP Arithmetic Operators • • • • • •
15-8
15.4.4
ZAP Command Line Element Separators • •
15-9
15.4.5
ZAP Command Line Location-Specifier Formats • 15-10
15.4.5.1
The Current Location Symbol
• • • 15-10
15.4.5.2
Byte Offset Format • • • • • • • • • • •
15-10
15.4.5.3
Block Number:Byte Offset Format
15-10
15.4.5.4
Relocation Register,Byte Offset Format
• 15-10
15.5
USING ZAP OPEN AND CLOSE COMMANDS
• 15-11
15.5.1
Opening Locations in a File • • • •
• • 15-12
15.5.2
Changing the Contents of a Location
• 15~13
15.5.3
Closing Locations in a File • • • •
• 15-13
15.5.3.1
Closing a Location and Opening the
Preceding Location
•
• • • 15-13
15.5.3.2
Closing a Location and Opening an Offset
Location
• • • • • • • • • • • • • • • • • 15-14
15.5.3.3
Closing a Location and Opening an Absolute
Location
• • • • •
• • • • • • • • • • 15-14
15.5.3.4
Closing a Location and Opening a Branch
Target Location • • • • • • • • • • • • • • 15-14
15.5.3.5
Closing a Location and Opening a Previous
Location • • • • • • • • • • •
• 15-15
15.6
USING ZAP GENERAL PURPOSE COMMANDS
• 15-15
15.6.1
The X Command
• • • •
• • • • • • 15-16
15.6.2
The K Command
• • • •
• • • • • 15-16
15.6.3
The 0 Command
• • • • •
15-17
15.6.4
The Equal Sign (=) Command •
• 15-17
15.6.5
The V Command
• • • • • • •
• 15-17
15.6.6
The R Command • • • • •
• • • 15-18
15.7
EXAMPLES • • • • • • • • •
• • • • • • 15-18
15.8
ZAP ERROR MESSAGES
• • • • •
• • • • • 15-23
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.15 .1
A.15.2
A.15.3
APPENDIX B
B.l
B.1.1

COMMANDS AND SWITCHES
INTRODUCTION • • • •
• •
EDI COMMAND SUMMARY
• • • • •
PIP COMMAND SUMMARY • • • • • • • •
FLX COMMAND SUMMARY
• • •
FMT COMMAND SUMMARY
BAD COMMAND SUMMARY
BRU COMMAND SUMMARY
• • •
DSC COMMAND SUMMARY
VFY COMMAND SUMMARY
LBR COMMAND SUMMARY
DMP COMMAND SUMMARY
CMP COMMAND SUMMARY
• • • •
SLP COMMAND SUMMARY
• • •
PAT COMMAND SUMMARY
• • •
ZAP COMMAND AND SWITCH SUMMARY •
ZAP Open/Close Commands
ZAP General-Purpose Commands
ZAP Switches • • • • • • •
• • • •

• • A-1
• • A-1
• • A-5
• • A-9
A-11

•

•
•
•

•

A-12
A-13
A-16
A-17
A-18
A-20
A-22
A-23
A-24
A-25
A-25
A-26
A-27

THE CROSS-REFERENCE PROCESSOR (CRF)
HOW CRF PROCESSES DATA • • • • • • •
MACR0-11 or Task Builder Processing

• • B-1
• • • • • • B-1
April 1983

CONTENTS
Page
B.1.2
B.2
B.3
B.4

CRF Processing • • • • • • • • • •
• B-3
THE CRF SYMBOL TABLE FILE • • • • • • • • • • • • B-3
THE CRF SEND PACKET
• • • • • • • • • • • B-4
CRF ERROR MESSAGES • • • • •
• • • • • • B-5

EXAMPLES
EXAMPLE 2-1
11-1
11-2
11-3

Line Printer Position for the TYPE Command and
the PRINT Command
• • • • • • • • • • • • • • • 2-18
Dumping Virtual Blocks in Hexadecimal, Radix-SO,
and Decimal Format • • • •
• • • •
11-9
Dumping Virtual Records in ASCII and Decimal
Word Format
• • • • • • • • •
• • 11-10
Dumping the File Header of a File • • • • • • • 11-11

FIGURES
FIGURE

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

Results of Copy Command With and Without /NV
Specified • • • • • • • • • • • • • • • • • • • 3-13
Sample Directories Before and After Execution
3-20
Directory Listing Examples • • • • • • • • • • • 3-27
Format of Protection Word • • • • • • • • • • • 3-31
Use of the Purge Switch • • • • • • • • • • • • 3-32
Results of Rename Switch With and Without /NV
Specified • • • • • • • • • • • • • • • • •
3-35
DOS-11 Directory Listings • • • • • • • • • • • • 4-9
RT-11 RKOS Cartridge Disk Directory Listing
4-11
Data Transfer for DSC Copy Operation • • • • • • • 8-2
Data Transfer for DSC Compare Operation
• • • 8-3
General Format for Object and Macro Library Files 10-3
Universal Library File Format • • • • •
10-4
Contents of Library Header • • • • • • • •
10-5
Format of Entry Point Table Element • • • •
10-6
Format of Module Name Table Element • • • •
10-6
Module Header Format for Object and Macro
Libraries • • • • •
• • • • • • • • • •
10-6
Module Header Format for Universal Libraries • • 10-7
Sample Files used in LBR Examples 1-4 • • • • • 10-25
Output Library File After Execution of Example 1 10-26
Output Library File After Execution of Example 2 10-26
Output Library File After Execution of Example 3 10-27
Sample Files for Universal Library Replace
Example • • • • • • • • • • • • • • • • • • • • 10-28
Output Library File After Execution of Universal
Library Replace Example
• • • •
10-28
MACRO Listing Before and After Running LBR with
/SZ Switch • • • • • • • • • • • • • • •
• 10-32
Input Files and Output Files Used During SLP
13-4
Process • • • • • • • • • • • • • • • • • •
Processing Steps Required to Update a Module
14-2
Using PAT • • • • • • • • • • • • • • • • •
How MACR0-11, the Task Builder, and CRF Generate
Cross-Reference Li stings • • •
• • • • • • • B-2
Format of the CRF Symbol Table File • • • •
B-4
Format of the CRF SEND Packet • • • •
• B-5
I

xii

CONTENTS
Page
TABLES
TABLE

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

EDI Default File Specifications
• • • • •
• • 2-3
Line-by-Line and Block Mode Differences
• • 2-5
Basic EDI Commands •
2-10
EDI Setup Commands • • • • • • • • • • • • • • • 2-21
EDI Locator Commands • • • • • • • • • •
2-22
EDI Text Modification and Manipulation Commands
2-23
EDI Macro Commands • • • • • • • • • • • • • • • 2-25
EDI Input/Output Commands • • •
• • • • • • 2-25
EDI Device Output Commands • • •
• • • • 2-26
EDI Close Operation Commands • •
• • • • • • 2-27
PIP Default File Specifications
• • 3-2
PIP Switches and Subswitches • •
• • • • 3-3
PIP Copy Command and Merge Subswitches
3-11
List Subswitches • • • • • • • • •
3-25
Response Choices for the Selective Delete Switch 3-38
PIP Error Codes • • • • • •
3-54
FLX Transfer Mode Switches •
• • • • • • • • • 4-5
FLX Control Switches • • • •
• • • • • • • • • 4-6
Differences Between Files-11 and DOS-11 Cassette
Files Format • • • • • • • •
4-13
Ranges for Manual FMT Operations • • • • • • •
5-4
FMT-Supported Disk Volumes • • • •
• 5-5
BAD Switches • • • • • • • • • • • • • • •
• • 6-2
Devices Supported by Stand-alone BAD •
6-9
Mounting and Initializing Volumes
• • 7-2
Devices Supported by On-Line BRU •
7-5
Summary of BRU Command Qualifiers
• 7-8
DSC-Supported Devices
• • • • • • •
• • 8-4
DSC Switches and Options • • • • • • • • • • •
8-7
Operating System Limits for DSC Block Factor
8-13
The /Rewind Switch and DSC Operations
8-17
Stand-Alone DSCSYS.SYS Switches • • • • •
8-20
System-Generated CSR and Vector Addresses
8-21
General Error and I/O Error Message Codes
8-29
VFY Switches and Functions • • • • • •
• 9-4
LBR File Specifiers Defaults • • • • •
10-8
LBR Switches • • • • • • • • • • • • •
• 10-10
DMP Switches • • • • • • • • • • • • •
11-3
Summary of CMP Default Switch Settings
12-4
SLP Operators • • • • •
• •••
• • • • 13-9
SLP Switches • • • • • • • • • • • •
• 13-15
ZAP Arithmetic Operators • • • • • •
15-9
ZAP Command Line Element Separators
15-9
ZAP Open and Close Commands • • • •
• 15-11
ZAP General Purpose Commands • • • • • • • • • • 15-15

xiii

PREFACE

MANUAL OBJECTIVES
The RSX-llM/M-PLUS Utilities Manual is a reference manual describing
the use of 15 utilities supported on the RSX-llM and RSX-llM-PLUS
operating systems.

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

STRUCTURE OF THIS DOCUMENT
Chapter 1 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 Line Text Editor (EDI).
Chapter 3 describes the Peripheral Interchange Program (PIP).
Chapter 4 describes the File Transfer Utility Program (FLX).
Chapter 5 describes the Disk Volume Formatter Utility (FMT).
Chapter 6 describes the Bad Block Locator Utility (BAD).
Chapter 7 describes the Backup and Restore Utility (BRU).
Chapter 8 describes the Disk Save and Compress Utility Program (DSC).
Chapter 9 describes the File Structure Verification Utility (VFY).
Chapter 10 describes the Librarian Utility Program (LBR).
Chapter 11 describes the File Dump Utility (DMP).
Chapter 12 describes the File Compare Utility (CMP).
Chapter 13 describes the Source Language Input Program (SLP).
Chapter 14 describes the Object Module Patch Utility (PAT).
Chapter 15 describes the Task/File Patch Program (ZAP).

PREFACE
Appendix A
utilities.

summary

the

commands

and

switches

for

the

Appendix B describes the Cross-Reference Processor (CRF) •

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

CONVENTIONS USED IN THIS DOCUMENT
Use of Red Ink
User input appears in red.
Lines and prompting characters
the system appear in black.

output

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
IBm
symbol, which denotes the RETURN key.
Use of Lowercase Characters
Lowercase characters in a command line indicate variables
the user must substitute a word or value.
For example:

for

which

filename.filetype;version
This command indicates the values that comprise a file specification;
values are substituted for each of these variables as appropriate.
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
commarid:
Write
This notation means that W, WR, WRI, WRIT, and
specifications for the WRITE command.

xvi

WRITE

are

all

valid

PREFACE

Use of Square Brackets ([])
Square brackets indicate optional entries in a command line or a file
specification.
Note that when an option is entered, the brackets are
not included in the command line.
Square brackets also are a part of the User File Directory (UFD) and
User Identification Code (UIC) syntax {[group,member] ). When you use
a UIC or UFD {in a file specification, for example), brackets are
required syntax elements;
that is, they do not indicate optional
entries.
Use of Braces ({})
Braces indicate a choice of required entries for a command line.
You
can use any of the entries enclosed in the braces, but you must
specify one of them.
Use of Commas {,)
Commas are used as separators for command line parameters and to
indicate positional entries on a command line. Positional entries are
those elements that must be in a certain place in the command line.
Although you might omit elements that come before the desired element,
the commas that separate them must still be included.
Use of 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 of Periods (.)
Periods in the file specification separate the file name and file
type.
When the file type is not specified, the period may be omitted
from the file specification.
Use of 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 and subswitches in the command line.
When
shown in the command line format, they should be specified as shown.

A horizontal ellipsis indicates that
repeated one or more times.

xvii

the

preceding

item(s)

can

PREFACE

The symbol
while you
(CTRL/0)

mRL~J
indicates that you must press the key labeled CTRL
simultaneously press another key, for example,
CTRL/Cl

tTRL/Z) •

Command lines are terminated by
otherwise indicated in the text.
key is
ffi)

pressing the RETURN key unless
The form used to denote the RETURN

Use of Shading
Shaded portions of text describe only one operating system.
Pink
shading indicates that the text describes only RSX-llM operating
systems.
Gray shading indicates that the text describes
only
RSX-llM-PLUS operating systems. The smallest shaded portion of text
is a paragraph. The text that is not shaded describes both operating
systems.

xviii

SUMMARY OF TECHNICAL CHANGES

The following is a list of the technical changes (such as new
functionality, and new and revised switches) by utility, in the order
in which the utility appears in this manual.

Peripheral Interchange Program (PIP)
ANSI magnetic tapes are now supported.
& - Ampersand (new) - Separates each
command
commands are specified in the same command line.

several

when

% - Wildcard (new) - Denotes exactly one character

in
name and/or file type of an input file specification.

the

/CD - Creation Date switch (revised) - Can be set as the
(instead of /-CD).
/DD - Default Date switch (new) - Restricts file
files created during a specified period of time.

file

default

searches

/DF - Default switch (revised) - Specified with no arguments, it
returns the default device to SYO: and the UFD to the UIC from
which PIP was invoked.
/EX - File
Exclusion
switch
(new) - Excludes
specification's worth of files during a file search.

one

file

/FR - Free Blocks switch (revised) - Displays the amount of
available space on a specified volume, the largest contiguous
space on that volume, and the number of available file headers.
/ID - Identity switch (revised) - Identifies the version
being used and if PIP is linked to ANSI FCS.
/TD - Today switch (new) - Restricts
created on the current day.

file

searches

of
to

PIP
files

File Transfer Utility Program (FLX)
The TU78 magnetic tape is now supported.
/DNS:6250 - Density switch (revised) - Specifies
6250 bpi to support the TU78 magnetic tape.

xix

density

SUMMARY OF TECHNICAL CHANGES
Disk Volume Formatter Utility (FMT)
The RMOS disk is fully supported.
larger RM03.

FMT

treats

the

RMOS

DL:-type devices are supported, and some corrupted DL:-type
cartridges can be made usable again.
/VE - Verify switch (revised) -

disk

is now the default operation.

/-VE, /NOVE, /-VERIFY, /NOVERIFY - No Verify
Inhibits the default verification operation.
/DENSITY, /MANUAL, /VERIFY
/MAN, and /VE respectively.

(new) - Switch

switch

synonyms

(new)
for

/DENS,

Bad Block Locator Utility (BAD)
A multiheader BADBLK.SYS file is now supported.
The maximum
allowable retrieval pointers in the bad block descriptor file
have been expanded from 102 to 126 for non-last-track devices.
The updated stand-alone version of BAD supports the following
devices: the RMOS, RMSO, and RP07 disk packs, and the RASO fixed
media disk.
/ALO:volume label - Allocate switch (new) - Prompts for blocks to
be allocated to BADBLK.SYS and to be entered in the bad block
descriptor file.
/PAT=m:n - Pattern switch (new) - Specifies the double-word
pattern used to locate bad blocks.

data

Backup and Restore Utility (BRU)
BRU now supports multivolume backup and restore operations
the /IMAGE switch.

using

BRU now supports the following devices: RA60/RA81/RC25/RD51/RX50
disks, RL11/RL02 cartridge disks, RH70/RM05/RM80/RP07 disk packs,
UDA50/RP07 disk packs, TM78/TU78 magnetic tapes, MLll electronic
memory, and TSll/TSVOS/TUSO magnetic tapes.
Disk volumes with multiheader index files (structure
are supported.

level

402)

There are now two stand-alone BRU systems.
BRU64K is the
stand-alone version for the RSX-llM and BRUSYS is the stand-alone
version for RSX-llM-PLUS.
/DENSITY - Density switch (revised) - For TU78 magnetic tapes,
you can specify a density of 1600 or 6250 bpi (6250 is the
default bpi) •

/IMAGE:option - Image switch (new) - Specifies that you
do a multiple disk-to-disk backup or restore operation.

want

/UFO - User File Directory switch (new) - Directs BRU to create a
UFO (if it does not already exist) on a mounted output volume,
and then to copy into it the files from the same UFO on the input
volume.

April 1983

SUMMARY OF TECHNICAL CHANGES
Disk Save and Compress Utility Program (DSC)
There are
DSC64K.

two

new

stand-alone

versions

DSC:

DSCSYS

and

DSCSYS is a combination of DSCS8 and DSCS16.
This version
requires 28K words to run and a maximum blocking factor of 4.
DSCSYS supports the following new devices: the RP07 disk, the
RA08 fixed media disk, and the TU78 magnetic tape.
DSC64K is essentially an RSX-llM system with BAD, FMT, DSC, and
CNF fixed in memory. The maximum blocking factor is 4 and DT,
DX, DY, DD, DF, and DS devices are not supported.
DSC now supports up to 64K files on a volume.
/BAD=OVR - Override option
(new) - Ignores
the
bad
block
descriptor area and accesses the last good block on the next to
last track of the disk to obtain the data to create BADBLK.SYS.
/BAD=MAN:OVR - Manual Override option (new) - Allows manual entry
of bad block data to the bad block file BADBLK.SYS.
/DENS=6250 - Density switch (revised) - Creates magnetic tapes at
6250 bpi.
The /DENS:6250 option is valid with TU78 magnetic
tapes only.

File Structure Verification Utility Program (VFY)
/DV - Directory Validation switch
against the files they list.

(new) - Validates

directories

/HD - Header Delete switch
(new) - Recognizes and deletes bad
file headers on a volume. The /AL subswitch allows bad headers
to be automatically deleted with no user intervention.

File Dump Utility Program (DMP)
Multiple-format dumps are supported. Any or all
switches can be specified in a command line.

the

format

ANSI magnetic tapes are supported.
/LC - Lower Case switch (new) - Specifies that the data should be
dumped in lowercase characters.
/OCT - Octal switch (new) - Specifies that the data
dumped in octal format in addition to other formats.

should

/SB:n or /SB:-n - Specifies the number of blocks DMP space Blocks
switch (new) - Spaces forward or backward on a tape.
/SF:n or /SF:-n - Space Files switch (new) - Specifies the number
of end-of-file {EOF) marks DMP spaces forward or backward on a
tape.

xxi

SUMMARY OF TECHNICAL CHANGES
File Compare Utility (CMP)
CMP's default output device/file is now TI:,.
Any unspecified portions of the second input file specification
default to the specifications for the first input file.

Source Language Input Program (SLP)
/SQ - Sequence switch (new) - Sequences the lines in the output
file so that they reflect the line numbers of the original input
file.
/RS - Resequence switch
output file.

(new) - Resequences

the

lines

the

/NS - No Sequence switch (new) - Does not sequence lines in
output file.
New lines are indicated by the audit trail.

the

Task/File Patch Program (ZAP)

Four types of task image files are supported:
•

Regular task image files (including those mapped
and supervisor mode libraries)

•

Multiuser task image files (RSX-llM-PLUS only)

•

I- and
D-space
(RSX-llM-PLUS only)

•

Resident libraries

(instruction

and

data

resident

space)

tasks

Resident libraries can be changed in task image mode. ZAP finds
the segments and allows you to make changes in both absolute mode
and task image mode.

/LI - List switch (revised) - Includes read-only segments of a
task in its segment table.
ZAP finds the starting address and
allows you to make changes in both absolute mode and task image
mode.
For I- and D-space tasks, the /LI switch lists the
starting block number and the address boundaries of each segment.

xx ii

April 1983

CHAPTER 1
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-llM/M-PLUS 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.
Two
appendixes are also included to provide you with a summary of commands
and switches for 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
introduction:

1.1

summarizing

the

RSX-llM/M-PLUS

utilities,

this

•

Describes how to enter RSX-llM/M-PLUS command lines
specifications (Sections 1.2 and 1.3)

and

file

•

Describes how to invoke utilities and enter command
them (Section 1.4)

lines

•

Describes how to use indirect command files (Section 1.5)

RSX-llM/M-PLUS UTILITY PROGRAMS

This manual provides reference
RSX-llM/M-PLUS utilities:

information

Line Text Editor (EDI)
Peripheral Interchange Program (PIP)
File Transfer Utility Program {FLX)
Disk Volume Formatter Utility {FMT)
Bad Block Locator Utility (BAD)
Backup and Restore Utility {BRU)
Disk Save and Compress Utility Program {DSC)
File Structure Verification Utility {VFY)
Librarian Utility Program {LBR)
File Dump Utility (DMP)

1-1

for

the

following

INTRODUCTION
File Compare Utility (CMP)
Source Language Input Program (SLP)
Object Module Patch Utility (PAT)
Task/File Patch Program (ZAP)
The following sections briefly describe each utility.
Note that the utilities described in this manual are not the only
programs on RSX-llM and RSX-llM-PLUS that are used as or considered to
be utilities. TKB, CDA, and MAC are examples of other utility-like
programs.
Some programs, such as the editor EDI', are common across
different operating systems.
These other programs are documented
elsewhere in the RSX-llM/M-PLUS documentation set.
Refer to the
RSX-llM/RSX-llS or RSX-llM-PLUS Information Directory and Index for
information on what programs are available and where they are
described.

1.1.1

Line Text Editor (EDI)

EDI is a line-oriented, interactive editor used to create and maintain
text
and
source files.
(The RSX-llM/M-PLUS Guide to Program
Development gives specific information about using EDI to create and
maintain program source files.)

1.1.2

Peripheral Interchange Program (PIP)

PIP copies files and performs several file control functions, such as
concatenating, renaming, spooling, listing, deleting, and unlocking.

1.1.3

File Transfer Utility 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.4

Disk Volume Formatter Utility (FMT)

FMT formats and verifies several types of Files-11 disks.
FMT writes
and verifies sector headers, sets the density for flexible disks, and
allows spawning of the Bad Block Locator Utility (if your system
allows spawned tasks) •

1.1.5

Bad Block Locator Utility (BAD)

BAD determines the number and location of bad blocks on a volume. The
information gathered from running BAD on a volume can be used in
different ways when that volume is initialized.

1-2

INTRODUCTION
1.1.6

Backup and Restore Utility (BRU)

BRU transfers files from a Files-11 volume to one or more backup
volumes
(including non-Files-11 volumes) and retrieves files from the
backup volume (or volumes). BRU is faster than DSC
(see Section
1.1.7)
in most areas. Also, BRU compresses data, the volumes do not
have to be initialized, and incremental backups are possible.

1.1.7

Disk Save and Compress Utility 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 on-line or stand-alone.

1.1.8

File Structure Verification Utility (VFY)

VFY is a disk verification program that verifies the
validity of the file structure on a Files-11 volume.

1.1.9

consistency

and

Librarian Utility Program (LBR)

LBR is a library maintenance program that creates, displays, anc
modifies library files.
LBR can process macro, object, and universal
libraries.

1.1.10

File Dump Utility (DMP)

DMP is a file listing program that allows you to examine the contents
of a file or volume of files. DMP also provides options that control
the format of the contents.

1.1.11

File Compare Utility (CMP)

CMP compares two text files,
record
differences between the two files.

1.1.12

record,

lists

the

maintain

and

Source Language Input Program (SLP)

SLP is a noninteractive editing program that is used to
audit source files.

1.1.13

and

Object Module Patch Utility (PAT)

PAT updates, or patches, relocatable binary object modules.

1-3

INTRODUCTION
1.1.14

Task/File Patch Program (ZAP)

ZAP is a patch utility that examines and directly
in a task image file or data file.

1.2

modifies

locations

COMMAND LINES

The general format for command lines in
utilities is:

most

the

RSX-llM/M-PLUS

outfile[ ••• ,outfile]=infile[ ••• ,infile] ~
The variables outfile and
infile are file specifications for the
output and
input files to be operated on by the utility.
(File
specifications are described in Section 1.3.)
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.
Most of the utilities also accept
indirect command files containing command lines to the utility, as
described in Section 1.5.

1.3

FILE SPECIFICATIONS

In the command line format described
in Section 1.2, outfile and
infile
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 default length is 80 characters).
The format for entering file specifications is:
ddnn: [g,m]filename.type;version/switch ••• /subswitch •••
ddnn:
The physical or logical device unit containing the desired
volume.
The name consists of two or three ASCII characters
followed by an optional 1-, 2-, or 3-digit octal number and a
colon, for example, DMO:, or TT116:.
The default is the user's system device, SY:.

[g,m]
The User File Directory (UFD) listing the desired file or files.
The variables g and m are octal numbers from 0 to 377 that
represent the group and member numbers,
respectively, of the
file's owner.
The brackets are a mandatory part of the UFD
syntax.
The default is the current UIC
which your terminal is set.
See
the
RSX-llM/M-PLUS
MCR
RSX-llM/M-PLUS Command Langliage
UICs and UFDs.

1-4

(User

Identification

Code)

Operations
Manual
or
the
Manual for more information on

INTRODUCTION
filename
The name of the file.
characters in length.

File

names

can

from

one

nine

If you want to include special characters in the file name
(for
example, semicolons or exclamation marks), place double quotation
marks around the name.
If you use only one double quotation
mark, MCR or DCL assumes an American National Standard X.327-1978
file name.
(See the RSX-llM/M-PLUS I/O Operations Manual for
more
information on double quote support.) Note that not all
utilities or other tasks allow special characters.
There is no default.
type
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.
In this way, the file type identifies the nature of the contents
of the file.
File type and file name are separated by a period. The file type
may not be specified or can be up to three alphanumeric
characters in length.
The default for a file type depends on the
utility or task you are working with and if the file is an input
or output file.
See
the
RSX-llM/M-PLUS
MCR
RSX-llM/M-PLUS Command LangLiage
file types.

Operations
Manual
or
the
Manual for a list of standard

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 1 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 range
from 1 through 77777(8).
However, you can also use 0 to specify
the highest numbered version and -1 to specify the lowest
numbered version (0 is the default).
If a
file has a version
number of 77777, no more versions of it can be created.
Version number and file type are separated by a
default is the latest version.

semicolon.

The

/switch (also /qualifier)
BRU)
An ASCII name specifying a switch
(or qualifier in
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

invokes the switch function

/-sw

negates the switch function

/NOsw

negates the switch function

Switches can also take values in the form of ASCII strings and
numeric strings.
The values modify the function of the switch.

1-5

INTRODUCTION
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 specification 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 examples of valid switch specifications:
/SW : 2 7. : MAP: 2 9.
/-SW
/NOSW:-#SO:SWITCH
/subswitch
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 IBID
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 THE UTILITIES

You invoke a utility from the command line interpreter
{CLI)
environment.
The CL! can be the Monitor Console Routine {MCR), the
DIGITAL Command Language {DCL), or an alternate user-written CLI.
For
more information on MCR, see the RSX-llM/M-PLUS MCR Operations Manual.
For more information on DCL, see the RSX-llM/M-PLlJS Command Language
Manual.
To determine whether you are using MCR or DCL or another CLI, type
CTRL/C, which returns the explicit monitor prompt: MCR> or DCL> or
CLI>.
You can work with a utility directly {interactively) 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.1 describes these methods. For·systems in which not all
utilities are installed, you can use the method described in Section
1. 4. 2.
Section 1.5 describes how to invoke a utility
commands from an indirect command file.

that

You can invoke a utility when MCR or DCL prompts you.
are:
>

or {if you type CTRL/C first)

MCR>

The DCL prompts are:
>

or {if you type CTRL/C first)

1-6

DCL>

can

then

The MCR prompts

INTRODUCTION
In MCR, the utilities are always invoked by their 3-character names.
DCL, however, has commands that access utilities transparently to the
user. You do not have to explicitly specify the utility 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 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 (or MC).

1.4.1

command

Invoking Installed Utilities

RSX-llM/M-PLUS systems provided in distribution kits do not have any
utilities installed.
Once the system has been generated, the system
manager usually installs any commonly used utilities. Use the MCR TAS
or DCL SHOW TASKS /INSTALL commands to see which utilities are
currently installed in the system. If the utility you want to use is
not installed, any privileged user can install it with the MCR or DCL
INSTALL command. Once the utility is installed, you can invoke it.
The following sections describe the three primary methods you can
to invoke installed utilities.

use

1.4.1.1 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:
>utilityname command-line
or
MCR>utilityname command-line
Using this method to invoke the utility allows you to enter a single
command for execution.
The utility is installed, the command is
executed, and control returns to MCR.
(The method described in the
following section 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.1.3.
(However, you can specify
>SLP @indirectcommandfile
or
>ZAP @indirectcommandfile
See Section 1.5 for more information.)

1-7

INTRODUCTION
1.4.1.2 Invoking a Utility and Returning Control to DCL - Use one of
the following forms of command lines to invoke a utility to execute a
function and return control directly to DCL:
>commandname command-line
or
>MCR utilityname command-line
Using these methods to invoke the utility allow you to enter a single
command for execution.
The utility is installed, the command is
executed, and control returns to DCL. With the first method, the DCL
command transparently accesses the utility (see Section 1.4).
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.1.3.
(However, you can specify
>SLP @indirectcommandfile
or
>ZAP @indirectcommandfile
See Section 1.5 for more information.)

1.4.1.3 Invoking and Passing Control to a Utility - Use one of the
following forms of command lines to invoke an installed utility and
pass control to it:
For MCR:
>util i tyname
For DCL:
>MCR utilityname
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:
util i tyname>
You can then enter the command line 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.

1-8

INTRODUCTION
1.4.2

Invoking Uninstalled Utilities

You can use the following method to
invoke an uninstalled utility.
This method is useful for smaller systems in which not all utilities
are installed. This method uses either the MCR RUN command or the DCL
RUN command to invoke the utility.
The method invokes the utility by means of the following command:
>RUN $utilityname
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:
util i tyname>
Then it waits for you to enter a command line. The utility continues
to prompt you after each command line is executed. To terminate the
utility, enter CTRL/Z.
Control is then returned to MCR or DCL.
A variation of this method allows the utility to run under a UIC other
than the current UIC:
For MCR:
>RUN $utilityname/UIC=[g,m]
For DCL:
>RUN/UIC: [g ,m] $util i tyname
When the utility gains control, it prompts for
until you enter CTRL/Z.

1.5

functions

execute

USING INDIRECT COMMAND FILES

An indirect command file normally contains a sequence of command lines
that are interpreted by a 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.
The command lines contained in the indirect command file are executed
when the indirect command file is invoked.
If you invoke the file
from MCR or DCL, each command line must begin with the name of the
utility or command you want to use.
If you invoke the file from the
utility itself, the command lines do not begin with the name of the
utility, but they must all be legal for that utility.
For example, an indirect command
series of PIP command lines:

file

=DB2: [303,24]TESTPREP.CMD
TESTPREP. *;*/LI
TEST PREP. */PU : 2
*.CMD/SP

1-9

might

contain

the

following

INTRODUCTION
To invoke the indirect command file (PIPCMDS.CMD), enter
following sets of commands:

one

the

For MCR:
>PIP @PI PCMDS. CMD IBru
or
>PIP(Brn
PI P>@PI PCMDS (Brn
or
>RUN $PIP (Brn
PI P>@PI PCMDS (Brn
For DCL:
>RUN $PIP (Brn
PI P>@PI PCMDS (Brn
or
>MCR PIP @PI PCMDS (Brn
or
>MCR PIP (Brn
PI P>@PI PCMDS IBfl)
In this example, PIP is invoked and accesses the file PIPCMDS.CMD,
which contains the sequence of PIP command lines. Because PIP is
invoked first, the command lines in the file do not have to begin with
PIP.
PIP executes the command lines and returns control to MCR, DCL,
or PIP, depending on which command set you use.
RSX-llM and RSX-llM-PLUS also allow you to use indirect command files
that contain MCR or DCL commands. The command lines do not begin with
MCR or DCL; they must only be legal for the CL!.
You invoke the
indirect command file by entering only the file specification preceded
by the at sign (@) in response to the prompt (in this case, the MCR
prompt) :
>@indirectcommandfile
The default values for indirect command file specifications are:
•

device - SY:

•

[g,m] - 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 indirect command files, see the
RSX-llM/M-PLUS MCR Operations Manual.

1-10

CHAPTER 2
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 MACR0-11 source files.
EDI 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
files, and select data modes.

conditions,

•

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 sequences of EDI
commands.

•

File input and output commands
input, output, and saved files.

•

Device output commands send output to a terminal or a printer.

•

Close and exit commands terminate editing operations.

transfer

text

and

open

from

Commands are categorized in this chapter as Basic EDI Commands
(Section 2.2}, EDI Commands: Function Summary (Section 2.3}, and EDI
Commands: Detailed Reference Summary (Section 2. 4).
Restrictions,
system device considerations, and error messages for these commands
are discussed in Sections 2.5 and 2.6.

2.1

USING EDI

This section gives background information about EDI that is
for you to know before you read the command descriptions.

2.1.1

important

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 prompt:
EDI>

2-1

LINE TEXT EDITOR (EDI)
At this point, you must enter the file specification for the
be edited.

file

2.1.1.1 Entering File Specifications - Enter a file specification
the following format:

ddnn:[ufd]filename.filetype;version
The abbreviation ufilespec" 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.
2.1.2.)

(EDI control modes are

described

Section

If the message FILE DOES NOT EXIST is printed, 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 0]

*
and waits in edit mode for you to issue the first command.
If the ">EDI filespec" format is used, the prompt (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, edit mode if the
file name already exists.
After EDI has identified the input file and created the output file,
it is ready for commands.
In edit mode, the first line available for
editing is one line above the first line 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 issue a
NEXT command to make that line available.

2.1.1.2 Defaults in File Specifications - EDI uses a default if any
of the elements of the file specification, except the input file name,
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 editing 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 2-1.

2-2

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

Element

Default Value
for Input File

Default Value
for Output File

ddnn:

SYO:

Same as input device

[ufd]

UFD under which EDI
is currently running

Same as input [ufd]

filename

No default -- must
be specified

Same as input file name

f iletype

Unspecified

Same as input file type

;version

Latest version

Latest version + l

2.1.2

Control Modes: Edit and Input

EDI runs in two control modes:
•

Edit mode (command mode)

•

Input mode (text mode)

Edit mode is invoked automatically when you specify an existing file.
In edit mode, EDI issues an asterisk (*) as a prompt.
EDI acts upon
commands and data to open and close files;
to bring 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 by pressing the
RETURN key, EDI sends a line feed to the terminal.
To switch from edit mode to input mode, enter the INSERT command and
press the RETURN key. To return to edit mode, press the RETURN key as
the only character on an input line.
EDI will issue the asterisk
prompt, signifying edit mode.

2.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
terminated by pressing the RETURN key.) The two modes are:
•

Line-by-Line Mode allows access to one line of text at a 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.

Block mode is the default text access mode.
2-3

LINE TEXT EDITOR {EDI)
In addition to these two text access modes,
EDI provides a way to
process text "pages." This feature is described in Section 2.1.3.3.

2.1.3.1 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 discussed later in this chapter.
However, you
cannot easily direct the ~ointer backward within the file.
When you open a file at the beginning of 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 line, that line is no longer accessible
unless you enter a TOF or TOP command (described in Section 2.4). TOF
causes the input and output files to be closed, and the output file to
become the new input file.
TOF also ends line-by-line mode.

2.1.3.2 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
A block is the number of lines read into the buffer by a RENEW or READ
command. This number is either:
1.

Specified with the SIZE command (default is 38 lines
SIZE command is not issued),

the

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

2-4

LINE TEXT EDITOR (EDI)
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 2-2 briefly summarizes the differences between line-by-line and
block mode.
Regardless of the editing mode, the line pointer always
points to the first character in the line.
Table 2-2
Line-by-Line and Block Mode Differences
Line-by-Line Mode

Block Mode

One line is available for
modification at a time.

A block of lines is 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
search the entire file.

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

2.1.3.3 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 refer 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.
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
command, 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
{EOF), EDI
increments the page count to 1.

2.1.4

Text Files

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

2-5

LINE TEXT EDITOR (EDI)
2.1.4.1 Input and Secondary Files - EDI
following:

accepts

input

•

The input terminal

•

Files-11 volumes that contain any of the following:

from

the

(that is, commands and text entries)

- The file to be edited
- A secondary file
- A save file
- A macro file
The input file is always preserved.I 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.
Instead, 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.

2.1.4.2 Output Files - The output file defaults
device, directory file name, and file type
version number is incremented by one.

disk

when

to the input file
specifications. The

If you wish to change any of these parameters
(except device and
directory), specify a new file specification when closing a file or
exiting at the end of an EDI session.

2.1.5

Terminal Conventions

RSX-llM/M-PLUS and EDI provide terminal keyboard functions that
you to:

• Delete characters on an input line
• Delete an entire input line
• Move the current line pointer forward in a file
• Move the current line pointer backward in a file
an editing session and return control to
• Terminate
(for example, MCR or DCL)

allow

your

CLI

2.1.5.1 Character Erase (DELETE or RUBOUT;
CTRL/R) - Pressing the
DELETE key (marked RUBOUT on some terminals)
deletes individual
characters if used before the RETURN key is pressed.
During editing
operations, DELETE does not affect previously prepared text.

1. To delete the input file, use the CLOSE-AND-DELETE command
EXIT-AND-DELETE command, or use PIP (see Chapter 3).
2-6

the

LINE TEXT EDITOR (EDI)
When the DELETE key is pressed, it is echoed first as a backslash
(\)
and is followed by the previously typed character.
Each successive
DELETE results in the echo of an earlier typed character.
When the
first non-DELETE character is typed,
it is echoed as a backslash
(closing the DELETE sequence) followed by the typed character.
For
example:
First DELETE typed
Second DELETE
Thi rd DELETE
Fir st non-DELETE

MISTKAE\E
MISTKAE\EA
MISTKAE\EAK
MISTKAE\EAK\AKE

For some CRT terminals, DELETE (or RUBOUT) works in a more obvious
way. Each DELETE causes the cursor to backspace, erasing the previous
character. You~ 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.
It is typed by holding down the CTRL key and pressing R.
CTRL/R echoes AR and is followed by a return and line feed.
For
example, at a hardcopy terminal you enter:
MISTKAE tQru
The echoed result is:
MISTKAE\EAK "R
MIST

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

2.1.5.3 The RETURB Key - The RETURN key has
depending on how it is used:

the

following

file

effects,

•

When issued in place of an input
RETURN key causes EDI to terminate.

specification,

the

•

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

line

•

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

input

•

When issued alone after an
invokes input mode.

RETURN

key

INSERT

command,

the

2.1.5.4 Terminating the Previous Text Line (ESCape or ALTmode) - When
EDI is in edit mode, pressing the ESCape (or ALTmode) key 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.
When EDI is in input mode, ESC acts as a return and terminates the
line.
If ESC is the first character of an input line, EDI exits from
input mode.
2-7

LINE TEXT EDITOR (EDI)
2.1.5.5 Terminating EDI (CTRL/Z) - CTRL/Z causes EDI to terminate.
EDI writes the remainder of the input file into the output file and
then closes both files before terminating. Use CTRL/Z to terminate
EDI in edit mode and input mode. CTRL/Z erases your last input line
if you enter the command as a line terminator.

2.1.6

EDI Command Conventions

EDI uses asterisks (*)
and ellipses ( ••• )
in special ways.
The
following sections describe these and also the notation convention
used to define EDI command abbreviations.

2.1.6.1 Use of Asterisk (*) - The asterisk (*) can be used
of any numeric argument.
It evaluates to 32767(10).

place

Example
The following command results in the printing of the remainder of
the block buffer or file.
PRINT

2.1.6.2 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, you can use
the following special string constructs. In these special cases, the
ellipsis ( ••• ) represents any number of intervening characters.
Case 1.

stringl ••• 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.

Case 3.

string •••

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

Case 4.

The entire current line.

Examples
In the following examples, the CHANGE command is used with the
four cases of special string constructs.
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.

2-8

LINE TEXT EDITOR (EDI)
Case 2.

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

Case 3.

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

Case 4.

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

2.1.6.3 Command Abbreviations - EDI permits the use of truncated
commands.
Where these shorter forms are allowed, the command format
specifications represent the shortest acceptable form
in uppercase
letters.
The lowercase letters may be entered optionally. The
following example shows the abbreviations allowed for the VERIFY
command. The command format specification is:
Verify
The following truncations are valid for the VERIFY command:

v
Ve
Ver
Veri
Ver if
Verify

2.2

BASIC EDI COMMANDS

The basic EDI commands listed in Table 2-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.
A more
detailed description of each command follows the table.
These
commands are the most important EDI commands.
As you become familiar
with EDI operations, the additional commands listed in Section 2.3 and
described in Section 2.4 will allow you to use all of EDI's
capabilities.

2-9

LINE TEXT EDITOR (EDI)
Table 2-3
Basic EDI Commands
Command

Command Format

ADD

Add string

Append string to current line.

ADD & PRINT

AP string

Append string to current
and print resulting line.

BOTTOM

Bottom

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

CHANGE

[n]Change /string!/
string2 [/]

Re pl ace
n times

tTRL/Z)

Type a Control

DELETE

Delete [n]
or
Delete [-n]

Delete current line and n-1
lines if n is positive; delete
n lines preceding current line
if
n
is
negative.
[-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, make it
new current line and exit from
input mode
(block mode only).
Same as NP-1.

EXIT

EXi t

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.

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.

Pr int [n]

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

Description

stringl with string2
in the current line.

Close
files
and
editing
session.

[ fil espec]

line

terminate

new

output
editing

(continued on next page)

2-10

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

Command Format

RENEW

RENew[n]

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

Press the RETURN key

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

RETYPE

Retype string

Replace
current
line
with
string or delete current line
if string is not given.

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.

2.2.1

Description

ADD

This command causes the specified string to be appended to the current
line.
Format
Add string
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 @Pl

@Pl

AGAIN.

2-11

LINE TEXT EDITOR (EDI)
ADD & PRINT

2.2.2

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

Format
AP string

Example
Using the same line used for the ADD command, the
command causes the new line to be printed as follows:

following

*AP AGAIN.
HAPPY DAYS ARE HERE AGAIN.

2.2.3

BOTTOM

This command 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 2.4.14).

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

2.2.4

bottom

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 asterisk
prompt.
If stringl is not given, string2 is inserted at the beginning
of the line.
If string2 is not given, stringl is deleted from the
current line.
The search for stringl begins at the beginning of the current line and
proceeds across the line until a match is found.

2-12

LINE TEXT EDITOR (EDI)
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
following example.
If no match occurs, a [NO MATCH] message is displayed.
Format
[n]Change /stringl/string2[/]
Example
TO SEPERATE THE THOUGHTS, USE SEPERATE SENTENCES.
2C/SEPE/SEPA/
TO SEPARATE THE THOUGHTS, USE SEPARATE SENTENCES.

2.2.5

CTRL/Z

Typing CTRL/Z (holding the CTRL 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.

2.2.6

DELETE

This command causes lines of text
manner:

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.

•

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 not given, the current line is deleted, and
line becomes the new current line.

2-13

the

LINE TEXT EDITOR (EDI)
Format
Delete [n]
or
Delete [-n]

Example
To delete the previous five lines in the block buffer,
following command:

type

the

*D -5

DELETE & PRINT

2.2.7

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

IS
IS
IS
IS

LINE
LINE
LINE
LINE

2
3
4

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

command

*DP 2

THIS IS LINE 3

2.2.8

The ESCape Key

2.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 file name.

2-14

LINE TEXT EDITOR (EDI)
Format
EXi t

[ fil espec]

Example
The command
*EX
terminates the editing session without renaming the output
It causes EDI to display:

file.

[EXIT]
The output f ilename.f iletype is the
same
as
the
input
filename.filetype.
The version number is one greater than that
of the input file.

2.2.10

INSERT

This command inserts a string immediately following the current line.
The string becomes the new current line.
If a string is not
specified, EDI enters input mode.
Format
Insert [string]
Example
*I TEXT INSERT IN EDIT MODE

Insert
a
immediately
line.

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

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

A RETURN or ESC as the only
character in an input line
causes EDI to return to edit
mode and to prompt for a new
command.

2. 2. 11

line
of
text
after the current

LOCATE

This command causes a search for a 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.
If a string is not specified, the line following the current line is
If n is
considered a match, and the line pointer is positioned there.
specified, the nth occurrence of string is located.

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

Format
[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.

2.2.12

This command moves the current line 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.
n can be used only in the block mode.

A negative

for

current

line

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

command

moves

the

*N -5

2.2.13

NEXT & PRINT

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

that

the

Format
NP [n]
or
NP [-n]
The following conventions can be used in place of issuing
command:
•

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

•

Pressing the ESCape (or ALTmode) key while in the
is the same as an NP-1 command.

•

If n is not specified, then a value of +l is assumed.
2-16

block

mode

LINE TEXT EDITOR (EDI)
Example
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

following

*NP 2
LINE 3 OF THE FILE
* (®)
LINE 4 OF THE FILE
* @
LINE 3 OF THE FILE
*@
LINE 2 OF THE FILE

2.2.14

This command prints 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 1 is assumed.
Format
Print [n]

2-17

LINE TEXT EDITOR (EDI)
Example
Example 2-1 illustrates both the PRINT and the TYPE commands:
Example 2-1 Line Pointer Position for the
TYPE Command and the PRINT Command
Before
File A

File B

Line 1

Line 2

Line 3

Line 4

Line 5

*TYPE 5

*PRINT 5

Line 1

Line 2

Line 3

Line 4

Line 5

*
After

File A

File B

Line 1

Line 2

Line 3

Line 4

Line 5

c) is the Line Pointer

ZK-173-81

2-18

LINE TEXT EDITOR (EDI)
2.2.15

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 process is performed. This command may be used only in block
mode. Refer to Section 2.1.3 for information on how EDI block buffers
are processed.
Format
RENew [n]
Example
*RENEW 10
Ten blocks are transferred consecutively from the input file to
the block buffer. The initial contents of the block buffer and
the next nine blocks are transferred consecutively to the output
file.
The current line pointer points to the first line in the
tenth block, which is currently in the block buffer.

2.2.16

The RETURH Key

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 pressing a series of
RETURNs. This command is equivalent to NP+l (NEXT & PRINT command).
In input mode, a RETURN causes EDI to return from input mode
mode.

2.2.17

edit

RETYPE

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

If a string

Format
Retype [string]
Example
*R THIS IS A NEW LINE
The string THIS IS A NEW LINE replaces the current line.

2.2.18

TOP

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.

2-19

LINE TEXT EDITOR (EDI)
Format

TOF
Example
*TOF
This command writes the previously edited pages into ~he output
file, resets the current line pointer to the top o~ the input
file, and reads the first block into the block buffer.

2.2.19

TOP

This command 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 with TOP, you can
enter lines preceding the first line in the block or file.
TOP differs from TOF in the following ways:
In line-by-line mode, TOP creates a new file and moves the
• current
Unlike TOF, it
line pointer to the top of the file.
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

Example
*TOP
This command directs the current line pointer to the top
current block in block mode.

2.3

the

EDI COMM.ANDS: 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:
•

Setup commands select operating
files, and 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 sequences of EDI
commands.

2-20

conditions,

and

open

LINE TEXT EDITOR (EDI)
•

File input/output commands transfer
input/output, and save files.

text

•

Device output commands send
printer.

terminal

•

Close and exit commands terminate editing operations.

2.3.1

output

and

from

line

Setup Commands

The setup commands
features of EDI.
text access modes,
Setup commands are

allow you to enable or disable certain special
Among these features are the block and line-by-line
and the automatic verification of LOCATE commands.
listed in Table 2-4.
Table 2-4
EDI Setup Commands
Description

Command

Format

BLOCK ON/OFF

BLock [ON] or
BLock OFF

Switch text access modes.

CONCATENATION
CHARACTER

CC [letter]

Change concatenation character
to specified character (default
is &) •

OPEN SECONDARY

OPens filespec

Open specified secondary file.

OUTPUT

output ON or
output OFF

Continue
or
discontinue
transfer
to
output
file
(line-by-line mode).

SELECT PRIMARY

Reestablish
input file.

SELECT SECONDARY

Select opened secondary file as
input file.

SIZE

SIZE n

Specify maximum number of lines
to be read into block buffer.

TAB

TAb [ON] or
TAb OFF

Turn
off.

UPPER CASE
ON/OFF

UC [ON] or
UC OFF

Enable or disable conversion of
lowercase characters
entered
from
terminal
to uppercase
characters.

VERIFY

Verify [ON] or
Verify OFF

Select
whether locator
and
change commands are verified.

ON/OFF

2-21

primary

automatic

file

tabbing

on or

LINE TEXT EDITOR (EDI)
2.3.2

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. These commands are listed in Table 2-5.
The locator commands allow you to:
•

Set the line pointer to either the top or bottom of the
file or block buffer.

input

the line pointer a specified number of lines away from
• Move
its current position.
Move the line pointer
• string.

line

containing

given

text

In edit mode, the RETURN and ESCape (or ALTmode) keys act to relocate
the line pointer.
A RETURN moves the pointer to the next line. An
ESCape moves the line pointer back one line (in block mode only).
In
each case, the line is printed.
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 2-5
EDI Locator Commands
Command

Format

Description

BEGIN or
TOP

Begin
Top

Set current line to the line
preceding top line in
file
(line-by-line mode)
or block
buff er
(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.

(lliJ

(or ALTmode)

Press ESC (or ALT)
key

Print previous line, make it
new current line, or exit from
input mode (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 1.
Set line pointer to located
line.

LOCATE

[n]Locate string

Locate
nth
occurrence
of
string.
In block mode, search
stops at end of block.
(continued on next page)
2-22

LINE TEXT EDITOR (EDI)
Table 2-5 (Cont.)
EDI Locator Commands
Command

Description

Format

Next [n]
Next [-n]

Establish new current line n
lines away from current line.

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

PAGE LOCATE
(Block
Mode only)

[n] PLocate string

Search successive blocks for
the nth occurrence of string.
String may occur anywhere in
line.

Press RETURN Key

Print the next line, make it
the current line, exit from
input mode.

SC /stringl/string2[/]

Locate stringl
with string2.

SEARCH &
CHANGE

2.3.3

and replace it

Text Modification and Manipulation Commands

The text modification and manipulation commands enable you
text. Table 2-6 lists these commands.

modify

Table 2-6
EDI Text Modification and Manipulation Commands
Command
ADD
ADD

CHANGE

Format

Description

Add string

Append string to
line.

current

AP string

Append
the
string to
current line and print
resulting line.

[n]Change/stringl/
string2 [/]

Replace
string 1
with
str ing2 in the current
line n times.
(continued on next page)

2-23

LINE TEXT EDITOR (EDI)
Table 2-6 (Cont.)
EDI Text Modification and Manipulation Commands
Command

Format

Description

DELETE

Delete [n] or
Delete [-n]

Delete
current line and
n-1
lines
if
n
is
positive; delete n lines
preceding current line if
n
is
negative.
[-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.
Erase the current block
buff er and the next n-1
blocks if in block mode.

FORM FEED

Insert form feed
into
block
buffer
(used to
delimit a page).

INSERT

Insert string

Enter string
following
current
line or enter
input mode if string is
not specified.

LINE CHANGE

[n] LC/stringl/
string2 [/]

Change all occurrences of
stringl in current line
(and
n-1
lines)
to
string2.

OVERLAY

Overlay [n)

Delete n lines,
enter
input mode, and insert
new line(s) as typed in
place
of
original
line ( s) •

PASTE

PAste/str ing 1/
string2 [/]

Search
all
remaining
lines in file or block
buffer
for stringl and
replace with string2.

RETYPE

Retype [string]

Replace the current line
with string or delete the
current line if string is
not given.

TOP OF FILE

TOF

Return to the top of the
input file and save all
pages previously edited.

UNSAVE

UNSave [filespec]

Insert all
lines
from
specified file following
current line.
If filespec
is not given, SAVE.TMP is
used.

2-24

LINE TEXT EDITOR (EDI)
2.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. Table 2-7 lists the macro commands.
Table 2-7
EDI Macro Commands
Format

Description

MACRO

MACRO x definition

The
Define macro number x.
value x may be 1, 2, or 3.

MACRO CALL

MCall

Retrieve macro
definitions
stored in file MCALL ;n.

MACRO EXECUTE

[n]Mx [a]

Execute macro x [n] times,
passing
numeric
while
argument [a] •

MACRO
IMMEDIATE

[n] <definition>

Define and execute a macro n
Store it as macro
times.
number 1.

Command

2.3.5

File Input/Output Commands

Input/output commands control the
input/output files, and save files.

movement of text to and from
Table 2-8 lists these commands.

Table 2-8
EDI Input/Output Commands
Command

Description

Format

FILE

FILe filespec

Transfer lines from input file
to both the output file and the
specified file until a form
is
end-of-file
feed
or
encountered.
(Line-by-1 ine
mode only.)

READ

REAd [n]

Read next n blocks of text into
buffer
block
buffer.
If
is
contains text, new text
appended to it.

RENEW

RE New [n]

Write the current block to the
output file and read new block
from the input file.
(continued on next page)

2-25

LINE TEXT EDITOR (EDI)
Table 2-8 (Cont.)
EDI Input/Output Commands
Description

Format

Command
SAVE

SAve [n]

WRITE

Write

2.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 UFO on
the device for the file you are
editing.
You can override the
default
by
specifying
a
different device and UFO.
Write contents of block buffer
to output file and erase block
buffer.

These commands direct output to your terminal or to
{CL:). They are listed in Table 2-9.

pseudo

device

Table 2-9
EDI Device Output Commands
Command

Description

Format

LIST ON TERMINAL

List

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
the
pseudo
device CL:.

Pr int [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.

2-26

LINE TEXT EDITOR (EDI)
2.3.7

CLOSE and EXIT Commands

The CLOSE and EXIT commands terminate EDI operations and write the
remainder of the input file into output file.
Table 2-10 lists these
commands.
Table 2-10
EDI Close Operation Commands
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 il espec]

Same as CLOSE except that input
file
is deleted.
EDI> prompt
is issued.

Type a control Z

Close files and terminate EDI.

EXi t

[ filespec]

Close files,
rename
output
file, and terminate EDI.

EDx [ f i1 espec]

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
delete
output
file.
prompt is issued.

Command

EXIT
EXIT

DELETE

KILL

2.4

files,
EDI>

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.

2.4.1

ADD

ADD causes the specified string to be appended to the current line.
Format
Add string
For examples and information describing
Section 2. 2. 1.
2-27

how

use

ADD,

refer

LINE TEXT EDITOR (EDI)
ADD & PRINT (AP)

2.4.2

ADD & PRINT performs the same function as ADD except that the new line
is printed.
Format
AP string
For examples and information describing how to use ADD & PRINT,
to Section 2.2.2.

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

*B
In this example, the current line pointer is moved to the top
the block buffer (block mode is assumed).

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

Format
BLock [ON]

or
BLock OFF

2-28

It is assumed when

when

neither

LINE TEXT EDITOR (EDI)

Example
*BLOCK ON
This command causes EDI to switch to block mode.
of text is read into the block buffer.

The next

block

BOTTOM

2.4.5

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,
2. 2. 3.

2.4.6

refer

Section

and,

found,

refer

Section

CHANGE

CHANGE searches for string!
replaces it with string2.

the

current

line

Format
(n] Change /stringl/string2(/]
For examples and information on how to use CHANGE,
2.2.4.

2.4.7

This command transfers all rema1n1ng 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 renamed to the
file spec. 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

Format
CLose ( filespec]

Example
*CL
EDI>
This command closes both input and output files, and EDI
to the initial command sequence.

2-29

returns

LINE TEXT EDITOR (EDI)
2.4.8

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.

Format
CLOSES

CLOSE & DELETE (CD)

2.4.9

This command transfers
input file
(in that
files. The input file
included, the output
acts like CLOSE except

all remaining lines in the block buffer and the
order)
into the output file, and closes both
is then deleted.
If a file specification is
file is renamed to the file spec. This command
that the input file is deleted.

If a secondary file was opened during the editing session and was
closed, it remains open.

not

Format
CDl [filespec]

2.4.10

CONCATENATION CHARACTER (CC)

The concatenation character allows you to give commands on one input
line.
By default, the concatenation character is the ampersand (&).
To reference text containing an ampersand (for example, in LOCATE or
CHANGE commands), you must change the concatenation character to some
other character.
If the CC command is used without an
character is changed to the ampersand.

argument,

the

concatenation

Format
CC [letter]

Example
*CC :
*L A&B:C /A&B/ABC/
CONCATENATION TEST CONTAINING A&B.
CONCATENATION TEST CONTAINING ABC.
*CC
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 changes the
default
character from the ampersand to the colon.

2-30

concatenation

LINE TEXT EDITOR (EDI)
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 colon.)
The third command line changes the concatenation
to the normal default value, &.

2.4.11

character

back

CTRL/Z

CTRL/Z is a Command Line Interpreter (CL!)
function that terminates
EDI.
For usage information on CTRL/Z, refer to Section 2.2.5.

2.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,
2.2.6.

2.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 2.2.7.

2.4.14

PRINT,

refer

END

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,
however, that if the last line was deleted before you issued END, the
pointer will be located past the text, and thus the last line will not
be printed. END performs the same function as BOTTOM.
Format
End

2-31

LINE TEXT EDITOR (EDI)
Example
*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).

2.4.15

the

ERASE

In line-by-line mode, this command erases the current line.
In this
mode, n can 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.
Format
ERASE [n]
Example
*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.

2.4.16

The ESCape Key

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
block, one line at a time, by pressing a series of ESCapes.
Pressing
ESCape is equivalent to typing NP-1 (NEXT & PRINT command).
If EDI is in input mode, ESC acts like RETURN and terminates a line of
input. ESC also exits from input mode if it is the first character of
the line.

2.4.17

EXIT

EXIT writes all rema1n1ng records
files, and terminates EDI.

the

output

file,

closes

the

For examples and information on how to
2.2.9.

use

EXIT,

refer

Section

This command functions in the same way as the CLOSE & DELETE
except that EDI also terminates.

command

Format
EXIT [filespec]

2.4.18

EXIT & DELETE (ED)

2-32

LINE TEXT EDITOR (EDI)
Format
EDx [filespec]
Example
*EDX NEWFILE.DOC
[EXIT]

2.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 (that is, 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.
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.

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

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
string is found.
Format
[n]Find [string]

2-33

LINE TEXT EDITOR (EDI)
Example
*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.

2.4.21

FORM FEED (FF)

This command allows you to insert form feeds into the text to delimit
pages.
The form feed is inserted after the current line. The line
containing the form feed then becomes the new current line.
Format
FF
Example
*P
THIS IS THE IAST LINE ON THE PAGE
*FF
In this example, a form feed is inserted into the text
the current line.

2.4.22

following

INSERT

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,
2.2.10.

2.4.23

refer

Section

KILL

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.
Format
KILL
Example
*KILL
EDI>

2-34

LINE TEXT EDITOR (EDI)
In this example, the output file is deleted and EDI displays
prompt:

the

EDI>
At this point, you can return control to your CLI by means
CTRL/Z or enter a file specification for a file to be edited.

2.4.24

LINE CHARGE (LC)

This command is similar to CHANGE except that all occurrences of
stringl 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 not given, all occurrences of stringl are deleted. New
lines are printed if the VERIFY ON command is in effect.
If stringl is given, but EDI cannot locate the string in the
line, EDI prints [NO MATCH] and returns the asterisk prompt.

current

Format
[n]LC /stringl/string2[/]
Example
If the current line is:
THES ES THE LINE TO BE ESSUED.
The following commands would correct the errors:
*V ON
*LC /ES/IS
THIS IS THE LINE TO BE ISSUED

2.4.25

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 synchroni?.ation 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
Example

*LI
This command causes all rema1n1ng lines in the block buffer or
all rema1n1ng lines in the input file to be printed on the
terminal.

2-35

LINE TEXT EDITOR (EDI)
2.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.

Format
LP

Example
*LP

This command causes all rema1n1ng lines in the block buffer or
all remaining lines in the input file to be printed on the pseudo
device CL:.

2.4.27

LOCATE

LOCATE searches for a string beginning at the line following the
current line. The string can occur anywhere in the lines searched.

Format
[n] Locate string
For examples and information on how to use LOCATE,
2.2.11.

2.4.28

refer

Section

MACRO

This command is used to define macros. Space is available for three
macro definitions.
The definition 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 with 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.

Format
MACRO x definition

x
Specifies the macro number (1, 2, or 3).

2-36

LINE TEXT EDITOR (EDI)
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 occurrences 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

2.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, and so on.
The file used to store the macro definitions must be the latest
version of file MCALL -- that is, MCALL;n. The file type must be null
or blank. If the macro definitions to be loaded are in a file of
another name, you can use PIP with the /NV switch, to rename the file.
{Refer to Chapter 3 for descriptions of PIP commands.)

Format
MCall
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
call.

macro

Example
*MC
This command retrieves the macro definitions stored in file
MCALL;n, where n represents the latest version of the file MCALL.

2-37

LINE TEXT EDITOR (EDI)
2.4.30

MACRO EXECUTE

This command executes a macro n times while passing it an optional
numeric argument a.
If a macro numeric argument is defined with 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 by
means of a MACRO command or called with a MACRO CALL command.
Use the MACRO EXECUTE command to execute any one of the three macro
definitions stored in the EDI macro storage area any number of times.

Format
[n]Mx [a]
n

Specifies the number
executed.

times

the

macro

x
Specifies the macro number (1, 2, or 3).

a
Specifies the numeric argument to be passed when the
macro is executed
(ignored
if the argument % is not
present in macro definition).
Examples
*2Ml
Execute macro number 1 twice.
*3M2 5
Execute macro number 2 three times, passing the numeric
5 each time the macro is executed.

argument

The example in Section 2.6.4 illustrates how to use the EDI macro
commands in editing a file.

2.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 1 storage area
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<defini ti on>

2-38

LINE TEXT EDITOR (EDI)
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 2.6.3 illustrates the
IMMEDIATE command.

2.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
2.2.12.

2.4.33

use

NEXT,

refer

Section

NEXT & PRINT

NEXT & PRINT performs the same function NEXT performs except that
new current line is displayed.

the

Format
NP [n]
or
NP [-n]
For examples and information on how to use
Section 2.2.13.

2.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 by means
of the SELECT SECONDARY command (SS) for input.
Format
OPens filespec
Example
*OPENS RICKS.MAC
*SS
*READ 1
The file RICKS.MAC is opened as a secondary input file, then
first block is read in.

2-39

the

LINE TEXT EDITOR (EDI)
2.4.35

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.
Format
OUtput ON
or
output OFF
If neither ON or OFF is specified, ON is assumed.
Example
*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 not 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.

2.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.
Format
Overlay [n]
Example
*O 2
This command deletes two lines and
mode.

2-40

causes

EDI

enter

input

LINE TEXT EDITOR (EDI)
2.4.37

PAGE

This command causes EDI to enter block mode, if not already in it, 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
PAGe n
Example
*PAG 1
[00050 LINES READ IN]
[00050 LINES READ IN]
[00050 LINES READ IN]
[00050 LINES READ IN]
(00017 LINES READ IN]
[PAGE l]

*
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 (that is,
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.

2.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 can be used only in
block mode.
Format
[n]PFind string

2.4.39

PAGE 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 can be used only in block mode.

2-41

LINE TEXT EDITOR (EDI)
Format
[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 the string.

2.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 string! 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, EDI returns the asterisk (*) prompt. When the
command completes, the line pointer is at the top of the buffer or
input file.
Format
PAste /stringl/string2[/]
Example
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:
*PA/Y/T
If the VERIFY ON command is in effect, all corrected
printed. To discontinue printing, type CTRL/O.

2.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
2.2.14.

2.4.42

PRINT,

refer

Section

READ

This command reads the next n blocks of text into the block buffer.
If a block is already in the buffer, the new block(s) is (are)
appended to it.
EDI must be in block mode before this command can be executed.

2-42

LINE TEXT EDITOR (EDI)
A READ command cannot 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 1 is assumed.
must be positive.

The value

Example
*SIZE 15
~READ 4
This example reads four 15-line blocks of the input file into the
block buffer.

2.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
2.2.15.

2.4.44

RENEW,

refer

Section

The RETURB Key

In edit mode, the RETURN key represents the return that displays the
next line in the file or block buffer. In input mode, entering the
RETURN returns EDI to edit mode.
For information on EDI command
modes, refer to Section 2.1.2.
For information on the RETURN key,
refer to Section 2.2.16.

2.4.45

RETYPE

RETYPE replaces the current line with string.
Format
Retype [string]
For information on how to use RETYPE, refer to Section 2.2.17.

2-43

LINE TEXT EDITOR (EDI)
2.4.46

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 on the device for
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 i l espec]

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

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,

EDI does not delete the save file.
volume until deleted.

2.4.47

EDIT.MAC

file,

It remains on

the

input

lines

input

specified

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 the asterisk (*) prompt and the line pointer is
positioned at the end-of-file or the bottom of the block buffer.

2-44

LINE TEXT EDITOR (EDI)
Format
SC /stringl/string2[/]

Example
If the following incorrect
block:

line

contained

the

current

THES IS THE LINE TO BE ISSUED.
the following commands 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.

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

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.

2-45

LINE TEXT EDITOR (EDI)
2.4.49

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 Section 2.4.28.

2. 4. 50

SIZE

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 depends 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 the
discussion of block mode in Section 2.1.3.)
Format
SIZE n
Example
*SIZE 50
This command conditions EDI to read 50 lines
buffer during a single READ or RENEW command.

2.4.51

into

the

block

TAB 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.
Format
TAb [ON)
or
TAb OFF
If neither ON nor OFF is specified when a TAB command is
ON is assumed.

2-46

issued,

LINE TEXT EDITOR (EDI)
Example
*TAB ON
*I
; THIS IS A SAMPLE OF TABBING.
THIS LINE GETS A TAB
1: THIS ONE DOESN'T
END
*TAB OFF
*N -3
*P 4
; THIS IS A SAMPLE OF TABBING.
THIS LINE GETS A TAB
1: THIS ONE DOESN'T
END

2.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 by means of TOP, you can insert
lines preceding the first line in the file.
Format
Top
For examples and information on how
2.2.19.

2.4.53

use

TOP,

refer

Section

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

2.4.54

use

TOF,

refer

Section

TYPE

This command is similar to the PRINT command
{Section 2.2.14).
In
line-by-line mode, the two are identical. In block mode, TYPE does
not move the l~ne pointer after displaying the requested text unless
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.

2-47

LINE TEXT EDITOR (EDI)
Format
TYpe [n]
Example
See the example of the PRINT command (Section 2.2.14).

2.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 default
file is 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.
Format
UNSave [filespec]
Example
File SEC.DAT;! contains a group of lines to be inserted after the
current
line.
The following command performs the desired
operation.
*UN S SEC • DAT; 1

Section 2.6.2 contains an
commands.

2.4.56

example

using

the

SAVE

and

UNSAVE

UPPER CASE ON/OFF

This command allows you to enter lowercase characters from a terminal
and have them converted to uppercase characters.
If UPPER CASE OFF is
issued, all input characters are accepted as they are entered,
including the EDI commands.
Format
[ON]
or
UC OFF
UC

If neither ON nor OFF is specified, then ON is assumed.
Example
*UC OFF

*I this line is entered in lowercase
*'UC ON

*I this line is converted to uppercase
Assuming that the input terminal
is capable of generating
lowercase input, the commands in the example would create the
following lines in the output file.
this line is entered in lower case
THIS LINE IS CONVERTED TO UPPER CASE

2-48

LINE TEXT EDITOR (EDI)
However, in both instances, the characters
uppercase before the file is closed.

are

converted

To create a file containing lowercase characters, use the MCR SET
/LOWER=TI:
or the DCL SET TERM LOWER command and the EDI UC OFF
command.

2.4.57

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. VERIFY ON is
the default when EDI is started.
Format
Verify [ON]
or
Verify OFF
If neither ON nor OFF is specified, ON is 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 VERIFY ON, EDI automatically
prints the line.

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

2-49

LINE TEXT EDITOR (EDI)
2.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.

all

•

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 the resulting file on disk, do one of the following:
- Transfer the file to disk and perform the editing there.
- Edit the file on DECtape and then use PIP or FLX to transfer
the file to disk.

•

To use a device other
command.

than

SY:,

mount

with

the

MOUNT

To edit a version
• explicitly
state

of a file other than the latest one,
the desired version number in the file
The
specification. This file is opened as the input file.
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 or the
DCL DELETE command.

•

EDI accepts variable-length
characters long.

•

The record type of
variable-length.

•

EDI preserves the record attributes of the input file.
For
example, the FORTRAN carriage control attribute is preserved
in the output file.

•

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.

•

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.

output

input

files

2-50

lines

edited

up
by

EDI

132 (10)

always

LINE TEXT EDITOR (EDI)
2.6

SAMPLE EDITING OPERATIONS

Sample editing operations are included in this section
how the various EDI commands can be used:

illustrate

•

A file is edited using a few basic EDI commands.

•

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 manner shown in the second example.

•

An immediate macro command is defined and executed in a single
step.

•

A file containing errors is edited using the macro commands.

2.6.1

File Editing Sample

>EDI PRTBLD.CMD
[PAGE
1)
*P *
COMMAND FILE TO BUILD
PRNT SYMBIONT
FOR RSX-llM MAXXED SYSTEM

File PRTBLD.CMD is opened for editing. A PRINT * command
is issued to print the contents of the file. The following
errors are detected:
1 - PRNT should be PRINT.
2 - MAXXED should be MAPPED.

;

[l,54]PRT/MM/-CP,LP:=PRTBLD/MP

3 - /-CP should be /CP.

;

; OPTIONS

STACK=40
PAR=PARK:O:lOOOO
UNITS=4
TASK=PRT •••
ASG=C0:2,LP:3
PRI=60
UC=[lO,l]
SPECIFY
SPECIFY FLAG WHICH CONTROLS
FILE DELETION AFTER PRINTING

4 - INPUT should be appended to the line containing the
word OPTIONS.
5 - PARK should be PAR4K.

6 - uc should be UIC.
7 - The line containing

SPECIFY should be deleted.

TO ENABLE DELETION USE
GBLPAT=PRT;$DELET:l
TO INHIBIT DELETION USE
DEFAULT FROM ASSEMBLY IS
FILE DELETION ENARBLED
GBLPAT=PRT:$DELET

[*EOB*]

8 - The comment line containing the format used to inhibit
deletion is missing.
9 - ENARBLED should be ENABLED.
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.

2-51

LINE TEXT EDITOR (EDI)
*TOP
[PAGE
l]
*PL PRNT
; PRNT SYMB !ONT
*c/RN/RIN/
; PRINT SYMBIONT

; 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]

*
I

*; SPECIFY
*DP
; SPECIFY FLAG WHICH CONTROLS
*PL INH
; TO INHIBIT DELETION USE
*I
GBLPAT=PRT:$DELET:O
*PL RB
; FILE DELETION ENARBLED
*C/R//
, FILE DELETION ENABLED

*;
*
GBLPAT=PRT:$DELET
*AP : 1
GBLPAT=PRT:$DELET:l
*TOF
[PAGE
1]
*P *
COMMAND FILE TO BUILD
PRINT SYMBIONT
FOR RSX-llM MAPPED SYSTEM

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 corrected line is displayed automatically.
2 - A 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 line 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 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.
7 - The line pointer is moved down two lines by means
of a 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.
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 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.
10 - The line pointer is moved down two lines using two
RETURNS to locate the last line in error.
An ADD AND PRINT command is issued to append
:1 following the word $DELET.
The necessary corrections are complete, so the line pointer
is moved to the top of the file by means of a TOF command.
A PRINT * command is issued to print the complete file
with all corrections

2-52

LINE TEXT EDITOR (EDI)
[l,54]PRT/MM/CP,LP:=PRTBLD/MP
I

; OPTIONS INPUT
STACK=40
PAR=PAR4K:O:l0000
UNITS=4
TASK=PRT •••
ASG=CO: 2, LP: 3
PRI=60
UIC=[lO,l]
SPECIFY FLAG WHICH CONTROLS
FILE DELETION AFTER PRINTING
TO ENABLE DELETION USE
GBLPAT=PRT:$DELET:l
TO INHIBIT DELETION USE
GBLPAT=PRT:$DELET:O
DEFAULT FROM ASSEMBLY IS
FILE DELETION ENABLED
;

GBLPAT=PRT:$DELET:l
I
[*EOB*)
*EX
[EXIT)

2.6.2

An EXIT command is issued to close the file and
terminate the editing session.

SAVE and UNSAVE Sample

*LI
THIS IS LINE l PAGE
THIS IS LINE 2 PAGE
THIS IS LINE 3 PAGE
THIS IS LINE 4 PAGE
THIS IS LINE 5 PAGE
[*EOB*)

l
l
l
1
l

The line pointer is returned to the top.
A SAVE command is used to save the
five lines in a separate file.

*SA 5 SAVl. DAT
*T
*SA 5 SAV2. DAT
*CL
EDI>SAVl. DAT
[PAGE
1)
*LI
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
[*EOB*)

The file to be used in this example is
printed using the LIST command.

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

2-53

LINE TEXT EDITOR (EDI)
*PA/PAGE l/PAGE 2/
THIS IS LINE 1 PAGE 2
THIS IS LINE 2 PAGE 2
THIS rs LINE 3 PAGE 2
THIS IS LINE 4 PAGE 2
THIS IS LINE 5 PAGE 2
*CL
EDI>SAVE2. DAT
[PAGE
l]
*LI
THIS IS LINE l PAGE l
THIS IS LIN~ 2 PAGE l
THIS IS LINE 3 PAGE l
THIS IS LINE 4 PAGE l
THIS IS LINE 5 PAGE l
[*EOB*l

A PASTE command is used to change
PAGE l to PAGE 2 in all lines.

*PA/PAGE l/PAGE 3/
THIS rs LINE l PAGE 3
THIS rs LINE 2 PAGE 3
THIS IS LINE 3 PAGE 3
THIS IS LINE 4 PAGE 3
THIS IS LINE 5 PAGE 3
*CL
EDI>START.DAT
[PAGE
l]
*BO
THIS rs LINE 5 PAGE l
*UNS SAVl.DAT
*UNS SAV2.DAT
*T
*LI
THIS IS LINE l PAGE l
THIS IS LINE 2 PAGE l
THIS IS LINE 3 PAGE l
THIS rs LINE 4 PAGE l
THIS IS LINE 5 PAGE 1
THIS rs LINE l PAGE 2
THIS rs 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 l PAGE 3
THIS IS LINE 2 PAGE 3
THIS rs LINE 3 PAGE 3
THIS rs LINE 4 PAGE 3
THIS IS LINE 5 PAGE 3
[ *EOB*]
*EX
[EXIT]

A PASTE command is used to change
PAGE l to PAGE 3 in all lines.

The first save file is closed.
The second save file is opened.
The LIST command is used to display
the contents of the file.

The second save file is closed.
The original input file is opened again.
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 f i1 e.

2-54

LINE TEXT EDITOR (EDI)

2.6.3
*LI
ABC
ABC
ABC
ABC
ABC

Use of MACRO IMMEDIATE Command
A LIST command is issued to print
the file used in this example.

IN LINE 1 - ABC
IN LINE 2 - ABC

IN LINE 3 - ABC
IN LINE 4 - ABC
IN LINE 5 - ABC

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

The immediate macro is defined
and executed to find the first
four lines that 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.

*
2.6.4

Use of Macro Commands

*LI
THIS LITTLE FILE HAS
MANY CONNON ETTORS SO
WE CAN SHOW YOU HOW
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/
*M3
THE MACRO CONNANDS CAN
FIRST, THE DESIRED MACRO
MUST BE DEFINED; THE LINE
WITH AN ETTOR, AND THEN, THE
IS !SS UE D TO C OTTECT THE
*NP2
MANY CONNON ETTORS SO
*Ml
MANY COMMON ETTORS SO
*M2

The LIST command is used to print the
file and the file is checked for errors.
The following errors are located.
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
of THE (see macro 3).

The three macro definitions that will
correct the errors are typed.
Macro 3 is used to change all YHE
strings to THE.

NP2 is used to locate a line with errors.
Ml is used to change NN to MM.
M2 is used to change TT to RR.

2-55

LINE TEXT EDITOR (EDI)
MANY COMMON ERRORS SO
"NP2

THE MACRO CONNANDS CAN
*Ml
THE MACRO COMMANDS CAN

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 string
and change it to RR.

*M2

WITH AN ERROR; AND THEN, THE

MACRO EXECUTE CONNAND
*Ml
MACRO EXECUTE COMMAND

A RETURN is used here to locate the next line
in error.
Ml is used to change NN to MM.

*M2

IS ISSUED TO CORRECT THE
*M2

ERROR
*T

*LI
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 EXEC UTE C<JttMAND
rs ISSUED TO CORRECT THE
ERROR.
[ *EOB*]

2.7

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.

EDI ERROR MESSAGES

The four classes of EDI error messages are:
•

Command level information messages

•

File access error messages

•

Error messages requiring EDI to restart

•

Fatal error messages

The following sections describe all the messages that can be displayed
in each class. If the recovery procedure is not evident, a suggested
user action is given.

2-56

LINE TEXT EDITOR (EDI)
2.7.1

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 are 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.
[BUFFER CAPACITY EXCEEDED BY]
off ending 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 by using 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.
Occasionally, this message results when you try to open a file
that was not created by EDI.
You can overcome this difficulty by
using the SIZE command procedure that follows:
1.

Type KI LL.

When EDI prompts for a
nonexistent file name.
input mode.

Use the RETURN key 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.

new file specification, enter a
EDI creates a new file and enters

into

[CREATING NEW FILE]
INPUT
Explanation: The input file specified with 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.

2-57

LINE TEXT EDITOR (EDI)
User Action: If you intend to create a new file, continue
entering new lines as required. Otherwise, enter edit mode by
pressing RETURN and 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 (for example, a READ command in line-by-line mode).
[ILL NUM]
Explanation: Either you have supplied a nonnumeric character
when a numeric is required or you have given a negative number
when a positive number is required.
[ILL STRING CONST]
Explanation: A search string specified in a CHANGE, LC, PASTE,
or SC command does not contain a matching string termination
character (for example, 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.
[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 the PIP /RE switch or the DCL RENAME command 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

2-58

desired

LINE TEXT EDITOR (EDI)
[MACRO NUMERIC ARG UNDEFINED]
Explanation:
You have tried to execute a macro without supplying
a numeric argument.
The macro definition contains a percent (%)
character and thus demands a numeric argument.
specifying

the

Explanation:
You have issued an MCALL command to retrieve a
of macros, but the file MCALL cannot be found.

set

User Action:
Reenter
the
appropriate numeric argument.

command

line,

[MCALL FILE DOES NOT EXIST]

User Action:
The desired set of macro definitions may exist
under another User File Directory.
If this is the case, use PIP
or the appropriate DCL commands to copy or rename the MCALL file
into the current directory.
[NO INPUT FILE OPEN]
Explanation:
You have issued a
PAGE,
READ, or RENEW command
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:
You have issued a CHANGE command with a
be changed that is not in the current line.

string

[OVERLAYING PREVIOUSLY DEFINED MACRO]
Explanation:
You have issued a MACRO command that redefines a
previously defined macro.
This message lets you know that the
. previous definition is no longer in effect.
[SAVE FILE 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 provide 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:
command and
command.

Close the secondary input file
using
the CLOSES
then open the desired secondary file with the OPENS

2-59

LINE TEXT EDITOR (EDI)
[SECONDARY FILE CURRENTLY SELECTED FOR INPUT]
Explanation: You have issued a CLOSE or KILL command 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:
incorrect.

You

entered

command

that

syntactically

[TOO MANY CHARS]
Explanation: A CHANGE,
LC,
PASTE,
SC, or ADD command has
resulted in a line that contains too many characters.
EDI limits
the length of a line to 132(10) characters.
User Action:
valid.

Reenter the command line to ensure that the line is

[*BOB*]
Explanation: You have reached the beginning-of-buffer.
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.
[*EOB*]
Explanation: You have reached the end-of-buffer.
The current
line pointer now points to the end of the buffer. Thus, if new
lines are inserted, they appear after the last text in the
buffer.
[*EOF*]
Explanation:

You have reached the end-of-file 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.

2.7.2

File Access Error Messages

Messages in this class mean that you have tried to access directories,
files,
or devices that are not present in the host system.
Each
message is prefixed with:
EDI -After the message is displayed, EDI
prints an asterisk to request input.
The messages in this class follow.

2-60

returns

command

level

and

LINE TEXT EDITOR (EDI)
EDI -- BAD FILE NAME
Explanation: EDI did not accept the file name. The most
error is a file name containing embedded blanks.
User Action:
reenter it.

Make sure that

the

file

name

common

correct,

then

EDI -- DEVICE NOT IN SYSTEM
Explanation:
command and
system.

You have given a FILE, OPENS,
SAVE, or UNSAVE
specified a devic~ 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 and specified
a User File Directory that does not exist on the specified
volume.
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 (SPR).
EDI -- BAD DEVICE NAME
EDI -- DEVICE NOT READY
EDI -- FILE ALREADY OPEN
EDI -- RENAME NAME ALREADY IN USE
EDI -- RENAME ON TWO DIFFERENT DEVICES
EDI -- WRITE ATTEMPT TO LOCKED UNIT

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

2-61

LINE TEXT EDITOR (EDI)
As with file access messages, each message in this class
with:

prefixed

EDI
After the appropriate message has been displayed, EDI prompts with:
EDI>
You may terminate the editing session at this point by pressing 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 the 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 9.
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.

then

reenter

the

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 reads of
reenter the command line.

the

file

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

2-62

LINE TEXT EDITOR (EDI)
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
Thus, the
close the file (for example, the task was aborted).
file attributes were not written and the file may contain
inconsistent data.
User Action:
Exit from EDI by pressing RETURN or CTRL/Z.
Use
the PIP /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 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(10) bytes.
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
Thus,
the
close the file (for example, the task was aborted).
file attributes were not written and the file may contain
inconsistent data.
User Action:
Use the PIP /UN switch to unlock the
Reinitiate EDI and try to recover the data in the 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
Re po rt ( S PR ) •

2-63

file.

LINE TEXT EDITOR (EDI)
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

2.7.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.
You may work with the following procedures on the truncated version of
an output file to save the editing performed before the fatal error
occurred.
1.

Use the PIP /RE switch or the DCL RENAME command to rename
the truncated version of the output file to avoid confusion.

Restart the editing session to the original input file.

Issue an OPENS command, specifying the renamed
secondary file.

Issue an SS command to select the secondary file for input.

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.

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.

2-64

that

the

file

last

block

the

was

LINE TEXT EDITOR (EDI}
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.
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.
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 to.
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, or use the DCL PURGE and DELETE
commands.
EDI -- FILE HEADER CHECKSUM ERROR
(primary input, secondary input,
Explanation: An input file
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

9.
EDI -- FILE HEADER FULL
Insufficient retrieval pointer space exists in the
Explanation:
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.

that

is
write-locked.
User Action:
Unlock the device
if
it
Otherwise, a hardware problem may exist. Consult your DIGITAL
Field Service representative.

2-65

LINE TEXT EDITOR (EDI)
EDI -- INDEX FILE FULL
Explanation: The file header block is not available to create an
ou~put
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, or use the DCL PURGE or DELETE
commands.
NOTE
The following error messages signify
hardware problems. If possible, remove
all important files from the volume,
then contact your local DIGITAL Field
Service representative.
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.
If such a failure
occurs, contact your local DIGITAL Field
Service representative.
EDI -- BAD DIRECTORY FILE
EDI -- BAD PARAMETERS ON A QIO
EDI -- INVALID FUNCTION CODE ON A QIO
EDI -- NO BLOCKS LEFT
EDI -- REQUEST TERMINATED

2-66

LINE TEXT EDITOR (EDI)
EDI

UNEXPECTED ERROR - EDITOR WILL ABORT

EDI -- WRITE ATTRIBUTE DATA FORMAT ERROR
TASK " ••• EDI" TERMINATED

2-67

CHAPTER 3
PERIPHERAL INTERCHANGE PROGRAM (PIP)

The Peripheral Interchange Program (PIP) is a 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:
•

Copying files from one device to another

•

Deleting files

•

Renaming files

•

Listing file directories

•

Setting the default device and UIC for PIP operations

•

Unlocking files

•

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

3.1

PIP COMMAND LINE

You request PIP functions by entering PIP command lines through the
initiating termjnal or by means of an indirect command file.
The
maximum nesting level for indirect command files
is four.
(Using
indirect command files is described in Chapter 1.) The format of PIP
command lines differs for each function.
Therefore, the command
line
formats are described in separate sections.

3.1.1

PIP Defaults for File Specification 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.
In the following
example,
Tl.MAC;S sets the defaults for
the
subsequent file specifications in the command
line.
Then, T2 is
specified and overrides Tl as the default filename;
however,
.MAC
remains the default file type.
Finally, .TSK is specified, which
overrides .MAC as the default, while T2 remains the deEault file name.

3-1

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Note, in this example, that the version number does not default.
PIP>Tl.MAC;5,T2,.TSK/BR
Tl.MAC; 5
T2.MAC; 1
T 2. TSK; 3
Table 3-1 summarizes the rules PIP uses to set defaults.
Table 3-1
PIP Default File Specifications
Element

Default Value

dev:

For the first file specification, the unit on which
the user's system disk is mounted (SYO:) or the
default that you specify with the /DF switch
(see
Section
3.2.2.6).
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 User
Identification .Code or UIC (that is, the UIC under
which you log on), the UIC you specify with the SET
command, or the default you specify with the /DF
switch (see Section 3.2.2.6). For subsequent file
specifications, either you explicitly specify a new
User File Directory or PIP assumes the UFD from the
previous
specification.
Only
the
asterisk
specification is valid as a wildcard
(see Section
3.1.3).

filename

No default for the first file specification.
For
subsequent file specifications, the last file name
that you explicitly specified.
Asterisk and/or
percent sign specifications are valid as wildcards
(see Section 3.1.3).

• f i l etype

No default for the first file specification.
For
subsequent file specifications, the last file type
that you explicitly specified.
Asterisk and/or
percent sign specifications are valid as wildcards
(see Section 3.1.3).

;version

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
exist in the output directory.
An
exception is the PIP file delete function, which
requires that a version number be specified.
An explicit version number is defined to be of the
form ;n where n is greater than 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,
just the asterisk (wildcard) may be
specified, as described in Section 3.1.3.

3-2

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.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 switch
or subswitch can have arguments that are separated from the switch or
subswitch name by a colon (:).
To allow several commands to be performed consecutively, more than one
command can be specified in a line. To separate each command, the
ampersand character (&) is used.
Most of the PIP switches operate on lists of file specifications. The
exceptions are /DD, /DF, /ID, and /TD, which are used by themselves.
Table 3-2 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 in Section 3.2.2.
Table 3-2
PIP Switches and Subswitches
Switch

Subswitch

/AP

Function
Appends file(s)
file.

/FO

to the end

existing

Specifies the file owner for a file.

/BS:n[.]

Defines the blocksize for magnetic tape.

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

/DD

Restricts file searches to files
during a specified period of time.

/DF

Changes PIP's default device and/or UFD.

Enters a synonym for a file in
file.

/NV

created

directory

Forces the version number of a file
greater than the latest version.

/EOF[:block:byte]

Specifies
file.

for

/EX

Excludes one file specification's
files during file searches.

worth

the

end-of-file

pointer

one

(continued on next page)

3-3

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-2 (Cont.)
PIP Switches and Subswitches
Switch

Subswitch

Function

/FI:filenum:seqnum

Accesses a file by its
number (file-ID).

/FR

Displays the amount of available space on
the specified volume, the largest contiguous
free space on that volume, and the number of
available file headers.

/ID

Identifies the version of PIP being used.

/LI

Lists directory files.
/BR

file

identification

Lists a directory file in brief format
alternate mode for the /LI switch).

(an

/FU[:n[.]] lists a directory file in full
format
alternate mode for the /LI switch).

(an

/ME

Lists the total number of blocks used for a
directory,
along with the total number
blocks allocated and the number of files in
that directory (an alternate mode for the
/LI switch).
Concatenates two
file.

files

into

one

/BL:n[.]

Allocates a number (n) of contiguous blocks.

/CO

Specifies that
contiguous.

/FO

Specifies the file ownership for a file.

Forces the version number of a file
greater than the latest version.

/SU

Supersedes (replaces) an existing file.

the

output

file(s)

/NM

Suppresses certain PIP error messages.

/PR

Changes the protection status of a file.
/FO

one

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.
(continued on next page)

3-4

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-2 (Cont.)
PIP Switches and Subswitches
Switch

Function

Subswi tch

/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

Specifies that records may span disk block
boundaries when copied from magnetic tape.

/SD

Selectively deletes files by prompting
your response before deleting.

for

/SP[:n[.]]

Spools files
printing.

printer

for

/SR

Allows shared reading of a file that has
already been opened for writing by another
user or task.

/TD

Restricts file searches to files created
the current day.

/TR

Truncates files 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

Specifies the owner for a file.

Switches and subswitches are described in the following sections.

3.1.2.1 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
device name, the UFD, the file name, file type, or version of the file
on which it is to operate.
You may specify a switch once for a list of file specifications.
example:

For

f ilespecl,f ilespec2,filespec3/DE
The /DE switch applies to all of the file specifications.
every specified file from its UFD.

3-5

PIP deletes

PERIPHERAL INTERCHANGE PROGRAM (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.

3.1.2.2 Subswitches - You can apply subswitches to ·one or more file
specifications,
depending
on
the placement of the subswitch.
Subswitches can appear in either the output file specification or the
input file specification.
If you place the subswitch in the output file specification, the
subswitch applies to the entire list of input file specifications.
For example, the Contiguous Output switch (/CO)
is applied to both
TEST.TSK and SAMP.DAT.
(The /CO switch is used with the Copy
function.
See Section 3.2.1.)
PIP>/CO=TEST.TSK;l,SAMP.DAT;l
PIP copies TEST.TSK;l and SAMP.DAT;l such that the copies,
and SAMP.DAT;2, are contiguous.

TEST.TSK;2

If you place the subswitch in the input file specification, it usually
applies only to the file specification that immediately precedes it.
In the following example, the New Ve·rsion subswitch (/NV)
is applied
to the file ASDG.MAC.
{The /NV subswi tch is being used with the
Rename switch, /RE.)
PIP>*.SMP=PRT2.QRT,ASDG.MAC/NV,KG.MAC/RE
PIP renames the files PRT2.QRT and KG.MAC, 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 th~ latest
version of file ASDG.SMP
(assuming a version of ASDG.SMP already
exists).
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.

Example
PIP>FILE1.CMD/GR:R/WO,FILE2.MAC/GR:RW
This command is equivalent to:
PIP>FILE1.CMD/GR:R/WO,FILE2.MAC/GR:RW/PR
The command results in the following file protection:
a. FILE 1

SYSTEM
MEMBER
GROUP
WORLD

Unchanged
Unchanged
Read access
No access

b. FILE 2

SYSTEM
MEMBER
GROUP
WORLD

Unchanged
Unchanged
Read/write access
Unchanged

{For more information on altering the protection level of a file,
Section 3.2.2.16.)

3-6

see

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Wildcards

3.1.3

PIP allows you to specify wildcards in file specifications.
The
wildcard characters are the asterisk
(*) and the percent sign (%)
characters.
You can use both wildcards in place of
explicit
specifications for
file names, and types and just the asterisk
wildcard in place of file directories and version numbers.
The asterisk can denote zero or more characters in the field you
specify it in, while the percent sign character can denote exactly one
character in the fields.
(Correct syntax must be followed, however.
See Section 3.1.3.2.)
Wildcards are restricted
in
describe and give examples
specifications.

some cases.
of wildcards

The following sections
in input and output file

3.1.3.1 Wildcards in Output File Specifications - Wildcards in
the
output· file specifications are restricted.
For the following PIP
functions, the output file specification cannot have any wildcards:
•

Concatenating files to a specified file

•

Appending files to an existing file

•

Updating (rewriting) an existing file

•

Listing a directory

If you use wildcards in the output file specification for any of these
functions,
the meaning of the command line would be ambiguous.
For
example:
PIP>LIST.*=[200,200]/LI
You have incompletely specified the output
returns an error message.

file

specification.

PIP

When you make copies of several files, the output specification
be *.*;* or defaulted from the input file specification(s).

must

For the Rename
(/RE)
and Enter
(/EN)
switches,
the
output
specification may have wildcards (asterisk only) 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.

NOTE
The percent sign (%) cannot be
output file specifications.

3-7

used

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.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.

•

*.D*;* means all
beginning with D.

•

TEST.*;* means all versions of all types of files named TEST.

•

T*.*;* means all versions of all types
beginning with T.

•

TEST.DAT;* means all versions of file TEST.DAT.

•

TEST.D%T;* means all versions of files named TEST with
three-character file types beginning with D and ending with T.

•

T%N.*;* means all versions of all file types
of
all
three-character file names beginning with T and ending with N.

•

*·* means the most recent version of all files.

•

*.DAT means the most recent version of all files of file
• DAT.

•

*%.DAT means the most recent version of all files that have at
least one character in their names and have the file type of
• DAT.

•

TEST.* means the most recent version of
files named TEST.

versions

all

files

with

file

files

all

types

with

file

names

type

types

for

377

PIP also provides the following wildcard UFD features:
•

[*,*] means all group,member number
octal) •

combinations

•

[nl,*] means all member numbers under group nl.

•

[*,n2] means all group numbers for member n2.

NOTE
The percent sign (%) character cannot be
used in the UFD.

3.2

PIP COMMAND FUNCTIONS

PIP copies Files-11 files and performs file control functions.
The
copying function and file control functions are described in the
following sections.

3.2.1

Copying Files-11 Files

To copy Files-11 files, you can enter the
specifying any switches.

3-8

PIP

command

line

without

PERIPHERAL INTERCHANGE PROGRAM (PIP)
The simplest format for the PIP command line is:
outf ile=inf ile
out file
The output file specification.
If the output file name,
file
type, and version are either defaulted or *.*;*, the input file
name, file type, and version are used for the output file
(see
/NV and /SU subswitches).
If you explicitly specify 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.
infile
The input file specification.
If the file name, file type,
version fields are not specified, then *.*;* is the default.

and

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 general format of the PIP command line is:
outfile=infilel [,infile2 ••• ,infilen] [[/ME] [/subswitch]]
out file
The output file specification.
infile
The input .file specification.

/ME
The Merge switch.
/subswitch
Specifies any of the subswitches that you can enter as part of
the basic command line or with the Merge switch.
(Table 3-3
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.

3-9

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Examples
1.

PIP>DKl:SAMP.DAT=DK2:TEST.DAT
Copies the latest version of file TEST.DAT {in
UFD) from DK2: to DKl:, naming it SAMP.DAT.

the

current

PIP>DKl: [*,*] =DKO: [11,*]
Copies all files from all members in group number 11 of DKO:
to DKl:.
The files are copied to the same UFD on DKl: that
they were in on DKO:. Note that the user must have write
access to all group number 11 UFOs on DKl:.

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

PIP>DKl:SAMP.DAT=DK2:TEST.DAT;l,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 current UFD. Note the result would be the same if the
/ME switch was not specified.

PIP>DKl:=DB2:TESTPROG.MAC,.OBJ
Copies the latest versions of TESTPROG.MAC and TESTPROG.OBJ
from DB2: to DKl:, using the current UFD for both DB2: and
DKl:.

PI P>DKl: =DKO: *.DAT;*
Copies all versions of all of the files of file type .DAT
the current UFD from DKO: to DKl:.

PIP>DT0:=[200,10]*.*;*
Copies all files under [200,10] from the default device (SY:)
to DTO:, using the current UFD.

PIP>DPO: [200, lO]=DTO:*.*
Copies the latest versions of all files from DTO:
in the
current UFD to DPO: [200,10].
Note that the user must have
write access to [200,10].

3-10

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-3
PIP Copy Command and Merge Subswitches
Subswitch

Description

/BL:n[.]

Blocks Allocated -- This subswitch specifies the
number of 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 can 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 copying from tape.
(PIP allocates file space before the copy operation
is executed.
The length of magnetic tape input
files is on the trailing label for the file.)

/-CO

Noncontiguous Output -- This subswitch specifies
that the output file does not have to be contiguous.
If you do not specify the /BL:n subswitch, the /CO
subswitch, or the /-CO subswitch, PIP defaults to
the size and attributes of the input file.

/FO

Set File Ownership -- This subswitch specifies that
the owner of the output file will be the same as the
output UFD. If you do not specify /FO, the 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
1.

If PIP is running under the UIC

[1,1],

DKO: [200, 200] =DKl: [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,
DKO: [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.
(continued on next page)

3-11

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-3 (Cont.)
PIP Copy Command and Merge Subswitches
Subswitch
/FO (Cont.)

Description
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: [*,*]=DKO: [*,10] *.MAC/FO
Copies all the .MAC files from all group numbers
with member 10 to DKl:, preserving the UFD and
setting the file owner for each file to that
UFD.

/SU

Supersede -- This subswitch allows you to copy one
or more input files to a file whose file name, file
type, and version may already exist in a
UFD.
The
existing file is deleted and a new one is created
with the data from the input file{s).
If the file
does not already exist, it is created.
The output file's name, type, and version number
remain the same, but its file identification number
(file-ID) may be 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 3-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.)

3-12

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Directories Before COPY
INPUT DIRECTORY
[2jl, 2/61]

OUTPUT DIRECTORY
[ ljj, ljj]

RICK.DAT;!

RICK.DAT;2
RICK.DAT;4

Directories After COPY Without /NV Switch Set
{version number preserved)
INPUT DIRECTORY
[ 2,01 I 2,01 J

OUTPUT DIRECTORY
[ 1,0,0 I 1,0,0]

RICK.DAT;!

RICK.DAT;2
RICK.DAT;4
RICK.DAT;!

The command used was:
DKl:(l,6,0,1,0,0] = DK2: [2,01,2,0l]RICK.DAT;l

Directories After COPY With /NV Switch Set
INPUT DI RECTORY
[2,01,2,01]

OUTPUT DIRECTORY
[ l.0f6, l.0f6J

RICK.DAT;l

RICK.DAT;2
RICK.DAT;4
RICK.DAT;S

The command used was:
DKl: [ 1,0,0, 1,0,0 J· = DKl: [ 2,01, 2,01] RICK. DAT; l/NV
NOTE
The version specified with the /NV subswitch must be explicit or default; no
wild cards allowed.
ZK-174-81

Figure 3-1

Results of Copy Command With and Without /NV Specified

3-13

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.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 can specify several PIP switches in a command line with no file
specifications
(that is, they may be entered by themselves).
These
switches include /DD, /DF, /ID, and /TD.
You can specify one or more commands in a line. When using multiple
commands, the ampersand character
(&) separates each command.
For
example:
PIP>TEST.DAT;2=SAMP.DAT;2/SU,SAMP.DAT;l&TEST.DAT;*/FU&SAMP.DAT/PU/LD
1.

PIP merges SAMP.DAT;2 and SAMP.DAT;l into TEST.DAT;2.
The
/SU subswitch causes TEST.DAT's file name, file type, and
version number to remain the same, but TEST.DAT;2's contents
are replaced with the input file's contents.

The /FU switch causes PIP to do a full format listing of
versions of the file TEST.DAT.

all

The /PU switch causes PIP to purge SAMP.DAT and
subswitch causes PIP to list the deleted files.

/LD

the

The values that you specify with the switches and subswitches default
to oqtal.
You can specify decimal values by adding a decimal point
after the value.

3.2.2.l /AP -- Append Switch - The Append switch
(/AP)
opens
an
existing file and appends the input file(s) to the end of it. Specify
the /AP switch in the following format:
outfile=infilel[,infile2 ••• ,infilen]/AP[/FO]
outf ile
The output file specification. Wildcard specifications are not
allowed
in the output file specification. The file type and the
record attributes for the output file remain the same after the
input file(s)
have been appended to it. The file name and file
type for the output file must be specified explicitly.
infile
The input file specification.
If the file name, file
version are not specified, then *.*;* is the default.
/AP
The Append switch.

3-14

type,

and

PERIPHERAL INTERCHANGE PROGRAM (PIP)
/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 3.2.1 for examples of using /FO.

Example
PIP>DKl:FILEl.DAT;l=FILE2.DAT;l,FILE3.DAT;l,FILE4.DAT;l/AP
Opens FILEl.DAT;l on DKl:
and appends
the
FILE2.DAT;l, FILE3.DAT;l and FILE4.DAT;l to it.

contents

Note that if the output file is contiguous before the
it may not be contiguous afterwards.

appending,

3.2.2.2 /BS:n -- Block Size Switch - The Block Size switch (/BS:n)
defines the block size for magnetic tapes. This switch allows you to
read or write bigger blocks onto magnetic tape, thereby saving some of
the space taken by interrecord gaps.
The default block size is
512(10) bytes per block. Specify the /BS switch using the following
format:
outf ile/BS:n=infile

outf ile
The output file specification.
/BS:n[.]
The Block Size switch, where n is an octal
specifying the number of bytes in a block.

decimal

number

infile
The input file specification.
The /BS switch specifies the block size of the output file.
If the
block size specified is smaller than the actual block size, an I/O
error occurs.

Example
PIP>MT:BA.DOC/BS:2048.=AMBER.DOC
This command increases the block size of the output file, BA.DOC,
to 2048(10) bytes per block.

3-15

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.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 explicit or implicit
Merge switch (/ME) and/or with an output magnetic tape device.
Specify the /CD switch in the following format:
outfile/CD=infilel[,infile2 ••• ,infilen]
or
outfile=infilel/CD[,infile2 ••• ,infilen]
outf ile
The output file specification.
infile
The input file specification.
/CD
The Creation Date switch.
Example
PIP>/LI
DIRECTORY DB 1: [200, 200]
21-NOV-80 14: 02
FILE.DAT;7

12.

6-0CT-80 16:13

PIP>TEST.DAT/CD=FILE.DAT/LI
DIRECTORY DBl: [200,200]
21-NOV-80 14: 05
FILE. DAT; 7
TEST.DAT;l

12.
12.

6-0CT-8 0 16: 13
6-0CT-80 16:13

The command creates a new file, TEST.DAT, from FILE.DAT and gives
it the creation date of FILE.DAT rather than the transfer date.

3.2.2.4 /DD -- Default Date Switch - The Default Date switch (/DD)
restricts file searches to files created during a specific period of
time. Specify the /DD switch in the following format:
/DD:startdate:enddate
/DD
The Default Date switch
startdate
The beginning date of the specified time period in the form
dd-mm-yy. May be unlimited by using the wildcard character (*).

3-16

PERIPHERAL INTERCHANGE PROGRAM {PIP)
enddate
The ending date of the specified time period in the form
dd-mm-yy. May be unlimited by using the wildcard character (*).
Specifying the wildcard for both startdate and enddate negates the /DD
switch:
/DD:*:*
The date restrictions for the file searches are now disabled.
Examples
1.

PIP>/DD:Ol-JUN-80:01-JUL-80/LI
Lists all files created from 1 June 1980 through 1 July 1980.

PIP>/DD:*:l-JUN-80/LI
Lists all files created on or before 1 June 1980.

PIP>/DD:l-JUN-80:*/LI
Lists all files created on or after 1 June 1980.

3.2.2.5 /DE -- Delete Switch - The Delete switch (/DE) deletes files
from a UFO.
Optionally, you can specify that the deleted files be
listed on your terminal. Specify the /DE switch in the following
format:
infilel[,infile2 ••• ,infilen]/DE[/LD]
infile
The input file specification.
/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.
Examples
1.

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.

3-17

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Wildcards in the file name or file type
version of ;-1, ;O, or ;
is specified.

fields

are

illegal

when

You must issue the file specification because an un spec if i ed
name, file type, and version does not default to * • *•*
I
•

file

The input file specification can take all the usual
forms,
including
wildcards
(even in [ufd] ). The only special requirement is that the
version field must always be specified.
Examples
1.

PIP>TEST.DAT;S/DE
Deletes version 5 of file TEST.DAT from the
directory on the default device.

default

PI P>TEST. DAT; 1,; 2/DE
Deletes versions 1 and 2 of file TEST.DAT
default directory on the default device.

current

from

the

current

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 both file types.

PI P> * • OBJ; * /L D, * • TM P; */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.

3.2.2.6 /DF -- Default Switch - The Default switch (/DF) changes
default device and/or UFO for the current PIP task.

the

The usual default device of PIP is the user's system device (SYO:).
The usual default UFO is the UIC under which PIP is currently running.
The /DF switch alters only the default UFO.
It does not affect the
UIC under which PIP is running, nor does it circumvent
file
protection.
Specify the /DF switch in one of the following formats:
dev: [ufd] /DF
or
dev:/DF
or
[ufd] /OF
or
/DF

3-18

PERIPHERAL INTERCHANGE PROGRAM (PIP)
dev:
If specified, the new default device to be applied to
PIP command lines.

subsequent

[ufd]
If specified, the new default UFD to be applied to subsequent PIP
command lines.
/DF
The Default switch.
The /DF switch specified with no arguments returns the default device
to the user's system device (SYD:) and the default UFD to the UIC from
which PIP was invoked.
Examples
1.

PIP> [ 2 7, 2 7] /DF
Sets the default UFD to [27,27].

PIP>DKl:/DF
Sets the default device to DKl:.

PIP>DKl: [27, 27] /DF
Sets the default device to
[ 2 7' 27] •

DKl:

and

the

default

UFD

and

default

PIP>/DF
Returns the user's default device to SYD:
UFD to the UIC from which PIP was invoked.

the

3.2.2.7 /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[/NVJ
outfile
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.
A file name, file type, or version field that is
either wildcard
(*) or
default
(null)
means
that
the
corresponding field of the input file is to be used.
infile
The file specification for the input file in the format:
dev: [ufd]filename.filetype;version/EN[/NV]

3-19

PERIPHERAL INTERCHANGE PROGRAM {PIP)
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 returns an error message that
requests that the line be reentered.
The default input file specification is

* *·*
•

•

/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.
(Specifying the /NV subswitch is not necessary when
both the input and output files are under the same file
d i rec tor y • )
Example (see Figure 3-2)
PI P >[ l 0 l , 101 ] TWIG /EN= [ 2 0 0 , 2 0 0 ] RICK. DAT ; 1

Before
DIRECTORY [200,200]

DIRECTORY [101,101]
JEN.OBJ;2

RICK.DAT;l

LAU.OBJ;3

After
DIRECTORY [200,200]

DIRECTORY [101,101]

RICK.DAT;l

JEN.OBJ;2
LAU.OBJ;3
TWIG.DAT;l
NOTE

The directory items for RICK.DAT;l and
TWIG.DAT;l both reference the same file.
ZK-175-81

Figure 3-2

Sample Directories Before and After Execution

3-20

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.2.2.8 /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 classified group or world to the
file owner's UIC, you need read access to read the attribute and write
access to change it.
Specify the /EOF switch in the following format:
infilel/EOF[:block:byte] [, ••• infilen/EOF[:block:byte]]
infile
The input file specification.
The file specification must be issued because an unspecified file
name, file type, and version do not default to *.*;*.
block
The block number where the EOF pointer is to be placed. Usually,
the EOF pointer cannot be placed beyond the highest number of
blocks allocated to the file.
However, if all the bytes of the
allocated blocks are used, the EOF pointer can be placed in the
first byte of the next block (/EOF:
blocks allocated plus
one:O). The block number can be octal or decimal.
byte
The byte location of EOF is the first unused byte of
specified block.
The byte number can be octal or decimal.
maximum value for byte is 777(8).

the
The

If you do not enter either of the values for block and byte,
PIP
places EOF past 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 returns an error message.
Note that the /EOF switch is local to each file
therefo~e does not default from left to right.

specification

and

Example
PIP>A.TMP/EOF:l7:253,AA.TMP/EOF
is equivalent to
PIP>A.TMP/EOF:l7:253,AA.TMP/EOF:23:0
where the file AA.TMP has 22 blocks allocated.

3.2.2.9 /EX -- File Exclusion Switch - The File Exclusion switch
(/EX)
excludes one file specification's worth of files during file
searches. You can exclude any field in the file specification.
The
fields can have in them characters and/or wildcards. Specify the /EX
switch in the following format:
f ilespec/EX

3-21

PERIPHERAL INTERCHANGE PROGRAM (PIP)
filespec
The file specification. The file name and/or the file type
and/or the version number can be a wildcard, but not all three
fields.
Also, you cannot specify devices or UFOs.
/EX
The File Exclusion switch.
Specifying the /EX switch by itself negates it.
PI P>/EX
Example
PIP>*.CMD;*/EX/LI
DIRECTORY DBl: [301,7]
8-JUL-81 14: 50
*. CMD; *EXCLUDED
EXECM.MAC;23
RUN. TSK; 46
FRANK. OBJ; 16
DEBBIE.COR;2

45.
5.
33.
5. o.

23-FEB-80
29-0CT-80
02-MAY-80
14-JAN-81

Excludes all files of the type
*.*;*/LI.

.CMD

14:23
11: 59
13:58
12:01

from

the

done

3.2.2.10 /FI -- File Identification Switch - The File Identification
switch {/FI)
allows you to access an existing file by its file
identification number
(File-ID).
Specify the /FI switch in the
following format:
outfile=/FI:filenum:seqnum
/FI
The File Identification switch.
f ilenum
The file number.
seqnum
The sequence number of the file.
The file identification number (file-ID) 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). The /FU switch displays the
file
identification and sequence numbers and other information
describing the file.
Examples
1.

You can use the /FI switch to create a directory entry for
file.
PIP>XYZ.TSK=/FI:301:27/EN

3-22

PERIPHERAL INTERCHANGE PROGRAM (PIP)
2.

You can copy a file using the /FI:

switch.

PIP>A.B=/FI:301:27
3.

To list entries in
the
directory
file
whose
file
identification is 1275,47, use the /FI switch in the format:
PIP>/FI:l275:47/LI
DIRECTORY DR2: FILE ID 001275,000047,0
8-AUG-81 15:58
MCR.CMD
DCL.CMD

1.
1.

29-NOV-80 13:22
29-NOV-80 13:24

displays the
3.2.2.11 /FR -- Free Switch - The Free switch (/FR)
amount
of available space on a specified volume, the largest
contiguous space on that volume, the number of available file headers,
and the number of file headers used.
Specify the /FR switch in the
following format:
[dev:]/FR
If you do not specify dev:, PIP defaults to SYO:.
The format of the information from the /FR switch is shown below.
dev:
HAS xxxx. BLOCKS FREE, yyyy. BLOCKS USED OUT OF zzzz.
LARGEST CONTIGUOUS SPACE = nnnn. BLOCKS
aaaa. FILE HEADERS ARE FREE, bbbb. HEADERS USED OUT OF cccc.
Usually, the number of free file headers corresponds to the number of
files that can be created. However, fragmented files and files that
are too large for one file header must be allocated more than one file
header.
The number of file headers will not exceed the number
can be created.

files

that

Example
PIP>db7:/FR
DB7: HAS 10662. BLOCKS FREE, 330008. BLOCKS USED OUT OF 340670.
LARGEST CONTIGUOUS SPACE = 4189. BLOCKS
9025. FILE HEADERS ARE FREE, 11931. HEADERS USED OUT OF 20956.

3.2.2.12 /ID -- Identify Switch - The
Identify
switch
(/ID)
identifies the version of PIP being used. Specify the /ID switch in
the following format:
/ID
When you specify this switch, the version
input terminal as follows:
PIP VERSION Mvvee (ANSI)

3-23

number

listed

the

PERIPHERAL INTERCHANGE PROGRAM (PIP)

vv
The version number.
ee
The edit number.
(ANSI)
It PIP is linked
to an
Otherwise, it is blank.

ANSI

FCS,

this

field

will

appear.

NOTE

For ·RSX-llM ()~~ratit19 sy.Stein~'. }f .·•· you
want ANSI mag:netic tape St.lPi:><>rt; PIP
mustbe built with ANSL!B instead of
SYS.LIB••
Example
PIP>/ID
PIP -- PIP VERSION Ml340 (ANSI)

3.2.2.13 /LI -- List Switch - The List switch (/LI) lists one or more
files contained in a UFD, along with their status information. Three
alternate mode subswitches (/BR, /FU, and /TB) allow you a choice of
directory listing formats.
Table 3-4 describes these switches.
Specify the /LI switch in the following format:
[listfile=]infilel[,infile2 ••• ,infilen]/LI[/subswitch]
listf ile
The file specification to be listed in the format:
dev: [ufd]filename.filetype;version
If listfile is not specified, it defaults to TI:.
infile
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}

3-24

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.

file code:
{null)

c
L

noncontiguous
contiguous
= locked

creation date and time

summary line, which
includes
used/allocated and files printed.

the

number

blocks

/subswitch
The alternate mode subswitch of the
Table 3-4).

List

switch

{described

Table 3-4
List Subswitches
Subswitch

Description

/BR

Specifies the brief form of directory listing.
This
switch lists only the file name, file type, and
version.

/FU[:n[.]]

Specifies the full directory format.
Because the /FU
format
uses
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 classified 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
3.2.2.16.}
If specified, n is the number of characters per
line.
If not specified, the number defaults to the
buffer size of the output device.
The /FU 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)

{continued on next page)

3-25

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-4 {Cont.)
List Subswitches
Subswitch
/FU[:n[.]]
(Cont.)

Description
4.

file code:
(null) = noncontiguous
c = contiguous
L
= locked

creation date and time

owner UIC and file protection in the format:
[group,member] [system,owner,group,world]
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 used.

This switch only outputs the
following format:
TOTAL OF nnnn./mmmm.

summary

line

BLOCKS IN xxxx.

the

FILES

where:
nnnn = blocks used
mmmm = blocks allocated
xxxx = number of files
Figure 3-3 contains sample directory listings in the various formats.

3-26

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Total Blocks (/TB) Format
STORAGE USED/ALLOCATED FOR DIRECTORY DK2:C200•270J
15-JUL-75 l~!i: 46
TOTAL OF 145./150. BLOCKS IN S. FILES

Brief (/BR) Format
DIRECTORY DK2:C200,270J
CKTST.HACf6
IOTST.HACf4
IOTST.TSKf1
CKTST.TSKfl
CKTST.HACf7

Standard (/LI) Format
DIRECTORY DK2:t200,270J
15-JUL-75 15:46
CKTST.HACf6
IOTST.HACf4
IOTST.TSKH
CKTST.TSKfl
CKTST.HACf7

3.
4.
69.
69.

15-JUL-75 15:39
15-JUL-75 15:39
C 15-JUL-75 15:39
C 15-JUL-75 15:40
L 15-JUL-75 15:40

TOTAL OF 145. BLOCKS IN 5. FILES

Full (/FU) Format
DIRECTORY DK2:C200,270J
15-JUL-75 15:46
CKTST.HACf6
<10,10>
C200•270JCRWED,RWED•RWED,RJ
IOTST .HACf 4
<1 t..11>
C200•270JCRWED,RWED•RWED,RJ
IOTST.TSKfl
<7•12>
C200,270lCRWED,RWED•RWED•Rl
CKTST.TSKfl
<12•13>
C200,270ltRWED,RWEDrRWED,RJ
CKTST.HACf7
(13•14)
C200,270JtRWED,RWED,RWEDrRJ

15-JUL-75 15139

3.13.

15-JUL-75 1:5'39
69.169.

15-JUL-75 15139

69.169.

15-JUL-75 15140

0.15.

L 15-JUL-75 15140

TOTAL OF 145./150. BLOCKS IN 5. FILES
Figure 3-3

Directory Listing Examples

3-27

ZK-176-81

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Examples
1.

PIP>/LI
Lists the
directory.

the
all

format
{132-column
line printer in full
of the directories on the current default

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
1 is ting) ,
device.

directory of the current default device
(This is equivalent to TI:=*.*;*/LI.)

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.

PI P>LP: = [11, *] * .CMD; */LI
Lists on the line printer all versions of all files with
file type .CMD in all directories in group 11.

the

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.

3.2.2.14 /ME -- Merge Switch - The Merge switch {/ME)
creates
a
single file from two or more existing files.
The /ME switch is used
in copying Files-11 files and is described in Section 3.2.1.

3.2.2.15 /NM -- No Message Switch - The No Message
switch
{/NM)
suppresses the PIP error messages, NO SUCH FILES(S) and FILE NOT
LOCKED, when you are manipulating files.
Specify the /NM switch in
the following format:
infilel [ ,infile2, ••• infilen] [/sw] /NM

3-28

PERIPHERAL INTERCHANGE PROGRAM (PIP)

infile
The input file specification.
/sw

Any combination of appropriate
example, the /LI, /DE, /PU,
respective subswitches.

switches and subswitches, for
or /UN switches and any of their

/NM

The No Message switch.
The /NM switch applies not only to the file specification
preceding it, but also to all file specifications to the right of
it.

Example
PIP>*.MAC;*/NM,TEST.DAT;l,FILES.OBJ;*/DE
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.

3.2.2.16 /PR -- Protect Switch - The Protect switch (/PR) allows you
to set the protection status of a file.
File protection is provided
for four categories:
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).
Owner
Specifies which categories of access the owner has allowed.
Group
Specifies which categories of access other members
group have.

the

same

World
Specifies categories of access given all other UICs.
For each category, you can specify whether that category can read,
write, extend, or delete the file.
To alter the protection level of a
file, you can use either the /PR subswitches (/SY, /OW, /GR, /WO) or
octal representation (/PR:n). For either method, if you are the file
owner or have a system-level UIC, you can alter the protection level
without having read or write access. However, because the protection
level of a file is a protected attribute, you cannot alter the
protection level if you are group or world to the file owner's UIC.
(You can read protected attributes if you have read access.)

3-29

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Specify the /PR switch in the following format:
inf i l e/PR [/SY [: RWED]] [/OW [: RWED]] [/GR [: RWED]] [/WO [: RWED]] [/FO]
infile
The file specification for the file
changed in the format:

whose

protection

being

File specification must be issued because an unspecified
name, file type, and version do not default to * • *·*
I
•

file

dev: [ufd]filename.filetype;version

/PR
The Protect switch.
/SY,/OW,/GR, and /WO
The subswitches that specify protection level for a file.
These
subswitches specify which protection level
is to be altered
(others are left intact). The values that follow the switch are
any of the four letters, R, W, E, and D (for read, write, extend,
and delete), in any order. They specify which privileges the
respective categories can have.
If you enter the subswitch and
do not specify a value, no privileges are granted for that
category.
The subswitches are identified as follows:
/SY
/OW
/GR
/WO

is
is
is
is

the
the
the
the

System subswitch.
Owner subswitch.
Group subswitch.
World subswitch.

Protection can also be specified by an optional
the /PR switch, in the format:

octal

value

/PR:n
The variable n is the octal representation of the protection to
be assigned to the file.
This octal number is taken as the new
protection word.
(See the RSX-llM or RSX-llM-PLUS Mini-Reference
Manual for the list of octal codes.) The format of the protection
word is shown in Figure 3-4.

/FO
The Set File Ownership subswitch, which allows you to set the
ownership of a file to that of the UIC of the directory in which
it is entered.
(You can change the file ownership at the same
time you set the protection value.) If there are files in the
[200,200] directory that are owned by another UIC, the command
PIP>[200,200]*.*;*/PR/FO
causes all files to be owned by [200,200] without changing
protection.

3-30

their

PERIPHERAL INTERCHANGE PROGRAM (PIP)

Protection
word

8 7

12 11

WORLD

GROUP

4 3

OWNER

SYSTEM

/
/

)"2 1 0
l'olElWlR(
(bit set means NO access permitted.)
Example
TEST.DAT;5/PR:3
(bits 0 & 1 set)
deny write and read access to the system
for file TEST.DAT;S.
ZK-177-81

Figure 3-4

Format of Protection Word

Examples
1.

PIP>TEST.DAT;S/PR/OW:RWE/GR:RWE/WO
Sets the protection level so that the owner and group have
RWE privileges (not delete), world has no access privileges,
and system privileges are unchanged.

PIP> [ *, *] *. *; */PR: 0
Sets the protection level of all files so that all categories
are granted all access privileges.

PIP>DKO: [*,*] *.*; */PR/FO
Causes all file owners to be the same UIC as the UFD in which
the files are entered.

3.2.2.17 /PU -- Purge Switch - The Purge switch (/PU) deletes
a
specified range of obsolete versions of a file. Optionally, you can
specify that the names of deleted files be listed on your terminal.
Specify the /PU switch in the following format:
inf il el [,inf ile2 ••• , infil en] /PU [: n] [/LD]
infile
The file specification for the file(s) to be deleted.
specification takes the form:

The

file

dev: [ufd]filename.filetype
Note that a version number is not needed.
ignored.

3-31

specified,

PERIPHERAL INTERCHANGE PROGRAM (PIP)
/PU [: n [.]]
The Purge switch. If you specify the optional value n and the
latest version of the file is m, then all existing versions less
than or equal to m-n are deleted (see Figure 3-5).
Although it
is useful to think of this command as deleting all but the n most
recent versions, it is important to understand that if any
versions are already deleted between m-n and m, fewer than n
versions will be retained. The most recent version of the file
is always retained.
If you omit the value n, PIP defaults to 1, and all but the
latest version of the file are deleted. If n is greater than the
number of versions of the specified files, no files are deleted.
The value n is local and defaults from left to right. This means
that if you specify n at the end of the command line, it only
applies to the infile immediately preceding it.
All other
infiles default to one.
However, n applies to all following
infiles until you make a new specification for n.
/LD
The List Deleted files subswitch.
Examples
1.

PIP>*.OBJ,*.MAC/PU:2/LD
Deletes all but the highest version of all files with a file
type of .OBJ, and all but the two highest versions of all
files with a file type of .MAC. Lists all deleted files.

PIP>*.OBJ/PU:2/LD,*.MAC
Deletes all but the two highest versions of all files
file types of .OBJ and .MAC. Lists all deleted files.

Directory Before Purge

Directory After Purge

GARY;!
GARY;2
GARY;3
GARY;4
GARY;S
RICK;4
RICK;S
RICK;7

with

GARY;3
GARY;4
GARY;S

c:) GARY /PU : 3, RICK/PU: 2

RICK;7

In the case of the files named GARY, the three latest versions (3, 4, and 5)
are retained; versions 1 and 2 are deleted. In the case of the files named
RICK, since version 6 did not exist, only version 7 is retained; and all
existing versions less than or equal to 5, for example, versions 4 and 5,
are deleted.
ZK-178-81

Figure 3-5

Use of the Purge Switch
3-32

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.2.2.18 /RE -- Rename Switch - The Rename switch (/RE)
changes the
name of a
file.
There is also a New Version subswitch (/NV) that
forces the renamed file to have a version number one greater than the
latest version of the previously existing file with the same name (see
Figure 3-6). Note that you cannot rename a file that is copied from
one device to another device.
Specify the Rename switch in the
following format:
outfile=infilel[,infile2 ••• ,infilen]/RE[/NV]
outf ile
The file specification to be given to the new file.
The output
file specification has a special property in that the file name,
file type, and version are each allowed to be explicit, wildcard
(*), or defaulted (null). A UFD, filename, filetype, or version
field that is either wildcard (*) or defaulted (null) means that
the corresponding field of the input file is to be used. Thus,
the Rename switch can change one or more fields while preserving
the others.
The output file specification takes the following
form:
dev: [ufd]filename.filetype;version
infile
The file specification of the file to be renamed. The input file
specifications are standard and allow wildcards in all fields,
including UFD.
The input file specification takes the
following
form:
dev: [ufd]filename.filetype;version
An unspecified file name, file

type,

and

version

defaults

* • *•*
I
•
The /RE switch does not transfer data.
The file
is entered
in
the new directory and deleted from the old directory.
The
directories must be on the same device because data is not
transferred.
You can move files out of one directory into
another, preserving the file name, file type, and version, or
changing them if desired.
(This is permitted only if PIP is
running under a
UIC with write privileges for each of the
directories involved.)
If you specify a device on either the input or output side, that
device sets the default for the other side.
If both the input
side and the output side explicitly reference different devices,
PIP returns an error message and requests that you reenter the
line.

/RE
The Rename switch.

3-33

PERIPHERAL INTERCHANGE PROGRAM (PIP)
/NV
The New Version subswitch. The /NV subswitch forces the version
number of the renamed file to a number one greater than the
latest version for the file.
The /NV subswitch may appear on either side of the equal sign.
If it appears on the output side, all of the version numbers of
files being renamed are forced to a number one greater than the
latest version for the file.
If it appears on the input side,
only the file that has the subswitch appended to it has its
version number forced to one greater than the latest version of
the file.
(Specifying /NV is not necessary when both the input
and output files are under the same directory file.)

Examples
1.

PIP>TESTFILE.DAT;l=TEST.DAT;S/RE
Renames TEST.DAT;S to TESTFILE.DAT;l.

PIP>BACKUP.*;*=TEST.*;*/RE
Renames all versions of all files with file names TEST to
BACKUP, preserving the file type and version of each file.

PIP>*.*;l=*.*;*/RE
Renames all copies of all files to version 1.

PIP>[200,220]=[200,200]/RE
Renames all files from [200,200] to [200,220], preserving the
file name, file type, and version of each file.

PIP>EXAMPLE.*;*=TEST.*;*/RE
Renames all versions of all files with the file name TEST to
the file name EXAMPLE, preserving the file type and version
of each file.

PIP>SAVE.DAT/RE/NV=OUTPUT.DAT;l
Renames OUTPUT.DAT;l and forces the version number to one
greater than the latest version of SAVE.DAT. Figure 3-6
illustrates the results with and without the /NV switch.

3-34

PERIPHERAL INTERCHANGE PROGRAM {PIP)

Directory Before Rename
SAVE.DAT;2
SAVE.DAT;3
SAVE.DAT;4
OUTPUT.DAT;!
OUTPUT.DAT;2
Directory After Rename Without /NV Switch Set
SAVE.DAT;2
SAVE.DAT;3
SAVE.DAT;4
SAVE.DAT;!
OUTPUT.DAT;2
Directory After Rename With /NV Switch Set
SAVE.DAT;2
SAVE.DAT;3
SAVE.DAT;4
SAVE.DAT;5
OUTPUT.DAT;2
ZK-179-81

Figure 3-6

Results of Rename Switch With and Without /NV Specified

3.2.2.19 /RM -- Remove Switch - The Remove switch
(/RM)
removes an
entry from a UFD, but does not delete the file associated with that
entry.
The Remove switch is particularly useful
for
deleting
directory entries which,
for whatever reason, point to nonexistent
files.
It is also used to delete synonyms generated by the Enter
switch.
If the last entry for an existing file is removed, that file
can be located only by using the VFY utility with its /LO switch
(see
Chapter 9). Specify the /RM switch in the following format:
infilel[,infile2 ••• ,infilen]/RM
infile
The file
removed.

specification for the directory file
The file specification takes the form:

entry

dev: [ufd]filename.filetype;version
The file specification must be issued because a null
file type, and version do not default to *.*;*.

file

name,

/RM
The Remove switch.
Example
PIP>DKl: [10, lO]RICKSFILE.DAT;l/RM
Removes the file entry RICKSFILE.DAT;l from the directory [10,10]
on DKl:.

3-35

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.2.2.20 /RW -- Rewind Switch - The Rewind switch (/RW)
directs PIP
to rewind magnetic tape.
(The /RW switch cannot be used for
DECtapes.) You can apply this switch to both input and output
specifications.
When you specify the /RW switch with the output
specification, PIP begins writing the file at the beginning of the
tape. You can use this technique to erase a tape before writing files
on it. Specify the /RW switch in the following format:
outfile/RW=infile
or
outf ile=infile/RW
outf ile
The output file specification.
infile
The input file specification.

/RW
The Rewind switch.
When you apply the /RW switch to the input specification, it rewinds
the tape before searching for the input file. The magnetic tape
processor performs the following process when it searches for a file
to open:
1.

Searches from the current position to end of tape

Rewinds the tape

Searches from the beginning of tape to the point where search
processing began

You can use /RW with the input specification to save search time.
If
you know a file is behind the tape's current position, /RW rewinds the
tape before searching for the file to open. This saves the time that
otherwise would have been taken to search for the file between the
current position and the end of the tape.
Example
PIP>MT:/RW=[200,200]
Starts the beginning of the tape and outputs
directory [200,200].

all

files

the

Rewinds the tape, then searches the tape for the file AB.DOC
outputs the file renaming it AMBER.DOC.

and

PIP>AMBER.DOC=MT:AB.DOC/RW

3-36

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.2.2.21 /SB -- Span Blocks Switch - The Span Blocks switch (/SB)
allows you to control whether records copied from magnetic tape to
disk will cross block boundaries. If you omit this switch, the file
is copied with records possibly crossing block boundaries. If you
specify /-SB, the records will not cross block boundaries.
Specify the Span Blocks switch in the following format:
outdsk:outfile/SB=inmag:infile
outf ile
The disk output file.
infile
The magnetic tape input file.
/SB
The Span Blocks switch.
Example
PIP>DKl:FILES.DAT/-SB=MMO:FILES.DAT
Copies FILES.DAT records to the disk from magnetic tape.
on the disk will not cross block boundaries.

Records

3.2.2.22 /SD -- Selective Delete Switch - The Selective Delete switch
(/SD)
prompts for your response before deleting a file that you have
specified in the command line for deletion. The response choices are
carriage return
(<RET>) or control-Z
(AZ), or Y, N, G, or Q, each
followed by either a carriage return {<RET>) or control-Z (AZ). Table
3-5 describes the effect of each combination of letter and terminator.
Specify the /SD switch in the following format:
infilel[,infile2 ••• ,infilen]/SD
infile
The input file specification in the form:
dev: [ufd]filename.filetype;version
The file specification must be issued because a null
file type, and version do not default to *.*;*.
/SD
The Selective Delete switch.

3-37

file

name,

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-5
Response Choices for the Selective Delete Switch
Letter

Terminator

Operation

@IT)

Delete this file and continue.

(CTRL/Z)

Delete this file and exit from PIP.

[N]

@IT)

Save this file and continue.

[N]

©TRL/Z)

Save this file and exit from PIP.

@IT)

Save this file and return to command mode.

(CTRL/Z)

Save this file and exit from PIP.

@IT)

Delete this and all rema1n1ng candid ates,
and return to PIP
list
deleted files,
command mode.

(CTRL/Z)

Delete this and all remaining candidates,
list deleted files, and exit from PIP.

Examples

PIP>MYFILE.DAT;*/SD
DELETE FILE DBI: [200, 200]MYFILE.DAT;l [Y/N/G/Q]?
DELETE FILE DBI: [200,200]MYFILE.DAT;2 [Y/N/G/Q]?

Y @IT)
G @IT)

THE FOLLOWING FILES HAVE BEEN DELETED:
DBI: [200,200]MYFILE.DAT;2
DBI: [200,200]MYFILE.DAT;3
PIP>
Deletes MYFILE.DAT;l and PIP goes to the next candidate,
MYFILE.DAT;2.
Deletes this file and all remaining versions
of MYFILE.DAT.
Lists the deleted files and then PIP prompts
for the next command.
2.

PI P>TEST. *; */SD
DELETE FILE DBI: [200,200]TEST.DAT;l [Y/N/G/Q]?
DELETE FILE DBI: [200,200]TEST.TXT;3 [Y/N/G/Q]?
Saves TEST.DAT;!.
PIP goes on to the next candidate,
TEST.TXT;3.
Saves this file and all remaining files with
file name TEST and then exits from PIP.

3.2.2.23 /SP -- Spool Switch - The Spool switch (/SP) directs a file
to a line printer for printing. This switch a plies only if you have
1
t}Je .• Pt$nt•··•·•·$pbo1.E!~·····.>~.a$k· (1'{$}{fl~t0. or lfl!fllll:ill!llllilli1li tl~ll~tlt~lnl·~(ll!lllllli!llfillfll:llJ1f11111
installed.
(For more information on the Queue Manager and the Print
Spooler, see the RSX-llM/llM-PLUS Batch and Queue Operations Manual.)
Specify the /SP switch in the following format:
infilel[,infile2 ••• ,infilen]/SP[:n]

3-38

PERIPHERAL INTERCHANGE PROGRAM (PIP)
infile
The file specification of the file to be spooled for printing.
The file specification takes the form:
dev: [ufd]filename.filetype;version
The file specification must be issued because a null
file type, and version do not default to *.*;*.

file

name,

If the file is specified by its file identification number
(file-ID), it will be printed. File identification numbers are
discussed in Section 3.2.2.10.
/SP
The Spool switch.
n

The number of copies you want spooled.
(If a deleting spooler
was specified during system generation, only one copy of a file
is printed, regardless of the value of n. The file is deleted
after the first copy has been printed.) If n is omitted, a value
of 1 is assumed.
Example
PIP>RICK1.LST;l,KATHY.LST;l,/FI:l2:22/SP
Spools the files RICKl.LST;l, KATHY.LST;l, and the file whose
file identification number
(file-ID) is 12:22 for asynchronous
printing.

3.2.2.24 /SR -- Shared Reading Switch - The Shared Reading
switch
(/SR)
allows you to read a file that has already been opened for
writing by another task. You have no guarantee that you will get the
information you want since the EOF pointer may be incorrect at the
time you open the file.
Specify the /SR switch in the following
format:
outf ile=infile/SR
outf ile
The output file specification.
infile
The input file specification.
/SR
The Shared Reading switch.
Example
PIP>TI:=[210,20]FILES.DAT/SR
Enables you to read FILES.DAT even though another task
already opened it for writing.

3-39

may

have

PERIPHERAL INTERCHANGE PROGRAM (PIP)
3.2.2.25 /TD -- Today Default Switch - The Today Default switch (/TD)
restricts file searches to files created on the current day.
Specify
the /TD switch in the following format:
/TD
/TD
The Today Default switch
Note that specifying the wildcard for both startdate and enddate of
the /DD switch (/DD:*:*) also negates /the TD switch (/DD, see Section
3.2.2.4).
Examples
PIP>/TD/LI
DIRECTORY DB2: [301, 357]
20-JAN-81 11: 02
DAY OF 20-JAN-81
TEST.DAT;l

F ILES • T XT ; 1

1.
1.

INFO. DAT; 1

20-JAN-81 10:40
20-JAN-81 10: 41
20-JAN-81 10:50

TOTAL OF 3./15. BLOCKS IN 3. FILES

3.2.2.26 /TR -- Truncate Switch - The Truncate switch
(/TR)
allows
you to truncate files back to their logical end-of-file point.
Note
that RMS-11 files other
than
those
that
are
fixed-length,
variable-length, or sequenced cannot be truncated.
Specify /TR in the
following format:
infilel[,infile2 ••• ,infilen]/TR
infile
The input file specification.
The file specification must be issued because an unspecified file
name, file type, and version do not default to *.*;*.
/TR
The Truncate switch.
Example
PIP>*.MAC/LI
DIRECTORY DR2: [301, 7]
2-AUG-81 15: 32
A.MAC;l
B.MAC;l
C.MAC;2

2.
5.

20-SEP-80 14:02
20-SEP-8 0 15: 38
28-SEP-80 09:54

TOTAL OF 10./15. BLOCKS IN 3. FILES

3-40

PERIPHERAL INTERCHANGE PROGRAM {PIP)
PIP>*.MAC/TR
PIP>*.MAC/LI
DIRECTORY DR2: [301,7]
2-AUG-81 15:33
A.MAC;l
B.MAC;l
C.MAC;2

2.
5.

20-SEP-80 14:02
20-SEP-80 15: 38
28-SEP-80 09:54

TOTAL OF 10./10. BLOCKS IN 3. FILES
FCS allocates a certain number of blocks to a file.
The file may
or may not use the number of blocks allocated to it. The /TR
switch moves the EOF pointer to the end of the file and frees the
unused blocks for use by other files.

3.2.2.27 /UF -- User File Directory Switch - The User File Directory
switch (/UF) creates a UFD entry in the Master File Directory (MFD) on
the volume to which you are transferring a file.
You must also
transfer ownership of the file to access the file.
Use the /FO
subswitch to transfer file ownership, and use [*,*] as the UFD in the
output file specification if you want to create the UFD(s) from which
you are obtaining the files being transferred.
Specify the /UF switch
in the following format:
outfile/UF[/FO]=infilel ••• ,infilen
out file
The file specification for the output file.
infile
The file specification for the input file.
/UF
The User File Directory switch.
/FO
The File Ownership subswitch.
Section 3.2.1.

The /FO subswitch is described

Example
PIP>DK6: [*,*]/UF/FO=SY: (104, 20] *.MAC,*.OBJ
To use the /UF switch, you must have write access to the Master File
Directory of the volume on which the files are being written.
If that
volume is a system volume, you must have a system-level UIC to use the
/UF switch.
If the volume to which you are writing files is your
private volume, use the following procedure to change your UIC so that
you can write to it.
1.

Log onto the system under your UIC.

Reset your UIC to a privileged class using the SET command:
SET /UIC=[group,member]
where group and member specify a privileged class.

3-41

PERIPHERAL INTERCHANGE PROGRAM (PIP)
A typical use of the /UF switch is creation of a backup volume.
In
the following command, you are writing all files with file types .OBJ
and .MAC in UFD [104,20] to a backup volume called DK6:.

3.2.2.28 /UN -- Unlock Switch - The Unlock switch
(/UN)
unlocks
(gives permission to open)
a file that was locked because it was
improperly closed.
If a program using File Control Services (FCS) has
a file open with write access and exits without first closing the
file, the file is locked against further access as a warning that it
may
not
contain proper information.
Typically, the following
information is not written to the file:
1.

The current block buffer being altered

The record
information

that

attributes

contain

the

end-of-file

After you have used the /UN switch, you can access the file, determine
the extent of the damage, and, if possible, take corrective action.
Specify the Unlock switch in the following format:
infilel[,infile2 ••• ,infilen]/UN
infile
unlocked.

The

file

The file specification must be given because a null
file type, and version do not default to *.*;*.

file

name,

You must run PIP under the UIC of
system-level UIC.

The file specification for the file to
specification takes the form:

dev: [ufd]filename.filetype;version

the

file

owner

under

/UN
The Unlock switch.
Example
PIP>DKl: [100,100]RICK1.0BJ;3/UN
Unlocks the file RICK1.0BJ;3 in
DKl:.

directory

[100,100]

device

3.2.2.29 /UP -- Update Switch - The Update switch (/UP) is similar to
the basic PIP copy function or the Merge switch except that an
existing file is opened and new data
is written into it from the
beginning.
Existing data in the output file is destroyed and replaced
by the data that constitutes the input file(s).
Unlike the Supersede
switch /SU,
(Section 3.2.1) /UP does not delete the existing file
before rewriting the data. Therefore, its file identification number
(File-ID)
remains the same. Also, the number of blocks allocated to
the output file can be the same or greater, but never less than the
number of blocks allocated to the existing file.
However, as with the
/SU switch, the file's name, type, and version number remain the same.

3-42

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Specify the Update switch in the format:
outfile=infilel[,infile2 ••• ,infilen]/UP[/FO]
outfile
The file specification for the file to be
specification takes the form:

rewritten.

The

file

dev: [ufd]filename.filetype;version
As for the Merge and the Append switches, the output file
specification must be explicit, that is, no wildcards are
allowed.
The characteristics and record attributes of the output file
taken from the first input file.

are

infile
The file specification for the file to be copied
into the
file
that is being
rewritten.
The input file specification{s) take
the form:
dev: [ufd]filename.filetype;version
An unspecified file name, file type, and version default to * • *·*
I
/UP
The Update switch.

/FO
The Set File Ownership subswitch, which specifies that the owning
UIC of the output file corresponds to the directory into which
the file was entered.
If you do not specify the /FO switch,
the
owning
UIC of all new files
is the UIC under which PIP is
running, regardless of the directory into which the file was
entered.
Refer to Section 3.2.1 for examples for using the /FO
subswitch.
Example
PIP>DKl:SAMPLE.DAT;l=TESTl.DAT;l,TEST2.DAT;l,TEST3.DAT;l/UP
Opens SAMPLE.DAT;l on DKl:
and replaces the data currently in
the file with the contents of files TESTl.DAT;l, TEST2.DAT;l and
TEST3.DAT;l.

3.3

PIP ERROR MESSAGES

Errors encountered by PIP
following format:

during

processing

are

displayed

PIP -- <main error message>
<filename or f ilespec> -

3-43

the

PERIPHERAL INTERCHANGE PROGRAM (PIP)
The file name or file specification, if present, identifies the file
or set of files being processed when the error occurred.
If the error
was detected by the operating system, file system, or device driver,
the secondary error message is included to explain the cause of the
error.
PIP error messages are contained in a message file on the system
device.
If PIP cannot access the message file, errors are reported in
the following format:
PIP -- ERROR CODE nn.
<filename or filespec> -

or
<QIO Error Code -qq.>
nn
One of the PIP error codes contained in Table 3-6.

-mm
One of the standard system, file primitive, or FCS
in the IAS/RSX-11 I/O Operations Reference Manual.

codes

listed

-qq
One of the directive error
Operations Reference Manual.

codes

listed

IAS/RSX-11

The PIP error messages, their descriptions and suggested user
are as follows:
PIP

I/O

actions

ALLOCATION FAILURE - NO CONTIGUOUS SPACE
Explanation: Not enough contiguous space was
output volume for the file being copied.

available

the

User Action: Delete all files that are no longer required on the
output volume, then reenter the command line. Also, use the BRU
or DSC utilities to compress the files on your disk.
BRU is
described in Chapter 7 and DSC is described in Chapter 8.
PIP -- ALLOCATION FAILURE ON OUTPUT FILE
or
PIP

ALLOCATION FAILURE - NO SPACE AVAILABLE
Explanation: Not enough space was available on the output volume
for the file being copied.
User Action: Delete all files that are no longer required on the
output volume, then reenter the command line. Also, use the BRU
or DSC utilities to compress the files on your disk.
BRU is
described in Chapter 7 and DSC is described in Chapter 8.

3-44

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- BAD USE OF WILD CARDS/CHARACTERS IN DESTINATION FILE NAME
Explanation: A wildcard/character was specified
file name when use of a wildcard/character
disallowed.
User Action: Reenter the
explicitly specified.
PIP -- CANNOT EXCLUDE

command

line

with

for
was
the

an output
explicitly
output

file

*.*;*

Explanation: The /EX switch does not accept all wildcards as the
input file specification.
User Action: Determine the files to be excluded and reenter
command line.

the

PIP -- CANNOT FIND DIRECTORY FILE
Explanation:

The specified UFO does not exist on the volume.

User Action: Reenter the command line,
UFO or the correct volume.

specifying

the

correct

PIP -- CANNOT FIND FILE(S)
Explanation: The file(s} specified in the command line was(were}
not found in the designated directory.
User Action: Check
command line.

the

file

specification

and

reenter

the

PIP -- CANNOT RENAME FROM ONE DEVICE TO ANOTHER
Explanation:

You attempted to rename a file across devices.

User Action: Reenter the command line, renaming the file on the
input volume, then enter another command to transfer the file to
the intended volume.
PIP -- CANNOT TRUNCATE THIS FILETYPE
Explanation: PIP
can
only
truncate
files
fixed-length, variable-length, and sequenced records.
User Action: Check
command line.

the

file

3-45

specification

and

containing

reenter

the

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- CLOSE FAILURE ON INPUT FILE
or
PIP -- CLOSE FAILURE ON OUTPUT FILE
Explanation: The input or output file could not be properly
closed.
If the failure is on the output file, the output file is
then locked to indicate possible corruption.
User Action: Reenter the command line.
If the error recurs, run
a validity check of the file structure using the Verify utility
{VFY) on the volume in question to determine if it is corrupted.
VFY is described in Chapter 9.
PIP -- COMMAND SYNTAX ERROR
Explanation:

Command did not conform to syntax rules.

User Action:

Reenter the command line with the correct syntax.

PIP -- DEVICE NOT MOUNTED/ALLOCATED
Explanation: The drive had not been allocated, the
not mounted, or another user had mounted the device.
User Action: Allocate the drive and/or mount
reenter the command line.

the

device
device,

was
then

PIP -- DIRECTORY WRITE PROTECTED
Explanation: PIP could not remove an entry from a directory
because the device was write-protected or because of a privilege
violation.
User Action: Enable the device for write operations or have
owner of the directory change its protection.

the

PIP -- ERROR FROM PARSE
Explanation:

The specified directory file does not exist.

User Action:
specified.

Reenter the

command

line

with

the

correct

UIC

PIP -- EXPLICIT OUTPUT FILENAME REQUIRED
Explanation:

Self-explanatory.

User Action: Reenter the command line with the
explicitly specified.

3-46

output

filename

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- FAILED TO ATTACH OUTPUT DEVICE
or
PIP -- FAILED TO DETACH OUTPUT DEVICE
Explanation: An attempt to attach/detach a
record-oriented
output device failed. This is usually caused by the device being
off-line or nonresident.
User Action: Ensure that the device is on-line and
command line.

reenter

the

PIP -- FAILED TO ATTACH TERMINAL
Explanation: PIP could not attach a terminal,
of a privilege violation.

probably

because

User Action: Determine the cause of the failure and correct
Reenter the command line.

it.

PIP -- FAILED TO CREATE OUTPUT UFD
Explanation: PIP could not create an entry in a directory
because the device was write-protected or because of a privilege
violation.
User Action: Enable the unit for write operations
owner of the directory change its protection.

have

the

reenter

the

PIP -- FAILED TO DELETE FILE
or
PIP

FAILED TO MARK FILE FOR DELETE
Explanation:

You attempted to delete a protected file.

User Action: Request PIP under the correct UIC and
command line.
PIP -- FAILED TO ENTER NEW FILE NAME

Explanation: You specified a file that already exists in the
directory file, or you did not have the necessary privileges to
make entries in the specified directory file.
User Action: Reenter the command line, ensuring that the file
name and UFD are specified correctly, or request PIP under the
correct UIC and reenter the command line.
PIP -- FAILED TO FIND FILE(S)
Explanation: The file(s) specified in the command line was(were)
not found in the designated directory.
User Action: Check
command line.

the

file

3-47

specification

and

reenter

the

PERIPHERAL INTERCHANGE PROGRAM (PIP)

PIP -- FAILED TO GET TIME PARAMETERS

Explanation:

An internal system failure occurred while
trying to obtain the current date and time.

PIP

was

User Action: Reenter the command line. If the problem persists,
submit a Software Performance Report (SPR).
PIP -- FAILED TO OPEN INDEX FILE

Explanation: PIP was unable to read
because of a privilege violation.
User Action:
UIC, or have
index file.

the

index

file,

probably

Retry the operation by running PIP under a system
the system manager change the protection on the

PIP -- FAILED TO OPEN STORAGE BITMAP FILE

Explanation: PIP could not read the specified volume's
bit map, probably because of a privilege violation.

storage

User Action: Retry the operation by running PIP under a system
UIC, or have the system manager change the protection on the
storage bit map.
PIP -- FAILED TO READ ATTRIBUTES

Explanation: The volume you specified was corrupted or
not have the necessary privileges to access the file.

you

did

User Action:

Ensure that PIP is running under the correct UIC.
If the UIC is correct, then run the validity check of the File
Structure Verification Utility (VFY)
against the volume in
question to determine where and to what extent the volume is
corrupted. VFY is described in Chapter 9.
PIP -- FAILED TO REMOVE DIRECTORY ENTRY

Explanation:
because the
violation.

PIP could not remove an entry from a directory
unit was write-protected or because of a privilege

User Action: Enable the unit for write operations
owner of the directory change its protection.

have

the

PIP -- FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST

Explanation: PIP has removed a file from a directory, failed to
enter it (using /RE)
into another directory, ~nd failed to
replace the original directory entry.
User Action:

Run the lost
Verification Utility (VFY)
described in Chapter 9.

check
of
to recover

3-48

the
File
Structure
the file name. VFY is

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- FAILED TO SPOOL FILE FOR PRINTING
Explanation:

The Queue Manager is not installed.

User Action:
line.

Install the Queue Manager and reenter

the

command

PIP -- FAILED TO TRUNCATE FILE
Explanation: The volume you specified is corrupted or you did
not have the necessary privileges (write, extend) to truncate
this file.
User Action: Ensure that PIP is running under the correct UIC.
If the UIC is correct, then run the validity check of the File
Structure Verification Utility (VFY)
against the volume in
question to determine where and to what extent the volume is
corrupted. VFY is described in Chapter 9.
PIP -- FAILED TO WRITE ATTRIBUTES
Explanation: The volume you specified is corrupted or you did
not have the necessary privileges to write the file attributes.
User Action: Ensure that PIP is running under the correct UIC.
If the UIC is correct, then run the validity check of the File
Structure Verification Utility (VFY)
against the volume in
question to determine where and to what extent the volume is
corrupted. VFY is described in Chapter 9.
PIP -- FILE IS LOST
Explanation:
PIP has removed a file from its directory,
to delete it, and failed to restore the directory entry.
User Action: Run the lost
Verification Utility (VFY)
described in Chapter 9.

check
of
to recover

failed

the
File
Structure
the file name. VFY is

PIP -- FILE NOT LOCKED
Explanation:
locked.

The /UN switch was entered for a file that was

User Action:
file.

Reenter the command line,

specifying

the

not

correct

PIP -- GET COMMAND LINE - BAD @ FILE NAME
Explanation:
specified.

illegal

indirect

command

User Action: Reenter the command line,
name for the indirect command file.

3-49

file

specifying

name
the

was

correct

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP - GET COMMAND LINE - FAILED TO OPEN @ FILE
Explanation:
file.

PIP could not find the specified

User Action: Check the specification for
file and reenter the command line.

the

indirect

command

indirect

command

PIP -- GET COMMAND LINE - I/O ERROR
Explanation: An I/O error occurred during an attempt to
command line.

read

User Action: Check the command to ensure that you entered it
correctly, then reenter the command line. If the error persists,
submit a Software Performance Report (SPR).
PIP -- GET COMMAND LINE - MAX @ FILE DEPTH EXCEEDED
Explanation: The maximum level of nesting for
files (4) was exceeded.
User Action:

indirect

command

Reduce the level of nesting.

PIP -- ILLEGAL COMMAND
Explanation:

The command was not recognized by PIP.

User Action: Reenter the
correctly specified.

command

line

with

the

PIP

command

PIP -- ILLEGAL EOF VALUE
Explanation: You specified an illegal block and/or byte value in
the command line.
User Action:

Reenter the command line with the correct values.

PIP -- ILLEGAL RESPONSE - TRY AGAIN
Explanation:

Self-explanatory.

User Action:
prompts you.

Check which response you want and enter it when PIP

PIP -- ILLEGAL SWITCH
Explanation:

The specified switch was not a legal PIP switch.

User Action: Reenter the command line with
specification.

3-50

the

correct

switch

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- ILLEGAL "*" COPY TO SAME DEVICE AND DIRECTORY

Explanation:

You attempted to copy all versions of a
file
into
This
the same directory that is being scanned for input files.
would result in an infinite number of versions of the same file,
so is not allowed.

User Action:

Reenter the command line,
renaming
copying them into a different directory.

the

files

PIP -- ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION

Explanation:

The use of either a wildcard version number or a
latest version number in the attempted operation would result in
inconsistent or unpredictable output.

User Action: Reenter the command line with different options
with an explicit or default version number.

PIP -- INPUT FILES HAVE CONFLICTING ATTRIBUTES

Explanation:

The input files specified in a Merge,
Update, or
Supersede command had conflicting attributes or the attributes of
the input file(s) specified in an Append command conflicted with
those of the output file.

User Action: The message is a warning only.
The specified
action was completed despite the conflict. With a Merge, Update,
or Supersede command, the attributes of the output file will be
those of the first input file.
With an Append command, the
attributes of the output file are unchanged.
The resulting
file
should, however, be suspect because its attributes may not
correctly represent all the records in the file.
PIP -- I/O ERROR ON INPUT FILE
or
PIP -- I/O ERROR ON OUTPUT FILE

Explanation:

One of the following conditions may exist:

•

The device is not on-line

•

The device is not mounted

•

The hardware has failed

•

The volume is full

•

The input file is corrupted

(output only)

Note that these are the most common conditions.
than those listed may have caused the message.

Conditions other

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

3-51

message

and

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- NOT A DIRECTORY DEVICE
Explanation: A directory-oriented command was issued to a device
that does not have directories (such as a printer).
User Action:

Reenter the command line without specifying a UFO.

PIP -- NOT ENOUGH BUFFER SPACE AVAILABLE
Explanation: PIP did not have enough I/O buffer space to perform
the requested command.
User Action: Have the system manager install PIP in a larger
partition or increase the size specified by the /INC switch with
the MCR INSTALL command. See the RSX-llM/M-PLUS MCR Operations
Manual.
PIP -- NO SUCH FILE(S)
Explanation: The file(s) specified in the command was(were)
found in the designated directory.

not

User Action: Check
command line.

the

file

specification

and

reenter

PIP -- ONLY [*,*] IS LEGAL AS DESTINATION UIC
Explanation: A UFO other than [*,*] was specified as the
file UFO for a copy operation.
User Action: Reenter the command line with
the output UFO.

[*,*]

output

specified

PIP -- OPEN FAILURE ON INPUT FILE
or
PIP -- OPEN FAILURE ON OUTPUT FILE
Explanation: The specified file could not be opened.
following conditions may exist:

One of the

•

The file is protected against access.

•

A problem on the physical device (for example, device down).

•

The volume is not mounted.

•

The specified file directory does not exist.

•

The named file does not exist in the specified directory.

Note that these are the most common conditions.
than those listed may have caused the message.

Conditions other

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

3-52

message

and

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP -- OUTPUT FILE ALREADY EXISTS

NOT SUPERSEDED

Explanation: An output file of the same name, type, and
as the file specified already exists.

version

User Action: Retry the copy with /NV to assign
number or use /SU to supersede the output file.

new

version

the

switches

specifying

the

correct

PIP -- TOO MANY COMMAND SWITCHES - AMBIGUOUS
Explanation:
conflict.

Too many switches were specified

User Action: Reenter the command line,
set of switches.
PIP -- VERSION MUST BE EXPLICIT OR "*"

3.4

Explanation: The version number of the specified
expressed explicitly or as a wildcard (*).

file

User Action: Reenter the command line with
correctly expressed.

version

the

must

number

PIP ERROR CODES

Table 3-6 identifies the error codes PIP issues when it does not have
access to the message file.
The descriptions and suggested user
actions for these error codes are identical to those described in
Section 3.3.

3-53

PERIPHERAL INTERCHANGE PROGRAM (PIP)
Table 3-6
PIP Error Codes
Error Code

Error Message

COMMAND SYNTAX ERROR
ILLEGAL SWITCH
TOO MANY COMMAND SWITCHES - AMBIGUOUS
ONLY [*,*] IS LEGAL AS DESTINATION UIC
ILLEGAL COMMAND
ILLEGAL "*" COPY TO SAME DEVICE AND DIRECTORY
BAD USE OF WILDCARDS/CHARACTERS IN DESTINATION FILE NAME
EXPLICIT OUTPUT FILE NAME REQUIRED
ALLOCATION FAILURE - NO CONTIGUOUS SPACE
ALLOCATION FAILURE - NO SPACE AVAILABLE
ALLOCATION FAILURE ON OUTPUT FILE
I/O ERROR ON INPUT FILE
I/O ERROR ON OUTPUT FILE
ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION
FAILED TO CREATE OUTPUT UFD
INPUT FILES HAVE CONFLICTING ATTRIBUTES
OPEN FAILURE ON INPUT FILE
OPEN FAILURE ON OUTPUT FILE
CLOSE FAILURE ON INPUT FILE
CLOSE FAILURE ON OUTPUT FILE
FAILED TO DETACH OUTPUT DEVICE
DEVICE NOT MOUNTED/ALLOCATED
OUTPUT FILE ALREADY EXISTS - NOT SUPERSEDED
FAILED TO MARK FILE FOR DELETE
FILE IS LOST
VERSION MUST BE EXPLICIT OR "*"
ERROR FROM PARSE
FAILED TO DELETE FILE
FAILED TO ATTACH TERMINAL
ILLEGAL RESPONSE - TRY AGAIN
CANNOT EXCLUDE *.*;*
CANNOT FIND DIRECTORY FILE
FAILED TO ATTACH OUTPUT DEVICE
FAILED TO GET TIME PARAMETERS
NOT A DIRECTORY DEVICE
FAILED TO WRITE ATTRIBUTES
FAILED TO READ ATTRIBUTES
FILE NOT LOCKED
FAILED TO ENTER NEW FILE NAME
FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST
CANNOT RENAME FROM ONE DEVICE TO ANOTHER
FAILED TO SPOOL FILE FOR PRINTING
CANNOT SPOOL BY FILE ID (RSX-llD only)
FAILED TO OPEN STORAGE BITMAP FILE
FAILED TO OPEN INDEX FILE
FAILED TO FIND FILE{S)
CANNOT FIND FILE(S)
N0 S UC H F I LE ( S )
FAILED TO REMOVE DIRECTOR~ ENTRY
DIRECTORY WRITE PROTECTED
NOT ENOUGH BUFFER SPACE AVAILABLE
FAILED TO TRUNCATE FILE
CANNOT TRUNCATE THIS FILETYPE
ILLEGAL EOF VALUE

2
3

4
5
6
7
8
9
10
11
12
13
14
15

16
17
18
19
20
21
22
23
24

25
26
27
28
29
30
31
32
33
34
35
36
37

38
39
40
41
42
43

44
45

47
48
49

50
51
52
53
54

3-54

CHAPTER 4

FILE TRANSFER PROGRAM (FLX)

The File Transfer Utility Program {FLX)
allows you to use foreign
volumes
(not in Files-11 format) in DIGITAL's DOS-11 or RT-11 format.
FLX converts the format of a file to the format of the volume the file
is being transferred to.
FLX can be used to initialize and list directories of cassettes and
RT-11 or DOS-11 file-structured volumes.
FLX can also be used to
delete files from RT-11 or DOS-11 formatted volumes.
FLX performs file transfers {and format conversions,
from:

appropriate)

• DOS-11 to Files-11 volumes
• Files-11 to DOS-11 volumes
• DOS-11 to DOS-11 volumes
• Files-11 to Files-11 volumes
• Files-11 to RT-11 volumes
• RT-11 to RT-11 volumes
• RT-11 to Files-11 volumes
Valid DOS-11 devices are:

Device Abbreviation

Device
PCll paper tape punch
PCll or PRll paper tape reader
RK05 cartridge disk
TU78 magnetic tape
TE16, TU16, TU45, or TU77 magnetic tape
TS04 magnetic tape
TUlO, or TS03 magnetic tape
TU56 DECtape
TU60 tape cassette

4-1

PR
DK

MF
MM
MS

DT
CT

FILE TRANSFER PROGRAM (FLX)
Valid RT-11 devices are:
Device

Device Abbreviation

RL01/RL02 cartridge
RKOS cartridge disk
RK06 or RK07 cartridge disk
RXOl floppy disk
RX02 floppy disk
TU56 DECtape
TU58 DECtape II data cartridge

DL
DK
DM
DX
DY
DT
DD

FLX supports all Files-11 devices,
including RSX-format cassettes.
They are volumes that you have initialized using the MCR INITVOL or
DCL INITIALIZE command. DOS-11 and RT-11 volumes are initialized
using FLX.
On RSX-llM-PLUS, DOS-11 and RT-11 volumes must be mounted
with foreign characteristics before you can use FLX.
On RSX-llM, such
volumes must be unmounted.
You can use FLX interactively or by means of an indirect commmand
file.
FLX
allows
only
one level of indirect command file
specification.
You can invoke FLX in two ways: by specifying FLX or by specifying
FLX and a command line.
If you only specify FLX, the utility responds
with the prompt:
FLX>
FLX

can also access an indirect command file in the following manner:
>FLX @FOO.CMD
or
FLX>@FOO.CMD

4.1

FLX COMMAND FORMAT

Although formats for specifying FLX functions vary, the general format
for entering FLX command lines is:
devicespec/sw=infile/sw, ••• ,infilen/sw
devicespec
The device specification for the FLX output device,
the form:

which

takes

dev: [ufd]
The [ufd] field is optional;
if it is not specified, FLX uses
the current UIC.
Do not specify a UFD if the output device is in
RT-11 format.

4-2

FILE TRANSFER PROGRAM (FLX)
If you explicitly enter the output device specification, you must
enter the equal sign.
FLX does not permit output file specifications.
take the names of the input files.

The output files

infilen
The input file specifications, which take the form:
dev: [ufd]filename.filetype;version
The UFD is not specified for RT-11 volumes.
/sw
One of three types of FLX switches
4. 2.

described

below

Section

FLX supports 9-character file names for DOS-11-format magnetic tapes.
When you transfer the file back to Files-11 format, (which uses a
12-character filename) FLX will recover the last three characters.
Wildcards are valid only for input file specifications.
Version numbers are valid only for Files-11 files and cannot be
specified as wildcards.
The standard rules for updating version
numbers apply (see the RSX-llM/M-PLUS MCR Operations Manual).

4.2

FLX SWITCHES

FLX provides three types of switches for file transfers:
•

Volume format switches

•

Transfer mode switches

•

Control switches

Volume format switches specify the format of the volume on which files
are stored; that is, Files-11, DOS-11, or RT-11 volumes.
Transfer mode switches ~rovide the means for specifying the format of
a file on a non-Files-11 volume.
Filea can be in formatted ASCII,
formatted binary, or file image format.
Control switches provide control functions useful
during
file
transfers.
Using file control switches, you can specify, for example,
the number of blocks to be allocated to an output file or the UFD for
an output file.

4-3

FILE TRANSFER PROGRAM (FLX)
4.2.1

Volume Format Switches

FLX has three volume format switches that define
specified volumes.

the

format

the

/DO

Identifies the volume as a DOS-11 formatted volume.

/RS

Identifies the volume as a Files-11 formatted volume.

/RT

Identifies the volume as an RT-11 formatted volume.

Initially, input volumes default to DOS-11 format and output volumes
default to Files-11 format.
FLX assumes these default volume formats
if you do not specify switches in the command line.
You can change the initial default by entering /RS or /DO on a command
line by itself.
/RS sets the default for input volumes to Files-11
format and output volumes to DOS-11 format. /DO sets the default for
input volumes to DOS-11 format and output volumes to Files-11 format.
For example, to specify the default transfer direction
to DOS-11, type:

from

Files-11

Files-11,

FLX>/RS
To specify the default transfer direction
type:

from

DOS-11

FLX>/DO
If /RT is specified on one side of a command line, the
for the other side is /RS.

default

entry

Examples
1.

FLX>DKO:=DTO:SYSl.MAC/RT
The output is defaulted to /RS.

FLX>DKO:/RT=DKO:SYSl.MAC
The input is defaulted to /RS.

4.2.2

Transfer Mode Switches

FLX has three transfer mode switches, one for each type of file
format.
Files can be in formatted ASCII, formatted binary, or file
image format.
Format conversions can be in either direction, and are
between DOS-11 files and Files-11 files or between RT-11 files and
Files-11 files.
Specifying a transfer mode switch determines which
format the output file will be in after the conversion of the file.
Table 4-1 describes the transfer mode switches.

4-4

FILE TRANSFER PROGRAM (FLX)
Table 4-1
FLX Transfer Mode Switches
Description

Switch
/FA:n

Formatted ASCII
The DOS-11 or RT-11 output file is to be formatted ASCII.
Formatted
ASCII
is defined as ASCII data records
terminated by a carriage return/line feed (RET-LF), form
feed
(FF), or vertical tab
(VT).
In transfers from
DOS-11 or RT-11 files to Files-11 files, RET-LF pairs are
removed from the end of records.
In transfers from
Files-11 files to DOS-11 or RT-11 files, RET-LF pairs are
added to the end of each record that does not already end
with LF or FF.
In both directions, all nulls, rubouts,
and vertical tabs are removed from input records.
If you specify /FA:n with Files-11 output, fixed-length
records of size n are generated. Output records are
padded with nulls, if necessary.
FLX
If you do not specify /FA:n with Files-11 output,
generates variable-length records.
The output record
size equals the input record size.
ASCII data is transferred as 7-bit values. Bit 8 of each
byte is masked off before transfer. CTRL/Z (ASCII 032
octal) is treated as the logical end-of-input file for
formatted ASCII transfers from DOS-11 cassette or paper
tape to Files-11.

/FB:n

Formatted Binary
The DOS-11 or RT-11 output file is to be formatted
binary.
In this mode, formatted binary headers and
checksums are added to records that are output to DOS-11
or RT-11 files, and removed when transferred to Files-11
files.
If you specify /FB:n with Files-11 output, fixed-length
records of size /FB:n are output (512 (10) bytes is the
maximum). FLX pads records with nulls to create the
specified length.
If you do not specify /FB:n with Files-11 output, FLX
generates variable-length records.
The output record
size equals the input record size.

/IM:n

Image Mode
The transfer is to be in image mode.
Image mode forces
fixed-length records.
You can use the value n to
indicate the desired record length (in decimal bytes) for
Files-11 output (512 (10) bytes maximum).
If you do not
specify n, FLX assumes a record length of 512(10) bytes.

4-5

FILE TRANSFER PROGRAM (FLX)
FLX assumes the following default transfer modes for these file types
(with the exception of paper tape transfers described in Section 4.6).
Switch

File Type

Image

/IM:n

• TSK, .OLB, .MLB, .SYS,
• SML, .ULB, • EXE

Formatted Binary

/FB:n

• OBJ, .STB, .BIN, .LDA

Formatted ASCII

/FA:n

All others

Mode

If you specify n with /FA, /FB, or /IM when the output file is
Files-11 file, FLX ignores n.

not

The RSX-llM/M-PLUS MCR Operations Manual defines the above file types.

4.2.3

Control Switches

FLX provides a number of control switches to control file
Table 4-2 describes these switches.

processing.

Table 4-2
FLX Control Switches
Switch
/BL:n[.]

Description
Indicates the number of contiguous blocks (n)
decimal to be allocated to the output file.

in octal or

This switch is normally used with the /CO
switch
(described later in the table). Because all RT-11 files
are contiguous, the /CO switch is not required with the
/BL:n switch for RT-11 output.
If you do not specify /BL, the input file size is used as
the output file size.
The file allocation scheme used for RT-11
volumes
normally allocates the largest available space on the
volume for a new file.
Using /BL:n with the /RT switch
for the output file causes the output file to be
allocated the first unused space of size n.
However,
when the RT-11 file is closed, the input file size is
used as the output file size.
If the input file is not
n, an error results.
/BS:n

Specifies the block size n.
output.

in bytes for

cassette

tape

If you do not specify /BS, a block size of 128(10)
is
assumed.
/BS is only valid in a cassette tape (CT)
output file specification with /RS specified.
/CO

Indicates that the output file is to be contiguous.
/CO switch is used only with disks and DECtapes.

The

If the input file is on paper tape, cassette, or DOS-11
magnetic tape, /BL is also required.
FLX transfers the
(continued on next page)
4-6

FILE TRANSFER PROGRAM (FLX)
Table 4-2
(Cont.)
FLX Control Switches
Switch

Description

/CO
(Cont.)

file types .TSK, .SYS, and .OLB to Files-11 volumes with
/CO implied when the input is a Files-11 volume, or a
DOS-11 or RT-11 DECtape or disk.

/DE

Deletes files from a DOS-11 DECtape or disk.
It is used
also with /RT to delete files from an RT-11 DECtape or
disk. When you specify /DE, the FLX command line has no
output specification.

/DI

Causes a directory listing of cassettes or DOS volumes to
be listed on a specified output file.
It is used also
with /RT to generate a directory listing of RT-11 volumes
in a specified output file.
You cannot list Files-11 volume directories using FLX.
If you do not specify an output device, the directory is
sent to TI:.
If you do not specify file name and file
type on the input file specification, a wildcard is
assumed.
See Section 4.3 for
information
on
DOS-11-volume
directory manipulation. See Section 4.4 for information
on RT-11-volume directory manipulation.

/DNS:n

Specifies the density of the magnetic tape; where n is
800,
1600 or 6250 bpi.
If n is any other value or not
specified, FLX prints an error message.
If you do not
specify /DNS:n, the magnetic tape density defaults to
6250 bpi for the TU78, 1600 bpi for the TS04, and 800 bpi
for all other Magtape devices.
If you specify /DNS with
a nonmagnetic device, FLX ignores the switch.

/FC

When using FORTRAN files, indicates that FORTRAN carriage
control conventions are to be used.
The /FC switch
applies only to Files-11 output files.
(If you have the
PDP-11 FORTRAN Language Reference Manual, refer to it for
more information on FORTRAN carriage control conventions.
Otherwise,
refer
to the IAS/RSX-11 I/O Operations
Reference Manual for a discussion of the file data block
and record attributes, of which setting carriage control
is a part.)

/ID

Requests the current version number of FLX to be printed.
You can specify /ID as part of an output or input
specification or type it in response to the FLX prompt
( FLX>) •

/LI

Same as /DI.

/NU: n [.]

Used with the /ZE and /RT switches to specify the number
of directory blocks (n) in octal or decimal to allocate
when initializing an RT-11,disk or DECtape.
If you do
not specify /NU:n, four directory blocks are allocated.
The maximum number of blocks that can be allocated is
37 (8) 31 (10).
(continued on next page)

4-7

FILE TRANSFER PROGRAM (FLX)
Table 4-2
(Cont.)
FLX Control Switches
Description

Switch
/RW

Rewinds the magnetic tape before beginning the file
transfer.
Specifying /-RW causes FLX to begin the
transfer without first rewinding the magnetic tape.
If
you do not specify either rewind option, the switch
defaults to /RW.
If you specify the /RW switch with a
non-magnetic-tape device, or with /LI, /DI, or /ZE, FLX
ignores /RW.

/SP

Indicates that the converted file is to be spooled by the
print spooler task or the queue management system. The
/SP switch applies only to Files-11 output files.

/UI

Indicates that the output file is to have the same UFD as
the input file.
FLX ignores the /UI switch if the output
specification contains an explicit UFD.
/UI is valid
only for output files in DOS-11 or Files-11 format.

/VE

Causes each record written to a cassette to be read and
verified.
The /VE switch is only val id with a CT output
file specification.

/ZE[:n.]

Initializes cassettes or DOS-11 volumes.
It is also used
with
/RT
(and
/NU)
to initialize RT-11 volumes.
Initializing erases any files already on the device. The
/ZE switch does not require a file specification.
For DOS-11 DECtape, /ZE creates an entry for the
UIC.

4.3

current

DOS-11 VOLUME DIRECTORY MANIPULATION

This section contains examples that show how to display DOS-11
directory listings, delete DOS-11 files, and initialize DOS-11 volumes
using the FLX switches.
On RSX-llM-PLUS, DOS-11 volumes must
characteristics before you can use FLX.
be unmounted.

4.3.1

be mounted
with
foreign
On RSX-llM, the volumes must

Displaying DOS-11 Directory Listings

The /LI or the /DI switch instructs FLX to send the directory of
cassette or DOS-11 volume specified in the input specification to
Files-11 file specified in the output specification. If you do
enter an output specification, FLX sends the directory to TI:.
example:

the
the
not
For

FLX>DTO: (100,100}*.MAC/LI
This command line lists on your terminal the directory of
files under UFD (100,100] on the DOS-11 DECtape on DTO:.

all

.MAC

Figure 4-1 shows sample directory listings for a DOS-11 DECtape and
TU60 cassette.

4-8

FILE TRANSFER PROGRAM (FLX)

DECtape Directory Listing

8 DIRECTORY
8 19-SEP-78
0 FLX.TSK

OT: [200, 200]
8104.
8.

UFD.TSK
TKN.TSK
MOU.TSK

6.
14.

019-SEP-78
19-SEP-78
19-SEP-78
19-SEP-78

<233>
<233>
<233>
<233>

Cf) TOTAL OF 132. BLOCKS IN 4. FILES
Cassette Directory Listing

8 DIRECTORY
8 19-SEP-78
0 UFD.TSK-0

e CT: [200,200] e
0 28.

20.
52.

TKN.TSK-0
MOU.TSK-0

819-SEP-78 128.
19-SEP-78 128.
19-SEP-78 128.

Ci) TOTAL OF 100. BLOCKS IN 3. FILES
ZK-180-81

Figure 4-1

DOS-11 Directory Listings

Notes on Figure 4-1:

This line identifies the listing as a directory listing.

The device name and unit number.

The User File Directory.

The date the directory was listed.

file name, file type, version number, and sequence number
0 The
(cassettes only).

The file size in decimal blocks.

8 The file creation date.
record size in decimal
0 The
only.)

bytes

for

the

file

total of the actual file sizes
0 Afiles
in the directory.

and

the

total

4D The default protection code provided by the system.

4-9

(cassettes
number

FILE TRANSFER PROGRAM (FLX)
4.3.2

Deleting DOS-11 Files

You can delete files from DOS-11 disks or DECtapes using the Delete
switch (/DE). The /DE switch requires only the file specification for
the file you are deleting. For example:
FLX>DKl: [100,}00]SYSl.MAC/DE
This command line deletes SYSl.MAC under UFD (100,100] from the DOS-11
disk on DKl:.

4.3.3

Initializing DOS-11 Volumes

You can initialize cassettes and DOS-11 volumes using the /ZE switch.
This switch requires only the device specification for the volume you
are initializing. For example:
FLX>DT 1: /Z E
This command line initializes the DECtape on DTl:

4.4

in DOS-11 format.

RT-11 VOLUME DIRECTORY MANIPULATION

You can display RT-11 directory listings, delete RT-11 files, and
initialize RT-11 volumes using the FLX switches described in this
section.
mounted
with
foreign
On RSX-llM-PLUS,
RT-11 volumes must be
characteristics before you can use FLX.
On RSX-llM, the volumes must
be unmounted.

4.4.1

Displaying RT-11 Directory Listings

The /LI or the /DI switch, when combined with the /RT switch,
instructs FLX to send the directory of the RT-11 volume in the input
specification to the Files-11 file in the output specification.
If
you do not enter an output specification, FLX sends the directory to
TI:.
For example:
FLX>DTO:*.MAC/LI/RT
This command lists on your terminal all .MAC files on the RT-11 volume
on DTO:.
Figure 4-2 shows a sample directory listing for an RT-11 disk.

4-10

FILE TRANSFER PROGRAM (FLX)

0 DIRECTORY 8 DK:
e
4-JUN-78
SIPBOO.MAC e 49. 0 4-JUN-78
W < UNUSED >
6.
A

SIP
.MAC
10.
SIPCO .MAC
7.
< UNUSED > 21.
SIPQIO.MAC
7.
< UNUSED > 4686.

4-JUN-78
4-JUN-78
4-JUN-78

8 4 713. FREE BLOCKS
ft TOTAL OF 73. BLOCKS IN 4. FILES
ZK-181-81

Figure 4-2

RT-11 RK05 Cartridge Disk Directory Listing

Notes on Figure 4-2:

This line identifies the listing as a directory listing.

0 The device name and unit number.

e The date the directory was listed.
0

The file name and file type;

<UNUSED> indicates free space.

e The number of blocks in the file or free space.
G The file creation date, or blank for free space.
0 The total number of free blocks on the volume.
0 The total number of blocks allocated to files on the volume.

4-11

FILE TRANSFER PROGRAM (FLX)
4.4.2

Deleting RT-11 Files

You can delete files from RT-11 disks or DECtapes using the Delete
switch {/DE) with the RT-11 switch {/RT). The command line on which
you specify /DE/RT requires only the file specification for the file
you are deleting. For example:
FLX>DKl:SYS/.MAC/DE/RT
This command line deletes SYS/.MAC from the RT-11 volume on DKl:.

4.4.3

Initializing RT-11 Volumes

You can initialize RT-11 volumes using the /ZE switch with the /RT
switch. The /ZE switch requires only the device specification for the
volume you are initializing. For example:
FLX>DTl:/ZE/RT
This command line initializes the DECtape on DTl:
in RT-11 format.
When you initialize RT-11 volumes, the /ZE switch takes an optional
argument in the form:
/ZE:n
The value n specifies the number of extra words per directory entry.
A directory segment consists of two disk blocks with a total of
512(10) words. The directory header uses five words, leaving 507(10)
words for directory entries.
Normally, each directory entry uses seven words;
two directory
entries within each directory segment are allocated to the file
system. Therefore, the number of entries in each segment {when no
extra words are specified) is determined as follows:
Directory entries

{507/7)-2
72-2
= 70

Some RT-11 applications require extra words in the directory entries.
When you specify extra words for directory entries {/ZE:n), the number
of directory entries is determined as follows:
Directory entries = [507/(n+7)]-2
For example, 61(10) entries can be made per directory segment
specify /ZE:l.

you

Use of the /NU switch with the /ZE and /RT switches specifies the
number of directory segments to allocate to the RT-11 volume. The /NU
switch has the following form:
/NU:n

4-12

FILE TRANSFER PROGRAM (FLX)
The value n specifies the number of directory segments to allocate.
Four directory segments are allocated by default. The maximum number
of segments that can be allocated is 37(8) or 31(10). For example:
FLX>DTO:/ZE:2/NU:6/RT
This command line initializes the DECtape on OTO:
in RT-11 format,
allocates two extra words per directory entry, and allocates six
directory segments. This results in a total of 54(10) directory
entries, each of which uses 9 words.

4.5

FLX TA11/TU60 CASSETTE SUPPORT

FLX supports the DIGITAL standard cassette file structure. Files can
be transferred to and from cassettes in either Files-11 format (/RS)
or DOS-11 format (/DO). The transfer mode selected depends on the
file format requirements.
The file formats for Files-11 or DOS-11 cassette files are almost the
same;
that is, they both conform to the DIGITAL standard cassette
file format. The differences between the Files-11 and DOS-11 cassette
file formats are shown in Table 4-3.
Table 4-3
Differences Between Files-11 and DOS-11 Cassette Files Format
Files-11 Format

DOS-11 Format

Standard level 2

Standard level 0

12-character file name (9character file name and 3character file type)

9-character file name (6character file name and 3character file type)

Blocks of any size up to
512(10) bytes (128 decimal
bytes default)

128(10)-byte blocks

Version numbers

No version numbers

Files-11 cassette file format (level 2) is a superset of the DOS-11
cassette file format (level 0). Therefore, any cassette written in
DOS-11 format can be read in Files-11 format. The reverse of this,
however, is true only when:
•

The Files-11 file is written with 128(10)-byte blocks.

•

The extra file header data (such as version number),
does not appear in DOS-11 files, can be ignored.

which

Files-11 files and DOS-11 files can be mixed on a given cassette as
long as you use a proper retrieval mode when you access the file.
Files of various block sizes can also share a given cassette.
FLX
uses the block size contained in the file label data when reading a
file.

4-13

FILE TRANSFER PROGRAM (FLX)
4.5.1

Multivolume Cassette Support

FLX supports multivolume cassette files in both
formats.
No special switches are required
multivolume file is being accessed.

4.5.2

Files-11 and DOS-11
to notify FLX that a

FLX Cassette Output Files

When FLX detects the physical end-of-tape for an output cassette,
following sequence of events occurs.
1.

the

FLX issues the following message:
FLX -- END OF VOLUME ON CASSETTE
CTn: [g,m]
The variables n, g, and m specify
number, and member number.

The cassette is rewound.

FLX issues an additional message:
MOUNT NEW CASSETTE?
FLX>

the

unit

number,

group

(Y, Z (OUTPUT ONLY) OR CR)

At this point, you have three alternatives:
a.

Mount the next output cassette volume and type Y,
followed by a carriage return.
If you select this
alternative, the new output cassette is rewound, FLX
searches for the logical end-of-tape (end of the last
file), and then continues transferring data onto the
tape.
If FLX, while searching for logical end-of-tape,
encounters a file with the same file name as the current
input file, it displays the following message:
FLX

FILE ALREADY EXISTS

FLX then returns to step 3.
b.

Mount the next output cassette volume and type Z,
followed by a carriage return. The new output cassette
is rewound, and FLX continues by transferring data onto
it.
Thus, the tape is effectively zeroed (initialized)
before data is transferred to it.

Enter a carriage return to terminate the transfer.
assumes
that
If you select this alternative, FLX
end-of-file
(EOF)
is desired and issues the following
message:
FLX -- REQUEST TERMINATED -- LAST BLOCK NOT WRITTEN
This message indicates that the last input
processed was not written onto the tape.

4-14

file

block

FILE TRANSFER PROGRAM (FLX)
4.5.3

FLX Cassette Input Files

When FLX detects the physical end-of-tape for an input
following sequence of events occurs:
1.

cassette,

the

FLX issues the following message, including the input
specification on which the end-of-tape was detected:

file

FLX -- END OF VOLUME ON CASSETTE
CTn:[g,m]filename.type
The variables n, g, and m specify
number, and member number.
2.

The cassette is rewound.

FLX issues an additional message:
MOUNT NEW CASSETTE:
FLX>

the

unit

number,

group

(Y, Z (OUTPUT ONLY) OR CR)

At this point you have two alternatives:
a.

Mount the next input cassette volume and type Y, followed
by a carriage return to continue.
If you select this
alternative, the new input cassette is rewound, and a
validity check is performed on the fil~ label and
sequence number.
If the file label and sequence number
are correct, FLX begins processing data from the volume.
If, however, the file label and sequence number are not
correct, FLX issues the following message:
FLX

FILE NOT FOUND

The process then returns to step 3.
b.

Type a carriage return to terminate the transfer.
If you
select this alternative,
FLX assumes that end-of-file
(EOF) is desired, and the transfer is terminated.
If the
input file is being processed as a formatted binary or an
ASCII file, a format error may occur.
If you enter Z, FLX prints the message:
FLX -- BAD RESPONSE
The process then returns to step 3.

4.6

FLX PAPER TAPE SUPPORT

FLX supports the DIGITAL standard paper tape devices, such as the
PC-11 Paper Tape Reader/Punch and the PR-11 Paper Tape Reader, as
DOS-11 devices.
FLX lets you delimit records on paper tape for files in formatted
binary mode or in formatted ASCII mode.
Formatted binary records are
delimited by standard DOS-11 4-byte headers and a trailing checksum.
Formatted ASCII records that do not already end with line feeds or
form feeds are delimited by carriage return-line feed pairs.

4-15

FILE TRANSFER PROGRAM (FLX)
FLX gives special treatment to files that normally default to image
mode transfers, that is; .TSK, .OLB, .MLB, .SYS, .SML, .EXE, and .ULB
files.
On output to paper tape, these files are written, by default,
in formatted binary.
When read back from paper tape to a Files-11
volume, the file is written
by
default,
with
fixed-length,
512(10)-byte records.
These defaults ensure that when the files are read back from paper
tape they are in the same format as they were before being punched.
However, the new files are not contiguous unless you specify /CO/BL:n
with the output file specification.
You must know an appropriate
value for n (the number of contiguous blocks to allocate)
before
issuing the command. You can also use PIP to create a contiguous file
from the file that is read back from tape (see Chapter 3).
The use of explicit transfer mode switches to transfer .TSK,
.OLB,
.MLB, .SYS, .SML, .EXE, and .ULB files between paper tape and Files-11
volumes can cause files read back from paper tape to be different from
the files that were originally written out.
For FLX paper tape transfer commands, you cannot specify file names in
the output specification.
The file name entered for the input file
specification is used as the file name for the output file.
For
example:
FLX>DKl:/RS=PR:CRTMAC.DAT/DO
This command line
DKl:CRTMAC.DAT.

writes

output

file

whose

file

name

If you do not specify a file name on the input file specification, the
default file name is .;n where n represents the latest version number.
RSX-llM and RSX-llM-PLUS systems support paper tapes only as DOS-11
devices.
Therefore, you must specify the /DO switch with paper tape
file specifications.
The following examples
show
paper
tape
specifications for input and output file specifications:
FLX>PP:/DO-CRTMAC.DAT/RS
FLX>DK:/RS=PR:CRTMAC.DAT/DO
To copy from one paper tape to another, use the
(/IM) regardless of the format of the paper tapes.

Image-Mode switch
For example:

FLX>PP:/DO/IM=PR:/DO

4.7

FORTRAN DIRECT ACCESS FILES

FORTRAN direct access files must be transferred in
example:

Image

mode.

For

To recover the file, you must specify the record length in bytes
to exceed 512(10) bytes). For example:

(not

FLX>DKO:/DO/IM=FOO.TJP/RS

FLX>/RS/IM:n=DKO:FOO.TJP/DO
The variable n specifies the record length in bytes.

4-16

FILE TRANSFER PROGRAM (FLX)
4.8

FLX ERROR MESSAGES

Errors encountered by FLX during processing are reported on the
initiating terminal. The FLX error messages, their explanations, and
suggested user actions are described in this section.
FLX -- BAD LIST FILE SPEC
Explanation:
1.

One of the following was specified:

More than one output file for an /LI or /DI operation.

2. Wildcards in the output file specification for an /LI or
operation.
User Action:

/DI

Reenter the command line correctly.

FLX -- BAD RESPONSE
Explanation:

Z was entered in response to the message:

MOUNT NEW CASSETTE {Y, Z {OUTPUT ONLY) OR CR)
FLX>
The cassette in question is an input volume.
User Action:
redisplayed.

Respond

with

after

the

message

FLX -- CAN'T OPEN @ FILE
Explanation: The specified indirect command file
opened for one of the following reasons:

could

not

•

The file is protected against access.

•

A problem exists on the physical device (for example, the disk
is not spinning).

•

The volume is not mounted or is allocated to another user.

•

The volume is not on-line.

•

The specified file directory does not exist.

•

The named file does not exist in the specified directory.

User Action:

Correct the condition and reenter the command line.

FLX -- CO FILES TO OUTPUT DEVICE NOT ALLOWED
Explanation: An illegal output device
tape) was entered with the /CO switch.
User Action:
switch.

{for

example,

magnetic

Reenter the command line without specifying the /CO

4-17

FILE TRANSFER PROGRAM (FLX)
FLX -- CASSETTE ERROR I/O TERMINATED
Explanation: A hardware error occurred during the end-of-volume
sequence on a cassette volume. The transfer was aborted.
User Action:

Reenter the command line using a new cassette.

FLX -- COMMAND SYNTAX ERROR
Explanation: The command was entered in a format that
conform to syntax rules.
User Action:

does

not

Reenter the command line with the correct syntax.

FLX -- CONFLICTING TRANSFER MODES SPECIFIED
Explanation:
For example:

Conflicting transfer mode qualifiers were

entered.

SYO:=DTO:FOO.OBJ/IM/FB
User Action: Reenter the command line
mode switch specified.

with

only

one

transfer

FLX -- DOS-11 OR RT-11 DEVICE NOT VALID FORMAT
Explanation: The device specified with the /DO switch has an
incorrect DOS-11 file structure, or the device specified with the
/RT switch has an incorrect RT-11 file structure.
User Action: Correctly identify the file
volume, and then reenter the command line.
FLX -- DT:

structure

each

reenter

the

UFD FULL

Explanation:

The DECtape directory is full.

User Action: Delete
command line.

all

unnecessary

files,

and

FLX -- END OF VOLUME ON CASSETTE
MOUNT NEW CASSETTE? (Y, Z (OUTPUT ONLY) OR CR)
Explanation:
Physical end-of-tape
cassette transfer.
The tape is
mount the next cassette.

was encountered during
a
rewound and you are asked to

User Action: See Section 4.5.2 if an output
performed or Section 4.5.3 if an input
performed.

4-18

transfer
transfer

is
is

being
being

FILE TRANSFER PROGRAM (FLX)
FLX -- ERROR DURING DIRECTORY I/O
Explanation:

One of the following conditions may exist:

The volume is not write-enabled.

The /DO, /RT or /RS switches were incorrectly specified.

The volume is not in the proper format.

A hardware error occurred during a
{for example, bad tape).

directory

I/O

User Action: The following responses correspond {by
the conditions listed above.

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

Reenter the command line.

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.
FLX -- WARNING
Explanation:
of sequence.

with

the

file

name

and

accessed

out

INPUT FILE OUT OF SEQUENCE
A multivolume cassette file is being

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
Explanation:
specified.

More than one level of indirect

User Action: Reenter the command line with
indirect command file specified.

4-19

command
only

one

file

was

level

FILE TRANSFER PROGRAM (FLX)
FLX -- @ FILE SYNTAX ERROR
Explanation:
file.

A syntax error occurred

the

User Action: Edit the indirect command file.
the corrected indirect command file.

indirect
Rerun

command

FLX

using

FLX -- FMTD ASCII RECORD FORMAT BAD
or
FLX -- FMTD BINARY RECORD FORMAT BAD
Explanation: Either the file is
specified type.

corrupted

not

the

User Action:
If the file is corrupted, no recovery is possible.
If
the file type is incorrect, reenter the command line
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
Explanation: More than one input or output specification
command was entered where only one is allowed.
User Action:

Reenter the command line with the proper syntax.

FLX -- INVALID DEVICE
Explanation: A device was specified that cannot be used for the
purpose specified. For example, a line printer was specified as
an input device.
User Action:
specified.

Reenter

the

command

line

with

valid

device

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:

Reenter the command line with the proper syntax.

4-20

FILE TRANSFER PROGRAM (FLX)
FLX -- INVALID SWITCH
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 off-line.

•

A hardware error occurred (for example, bad tape).

User Action: Ensure that the device is on-line.
Reenter the
command line.
If a hardware error recurs, recovery may not be
possible.
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 device is not on-line.

•

The specified volume is not mounted.

•

A hardware error occurred (for example, bad tape).

User Action: Ensure that the device is on-line and is operable.
Reenter the command line with the required switch specified.
FLX -- I/O ERROR ON COMMAND INPUT
Explanation: An unexpected
error
in
command
input
was
encountered from either an' indirect command file or from the
initiating terminal;
FLX exits.
User Action:

Restart FLX.

4-21

FILE TRANSFER PROGRAM (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 SYO: for
operations involving DOS-11 CT, DT, or MT volumes.
This error
occurs when one of the following conditions exists:
•

SYO:

is not on-line and mounted.

•

SYO:

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/0 ERROR ON LIST FILE
Explanation: An error occurred on the output device during a /DI
or /LI operation.
There is a hardware problem with the output
device (for example, a 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
operation that does not allow one.
User Action: Reenter the command line
specification.

was

without

entered
an

for

output

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

4-22

FILE TRANSFER PROGRAM (FLX)
FLX -- REQUEST TERMINATED -- LAST BLOCK NOT WRITTEN
Explanation: A carriage return 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 written.
Therefore, the output file is incomplete.
User Action:
required.
FLX -- WARNING

This

message

informational.

SPECIFIED RECORD SIZE BAD, 512.

action

USED

Explanation: The record size n specified with the /FA, /FB, or
/IM switch is not acceptable. A record size of 512(10) bytes is
assumed.
User Action:

This is a warning message.

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:

Correct the condition and reenter the command line.

FLX -- UNABLE TO OPEN LIST FILE
Explanation: The list file cannot be opened under the specified
file name and directory, or the specified volume may not be a
valid Files-11 volume.
User Action: Reenter the command
file name and directory.

4-23

line

specifying

the

correct

FILE TRANSFER PROGRAM (FLX)
FLX -- UNDIAGNOSABLE REQUEST
Explanation:

FLX does not recognize the command line syntax.

User Action:

Reenter the command line with the proper syntax.

FLX -- /CO FILES FROM INPUT DEVICE NOT ALLOWED UNLESS BL:

SPEC

Explanation: When transferring files from MT, PR, or CT volumes,
the /CO switch can only be specified when the /BL switch is also
specified.
User Action:
switch.
FLX --

Reenter

the

command

line,

specifying

the

/BL

* IN VERSION NUMBER NOT ALLOWED

Explanation: A wildcard was detected in the version number field
of a file specification.
User Action: Reenter the command line with all
explicitly specified.

version

numbers

FLX -- ILLEGAL DENSITY VALUE
Explanation: Either the specified density value is not supported
by the target tape drive or some value other than 800, 1600 or
6250 was input.
User Action:

Reenter the command with the proper density value.

4-24

CHAPTER 5
DISK VOLUME FORMATTER (FMT)

The Disk Volume Formatter (FMT) utility formats and verifies disk
cartridge, disk pack, fixed media disk, and flexible disk volumes
under any RSX-llM or RSX-llM-PLUS operating system that includes on
line formatting support in the Executive.
(Check with your system
manager to determine whether your system includes this feature.)
In general, FMT performs the following functions:

5.1

•

Writes a complete header for each sector of the volume
formatting.

•

Verifies the address contents of each sector header.

•

Sets the density for RX02 floppy disks (DY).

•

Lets you specify an error limit for the volume
being
formatted.
FMT terminates processing when the error limit is
reached.

•

Lets the Bad Block Locator task
system permits spawned tasks.

(BAD)

run

(spawn)

your

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 comma~d line is:
>FMT ddn:[/switch l ••• /switch m]
The variable dd is the abbreviation for the volume you are formatting
and n is the unit number of the volume. The possible switches are:
/BAD
Runs the Bad Block Locator task (BAD) if it is installed
system.
Note that the /BAD switch can only be used with operating
that ~~}ow spa\\'nil'lg ?f . . tasks. ~f)X~llM p'('QV ~$($
aJ5 $t:em>
tion qptJO:t'l •

5-1

the

DISK VOLUME FORMATTER (FMT)
/DENSITY or /DENS
Selects high {double) or low {single)
disks.

density

for

RX02

floppy

/ERL
Determines the number of errors FMT will allow on the volume.
/MANUAL or /MAN
Enters manual operating mode and formats the sector or track
specify.

you

/NOVERIFY or /NOVE or /-VERIFY or /-VE
Inhibits the default verification of a successful FMT operation.
/OVR
Overrides or ignores the Manufacturer's Defined Bad
{MDBSF) •

Sector

File

Rewrites the MDBSF {on the last track of the device)
sectors found during FMT operation.

bad

/WLT
add

/VERIFY or /VE
Verifies that an FMT operation was successfully completed.
switch is the default.

This

/@Y
Informs FMT that it is rece1v1ng input from an indirect command
file that you have created.
A FMT command in this form does not
allow operator intervention in the process.
These switches are described in detail in Section 5.4.
To terminate FMT, type CTRL/Z
{AZ)
following
explained in Chapter 1 of this manual.

5.2

the

FMT

prompt,

MODES OF FMT OPERATION

FMT lets you format volumes in two operating modes:
normal and
manual.
In normal operating mode, FMT formats the entire volume.
In
manual operating mode, FMT permits you to
format individual sectors
{or tracks for DM:-type disks) that you specify in response to FMT
prompts.
FMT uses normal operating mode unless you specify manual
mode with the /MAN switch in the command line.
FMT normally retries an operation when it encounters an error.
If the
operation still fails,
FMT flags the sector as bad and displays the
following message:
Error writing header

5-2

DISK VOLUME FORMATTER (FMT)
If FMT encounters an error during the verification
prints one of the following messages on your terminal:

operation,

Error reading header
or
Header compare error
FMT then continues the verification operation.

5.2.1

Normal Operating Mode

When you invoke FMT in normal operating mode
switch), FMT prints the following message:

** WARNING - Data will be lost on ddn:
Continue?
[Y or N]

(without

the

/MANUAL

CAUTION
If you answer yes, FMT erases all
previously stored on the disk.

data

After a Y (yes) response, FMT returns the message:
Start formatting
It then performs the formatting functions you specify with switches in
the FMT command. After an N (no) response or a carriage return, FMT
returns control to the system monitor.
Normal FMT operation varies slightly according to the volume
formatting (see Section 5. 3).

5.2.2

Manual Operating Mode

If you specify manual operating mode (/MAN), FMT prints:

** WARNING - Data will be lost on ddn:
Continue? [Y or N]

CAUTION
If you answer yes, FMT erases all
previously stored on the disk.
After a Y (yes)

response, FMT returns the message:

Entering manual mode
It then displays the following prompts:
Cylinder=
Track
Sector
5-3

data

you

are

DISK VOLUME FORMATTER (FMT)
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 pound sign (#) to indicate an explicit octal
response.
If you enter a parameter that is out of the range for the
volume, FMT returns an error message and exits. Table 5-1 lists the
valid ranges for FMT manual mode operations.
Note that FMT manual operating mode cannot be used
disks.

with

RX02

floppy

FMT manual operating mode works the same on all disk volumes, with one
exception:
On DM:-type volumes (RK06 and RK07), FMT formats a
specific track.
For example:
FMT>DMO:/MAN
This command causes FMT to prompt:

** WARNI~G - Data will be lost on DMO:
Continue? [Y or N] Y

Entering manual mode
Cylinder= 237
Tr~ck
= 1
FMT then formats the entire track you specified.
Table 5-1
Ranges for Manual FMT Operations
Devicel

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

RP05

0-21

0-18

0-410

RP06

0-21

0-18

0-814

RK05/RK05F

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

RM05

0-31

0-18

0-822

RM80

0-31

0-13

0-558

5-4

DISK VOLUME FORMATTER (FMT)
5.3

FMT SUPPORTED DISK VOLUMES

The following sections describe using normal FMT operating mode with
the different types of FMT supported devices. Table 5-2 lists the
disk volumes that allow formatting and their device mnemonics.
Table 5-2
FMT-Supported Disk Volumes
Disk Volumes

Device Mnemonic

RP04 disk pack
RP05 disk pack
RP06 disk pack

DB:
DB:
DB:

RK05 disk cartridge
RK05F fixed media disk

DK:
DK:

RLOl disk cartridge
RL02 disk cartridge

DL:
DL:

RK06 disk cartridge
RK07 disk cartridge

OM:
OM:

RPR02 disk pack
RP02 disk pack
RP03 disk pack

DP:
DP:
DP:

RM 02 disk pack
RM03 disk pack
RM05 disk pack
RM80 fixed media disk

DR:
DR:
DR:
DR:

RX02 floppy disks

DY:

The status FMT requires for the disk volumes varies with the operating
system.
On an RSX-llM operating system, the disk volume must be
unmounted.

5.3.1

DB:-type Devices (RP04/RP05/RP06 Disk Packs)

When FMT formats a DB:-type volume, it tries to write 22 sector
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.
Unless you specify the /-VE switch, FMT verifies 11 headers at a time
until it has verified the volume. If FMT encounters an error, it
attempts to verify the headers individually to determine wh~re the
error occurred.
It then reports any bad headers and continues the
operation.

5-5

DISK VOLUME FORMATTER (FMT)
5.3.2

DK:-type Devices (RKOS Disk Cartridge or RKOSF Fixed Media Disks)

When FMT formats a DK:-type volume, it tries to write each sector
header individually until it has formatted the entire volume.
If FMT
encounters an error, it retries each header before reporting the
header as bad.
Unless you specify the /-VE switch, FMT verifies 12 headers at a time
until it has verified the 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.

5.3.3

DL:-type Devices (RL01/RL02 Disk Cartridges)

FMT does not format a DL:-type volume, but reads each block, one track
at a time, and determines which blocks were marked as bad by the
manufacturer's formatting process.
If the MDBSF is corrupt or has
been written over,
FMT then rewrites the Manufacturer Detected Bad
Sector File (MDBSF) on the last track with this information.
When
using FMT on a DL:-type device, the Write Last Track switch (/WLT)
must be specified.

5.3.4

DM:-type Devices (RK06/RK07 Disk Cartridges)

FMT writes DM:-type 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 before it designates which
headers are bad.
Unless you specify the /-VE switch, 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 track has been written,
each sector is read and the full 256 words of data are 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 DM:-type devices, it sets bad sector flags
in the headers already marked as bad in the MDBSF.
Unless you specify
the /-VE switch, FMT indicates whether the bad sector was flagged
in
the MDBSF.

5.3.5

DP:-type Devices (RPR02/RP02/RP03 Disk Packs)

When FMT formats a DP:-type volume, it tries to write 10 headers at a
time until
it has formatted the volume.
If FMT encounters an error,
it attempts to write each header individually and designates which
headers are bad.
Unless you specify the /-VE switch, FMT verifies 10 headers at a time
until
it has verified the 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.

5-6

DISK VOLUME FORMATTER (FMT)
5.3.6

DR:-type Devices (RM02/RM03/RM05/RM80 Disk Packs)

When FMT formats a DR:-type volume, it tries to write 32 headers at a
time until it has formatted the volume.
If FMT encounters an error,
it attempts to write each header individually and designates which
headers are bad.
Unless you specify the /-VE switch, FMT verifies 16 headers at a time
until it has verified the 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
verification operation.
When FMT writes headers on DR:-type volumes, it sets bad sector flags
in headers already designated as bad by the MDBSF. Unless you specify
the /-VE switch, FMT indicates whether the sector was marked bad in
the MDBSF.
On the RM80 disk, in addition to performing the functions indicated
for other DR:
devices, FMT reads a Skipped Sector File to identify
the sectors the manufacturer's formatter designated as "skipped
sectors," and then sets the skipped sector flag bit in the appropriate
sector headers. All data originally intended for a sector designated
as a skipped sector is moved to the following sector {for more
information, see the RSX-llM/M-PLUS I/O Drivers Reference Manual).

5.3.7

DY:-type Devices (RX02 Floppy Disks)

You can use,FMT to set an RX02 floppy disk to either high (double)
or
low (single)
density by using the /DENS switch. Unless you specify
the /-VE switch, FMT writes and reads block 0 and the last block on
the disk to determine that the density is consistent.
Note that manual operating mode cannot be used with DY:-type devices.

5.4

FMT SWITCH DESCRIPTIONS

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.
/BAD
The Bad switch spawns the Bad Block Locator task {BAD) after FMT
completes its processing. The BAD operation tests for the number
and location of any unusable blocks. BAD records this bad-block
information which is used by the initializing function.
If BAD
is not installed on the system, FMT prints a warning message on
your terminal and exits.
Note that the /BAD 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.
The format for an FMT command using the /BAD switch is:
FMT>dd n : /BAD

5-7

DISK VOLUME FORMATTER (FMT)
/DENSITY
The Density switch sets DY:-type floppy disks to either high
(double)
or low (single) density. The default is low density.
(This switch can also use SINGLE and DOUBLE as options.)
The formats for an FMT command using the /DENS switch are:
FMT>DYn:/DENS=HIGH (or DOUBLE)
FMT>DYn:/DENS=LOW (or SINGLE)
/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 the operation. The default
error limit is 256(10) errors. Any value greater than O or less
than or equal to 256(10) is valid.
The format for an FMT command using the /ERL switch is:
FMT>ddn:/ERL=n.
/MANUAL
The Manual switch puts FMT in manual operating mode and permits
you to format an individual sector (or track for DM:-type disk
cartridges) of a device. FMT assumes cylinder, track, and sector
numbers are decimal values unless they are preceded by a pound
sign (#),which indicates octal values.
Note that manual operating mode
devices.

cannot

used

with

DY:-type

In manual operating mode, FMT displays the following prompts:

** WARNING - Data will be lost on ddn:

Continue [Y OR N]?
Entering manual mode
Cylinder=
Track
Sector =
Operation complete
The format for an FMT command using the /MAN switch is:
FMT>ddn :/MAN
/NOVERIFY
The Noverify switch inhibits
default /VERIFY switch.

the

operation

performed

The format for an FMT command using the /NOVERIFY switch is:
FMT> ddn:/NOVERIFY

5-8

the

DISK VOLUME FORMATTER (FMT)
/OVR
The Override switch causes FMT to
ignore the Manufacturer's
Detected Bad Sector File
(MDBSF)
on DM:- and DR:-type 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 the reporting operation.
The format for an FMT command using the /OVR switch is:
FMT>ddn :/OVR
/VERIFY
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. This switch is the default.
The format for an FMT command using the /VE switch is:
FMT>ddn:/VE
/WLT
The Write Last Track switch, when used with the Verify switch on
DM:- and DR:-type volumes, rewrites the MDBSF 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 must be specified when using FMT
device.

DL:-type

The /WLT switch requires a decimal number {n below) which is used
as the volume's pack serial number.
The format for an FMT command using the /WLT switch is:
FMT>ddn:/WLT=n
/@Y
If you specify the @Y switch, FMT receives input from an indirect
command file that you have created.
In this method of operation,
FMT will not generate any operational messages or warnings to
your terminal.
No user intervention is possible until the FMT
operation is complete.
The format for an FMT command using the /@Y switch in an indirect
command file is:
FMT ddn:/@Y
Note that to run FMT from an indirect command file, FMT must be
installed before hand.
Otherwise, you will receive an error
message and the FMT operation will discontinue.

5-9

DISK VOLUME FORMATTER (FMT)
Example
To format a DK:-type volume using an indirect command file,
create the indirect command file FMTIND.CMD (you can specify any
file name) which contains the following:
FMT DK3:/@Y
Then issue the following indirect command from the prompt:
>@FM TI ND
FMT will start to format the disk, DK3: and the /@Y switch will
inhibit any FMT message from printing on your terminal until
after FMT has finished.

5.5

FMT MESSAGES

This section describes the messages FMT generates, and
responses.

possible

user

Command 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 hardware configuration.
User Action: Determine the correct command line with the correct
device mnemonic and reenter the command.
5-10

DISK VOLUME FORMATTER (FMT)
Device not ready
Explanation: The disk volume was not at operating speed when FMT
attempted to access it.
User Action: Allow the volume to
reenter the FMT command.

reach

operating

speed,

then

Device offline
Explanation: The
configuration.

device

not

the

system

hardware

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;

any

write

access

User Action:

Write-enable the unit and reenter the FMT command.

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 exceeded
either the number of errors specified with the /ERL switch or the
default 256(10) error limit that FMT sets.
User Action:
used.

Set a higher error limit if

the

/ERL

switch

was

Error reading data
Explanation:
from a disk.

FMT encountered an error when it tried to read data

User Action: None required.
continues the verification.

FMT

retries

the

operation

and

Error reading header
Explanation: FMT encountered an error when it tried
header during a verification operation.
User Action: None required.
continues the verification.

5-11

FMT

retries

the

read

operation

a
and

DISK VOLUME FORMATTER (FMT)
Error setting diskette density
Explanation: FMT tried to format a
operation failed.
User Action:
the density.

RX02

floppy

disk

but

the

Check the syntax and reenter the command, resetting

Error writing data
Explanation: FMT encountered an error when
sector headers.

User Action:
None required.
continues the verification.

the

FMT

retries

tried

write

operation

and

Error writing header
Explanation:
header.

FMT encountered an error when it tried to

User Action:

None required.

write

FMT retries the operation.

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
read the MDBSF on the last track of a device.
User Action:
(/OVR).

tried

Reenter the command, including the Override

switch

Fatal hardware error
Explanation: A fatal
configuration.
User Action:

error

occurred

the

system

hardware

Contact your DIGITAL Field Service representative.

Header compare error
Explanation: FMT found an error when it tried to compare headers
with the expected value during a verification error.
User Action:

None required.

FMT retries the operation.

Invalid switch
Explanation: An illegal switch or a switch not
specified device was used in an FMT command.
User Action:

valid

Check the syntax and reenter the command.
5-12

for

the

DISK VOLUME FORMATTER (FMT)
Manufacturer's Bad Sector File corrupt
Explanation: The factory-written bad block data file (MDBSF)
the last track of the disk is in an unusable format.

User Action: Reenter the command with the Override switch (/OVR)
to prevent FMT from trying to use the corrupt bad block data.
Marked bad in Manufacturer's Bad Sector File
Explanation: Indicates that bad block information is recorded in
the MDBSF on the disk.
User Action: None
information only.

required.

This

message

for

your

that

was

Privilege violation
Explanation: FMT attempted an operation on
mounted or allocated to another user.

device

User Action: Reenter the FMT command, using a device that is not
mounted or 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 for the volume.
User Action: Check Table 5-1
(Section
parameters and reenter the command.

5. 2. 2)

for

valid

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: An FMT command specified the Bad switch (/BAD), but
BAD could not be spawned. Either the operating system does not
spawn tasks or BAD is not installed.
User Action: Run the BAD utility separately (see Chapter
more information) •

for

Unrecoverable error - n
Explanation:

An I/O error (number n) caused FMT to terminate.

User Action: Reenter the FMT command and, if the error occurs
again, try the command specifying a different device, or refer to
the error codes in the IAS/RSX-11 I/O Operations Reference
Manual.
~-

5-13

CHAPTER 6
BAD BLOCK LOCATOR UTILITY (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 volume. Then you use the MCR Initialize Volume
command
(!NI),
which
allocates
the bad blocks to the file
[O,O]BADBLK.SYS. The bad blocks are marked as in-use and therefore
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 (see Sections 6.4.1.1 and 6.4.1.2).
You can
use BAD in its task version, which runs at the same time as other
tasks, or in its stand-alone version ([l,Sl]BADSYS.SYS), which runs by
itself on the computer. The stand-alone version is required if you
have a system with a single disk drive.

6.1

BAD COMMAND FORMAT

The command line for BAD is in the following format:
BAD>dev: [/sw] •••
dev
Specifies a physical device. The specification consists of two
alphanumeric characters followed by a 1- to 3-digit octal unit
number and colon.

/sw
Specifies 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.

6.2

BAD SWITCHES

Table 6-1 contains a reference list of BAD switches along with a brief
description of each. For a detailed description of BAD switches see
Section 6.6.

6-1

BAD BLOCK LOCATOR UTILITY (BAD)
Table 6-1
BAD Switches
Function

Switch

For Task and Stand-Alone Versions
/ALLOCATE:volume label
or /ALO:volume label

Prompts you for blocks to be allocated
to BADBLK.SYS and to be entered in the
bad block descriptor file.

/LIST
or /LI

Lists bad blocks as they are located.

/MANUAL
or /MAN

Prompts you for additional bad blocks
which are entered in the bad block
descriptor file.

/OVERRIDE
or /OVR

Creates the bad block descriptor file on
a last-track device.

/PATTERN=m:n
or /PAT=m:n

Specifies the double word data
used to locate bad blocks.

/RETRY

Recovers soft errors.

/UPDATE
or /UPD

Reads the bad block descriptor
and prompts for input.

pattern

file

For Stand-Alone Version Only
/CSR=nnnnnn

Specifies the CSR address of a device
that is not in a standard location.

/VEC=nnn

Specifies the interrupt vector address
of a device that is not in a standard
location.

/WCHK

Causes a write check.

/NOWCHK

Negates /WCHK.

6.3

BAD AND INDIRECT COMMAND FILES

BAD can access an indirect command file that contains a series of
command lines in the following manner:

BAD

BAD>@BADCMDS.CMD
In this example, BAD is invoked and accesses the file BADCMDS.CMD,
which contains a sequence of BAD command lines. BAD executes the
comands and returns with the BAD prompt. BAD allows nested command
files -- one command file can invoke another to a maximum depth of
three.

6-2

BAD BLOCK LOCATOR UTILITY (BAD)
BAD can also be invoked within an indirect command file.
Such a
command file can contain command lines for more than one utility and
is accessed by entering only the file specification preceded by the at
sign. For example:
>@INDIRECT.CMD
The default values for indirect command file specifications are:
d~

uf d
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 command files, see the
RSX-llM/M-PLUS MCR Operations Manual.

6.4

PROCESSING BAD BLOCK DATA

This section contains information on how BAD tests the reliability of
disks and DECtapes and formats bad block descriptor entries and how
the MCR INI command uses bad block information.

6.4.1

Verifying Devices

BAD verifies disks and DECtapes by writing a test pattern onto each of
the blocks on the device, reading the pattern into a buffer in memory,
and comparing the pattern written with the pattern read.
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
/PATTERN switch may be used to specify the double-word test pattern.
Its default values are 165555(8) and 133333(8), which are replicated
128(10) times per block. If BAD finds no bad blocks during individual
testing, the error logging subsystem may still log errors due to long
data transfers.

6.4.1.1 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. On non-last-track devices, BAD storage allows 126(10}
entries of bad block addresses. If more than the maximum number of
entries is recorded, BAD terminates with an error message. There must
be at least one good block in the last 256(10) blocks of the volume
for BAD to create this file, which is called the bad block descriptor
file.

6.4.1.2 BAD and Last-Track Devices - BAD
records
bad
block
information differently on last-track devices than on non-last-track
devices. Last-track devices include the RK06/07,
RLOl/02, RPO? and
the RM02/03/05/80.
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 when the
manufacturer formats the pack. This operation also sets bits in any
6-3

BAD BLOCK LOCATOR UTILITY (BAD)
header that is marked bad in the MDBSF and sets the SDBSF to be empty.
When you run BAD, entries are made in the SDBSF. BAD storage allows
126(10) entries of bad block addresses. The information contained in
the two last-track files is combined to form [O,O]BADBLK.SYS when you
issue the MCR INI command.

6.4.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.
For last-track devices, bad block descriptor entries are recorded as a
double-word in the SDBSF.
The first word of the double word contains
the address of the cylinder on which the bad block exists.
The
high-order
and
low-order
bytes
of the second word contain,
respectively, the track and sector addresses of the bad block.

6.4.3

The INI Command and BAD

Use BAD followed by the MCR INI command to produce a Files-11 volume.
The INI command uses the bad block information to create the file
[O,O]BADBLK.SYS. The [O,O] BADBLK.SYS file has allocated to it those
blocks found to be bad, thus ensuring that the file system does not
allocate a known bad block to a file.
For information on how to use the INI command, see the
MCR Operations Manual.

6.5

RSX-llM/M-PLUS

USING BAD

Before BAD can validate a device, that device must be formatted by the
manufacturer or by FMT (see Chapter 5) •

~~~ ~il.?1: :~~~zte~l•. ~p ~ ~.~~)tin~·i tnu~,t.····· ·~<>·~······ ·~···~··· mo~qt~('.l;

..QQ·.····.· al)/
.....
••·····<
Dis.moµnt·.···.c::C>mm~nct•··•'i.f:. tli~•d~vic.$.<P<>nt<;ri11§.·····a· . i:nounte.d.·•·····V()lume~

Is sue the

MCR

The following example illustrates a typical sequence of steps
introducing a disk (DKl:) to an R~X-llM or RSX-llM-PLUS system.

for

f!S,"+~·.1.~··.· P<Sirilil1~$'.

ALL DKl: ID
FMT DKl: [/sw] ID
BAD DKl: [/sw] ID
INI DKl: [label] [/sw] ID
MOU DKl: [label] [/sw] ID

ALL DKl: ID
MOU DKl:/FOR ID
FMT DKl: [/sw] ID
BAD DKl: [/sw] ID
!NI DKl: [label] [/SW] IBTil
DMOU DKl: ID
MOU DKl: [label] [/sw] ID

6-4

BAD BLOCK LOCATOR UTILITY (BAD)
You may execute BAD while other RSX-llM/M-PLUS tasks are executing.
Note that if the /ALO switch (Section 6.6.1) is used with BAD,
the
volume must be mounted as a Files-11 device and the user must have a
privileged account.

6.5.1

Programming Considerations

This section contains information you should know before you use BAD.

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

6.5.1.2 Device Controller Errors - The error logging subsystem may
log 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.

6.6

BAD SWITCH DESCRIPTIONS

The following sections describe the switches you can use
commands. The command format is described in Section 6.1.

6.6.1

with

BAD

Switches for Both Task and Stand-Alone Versions of BAD

/ALLOCATE:volume label
Causes BAD to prompt you for additional bad blocks which are
added to the bad block descriptor file and allocated to [O,O]
BADBLK.SYS.
The /ALLOCATE switch eliminates the
need
to
reinitialize the disk after updating the bad block descriptor
file.
This switch does not cause BAD to write pattern checks.
NOTE
To use this switch, the volume must be
mounted as a Files-11 device and the
user must be privileged.
/LIST
Causes all bad blocks to be printed by number
(in decimal)
on
your terminal. The bad blocks are listed as BAD performs a data
pattern check on each block. BAD does not list manually entered
blocks that are tested as reliable.
This switch is valid for all
devices.

6-5

BAD BLOCK LOCATOR UTILITY (BAD)
/MANUAL
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 or the SDBSF.
/OVERRIDE
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 IN! 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 with the IN! command to
construct
the
bad
block
file
[O,O]BADBLK.SYS.
See the RSX-llM/M-PLUS
MCR Operations Manual for a description
o-r-the MCR !NI command.
/PATTERN=m:n
Causes BAD to locate bad blocks
double word data pattern.

means

user-specified

The variable m:n represents the two 16-bit octal numbers used as
the double word data pattern. A decimal number may be specified
by placing a period after the number.
/RETRY
Causes BAD to attempt a recovery of hardware errors by means of
the device driver. This also means that soft errors, such as an
ECC (Error Correction Code) correctable error, will be recovered
and the block will be marked as good.
/UPDATE
Causes BAD to immediately read the bad block decriptor file and
prompt you for additional bad blocks. 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.
Examples of the /MANUAL, /ALLOCATE and /UPDATE Switches, which require
user input, are described in the following sections.
6-6

BAD BLOCK LOCATOR UTILITY (BAD)
6.6.2

The /MANUAL, /ALLOCATE and /UPDATE Switches: Examples

If you enter bad blocks by using the /MANUAL,
switches, BAD will prompt you as follows:

/ALLOCATE

/UPDATE

BAD>LBN (S) =
You may then enter bad blocks in the format:
blocknum:number
The variable 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 format.
Both blocknum and number default to decimal values unless preceded by
a pound sign (#),which indicates an octal value. For example:
BAD>LBN(S)=70:3([0
This command enters the block numbers 70, 71, and 72 in the bad block
descriptor file.
If you are using the /ALLOCATE switch, the blocks
are also allocated to [O,O]BADBLK.SYS.
You can also specify a single bad block.

For example:

BAD>LBN (S) = 3 ([IT)
This command enters block 3 in the bad block descriptor
/ALO switch also allocates block 3 to BADBLK.SYS.

file.

The

You can use both of
example:

line.

For

these

BAD>LBN(S)= 100:2,3,

forms

200:100

the

same

command

45:1

This command enters blocks 100, 101, 3, 200 through 299, and 45 in the
bad block descriptor file.
The /ALO switch also allocates these
blocks to (0,0] BADBLK.SYS. You can separate bad block sequences with
a space, tab, or comma.
If you are using the Manual or Update switches, and 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) = ([IT)
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.

6-7

the
Bad

BAD BLOCK LOCATOR UTILITY (BAD)
If you are using the /ALLOCATE switch and enter a carriage return in
response to the prompt, BAD will list all the LBNs allocated to
BADBLK.SYS before it will list the LBNs in the bad block descriptor
file.
For example:
BAD>LBN (s) = ~
LBNs allocated to BADBLK.SYS =
004799:001
000100:002
000003:001
000200:001
LBNs in BAD BLOCK File =
000100:002
000003:001
000200:001
000045:001
BAD> LBN (s) =
In this example, LBNs 100, 101, 003, and 200 are allocated to
[O, 0]
BADBLK.SYS, as is LBN 4799 which is the LBN for the bad block
descriptor file on this particular disk. Note that the LBN for the
bad block descriptor file does not appear in the Bad Block file.
However, this disk has one LBN (LBN 45) which is contained in the Bad
Block file but is not yet allocated to [O,O] BADBLK.SYS. You can now
allocate LBN 45 by entering it in response to the LBN(s)= prompt.
(The "Duplicate block number" message will appear because the LBN
already exists in the Bad Block file.)
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 for the
/MANUAL,
/ALLOCATE, or /UPDATE switch, enter ESCAPE, ALTMODE, or CTRL/Z in
response to the prompt. The bad block descriptor file will then
either be rewritten with the new bad block information (if you are
using the /UPDATE or /ALLOCATE switch) or pattern checking will start
(if you are using the /MANUAL switch). Blocks that you enter manually
and that BAD decides are reliable are included in the bad block
descriptor file.

6.6.3

Switches for Stand-Alone System Version Only

/CSR=nnnnnn
The variable nnnnnn is a new CSR address.
This switch allows you to specify the CSR address of the device
so that it conforms to that of the device in the user's system.
The /CSR switch remains in effect and need not be repeated if
more command lines are issued.

6-8

BAD BLOCK LOCATOR UTILITY (BAD)
/VEC=nnn
The variable nnn is a new interrupt vector address.
This switch allows you to specify the interrupt vector address so
that it conforms to the vector address of the device in the
user's system. The /VEC switch remains in effect if more command
lines are issued.
/WCHK
This switch causes a write-check operation to occur after each
write operation. The switch is not available for DT:-, DX:-, or
DY:-type devices.
/NOWCHK
This switch negates the /WCHK switch.
BAD expects to see
example:

all

switches

single

command

line.

For

BAD>DM3:/0VR/LI/VEC=300/CSR=l74406
This command line locates all bad blocks on DM3:,
ignores the
last-track data, lists all bad blocks, specifies 300 as the interrupt
vector, and specifies 174406 as the CSR address.
All switches are
validated for proper syntax before the actual bad block detection
takes place.

6.7

DEVICES SUPPORTED BY BAD

The devices in Table 6-2 are supported by the stand-alone version of
BAD.
If you have a task version of BAD, the Executive will support
any device suitable to your system's configuration.
Table 6-2
Devices Supported by Stand-alone BAD
Mnemonic

Type

CSR

Vector

RP04/05/06

176700

254

TU58 DECtape I I

1 75600

300

RFll Fixed-Head Disk

1 77460

204

RK03/05/05F Cartridge Disk

1 77404

220

RL01/RL02 Cartridge Disk Pack

174400

160

RK06/07 Cartridge Disk Pack

1 77440

210

RPR02/RP02/03 Disk Pack

176714

3201

1. Nonstandard Vector Address

(continued on next page)

6-9

BAD BLOCK LOCATOR UTILITY (BAD)
Table 6-2 (Cont.)
Devices Supported by Stand-alone BAD
Mnemonic

Type

CSR

Vector

RM02, and RM03,
RM05, RMSO, RP07 Disk Pack

176700

3401

RS03/04

172040

3101

TU56 DECtape

1 77342

214

RASO Fixed Media Disk

177510

154

RXOl Floppy Disk

1771 70

264

RX02 Floppy Disk

1 771 70

3501

MLll Electronic Memory

172000

1. Nonstandard Vector Address

6.8

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 messages are arranged alphabetically beginning with
the text following the device symbol (ddu:).
BAD --ddu:

Allocation Failure

Explanation: BAD failed to allocate the block number sequence
you entered. The I/O failed for a reason other than because the
block number was already allocated to another file. This message
applies to the /ALLOCATE switch only.
User Action: Either the volume is bad or the drive requires
maintenance.
Use another volume or contact your DIGITAL Field
Service Representative to fix the drive.
BAD -- ddu: Bad block file not found
Explanation: The bad block descriptor file could not be read
/UPDATE mode.

User Action: You must use the device without updating the
block file, or reformat the device and destroy all data.

bad

BAD -- ddu: Bad block file overflow
Explanation: BAD detected more than 126(10) entries of bad
blocks. This message usually indicates a device unit failure.
User Action: Either the volume is bad or the drive re qui res
maintenance.
Use another volume or contact your DIGITAL Field
Service Representative to fix the drive.

6-10

BAD BLOCK LOCATOR UTILITY (BAD)
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 already allocated - LBN= numb

Explanation: The block number sequence you entered is already
alloc_ated to a file (the file may or may not be BADBLK.SYS). The
value numb is the sequence you entered.
The block sequence
indicated by numb and list of block numbers which follow numb
were neither allocated to [0,0]BADBLK.SYS nor entered into the
bad block descriptor file.
This message only applies to the
/ALLOCATE switch.
User Action:

Reenter the command line with another value.

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: BAD did not recognize the command line entered from
the keyboard.
User Action:

Reenter the command line.

BAD -- Command too long
Explanation:

The command was longer than 80.

User Action:

Reenter the command line.

characters.

BAD -- ddu: CSR address not in system
Explanation: Self-explanatory. This message occurs only in
stand-alone system version of BAD.
User Action: Reenter the command
value for the /CSR switch.

line,

specifying

the

proper

BAD -- ddu: Device offline
Explanation: In the stand-alone version of BAD, the specified
device is not in the hardware configuration, or the /CSR switch
is improperly set.
User Action: Reenter the command line, setting the CSR
Vector addresses for the device to the proper addresses.

6-11

and

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. BAD ignores any block number sequences you may have
entered after the duplicate block numbers.
This message applies only to the /ALLOCATE, /MANUAL and /UPDATE
switches.
If this message appears when using the /ALLOCATE
switch, it means that the block number which was allocated to
[O,O]BADBLK.SYS already existed in the bad block descriptor file.
User Action: Reenter the command line with another value.
This
message applies to the /MANUAL, /ALLOCATE and /UPDATE switches
only.
BAD -- ddu: Failed to attach
Explanation:
tested.

BAD could not gain control

the

device

User Action: Determine if another task has attached the device.
If so, wait until the task exits or abort the task to gain
control of the device for BAD.
BAD -- ddu: Failed to read BADBLK.SYS header
Explanation: Self-explanatory.
/ALLOCATE switch.

This message only applies to the

User Action:
command.

initialized

The disk must be

using

the

MCR

INI

BAD -- ddu: Failed to read Manufacturer's Bad Sector File
Explanation: A disk-read hardware error occurred while BAD was
attempting to read the factory-written bad block data on the
last-track device cartridge.
User Action:
included.

Reenter the command line with the /OVERRRIDE switch

BAD -- ddu: Failed to read Software Bad Sector File
Explanation: The software-detected bad sector file could not
read in update mode.
User Action:
included.

Reenter the command line with the /OVERRIDE

switch

BAD -- ddu: Failed to write Bad Block File
Explanation: BAD could not write the bad block
condition usually results from a disk write error.
User Action: Reenter the command line.
the disk pack should be discarded.

6-12

file.

This

If the problem persists,

BAD BLOCK LOCATOR UTILITY (BAD)
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 line.

BAD -- ddu: Home block not found
Explanation: BAD was unable to read the
attempting to validate the volume label.
applies to the /ALLOCATE switch.
User Action:
command.

The disk must be

initialized

home block while
This message only
using

the

MCR

INI

processing

BAD -- ddu: Illegal device
Explanation: The device to which bad block
directed does not support a Files-11 structure.
User Action:

You must reformat your device before running BAD.

BAD -- Invalid block number - numb
Explanation: You entered an invalid block number sequence.
value numb is the invalid sequence.

The

User Action: Type another value and reenter the command line.
This message applies to the /MANUAL, /ALLOCATE or /UPDATE
switches only.
BAD -- Invalid switch
Explanation:

Self-explanatory

User Action:

Reenter the command line with a proper switch.

BAD -- ddu: Is an alignment cartridge
Explanation: The factory-written label on the last track of a
last-track device cartridge indicates an alignment cartridge {for
use only by Field Service).
User Action:

Mount and process another cartridge.

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

Reenter the command line with the /OVERRIDE

6-13

last
switch

BAD BLOCK LOCATOR UTILITY (BAD)
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
and specified the right device.

correctly

BAD -- ddu: Not ready
Explanation: The unit had not reached operating speed
attempted to access it.
User Action: Allow the unit
reenter the command line.

reach

operating

when

BAD

speed,

then

BAD -- ddu: Privilege violation
Explanation: An operation was attempted for a
mounted or allocated to another user.

device

that

was

User Action: Allocate another device, mount
necessary), and reenter the command line.

the

device

(if

BAD -- Syntax error
Explanation:

BAD detected a syntax error on the command line.

User Action:
command line.

Determine

BAD -- ddu: Total bad blocks

the

correct

syntax

and

reenter

the

= n.

Explanation: This is an information message indicating the total
number (in decimal) of bad blocks on the volume.
User Action:

Write the bad blocks count on the volume label.

BAD -- ddu: Unrecoverable error n
Explanation:
[n]
is the
driver.

An I/O error caused BAD to terminate.
The value
error code number of the I/O error returned by the

User Action: See the IAS/RSX-11 I/O Operations Reference Manual
for an explanation of the error code number.
If the same error
persists, contact your DIGITAL Field Service representive.
BAD -- ddu: Vector not multiple of four
Explanation:

Self-explanatory.

User Action: Reenter the command line including the /VEC
with the proper value.

6-14

switch

BAD BLOCK LOCATOR UTILITY (BAD)
BAD -- ddu: Volume label incorrect
Explanation: The volume label entered with the /ALLOCATE
did not match the label on the disk.

switch

User Action:
label.

volume

Reenter the command line using the

correct

BAD -- ddu: Write locked
Explanation:

The unit is write-locked.

User Action:

Write-enable the unit and reenter the command line.

6-15

CHAPTER 7
BACKUP AND RESTORE UTILITY (BRU)

The Backup and Restore Utility (BRU) allows you to back up and restore
Files-11 volumes. You can use BRU to transfer 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 backup files with BRO.
In the process
of copying, BRO also reorganizes and compresses files for efficient
storage and access.

You can use BRO stand-alone as well as on-line.
BRU64K is the
stand-alone version on RSX-llM and BRUSYS is the stand-alone version
on RSX-llM-PLUS.
Backup and restore operations take place on
volumes:

disk

and

magnetic

• Disk to tape
• Tape to disk

for backup operations

•

for either backup or restore operations

Disk to disk

tape

for restore operations

In addition to these basic
command qualifiers that:

data

transfer

functions,

BRO

provides

•

Initialize disks

•

Perform selective backup and restore operations

•

Control tape processing such as density, length, rewinding,
appending, and labeling according to the American National
Standard (ANS) X.327-1978

•

Perform volume and data checking

•

Display information such as backup set names and file names

Section 7.9 contains examples of various BRO operations.
more

BRO uses disk and tape volumes for its backup and restore operations.
Input disks must be in Files-11 format.
For tapes and multivolume
backup disks, BRO has its own format.

BRO can also be invoked through the DCL BACKUP command.
For
information, see the RSX-llM/M-PLUS Command Language Manual.

7.1

ON-LINE BRU DISK AND TAPE DEVICE INFORMATION

7-1

April 1983

BACKUP AND RESTORE UTILITY (BRO)
backs up from unmounted, mounted, and mounted foreign disk
I BRU
volumes.

I
I

BRU does not use the file system on input disks.
However, when you
are using a mounted volume for a backup operation, BRU checks the read
access privileges of UFOs and files against the UIC under which BRU is
running.
To back up from a mounted disk volume that is in Files-11
format, you must specify the /MOUNTED qualifier. For unmounted disks
or disks mounted foreign, no qualifier is necessary.
BRU also restores to unmounted and mounted disk volumes. Specify the
/INITIALIZE qualifier to restore to an unmounted volume on an RSX-llM
system or a volume mounted foreign on an RSX-llM or M-PLUS system.
This qualifier initializes the volume to Files-11 format.
To restore
to a mounted Files-11 volume on either
system,
specify
the
/NOINITIALIZE qualifier to indicate to BRU that the disk is mounted
and already in Files-11 format.
BRU backs up to and restores from tape volumes.
The tapes must
unmounted or mounted foreign on RSX-llM or mounted foreign
RSX-llM-PLUS. No qualifier is necessary in either case.

be
on

Table 7-1 summarizes how to initialize and mount a volume on each
I system.
BRU returns an error message for any wrong combination of
conditions.

Table 7-1
Mounting and Initializing Volumes
System
RSX-llM

Volume

Mount Status

Input disk

Not mounted
Mounted Files-11
Mounted foreign

None
/MOUNTED
None

Output disk

Not mounted
Mounted Files-11
Mounted foreign

/INITIALIZE
/NOINITIALIZE
/INITIALIZE

Input tape/
output tape

Not mounted
Mounted foreign

None
None

Input disk

Mounted foreign
Mounted Files-11

None
/MOUNTED

Output disk

Mounted foreign
Mounted Files-11

/INITIALIZE
/NOINITIALIZE

Input tape/
output tape

Mounted foreign

None

RSX-llM-PLUS

Mandatory Qualifier

For more detailed information on Files-11, refer to the IAS/RSX-11 I/O
Operations Reference Manual.
With BRU, you can also specify that a disk volume contain up to 65,500
(64K-36)
files.
The default is the value assigned to the input disk.
See the descriptions of the /HEADERS and /MAXIMUM qualifiers in
Section 7.4 for more information.

7-2

April 1983

BACKUP AND RESTORE UTILITY (BRO)
7.1.1

Backup Sets

A backup set consists of all the data directed to or from a tape or
disk volume (or volumes) during a single backup or restore operation.
Physically, more than one backup set may be contained on a tape or
disk, or a backup set can· extend over several tapes or disks.

7.1.2

Tape Sets and Disk Sets

More than one backup set can be contained on a tape or disk, or a
In either case,
backup set can extend over several tapes or disks.
the resulting output is called a tape or disk set.
A tape or disk set consists of the tape or disk volume (or volumes) to
which data is transferred during a single backup operation.

Backup
Operations - There
are
several
7.1.2.1 Tape and Disk
classifications of disk and tape backup operations to choose from.
You can classify a backup operation by how much of the original tape
or disk you are backing up and also by the format of the output
medium.
The following backup operations are available to you:
•

Full backup

•

Selective backup

•

Conventional backup

•

Image backup (for disks only)

A full backup or a selective backup refers to the files you are
backing up.
A conventional backup or an image backup refers to the
format of the output tape or disk. When you choose to do either a
full backup or a selective backup, you may or may not also choose to
do a conventional backup or an image backup.
The following
operations.

sections

explain

the

different

kinds

backup

7.1.2.2 Full and Selective Backup Operation - A full backup transfers
all the original files to a backup volume (or volumes). Thus, a full
backup ensures that you have a complete copy of the original disk.
A selective backup is a partial backup.
If you do a selective backup,
a subset of the original tape or disk is backed up. You select and
identify the files to be backed up by UFO,
date,
or
file
specification.
One type of selective backup is the incremental
backup.
An
incremental backup is a backup of files by date only.
Incremental
backups and selective backups are helpful over a short time span when
a full backup would take up too much time or system resources.

7-3

April 1983

BACKUP AND RESTORE UTILITY (BRU)
7.1.2.3 Conventional Backup Operation - A conventional backup to tape
copies the files from the original disk to a backup set on a BRO
format tape. The backup set can span multiple tapes and you can
append additional backup sets to a volume (or volumes). You cannot
access the files in the backup set directly.
Therefore, you must
restore the backup set to disk before you can access the individual
files contained in it.
A conventional backup to disk copies the files from the original disk
to another Files-11 disk. You can access the files on the input disk
or the output disk directly, eliminating the need to do a restore
operation.
If the output disk already has a Files-11 structure, you can add the
files from the original disk.
If the output disk does not have a
Files-11 structure, you must use BRO with the /INITIALIZE qualifier to
create a Files-11 structure on the output disk.

7.1.2.4 Image Backup to Disk Operation - An image backup to disk
copies the original disk to a container file on another Files-11 disk
(or disks).
Image backups are used for multivolume backup operations.
A disk container file has features similiar to features of tapes
created by a conventional backup to tape. A disk container file can
span multiple disks, and you can add several backup sets to a
container file.
If you want to do a backup operation, you must specify the SAVE option
with the /IMAGE qualifier.
If you want to do a restore operation, you
must specify the RESTORE option with the /IMAGE qualifier.
In order
to access the files in a backup set, you must restore the backup set
to another disk.
(See Section 7.4 for a description of command
qualifiers.)
If the output disk already has a Files-11 structure, you can add the
container file to it.
If the output disk does not have a Files-11
structure, BRU creates its own structure on the disk with the
container file.

7.1.3

Multivolume Tape and Disk Operations

When you specify a magnetic tape drive as the output device or when
you specify a disk for an image backup in a BRU operation, BRU
transfers the data contents of the input disk to the tape or disk on
the drive.
This data transfer often involves more than one reel of
tape or more than one disk and may use more than one tape or disk
drive.

You can specify more than one type of drive in a single BRO command.
However, although you can specify up to eight drives per command, you
can specify an individual tape or disk drive only once.

If the number of volumes required exceeds the number available, BRO
lets you replace tapes or disks on the specified drive in round-robin
fashion.
You can only use all 7-track or all 9-track tapes in a multivolume
tape set.
You cannot switch from one track type to the other within
the set.

7-4

April 1983

BACKUP AND RESTORE UTILITY (BRO)
disk

disks

You can only use the same disk types when backing up to multiple
in image mode.
You cannot mix disks.

7.1.4

Supported Devices

Table 7-2 lists all the devices that on-line BRU supports.
from DB through EM are all block-structured devices.

The

Table 7-2
Devices Supported by On-Line BRU
Mnemonic

Type

RH11/RP04/RP05/RP06 or RH70/RP04/RP05/RP06 disk
pack

TU58 cassette (DECtape II)

RFll/RSll fixed head disk

RK11/RK05/RK05F cartridge pack

RL11/RL01/RL02 cartridge disk

RK611/RK06/RK07 cartridge disk

RP11/RP02/RP03 disk pack

RH70/RM03/RM05/RM80/RP07 or RH11/RM02 disk pack

RH11/RS03/RS04 or RH70/RS03/RS04 fixed head disk

TC11/TU56 DECtape

RA80/RA60/RA81/RC25/RD51/RX50 disk

RXll/RXOl floppy disk

RX211/RX02 floppy disk

MLll electronic memory

TM78/TU78 magnetic tape

RH11/TM02-03/TE16/TU16/TU45/TU77 and
RH70/TM02-03/TE16/TU16/TU45/TU77
9-track magnetic tape

TS11/TSV05/TU80 magnetic tape

TMll/TElO/TUlO 7- or 9-track magnetic tape or
TS03 9-track magnetic tape

7.2

COMMAND LINES

This section describes the rules for entering command lines for BRU.
The section defines the command line syntax and describes prompts,
command line parameters, and command qualifiers.

7-5

April 1983

BACKUP AND RESTORE UTILITY (BRO)
7.2.l

Command Line Syntax

BRO command lines have a maximum length of 256(10) characters except
in one case of using continuation lines (see Section 7.2.2.2). The
general syntax of the BRO command line is:
BRU>/qualifier(s)

indevicel:, ••• [filespec, ••• ] outdevicel:, •••

However, if you type only
>BRO~

the following three prompts appear on the terminal:
FROM:
TO:
INITIALIZE [Y/N] :
FROM
Requests that you enter the name (or names) of the devices on
which the input volume (or volumes) reside. The names should
be in the form specified in the description of the command line
parameters (see Section 7.2.2).
If you want, you may specify a
UIC, but this is not required.

I
TO

Requests that you enter the name
(or names)
of the output
devices.
The names should be in the form specified in the
description of the command line parameters (see Section 7.2.2).
The UIC should not be specified in the command line because BRU
tries to copy the entire UIC.
INITIALIZE [Y/N]
Enter Y (for YES)

if you want to initialize the output volume.

Enter N (for NO)
volume.

if you do not want to

There is no default answer.
N.

7.2.2

initialize

the

output

You must respond with either Y

Command Line Parameters

The parameters for BRU command lines
specifications, and file specifications.

are

qualifiers,

device

/qualifier(s)
Specifies any of the command qualifiers listed in Section 7.3.
If
two or more qualifiers are specified, they must be
contiguous, that is, separated with a slash only.
The
qualifiers can appear in any order.
You can use a shorter form of a qualifier as long as it is
unique.
All BRU qualifiers are unique to three characters.
For example:
BRU>/REW/INI/OUT:BACKUP MMO:

7-6

DBO:

April 1983

BACKUP AND RESTORE UTILITY (BRO)
When a qualifier has options, you must separate
from the option by a colon in the form:

the

qualifier

/qualifier:option
indevice
Specifies the physical device (or devices) from which data is
transferred.
For tapes and for disks (if you are using the
/IMAGE qualifier) you can specify more than one input device
and more than one type of drive. Devices are specified in the
form:

dd [nn] :
The variable dd represents the device mnemonic
and
nn
represents the octal unit number associated with that device.
The unit number is specified as one or two digits; the default
unit number is O.
For example, a TU77 tape drive can be
referenced as MMOO:, MMO:, MM:, MMOl:, MMl:, and so forth,
depending on your configuration.
The colon is a required
delimiter.
Separate the device specifications with commas when you specify
more than one device.
f ilespec

Indicates the file specification used to select particular
files or categories of files to be backed up or restored. The
file specification is in the following format:
[ufd]filename.filetype;version
You can specify up to 16(10)
file specifications in each
command line.
When you enter a command line with no file
specifications, all the files on the input volume are copied to
the output volume.
Files can be backed up or restored selectively by UFO, file
name,
file type, 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 (*). The wildcard has the same effect as no
version number.
BRO does not support 0 or -1 as version
numbers.
outdevice
Specifies the output device to which data is being transferred.
For tapes and for disks (if you are using the /IMAGE qualifier)
you can specify more than one output device. The form is the
same as for indevice (described previously).

7.2.2.1 Wildcards in Input Specifications - The following wildcard
(*) features are provided for input file UFD specifications:
[*,*] means all group,member combinations.
[nl,*] means all member numbers for group nl.
[*,n2] means all group numbers for member n2.
BRO also supports the wildcard in the remaining elements of a file
specification: file name, file type, and version number. BRO

7-7

April 1983

BACKUP AND RESTORE UTILITY (BRU)
generally follows the rules for use of wildcards
(see
the
RSX-llM/M-PLUS MCR Operations Manual), except in the following two
instances:
•

When you omit a file specification element, BRU treats the
omitted element as if it were a wildcard. For example, when
you specify only file name and file type in a file
specification, all version numbers are transferred in the
backup or restore operation. However, when you omit the
UFO, it defaults to your current urc.

•

When you specify particular UFOs on a command line but do
not specify file names and/or file types, all the files in
those UFOs are transferred in the backup or
restore
operation. That is, you do not have to specify [ufd]*.*·

7.2.2.2 Continuation Lines - BRU command lines have a maximum
length of 256(10) characters. BRU allows you to continue a command
line onto more than one line by using a hyphen
(-)
as the
continuation character.
On RSX-llM systems, BRU supports continuation line!; ... only when you
in\1oke . BR~J ..•and. th.en.·.. respond to tpe . ~RU> protn:r;>t• BRO does not
s~pport. continuation lines . when r.unfrom an.indirect.coinmand fil~ or
wh~n<you .ept:~r ttie command. line on the same line as the one on which
you·tnvoked BRU.,

Section 7.9 gives examples of
RSX-llM-PLUS.

7.3

continuation

lines

RSX-llM

and

SUMMARY OF COMMAND QUALIFIERS, OPTIONS, AND DEFAULTS

Table 7-3 lists the command qualifiers available for backup and
restore operations.
For a detailed explanation of each qualifier,
see Section 7.4.
Examples of using various qualifiers are given in
Section 7.9.
Table 7-3
Summary of BRU Command Qualifiers
Command Qualifiers

Options

Default

/APPEND

None

/BACKUP SET:name
-

Volume name
of the disk
being backed
up
(continued on next page)

7-8

April 1983

BACKUP AND RESTORE UTILITY (BRU)
Table 7-3
(Cont.)
Summary of BRO Command Qualifiers
Command Qualifiers
/BAD:

Options

Default

MANUAL
AUTOMATIC
OVERRIDE

BAD:AUTOMATIC

/BUFFERS:number

Number of
FCBs from the
input disk

/COMPARE

None

/CREATED:

BEFORE:(dd-mmm-yy hh:mm:ss)
BEFORE:dd-mmm-yy
BEFORE:hh:mm:ss
AFTER:(dd-mmm-yy hh:mm:ss)
AFTER:dd-mmm-yy
AFTER:hh:mm:ss

Current date

/DENSITY:number

Default
density of
drive

/DIRECTORY

None

/DISPLAY

None

/ERRORS:number

/ERRORS:25.

/EXCLUDE

None

/EXTEND:number

Number of
blocks from
the input
disk

/HEADERS:number

Number of
headers
allocated
to the input
volume

/IMAGE:

SAVE
RESTORE

None

/INITIAL! ZE

None

/INVOLUME:name

None

/LENGTH:number

The length of
the output
tape
(continued on next page)

7-9

April 1983

BACKUP AND RESTORE UTILITY (BRU)
Table 7-3
(Cont.)
Summary of BRU Command Qualifiers
Command Qualifiers

Options

Default

/MAXIMUM:number

Maximum
number of
files allowed
on input the
volume

/MOUNTED

None

/NEW_VERSION

/NOSUPERSEDE

/NOINITIALIZE

None

/NOPRESERVE

None

/NOSUPERSEDE

/OUTVOLUME:name

Input disk
volume name

/POSITION:

BEGINNING
MIDDLE
END
BLOCK:number

Index file
position on
the input
disk

/PROTECTION:

SYSTEM:value
OWNER:value
GROUP:value
WORLD:value

Protection of
the input
disk

/REVISED:

BEFORE:(dd-rnrnm-yy hh:mm:ss)
BEFORE:dd-mmm-yy
BEFORE:hh:mm:ss
AFTER:(dd-mmm-yy hh:mm:ss)
AFTER:dd-rnrnm-yy
AFTER:hh:mrn:ss

Current date

/REWIND

None

/SUPERSEDE

/NOSUPERSEDE

/TAPE_LABEL:label

None

/UFO

None

/VERIFY

None

/WINDOWS:value

Number of
mapping
pointers on
the input
disk

7-10

BACKUP AND RESTORE UTILITY (BRU)
Command Qualifier Functions

7.3.1

When you initialize a disk using the BRU /INITIALIZE qualifier, use
the following qualifiers to specify various characteristics for the
output disk.
/BAD

/NO PRESERVE

/BUFFERS

/OUTVOLUME

/EXTEND

/POSITION

/HEADERS

/PROTECTION

/MAXIMUM

/WINDOWS

The /MOUNTED command qualifier allows you to copy files from a mounted
disk.
The following command qualifiers allow you to copy files to a
disk with various results.
Note that these qualifiers
available in stand-alone BRU (see Section 7.5).

mounted
are not

/NEW_VERSION
/NO INITIALIZE
/NOSUPERSEDE
/SUPERSEDE
/UFD
The following command qualifiers allow you to backup or
according to:

restore

data

The following qualifiers allow you to control backup and restore
processing:

tape

•

File specification

•

Date and time of creation

•

Date and time of revision

The qualifiers are:
/CREATED
/EXCLUDE
/REVISED

/APPEND

/LENGTH

/BACKUP_SET

/REWIND

/DENSITY

/TAPE_LABEL

/ERRORS

7-11

BACKUP AND RESTORE UTILITY (BRO)
The following command qualifiers allow you to detect differences
between data on the input volume and data on the output volume:
/COMPARE
/INVOLUME
/VERIFY
The /DIRECTORY and /DISPLAY command
about the files being transferred.

qualifiers

display

information

/IMAGE command qualifier is for both disk image backups and all
I The
restore operations.

7.4

DESCRIPTIONS OF COMMAND QUALIFIERS

The following
detail.

paragraphs

describe

the

BRU

command

qualifiers

/APPEND

Directs BRU to append a backup set from the input disk volume to
the last backup set on the output tape, or on the output disk if
you are using the /IMAGE qualifier.
If the output tape was positioned at the beginning the /APPEND
qualifier causes BRU to skip to the logical end-of-tape before it
writes the new backup set. BRU searches the output volume for
the last logical end-of-file.
If the output tape is already positioned at the
logical
end-of-tape, /APPEND causes BRU to start writing where the device
is currently positioned.
If the output tape is not positioned at the beginning, or if it
is not at the logical end-of-tape, you can use the /REWIND
qualifier with /APPEND to rewind the tape and then space forward
until the logical end-of-tape.
If the tape is a continuation tape (that is, not the first
tape
in a set) or if the last backup set does not end on the tape, BRU
displays an error message.
If the output device is a disk and you are using the /IMAGE
qualifier, /APPEND causes BRU to check the container file header
for the logical end-of-file on the output disk. BRU then starts
writing at the logical end-of-file.
If the output disk is a continuation disk (that is, not the first
disk in a set)
or if the last backup set does not end on the
disk, BRU displays an error message.
You cannot use the /APPEND qualifier during a backup operation to
a mounted disk.

7-12

April 1983

BACKUP AND RESTORE UTILITY (BRU)
/BACKUP_SET:name
Specifies the name of the backup set (refer to Section 7.1.1)
to
be placed on tape or disk. For tape and for an unmounted disk,
the default name is the volume name of the disk being backed up.
This name may be up to 12(10) characters long. For a mounted
input or output disk during an image backup or restore operation,
you
can specify the full backup set file name with the
/BACKUP SET qualifier.
If you do not specify the file name, the
default-is [O,O]BACKUP.SYS.
When applied to an output 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.

When this qualifier is applied to an input tape volume, BRU
searches the first tape for the specified backup set name.
If
you do not specify a backup set name with the input volume, BRU
restores the first backup set it finds on the tape. You can
restore several sequential backup sets from the same tape without
rewinding the tape between BRU operations. BRU does not rewind
the first device in a backup set unless you specify the /REWIND
qualifier.
When this qualifier is applied to an input disk volume, BRU
searches the entire disk for each backup set you specify. Each
backup set is then restored in the order of the backup set names
you provided.
/BAD:AUTOMATIC
OVERRIDE
MANUAL
The /BAD qualifier creates the file BADBLK.SYS on the output
disk.
The qualifier is used with the /INITIALIZE qualifier
during tape-to-disk or disk-to-disk operations.
For complete information on how to use the options for /BAD,
Section 7.6. The following are summary descriptions only.

see

For last-track devices, the AUTOMATIC option 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. AUTOMATIC is the default option.
The OVERRIDE option 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
and ignores the
manufacturer-written information.
The MANUAL option accepts the addresses of bad blocks you enter
interactively at your terminal.
It also specifies that BRU use
either the manufacturer-written bad block information and the
software-detected bad sector file (for last-track devices) or the
bad block descriptor block (for nonlast-track devices) to create
BADBLK.SYS.

7-13

April 1983

BACKUP AND RESTORE UTILITY (BRO)
/BUFFERS:number
Specifies the default number of directory File Control Blocks
(FCBs)
on each volume.
The FCBs are stored in memory by the
Ancillary Control Processor (ACP) when the volume is mounted.
The more FCBs there are stored in memory, the faster that files
contained in heavily used directories are found.
The default
number of buffers is the same as 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 line 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, /NOINITIALIZE, and /APPEND qualifiers.
/COMPARE Output
When the compare operation detects differences, it displays
a message at your terminal. The compare operation always
displays the mnemonic of the device on which the difference
was detected and the type of record in which the difference
was encountered (a control record, a header record, or a
data record).
If the record type is a header record, the compare operation
also displays the file-ID for the file.
If the record type
is a data record, the compare operation also displays the
file-ID,
the Logical Block Number
(LBN) of the block in
error, and the name of the file if it is available.
/CREATED:BEFORE:(dd-mmm-yy hh:mm:ss)
BEFORE:dd-mmm-yy
BEFORE:hh:mm:ss
AFTER:(dd-mmm-yy hh:mm:ss)
AFTER:dd-mmm-yy
AFTER:hh:mm:ss
Backs up or restores files created before or after the
date and/or time.

specified

If you use the BEFORE option, BRU copies any files created before
the specified date and/or time.
If you use the AFTER option, BRU copies any files created on or
after the specified date and/or at or after the specified time.
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 the current date as the default.
If you specify
only a date, the time defaults to 00:00.
/DENSITY:number
Specifies the density (bpi) at which BRU writes to
following chart shows the values you can specify.

7-14

tape.

The

BACKUP AND RESTORE UTILITY (BRU)
Drive
TUlO/TElO
TU16/TE16
TU45
TU77
TSll
TSV05
TU78
TU80

Default Density

Optional Density

800
800
800
800
1600
1600
6250
1600

None
1600
1600
1600
None
None
1600
None

I
I

If you specify /DENSITY with /APPEND, you must specify the
density at which the existing tape data was written. For
example, if the tape was first written at a density of 800 bpi,
you must specify a density of 800.
If you specify a density
other than the original density, BRU displays a 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

/DIRECTORY
Lists at your terminal the backup set names or files on the
specified tape or disk volume.
In a multivolume tape set, the
directory is on the first tape of the set.
In a multivolume disk
set, the directory is on the first disk of the set.

Using /DIRECTORY to Display Backup Set Names:
When specified with no backup set name, /DIRECTORY lists all
the backup sets on the volume:
BRU>/DIRECTORY MMO:
VOLl
VOLl

BACKUPl LABELl
BACKUP2 LABELl

2-JAN-83
3-JAN-83

BRU>/DIRECTORY DUO:
VOLl
VOL2

BACKUPl LABELl
BACKUPl LABEL2

13-JUN-83
14-JUN-83

Using /DIRECTORY to Display File Names:
To display the names of files in a backup set, enter the
backup set name with /DIRECTORY in the form shown below.
If the backup set is not on the tape or disk, BRU
execution and displays a message at your terminal.

halts

An example with tape follows:

>RUN BRU
BRU>/BACKUP SET:23MAY82A/DIRECTORY MMl:
VOLl.
23MAY82A
HWHDOC 13-JUN-82 23:37:11
[000,000]
[303,013]
27DECE.LST;l
2JANA.LST;l
18JANC.LST;l
4JANA.LST;2

7-15

April 1983

BACKUP AND RESTORE UTILITY (BRO)
25DECA.MAC;l
9DECA.LST;2
X.MAC;l
X.OBJ;l
X.TSK;l
APNDXC.TXT;l
X.MAP;l
[001,054]
RSX11M.STB;45
[002,054]
RSXllM. STB; 3 6
[003,054]
RSX11M.STB;3
[005,054]
[306,006]
APNDXB.MAC;l
BRU - COMPLETED ON MMl:
BRU> (CTRL/Z)

>
/DISPLAY
Prints at your terminal the file name and UFO of each file as the
header for that file is being transferred by BRU.
/ERRORS:number
Terminates a restore operation after the specified number of
nonfatal· tape read errors. The range for number is 0 to 65535.
The default number of errors before termination is 25(10).
/EXCLUDE

Backs up or restores all of the files on the tape or disk
the files specified on the command line.

except

/EXTEND:number

Specifies the default number of blocks by which a file is
extended when that file has exhau.sted its allocated space. This
value is used by an ACP when the volume is mounted. The default
is the number of blocks from the input disk.
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 bitmap file.
(The storage bitmap
file is generally located in the middle of the disk.) Proper
placement of file headers can help reduce head motion during I/O
operations.
The default is the number of headers allocated to
the input volume.
The /HEADERS qualifier is used with the /INITIALIZE
during tape-to-disk or disk-to-disk operations.

qualifier

If you want to copy files from a disk with a single-header index
file
(structure level 401)
to a disk with a multiheader index
file (structure level 402), specify a number of file headers with
/HEADERS and a number of files with the /MAXIMUM qualifier that

7-16

April 1983

BACKUP AND RESTORE UTILITY (BRO)
are both large enough to make the output disk contain a
multiheader index file.
See the description of the INI command
in the RSX-llM/M-PLUS MCR Operations Manual for a table of
maximum and default values.

/IMAGE:SAVE
:RESTORE
Specifies that you want to do a multiple disk-to-disk backup or
restore operation.
If you are doing a backup operation, you
must specify the SAVE option on the command line.
If you want
to do a restore operation, you must specify the RESTORE option
on the command line.
If you want to do a backup operation, you must use this
qualifier when you create the backup file that represents the
image copy of the input disk or disks.
For example, this
qualifier must be used when you copy a large disk to several
small disks, or if you copy several small disks to a mounted
large disk.
If you want to do a restore operation, you must use this
qualifier when restoring from a backup file that represents the
image copy of the original disk.

/INITIAL! ZE
Specifies that you want to initialize the output disk during a
tape-to-disk or disk-to-disk operation.
Initialization places a
Files-11 structure on the disk, including the boot block, the
home block, and such files as INDEXF.SYS, BADBLK.SYS, and
000000.DIR.
The conditions for initializing an output volume differ between
RSX-llM and RSX-llM-PLUS. BRU returns a privilege violation if
the conditions are not met satisfactorily (see Table 7-1).
On RSX-llM, the volume must he unmounted or mount:ed ~oteign.

Along with the /INITIALIZE qualifier, you can specify
following qualifiers when you are initializing a disk:
/BAD
/BUFFERS
/EXTEND
/HEADERS
/MAXIMUM

the

/NO PRESERVE
/OUTVOLUME
/POSITION
/PROTECTION
/WINDOWS

If you do not specify any of these qualifiers, BRU defaults to
the characteristics of the input volume except for the /BAD
qualifier and the /NOPRESERVE qualifier. For the /BAD qualifier,
the default is AUTOMATIC. For the /NOPRESERVE qualifier, there
is no default.

/INVOLUME:name
Specifies the volume label of the input disk.
up to 12(10) characters long.

This name

can

For disk-to-tape or disk-to-disk operations, the
/INVOLUME
qualifier directs BRU to look for the volume label of the input
volume to verify that the disk has the correct label. This check
ensures that you do not back up the wrong volume.

7-17

April 1983

BACKUP AND RESTORE UTILITY (BRO)

For restore operations, /INVOLUME directs BRU to check the volume
label of the disk that is stored in the backup set on tape or in
the image backup set file on the disk.
/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 is 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 maximum number of files that can be placed on a
volume as determined by the number of file headers in the
volume's index file.
(BRU supports up to 65,500 files on a
volume.)
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 that is different in size from the input disk.
If you want to copy files from a disk with a single-header index
file
(structure level 401)
to a disk with a multiheader index
file (structure level 402), specify a number of files with
/MAXIMUM and a number of file headers with the /HEADERS qualifier
that are both large enough to make the output disk contain a
multiheader index file.
See the description of the INI command
in the RSX-llM/M-PLUS MCR Operations Manual for a table of
maximum and default values.
/MOUNTED

Allows you to back up files from a disk that is mounted as a
Files-11 volume (by means of the MCR or DCL MOUNT commands).
If
you use the /MOUNTED qualifier when the input device is a tape,
BRU issues a syntax error.
BRU does not use the file system to read files from the input
disk.
Instead, it issues logical queue I/Os (such as IO.RLB).
To issue these QIOs to a mounted Files-11 disk, BRU must be built
as a privileged task (PR:O).
(BRU does not have to be privileged
for operations on unmounted volumes or volumes mounted foreign.)
However, when you are restoring to a mounted disk (and you have
specified the /NOINITIALIZE qualifier), BRU uses the file system
to access the output disk. Therefore, a restore operation to a
mounted disk is slower than a restore to an unmounted disk.
BRU must also be privileged to back up a disk that is being
accessed
by other users.
The /MOUNTED qualifier must be
specified in the command line.
When backing up files from a mounted
(changes to or addition or deletion
running causes the following results:

volume, disk activity
of files) while BRU is

•

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 in the file on the
output volume.

•

If the file is deleted while BRU is backing up the
the data that comprises the file may be corrupted.

7-18

disk,

April 1983

BACKUP AND RESTORE UTILITY (BRU)
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 reused file-ID) will appear as a synonym for the old
file with the same file-ID.
•

If the disk is changed (files are deleted or changed)
after BRU generates the directory, the directory on the
first tape of the tape set or the directory in the backup
set file on the disk 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.

•

If the file or data are being changed during a transfer
operation, BRU will not be able to verify the accuracy of
the operation. Do not attempt a verify operation in this
case.

Note that this restriction also includes the file being
used by the error logger. The error logger file changes
when any hardware errors occur, which can cause the
verify operation to fail.
To ensure that the verify
operation succeeds, switch the error logger file to a
different disk or exclude it with the /EXCLUDE qualifier.
/NEW_VERSION
Resolves file specification conflicts that occur during restore
operations and during backups to a mounted disk using the
/IMAGE:SAVE qualifier. When a file already exists on the output
disk volume, /NEW_VERSION creates a new version of the file.
/NOINITIALIZE
Specifies that you do not want to initialize the output disk
because it is already in Files-11 format.
The output disk must
be mounted as a Files-11 volume. You cannot enter any of the
initialization qualifiers when you specify /NOINITIALIZE.
If you
enter any of these qualifiers, BRU issues an error message.
/NO PRESERVE
Specifies that you do not want to preserve file-IDs (file-IDs are
generally preserved).
If you specify the /NOPRESERVE qualifier,
BRU suppresses the message that file-IDs are not being preserved.
Note that in restoring to a mounted disk, not preserving file-IDs
is BRU's default action.
/NOPRESERVE is used only with the
/INITIALIZE qualifier.
When file-IDs are not preserved,
incrementing them sequentially.

BRU

assigns

new

file-IDs,

/NOSUPERSEDE
Specifies that when file specifications on the mounted output
disk are identical to those on the input volume, the file on the
input volume is not transferred. That is, the file on the output
disk is not superseded by the file on the input volume.
/NOSUPERSEDE is the default.

7-19

April 1983

BACKUP AND RESTORE UTILITY (BRO)
/OUTVOLUME:name
Specifies the volume label of the output disk.
up to 12(10) characters long.

This label can be

For disk-to-tape backup operations, the name of the input disk
volume stored on the output tape volume is changed to the name
specified with the /OUTVOLUME qualifier.
For tape-to-disk 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:
•

In backup operations, the input disk volume name is used
as the volume name stored on the output tape volume.

•

In restore operations, the volume name stored on the
input tape volume is used as the name of the output disk
volume.

•

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

Specifies the location of the index file on the output disk
volume being initialized, usually to minimize access time. The
BEGINNING, MIDDLE, and END options specify the beginning, middle,
and end of a volume.
The BLOCK:number option specifies a block
number where the index file is to be placed.
The BEGINNING or
END option is generally used only when a disk mostly contains
large contiguous files. MIDDLE is recommended to minimize access
time.
When you use the BLOCK:number option, the number is decimal by
default
(the period is optional). To specify an octal number,
place a pound sign (#) in front of the number.
If there are any
conflicts, BRU issues a warning message.
When you do not use the /POSITION qualifier, BRU places the index
file in the same location as that on the input volume.
/PROTECTION:

SYSTEM:value
OWNER:value
GROUP:value
WORLD:value

Specifies the default protection status for all files created on
the output volume being initialized. This protection value does
not apply to files being transferred by BRU, but rather to
subsequent files created on the output volume by an ACP when the
volume is mounted.
If you do not specify any values, they
default to the protection values of the input disk.
The protection value can be R(ead), W(rite), E(xtend), or
D(elete), or any combination of the four.
See the RSX-llM/M-PLUS
MCR Operations Manual for an explanation of file protection.

7-20

BACKUP AND RESTORE UTILITY (BRO)
/REVISED:

BEFORE:(dd-mmm-yy hh:mm:ss)
BEFORE:dd-mmm-yy
BEFORE:hh:mm:ss
AFTER:(dd-mmm-yy hh:mm:ss)
AFTER:dd-mmm-yy
AFTER:hh:mm:ss

Backs up or restores files revised
after the specified date and time.

created

on,

before,

If you use the BEFORE option, BRU copies any files
created at or before the specified date and/or time.

revised

If you use the AFTER option, BRU copies any files revised or
created on or after the specified date and/or at or after the
specified time.
As with the /CREATED qualifier, if you specify both a date and
time, the date and time must be enclosed in parentheses.
If you
specify only a date or time, the parentheses are not necessary.
If you specify only a time, BRU uses the current date as a
default.
If you specify only a date, the time defaults to 00:00.
/REWIND

Rewinds 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 a backup set.

When specified with the /APPEND qualifier, BRU rewinds the output
tape and then searches for the logical end-of-tape before
executing the backup operation.
/SUPERSEDE

Specifies that when file specifications on the mounted 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.
For an /IMAGE operation, if you create a backup set file on a
mounted volume and a file with the same name exists, /SUPERSEDE
replaces this file.
/NOSUPERSEDE is the default.
/TAPE_LABEL:label

Specifies the 6-character volume identifier on the JUnerican
National Standard
(ANS) X.327-1978 label to be placed on a tape
during a backup operation or to be compared with the label on the
tape for append and restore operations. This allows you to check
that you are using the correct tape.
/UFO
Directs BRO to create UFOs (if they do not already exist)
on a
mounted output volume, then copy into it the files from the same
UFO on the input volume.
If you do not specify /UFO, BRU does
not copy the files.
/UFO is used only with the /NOINITIALIZE
qualifier.

7-21

April 1983

BACKUP AND RESTORE UTILITY (BRU)
/VERIFY

Copies data from the input volume, performs a
between the input volume and the output
transfer, and reports any differences.

compare operation
volume after the

/WINDOWS:number

Specifies the default number of mapping pointers to be allocated
for file windows when initializing an output disk.
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 for the input disk.
Choosing a large number of mapping pointers may speed up file
access.
However, a large file window also 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 the IAS/RSX-11 I/O Operations Reference Manual for
information.

7.5

STAND-ALONE BRO

You can also run BRU stand-alone. On RSX-llM, the stand-alone system
is called BRU64K.
On RSX-llM-PLUS,
it is BRUSYS.
The difference
between the BRU task contained in these stand-alone systems and the
on-line BRU described in the preceding sections is that stand-alone
BRU does not support a restore operation to a mounted volume.
Therefore, BRU will always initialize the output disk volume.
There
is no /INITIALIZE qualifier and the BRU task does not ask if you want
to initialize the output volume.
Other qualifiers that cannot be used in the stand-alone BRU systems
are /NEW_VERSION, /NOINITIALIZE, /NOSUPERSEDE, /SUPERSEDE, and /UFD.
Unlike other stand-alone systems, the BRU systems contain other tasks
besides the BRU task.
You invoke these other tasks before invoking
the BRU task.
(One task, CNF, is first invoked automatically when you
boot the stand-alone BRU system.)

~sx . . . 1·tf1~ ~~µ.64~·. co·ntatris two· other· ¥<is~]; .·~~$i.ia~.~:\ .' the
~i~i~~·.·······h*····.····•··~·.~.J;?. . . . . . . . .·. etP9•····~.N:~•· B.AO··••.·•.J•.~.··•·.·.·. . t:~•.~i ~~<.i ~~#~.~·····.· . .i:.09~··t.pr:·•····.··(J~iJ •.~ t:Y: . . . r~~~9r
4% 99,J?.t.e:r; ~}<•al'lcl .CN:Jj' is ···t:f\e,·.·.·· St(lna:,1ope,·c<;>P.f:.·~9u:r;(l;t:tot1 . .••.am;t oi•!;,k
P·1J()9~~m· . •· . • Jd~~er ~peg
t: h~··~.·•.•.·• ~.~ct:J o.Bt~ . ·.· · .• l'P\.l ;.~PV'Q~e,·•····ll:·RP·•.(lnd
~9~ ~p~ go····
ct~ c
i!:l•.·.··.··~11v. <>~E:!c'.l .• .• ?~~()rp,t:iq~.:J.:J..¥ ¥1¥\e,l'l . . ypµ
Orr

(.J~µ.qi:in·······

·J5y··.·r~Jsqill.Y:B~~pgij.t ~~1:h :t~e R(J.~

7-22

BACKUP AND RESTORE UTILITY (BRO)
After you boot the stand-alone BRU system,
the CNF task
automatically.
It lists the switches available for your use apd
prompts you for the devices you will be using.
It is recommended
you first specify /DEV to find out the status of the devices on
system. For example:
Enter first device:

runs
then
that
your

/DEV

Device

CSR

Vector

CSR Status

DB
DK
DL
DM
DP
DR
DU
MF FOR=O
MM FOR=O
MS
MT

176700
177404
174400
177440
176714
176300
172150
175400
172440
172522
172522

254
220
160
210
300
150
154
260
224
330
320

Present
Present
Not Present
Present
Present
Present
Not Present
Not Present
Present
Not Present
Not Present

Enter first device:
You can also use CNF and its switches to set the CSR and vector
addresses of devices present on your system or to change the default
formatter number (FOR=n) for some of the magnetic tape devices.
For
example:
Enter first device: DM2:/CSR=l77450/VEC=274

Enter second device: DL:

The CNF switches are:
/CSR=nnnnnn
Changes the default CSR for the device.
/DEV
Lists the default CSR and vector addresses for all of the
devices.
It is recommended that you use this switch first
to find out what devices are present on your system.
/FOR=n
Changes the default formatter number for some of the
magnetic tape devices.
The switch is valid for only the
MF:- and MM:-type devices. The initial default for n is O.
/VEC=nnn
Changes the default vector for the device.

7.5.1

Locating and Booting Stand-Alone BRO

Qtf R$X._;llM, •.··the BRt)64.«/ii~¥Si~~n\ '.<>t>. .the . . .·•af~~~~·~\l~J<?i?. < ..~J/tp .· J:'E!ql.liJsS 64K.
o/:h~g~ . ·. . . o~ ..... 'rt\e1tl<>ty · . · to it:µ~ithe ~~t;ee·.·. ta$J<~ l~R.Ui B~J)i CN?) •..· ·. ·.· . . The·· BR_U6fI<
sys.tE!m •.image .· (BRU64K.$¥f>J•· and.· symbol··. table · (BRlJ64K··~S'l'BJ· are.•·· loca,ted in
q~p[lrSll·. . 09' ..tl',)~<<~9.~1,p~t.1l<:1<1·i~~·.·. . YP.lµmes~.

7-23

April 1983

BACKUP AND RESTORE UTILITY (BRU)

- ·~$~M~S
.~. •. o.i;.~~~P
.:..;.·· Rf:ttJ,TIL

I
On both RSX-llM and RSX-llM-PLUS, you can
BRO system in one of two ways:
1.

Software boot stand-alone BRO by
BOOT command as follows:

bootstrap

the

using

privileged

the

stand-alone
MCR

For RSX-llM mapped systems
>INS $BOO
>BOO [l,5l]BRU64K
For RSX-llM-PLUS
>INS $BOO
>BOO [6,54]BRUSYS

Hardware boot stand-alone BRO
following
bootstrap procedure for your processor.

the

hardware

To create a hardware-bootable stand-alone BRO tape from the
distribution disk,
use the Virtual Monitor Console Routine
(VMR) to save the system image to tape as follows:
For RSX-llM

>SET /UIC=[l,54]
RUN [l,54]VMR
ENTER FILENAME: BRU64K
VMR>SAVE MT:BRU64K
VMR> (CTRL/Z)
For RSX-llM-PLUS

>SET /UIC=[6,54]
RUN VMRM41
ENTER FILENAME: BRUSYS
VMR>SAVE MT:BRUSYS
VMR> (CTRL/Z)
This tape contains a hardware-bootable
image
of
the
stand-alone BRO system.
(See the RSX-llM/M-PLUS System
Management Guide for information on VMR.)

7.6

ON-LINE BRU BAD BLOCK PROCESSING

After you have formatted a disk with the Disk Volume Formatter Utility
(FMT;
see Chapter 5)
and marked any bad blocks on it with the Bad
Block Locator Utility (BAD;
see Chapter 6), you can initialize it
with BRO.
If you specify the /BAD qualifier with the /INITIALIZE qualifier, BRO
uses the bad block information from running BAD on the disk to create
the file BADBLK.SYS.
This file has allocated to it all of the bad
blocks on the disk so that other files will not try to use them.

7-24

April 1983

BACKUP AND RESTORE UTILITY (BRO)
The /BAD qualifier has three options: AUTOMATIC, which is the default
option, OVERRIDE, and MANUAL. The following sections describe how to
use these options.

7.6.1

Using the AUTOMATIC Option

The AUTOMATIC option specifies that BRO use the existing bad block
information on the disk to create the file BADBLK.SYS. For last-track
devices, BRO uses the manufacturer-written bad block information and
the software bad sector file.
For nonlast-track devices, BRO uses the
bad block descriptor block.

7.6.2

Using the OVERRIDE Option

The OVERRIDE option applies only to last-track devices.
disk appear to be a nonlast-track device.

It makes

the

When you use OVERRIDE with BRO, ensure that the disk you are
processing has previously been processed by the BAD utility with the
BAD /OVR switch specified. Using the BAD /OVR switch makes last-track
devices look like nonlast-track devices by using the last good block
before the last track as the bad block descriptor block.
/OVR
processing includes that last track as bad data when it creates the
bad block descriptor block.
OVERRIDE processing for BRO assumes that the bad block
block written by BAD exists on the disk being processed.

7.6.3

descriptor

Using the MANUAL Option

The MANUAL option accepts the addresses of bad blocks you enter
interactively at your terminal.
It also specifies that BRO use either
the
manufacturer-written
bad
block
information
and
the
software-detected bad sector file (for last-track devices) or the bad
block (for nonlast-track devices)
descriptor
block
to
create
BADBLK.SYS.
If there is no software-written bad block information, a
message will be displayed informing you that BAD has not processed the
disk.
When you specify /BAD:MANUAL, BRO issues 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[.]]
BRO 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 number sign
(#).
If you do not specify count, it defaults to 1.
If you enter a bad block that is already in the bad
generates an error message.

block

file,

BRO

To get a list of the LBNs you have entered so far, type one slash (/).
To co~y the LBNs into BADBLK.SYS, type two slashes (//).
When you have finished entering bad blocks, press the
return to BRO command level.

7-25

RETURN

key

BACKUP AND RESTORE UTILITY (BRU)
7.7

USING BRU TO COPY DISKS CONTAINING SYSTEM IMAGES

When you copy a bootable system disk to a disk of the same controller
type, BRU automatically produces a bootable output disk for you.
If, however, you are copying an unsaved (virgin) system or copying a
saved system to a smaller disk or to a disk of a different controller
type, you can use the procedures described in the following sections
to ensure that BRU produces a bootable output disk.

7.7.1

Copying an Unsaved (Virgin) System

In an unsaved system, installed tasks are pointed to by the physical
LBN of the task image on the disk. When you copy an unsaved system
with BRU, BRU assigns new LBNs for the task images on the output disk.
Therefore, if you want to be able to software boot the copied system,
you must first use VMR to remove and reinstall any tasks.
(VMR, the
Virtual Monitor Console Routine, is described in the RSX-llM/M-PLUS
System Management Guide.)

7.7.2

Copying a Saved System

In a saved system, installed tasks are pointed to by the file-ID of
the task image on the disk. To copy a saved system to a smaller disk
or to a disk of a different controller type, use the following
procedures.

7.7.2.1 Copying to a Smaller Disk - If you want to copy a disk with a
saved system to a smaller disk, the most common method is to first use
the /MAXIMUM and /HEADERS qualifiers (described in Section 7.4)
to
decrease the size of the index file.
BRU is then unable to preserve
the file-IDs of the files, so you must use VMR to remove and reinstall
any tasks in the copied system image (the image on the output disk).

7.7.2.2 Copying to a Different Controller Type - If you have used BRU
to copy a hardware-bootable disk to a disk of a different controller
type and you want the output disk to also be hardware-bootable, you
must use the MCR BOOT command to boot the saved system on the output
disk. Then you use the MCR SAVE /WB command to write the correct boot
block on the output disk.

MCR SAV /WB

7.8

BRU FILE TREATMENT

The following sections describe how BRU
headers, file synonyms, and lost files.

7-26

treats

file

dates,

file

April 1983

BACKUP AND RESTORE UTILITY (BRO)
7.8.1

Creation and Revision Dates of Files

BRU always preserves the creation and rev1s1on dates of files that it
transfers. However, since BRU creates UFOs during a restore operation
to a disk being initialized, and also when the /UFO qualifier is
specified, the creation date of the UFO is the date on which BRU
created it.

7.8.2

File Headers

BRU preserves all characteristics of a file, if possible.
three exceptions:

There

are

•

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 correctly reflect the file's size.

7.8.3

File Synonyms

File synonyms are files that have different names but share the same
file-ID and data. They can be created with the PIP utility but also
occur when a file-ID from a deleted file is reused in a UFO that BRU
has not yet copied.
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.

7.8.4

Lost Files

A file that is not contained in any UFD is known as a lost file.
BRO
does not find lost files.
To find lost files, use the File Structure
Verification Utility (VFY) with its /LOst switch before using BRU to
back up the disk (VFY is described in Chapter 9).

7.9

EXAMPLES

This section gives examples of various BRU operations and command
lines.
Note that the qualifiers used in the command lines have been
truncated to three characters. All of the BRO qualifiers are unique
to three characters.
Examples 1 through 6 and examples 11 and 12 also show
messages that BRU returns during some operations.
examples do not include these messages.

informational
The remaining

The following list is a summary of the operations
shown in the examples:

command

Disk-to-tape backup
restore operations.

(with

7-27

verification)

and
and

lines

tape-to-disk

April 1983

BACKUP AND RESTORE UTILITY (BRO)

I
I

Disk-to-disk backup operation.

Disk-to-disk backup operation including changing the maximum
number of files and initial header allocation for the output
disk.

Disk-to-disk multivolume backup operation.

Disk-to-disk multivolume restore operation.

Disk-to-disk multivolume backup (with appending) and disk
disk restore operation.

Disk-to-tape incremental backup operation (by date) with tape
verification.

Disk-to-tape
selective
specification).

(by

file

Mounted disk-to-tape backup and tape-to-mounted disk
operations.

restore

10.

Disk-to-tape backup (with appending) and tape-to-mounted disk
restore operations.

11.

Exclusion of certain files during a backup operation.

12.

Manually entering bad blocks and displaying them.

13.

Continuation command lines on RSX-llM and RSX-llM-PLOS.

14.

Continuation command lines on RSX-llM-PLOS only.

backup

operation

Example 1 shows how to use BRO to back up an entire disk volume onto
two 1600 bpi magnetic tapes and then how to restore the disk. For the
backup operation, BRO verifies the output volumes as part of the
operation.
(Verifying
volumes
is specified with the /VERIFY
qualifier.) If files do not verify, BRO returns an error message.
To back up DM2: onto the magnetic tapes on MMO:
the following command line:

and

MMl:,

use

BRO>/DEN:l600/VER DM2: MMO:,MMl:(Bli)
BRO - STARTING TAPE 1 ON MMO:
BRO - END OF TAPE 1 ON MMO:
BRO - STARTING VERIFY PASS TAPE 1 ON MMO:
BRU - END OF TAPE 1 ON MMO:
BRU - STARTING TAPE 2 ON MMl:
BRU - END OF TAPE 2 ON MMl:
BRO - STARTING VERIFY PASS TAPE 2 ON MMl:
BRO - END OF TAPE 2 ON MMl:
BRO - COMPLETED
BRO) (CTRL/z)

7-28

April 1983

BACKUP AND RESTORE UTILITY (BRO)
To restore the entire disk and rewind the first input tape, use
the following command line
(the /INI qualifier specifies that
DM2: will be initialized before the restore operation begins):
BRU>/REW/DEN:l600/INI MM:,MMl: DM2:fil!)
BRU - STARTING TAPE 1 ON MMO:
BRU -- *WARNING* -- THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM
BRU - END OF TAPE 1 ON MMO:
BRU - STARTING TAPE 2 ON MMl:
BRU - END OF TAPE 2 ON MMl:
BRU - COMPLETED
BRU> (CTRL/Z)

>
Example 2 shows how to do a disk-to-disk backup operation for an
entire disk. The characteristics of the output disk default to those
of the input disk.
This operation (and every other BRU operation) can
be done in two ways.
>BRU/INI DM: DMl:~
BRO - COMPLETED
or
>BRO~

BRO> ffi)
FROM: DM: ffi)
TO:
DMl: ffi)
INITIALIZE OUTPUT DISK [Y/N] :Y~
BRO - COMPLETED
BR u>(CTRL/Z)
These two command lines tell BRO to initialize the output disk
(DMl:) and then back up all of the files on the input disk (OMO:)
onto it.
Example 3 shows another disk-to-disk backup operation. This time, the
maximum number of files and initial file header allocation for the
output disk are changed. This information is contained in the index
file, which can be placed at different locations on the disk.
BRU>/INI/MAX:10000/HEA:5000/POS:BEG OM: DMl:ffi)
BRO - COMPLETED
This command initializes the output disk
(DMl:)
and tells BRO
that the maximum number of files allowed on the disk will be
10000(10) and the initial file header allocation will be 5000(10)
headers.
The index file, which contains this information, will
be placed at the beginning of the disk. When the output disk has
been initialized, all of the files on the input disk (OM:) will
be copied onto it.

7-29

BACKUP AND RESTORE UTILITY (BRO)
Example 4 shows a multiple disk-to-disk backup operation.
You must
use the SAVE option with the /IMAGE qualifier when doing a multiple
disk-to-disk backup operation.
BRU>/INI/IMA:SAV/VER/MOU DL: DY: (8D)
BRU - MOUNT DISK 1 ON DYO:. PRESS "RETURN" WHEN DONE
BRU - STARTING DISK 1 ON DYO:
BRU - END OF DISK 1 ON DYO:
BRU - STARTING VERIFY PASS DISK 1 ON DYO:
BRU - END OF DISK 1 ON DYO:
BRU - MOUNT DISK 2 ON DYO:

• PRESS "RETURN" WHEN DONE

BRU - STARTING DISK 2 ON DYO:
BRU - END OF DISK 2 ON DYO:
BRU - STARTING VERIFY PASS DISK 2 ON DYO:
BRU - END OF DISK 2 ON DYO:
BRU - MOUNT DISK 3 ON DYO:

• PRESS "RETURN" WHEN DONE

BRU - STARTING DISK 3 ON DYO:
BRU - END OF DISK 3 ON DYO:
BRU - STARTING VERIFY PASS DISK 3 ON DYO:
BRU - END OF DISK 3 ON DYO:
BRU - COMPLETED
BRU> (CTRL/z)
Example 5 shows a multiple disk-to-disk restore operation. You must
specify the RESTORE option on the command line with the /IMAGE
qualifier.
BRU>/INI/IMA:RES/VER DY: DL: (8D)
BRU - MOUNT DISK 1 ON DYO: • PRESS "RETURN" WHEN DONE
BRU - STARTING DISK l ON DYO:
BRU - THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM
BRU - END OF DISK 1 ON DYO:
BRU - MOUNT DISK 2 ON DYO: • PRESS "RETURN" WHEN DONE
BRU - STARTING DISK 2 ON DYO:
BRU - END OF DISK 2 ON DYO:
BRU - MOUNT DISK 3 ON DYO: • PRESS "RETURN" WHEN DONE

7-30

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRU - STARTING DISK 3 ON DYO:
BRU - END OF DISK 3 ON DYO:
BRU - MOUNT DISK 1 ON DYO: • PRESS "RETURN" WHEN DONE
BRO - STARTING VERIFY PASS DISK 1 ON DYO:
BRU - END OF DISK 1 ON DYO:
BRU - MOUNT DISK 2 ON DYO: • PRESS "RETURN" WHEN DONE
BRO - STARTING VERIFY PASS DISK 2 ON DYO:
BRU - END OF DISK 2 ON DYO:
BRU - MOUNT DISK 3 ON DYO: • PRESS "RETURN" WHEN DONE
BRO - STARTING VERIFY PASS DISK 3 ON DYO:
BRO - END OF DISK 3 ON DYO:
BRU - COMPLETED
BRO> (CTRL/z)
Example 6 show how to append backup sets on a multivolume disk, plus
restore the multivolume disk set.
If your multivolume backup disk
contains a backup set that does not occupy the entire disk, you can
append backup sets on the same disk using the /APPEND qualifier.
BRU>/APP/IMA:SAVE/BACKUP:SECOND/INI
FROM:

DB:~

TO:

DK:,DKl:~

BRU - MOUNT DISK 1 on DKO:

• PRESS "RETURN" WHEN DONE.

BRU - STARTING DISK 1 on DKO:
BRU - END OF DISK 1 on DKO:
BRU - MOUNT DISK 2 ON DKl:

• PRESS "RETURN" WHEN DONE.

BRU - STARTING DISK 2 ON DKl:
BRU - END OF DISK 2 ON DKl:
BRU - COMPLETED
BRU> (CTRL/Z)
To restore the appended backup set from the multivolume disk set,
you have to specify the following:
BRU>/IMA:RES/BACKUPSET:SECOND/INI DK:,DKl:

DBO:

BRU - MOUNT DISK 1 ON DKO: • PRESS "RETURN" WHEN DONE.
BRU - STARTING DISK 1 ON DKO:
BRU - END OF DISK 1 ON DKO:
BRU - MOUNT DISK 2 ON DKO: • PRESS "RETURN" WHEN DONE.

7-31

April 1983

BACKUP AND RESTORE UTILITY (BRO)
BRU - STARTING DISK 2 ON DKl:
BRU - END OF DISK 2 ON DKl:
BRU - COMPLETED
BRU> (CTRL/Z)
Examples 7 and 8 show how to do incremental backups with BRU.
Example
7 (following) shows a backup-by-date operation (and tape verification)
and Example 8 shows a backup-by-file-specification operation.
BRU>/REV:AFT: (14-FEB-83 17:00)/VERIBID
FROM: OM: IBID
TO:

MT: IBID

This command line backs up all files on the disk that were
revised after 5:00 P.M.
on February 24, 1981. After all the
files have been copied onto the tape, BRU verifies the tape.
If
files on the tape do not verify, BRU returns an error message.

Example 8 shows a backup-by-file-specification operation:
BRU> DB: [ 7, 10] , [ 301, 3 0 4] * • MAC,* • CMD IBID
TO :
MM : IBID
In this case, BRU backs up all the files in UFO
[7,10]
and all
the .MAC and .CMD files in UFO [301,304] on the input disk to a
magnetic tape.
Example 9 shows how to back up files from a mounted disk and then
ways to restore files to a mounted disk.

two

BRU>/MOU DB:[304,303] ,[7,326] MM:IBIT)
This command line informs BRU that the input disk is mounted as a
Files-11 device.
BRU>/NOI MM:[304,303] DB:IBID
This command line restores the files
in UFO [304,303]
on the
magnetic
tape
to
the mounted disk volume without first
initializing it.
In this case, any file on the tape that is
identical to a file already on the disk is not superseded (the
input file is not copied).
Not superseding files is the default
operation for BRU.
BRU>/NOI/NEW MM: [7,326] DB: IBID
This command line restores the files in UFO
[7,326]
on the
magnetic
tape
to
the mounted disk volume without first
initializing it. The /NEW (/NEW VERSION) qualifier tells BRU to
create a new version of any duplTcate files.
Example 10 shows how to append files from a disk to a tape with a
backup set already on it and then how to restore the set back to a
mounted disk.

7-32

April 1983

BACKUP AND RESTORE UTILITY (BRO)
BRU> /APP /VER/BAC: TODAY fill)
FROM: DB: [ 7, 3 2 6] ffiITl
TO:

MM: ffiITl

This command line appends the files in UFO [7,326] on the input
disk to a magnetic tape.
The name of the backup set being
written on the tape is "TODAY". After the backup operation is
completed, BRU verifies the tape.
BRU>/REW/BAC:TODAY/NOI MM:

DB:(BD)

This command line rewinds the magnetic tape containing the backup
set "TODAY". All of the files in TODAY are then copied back onto
a mounted output disk.
If a file already exists on the disk, BRU
defaults to /NOSUPERSEDE to resolve the conflict.

Example 11 shows how to exclude certain files from being copied during
a backup operation.
BRU>/MOU/EXC OM: [1,6] MMl:(BD)
BRU - STARTING TAPE 1 ON MMl:
BRU - END OF TAPE 1 ON MMl:
BRU - COMPLETED
BRU> (CTRL/Z)
This command line backs up all of the files on the input
except for those in UFD [1,6], onto the magnetic tape.

Example 12 shows how to enter bad blocks manually and how
them.

disk,

display

BRO>/REW/INI/BAD:MAN MMl: DM:(BD)
BRO - STARTING TAPE 1 ON MMl:
BRO>LBN (S) =/(BIT)
053768:022
BRU>LBN(S)=l0500:2
BRO>LBN(S)=l2000
BRO>LBN (S) =/(BIT)
053768:022
010500:002
012000:001
BRU>LBN (S) =//(BIT)
BRO -- *WARNING*

THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM

BRU - END OF TAPE 1 ON MMl:
BRO - COMPLETED
BRO> (CTRL/Z)
This command line first initializes the output disk and then
requests you to enter the locations of any bad blocks before
copying the files
from the magnetic tape.
The first slash (/)

7-33

BACKUP AND RESTORE UTILITY (BRU)
displays the bad blocks in the bad sector file on the last track
of the disk. The second slash displays those blocks and the ones
that have been entered manually. Two slashes (//) returns you to
the BRU command level.
In this example, two locations of bad blocks for the disk were
entered:
there are 2 bad blocks starting at LBN 10500 and 1
block at LBN 12000. You can enter the LBN in either decimal (the
default)
or octal (precede the number with #), but the number of
bad blocks must be in decimal.
When you do not specify the
number of bad blocks, it defaults to 1.

Examples 13 and 14 show BRU continuation command lines on RSX-llM
RSX-llM-PLUS (see Section 7.2.2.2 for more information).

and

RSX-llM and RSX-llM-PLUS
>RUN BRU
BRU>/REWINOBRU> /INVOLUME: BACKUPBRU>/BACKUP SET:25MAY81BRU>/TAPE LABEL:BRU123
FROM:
OMO:
TO:
MMO:
RSX-llM and RSX-llM-PLUS support continuation
invoke BRU and then respond to the BRU> prompt.
can be 256(10) characters long.

lines when you
The command line

>BRU/REWINO-> /INVOLUME: BACKUP->/BACKUP SET:25MAY81->/TAPE_LABEL:BRU123 OMO: MMO:

7.10

MESSAGES

This section lists BRU information and error messages, describes the
meaning of the message, and suggests actions to correct the errors. A
WARNING message indicates an error that may or may not terminate the
BRU operation.
A FATAL message indicates an error that always
terminates the operation.
BRU -- *WARNING* -- ALLOCATION FAILURE [ufd]filename.type;version

Explanation: During a copy to a mounted volume,
enough free space to copy the specified file.

there

was

not

User Action: Create enough free space on the volume by using the
Peripheral Interchange Program (PIP; see Chapter 3) to delete or
truncate some files and then reenter the command line.

7-34

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- ALLOCATION FOR SYSTEM 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:
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 OPTION
Explanation: An option specified with a qualifier is not unique.
For example,
the "B" in /POSITION:B could mean either BEGINNING
or BLOCK.
User Action:
Use a form of the option that is unique.
options are unique to two characters.

All

BRU

BRU -- *FATAL* -- AMBIGUOUS QUALIFIER
Explanation: A qualifier is not unique.
mean either /REVISED or /REWIND.

For example, /RE

User Action:
Use a form of the qualifier that
BRU qualifiers are unique to three characters.
BRU

*WARNING*

unique.

could
All

APPENDING AT DEFAULT BPI ON ddnn:
or

BRU

*WARNING*

APPENDING AT 1600 BPI ON ddnn:

Explanation: The wrong tape density was specified with the
/APPEND qualifier. BRU performs an append operation only at the
density at which the tape was previously written.
The default
bpi
in the first message is either 800 or 6250, depending on the
type of tape drive.
User Action:

None.

BRU continues at the correct density.

BRU -- *FATAL* -- ATTACH FAILED ON ddnn:
Explanation:

BRU could not attach the specified device.

User Action: Check to see if another task has the
attached or if the device has a volume mounted on it.

device

BRU -- *FATAL* -- BACKUP DISK READ ERROR
Explanation: An unrecoverable read error occurred on the output
backup disk,
possibly caused by an undetected bad block, or an
error occurred while BRU was sizing the input or output disk for
a multivolume backup operation.
User Action:
Use the BAD utility to locate all bad blocks.
Then
use BRU with the /BAD:AUTOMATIC qualifier to use the existing bad
block information on the disk to create the file BADBLK.SYS.

7-35

April 1983

BACKUP AND RESTORE UTILITY (BRO)
BRO -- *FATAL* -- BACKUP DISK WRITE ERROR
Explanation: An unrecoverable write error occurred on the output
backup disk during a multivolume backup operation.
The error
could have been caused by an undetected bad block.
User Action:
Use the BAD utility to locate all bad blocks
(see
Chapter 6).
Then use BRO with the /BAD:AUTOMATIC qualifier to
use the existing bad block information on the disk to create the
file BADBLK.SYS.
BRO -- *WARNING* -- BAD BLOCK DATA ERROR
Explanation: A manually entered bad block
syntax was incorrect.

count,

resulted

User Action:
None.
You cannot enter more bad blocks than
file will hold.
You may not want to use the disk anymore.

the

User Action:

location,

Enter the correct information.

BRU -- *WARNING* -- BAD BLOCK FILE FULL
Explanation: The manual addition of bad blocks has
more than 204(10) sets of contiguous bad blocks.

BRU

*WARNING* -- BLOCK EXCEEDS VOLUME SIZE
Explanation:
You have manually entered
larger than the size of the output disk.
User Action:

bad

block

that

Enter the correct block.

BRU -- *WARNING* -- BOOT BLOCK IS BAD
Explanation: BRU cannot write to the output
boot
Therefore, the output disk will not be hardware-bootable.
User Action:

None.

block.

BRU continues 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 Action:

None.

BRU continues the operation.

BRU -- *WARNING* -- BOOT BLOCK READ ERROR
Explanation:
block.

An error occurred while BRU was

User Action:

None.

reading

the

boot

BRU continues the operation.

7-36

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *WARNING* -- BOOT BLOCK VERIFY ERROR ON ddnn:
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 continues the operation.

BRU-- *FATAL* -- CANNOT APPEND ON A MOUNTED DISK
Explanation: A multivolume backup operation to disk is not
possible because you cannot append to a mounted disk.
You can
only use the /APPEND qualifier when doing a multivolume disk
backup operation to an unmounted disk.
User Action: You must use another
backup operations.

disk

proceed

with

your

BRU-- *FATAL* -- CANNOT MIX DIFFERENT TYPES OF DISKS
Explanation: The input disk and the output disk are of different
types for a multivolume disk operation.
User Action:
You must specify the same type of disk for
the
input and/or output disk when you do a multivolume restore or
backup operation.
BRU-- *WARNING* -- CANNOT RESTORE CONTIGUOUSLY [ufd]filename.type;version
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 Peripheral Interchange Program
(PIP; see Chapter 3) to make the file contiguous again.
Use the
PIP switches /DE and /TR to reclaim disk space by deletion or
truncation.
BRU -- *WARNING* -- CLOSE OR WRITE ATTRIBUTES ERROR [ufd]filename.type;version
I/O ERROR CODE number
Explanation: During a copy to a mounted volume, BRU encountered
an error while attempting to close the specified file.
User Action:
If possible, determine the cause of the error from
the I/O code.
(Refer to the IAS/RSX-11 I/O Operations Reference
Manual.) If it is correctable, delete the--Port1on of the file
that BRU has copied, and reenter the command line.
BRU -- COMPLETED
Explanation:

The BRU operation is complete.

User Action:
CTRL/Z.

Enter another BRU

7-37

command

line

exit

with

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- CONFLICTING QUALIFIERS
Explanation: Two or more of the specified qualifiers
are
mutually exclusive:
for example, /SUPERSEDE and /NOSUPERSEDE.
User Action:

Reenter the command line.

BRU -- *WARNING* -- DATA ID RECORD VERIFY ERROR
Explanation: An error
80-byte data-ID record.
User Action:

None.

occurred

while

BRU

was

verifying

BRU continues the operation.

BRU -- *WARNING* -- DATA RECORD VERIFY ERROR [ufd]filename.type;version
FILE ID number
LBN number
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 UFD is printed with a file name, the UFD is the owner UFD
from the file's header, not the UFD in which the file is
contained.
User Action:

None.

BRU continues the operation.

BRU -- *WARNING* -- DATA WAS LOST DUE TO IO ERRORS [ufd]filename.type;version
Explanation: A tape read error resulted
in missed
files are restored, but may contain erroneous data.

data.

The

If a UFD is printed with a file name, the UFD is the owner UFD
from the file's header, not the UFD in which the file is
contained.
User Action:

None.

BRU continues the operation.

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:
The device must be either a disk or a tape, but not
both. This applies to both input and output specifications.
BRU -- *FATAL* -- DEVICE NOT IN SYSTEM
Explanation:
system.

A device was specified that does not exist

User Action:
Reenter the command line,
device specification.

7-38

specifying

the

correct

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- DEVICE NOT SUPPORTED
Explanation: The specified device was not a tape or a
it was a disk that is not supported by BRU.

disk,

User Action: BRU supports only certain disk and magnetic tape
devices. See Table 7-2 for a list of supported devices.
Reenter
the command line, specifying supported devices.
BRU -- *FATAL* -- DIRECTIVE ERROR
Explanation:

An internal error occurred in BRU.

User Action: Reenter the command line.
If the error persists,
submit a Software Performance Report (SPR) that includes a hard
copy of the BRU operations and error messages.
BRU -- *WARNING* -- DIRECTORY VERIFY ERROR
Explanation: A directory record on the input
match a directory record on the output device.
User Action:

None.

device

did

not

BRU continues 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:
volume.

Reenter the command line, using a different

output

BRU --* -- DISK LABEL ERROR
Explanation: An I/O error occurred while BRU was reading or
writing a disk label. A write error is fatal; a read error is
not fatal as long as BRU can continue reading the disk. See the
IAS/RSX-11 I/O Operations Reference Manual for the definition of
the I/O error-code number.
User Action:
If a write error occurred,
line, specifying a different disk.
BRU -- *WARNING* -- DISK OUT OF SEQUENCE.

reenter

the

command

PLEASE MOUNT CORRECT DISK.

Explanation: The wrong disk volume was mounted on the disk drive
during a restore-from-disk operation from a multivolume backup
set.
User Action:

Mount the correct disk on the drive.

7-39

April 1983

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- DISK READ ERROR
Explanation: An unrecoverable read error occurred on the output
disk, possibly caused by an undetected bad block, or an error
occurred while BRU was sizing the input or output disk.

User Action:

Use the BAD utility to locate all bad blocks. Then
use BRU with the /BAD:AUTOMATIC qualifier to use the existing bad
block information on the disk to create the file BADBLK.SYS.
BRU -- *FATAL* -- DISK WRITE ERROR
Explanation: An unrecoverable write error occurred on the output
disk.
The error could have been caused by an undetected bad
block.

User Action: Use the BAD utility to locate all bad blocks (see
Chapter 6).
Then use BRU with the /BAD:AUTOMATIC qualifier to
use the existing bad block information on the disk to create the
file BADBLK.SYS.
BRO -- *FATAL* -- DOUBLY DEFINED QUALIFIER
Explanation: The same qualifier was specified more than once
the command line.

User Action:

Reenter the command line, specifying the

qualifier

once.
BRO -- *WARNING* -- DUPLICATE BLOCKS FOUND

BRO

Explanation:
block file.

A manually entered bad block was already in the bad

User Action:

None.

BRO continues the operation.

-- END OF DISK Number ON ddnn:
Explanation:
disk.

BRO has finished transferring data or

user Action:

None.

verifying

This is an informational message.

BRO -- END OF TAPE number ON ddnn:
Explanation:
tape.

BRO has finished transferring data or

user Action:

None.

This is an informational message.

BRO -- *FATAL* -- END OF VOLUME ENCOUNTERED.

verifying

BACKUP SET NOT FOUND

Explanation: The backup set specified for a restore operation is
not on the tape or disk volume.

User Action:

Mount the correct tape or disk volume or reenter
the command line, specifying the correct backup set name.

7-40

April 1983

BACKUP AND RESTORE UTILITY (BRO)

BRU -- *WARNING* -- EOT MARKER ERROR
Explanation: During a backup operation, an error occurred while
BRU was writing or verifying the end-of-tape label on the output
tape.
After a restore operation, an error occurred while BRU was
positioning the tape at the end of a backup set for a subsequent
operation.
User Action: On a write error, BRO rewinds the current tape and
places it off-line. BRU then requests that a new tape be mounted
and rewrites the data on the new tape.
On a verify error, BRO continues the operation.
On a positioning error, BRO finishes the operation. If you want
to perform another BRU operation on the tape, use the /REWIND
qualifier to position the tape to beginning-of-tape.
BRO -- *WARNING* -- ERROR ACCESSING FILE
I/O ERROR CODE number
FILE ID number
Explanation: An error occurred while BRO was writing data into a
file,
or BRU tried to do a compare read on a file that was
already opened. BRU will continue with the next file.
See the IAS/RSX-11 I/O Operations Reference
definition of the I/O error code number.

Manual

for

the

User Action: After BRO has finished, delete the
enter a command line, specifying the file.

file

and

then

BRU -- *WARNING* -- ERROR ACCESSING UFO.
I/O ERROR CODE number

SKIPPING [ufd]

Explanation: During a copy to a mounted volume, an error
occurred when BRU attempted to access a directory. See the
IAS/RSX-11 I/O Operations Reference Manual for the definition of
the I/0 error-code number.
User Action:
If possible, determine the cause of the error from
the I/O error code.
If correctable, try the copy operation
again.
BRU -- *FATAL*

ERROR LIMIT EXCEEDED

Explanation: BRU has reached the specified number of
errors and terminated execution.

tape

read

User Action: Reenter the command line, using a different tape
drive, or reenter the command line after cleaning the tape drive
heads on the original drive.
BRU -- *FATAL* -- ERROR READING COMMAND FILE
Explanation: An I/O error occurred while
indirect command file.
User Action:

Reenter the command line.

7-41

BRU

was

reading

the

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *WARNING* -- ERROR READING DATA BLOCKS
I/O ERROR CODE number
FILE ID number
LBN number
or
RECOVERED
Explanation: An I/O error occurred while BRU was reading a data
block from the disk. The file-ID of the file that 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 re-reading the disk.
See the IAS/RSX-11 I/O Operations
definition of the I/O error code.
User Action:

None.

Reference

Manual

for

the

BRU continues the operation.

BRU -- *WARNING* -- ERROR READING UFO [ufd]
Explanation: An I/O error occurred while BRU was reading a block
from the specified UFO. Any files contained in this block of the
UFO are not backed up.
User Action: Reenter the command line.
If the error still
occurs, you can find
the lost files by using the VFY utility
(refer to Chapter 9).
BRU -- *WARNING* -- ERROR READING UFO HEADER [ufd]
Explanation: An error occurred while BRU was reading the header
of the specified UFO. Files in this UFO are not backed up.
User Action:
occurs, use

Reenter the command line.
If the error still
the VFY utility to find the lost files (see Chapter

9) •

BRU -- *WARNING* -- EXTENDING INDEX FILE
Explanation: The initial number of file headers was too small.
Either
256(10)
or 16(10) more headers will be allocated,
depending on the number of blocks on the output disk.
User Action:

None.

BRU continues 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.

bad

Reenter the command line, using

block

information

the

/BAD:OVERRIDE

BRU -- *WARNING*
FILE HEADER READ ERROR [ufd]filename.type;version
I/O ERROR CODE number
Explanation: An I/O error occurred while BRU was reading a file
header.
That file is not backed up.
See the IAS/RSX-11 I/O
Operations Reference Manual for the definition of the I/O error
code number.
User Action:

None.

BRU continues the operation.
7-42

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *WARNING* -- FILE HEADER VERIFY ERROR [ufd]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 continues the operation.

BRU -- *WARNING* -- FILE ID AREA VERIFY ERROR
Explanation: The BRO-generated file-ID area of a data record was
different on the input and output devices.
User Action:

None.

BRU continues the operation.

BRU -- *FATAL* -- FILE ID EXCEEDS MAXIMUM NUMBER OF FILES
Explanation: You specified a maximum number of files with the
/MAXIMUM qualifier that was smaller than a file-ID encountered on
the input volume.
User Action:
Reenter the command line, specifying a larger value
with the /MAXIMUM qualifier.
BRO -- *WARNING* -- FILE ID SEQUENCE NUMBER ERROR [ufd]filename.type;version
Explanation:

The two possible sources of this error are:

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 Master File Directory
(MFD) •

Therefore, the file or UFO is not valid and is not copied.
User Action:

None.

BRU continues the operation.

BRU -- *WARNING* -- FILE IDS WILL NOT BE PRESERVED
Explanation: File-IDs cannot be preserved because the index file
bitmap on the output disk is too small. This is because the
value specified with the /MAXIMUM qualifier was too small.
User Action: None.
BRU continues
the
operation
without
preserving file-IDs.
If your input disk had a hardware-bootable
system on it, your output disk will not be hardware-bootable.
If you want the disk to be hardware-bootable, perform the BRU
operation again, specifying a larger value with the /MAXIMUM
qualifier.
BRU -- *WARNING* -- FILE MARKED FOR DELETE [ufd]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 is not copied.
User Action:

None.

BRU continues the operation.

7-43

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *WARNING* -- FILE NOT FOUND [ufd]filename.type;version
Explanation: During a backup operation, BRU cannot find the
header for the specified file or directory in the index file.
The file is not copied.
During the verify or compare pass of a restore operation,
cannot find the specified file on the output device.
User Action:

None.

BRU

BRU continues the operation.

BRU -- *FATAL* -- FILE NOT FOUND
Explanation:
file.

BRU could not find the specified

indirect

command

User Action: Reenter the command line, correctly specifying
indirect command file.

the

BRU -- *WARNING* -- FILE NOT SUPERSEDED [ufd]filename.type;version
Explanation: During a copy to a mounted volume with /NOSUPERSEDE
specified
(or defaulted), the specified file was not restored
because it already existed on the output disk.
User Action:
If you want the file to be restored, enter a
command line, specifying the file and either /SUPERSEDE or
/NEW_VERSION.
BRU

*FATAL*
Explanation:
loaded.

HANDLER NOT RESIDENT
The device driver for the specified device

not

User Action: Load the driver for the specified device or reenter
the command line, specifying the correct device name.
BRU -- *WARNING* -- HEADER ID RECORD VERIFY ERROR
Explanation: The BRO-generated header-ID record on the
device is different from the one on the input device.
User Action:

None.

output

BRU continues the operation.

BRU -- *WARNING* -- HEADER READ ERROR [ufd]filename.type;version
I/0 ERROR CODE number
Explanation: An I/O error occurred while BRU was reading a
header in the index file during a backup operation.

file

If this error occurs during a restore operation, it is fatal.
See the IAS/RSX-11 I/O Operations Reference
definition of the I/o-error code number.
User Action:

None.

7-44

Manual

for

the

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- HOME BLOCK READ ERROR
I/O ERROR CODE number
Explanation: An I/O error occurred while BRU was reading the
home
block on the input device.
See the IAS/RSX-11 I/O
Operations Reference Manual for the definition of the I/O error
code number.
User Action:

Reenter the command line.

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 continues, but it is suggested that
the operation.

different
you

retry

BRU -- *FATAL* -- HOME BLOCK WRITE ERROR
Explanation: An unrecoverable I/O error occurred while
writing the home block on the output device.

BRU

was

User Action: Use the BAD utility to find all the bad
the disk before initializing it.

blocks

BRU _-- *FATAL* -- ILLEGAL USE OF DIRECTORY QUALIFIER
Explanation:

Possible sources for this error are:

The /DIRECTORY qualifier was specified
device.

The /DIRECTORY qualifier was specified with a device
other than a tape or backup disk with the BRU container
file.

The /INITIALIZE qualifier or any of
its
related
qualifiers were specified with the /DIRECTORY qualifier.

User Action: Refer to Section 7.4 for
uses of the /DIRECTORY qualifier.

with

description

output

valid

BRU -- *FATAL* -- INCONSISTENT INITIALIZE QUALIFIERS
Explanation: The /INITIALIZE qualifier or any of its related
qualifiers
were
specified
for the output disk, but the
/NOINITIALIZE qualifier was also used.
User Action:

Reenter the command line.

BRU -- *FATAL* -- INDEX FILE HEADER READ ERROR
I/O ERROR CODE number
Explanation: An I/O error occurred while BRU was reading the
header of the index file on the input disk. See the IAS/RSX-11
I/O Operations Reference Manual for the definition of the I/O
error code number.
User Action:

Reenter the command line.

7-45

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- INDEX FILE WRITE ERROR
Explanation: An I/O error occurred while
index file on the output disk.

BRU

was

writing

the

User Action: Use the BAD utility (see Chapter 6) to identify the
bad blocks on the output disk, then reenter the command line.
BRO -- *FATAL* -- INDEXF.SYS IS FULL
Explanation:

The index file cannot map any more file headers.

User Action: Reenter the command line, specifying a larger value
with the /MAXIMUM qualifier.
BRO

*FATAL* -- INITIALIZE QUALIFIERS INVALID WHEN OUTPUT IS TAPE
Explanation: The /INITIALIZE qualifier and the other qualifiers
that you can specify with it may be used only when the output
device is a disk.
User Action:

Reenter the command line.

BRU -- *FATAL* -- INPUT DEVICE EQUALS OUTPUT DEVICE
Explanation:

The input and output devices must be different.

User Action:
Reenter the command
devices for input and output.

line,

specifying

different

BRU -- *FATAL* -- INPUT LINE TOO LONG
Explanation:
characters.

The maximum length of a

command

line

256(10)

User Action: Truncate qualifiers and options to shorten the
line.
Make sure the truncated forms are unique.
All BRU
qualifiers are unique to three characters;
a~l
options are
unique to two characters.
BRU -- *WARNING* -- INPUT VOLUME STRUCTURE LEVEL DIFFERS FROM OUTPUT VOLUME
Explanation: You have initialized the output volume,
specifying
with the /MAXIMUM qualifier that the number of files allowed on
the volume be greater than 25593. This causes the index file on
the output volume to have more than one file header.
User Action:

None.

BRU -- *FATAL* -- INTERNAL ERROR
Explanation: BRU has detected
should not normally occur.

itself.

This

User Action:
Please submit a Software Performance Report
with a hard copy of the BRU operations and error messages.

(SPR)

7-46

error

within

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *FATAL* -- INVALID DATE OR TIME
Explanation:
In the command line, a date or time
incorrectly or is out of range.
User Action:

was

specified

Specify the correct date or time.

BRU -- *WARNING* -- INVALID DATE OR TIME [ufd]filename.type;version
Explanation: An invalid date or time was encountered in
header during an incremental backup.

file

User Action:
copied.

file

None.

BRU continues the operation.

The

BRU -- *FATAL* -- INVALID DENSITY OR TAPE FORMAT
Explanation: You specified a density that was neither the
default bpi
(800 or 6250) nor 1600 bpi or you attempted to use
both 7-track and 9-track tapes in a multivolume tape set.
User Action:
In the former case, reenter the command line,
specifying the correct density.
In the latter case, only use all
7-track or all 9-track tapes for a multivolume tape set.
BRU -- *FATAL* -- INVALID DISK FORMAT
Explanation: The disk that was mounted for an
operation is not a BRU multivolume backup disk.
User Action:

/IMAGE

restore

Mount the correct disk.

BRU -- *FATAL* -- INVALID FILENAME
Explanation: The name
syntactically correct.
User Action:

the

indirect

command

file

not

Reenter the command line.

BRU -- *WARNING* -- INVALID TAPE FORMAT
Explanation:
operation.

An invalid tape record was read

User Action:

None.

during

restore

The invalid record is not restored.

BRU -- *FATAL* -- INVALID VALUE OR NAME
Explanation: A value or name specified
illegal syntax or is out of range.

for

qualifier

User Action:
Refer to Section 7.4 to determine the legal
for the particular qualifier.

7-47

has

values

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRO -- *FATAL* -- MANUFACTURER BAD SECTOR FILE IS CORRUPT
Explanation: BRO was unable to read the
from a last-track output disk.

bad

User Action: Reenter
the
/BAD:OVERRIDE qualifier.

line,

command

block

information

specifying

the

was

the

BRO -- *FATAL* -- MFD HEADER READ ERROR
Explanation:
An I/O error occurred while
header of the Master File Directory.

BRO

reading

User Action:
Reenter the command line.
If the header still
cannot be read,
the files on the disk are lost and may be
recovered using the VFY utility (see Chapter 9).
BRO -- *WARNING* -- MFD READ ERROR
Explanation: An I/O error occurred while BRO was reading a block
of the MFD. BRO cannot copy the UFOs in that block of the MFD.
User Action:
Reenter the command line.
If the block cannot be
(Refer to
read, use the VFY utility to recover the lost files.
Chapter 9 for information on VFY.)
BRO

-- *FATAL* -- MISSING COLON
a

value

was

not

than

one

level

requests

Explanation: A qualifier option that accepts
followed by a colon.
User Action:
BRO

Reenter the command line.

-- *FATAL* -- MORE THAN 1 LEVEL OF INDIRECTION
Explanation: BRO does
indirect command files.
User Action:

not

support

Reenter the command line.

BRO -- MOUNT DISK ri ON ddnn:.

PRESS "RETURN" WHEN DONE

Explanation: This message is issued each time
disk for an image backup or restore operation.

BRO

User Action: Mount the disk specified on the drive specified and
then press "RETURN".
BRO -- MOUNT TAPE n ON ddnn:
Explanation: There is no tape on the specified drive or the tape
is not at load point.
This message prints every two minutes
until the tape is mounted.
User Action:

Mount the tape specified on the drive specified.

7-48

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRU -- MOUNT ANOTHER DISK
Explanation: BRU is requesting that a new disk be mounted
encountering a fatal disk write error.
User Action:

after

Mount a new disk on the drive.

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 -- *FATAL* -- NAME EXCEEDS MAXIMUM ALLOWED LENGTH
Explanation: A name, such as a backup set name, is longer than
12(10) characters. An exception to this rule is during an /IMAGE
backup operation to a mounted disk. You may specify more than
12(10)
characters if you are adding the name of the backup set
filename to the command line. For additional information, -see
Section 7.4 for a description of the /BACKUP_SET qualifier.
User Action:

Specify a name not greater than 12 characters.

BRO -- *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.
BRO continues the operation.
Refer
Section 7.6 for information on bad block processing by BRU.

BRO -- *WARNING* -- NO FILES FOUND
Explanation: During a backup or restore operation, BRO
find any files to transfer.
Oser Action:

did

not

None.

BRO -- *WARNING* -- NONFATAL QUALIFIER CONFLICTS BEING IGNORED
Explanation: You entered a qualifier that conflicts with the
rest of the command line, but is not fatal if ignored. For
example, you used the /REWIND qualifier on a disk-to-disk
operation.
User Action:

None.

BRO continues the operation.

BRO -- *WARNING* -- NO SUCH UFO EXISTS.

SKIPPING [ufd]

Explanation: During a copy to a mounted volume, BRO encountered
one or more files in the specified UFO on the input volume, but
there is no corresponding UFO on the output volume.
User Action: Reenter the command
qualifier to create the UFO.

7-49

line,

specifying

the

/UFO

April 1983

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *FATAL* -- NUMBER OF HEADERS INCONSISTENT WITH MAXIMUM FILES
Explanation: During an attempt to initialize .an output volume,
BRU found that the maximum number of files specified with the
/MAXIMUM qualifier was inconsistent with the number of headers
initially
allocated
to the index file with the /HEADERS
qualifier.
User Action: See the RSX-llM/M-PLUS MCR Operations Manual
(the
INI command) for the legal ranges of values for the /MAXIMUM and
/HEADERS qualifiers.
BRU -- *WARNING* -- OPEN ERROR
I/O ERROR CODE number
FILE I/D number or [ufd]filename.type;version
Explanation: During a copy operation to a mounted volume, an
error occurred while BRU was attempting to open the specified
file.
See the IAS/RSX-11 I/O Operations Reference Manual for the
definition of the I/O error-code number.
User Action: Determine the cause of the error from the I/O error
code.
If correctable, delete any portion of the file already
copied by BRU, then reenter the command line.
BRU -- *FATAL*

OUTPUT DISK TOO FRAGMENTED TO RESTORE

Explanation: The internal tables in BRU have overflowed due to
the 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 DEVICE 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, reenter the
If you were
command line, specifying only the files you want.
doing an append to a tape that is already full,
reenter the
command line, specifying a new tape.
BRU -- *FATAL* -- OVERRIDE INVALID WITH NON LAST TRACK DEVICE
Explanation: The OVERRIDE option may
output disk is a last-track device.
User Action:

used

Refer to Section 7.4.

BRU -- PLEASE ANSWER YES OR NO
Explanation:

BRU requires a YES or NO response.

User Action:

Enter YES or NO at your terminal.

7-50

only

when

the

BACKUP AND RESTORE UTILITY (BRO)
BRU -- *WARNING* -- PRIVILEGE VIOLATION [ufd]filename.type;version
Explanation: During a backup operation, you attempted to copy
file that you do not have read access to.
User Action:

None.

BRU does not copy the file.

BRU -- *FATAL* -- PRIVILEGE VIOLATION
Explanation: The mount status of one of the
devices
is
inconsistent with the qualifiers specified in the command line.
User Action: See Table 7-1 for the correct combinations of
mounted devices and qualifiers, then reenter the command line.
BRU -- *FATAL* -- RAN OUT OF SPARE FILE IDS
Explanation: The output disk required more file headers than the
input disk, but no free headers were available. The lack of
headers is probably due to one of the following reasons:
1.

The output disk is too fragmented because of bad blocks.

There are no free file headers on the input disk.

User Action:
If you do not need to preserve file-IDs,
the command line, specifying the /NOPRESERVE qualifier.

reenter

If you want to preserve file-IDs, do one of the following:
1.

If the output disk is too fragmented, run BAD
(see
Chapter 6)
on it to display the number of bad blocks.
If it contains a large number of bad blocks, you may
want to use a different disk.

use the PIP /FR switch (see Chapter 3)
to display the
number of free file headers on the input disk.
If there
are fewer than 4 free headers, delete some of the files
and then reenter the command line.
If you still do not
have enough file headers, specify the
/NOPRESERVE
qualifier in the command line.

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 continues the operation.

BRU -- *FATAL* -- REQUIRED INPUT DEVICE MISSING
Explanation: The input device was not specified on
line or in response to the prompt.
User Action:

Reenter the command line.

7-51

the

command

BACKUP AND RESTORE UTILITY (BRO)
BRO -- *FATAL* -- REQUIRED OUTPUT DEVICE MISSING
Explanation: The output device was not specified on the
line or in response to the prompt.
User Action:

command

Reenter the command line.

BRO -- REWIND ERROR ON ddnn:
Explanation: 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 a verify operation. The error is not fatal
if BRO is rewinding a tape it is finished with.
User Action:
If the error is fatal, reenter the
If the error is not fatal, no action is required.

command

line.

BRO -- *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 in
Files-11 format.
User Action:

Check to see that you have the correct disk •

•
BRO -- STARTING TAPE n ON ddnn:
Explanation: This message tells you which tape is
to or from which drive.
User Action:

None.

being

copied

This is an informational message.

BRO -- STARTING VERIFY PASS
Explanation: This message tells you that the verify
disk-to-disk operation is beginning.
User Action:

None.

pass

This is an informational message.

BRO -- STARTING VERIFY PASS TAPE n ON ddnn:
Explanation: This message tells you which tape is being verified
during a backup or restore operation.
User Action:

None.

This is an informational message.

BRU -- *FATAL* -- SYNTAX ERROR
Explanation:

The command line is invalid.

User Action:

Reenter the command line.

7-52

April 1983

BACKUP AND RESTORE UTILITY (BRU)
BRU -- TAPE LABEL ERROR ON ddnn:
I/0 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. See the
IAS/RSX-11
I/O Operations Reference Manual for the definition of
the I/O error-code number.
User Action:
If a write error occurred,
line, specifying a different tape.

reenter

the

command

BRU -- *WARNING* -- TAPE LABEL VERIFY ERROR
Explanation: BRU detected an error in the tape label
input or output tape volume during a verify operation.
User Action:

None.

the

BRU continues the operation.

BRU -- *WARNING* -- TAPE NOT AT BOT.

NO REWIND OR APPEND SPECIFIED

Explanation: For a backup operation to tape, BRU will not
process a tape that is not at BOT unless the /APPEND qualifier
was specified.
User Action:
If you want to start writing at
the tape, use the /REWIND qualifier.

the

beginning

You can append to a tape only at the end of the last backup set
on it.
If the tape is already positioned there, specify /APPEND
in the command line.
If it is not, specify both /REWIND and
/APPEND in the command line.
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.

BRU -- *WARNING* -- TAPE POSITIONING ERROR.

BACKSPACE FAILED

Explanation: During a backup operation, the tape
positioned properly for a future append operation.
User Action:
operation.

Rewind

the

tape

before

BRU -- *FATAL* -- TAPE POSITIONING ERROR.
I/O ERROR CODE number

attempting

was
the

not
append

NO EOV ENCOUNTERED

Explanation: The
tape
spacing
operation
to
find
the
end-of-volume for an append operation failed.
See the IAS/RSX-11
I/O Operations Reference Manual for the definition of the I/O
error code number.
User Action:

Reenter the command line.

7-53

BACKUP AND RESTORE UTILITY (BRU)
BRU -- *WARNING* -- TAPE READ ERROR
Explanation:

An I/O error occurred while BRU was reading a tape.

User Action:

None.

BRU continues the operation.

BRU -- *FATAL* -- TAPE TO TAPE NOT SUPPORTED
Explanation:

BRU does 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 BRU was writing to
tape.
BRU rewinds the tape and then requests that another tape
be mounted. See the IAS/RSX-11 I/O Operations Reference Manual
for the definition of the I/0 error code number.
User Action:
If the error is related to
terminate BRU and start over on another drive.

the

tape

drive,

BRU -- THIS DISK WILL NOT CONTAIN A HARDWARE BOOTABLE SYSTEM
Explanation: The output
This can be caused by:

disk

will

not

hardware-bootable.

The input disk not being bootable

The system image not being copied

Copying to a disk of different size or type
NOTE
This message is not issued when
restoring to a mounted volume.

User Action:

BRU

None.

BRU -- *FATAL* -- TOO MANY DEVICES
Explanation: For a conventional backup a disk may be specified
only once as an input or output device.
However, up to eight
tape drives or eight disks in an image backup may constitute the
input or output.
User Action:
Reenter the command line, specifying only one
or no more than eight tape drives.

disk

BRU -- *FATAL* -- TOO MANY FILE SPECIFICATIONS
Explanation: More than 16(10) file specifications were specified
on the command line.
User Action:
Reenter the command line. You can use wildcards to
reduce the number of file specifications on the command line.

7-54

BACKUP AND RESTORE UTILITY (BRO)
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.
Please submit a
Software Performance Report
(SPR)
with a hard copy of the BRU
operations and error messages.
BRU -- *WARNING* -- UFO RECORD VERIFY ERROR
Explanation: There is a
devices on a UFO record.
User Action:

None.

difference

between

input

and

output

BRU continues the operation.

BRU -- *FATAL* -- UNKNOWN OPTION
Explanation:
BRU.

An option was specified that was not recognized

User Action: Reenter the command line.
of legal options.

See Table 7-3 for a list

BRU -- *FATAL* -- UNKNOWN QUALIFIER
Explanation:
by BRU.

A qualifier was specified that was

not

recognized

User Action: Reenter the command line. See Table 7-3 for a list
of legal command qualifiers and their options.
BRU -- *FATAL* -- UNSUPPORTED STRUCTURE LEVEL
Explanation: The file structure level on the input disk
supported by BRU.

not

User Action: Ensure that you have the correct disk.
(See the
descriptions of the /HEADERS and /MAXIMUM qualifiers in Section
7.4 for information on structure levels.)
BRU -- *WARNING* -- VBN NOT IN FILE
Explanation: A file-ID was encountered that is larger than the
maximum file-ID in the index file. The file is ignored. This
error message occurs if a UFD entry was corrupted on the input
disk.
User Action:

None.

BRU continues the operation.

BRU -- *FATAL* -- VERIFY LOST
Explanation: During the verify pass of a disk-to-tape backup
operation, BRU has lost synchronization between the input and the
output. This is usually caused by the tape position being lost
or by backing up from a disk that is mounted and then changed
during the backup operation.
User Action:

Reenter the command line.

7-55

BACKUP AND RESTORE UTILITY (BRO)
BRU -- -FATAL* -- VOLUME NOT A BACKUP DISK
Explanation: The disk mounted for an append or restore operation
does not contain a backup set file generated by BRU.
User Action: Check to see that you have
reenter the command line.

the

correct

disk

and

BRU -- *FATAL* -- VOLUME NOT A BACKUP TAPE
Explanation:
The tape mounted for an append or restore operation
was not generated by BRU, or the tape is not positioned correctly
for an append operation.
User Action: Check to see that you have the correct tape, or
reenter the command line, specifying the /REWIND qualifier to
position the tape.
BRU -- *FATAL* -- VOLUME NOT READY
Explanation:

The device is not on-line.

User Action:
line.

Put the device

on-line

and

reenter

the

command

BRU -- *FATAL* -- VOLUME WRITE LOCKED
Explanation:

The output device is not write-enabled.

User Action:
If the output device is a tape, insert a write ring
to make it write-enabled.
If it is a disk, press the Write
Enable switch on the disk drive.

BRU -- *FATAL* -- WRONG BACKUP SET
Explanation: During a restore operation from a multireel tape
set or a multivolume disk backup set, BRU found that one of the
tapes or disks does not contain the correct backup set.
User Action:
tape.

Reenter the command line,

specifying

the

correct

BRU -- *FATAL* -- WRONG INPUT VOLUME LABEL
Explanation:
The input volume label specified with the /INVOLUME
qualifier does not match the volume label of the input device.
User Action:
Reenter the command line,
input volume label.

7-56

specifying

the

correct

April 1983

CHAPTER 8
DISK SAVE AND COMPRESS (DSC)

The Disk Save and Compress (DSC} utility copies a Files-11 structured
disk 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, therefore, reduces the number
of retrieval pointers and file headers required for the same files on
the new 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 reduces 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 in compressed form on another disk. ~e
operation can use one command
(for a disk-to-disk cycle}
or two
commands (for a disk-to-tape and tape-to-disk cycle}. You can use DSC
on-line or in either of its stand-alone versions
(DSCSYS.SYS or
DSC64K.SYS}.
After a DSC copy operation, individual files are written in available
contiguous blocks and the blocks available for new files are located
in a contiguous area at the end of the new volume.
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.
DSC reads and writes data to its two buffers when it performs copy or
compare operations.
(See Figures 8-1 and 8-2.) Each buffer normally
is large enough to contain four disk blocks and a 16-byte buffer
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. The maximum blocking
factor is 4 for both stand-alone versions.
In a disk-to-disk copy operation, DSC:
1.

Copies data from disk to a DSC buffer

Copies data from the DSC buffer to another disk

8-1

DISK SAVE AND COMPRESS (DSC)
In a disk-to-tape and tape-to-disk operation, DSC:
1.

Copies data from disk to a DSC buffer

Writes data from the DSC buffer to tape

Copies data from tape to a DSC buff er

Writes data from the DSC buffer to another disk

---.

•

BLOCKS OF DATA

disk

•

DSC
BUFFER 1

-----

data

You can execute operations 3 and 4 to restore
time.

I
-

DSC
BUFFER 2

•

DISK INPUT DEVICE

DISK OUTPUT DEVICE

0 DSC reads eight (default) or more blocks of data from the disk input device to two
buffers.

8 In disk-to-tape copy operations, DSC writes data from the buffers to magnetic tape.
0 In disk-to-disk copy operations, DSC writes data from the buffers to the disk output
device.

DSC repeats steps 0 and 8 or 8 until it copies the entire input device.
ZK-182-81

Figure 8-1

Data Transfer for DSC Copy Operation

8-2

any

DISK SAVE AND COMPRESS (DSC)

•

BLOCKS OF DATA

DSC
BUFFER 1

DSC

BUFFER 2

----

l
i

•

DISK INPUT DEVICE

DISK OUTPUT DEVICE

0 DSC reads four blocks (default) of data from the disk input device to a buffer.
f) DSC reads four blocks (default) of data from the disk output device to the second buffer.

C) DSC compar~s the contents of the two buffers.
C) DSC prints the differences on your terminal.
DSC repeats steps 0 through G until it has compared the entire device.
ZK-183-81

Figure 8-2

Data Transfer for DSC Compare Operation

After a disk-to-disk copy operation, you can access the data on the
new disk directly.
However, after a disk-to-tape operation you cannot
access the data on tape directly because it is stored in a
format
recognizable only to DSC.
To access this data, you must perform a
second DSC copy operation and transfer the data to another disk
volume.
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),
such a saved system can function normally when it is
rebooted.
You can also use DSC to recover from hardware malfunctions that have
made a portion of a disk volume unreadable.
If the contents of a
block allocated to a data file cause a read error, you can use DSC to
copy the garbled contents to the output device and to generate a
warning message labeling the garbled data block.
You can then access
the block and correct its contents.

8-3

DISK SAVE AND COMPRESS (DSC)
8.1

DSC-SUPPORTED VOLUMES

You can use DSC with a
devices.
The status
operating system.

variety of mass storage or magnetic tape
DSC requires for the devices varies with the

Table 8-1 lists the devices that can be used with DSC operations.
Table 8-1
DSC-Supported Devices
Type

Abbreviation

Class

RP04/RP05/RP06 disk pack

Block structured

TU58 cassette (DECtape II)

Block structured

RFll/RSll fixed head disk

Block structured

RKOS/RKOSF cartridge disk

Block structured

RL01/RL02 cartridge disk

Block structured

RK06/RK07 cartridge
disk

Block structured

RP02/RP03 disk pack

Block structured

RM02/RM03/RM05/RM80/RP07
disk pack

Block structured

DS 1

RH70/RS03/RS04 and RH70/RS03/
fixed-head disk

Block structured

TU56 DECtape

Block structured

RA80 Fixed media disk
RXOl floppy disk

Block structured
Block structured

RX02 floppy disk

Block Structured

TE16/TU16/TU45/TU77
9-track magnetic tape

Tape

TSll magnetic tape

Tape

TUlO/TElO 7- or 9-track
magnetic tape and TS03
9-track magnetic tape

Tape

TU78 magnetic tape

Tape

1. Indicates that the device cannot be used
DSC.

with

either

stand-alone

2. Indicates that the device cannot be used with DSCSYS.SYS.

8-4

DISK SAVE AND COMPRESS (DSC)
8.2

INITIATING AND TERMINATING ON-LINE DSC

You can initiate the on-line DSC in any of the ways explained
Chapter 1 of this manual.
To terminate on-line DSC, type CTRL/Z.

8.3

INITIATING AND TERMINATING STAND-ALONE DSC

You can bootstrap stand-alone DSC (DSCSYS.SYS or DSC64K.SYS) from disk
or from tapes supplied with the operating system.
You can bootstrap stand-alone DSC in one of two ways:
1.

Software boot stand-alone DSC by entering the privileged
BOOT command as follows:

MCR

For Unmapped
>INS $BOO
>BOO[T] [l,SO]DSCSYS.SYS
For Mapped
>INS $BOO
>BOO [T] [l, 5l]DSC64K. SYS
2.

Hardware boot stand-alone DSC
beginning bootstrap address.

the

appropriate

To create a hardware-bootable stand-alone DSC tape from the
distribution disk, use the Virtual Monitor Console Routine
(VMR) to save the system image to tape.
When stand-alone DSC is booted, it displays the message:
RSX-llS V3.0 BL32 DISK SAVE AND COMPRESS UTILITY V4.0
DSC>
The prompt indicates that DSC is ready to accept commands.
stand-alone DSC by halting the processor.
When DSC64K.SYS is booted,
Si zing Program
(CNF)
is
prompt:

Terminate

the Stand-alone Configuration and Disk
active.
Type the following for the DSC

>RUN DSC
Section 8.8 describes stand-alone DSC64K.SYS.

8.4

DSC COMMAND FORMAT

Commands for DSC use the format:
DSC>outdev [s]: [filelabel] [/switch] =indev [s]: [filelabel] [/switch]
The parameters of this command format are:
Output Parameters
outdev:
The physical volume(s) to which data is copied. The format for
outdev:
is dd[nn]:
where dd are the ASCII characters for the

8-5

DISK SAVE AND COMPRESS (DSC)
volume abbreviation, [nn] is an optional 1- or 2-digit octal unit
number for the volume, and the colon (:) is required syntax for a
device specification.
If you omit the unit 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 tape
drives available in round-robin fashion.
Up to eight tape
drives, separated by commas, can be specified as output devices
in an on-line DSC operation. Stand-alone DSC permits only two
tapes to be used as output devices.
DSC ignores multiple disk specifications.
file label
Identifies the output disk's volume-ID, the tape file, or tape
set that 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, and you copy a disk to tape, DSC records
the volume ID of the input disk on the tape. When the copy is
from tape to disk, the output volume ID defaults to the ID
recorded on the tape.
In a disk to disk copy operation, the
output volume ID will default to the ID of the input disk.
switch
One or more of the optional switches described in Section 8.5.
Input Parameters
indev:
The physical volume(s), in the format dd[nn] :, from which data is
copied (see outdev:).
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-created tape set
contains the contents of the disk copied
by DSC.
switch
One or more of the optional switches described in Section 8.5.

8.5

DSC FILE LABELS, SWITCHES, AND OPTIONS

DSC commands can contain file labels and switches.
Some switches also
use options to specify values. Table 8-2 summarizes the DSC switches
and options. Note that all of these switches can be used with both
on-line and stand-alone DSC.
See Table 8-5 for switches available
only for stand-alone DSCSYS.
8-6

DISK SAVE AND COMPRESS (DSC)
Table 8-2
DSC Switches and Options
Switch

Description

Format

Append

/AP

Bad Block

NOAUTO
MAN
/BAD= ~~: NOAUTO

l
!
MAN:OVR

Appends a DSC file to the
first volume of a
tape set that already
contains a DSC file.
The
latter file is currently
the last file of the set.

Allows manual entry of
bad block locations; can
supplement, override, or
ignore the disk's bad
block file.

Block Factor

/BL=n
or
/BL:n

Sets the number of 256-word
blocks DSC can include in
each of its two buffers.

Compare

/CMP

Compares input and output
volumes for differences.

Density

/DENS=l600
/DENS=800: 1600
or
/DENS:l600
/DENS:800:1600
/DENS = 62 50

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.
Note that the DENS=l600
switch is valid with TU16,
TU77, TE16, or TU45 drives.
The DENS=800:1600 switch
is valid with TU16 or TU45
drives when they are not
controlled by the TM03
formatter. The /DENS = 6250
switch is only valid with
TU78 drives.

Rewind

/RW

Rewinds all magnetic tapes
before DSC executes the
current command.

Verify

/VE

Copies data from the input
volume and compares it with
data in the output volume.

8-7

DISK SAVE AND COMPRESS (DSC)
8.5.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 1 to 12 alphanumeric characters.
However, when copying to tape, DSC uses 9 characters to identify the
file it creates which contains the disk's 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 line to identify the
file on tape that will contain the data to be copied from the input
disk, DB 1:.
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 volume label of the output disk.
If you do not specify
an output file label, the default file label is that of the original
input disk, (as recorded in its Home Block).
For example:
DSC>DBl:=MMOl:,MM02:SYSFILE
In this command line, 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 on the first volume, DSC
issues an error message and terminates the operation.
If you enter the command line 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 switch, the tape may or may not be positioned at the beginning
before DSC begins its operation.

8-8

DISK SAVE AND COMPRESS (DSC)
8.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.
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 line, as follows:
outdev: [f ilelabel] /AP=indev: [file label] [/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 ddnn:

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 ddnn:

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 ddnn:

IS NOT THE ONLY REEL IN ITS SET

For example:
DSC>MMOl:,MM:SYSFILE/RW/AP=DXl:
This command line appends the contents of DXl:
to
the
last
DSC-created file already present on the first output volume specified,
MMOl:.
Since the /Rewind switch is specified (see Section 8.5.7), 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.
You can only use the /Append switch with output tape volumes.
Any
other use of the switch causes DSC to generate an error message and
terminate the operation.

8.5.3

/Bad Block Switch

Use the /Bad Block switch (/BAD) with output disk volumes
the way DSC uses bad block information.

control

with

manually

The options for the /BAD switch allow you to:
1.

Supplement the output disk
entered bad block data.

Ignore or override the bad block file on last
track
(manufacturer's
list
of bad blocks)
or non-last-track
devices.

Use only manually entered bad blocks.
8-9

bad

block

file

DISK SAVE AND COMPRESS (DSC)
The bad block descriptor of the disk is never altered by DSC.
If the /BAD switch is not specified, DSC will access the bad block
descriptor area
(the last good block on non-last-track disks or the
entire last track on last-track disks) to obtain the information to
create the bad block file, BADBLK.SYS.
If DSC determines that the
descriptor area is invalid, DSC displays a warning message
(see
Message 59).
The format for the /BAD switch and its options are:
/BAD=MAN
/BAD=NOAUTO
/BAD=MAN:NOAUTO
/BAD=OVR
/BAD=MAN:OVR
MAN
Supplements BADBLK.SYS with manually entered bad block data.
This option may be combined with either NOAUTO or OVR to produce
two more options.
NOAUTO
Ignores the bad block descriptor area on the disk. Note that in
this case, DSC will attempt to write in any block it selects.
This option may be combined with MANUAL to produce the option
MAN:NOAUTO.
MAN:NOAUTO
Enters only manually entered bad block data in the bad block file
BADBLK.SYS.
Thus, DSC bypasses only manually entered bad blocks
when selecting blocks to write in.
OVR
Ignores the bad block descriptor area and accesses the substitute
descriptor area
(the last good block on the next to the last
track on the disk)
to obtain the data for the creation of
BADBLK.SYS.
This option is valid only on last-track devices.
This option may also be combined with MAN to produce the option
MAN:OVR.
MAN:OVR
Allows manual entry of bad block
BADBLK.SYS.

data

the

bad

block

file

When you specify MAN, MAN:NOAUTO, or MAN:OVR with the /Bad switch, DSC
responds with the following prompt:
DSC>LBN(S)=
DSC issues this prompt after it accepts the original command line
before it transfers any data.

but

Enter the locations of bad blocks after the LBN(S)= prompt as follows:
DSC>LBN(S)=n:m.

8-10

DISK SAVE AND COMPRESS (DSC)
n

The logical block number (LBN), in
block in the group.

octal,

the

initial

bad

m
The number, in octal, of consecutive blocks contained
group.
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

{.)

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.
After you enter the first group of bad blocks,
DSC reissues the
LBN(S)= prompt. At this point, you can enter additional bad blocks.
To terminate manual bad block entry, enter a carriage return after the
LBN{S)= prompt.
When you have entered all the bad blocks
process, DSC begins the data transfer.

and

terminated

the

entry

For example:
DSC>DB1:/BAD=MAN:NOAUTO=MM01:,MM02:SYSFILE/RW
DSC>LBN(S)=702:7<TAB>644:2
DSC>LBN(S)=4057,5001:3
DSC>LBN{S)=<RET>
DSC>
DSC restores the output disk, DBl:,
from the tape file SYSFILE
contained on MMOl:
and MM02:, skipping only the blocks you entered
manually.
In the previous example, the following blocks will not be
used:
702
703
704
705
706
707
710

644
645

4057

5001
5002
5003

Compare the previous example with the following example:
DSC>DBl:/BAD=NOAUTO=DBO:
This example transfers data to the lowest LBNs on DBl:
the content of the resident bad block descriptor.

regardless

If you specify /BAD=OVR on a last track device, DSC reads the last
good block written by BAD on the next to the last track of the device.
The information in this substitute descriptor block is used to create
the bad block file.
If MAN:OVR is specified, manually entered blocks
will be added to the bad block file.

8-11

DISK SAVE AND COMPRESS (DSC)
8.5.3.1 Obtaining Bad Block Information - You can
information in two ways:
program

obtain

block

Running the Bad Block Locator
this manual

Running the DIGITAL Field Service stand-alone diagnostic

The BAD utility automatically provides bad
creates a bad block file that DSC can use.

(BAD),

bad

block

described

information

and

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.

DSC

8.5.3.2 Conversion to Logical Block Numbers - All
information must identify bad blocks by LBN.

bad

block

The manufacturer-furnished or diagnostic bad block information usually
identities bad blocks by physical address (sector-track-cylinder).
Before you enter this information manually for DSC, convert the
physical addresses to LBNS.
Use the following formula:
(((cylinder number*tracks/cylinder)+track number)*sectors/track)+sector number

For example, suppose a bad sector of an RP06 (19 tracks per cylinder
and 22 sectors per track) has the following physical address:

Cylinder Number
Track Number =
Sector Number =

Octal

Decimal

536(8)
16(8)
13(8)

350.
(14.)
(11.)

The LBN for the example is calculated as follows:
(((350.*19.)+14.)*22.)+ll.=146619.

8.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 with the
/BL switch.

8.5.4.1 Using the /BL Switch - The
switch is:

format

for

the

/Block

Factor

outdev: [filelabel]/BL=n=indev: [filelabel]
Note:

/BL:n will also be accepted.

The value 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.
(See your system manager for this information.)
8-12

DISK SAVE AND COMPRESS (DSC)
The /BL switch can be specified either on the input or output side
a DSC command line.

Note, if the input volume is tape, DSC determines the block factor
from the header label of tha input file and ignores the /BL switch.
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 line.
However, if you specify the
/BL switch only on the output side of a command line, 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 line
requires more memory than DSC has available, DSC displays the message
BAD BLOCKING FACTOR and exits.
For example:
DSC>DBl:/BL=ll=DBO:

or 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 on
your system, it will display the error message BAD BLOCKING FACTOR.
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.
Once DSC has expanded its buffers to the value of the /BL switch, that
value becomes the default value.
DSC does not reduce its task image
size if a command line is executed at a lower block factor.
However,
if you specify a lower block factor in a subsequent command line, DSC
will create that volume at the lower factor.

8.5.4.2 System-Dependent Requirements for /BL Switch - On-line DSC on
a mapped system expands automatically if memory is available.
(See
the RSX-llM System Generation and Installation Guide for details of
building DSC with additional memory.)
Table 8-3
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 Systems 1

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 beyond 4.
8-13

with

DISK SAVE AND COMPRESS (DSC)

8.5.5

/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.
The /Compare switch is always
specified on the output side of the DSC command line.
If the
comparison involves tape and disk, specify the tape as the input
device.
The /Compare switch performs only comparison operations; no
copy operation is involved.
To perform both a copy and compare
switch (see Section 8.5.8).

operation,

use

the

DSC

/Verify

Specify the /Compare switch as follows:
outdev: [filelabel]/CMP=indev: [filelabel]
When DSC finds a difference between the volumes it is comparing, it
displays a warning message on your terminal. This warning message
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 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
comparison with the next volume until it detects an EOF.
When DSC begins a comparison involving tape, it first positions the
specified or implied file as described
in Section 8.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 compare operation for it is completed.
DSC then resumes the
comparison using the next volume of the set.

8.5.6

/Density Switch

The Density switch, with its two options, allows you to override the
DSC default storage density of 800 bpi for TU16, TE16, TU77, and TU45
tape drives and 6250 bpi for the TU78.
The following
two sections
discuss these options.
Although you can use other tape drives with
DSC, only these drives can support the /Density switch.
You do not have to specify the /Density switch when a tape is the
input device. DSC determines the density of all input tapes by first
reading the tape at 800 bpi and then, if that fails,
reading it at
1600 bpi.
In the case of the TU78, DSC first reads the tape at 6250
bpi, then, if that fails, it reads the tape at 1600 bpi.
If you specify the /Density switch with a disk, DSC
message and halts the operation.

8-14

issues

error

DISK SAVE AND COMPRESS (DSC)
If you specify the /Density switch with tape drives other than those
above, DSC ignores the switch and does not alter the default density.
Note that TSll (TS04) drives write all tapes at 1600 bpi and cannot
support 800:1600.
The TSll
(TS04)
ignores the /Density switch,
therefore do not use it with these devices.

8.5.6.1 1600 bpi Option - The 1600 bpi Option directs the TU16, TE16,
TU77,
TU78, or TU45 drive to operate as an output volume at a density
of 1600 bpi. The drive then writes all volumes in the tape set at
that density.
For example:
DSC>MM01:,MM02:SYSFILE/RW/AP/DENS=l600=DB1:
In this example, MMOl:

and MM02:, are written at 1600 bpi density.

8.5.6.2 Split Density Option - The
Split
Density
Option
(/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
blocks on the first volume, at 1600 bpi. The first block on the file
contains the volume label 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 bpi and the remainder of the file at 1600 bpi.
DSC>MM01:,MM02:SYSFILE/RW/DENS=800:1600=DB1:
NOTE
Magnetic tapes created using the Split
Density
Option
do not comply with
American National Standard X3.27-1978.
You cannot use the Split Density Option with the TE16 magnetic tape
drive.
Tape drives controlled by a TM03 also cannot use the split
density option. The TM02 controller, however, does support the split
density option.

8.5.7

/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 operation. You can use it to rewind either input or output
volumes (see Table 8-4).
The /RW switch can be used only with magnetic tapes.
with any other volume, DSC prints an error message.

8-15

you

use

DISK SAVE AND COMPRESS (DSC)
INPUT

If you enter the /RW switch as part of the input specification, DSC
rewinds only the first tape before the DSC operation begins. The
other tapes are rewound before they are about to be accessed.
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 a volume of a tape set has been copied, DSC rewinds it and
places it offline.
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.
OUTPUT

If you enter the /RW switch as part of the output specification, DSC
rewinds the output tape before beginning a copy or compare function.
The default is no rewind and the tape is not moved.
If you do not enter the /RW switch with the output specification and
the first volume is not positioned at BOT, DSC begins its operation
after the last DSC-created EOF it finds on that volume.
After the output tape has been rewound, DSC determines if the tape is
positioned at the beginning (BOT).
For a compare function, a search
for the next file or a specific file begins at the current tape
position.
For a copy function, if the /Append switch was specified or
if the tape is not positioned at BOT, the search for the current end
of DSC created files begins (see Section 8.5.2);
otherwise, the copy
operation will overwrite any data previously stored on the tape.
Table 8-4 summarizes the use of the /Rewind switch
operations, with and without a file label.

with

various

DSC

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 BOT 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.
The following example shows the restoration of a DSC-created file:
DSC>DBl:=MM02:,MMOl:SYSFILE/RW

8-16

DISK SAVE AND COMPRESS (DSC)
Table 8-4
The /Rewind Switch and DSC Operations
Switch

Specification

File Label

Action

/RW

Input/Output

With/without

Rewinds first tape
before copy
operation begins.

/RW

Input

With

DSC searches for
specified file
from the beginning
of the first tape
volume before a
copy/compare
operation begins.

/RW

Input

Without

DSC copies/
compares the first
file it encounters
on the first
volume.

/RW

Output/With

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,
unless /AD is
specified.

Output

If the tape is not
at BOT, DSC writes
data, beginning
after the last
end-of-file block
it encounters.

Rewind
Switch

(If tape is
already at BOT,
and the /AP switch
is not specified,
DSC starts there.)
During copy
operations to
multiple tapes,
DSC rewinds the
tape as it is
filled and takes
it offline.

8-17

DISK SAVE AND COMPRESS (DSC)
In this example, DSC restores a volume (DBl:)
by using a tape set
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 search 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. If SYSFILE ended on MM02: the first time it
was accessed, the tape is not rewound and unloaded but is positioned
to access the next file.
NOTE
When you refer to tapes after your
system is booted, you must use the
/Rewind switch.
If you do not use the
switch, the tape driver will return an
error message.

8.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
(DSC does not
operation to verify that the two volumes are the same.
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:, then writes MM02:
and compares MM02:, after which 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 an input tape set, DSC
copy the first file it finds on the first volume of the set.

will

When DSC detects EOV or EOF on any volume of a tape set during a copy
operation, it repositions the volume to the beginning of the current
file segment 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 t~pe 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.

8-18

DISK SAVE AND COMPRESS (DSC)
8.6

DSC OPERATION 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. DSC then accesses
the remaining primary file headers in numerical order.
For example:
DSC>DBl:=DB2:
In this example, DSC copies all the files on DB2:

to DBl:.

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 reduces the
number of file extensions required as the retrieval pointers are
eliminated.
As a result of a copy operation, each primary file header is followed
by all of its extensions. Volumes created in a 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.
is allocated in as few
If an input file is not contiguous, data
in the first unoccupied blocks
contiguous sections as possible,
available on the output volume.
Before the actual copying of data to a disk begins, DSC must,
in
effect,
initialize the disk. This process might take several minutes
if there is a maximum number of files allocated
in the Index file.
Although it might appear that DSC is in a loop during this period, it
is actually zeroing out all headers in the Index file.

8.7

STAND-ALONE DSC - DSCSYS.SYS

Stand-alone DSC DSCSYS.SYS does not support all the features of the
on-line version. DECtapes, floppy diskettes, DF/DS fixed-head disks,
and TU58 cassettes cannot be used with the standalone version.
In
data transfer operations, stand-alone DSC uses all of the switches
described in Section 8.5.
The system data base in the stand-alone version has a Device Control
Block
(DCB) for each supported device type.
The DCB points to a Unit
Control Block (UCB) for logical unit 0 and for logical unit 1.
Except
for MS tapes, the UCBs for a specific device type point to a common
Status Control Block (SCB) which contains the CSR and Vector Addresses
associated with the related controller as listed in Table 8-6.

8-19

DISK SA~ AND COMPRESS (DSC)
Since MSO:
and MSl:
require unique CSR and Vector addresses, their
respective UCBs point to separate SCBs. The format of the system data
base imposes the following restrictions:
•

Logical unit numbers are limited to O and 1.

•

Only one controller per
supported per command.

•

DP and DR type devices have been assigned nonstandard vector
addresses
to
avoid possible conflict with DB devices.
Similarly, MT and MS tapes have been assigned nonstandard
vector addresses to avoid possible conflict with MM tapes.

device

type

(except

tapes}

You can overcome some of these limitations by using the four switches
listed in Table 8-5 to alter the system data base default values to
match your system. A mismatch of either the CSR or Vector address
will cause the stand-alone system to fail.
The switches can be used
only with stand-alone DSC.
Table 8-5
Stand-Alone DSCSYS.SYS Switches
Format

Switch

Description

/CSR=xxxx

/Control Status
Register switch

Specifies control status
addresses for a specific
SCB.

/TM02=x

/TM02/TM03 Formatter
switch

Specifies the physical
unit number of the
formatter on the
RH11/RH70 controller.

/UNIT=x

/Unit switch

Specifies the physical
unit that will be
referenced by the
indicated UCB.

/VEC=xxx

/Vector Address
switch

Specifies the vector
address for a specific SCB.

The four switches supplied with stand-alone DSC can appear together in
a single command line to specify the appropriate values of a single
device or device type. However, you can only specify 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 command lines until
you either specify new switches in a new
command line or terminate DSC.

8-20

DISK SAVE AND COMPRESS (DSC)
The general format for a stand-alone DSC command with switches is:
DSC>ddnn:/switchl=x ••• /switchn=y
ddnn:
The device identifier and unit number specifying the DCB and UCB
/switchl ••• /switchn
One or more of the
following sections

stand-alone

switches

described

the

x,y
The values you assign to the switch(es)

8.7.1

/Control Status Register Switch

Use the Control Status Register switch (/CSR)
to alter the device
Control Status Register address generated by stand-alone DSC so that
it conforms to the address required by your system for a particular
device.
Table 8-6 lists the CSR and vector addresses
supported by stand-alone DSCSYS.SYS.

the

Table 8-6
System-Generated CSR and Vector Addresses
Device Type

CSR

Vector

DB:

176700

254

DK:

1 77404

220

DL:

174400

160

DM:

177440

210

DP:

1 76714

300 1

DR:

176700

320 1

MM:

172440

224

MT:

172522

3201

MSO:

172522

320 1

MSl:

17252 6

3301

MF:

175400

260

1. Indicates nonstandard vector address.

8-21

device

types

DISK SAVE AND COMPRESS (DSC)
The following example illustrates the correct use of the /CSR switch:
DSC:MM1:/CSR=l60546
DSC>DBO:/CSR=l60646
In this example, DSC has set the CSR addresses of the MMl: tape drive
and the DBO:
disk drive to 160546 and 160646, respectively. After
you enter these values, you can enter another DSC 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 same type, only
specify the /CSR switch once for each device type.
(The exception is
the MS:
tape drive; each drive must be set to its correct CSR on the
host system.)

8.7.2

/TM02 Switch

Use the /TM02 switch (/TM02) to specify the physical unit number of
the TM02/TM03 formatter, associated with a particular UCB on the RH
controller for your system. This switch need only be used if that
physical number differs from the current value. Do not confuse this
number with the physical number assigned to a particular tape drive.
Stand-alone DSC is created with a physical unit number of 0 assigned
to the TM02/TM03 formatter on the RH controller. This assignment
affects each of the two UCB's for MM tapes. You can change this to
any octal digit from 1 to 7 for each MM: device. For example:
DSC>MM1:/TM02=1
This command line alters the physical unit number of the formatter
associated with MMl: from its current assignment on the RH controller
to 1. The /TM02 switch affects only the specified device.
If MMO:
also requires a change, the command must be repeated specifying MMO:.
If MMO:
and MMl: are associated with different RH controllers, they
cannot appear in the same command line. The /TM02 switch only works
with MM: devices.
It cannot be specified with an MT:, MS:, or a disk
device.

8.7.3

/Unit Switch

You can use the /Unit switch (/UNIT) to change the unit numbers DSC
accepts for device specifications. Stand-alone DSC is generated with,
and accepts only, two logical unit numbers, 0 and 1. This constraint
can be amended somewhat with the /UNIT switch. The numbers 0 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:
DSC >DP 1: /UNIT=S
This command will initiate a copy from the DP currently designated
physical unit 5 to DPl:.

DSC>DPl: =DPO:
In this command, the output device is the DP currently designated as
unit 1 unless the /UNIT switch had previously been applied to DPl:.
8-22

DISK SAVE AND COMPRESS (DSC)
8.7.4

/Vector Address Switch

Use the /Vector Address switch (/VEC) to change 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:
DSC>DB1:/VEC=320
After you enter this command line, all
accessed with a vector address of 320.
Stand-alone
conflicting
contains:

DB:-type

devices

will

DSC uses nonstandard vector
addresses
to
resolve
unit configurations. These conflicts occur when a system

•

MM, MT, or MS device types such as a TU16, TElO/TUlO or a TS03
drive, for example.

•

Any combination of RP02/03, RP04,05/06/07,
(such as an RP02 disk and an RP04 disk).

and

RM02/03/05/80

For example, before you can reference MM, MT, or MS tapes, you must
use the /VEC switch to change the DSC vector setting of 320 to the
correct value for your system.
DSC>MT1:/VEC=224
After you enter this command line, all MT devices will be accessed
with a vector address of 224 (instead of the DSC-generated vector
address of 320).
The /VEC switch applies to all drives of the same type except
case of MS:, where only the specified device is affected.

the

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.

8.8

STAND-ALONE DSC - DSC64K.SYS

DSC64K is similar to the on-line version of
exceptions:

DSC

with

the

following

•

DSC64K is not overlaid

•

DT, DX, DY, DD, DF, DS devices are not supported

•

Only one tape may be referenced either as input or output

•

The maximum blocking factor is 4

This version is essentially an RSX-llM system with BAD, FMT, DSC, and
CNF
fixed
in
memory,
and
requires
64KW of memory.
When
[l,5l]DSC64K.SYS is software booted, the system comes up with CNF
active.

8-23

DISK SAVE AND COMPRESS (DSC)
CNF is the Stand-alone Configuration and Disk Sizing Program.
It
lists the switches you can use and then prompts you for the first
device type for which you would like the CSR and vector information.
It is recommended that you first specify /DEV to find out the status
of devices on your system. You can also use CNF and its switches to
set the CSR and vector addresses of devices in your system or to
change the default formatter number (FOR=n) for some of the magnetic
tape devices.
(The functions of these switches correspond to the
switches listed in Table 8-5 for DECSYS.SYS.)
The CNF switches are:
/CSR=nnnnnn
Changes the default CSR for the device.
/DEV
Lists the default CSR and vector addresses for
devices.

all

the

/FOR=n
Changes the default formatter number for some of the
magnetic tape devices. The switch is only valid for MF:-and
MM:- type devices. The initial default for n is O.
/VEC=nnn
Changes the default for the device.
CNF will prompt you for the first device you want to reference.
If
adjustments are required for the device, use the appropriate CNF
switch(es). For example, to alter the vector and CSR values for MT:,
type the following:
MT:/VEC=nnn/CRS=nnnnnn
After the system data base has been adjusted with the new values, CNF
prompts you for the second device. The response will be similar to
the response for the first device. CNF will then request that you
press the RETURN key to return control to MCR.
Use the RUN command to
activate any one of the four installed utilities.
The DSC64K system image (DSC64K.SYS) and symbol table (DSC64K.STB) are
located in UFD [1,51] on the following disk volumes:

8.9

BIG DISK KIT

RSXMBL31

RK06/RK07 KIT

CLISRC

RL01/RL02 KIT

RLUTIL

RK05 KIT

DCLSRC

DSC DATA TRANSFERS

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.
8-24

data

DISK SAVE AND COMPRESS {DSC)
8.9.l

Data Transfer from Disk

After you enter a DSC command line 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 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:

8.9.2

Verifies that the disk is on line and in Files-11 format.

Transcribes disk index files, updated for their new status.

Reads the data to a DSC buffer.

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 backup of the disk's contents.
You can only use DSC-created tapes by copying them back to a disk and
restoring the disk's contents to their original
form.
Although the
tapes contain many individual files from the input disk, DSC treats
the tapes as if they contained a single file -- a file of the disk's
entire contents.
When DSC begins writing the disk'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 Ds·c
begins to restore the disk, it will load each volume in the tape set
in order.

8-25

DISK SAVE AND COMPRESS {DSC)
After the header, the tape set includes the data required to
reconstruct directory files, maps and pointers, and the actual files
copied 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 copy operation, first ensure that the tape devices are
online. You can specify multiple tape drives in the following way:
DS c >d d nn ( o ) : , d d n n {1 ) : , • • • d d n n ( 7 ) : [ f il e 1 a be 1 ] = ind ev :
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 line
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 line.
Although you can specify up to eight drives on the output side of the
command line (two drives in stand-alone DSC), you can specify each
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 previous example, the order of
replacement until an end-of-file is reached would be as follows:
MM 0:

MM l:

MM 4:

MM 2:

MM 0:

MM 1:

MM 4:

MM 2:

In summary, to transfer data to tape, DSC:

8.9.3

Verifies that the first or only
on-line and write-enabled.

volume

tape

set

Verifies that subsequent volumes of a tape set are at
Beginning
of
Tape
(BOT), on-1 ine when required, and
write-enabled.

Transcribes data from a DSC buffer to the tape.

Data Transfer from Tape

DSC can only use the tapes it creates to (1) reconstruct a disk or (2)
perform 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. Up to eight drives may be specified on the input side;
they
will be referenced in round-robin fashion as described in Section
8.9.2. As it transfers the data, DSC creates and updates directory
files.
Tape drives specified as input devices must be on line.
The volumes
in the tape set must be referenced in the correct order in the command
line.
8-26

DISK SAVE AND COMPRESS (DSC)
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:

8.9.4

Verifies that the tape drives are on line.

Accesses the volumes in a tape set in round-robin order.

Creates directory files.

Reads the data to a DSC buffer.

Data Transfer to Disk

A DSC operation is not complete
transfer is restored to disk.

until

the

data

involved

the

To receive input, a disk must be on line. Any disk large enough to
contain all the input data can be specified as the output disk when
the data is restored to the original disk.
The disk should have an up-to-date bad block descriptor or have bad
block data entered in a DSC command line 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 program (see Chapter 6).
After identifying the bad blocks on the output disk, DSC examines that
disk to ensure that it has enough free blocks to contain all the data
to be transferred.
DSC compares the number of blocks to
be
transferred from the input disk(s) with the number -of blocks available
on the output disk. DSC issues an error message and exits if too few
blocks are available.
DSC constructs the index and storage bit map files when it begins
transcribing files.
DSC updates the file headers to reflect the
location of the data 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 LBN available on the
disk.
DSC will write the primary file header, 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 RK05) or vice versa.
Compressing files in this manner is beneficial when retrieval pointers
for a noncontiguous file header are almost used up. Because DSC
creates each retrieval pointer to map as many contiguous blocks as
possible
(maximum
is
256.),
the number of pointers may be
significantly reduced.
DSC can also reduce the number of file
extensions and extension headers.

8-27

DISK SAVE AND COMPRESS (DSC)
Note that when DSC writes to a disk, it begins writing data into the
lowest LBN 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:

8.10

Verifies that the disk is on line.

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 displayed on your terminal in either a long or a
short form:
on-line DSC displays the long form and stand-alone DSC
displays the short form.
You can determine the meaning of the short
form message from the number provided with the message. Use the
number to find the long form message in Section 8.10.1.
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:

generates

the

short

form

Error messages which only appear with the stand-alone versions of
are described in Section 8.10.3.

DSC

Table 8-7 is a quick reference to the single letter codes
general messages and in I/O messages (Section 8.10.2).

FATAL *** 17 OUTPUT TAPE MMl:
The same error generates
stand-alone DSC:

the

format

NOT ANSI FORMAT

following

message

FATAL*** 17 - MMl

8-28

used

DISK SAVE AND COMPRESS (DSC)
Table 8-7
General Error and I/O Error Message Codes
Type of
Code

Meaning

Symbol

General
Error
Message

Code
Code
Code
Code
Code
Code

I/O
Error
Message

A
B
C
D
E
F

Failed to read storage bit 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
Reading
Reading
Reading
Reading

index file bit map
index file header
storage bit map
boot or home block
Read~~q file header
Input (or output device)
Writing index file bit map
Writing storage bit map header
Reading data
Reading input tape labels
Reading file attributes
Reading file header
Reading index file data
Reading summary data
Writing file header

c
D
E

F
G
H
I

K
L
M

When DSC identifies a file in which a problem has been detected, it
provides only the file-ID (file number, file sequence number) of that
file.
Use the Dump utility (DMP) (described in Chapter 11) with the
/FI switch and /HD switch to obtain the name of the file and other
information contained in the file header.
For example:
DMP>TI:=devid:/FI:x:y/HD/BL:O
This command line will cause DMP to output to a terminal the header(s)
of file x, y.
The variables x and y, displayed in certain DSC error
messages,
represent the file number and file
sequence
number
respectively.

8.10.1

DSC General Messages

The following are the general messages DSC can return.
2

CONFLICTING DEV.

TYPES

Explanation:
specified.

illegal

combination

device

types

was

User Action: Check for
typographical
errors
in
device
abbreviations and make sure that the disks and tape drives are
not specified on the same side of the command line.

8-29

DISK SAVE AND COMPRESS (DSC)
3

MIXED TAPE TYPES
Explanation: Two different types
specified in the command line.

User Action: Reenter the command line,
type of tape drive.
4

Explanation: The command line was entered with a switch
cannot be used with that command line.

that

ILLEGAL SWITCH

the

command

~ine,

specifying

12(10)

shorter

SYNTAX ERROR
Explanation:

An error occurred in the command line format.

User Action:

Reenter the command, specifying the right order.

DUP.

DEV.

NAME;

User Action:
only once.

than

once

Reenter the command line, specifying each device

TOO MANY DEV'S
Explanation: More than the legal number
specified on one side of the command line.
User Action: Reenter the command
than eight devices per side.

than

Reenter the command line, specifying

Explanation: The same device was entered more
the command line.

only

FILE LABEL TOO LONG

User Action:
file label.

specifying

were
one

Explanation: A file label consisting
alphanumeric characters was specified.

drives
only

User Action: Reenter
correct switches.
5

tape

DEV.

ddnn:

line,

devices

specifying

were
more

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 comm.and line.
Reenter the command line.

8-30

DISK SAVE AND COMPRESS {DSC)
10

DEV.

ddnn:

NOT FILES-11

Explanation: The specified input device is not formatted as a
Files-11 device.
User Action: Check the input device that was entered
command line. Reenter the command line.
11

the

Explanation: A syntax error occurred when bad block data
manually entered.

was

BAD BLOCK SYNTAX ERROR

User Action:
Reenter it.
12

Check

the

command

line

that

was

entered.

BAD BLOCK COUNT TOO LARGE
Explanation: There are too many groups of bad blocks {Maximum
is 125.) on the output disk for DSC to handle.
User Action:

Use a different output disk.

BAD BLOCK CLUSTER OUT OF RANGE
Explanation: A manually entered bad block
blocks does not exist on the output disk.

User Action: Check the numbers
Reenter the command line.

blocks

OUTPUT TAPE ddnn:

the

group

User Action: Change the output tape.
to begin a new tape set.
OUTPUT TAPE ddnn:

bad

entered.

FULL

Explanation: The specified tape is full and files
appended to it.

cannot

Reenter a command

be
line

NOT ONLY REEL IN SET

Explanation: The /Append switch was used with a tape that was
not the first tape of a set created by DSC.

User Action:
message 15).

Change tapes.

TAPE ddnn:

NOT ANSI FORMAT

Reenter

the

command

line

(see

OUTPUT TAPE
Explanation: If the medium is an output tape, the /Append
switch was specified and the tape is not in ANSI format.
User Action: Reenter the command line and either omit the /AP
switch to write the specified tape or change to an ANSI tape.

8-31

DISK SAVE AND COMPRESS (DSC)
INPUT TAPE
Explanation:
If the medium 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 line.
18

OUTPUT TAPE ddnn:

and

change

it,

necessary.

NOT DSC TAPE

Explanation: An /Append switch was specified with a tape that
was not created by DSC.
User Action: Reenter the command line and either
/Append switch or change to a DSC-created tape.
19

omit

the

Explanation:
If the medium is an input tape, the tape
mounted out of sequence and is not the first of a set.

was

TAPE ddnn:

A CONTINUATION TAPE

User Action: Reenter the command line and specify input tapes
in 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 line.

FILE STRUCTURE LEVEL ON ddnn:
Explanation: The device is not
disk, so tt cannot be used.
User Action:
line.

Replace the

change

drives

NOT SUPPORTED
a

device,

Files-11
and

Structure

reenter

the

Level
command

I/O ERROR A ON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains why
file bit map on the device could not be read.

the

index

User Action:
If possible, correct the
Reenter the command line.

the

error.

cause

I/O ERROR B ON ddnn:
(Additional error information)
Explanation: The I/0 error indicated explains why the index
file header on the device could not be read. The specified
file is lost.
If possible, correct the cause of the
User Action:
the device. Reenter the command line.
8-32

error

DISK SAVE AND COMPRESS (DSC)
25

CODE A
Explanation: The.file header for the
cannot be read.

storage

bit

map

file

User Action: The disk is unusable and, therefore, cannot
copied. Replace the disk and reenter the command line.
26

I/O ERROR C ON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains the error
occurred when DSC read the specified file.
User Action:

that

Reenter the command line.

rto ERROR D ON ddnn:
{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:
drive.

Reenter

the

command

line,

User Action:
If possible, correct the
Reenter the command line.

the

explains
the

error.

Explanation: The specified file does not have a
in the index file.
The file is not copied.

file

header

User Action: This is a warning only.
If
operation can be retried on a different drive.

desired,

INPUT DEVICE ddnn:

cause

file ID, y, y NOT PRESENT

User Action:

This is a warning only.

INPUT DEVICE ddnn:

the

File ID y, y IS DELETED

Explanation: The specified file was partially deleted on
input disk and was not copied.

new

I/O ERROR E ON ddnn:
file ID
{Additional error information)
Explanation: The
I/O error indicated
specified file header could not be read.

specifying

the

No action is required.

File ID y, y UNSUPPORTED STRUCTURE LEVEL

Explanation: The header of the file indicated by the message
does not contain 000401 in its File Structure Level Field
{indicates ODS-1 structure). DSC only copies ODS-1 files,
therefore this file will not be copied.
User Action: This message is only a warning.
attempt to copy the remainder of the input.
8-33

DSC

will

DISK SAVE AND COMPRESS (DSC)
35

INPUT DEVICE ddnn:

File ID y, y FILE NUMBER CHECK

Explanation: An incorrect file header was read from the disk,
causing the specified file to be lost.
User Action:
36

Reenter the command line.

INPUT DEVICE ddnn:

File ID, y, y FILE HEADER CHECKSUM ERROR

Explanation:
Incorrect file
specified file to be lost.
User Action:
37

header

contents

caused

the

Reenter the command line.

INPUT DEVICE ddnn:

File ID y, y SEQUENCE NUMBER CHECK

Explanation:

The sequence number is incorrect.

User Action:

Replace the disk and reenter the command line.

INPUT DEVICE ddnn:

File ID y, y SEGMENT NUMBER CHECK

Explanation: The linkage connecting file segments was broken;
the specified file is lost.
User Action:
39

Reenter the command line.

DIRECTIVE ERROR error number
Explanation: An internal error occurred, usually
of a system overload.
User Action:

the

result

Reenter the command line.

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
required unless another error message is displayed.
If
another error message is displayed, correct the cause of the
error and reenter the command line.

I/O ERROR I on ddnn:
File ID y, y VBN z, z
{Additional error information)
Explanation: An I/O error occurred that resulted in bad data
being read from the specified virtual block number of the
indicated file on the indicated device.
User Action:
examine the
error.

This is a warning message only.
You should
block specified to determine the extent of the

8-34

DISK SAVE AND COMPRESS (DSC)
42

VERIFICATION ERROR ON ddnn:
File ID y, y, y VBN z, z
Explanation: The input and output devices
verification operation did not match.

specified

User Action: This is a warning message only.
is necessary.
43

for

User Action

BAD DATA BLOCK ON ddnn:
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.
User Action: When the copy operation is completed, the data
contained in the specified block should be examined and
corrected.

MOUNT REEL x ON ddnn:
Explanation:

AND HIT RETURN

This is an instruction only.

User Action: Mount the volume number requested
on
specified tape drive and press the RETURN key when ready.
45

the

STARTING VERIFY PASS
Explanation: The copy operation is complete and DSC is
beginning the verify operation (specified with the /Verify
switch).
User Action: This is an
User Action is required.

informational

message

only.

RESUME COPYING
Explanation: The verify operation (specified with the /Verify
switch)
is complete and DSC is continuing the copy operation
(if there is more material to copy).
User Action: This is an
User Action is required.

ddnn:

IS WRITE LOCKED.

Explanation:

informational

message

only.

INSERT WRITE RING AND HIT RETURN.

The indicated device is write-locked.

User Action: Make sure the device is the one you want,
write-enable it, and press the RETURN key.
Reenter the
command line.

8-35

DISK SAVE AND COMPRESS (DSC)
48

INPUT FILE ON ddnn:

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:
49

Reenter the command line.

OUTPUT DEVICE ddnn:
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: Reenter the
fragmented output disk.
50

command

OUTPUT FILE HEADER FULL ON ddnn:

line,

specifying

less

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 current header(s) of the file.
The allocation
of blocks to the current output header is aborted. DSC will
copy as many blocks as it has mapped to that header before it
continues to allocate blocks to the header of the next output
file. Note that some blocks will not be copied during this
operation.
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.
PIP will assign a different file number to the output, other
than the original input file number, therefore the files will
not compare when you use the DSC /Compare switch.
51

OUTPUT FILE HEADER ON ddnn:

NOT MAPPED - FILE ID y, y, y

Explanation: Space for the specified
allocated. The file is lost.

file

User Action:
required.

Reenter the command line;

header
new

disk

was

not

may

I/O ERROR G ON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains why
File Bitmap could not be written.
User Action:

Reenter the command line.

8-36

the

Index

DISK SAVE AND COMPRESS (DSC)
53

FAILED TO READ FILE EXTENSION HEADER ON ddnn:

FILE ID y, y, y

Explanation: When copying from the input disk, DSC searched
for an extension header, but did not firtd 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:
54

Reenter the command line.

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 then reenter the command line.

INDEX FILE ALLOCATION FAILURE
Explanation: Too many bad blocks
allocation for the specified file.
User Action:

the

exist

allow

the

Replace the disk, then reenter the command line.

OUTPUT DISK ddnn:

IS NOT BOOTABLE

Explanation:
Logical block number O, which is the bootstrap
(This message
block, of the specified disk or tape is bad.
will always be proceeded by message 84 and/or 86 indicating
the reason for the error.)
User Action:
57

This is a warning only.

No action is required.

INVALID BAD BLOCK DATA
Explanation:
invalid.

The

bad

block

data

the

output

disk

User Action: Run the BAD program on the disk and manually
enter bad block data or reenter the command line specifying
another disk.
58

BAD BLOCK FILE FULL
Explanation:

Too many bad blocks exist on the output disk.

User Action:

Replace the disk then reenter the command line.

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 line,
specifying a new disk.

8-37

DISK SAVE AND COMPRESS (DSC)
60

OUTPUT DEVICE ddnn:

IS A DIAGNOSTIC PACK.

DO NOT USE IT!

Explanation: The specified output disk is a
and cannot be used.
User Action:
line.

diagnostic

Mount a new output disk and reenter the

pack

command

CODE B ON ddnn:
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 Action: Determine the extent
of
the
error.
If
necessary, try the tape on another drive or create another
tape.

CODE C ON ddnn:
File ID y, y, y VBN z, z
Explanation: The tape position was lost when DSC read the
data file specified. Data beyond the VBN mentioned is lost.
User Action: Re-create the tape or reenter the
specifying a different tape drive.

command

line

CODE DON ddnn:
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:

Reenter the command line.

FAILED TO MAP OUTPUT FILE ON ddnn:
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:

Reenter the command line.

OUTPUT DISK ddnn:

IS TOO SMALL -- nn BLOCKS NEEDED

Explanation: The output disk is not
accommodate the data to be transferred.
User Action:
output disk.

Reenter the command line,

8-38

large

enough

specifying

larger

DISK SAVE AND COMPRESS (DSC)
66

I/O ERROR C ON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains why the storage
bit map could not be read.
User Action:

Reenter the command line.

I/O ERROR H ON ddnn:
Explanation: The message that follows explains why the header
of the storage bit map file could not be written.
User Action:

Reenter the command line.

I/O ERROR JON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains why
labels on the specified device could not be read.
User Action:
tape drive.

the

tape

Reenter the command line, specifying a different

INPUT TAPE ON ddnn:

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 operation.
User Action:
If the /Verify switch was not
the tape and remount at BOT.
70

specified,

WRONG INPUT TAPE ON ddnn:
EXPECTING File ID, FOUND File ID
Explanation:

The input tapes were specified out of sequence.

User Action: Check the tapes, then reenter them
order after receiving the mount instructions.
71

check

CODE E ON ddnn:

proper

AFTER File ID y, y, y

Explanation: This message 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:

Reenter the command line.

8-39

DISK SAVE AND COMPRESS (DSC)
72

I/O ERROR K ON ddnn:
AFTER File ID y, y, y
{Additional error information)
Explanation: The I/O error indicated explains
attributes of the specified file could not be read.
User Action:

why

the

Reenter the command line.

I/O ERROR L ON ddnn:
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 file header from tape.
User Action:

Reenter the command line.

INPUT TAPE ddnn:

RESYNCHRONIZED AT File ID y, y, y

Explanation: 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 Action:
re in i ti at ed •
75

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

lhe

User Action: Check the file label and the tape, then reenter
the command specifying the correct tape and file label.
76

EXPECTED EXTENSION HEADER NOT PRESENT ON ddnn: File ID y, y, 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. Reenter the command line.
If not, the
input tape is bad and should be regenerated.
77

CODE F ON ddnn:

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:

Reenter the command line.

8-40

DISK SAVE AND COMPRESS (DSC)
78

I/O ERROR M ON ddnn:
(Additional error information)
Explanation: The message following the device
why the Index File data could not be read.
User Action:

name

explains

Reenter the command line.

INDEX FILE DATA NOT PRESENT
Explanation: When reading the input tape, DSC accessed a file
other than the index file.
This message is the result of a
tape error or an I/O error.
User Action: Re-create the tape or retry the same tape
different tape drive.

I/O ERROR N ON ddnn:
(Additional error information)
Explanation: The I/O error indicated explains why the index
and storage bitmap files from the specified input tape could
not be restored.
User Action: Reenter the command line, specifying a different
input tape drive.

VOLUME SUMMARY DATA NOT PRESENT
Explanation: Either DSC did not create the input tape or
tape contains incomplete data.
User Action:

Check the tape and reenter the command line.

I/O ERROR 0 ON ddnn: - File ID y, y, y
(Additional error information)
why

the

large

for

Explanation: The I/O error indicated explains
specified file header could not be written.
User Action:
83

Reenter the command line.

BAD BLOCKING FACTOR
Explanation: The specified blocking factor is too
the current operating system.
User Action: Specify a smaller blocking
the command line.

the

factor

and

reenter

INPUT DISK NOT BOOTABLE
Explanation: The input disk does not have a valid boot block,
therefore the output disk will not be bootable. This message
will always be accompanied with message 56 stating that the
output disk will not be bootable.
User Action:

This is a warning only.
8-41

No action is required.

DISK SAVE AND COMPRESS (DSC)
85

INPUT/OUTPUT DISKS DIFFER
Explanation: The boot block is usually different for each
disk type, therefore the output disk may not have a valid boot
block and may not be bootable.
(This message will always be
accompanied by other messages pertaining to the bootability of
the output disk.)
User Action: This is a warning only.
If message 84 is also
displayed, a copy from the output disk to another disk that is
the same type as the original input disk will yield a disk
that is bootable.

BAD LBN # 0
Explanation: The output disk has a bad LBN 0 which is the
boot block; therefore, the output disk will not be bootable.
User Action: This is a warning only. A copy from the output
disk to another disk with a good LBN 0 will yield a disk that
is bootable.

OUTPUT DISK ddnn:

MAY NOT BE BOOTABLE

Explanation: This message is always preceeded by message 85
which indicates the reason for the error. Other messages
concerning the bootability of the output disk may proceed this
message.
(If message 56 is displayed, the output disk will
not be bootable.
User Action: Refer to message 56 and messages 84, 85, and
for more detail.

8.10.2

DSC I/O Messages

In on-line and both stand-alone versions of DSC,
I/O errors are
identified 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.
BLOCK CHECK OR CRC CHECK
Explanation: A parity error occurred indicating that bad data
may have been transferred.
User Action:

Reenter the command line.

8-42

DISK SAVE AND COMPRESS (DSC)
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 and the device specification in
the command line, then reenter the command line.
DEVICE WRITE LOCKED
Explanation:

The disk drive is write-locked.

User Action: Write-enable the
command line.

disk

drive

and

reenter

the

END OF FILE DETECTED
Explanation:

The tape position was lost.

User Action:

Reenter the command line.

END OF TAPE DETECTED
Explanation:

The tape position was lost.

User Action:

Reenter the command line.

END OF VOLUME DETECTED
Explanation:

The tape position was lost.

User Action:

Reenter the command line.

FATAL HARDWARE ERROR
Explanation:

A hardware malfunction occurred.

User Action: Reenter the command line.
If the error repeats,
call your DIGITAL Field Service representative.
HANDLER NOT RESIDENT
Explanation:

The device driver (handler) was not loaded.

User Action:
Load the appropriate device driver
the command line.
INSUFFICIENT POOL SPACE
Explanation:

The operating system is overloaded.

User Action:

Reenter the command line.

8-43

and

reenter

DISK SAVE AND COMPRESS (DSC)
PARITY ERROR ON DEVICE
Explanation:

An uncorrectable read error occurred.

User Action:

Reenter the command line.

PRIVILEGE VIOLATION
Explanation: A device was mounted as Files-11 or is allocated
to a different user.
User Action:
RSX-llM Users: Dismount the disk, allocate
yourself, and reenter the command line.

the

device

RSX-llM-PLUS Users: Dismount the disk, mount it as a
device and reenter the command line.

foreign

ERROR CODE IS <Driver code>
Explanation:

An I/O error that DSC cannot translate occurred.

User Action:
If possible,
reenter the command line.

translate

the

error

code

and

Explanation: Tapes on drives have not been rewound since
system was booted.

the

User Action: Rewind the tapes, using the /Rewind switch in
DSC command line.

ILLEGAL FUNCTION

8.10.3

Stand-Alone DSC Messages

The following messages appear only
DSCSYS.SYS.
(Similar messages are
specify invalid values.)

with the
generated

stand-alone version
by DSC64K.SYS if you

ILLEGAL VECTOR ADDRESS
Explanation:

An illegal vector address was specified.

User Action: Correct the vector specification and reenter the
command line.
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.
User Action:
line.

Correct the

address

8-44

and

the

specified

reenter

the

CSR

command

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

SPECIFIED UNIT NUMBER EXCEEDS MAX.

OF 1

Explanation: Stand-alone DSC does
greater than 1.

not

unit

User Action: Correct the error and reenter the command
Specify the /Unit switch if required.

8-45

numbers
line.

CHAPTER 9
FILE STRUCTURE VERIFICATION UTILITY (VFY)

The File Structure Verification Utility
provides the ability to:

(VFY)

for

Files-11

volumes

•

Check the readability and validity of a file-structured volume
(default function).

•

Print the number of
volume (/FR) •

available

blocks

file-structured

Search for files in the index file that are not in any
• directory;
that is, files that are "lost" in the sense that
they cannot be accessed by file name (/LO).
(See the
IAS/RSX-11 I/O Operations Reference Manual for a description
of the index file.)

• Validate directories against the files they list ( /DV) •
•

List all files in the index file, showing the
name, and owner (/LI).

•

Mark as "used" all the blocks that appear to be available
are actually allocated to a file (/UP).

•

Rebuild the storage allocation bitmap so that itreflects the information in the index file (/RE).

•

Restore files that are marked for deletion (/DE).

•

Delete bad file headers (/HD).

•

Perform a read check on every
file-structured volume (/RC) •

allocated

file

ID,

file
but

properly

block

The volume to be verified must be mounted as a Files-11 device.
There should be no other activity on the volume while VFY is
executing.
In particular, activities that 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, /DE, or /HD switch is being
processed.
Aborting VFY while it is modifying the storage allocation
or index files can seriously endanger the integrity of that volume.

9-1

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.1

VFY COMMAND FORMAT

The command line for VFY uses the format:
VFY>listfile,scratchdev=indev/switch
The parameters of this command format are:
Output Parameters
listfile
Specifies the output listing file in the following format:
dev: [ufd]filename.filetype;ver
If you do not specify a device, the default for the output
listing device is the issuing terminal (TI:). The [ufd] is the
UIC under which VFY is currently running.
You must, however,
specify the file name and file type of the output file.
The
default version number will be the latest version plus one.
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 you.
The scratch
file is automatically deleted when VFY is terminated.
If you do
not specify a scratch device the default device is SYO:.
If the user's default system disk is faulty or full, use this
parameter to direct the scratch file to another device.
The
scratch file should always be assigned to a volume other than the
indev volume. The scratch file is not used with the /FR and /LI
switches.
Input Parameters
indev
Specifies the volume to be verified in the format dev:.
do not specify the volume, the default is SYO:.
/switch
Specifies the function to be performed by VFY.
The VFY switches are described in detail in Section 9.4.

9-2

you

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.2

VFY MODE OF OPERATION

VFY normally operates in read-only mode, where the scratch file,
if
required, is on another device. VFY requires write access under the
following conditions:
l.

If the /UP or /RE switch is used, VFY requires write
to the storage allocation map ([O,O]BITMAP.SYS).

access

If the /DE or /HD switch is specified, VFY
access to the index file ([O,O]INDEXF.SYS).

write

If the /LO switch is specified and lost files are found,
VFY
requires write access to the [1,3] User File Directory which
is the directory containing "lost" files.

requires

If write access to the volume index or bitmap files is required for
the desired operation, the user must mount the volume using the
/UNLOCK switch with the MCR or DCL MOUNT command.
VFY may be run under any UIC if only read access is required.
write access is required, VFY must run under a system UIC.

9.3

VFY VALIDITY CHECK

VFY checks the readability and validity of the volume mounted on the
specified device.
This function is the default function and 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
allocated to that file in the volume bitmap.
The volume may be write-protected if it is not the system volume, or
if the required scratch file is directed to another file-structured
volume.
A validity check is specified in the following format:
listfile,scratchdev=indev<RET>
or
indev<RET>
Example
>VFY DRO:
CONSISTENCY CHECK OF INDEX AND BITMAP ON DRO:
INDEX INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680.
BITMAP INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680.

9.4

VFY SWITCHES

VFY functions are specified with switches appended to the VFY command
line. The switches and their functions are summarized in Table 9-1.

9-3

FILE STRUCTURE VERIFICATION UTILITY (VFY)

Table 9-1
VFY Switches and Functions
Switch

Format

Delete

/DE

Resets the
indicators.

Directory Validation

/DV

Validates directories
the files they list.

Free

/FR

Prints out the available space
on a volume.

Header Delete

/HD

Deletes bad file headers on a
volume.
The subswitch /AL
allows the /HD
switch
to
delete
bad
file
headers
without prompting the user.

Identify

/ID

Identifies the VFY version.
This switch may be specified
on a command line by itself at
any time.

List

/LI

Lists the index file
ID.

Lost

/LO

Scans
the
file
structure
looking for files which are
not in any directory.

Read Check

/RC

Checks the volume to see if
every block of every file can
be read.

Rebuild

/RE

Recovers blocks that appear to
be
allocated
but are not
contained in a file.

Update

/UP

Allocates blocks that appear
to be available but have been
allocated to a file.

9.4.1

Description
marked-for-delete
against

file

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
deleted.
VFY must be running under a system UIC and the volume must be
with the /UNLOCK switch.

9-4

mounted

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.4.2

Directory Validation Switch (/DV)

The Directory Validation Switch (/DV) examines each directory on - the
volume.
(VFY considers any file on the volume with the file type .DIR
and a fixed record length of 16 bytes to be a directory.)
It then
reports any errors found that could be ~ttributed to a corrupt
directory or a nonexistent file listed in the directory. For example:
>VFY DX:/DV
THE FOLLOWING DIRECTORY ENTRIES WERE INVALID
[301,333] FILE ID 13,2,0 DELETED.FIL;l - FILE NOT FOUND
[301,333] FILE ID 12345,3,0 CORRUPTED.FID;l - FILE NOT FOUND
[301,333] FILE ID 14,2,0 GARBAGE.VER;l23456 - INVALID VERSIO~ NUMBER
[301, 333] FILE ID 15, 1, 444 RELVOLNEZ .ERO; 1 - RESERVED FIELD WAS NON-ZERO
4. INVALID DIRECTORY ENTRIES WERE FOUND
Directory entries may be invalid due to the following conditions:
FILE NOT FOUND
The file was either deleted without the corresponding directory
entry being removed or the file ID field in the directory entry
was corrupted. If the file does exist, it cannot be accessed
with this directory entry.
Remove the directory entry using the PIP /RM command.
INVALID VERSION NUMBER
The directory entry was corrupted. If the file
cannot be accessed with this directory entry.

does

exist,

Remove version zero of the file with the PIP /RM command.
RESERVED FIELD WAS NON-ZERO
The third word of the file ID field in a directory entry is a
reserved field and should always be zero. Remove the directory
entry with PIP /RM and then reenter it with the PIP /EN command.

9.4.3

Free Switch (/FR)

The Free switch (/FR) displays the
volume with the following message:
dev: HAS nnnn.

9.4.4

available

BLOCKS FREE, nnnn.

space

specifiea

BLOCKS USED OUT OF nnnn.

Header Delete Switch (/HD)

The Header Delete switch {/HD) recognizes all bad file headers on a
volume.
If you specify the /AL subswitch, all bad file headers will
automatically be deleted.

9-5

FILE STRUCTURE VERIFICATION UTILITY (VFY)
If you do not specify the /AL subswitch, VFY prompts you as follows:
>VFY DXl: /HD
CONSISTENCY CHECK OF INDEX AND BITMAP ON DXl:
FILE ID 000015,000003 007334.DIR;l OWNER (7,334]
BAD FILE HEADER
DELETE THIS HEADER [Y /N/Q/G]?
You may respond as follows:
Y (BIT)
N (BIT)
Q (BIT)
G (BIT)

deletes the header and proceeds
does not delete the header and proceeds
does not delete the header and does not proceed
deletes the header and all subsequent bad headers
does not delete the header and proceeds

(BIT)

If you give any other response, the following message will appear:
VFY -- ILLEGAL RESPONSE - TRY AGAIN

9.4.5

List Switch (/LI)

The List switch (/LI) lists the index file.
The output for each file
specifies the file number, file sequence number, file name, and owner
UIC, as shown in the following example:
VFY>DK: /LI
LISTING OF INDEX ON DKO:
FILE
FILE
FILE
FILE
FILE
FILE
FILE
FILE
FILE
FILE
FILE
FILE

9.4.6

ID
ID
ID
ID
ID
ID
ID
ID
ID
ID
ID
ID

OWNER
000001,000001 INDEXF. SYS; 1
OWNER
000002,000002 BITMAP.SYS;l
OWNER
000003,000003 BADS LK. SYS; 1
000004,000004 000000.DIR;l
OWNER
OWNER
000005,000005 C OR IM G • SYS ; 1
OWNER
000006,000006 001001.DIR;l
OWNER
000007,000007 001002.DIR;l
OWNER
000010,000010 EXEMC. MLB; 1
000011,000011 RSXMAC. SML; 1
OWNER
000012,000012 N0 DES • TB L ; 1
OWNER
000013,000036 QIOSYM. MSG; 311 OWNER
000014,000037 F 4PC OM • MSG ; 1
OWNER

(1, l]
[ 1, l]
[ 1, l]
[ 1, 1]
[ 1, 1]
[ 1, 1]
[ 1, 2]
[ 1, 1]
[ 1, 1]
[ 1, 1]
[ 1, 2]
[ 1, 2]

Lost Switch (/LO)

The Lost switch (/LO) scans the file structure looking for files that
are not in any directory and cannot be referenced by file name.
(VFY
considers any file on the volume with the filetype .DIR and a fixed
record length of 16 bytes to be a directory.) A list of the files is
produced, and if the "lost file directory"
[1,3]
exists on that
volume, the files will be entered in that directory.
If an I/O error
occurs, however, on a directory file operation, the files will not be
entered into (1,3].
The following error message will appear:
FAILED TO OPEN DIRECTORY FILE
ERROR CODE -16.
- DIRECTORY (301, 333]
AS A RESULT, NO FILES WILL BE ENTERED_IN (1,3]

9-6

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.4.7

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 optional parameter [:n] is the blocking factor that 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.
The buffer
area available may be increased by installing VFY in a larger
partition. Four blocks are available when VFY is installed in an SK
partition, and four blocks are added for each lK increment.
For the fastest read check, the maximum block factor should be used.
Whenever an error is encountered, each block of the portion in error
is reread to determine which data block(s) cannot be read.
When an error is detected, a file identification line is displayed
the following format:
FILE ID nn,nn filename.typ;ver.

n blocks used/n blocks allocated

Following this line, an error message is displayed.
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
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
the IAS/RSX-11 I/O Operations Reference Manual.

9.4.8

Rebuild Switch (/RE)

The Rebuild switch (/RE)- recovers lost blocks; that is,
appear to be allocated but are not contained in any file.
Multiply-allocated blocks must be deleted
before the Rebuild switch can take effect.

from

the

blo~ks

file

structure

You must run VFY under a system UIC and write-enable the volume.
scratch file should be on another volume.

9-7

that

The

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.4.9

Update Switch (/UP)

The Update switch (/UP) allocates blocks that appear to
but are actually allocated to a file.

Files with multiply-allocated blocks must be deleted
structure before the Update switch can take effect.

from

available
the

file

You must run VFY under a system UIC and write-enable the volume.
scratch file should be on another volume.

The

9.5

FILE ERROR REPORTING

As VFY verifies a volume, error conditions are reported. Errors for a
given file are preceded by a line that identifies the file in error.
This line is formatted as follows:
FILE ID nn,mm filename.filetype;version OWNER [uic]
nn,mm
Represents the unique file identification number assigned to
file by the system at file-creation time.

the

filename
Represents the file name •
• f iletype
Represents the file type (for example, .OBJ for object file).
;version
Represents the version number of the file.
[uic]
Represents the UIC for 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: VFY checks on the validity of
indicate that the header has been corrupted.

the

file

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
9.5.2).
9-8

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 9.5.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 9.5.1).
HEADER MAP ERROR
Explanation: VFY detected an error in the header map
also indicates a corrupted file header.

area

that

The last error message for the file is followed by a summary line
that file, as follows:

for

SUMMARY:

MULT=nn, FREE=nn, BAD=nn.

MULT
Specifies the number of multiple block allocations.

FREE
Specifies the number of blocks marked free that should have
allocated.

been

BAD
Specifies the number of errors encountered in the the map area of
the file header.
If the output for VFY is directed to a terminal and you do not wish to
see the error messages for a given file, enter CTRL/O.
This
terminates the listing of error messages for that file that is, all
messages but the summary line.

9.5.1

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.
Once files have been restored or deleted, run VFY with the /RE switch
to assure the consistency of the volume's storage allocation bitmap.

9-9

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.5.1.1 Restoring a File Marked-for-Delete - To
restore
a
file
marked-for-delete, mount the disk volume using the MCR or DCL MOUNT
command and the /UNLOCK switch. For example:
>MOU DKO:/UNL
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 command.

9.5.1.2 Deleting
a
File
Marked-for-Delete Files that
are
marked-for-delete can be deleted directly with PIP, once their unique
file ID has been obtain'ed by doing a validity check.
The file ID
appears as the first entry in the file identification line that
precedes each list of file errors {see Section 9.5).
The following
example shows 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
system device.
PIP issues the error message:

deleted

from

the

PIP -- FAILED TO MARK FILE FOR DELETE-NO SUCH FILE
since the file system denies the existence of
marked-for-delete; however, the file is deleted.

9.5.2

files

al ready

Deletion of Bad File Headers

If the volume contains bad file headers, it is advisable to delete
them first by using the /HD switch before you address the problem of
multiply-allocated or free blocks. Deleting bad file headers may free
the blocks that were contained in the files with the bad headers. See
Section 9.4.4 for a description of the /HD switch.

9.5.3

Deletion of Multiply-Allocated Blocks

If the file structure contains multiply-allocated blocks, it is
necessary to delete files until there are no such blocks. An
automatic rescan of the volume identifies which files share which
blocks.
This
rescan
lists
the
files
which
contain
the
multiply-allocated blocks. Use this information to determine which,
if any, of the files can be saved and then delete the rest with the
PIP delete function.
After the files have been deleted, VFY should be run once again to
ensure that all of the files containing multiply-allocated blocks have
been deleted.

9-10

FILE STRUCTURE VERIFICATION UTILITY (VFY)
9.5.4

Elimination of Free Blocks

Once there are no multiply-allocated blocks, the next concern is the
elimination of blocks that are marked as free in the storage
allocation bitmap but are actually allocated to a file. To reallocate
these blocks in the storage allocation bitmap, run the validity check
with the /UP switch. This allocates all blocks that should have been
marked as allocated. See Section 9.4.9 for a description of the /UP
switch.
When you have no multiply-allocated blocks and no blocks marked as
free that are actually in use, the file structure is safe for writing
new files and extending existing files.
Files may have data blocks
that have been overwritten as the result of multiple allocation.

9.5.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
(Section 9.3). The last two lines of output give the free space on
the volume.
The first line reports the amount of available space
according to the index file (that is, the number of blocks that are
not in use by any file in the index file). The second line reports
the amount of available space according to the storage allocation
bitmap.
If there are no errors, these two figures should agree.
If the index
file indicates that more blocks are free than the storage allocation
bitmap indicate, 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 and specifying the /RE
switch. See Section 9.4.8 for a description of the /RE switch.

9.6

VFY ERROR MESSAGES

The VFY error messages, their explanations, and suggested user actions
are described below.
VFY -- COMMAND SYNTAX ERROR
Explanation: The command as entered does not conform to
syn tax rules.

command

User Action:
specified.

syntax

Reenter the command line with

VFY -- CLOSE FAILURE ON BIT MAP
or
VFY -- CLOSE FAILURE ON INDEX FILE
or
VFY -- CLOSE FAILURE ON TEMPORARY FILE
or

9-11

the

correct

FILE STRUCTURE VERIFICATION UTILITY (VFY)
VFY -- CLOSE FAILURE ON LISTING FILE
or
VFY -- I/O ERROR ON INPUT FILE
or
VFY -- I/O ERROR ON OUTPUT FILE
or
VFY -- I/O ERROR READING DIRECTORY FILE
or
VFY -- I/O ERROR WRITING FILE HEADER
or
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 -- FAILED TO ALLOCATE SPACE FOR TEMP FILE
Explanation:
is full.

The volume specified for the temporary scratch file

User Action: Use PIP to delete unnecessary files and rerun VFY,
or specify another volume as the scratch device when you reenter
the command line.
VFY -- FAILED TO ATTACH DEVICE
or
VFY -- FAILED TO DETACH DEVICE
Explanation: The list file specified a terminal device.
not able to attach or detach the device.

VFY was

User Action: Reenter the command line with a
that can be attached or detached.

device

9-12

list

file

FILE STRUCTURE VERIFICATION UTILITY (VFY)
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
message and correct that condition.

the conditions caused the
Reenter the command line.

VFY -- FAILED TO FIND INDEXF.SYS;l IN MFD - WILL OPEN INDEX BY FILE ID 1,1
or
VFY -- FAILED TO FIND BITMAP.SYS;! IN MFD - WILL OPEN BITMAP BY FILE ID 2.2
Explanation:

The Master File Directory has been corrupted.

User Action:
7).

Copy the disk using the BRU

VFY -- FAILED TO OPEN DIRECTORY FILE

utility

(see

Chapter

(See OPEN FAILURE error messages)

VFY -- ILLEGAL DEVICE
Explanation: The input device specified is something other
a disk or DECtape.
User Action: Reenter the command line with
device specified.

mounted

than

Files-11

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

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 (8K minimum).

VFY -- OPEN FAILURE ON BIT MAP
or
VFY -- OPEN FAILURE ON INDEX FILE
or

9-13

switch

FILE STRUCTURE VERIFICATION UTILITY (VFY)
VFY -- OPEN FAILURE ON LISTING FILE
or
VFY -- OPEN FAILURE ON TEMPORARY FILE
or
VFY -- FAILED TO OPEN DIRECTORY FILE
or
VFY -- FAILED TO OPEN FILE FOR READ CHECK
Explanation:

One of the following conditions may exist:

•
•
•
•

VFY is not running under a system UIC but should be.

•

The specified file does not exist.

The named file does not exist in the specified directory.
The volume is not mounted •
The specified file is read protected •

User Action: Determine which of the above conditions caused the
message and correct that condition. Reenter the command line.
VFY -- STORAGE CONTROL BLOCK (VBNl of BITMAP.SYS) IS CORRUPTED
Explanation: The Storage Control Block is corrupt.
This
harmless, because only VFY and PIP /FR can examine the block.

User Action: Copy the disk using BRU or DSC (see Chapter 7 or 8,
respectively).
VFY -- THEY ARE STILL LOST, COULD NOT FIND DIRECTORY
Explanation: UFD [1,3] did not exist on the volume.
UFD [1,3]
is the "lost files" directory. VFY enters all files found by the
/LO switch into this directory.
User Action:
volume.

Use the MCR UFD command to enter UFD [1,3]

9-14

the

CHAPTER 10
LIBRARIAN UTILITY PROGRAM (LBR)

The Librarian Utility Program (LBR)
allows you to create, update,
modify,
list, and maintain library files. A library file is a direct
access file that contains a collection of related files.
LBR
organizes files, usually having the same file type, into library
modules so that you have rapid and convenient access to your files.
Library files contain two directory tables:
the entry point table
(EPT)
and the module name table (MNT). The EPT contains entry point
names that consist of global symbols defined as entry points in MACRO
source programs.
The MNT contains names of the modules in the
library. Both tables are alphabetically ordered.
The following paragraphs describe
object, macro, and universal.

the

three

types

libraries:

Object library files (.OLB) contain object files (.OBJ).
The module
names are derived from .TITLE directives, while the entry point names
are derived from global symbols defined in the module.
LBR references
the module code in the library by the module name. The source program
references object library modules by the entry point name.
Entry
points apply only to object libraries.
You use object module libraries as input to the Task Builder.
The
Task Builder
(TKB)
searches for definitions of all global symbols
referenced in a program in the following manner. First, TKB searches
the
other
modules
specified, then it searches the specified
user-written object module library, and finally,
it searches the
system library.
Macro library files (.MLB) contain source macro files
(.MAC).
The
module names are derived from
.MACRO directives. From each macro
definition, LBR extracts the name and creates an entry in the module
name table. The entry in the module name table is the means by which
the assembler finds the associated macro definition in the library.
You use macro library modules as input to the MACR0-11 Assembler. The
assembler searches the specified library for macros listed in .MCALL
statements and called in the source program before searching the
system macro library.
Universal library files (.ULB) contain modules inserted from any kind
of file whether it be a program or text. The module names are either
user-specified in the Insert (/IN) switch or derived from the file
name at the time of insertion.
Primarily, you use universal libraries to package related files
together.
You can reference a univeLsal library module in a program
by using the Universal Library Access ($ULA) system library routine.
$ULA, specified in the macro source program, establishes the necessary
10-1

LIBRARIAN UTILITY PROGRAM (LBR)
conditions for access (read only) to a universal library module.
(For
more information on $ULA, see the IAS/RSX-11 System Library Routines
Reference Manual.)
You can invoke LBR using any of the methods
described in Chapter 1.

10.1

for

invoking

utility

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 any
available space. The entry point table has zero length for macro and
universal libraries.
Figure 10-1 illustrates object and macro library
file format and Figure 10-2 illustrates universal library file format.

10.1.1

Library Header

The header section is a full block in which the first 24(10) words are
us,ed to describe the current status of the library. The header's
contents are updated as the library is modified.
This allows LBR to
access the necessary information to perform its functions
(for
example, Insert, Compress, and Delete).
The twenty-fourth word in the
library header is the default insert file type for universal libraries
and is undefined for macro and object libraries. See Figure 10-3.

10.1.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 po int is defined
(words 2-3).
(See Figure
10-4.) 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 applies only to object
library files.

10.1.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 10-5. The
module name table is sequenced in order of ascending module names.

10.1.4

Module Header

Each module starts with a header of eight words for object and macro
modules and 32(10)
words for universal modules.
The module header
contains information about the module such as the type and status of
the module,
its length
(number of words), and its attributes.
See
Figure 10-6 and Figure 10-7.
In object and universal modules, the low-order bit of the attributes
byte is set if the module has the selective search attribute.
In
universal modules, bit 1 of the attributes byte is set if the input
10-2

LIBRARIAN UTILITY PROGRAM (LBR)
file was contiguous.
Also, in object modules, the two words of
type-dependent information contain the module identification defined
by the .!DENT directive at assembly time. In macro modules, these two
words are undefined.
For universal modules, type-dependent identification is
the file type and version number of the input file.

derived

from

Universal libraries allow you to change the module header, which
contains optional descriptive information, by means of the Modify
Header switch (/MH).

FIXEDLENGTH
RECORDS

LIBRARY
HEADER
ENTRY POINT
TABLE
~

•

MODULE NAME
TABLE

VARIABLELENGTH
RECORDS

BLOCK
BOUNDARIES

MODULE 1 HEADER
MODULE 1

.
..
MODULE N HEADER

•

MODULE N
AVAILABLE SPACE
ZK-184-81

Figure 10-1

General Format for Object and Macro Library Files

10-3

LIBRARIAN UTILITY PROGRAll (LBR)

FIXEDLENGTH
RECORDS

LIBRARY.
HEADER
ENTRY POINT
TABLE

BLOCK
BOUNDARIE.S

MODULE NAME
TABLE
VARIABLELENGTH
RECORDS

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.
ZK-185-81

Figure 10-2

Universal Library File Format

10-4

LIBRARIAN UTILITY PROGRAM (LBR)

OFFSET
WORD

NON ZERO ID

LIBRARY TYPE

LBR (LIBRARIAN) VERSION

( . !DENT FORMAT}

YEAR

DATE AND

MONTH

TIME LAST

DAY

INSERT

HOUR

MINUTE

SECOND

RESERVED

SIZE EPT ENTR's

EPT STARTING RELATIVE BLOCK

NO. EPT ENTRIES ALLOCATED

NO. EPT ENTRIES AVAILABLE

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!

luNDEFINED FOR MACRO AND OBJECT LIBRARIES
ZK-186-81

Figure 10-3

Contents of Library Header

10-5

LIBRARIAN UTILITY PROGRAM (LBR)

WORD

GLOBAL SYMBOL

NAME ( RAD50)

2
3

ADDRESS OF
MODULE
HEADER

RELATIVE BLK.
BYTE IN BLOCK
ZK-187-81

Figure 10-4

WORD

Format of Entry Point Table Element

MODULE NAME

( RAD50)

RELATIVE BLK.

ADDRESS OF
MODULE
HEADER

BYTE IN BLOCK
ZK-188-81

Figure 10-5

Format of Module Name Table Element

OFFSET FROM
START OF
MODULE HEADER
0

ATTRIBUTES

STATUS

SIZE OF

MODULE (BYTES)

6
10

DATE
MODULE
INSERTED

O=NORMAL MODULE
l=DELETED MODULE

YEAR
MONTH

DAY

TYPE DEPENDENT

INFORMATION
ZK-189-81

Figure 10-6

Module Header Format for Object and Macro Libraries

10-6

LIBRARIAN UTILITY PROGRAM (LBR)
OFFSET
START
MODULE

FROM
OF
HEADER

ATTRIBUTES

SIZE OF

MODULE (BYTES)

STATUS

DATE

YEAR

MODULE

MONTH

INSERTED

DAY

!DENT

16
20

OPTIONAL

INFO

OPTIONAL

INFO

OPTIONAL

INFO

OPTIONAL

INFO

40
42
44

USER
FILE
ATTRIBUTES

..
.

ZK-190-81

Figure 10-7

Module Header Format for Universal Libraries
10-7

LIBRARIAN UTILITY PROGRAll (LBR)
10.2

LBR RESTRICTIONS

The following restrictions apply when using LBR:
•

Limit of 65,536(64.K) words per module.

•

Limit of 65,536(64.K) blocks per library.

•

Tables should be allocated their anticipated maximum size.
Expanding table allocations requires using the Compress switch
(/CO) 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 10.5.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).

The library's tables must contain enough space for both the modules
being replaced and their replacements because the new modules are
entered and the old modules are only logically (not physically)
deleted.

10.3

LBR COMMAND LINE

LBR accepts command lines in the following general format:
outfile[,listfile]=infilel[,infile2, ••• infilen]
LBR allows only one level of indirect command file nesting.
complete description of file specifiers, see Chapter 1.

10.4

For

DEFAULTS FOR LBR FILE SPECIFIERS

Table 10-1 describes the defaults for LBR file specifiers.
Table 10-1
LBR File Specifiers Defaults
Default

Specifier
dev:

Output File
SYO:
Listing File
The device that was specified for the output
file;
otherwise, the default for the output
file.
Input File
For the first input file specifier, SYO:.
For subsequent input file specifiers, the
device specified in the previous input file
specifier; otherwise, the default for the
previous input file specifier.
(continued on next page)
10-8

LIBRARIAN UTILITY PROGRAM (LBR)
Table 10-1 (Cont.)
LBR File Specifiers Defaults
Specifier

Default

dev:

Output File [ufd] Output File
The UIC under which LBR is currently running.
Listing File
The UFD that 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.

UIC

For subsequent input file specifiers, the UFD
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
10.5.4), except when the Compress (/CO) or
Create
(/CR)
switch
is
specified
(see
Sections 10.5.1 and 10.5.2, respectively).
Listing File
• LST
Input File
Refer to the
descriptions
of
Compress
(Section 10.5.1), Insert
(Section 10.5.8),
and Replace (Section 10.5.11) switches.

;ver

Latest version of the file, or latest version plus 1
for the output file when the Compress (/CO), Create
(/CR), or Extract (/EX) switches are specified.

/switch

Output File
/IN (Insert)
List File
/SP/LI

(Spool and List module names)

Input File
None.

10.5

LBR SWITCHES

LBR uses switches appended to file specifications to invoke functions.
These switches are summarized in Table 10-2.

10-9

LIBRARIAN UTILITY PROGRAM (LBR)
Table 10-2
LBR Switches
Option

Switch

Function

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 Point

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

List

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

Re pl ace

/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 the selective search
the module header.

Squeeze

/SZ

Reduce the size of the macro source.

/-SZ

Do not reduce
macro source.

Spool

10.5.1

the

size

its

attribute

specific

Compress Switch (/CO)

Use the Compress switch (/CO)
to physically delete all logically
deleted records, to put all free space at the end of the file, and to
make the free space available for new library module inserts.
Additionally, the library table specification may be altered for the
10-10

LIBRARIAN UTILITY PROGRAM (LBR)
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
The format for specifying the /CO switch is:

specification.

outfile/CO:size:ept:mnt=infile
outf ile
Specifies the file that is to become the compressed version of
the input file.
The default file type is .OLB if the input file
is an object library, .MLB if the 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. The 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. The maximum number
of entries is 4096(10).
infile
Specifies the library file to be compressed.
The 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 file type (see Section
10.5.4).
Example
LBR>RICKLIB/CO:l00.:128.:64.=SHEILA.OLB
In this example, file SHEILA.OLB is compressed, and a new
RICKLIB.OLB, is created with the following attributes:

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
version greater than the latest version for the file.

10-11

one

LIBRARIAN UTILITY PROGRAM (LBR)
Both files, RICKLIB.OLB and SHEILA.OLB,
directory file on SYO:.

10.5.2

reside

the

default

Create Switch (/CR)

Use the Create switch (/CR) to allocate a contiguous library file on a
direct access device (for example, a disk). The switch 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 /CR switch is:

specification.

outfile/CR:size:ept:mnt:libtype=infiletype
outf ile
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.
:size
Specifies the size of the new library file in disk
blocks. The default size is 100(10) blocks.

(256(10)word)

: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 zero for macro libraries and
universal libraries. The maximum number of entries is 4096(10).
:mnt
Specifies the number of module name table (MNT) entries to
allocate.
The default value is 256(10). The maximum number of
entries is 4096(10).
:libtype
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 10.5.4), or OBJ if
/DF has not been specified.
: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.
10-12

LIBRARIAN UTILITY PROGRAM (LBR)
Example
LBR>RICKLIB/CR::l28.:64.:0BJ=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
Secondly, 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 (/IN)
is the default switch for input files (see Section
10.5.8).

10.5.3

Delete Switch (/DE)

Use the Delete switch (/DE) to logically delete library modules and
their associated entry points (global symbols) from a library file.
Up to 15(10) 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 DE LE TED:
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 specification.
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 that 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 10.5.1).
The format for specifying the /DE switch is:
outfile/DE:modulel[:module2 ••• :modulen]
out file
Specifies the library file.
/DE
Specifies the Delete switch.
10-13

LIBRARIAN UTILITY PROGRAM (LBR)
: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.

10.5.4

Default Switch (/DF)

Use the Default switch (/DF) to specify the default library file type.
Acceptable default 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 /DF switch, OBJ is the default
library file type.
Specifying a default value:
1.

Sets the default file type for the Create switch (/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.
Exceptions
to this occur when you use /CO or /CR. When you specify /CO,
the default applies to the library input file.
When you
specify /CR, 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 /DF switch only affects the filetype of the file to be
opened. After that, the library header record information is
used to determine the type of library file being processed.

The /DF switch can be issued alone or appended to a library
specification. The format for specifying the /DF switch is:
outfile/DF:filetype •••
or
/DF:f iletype
outfile
Specifies the library file.
/DF
Specifies the Default switch.

10-14

file

LIBRARIAN UTILITY PROGRAM (LBR)
f iletype

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 current
default library type will be set to object libraries and the
following message will be displayed:
LBR -- *FATAL*-INVALID LIBRARY TYPE SPECIFIED
Examples
LBR>/DF:MAC
LBR>RICKLIB=infile
The file RICKLIB.MLB is opened for insertion.
LBR>/DF:MAC
LBR>RICKLIB/DF:OBJ=infile
OBJ replaces MAC as the default filetype.
is opened for insertion.

The

file

RICKLIB.OLB

LBR>/DF:MAC
LBR>RICKLIB/CR
The macro library RICKLIB.MLB is created.
LBR>/DF:MAC
LBR>RICKLIB/CR::::OBJ
Because OBJ is specified, it overrides the
object library RICKLIB.OLB is created.

default

(MAC).

The

LBR>/DF:OBJ
LBR>TEMP/CO=RICKLIB.MLB
Because RICKLIB.MLB is a macro library, MAC overrides the default
(OBJ). The macro library file TEMP.MLB is created to receive the
compressed output.
LBR>/DF:UNI
LBR>RICHLIB=TEST
The file RICHLIB.ULB is opened for insertion.

10.5.5

Delete Global Switch (/DG)

Use the Delete Global switch (/DG) to delete a specified entry point
(global symbol) from the EPT.
Up to 15(10) entry points may be
deleted with one command. This command does not affect the object
module that 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 begins processing the /DG switch,
message on the initiating terminal:
ENTRY POINTS DELETED:

10-15

prints

the

following

LIBRARIAN UTILITY PROGRAM (LBR)
As entry points are deleted from the library file, the 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 specification.
The format for specifying the /DG switch is:
outfile/DG:globall[:global2 ••• :globaln]
outf ile
Specifies the library file.
/DG
Specifies the Delete Global switch.
global
Specifies the name of the entry point to be deleted.
Example
LBR>RICKLIB/DG:SHEILA:LAURA:JENNY
ENTRY POINTS DE LE TED:
SHEILA
LAURA
JENNY
In this example, the entry points SHEILA, LAURA, and
deleted from the latest version of the library
SYO: RICKLIB. OLB.

10.5.6

JENNY are
file named

Entry Point Switch (/EP)

Use the Entry Point switch (/EP) to control (include or exclude)
placement of global symbols in a library entry point table.
switch can be specified in either a positive or negative format:
/EP
/-EP
/NOEP

the
The

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 format (/EP) causes all entry points in
modules to be entered in the library entry point table.

module

Either negative format (/-EP or /NOEP) provides for a module to be
included in a library, but excludes the entry points in that module
from being entered in the library entry point table.

10-16

LIBRARIAN UTILITY PROGRAM (LBR)
/EP is the LBR default.
If the switch is not specified,
points are entered into the library entry point table.

all

entry

The /EP switch has no effect on macro or universal libraries.
The format for specifying the /EP switch is:
outfile[ /EP ]=infile, ••• infilen

[ /-E p ]
[/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.
infile
Specifies an input file. When the /EP 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.
NOTE
Although not reflected in the command
formats, the positive and negative forms
of the switch may be applied to both the
output and input file specifications.
For example, the effect of /EP applied
to the output file can be overridden by
applying /-EP to a specific input file.
The /-EP switch is useful for including modules that contain duplicate
entry point names in the same library. The /-EP switch provides the
means for entering a module in the library without having its entry
points included in the library entry point table.
The /-EP switch 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.
The /-EP switch can be used to exclude entry points from
being entered in the library entry point table.
Depending on
specification
local effect.

whether the /EP switch is applied to the output
or to an input specification, it has either a global or

When applied to the output file specification, the /EP 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.

10-17

LIBRARIAN UTILITY PROGRAM (LBR)
When applied to an input file specification, the Entry Point switch
has a local effect. That is, LBR either 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.
Entry points in an object module are not affected by the /EP switch.
The switch only affects entries in the library entry point table.

10.5.7

Extract Switch (/EX)

Use the Extract switch /EX 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 in
command
line,
all
modules in the library are extracted
concatenated in the output file in alphabetical order.
For universal libraries, RMS fields cannot
record-oriented device, such as a terminal.

extracted

The /EX switch may be applied only to input file specifications.
format for specifying the /EX switch is:

the
and
a
The

outfile=infile/EX[:modulenamel ••• :modulenamen]
outf ile
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.
modulename
Specifies the name
library.

the

module

extracted

from

the

The object modules DXDRV, DKDRV, and TTDRV are concatenated
alphabetical order and written into the file DRIVERS.OBJ.

Examples
LBR>DRIVERS=RSXllM/EX:DXDRV:DKDRV:TTDRV

10-18

LIBRARIAN UTILITY PROGRAM (LBR)
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
file TEST.OBS in alphabetical order.

10.5.8

into

the

Insert Switch (/IN) for Object and Macro Libraries

Use the Insert switch /IN to insert 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.
(The
Insert switch for Universal Libraries, is explained in Section
10.5.9.) The /IN switch is the default library file option and can be
appended only to the library file specification.
If you attempt to insert an input module that 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 /IN switch is:
outfile[/IN]=infilel[,infile2, ••• infilen]
outfile
Specifies the library file into which the input modules are to be
inserted.
The default file type depends on the current default
(see Section 10.5.4). It is .OLB if the current default is
object libraries, .MLB if the current default is macro libraries.
/IN
Specifies the Insert switch.
infile
Specifies the input file containing the modules to be inserted
into the library file.
The default file type is .OBJ if the
outfile is an object library and .MAC if the outfile is a macro
library.

10-19

LIBRARIAN UTILITY PROGRAM (LBR)
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 RICKLIB, which also resides in the default directory
on SYO:. The default file type for files SHEILA, LAURA, and
JENNY is .OBJ if RICKLIB is an object module library, or .MAC if
RICKLIB is a macro library.

10.S.9

Insert Switch (/IN) for Universal Libraries

The Insert switch (/IN) works basically the same for universal
libraries as it does for object libraries and macro libraries.
However, when inserting a file into a universal library, the /IN
switch is applied to the input file rather than the output file. You
can also specify module name and descriptive information as switch
values in the command line.
In addition, LBR copies input file
attributes to the module header.
The high block indicator (F.HIBK of the file's descriptor block) 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 to it as are used.
The format for specifying the /IN switch for universal libraries is:
outfile=infile/IN:name:op:op:op:op
outf ile
Specifies the universal library into which the infile
inserted.

infile
Specifies the input file to be inserted into the outfile.
The
default for the file type is the value indicated at the universal
library's creation time.
(See Section 10.5.2.)
/IN
Specifies the Insert switch.
:name
Optionally specifies the module name (up to six
Radix-SO
characters).
The default is the first six characters of the
input file name.
:op
Specifies optional descriptive information (up to six 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.

10-20

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 MODl.
"THIS", "IS", "JAN2", and "TEXT" are stored
in the module header.
You can insert JOE.TXT without the /IN switch and its values. As
a result, all the information normally specified by the switch
values defaults as described in this example.

10.5.10

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.

These switches can be appended only to the output
or the list file specification.

file

specification

The /LI switch is the default value.
It need not be specified when a
listing file has been specified or when any other list switch is
included in the command line.
The format for specifying list switches is:
outfile[,listfile]/switch(es)
outf ile
Specifies the library file whose contents are 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>RICKLIB/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.

10-21

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>RICKLIB/FU
In this example, a listing of the names of all the modules in
file
SYO:RICKLIB.OLB, and a full description of each one
contained 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, which lists the module names, their entry points, and a
full description of each module for file RICKLIB.
")

10.5.11

Modify Header Switch (/MH)

The Modify Header switch pertains only to universal libraries and
allows you to modify the optional user-specified information in the
module header.
The format for specifying the /MH switch is:
outfile/MH:module:op:op:op:op

outfile
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 six 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 (i) clears the
corresponding information field.

Example
The optional descriptive information for module A of
is:
"MODA" "FCHCD" "OF" "FCH"
The LBR command is:
LBR>RICKLIB/MH:A:FCHTS:i::

10-22

RICKLIB.ULB

LIBRARIAN UTILITY PROGRAM (LBR)
The optional descriptive information for module A in file RICKLIB
is changed to:
"FCHTS" "

10.5.12

" "OF" "FCH"

Replace Switch (/RP) For Macro and Object Libraries

Use the Replace switch /RP 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 macro libraries, only first-level macro definitions are extracted
from the replacement files.
LBR recognizes only uppercase 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
specification and all of the input files are assumed to
contain replacement modules.

•

Local format - The /RP switch is appended to an input file
specification 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 file type depends on the
current default (see Section 10.5.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.
infile
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.
The Global format allows you to specify a list of input files
having to append the /RP switch to each of them.

10-23

without

LIBRARIAN UTILITY PROGRAM {LBR)
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 replaced), append /-RP or
/NORP to the desired input file specification.
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.
infile
Specifies the input file that contains replacement modules for
the output library file.
The local format default is the same as
the global format default.

/RP
Specifies the Replace switch. Appending the /RP
input file specifier constitutes the local format
This overrides the LBR default (/IN) and instructs
the module(s)
contained in the specified file
modules.

switch to an
of the switch.
LBR to treat
as replacement

Examples
The files used in the following four examples, and the modules
contained within each file, are depicted in Figure 10-8. 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 10-8.
1.

LBR>RICKLIB/RP=SHEILA,LAURA,JENNY
MODULE
MODULE
MODULE
MODULE
MODULE

"SHEILA"
II LAURAl II
"LAURA2"
"JENNYl"
"JENNY2"

REPLACED
REPLACED
REPLACED
REPLACED
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 same names in the library file
named RICKLIB and modules JENNY3 and LAURA3 are inserted.
The resulting library file is shown in Figure 10-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 the description of
the /IN switch in Section 10.5.8.) The resulting library file
is shown in Figure 10-10.

10-24

LIBRARIAN UTILITY PROGRAM (LBR)
3.

LBR>RICKLIB/RP=SHEILA,LAURA,JENNY,CHRIS/-RP
MODULE
MODULE
MODULE
MODULE
MODULE

"SHEILA"
"LAURAl"
"LAURA2"
"JENNYl"
"JENNY2"

REPLACED
REPLACED
REPLACED
REPLACED
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 that contains
modules to be inserted. The resulting library file is shown
in Figure 10-11.
4.

LBR>RICKLIB/RP=SHEILA,LAURA/-RP,JENNY
MODULE "SHEILA" REPLACED
LBR -- *FATAL* -- DUPLICATE MODULE "LAURAl" IN LAURA. OBJ; l
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 10-8). Therefore, LBR issued the
fatal
error message and terminated the processing of the
current command line.

OUTPUT
LIBRARY FILES

INPUT FILES

FILE NAME RICKLIB.OLB;l SHEILA.OBJ;! LAURA.OBJ;! JENNY.OBJ;! CHRIS.OBJ;!
LAURA!

JENNY!

CHRIS!

JENNY2

LAURA2

JENNY2

CHRIS2

LAURA!

LAURA3

JENNY3

JENNY!
OBJECT
MODULES

SHEILA

LAURA2
SHEILA
ZK-191-81

Figure 10-8

Sample Files Used in LBR Examples 1-4

10-25

LIBRARIAN UTILITY PROGRAM (LBR)

RICKLIB.OLB;l
JENNYl
JENNY2
JENNY3 1
LAURAl
LAURA2
LAURA3 1
SHEJ:LA
1. These modules did not exist
in the
library file prior to the execution of
this example, but they did exist in 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.
ZK-192-81

Figure 10-9

Output Library File After Execution of Example 1

RICKLIB.OLB;l
CHRIS1
CHRIS2

1
1

JENNYl
JENNY2
LAURAl
LAURA2
SHEILA

1. These modules are inserted.
2. This module is replaced.
Zl<-193-81

Figure 10-10

Output Library File After Execution of Example 2

10-26

LIBRARIAN UTILITY PROGRAM (LBR)

RICKLIB.OLB;l

CHRIS1 1
CHRIS2 1
JENNY!
JENNY2
JENNY3

LAURA!
LAURA2
LAURA3

SHEILA
1. 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.
2. These modules were inserted by default.
ZK-194-81

Figure 10-11

10.5.13

Output Library File After Execution of Example 3

Replace Switch (/RP) for Universal Libraries

Use the /RP switch for universal libraries in the same way as for
macro and object libraries.
However, you can also specify the same
values for the /RP switch as for the /IN switch for universal
libraries {see Section 10.5.9).
As with macro and object libraries, you can specify the /RP switch
with either the output file specification or with the input file
specifications.
The global format of the /RP switch for universal libraries is:
outfile/RP:name:op:op:op:op=infile[,infile2, •••• infilen]
The local format of the /RP switch for universal libraries is:
outfile=infile/RP:name:op:op:op:op[,infile2 •••• infilen]
outf ile
Specifies the universal library file.
infile
Specifies the input file that contains replacement modules for
the library file.
The default for the file type is the value
indicated at the universal library's creation time.
{See Section
10.5.2).

10-27

LIBRARIAN UTILITY PROGRAM (LBR)

/RP
Specifies the Replace switch.

:name
Optionally specifies the module name to be replaced
(up to six
Radix-SO characters). The default is the first six characters of
the inf i l e name.

:op
Specifies optional descriptive information (up to six 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.

Example
LBR>TEXT.ULB=DEBBIE.TXT/RP::THIS:IS:JAN3:UPDATE
MODULE "DEBBIE" REPLACED
In this example, LBR replaces the module DEBBIE in the universal
library TEXT.ULB with an updated module from file DEBBIE.TXT.
The date of replacement is specified by the optional user
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
The resulting library file is shown in Figure 10-13.

OUTPUT
LIBRARY FILE

INPUT FILES

FILE NAME

TEXT.ULB;l

DEBBIE.TXT

MODULES

DEBBIE
BERNIE

10-12.

ZK-195-81

Figure 10-12

Sample Files for Universal Library Replace Example

TEXT.ULB;l
DEBBI El
BERNIE

l.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.
ZK-196-81

Figure 10-13 Output Library File After Execution of
Universal Library Replace Example

10-28

LIBRARIAN UTILITY PROGRAM (LBR)
10.5.14

Spool Switch (/SP)

The Spool switch (/SP) is the list file default switch.
switch is specified or not, the results are the same;
listing file is spooled to the line printer.

Whether the
that is, the

After the listing file is created, a request is made to the print
spooler task to print the spooled file (see the RSX-llM/M-PLUS Batch
and Queue Operations Manual for a description of the spooler task).
The automatic printing of the listing file can be inhibited by
specifying /-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 /SP switch is:
outfile,listfile[/SP] or [/-SP]
outf ile
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:

10.5.15

The module SHEILA and its associated entry
deleted from the library file SY:RICKLIB.

points

are

The listing of the contents of the resulting library file
RICKLIB is written to the list file SY:RICKLST.LST.
Because the /-SP switch is specified, the file is not
automatically printed.

Selective Search Switch (/SS)

Use the Selective Search switch (/SS)
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 with input files for insertion or replacement
operations only, 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
10-29

LIBRARIAN UTILITY PROGRAM (LBR)
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.
The format for specifying the /SS switch is:
outfile=infilel/SS[,infile2[/SS], ••• infilen[/SS]]
outf ile
Specifies the library file.
infile
Specifies the input file that contains modules to be
searched.

selectively

/SS
Specifies the Selective Search switch.
Example
LBR>ANGEL=JOHN,JILL/SS,MARK/SS,MARY
The object files JOHN.OBJ, JILL.OBJ, MARK.OBJ, and MARY.OBJ are
inserted into object library ANGEL.OLB. The selective search
attribute bit is set in both the JILL and MARK object module
header.

10.5.16

Squeeze Switch (/SZ)

Use the Squeeze switch (/SZ) 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
/SZ switch has no effect on object libraries or universal libraries.
The /SZ switch can be specified in either of two formats:
•

Global format - The /SZ switch is appended to the library file
specification.
All of the input files are assumed to contain
modules to be squeezed.

•

Local format - The /SZ switch is appended to an input file
specification. The /SZ switch works only on the file to which
you append it.

Global Format
outfile/SZ=infilel[,infile2, ••• infilen]
outf ile
Specifies the library file.

10-30

LIBRARIAN UTILITY PROGRAM (LBR)
/SZ
Specifies the Squeeze switch.
infile
Specifies the input file that contains modules
during insertion into the library file.

squeezed

Use the global 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 specification.
Local Format
outfile=infilel/SZ[,infile2[/SZ] ••• ,infilen[/SZ]]
outf ile
Specifies the library file.
infile
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

the

If the line contains a semicolon embedded in noncomment text and you
want comments squeezed, code a dummy comment for that line. The /SZ
switch will use only the rightmost comment during squeeze processing.
Example
Figure 10-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.

10-31

LIBRARIAN UTILITY PROGRAM (LBR)

BEFORE
.MACRO

;***

MOVSTR RX,RY,?LBL

- - NOTE :
BOTH ARGUMENTS MUST BE REGISTERS

LBL:

MOVB
BNE
DEC

;MOVE A CHARACTER
;CONTINUE UNTIL NULL SEEN
;BACKUP OUTPUT PTR TO NULL

(RX) +, (RY) +
LBL
RY

;END OF MOVSTR
.ENDM
AFTER
.MACRO

;***
LBL:

MOVSTR RX,RY,?LBL

- - NOTE :
BOTH ARGUMENTS MUST BE REGISTERS
MOVB
(RX)+,(RY)+
BNE
LBL
DEC
RY
.ENDM
ZK-197-81

Figure 10-14 MACRO Listing Before
and After Running LBR with /SZ Switch

10.6

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 line.
Functions are performed in the following order:

1.
2.
3.

4.
5.
6.
7.
8.
9.

Default switch (/DF)
Create switch (/CR)
Delete switch (/DE)
Delete Global switch (/DG}
Modify Header switch (/MH}
Insert (/IN), Replace (/RP), Selective Search (/SS},
(/SZ}, Entry Point (/EP} switches
Compress switch (/CO}
Extract switch (/EX}
List switches (/LI}, /LE, /FU), Spool switch (/SP}

Squeeze

Example
LBR>FILE/DE:XYZ:$A,LP.LST:/LE/FU=MODX,MODY/RP
Functions, performed in order, are:
1.

Delete modules XYZ and $A.

Insert all modules
modules of MODY.

from

10-32

MODX

and

replace

duplicate

LIBRARIAN UTILITY PROGRAM (LBR)
3.

10.7

Produce a listing of the resultant library file on the
line printer with full module descriptions and all entry
points.

LBR ERROR MESSAGES

LBR returns two types of error messages:

diagnostic and fatal.

Diagnostic error messages describe a
condition
consideration, but the nature of the condition
termination of the command. Diagnostic messages are
terminal in the format:
LBR

that
requires
does not warrant
issued to your

*DIAG* - message

Fatal error messages describe a condition 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 your terminal 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 your terminal and LBR
returns to the highest level of command input.

10.7.l

Effect of Fatal Errors on Library Files

The status of a library file after fatal errors is:
1.

In general, output
indeterminate state.

errors

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 insertion process, the library is rewritten after
the insertion of all modules in each individual input file,
that is, between input files.

10-33

leave

the

library

LIBRARIAN UTILITY PROGRAM (LBR)
10.7.2

LBR Error Messages

LBR

BAD LIBRARY HEADER
Explanation:

The file is not a library file or it is corrupted.

User Action:
•

If the file is not a library file, reenter the
with a proper library file specified.

command

•

If the file is a proper library file, you should run the file
structure verification utility (VFY) against the volume to
determine if it is corrupted (see Chapter 9).

•

If the volume is corrupted, it must be
it can be used.

reconstructed

line

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.

LBR -- COMMAND I/O ERROR
Explanation:

One of the following conditions may exist:

•

A problem exists on the physical
cycled up) •

•

The file is corrupted or the format is
example, record length exceeds 132 bytes).

User Action:
Determine which of
message and correct that condition.

device

(for

example,

not

incorrect

(for

the conditions caused the
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 was 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 the
correct file.
If not, reenter the command line, specifying the
correct input file.
If the input file is the correct file, you
can delete the duplicate entry point from the library and reenter
the command line.

10-34

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- DUPLICATE MODULE NAME "name" IN filename
Explanation: An attempt was made to insert (without replacing) 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 with the /RP switch
appended to the input file specification.
LBR -- EPT OR MNT EXCEEDED IN filename
Explanation: The EPT or MNT table limit was reached
execution of an insert or replace operation.

during

the

User Action: Copy the library, increasing the table space
means of the Compress switch. Reenter the command line.

LBR -- EPT OR MNT 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 entries 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 input library file, or more than one
specified when using the /CO switch.

file,

was

User Action:
specified.

input

file

Reenter the command line with only one

LBR -- FATAL COMPRESS ERROR
Explanation: The input library file is corrupted
library file.
User Action: No recovery is possible.
be reconstructed.

10-35

not

The file in question must

LIBRARIAN UTILITY PROGRAM (LBR)
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 {SPR) along with the related
console dialog and any other pertinent information.
LBR -- ILLEGAL DEVICE/VOLUME
command line
Explanation: The Device specifier entered does not conform to
syntax
rules.
A device specifier consists of two ASCII
characters, followed by one or two optional octal digits.
User Action: Reenter the command line with
syntax specified and followed by a colon.

the

correct

device

LBR -- ILLEGAL DIRECTORY
command line
Explanation: The UFD 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 {[ggg,mmm] ).
User Action:
syntax.

Reenter the

command

line

with

the

correct

UFD

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 {SPR) along with the related
console dialog 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.
10-36

the

legal

switch

correct

switch

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- ILLEGAL SWITCH COMBINATION
Explanation:
combination.

Switches were entered that cannot
See Section 10.6.

User Action: Reenter the command line, specifying
in the proper combination.

executed
the

switches

LBR -- INDIRECT COMMAND SYNTAX ERROR
command line
Explanation: An indirect command file was specified in a
that does not conform to syntax rules.
User Action:

format

Reenter the command line with the correct syntax.

LBR -- INDIRECT FILE DEPTH EXCEEDED
command line
Explanation: An attempt was made to exceed one level of indirect
command files.
User Action: Rerun the job
command file specified.

with

only

one

level

indirect

LBR -- INDIRECT FILE OPEN FAILURE
command line
Explanation: The requested indirect command file does not
as specified. One of the following conditions may exist:
•

The user directory area 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 file does not exist as specified.

•

Insufficient dynamic memory exists in the Executive.

User Action:
Determine which of
message and correct that condition.

exist

device

the conditions caused the
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.

10-37

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- INSUFFICIENT DYNAMIC MEMORY TO CONTINUE
Explanation: The partition in which LBR is running is too
for the task size.

small

User Action: Remove the task
(LBR), install it in a larger
partition, and reenter the command line.
(See the MCR INSTALL
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:
spec i f ied.

greater

Reenter the command line

with

than

4096 (10)

the

correct

was
value

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 LIBRARY TYPE SPECIFIED
Explanation: An invalid library type was specified when using
the Create or Default switch. The values OBJ, MAC, and UNI are
the only valid specifications. See Sections 10.5.2 and 10.5.4.
User Action:
specified.

Reenter the command line

with

OBJ,

MAC,

UNI

module

into

LBR -- INVALID MODULE FORMAT in insertion module
Explanation: An attempt was made to insert a macro
an object library.

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 NAME -- "name"
Explantion: A module name that contains a non-Radix-SO character
was specified for deletion, insertion, or replacement of a module
in a universal library or in a macro module; or a module name
was specified for modification of a universal module header.
Radix-SO characters consist of the letters A through z, the
numbers 0 through 9, and the special characters period (.) and
dollar sign ($).
User Action:

Reenter the command line with a valid name.

10-38

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- INVALID OPERATION FOR OBJECT AND MACRO LIBRARIES
Explanation: Module
object
library or
operation.

header information was supplied
macro library in an insert or

User Action: No action required. The command will
as if the information had not been supplied.

for an
replace

executed

LBR -- INVALID RAD50 CHARACTER IN "character string"
Explanation: A character supplied as part of information when
using the Insert, Replace, or Modify Header switches for a
universal library is not a Radix-50 character.
the corresponding
Reenter a Radix-50

User Action: Determine which character of
switch value is not a Radix-50 character.
character in place of the invalid character.
LBR -- I/0 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

the conditions caused the
Reenter the command line.

User Action:
Determine which of
message and correct that condition.
LBR -- LIBRARY FILE SPECIFICATION MISSING

Explanation: A command line was entered without
library file.

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

User Action:
specified.

Reenter the command

line

with

the

LBR -- MARK FOR DELETE FAILURE ON LBR WORK FILE

The work file constitutes a lost file because it does not
in any file directory.
User Action: The file may be deleted by running
structure verification utility (VFY) (see Chapter 9).

the

appear
file

LBR -- MULTIPLE MODULE EXTRACTIONS NOT PERMITTED FOR UNI 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:
extraction.

Reenter

the

command
10-39

line

for

each

additional

LIBRARIAN UTILITY PROGRAM (LBR)
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 or the library file correctly specified.
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,
has detected an error.
One of the following conditions may
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 specified file directory does not exist.

•

The file does not exist as specified.

•

Insufficient contiguous space to allocate
(Compress and Create only) •

•

Insufficient dynamic memory exists in the Executive.

the

device

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 exists in the Executive.

User Action:
Determine which of
message and correct that condition.

10-40

the conditions caused the
Reenter the command line.

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: A positioning error has occurred on the input file.
One of the following conditions exist:
•

A problem exists on the physical device (for example it is not
cycled up) •

•

The file is corrupted or the format is wrong.

the
User Action: Determine which of the conditions caused
message and correct that condition. Reenter the command line.
LBR -- RMS MODULES CANNOT BE EXTRACTED TO RECORD ORIENTED DEVICES
Explanation: An attempt was made to extract a module inserted
from a nonsequential RMS file to a record-oriented device. 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

specified.

LBR

LBR -- TOO MANY OUTPUT FILES SPECIFIED
Explanation: More than two output
makes the following assumptions:

files

were

•

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:
extra file(s)

equal

No action is required.
LBR continues as though the
had not been specified.

10-41

LIBRARIAN UTILITY PROGRAM (LBR)
LBR -- VIRTUAL STORAGE REQUIREMENT EXCEEDS 65536 WORDS
Explanation: This error may occur if you are working with
maximum size libraries and you specify a single command line that
first logically deletes a large number of modules and entry
points, then replaces them with an equally large number of
modules and entry points that have names much different from
those being replaced. 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.
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.

10-42

CHAPTER 11
FILE DUMP UTILITY {DMP)

The File Dump Utility (DMP) enables the user to examine the contents
of a specific file or volume of files.
The output may be formatted in
ASCII, octal, decimal, hexadecimal, or Radix-50 form and dumped to any
suitable output device such as a line printer, terminal, magnetic
tape, DECtape, or disk.
You can dump the header and/or virtual blocks of a file or only the
virtual
records of a file.
If you are dumping a volume, a range of
logical blocks may be specified (see Sections 11.1 and 11.2).
DMP
normally handles blocks of up to 256(10) words in length.
If the
maximum block size exceeds 256(10) words, DMP's buffer size must be
increased as follows:
>RUN $DMP /INC=n
The value of the variable n must be equal to a multiple of 8 that is
equal to or greater than the maximum length block or record minus
256(10) words.
The same restriction applies when dumping records greater than 512(10)
bytes.
In this case, you must increase DMP's buffer size by altering
the DMPBLD.CMD or DMPANSBLD.CMD file as required, then rebuilding the
task.
See the appropriate system generation manual and your system
manager for more specific information on altering various features of
DMP.
You can invoke DMP by using any of the methods described in Chapter 1.
After DMP is invoked, it prompts:
DMP>
DMP is now ready for user input in the form of a command line.
DMP operates in two basic modes: file mode and device mode.
File
mode is used to dump virtual records or virtual blocks, and device
mode is used to dump logical blocks.

11. 1

FILE MODE

In file mode, one input file is specified, and all or a specified
range of virtual blocks are dumped. You can also dump all the virtual
records of a specified file in this mode. The input device must be
either a Files-11 formatted disk or a magnetic tape. The volume must
be mounted using the MCR MOUNT Command.

11-1

FILE DUMP UTILITY (DMP)
NOTE
If the input medium is magnetic tape,
DMP must be built with ANSLIB instead of
SYS LIB.
In file mode, you can specify that data be dumped one record or one
block at a time.
A virtual block or record refers to one block or
record of data in a file.
Virtual blocks and
records are numbered
sequentially from 1 through n, where n is the total number of blocks
or records in the file.
Virtual block 0 contains the header of the
file.
Use the /BL:n:m switch to dump virtual blocks and the /RC
switch to dump virtual records.
The /BL and /RC switches are mutually
exclusive.
(DMP switches are listed in Table 11-1.)

11.2

DEVICE MODE

In device mode, only the input device is specified, and a specified
range of logical blocks is dumped.
The /BL:n:m switch is a required
parameter in this mode.
A logical block refers to a physical 512-byte block on disk or DECtape
and to physical records on magnetic tape or cassette.
Logical blocks
are numbered from 0 to n-1, where n is the total number of logical
blocks on the device.
On RSX-llM, when DMP is in device mode, do not mount the volume.

11.3

DMP COMMAND FORMAT

The command line for DMP is in the following format:
[outf ile] [/sw] [/sw ••• ] =inspec [/sw] [/sw ••• ]
outf ile
Specifies the output file.
If the output file name and file type
are unspecified,
DMP creates the file DMPFIL.DMP.
If the file
type is .DMP, the file will be deleted after it is printed.
TI:
and LP:
(for terminal and line printer) are also acceptable
outfile specifications.
On RSX-llM, if you specify LP:, the file will not
print d~spooler is active.

the

/sw
Specifies one of the switches listed in Table 11-1.
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.
DMP will allow multiple dumps in a single command line.
Therefore, any or all of the current format switches may be

11-2

FILE DUMP UTILITY (DMP)
specified.
Certain switches are mutually
exclusive.
For
example, the /HX, /LW, and /WD switches, are mutually exclusive
hexadecimal dump switches. The first one in the following order
will be the only one executed: /LW, /WD, /HX.
inspec
Specifies the input device and file or input device only.
In
file mode, the equal sign and the input file name and file type
are required because DMP does not provide a default for either of
them.
However, the input file version number defaults to the
latest version and the device defaults to SY:
and the current
UIC.
In device mode, the equal sign and input device are required as
is the /BL:n:m switch which specifies the range of logical blocks
to be dumped.
For a complete description of file specifications, see Chapter 1.

11.4

DMP SWITCHES

DMP switch specifications consist of a slash (/) followed by a switch
name, optionally followed by a value. The value is separated from the
switch by a colon (:). DMP functions are implemented by the switches
described in Table 11-1.
Table 11-1
DMP Switches
Description

Switch
Default

The default is a word mode octal dump,
is spooled to the line printer.

which

/AS

Specifies that the data should be dumped one
byte at a time in ASCII mode. The control
characters (0-37) are printed as a circumflex
(~),
followed by the alphabetic character
corresponding to the character code plus 100.
For example, bell (code 7) is printed as ~G
(code 107). Lowercase characters
(140-177)
are printed as a percent sign (%),followed
by the corresponding uppercase
character
(character code minus 40), unless the /LC
switch is specified. Note that the /AS and
/OCT switches are mutually exclusive when
dumping bytes.

/BA:n:m

Specifies a 2-word base block address
(the
initial base address is O,O), where n is the
high-order base block address (octal), and m
is the low-order base block address (octal).
The address may also be specified in decimal
by using a period after the number. All
future block numbers specified by the /BL
switch will be added to this value to obtain
(continued on next page)

11-3

FILE DUMP UTILITY (DMP)

Table 11-1
(Cont.)
DMP Switches
Description

Switch
/BA:n:m (Cont.)

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.
Once the /BA switch
is specified,
it remains in effect until it
is used again to set a new base address.
When the /BA switch appears in a command
line, no blocks are dumped. The only result
of the command line 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. The values of n and m must not exceed
16 bits.
In file mode only, the /BL switch
is not required.
If the /BL switch is not
specified, DMP will dump all blocks of the
specified file, relative to the current base
address.
If /BL:n:m is specified in file mode,
it
specifies the range of virtual blocks to be
dumped.
If /BL:n:m is specified as /BL:O in
file mode, no virtual blocks are dumped.
This is useful for dumping only the header
portion of the file
(see /HD).
The /BL
switch and the /RC switch are
mutually
exclusive.
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.
The
value
n
represents the block number of the first
(continued on next page)

11-4

FILE DUMP UTILITY (DMP)
Table 11-1
(Cont.)
DMP Switches
Description

Switch
/BL:n:m (Cont.)

block dumped. Successive blocks are labeled
with a block number one higher than the
preceding block number.
The
dump
will
continue until the block labeled m is dumped.

/BY

Specifies that the data be
byte format.

/DC

Specifies that the data be dumped in
word format.

/DENS:n

Specifies the density of an input magnetic
tape with 800, 1600, and 6250 bpi capability,
when DMP is in device mode only.
The value
for n can be 800, 1600, or 6250.

dumped

octal
decimal

DMP does not automatically determine the
density of an input tape.
If the /DENS
switch is not specified in a DMP command
line, 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 and the
RSX-llM/M-PLUS
Command Language Manual for descriptions of
the MOUNT command and its /DENS switch.)
/FI: file-number:
sequence-number

In File Mode, the file number can be used
instead of
a
file
name
as
a
file
specification for input.

/HD[:F or :U]

This switch is an optional parameter used in
File Mode.
If specified, the /HD switch
causes the file header as well as
the
specified or implied portion of the file to
be dumped.
Example:
DMP>TI:=JMF.DAT/HD/BL:5:6
This example dumps the header of JMF.DAT in
header format and virtual blocks 5 and 6 in
octal format.
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
(continued on next page)

11-5

FILE DUMP UTILITY (DMP)
Table 11-1
(Cont.)
DMP Switches
Description

Switch
/HD[:F or :U]
(Cont.)

File headers are described in the
I/O Operations Reference Manual.

IAS/RSX-11

/HF

Specifies the format for data blocks that
have the Files-11 header structure. Other
blocks are output as an unformatted octal
dump.
Example,:
DMP>HEAD.LST=[O,Q]INDEXF.SYS/HF
This example generates a dump of the index
file
INDEXF.SYS and formats all the headers
in the file.

/HX

Specifies that the data
be
dumped
in
hexadecimal
byte
format.
Note that a
hexadecimal dump reads from right to left.
(See also the /LW and /WD switches.)

/ID

Causes DMP's version to be identified.
This
switch may be specified on a command line by
itself at any time.
Example:
DMP>/ID
DMP--DMP VERSION M07.1B
For DMP built with ANSLIB, the response is
DMP--DMP VERSION M07.1B (ANSI)

/LB

Requests logical block information for a
file.
The starting block number and a
contiguous or noncontiguous indication for
the file are displayed.
Example:
DMP>TI:=DKO:RICKSFILE.DAT;3/LB
STARTING BLOCK NUMBER= 0,135163 C
The file RICKSFILE.DAT, version 3,
is a
contiguous file starting at block number
0,135163.
(See /BA:n:m for block number
description.)

/LC

Specifies that the data should be dumped in
lowercase characters.
This switch can only
be used if the output device has lowercase
capability.
(continued on next page)

11-6

FILE DUMP UTILITY (DMP)
Table 11-1
(Cont.)
DMP Switches
Description

Switch

dumped

/LW

Specifies that the data
be
hexadecimal double-word format.

/MD [ :n]

Specifies a memory dump and allows control of
line numbers.
Line numbers are normally
reset to zero whenever a block boundary is
crossed.
The /MD 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
specification.

/OCT

Specifies that the data should be dumped
in
octal format in addition to other formats
specified.
If no DMP format switches are
specified, the default is octal. The /AS
switch and the /OCT switch are mutually
exclusive when dumping bytes.

/RS

Specifies
that
data
Radix-SO-format words.

/RC

Specifies that
time
(rather
data format is
these format
/RS, or /WD.

dumped

data be dumped a record at a
than a block at a time) • The
determined by setting any of
switches: /AS, /DC, /HX, /LW,

The largest record that DMP can process is
limited by the amount of space available to
the DMP task. DMP's task image has Sl2(10)
bytes allocated to it initially. To increase
the amount of space available, use the MCR
INSTALL command /INC switch.
For example, to
dump a file with 1024-byte records, you must
specify /INC=2S6.
(at least).
If the input
is a tape and the block size is greater than
Sl2
bytes,
$FSR1
must be expanded as
described in the DMPBLD.CMD or DMPANSBLD.CMD
file.
The /RC switch and
mutually exclusive.
/RW

the

/BL

switch

are

Causes DMP to issue a rewind command before
referencing a specified tape. This switch
may be specified at any time to reposition a
tape at the beginning-of-tape (BOT).
(continued on next page)

11-7

FILE DUMP UTILITY (DMP)
Table 11-1
(Cont.)
DMP Switches
Description

Switch
/SB:n
or
/SB:-n

Specifies the number of blocks DMP spaces
forward (n)
or backward
(-n)
on tape. DMP
stops when it senses end-of-tape (EQT).
DMP
will space only single blocks beyond EQT.

/SF:n
or
/SF:-n

Specifies the number of end-of-file
(EOF)
marks DMP spaces forward (n) or backward (-n)
on tape. DMP stops when it senses EQT or
BOT.
DMP will space only single EOF marks
beyond EQT.

/SP

Causes the dump output file to be spooled to
the line printer. The /SP switch 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.

11.5

dumped

DMP EXAMPLES

Three examples of dump listings are included in this section to
illustrate how the various DMP switches can be used.
DMP edits blocks
or records 16(10) bytes at a time. The dump includes the indicated
number of valid bytes in the block or record. The remaining number of
bytes are listed as null bytes (0).

11.5.1

A Multiple Format Dump

The command line shown in Example 11-1 dumps virtual blocks 5 and 6 of
DSC.MAC in hexadecimal, Radix-50, and decimal format.
Each line of
the output file will appear in three different formats.

11-8

FILE DUMP UTILITY (DMP)
Example 11-1 Dumping Virtual Blocks in Hexadecimal,
Radix-SO, and Decimal Format
DMP>DOC.DMP=C301,357JDSC.MAC/HX/R5/DC/BL:5:6

The contents of DOC.DMP are:
DUMP OF DB0:(301,357JDSC.MAC;1 - FILE ID 17725,11,0
VIRTUAL BLOCK o,000005 - SIZE 512. BYTES
4E 41 4D 4D 4F 43 20 41 20 3B 00 1E 53 45 52 49
0000
;Hexadecimal
000000
MFY ML7
0 EFK EFQ L$K LN/ LT3
iRadix-50
o. 21065. 21317. 00030. 08251. 08257. 20291. 19789. 20033.;Decimal
53 45 53 53 45 43 4F 52 50 20 44 4E 41 20 2C 44
0010
000020
GCL JP2 J7F L22 L$Z KCK MMK ML7
16. 11332. 16672. 17486. 20512. 20306. 17731. 21331. 21317.
53 52 49 46 20 3B 00 39 00 3B 00 01 2E 54 49 20

0020

DUMP OF DBO:C301,357JDSC.MAC;1 - FILE ID 17725,lltO
VIRTUAL BLOCK o,000006 - SIZE 512. BYTES
20 44 4E 46 55 42 24 20 51 45 20 30 52 20 46 49
0000
000000
KI3 MEX EF M E ElH MYZ LT8 EFT
o. 17993. 21024. 08240. 20805. 09248. 21826+ 20038. 08260.
44 4E 45 09 00 09 50 4F 4F 4C 20 45 56 41 45 4C
0010
000020
KCT M2A EFU L$T L39
I KA3 J7F
16. 17740. 22081. 08261. 20300. 20559. 00009+ 17673. 17486.
54 53 24 20 54 45 4C 09 00 2B 00 50 4F 4F 4C 20

11-9

0020

FILE DUMP UTILITY (DMP)
11.5.2

A Record Dump

The command line shown in Example 11-2 dumps all of
records of YACHT.SEQ in ASCII and decimal word format.

the

virtual

Example 11-2 Dumping Virtual Records in ASCII and Decimal Word Format
DMP>REC.DMP=C301,357JYACHT.SEQ/RC/AS/DC

The contents of REC.DMP are:
DUMP OF DBO:C7,337JYACHT.SEQ;1 - FILE ID 15451,35,0
RECORD NUMBER 01. - SIZE 41. BYTES
000000

A L

M K

19521. 17730. 18258. 08224. 08224. 14131. 19744. 08267.

000020
16.

I
I
K E T C H
3
7
2 0 0
18761. 08224. 17739. 17236. 08264. 14131. 12832. 12336.

000040
32.

0 0 1 2 3 6 9 5 1 "'@ "'@ "'@ "'@ "'@ "'@ ~@
12336. 12849. 13875. 13625+ 00049. 00000. 00000. 00000.
RECORD NUMBER 02. - SIZE 41. BYTES

000000

A
N
7 9
L B I
19521. 18754. 08270. 08224+ 08224. 14647. 08224. 08224.

000020
16.

s L 0 0 p
2 6
0 4 2
08224. 08224. 19539. 20303. 08272. 13874. 12320+ 12852.

000040
32.

0 0 1 0 1 7 9 0 0 "'@ "'@ "'@ "'@ "'@ "'@ '"'@
12336. 12337. 14129. 12345+ 00048. 00000. 00000. 00000.

11.5.3

A Header Dump

The command line shown in
DSC.MAC.

Example

11-3

11-10

dumps

only

the

header

FILE DUMP UTILITY (DMP)

Example 11-3 Dumping the File Header of a File
DMP>DHR.DMP=[301,357JDSC.MAC/HD/BL:o

The contents of DHR.DMP are:
DUMP OF DB0:[301,357JDSC.MAC;1 - FILE ID 17725,11,0

FILE HEADER
HEADER AREA
H. I DOF

027

H.MPOF
H.FNUM,
H+fSEQ

05b

<17725,11)
401
[301,357J

H+FLEV

H+FOWN
H.FPRO
H.UCHA
H.SCHA
H.UFAT

[RWED,RWED1RWED1RJ
000=
000
F. RTYF'
F. RATT
F.RSIZ

F.HIBK
F+EFBK
F.FFBY
rnEST>

=
002 = R.VAR
002 =
FD.CR
116

= 78.

H: 0 U 000040
H:O U000040
532

= 32.
32.

= 346.

000000 000000 000000 000000 000000 000000 000000 000000
000000

IDENTIFICATION AREA
l+FNAM,
I+FTYP,

I+FVER
I.RVNO
I+RVDT

DSC

.MAC;1

13-0CT-BO
09:52:46
13-0CT-BO

I. RVTI

I.CRDT
I. CRTI

I.EXDT
MAP AREA
M+ESQN
M.ERVN
M.EFNU,
M+EFSQ
M.CTSZ
M.LBSZ
M.USE
M.MAX

000
000

(0,0)
001
003
014 = 12.
314
204.

M+RTRV

SIZE

LBN

11.

H:ooo U036215 = 15501.
H:ooo L:036235 = 15517.
H:ooo L:036250 = 15528.
H:ooo u 036272 = 15546.
H:ooo u 036313 = 15563.
H:ooo U036411 = 15625+

CHECKSUM
H.CKSM

122620

12.
3.
1.

2.
3.

11-11

FILE DUMP UTILITY (DMP)
11.6

DMP ERROR MESSAGES

DMP -- BAD DEVICE NAME
Explanation: An incorrect device name
specification.

was

entered

User Action:
device.

specifying

the

correct

Reenter the command

line

file

DMP -- BLOCK SWITCH REQUIRED IN LOGICAL BLOCK MODE
Explanation:

Self-explanatory (/BL must be specified.)

User Action:

Reenter the command line specifying the /BL switch.

DMP -- CANNOT FIND INPUT FILE
Explanation: The requested
specified directory.

file

cannot

User Action: Reenter the command
file name and UFO.

line

located

specifying

the

correct

DMP -- COMMAND SYNTAX ERROR
Explanation: A command line was entered in a
not conform to syntax rules.
User Action:
syntax.

Reenter the command

format

that

line

specifying

the

device

was

entered

Reenter the command

line

specifying

the

does

correct

DMP -- FAILED TO ASSIGN LUN
Explanation: An
specification.
User Action:
device.

illegal

file
correct

DMP -- FAILED TO READ ATTRIBUTES
Explanation: A file was specified for which
read access privileges.
User Action: Rerun DMP
privileges to the file.

under

UIC

that

you
has

did

not

read

have
access

DMP -- ILLEGAL DENSITY VALUE
Explanation: A value other than 800,
specified with the DMP /DENS switch.
User Action:

1600,

6250

bpi

was

Reenter the /DENS switch with the proper value.

DMP -- ILLEGAL SWITCH
Explanation: A switch was specified that is not a valid
switch, or a legal switch was used in an invalid manner.
User Action:
switch.

Reenter the command

11-12

line

specifying

the

DMP

correct

FILE DUMP UTILITY (DMP}
DMP -- ILLEGAL USE OF /RC SWITCH
Explanation: The /RC switch can be used only in file
Sect i on 11. 1) •
User Action:

mode

(see

Reenter the command line specifying a file name.

DMP -- ILLEGAL VALUE ON HD SWITCH
Explanation:
switch.

An option was entered other than F or U for the /HD

User Action:
option.

Reenter the command

line

specifying

the

correct

DMP -- I/O ERROR ON INPUT FILE
or
DMP -- I/O ERROR ON OUTPUT FILE
Explanation:

One of the following conditions exists:

•

A problem exists on the physical
device cycled down) •

device

(for

example,

•

The file is corrupted or the format is incorrect.

•

The output volume is full.

User Action:
Determine which condition caused the
correct that condition.
Reenter the command line.

the

message

and

input

file

DMP -- NO INPUT FILE SPECIFIED
Explanation: A command line
specification.
User Action:

was

entered

with

Reenter the command line specifying an input file.

DMP -- NO LISTS OR WILD CARDS ALLOWED
Explanation: Either a command line 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, specifying only one input
file
specification and one output file specification.
No
wildcard specifications are allowed.
DMP -- OPEN FAILURE ON INDIRECT FILE
Explanation: The requested indirect command file does not
as specified. One of the following conditions exists:
•

The file is protected against access.

•

A problem exists on the physical
device cycled down) •

•

The volume is not mounted.

11-13

device

(for

example,

exist

the

FILE DUMP UTILITY (DMP)
•

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.

message

and

example,

the

DMP -- OPEN FAILURE ON INPUT FILE
or
DMP -- OPEN FAILURE ON OUTPUT FILE
Explanation:

One of the following conditions exists:

•

The file is protected against access.

•

A problem exists on the physical
device cycled down).

•

The named file does not exist in the specified directory.

•

The volume is not mounted.

•

The specified file directory does not exist.

device

(for

User Action:
Determine which condition caused the
correct that condition. Reenter the command line.

11-14

message

and

CHAPTER 12
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, 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 Source Language
Input Program utility
(SLP).
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 13.)

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 specify
the number of lines required for CMP to consider that a match has been
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 in the
command line. The defaults are:

SYO:
[current UIC]
FI LC OM
.LST

The user's default system device
The UIC that CMP is running under
The default file name
The default file type

However, if you do not specify an output
defaults to your terminal.
For example:
CMP>FILE1.MAC,FILE2.MAC

12-1

file,

the

output

THE FILE COMPARE UTILITY (CMP)
CMP lists the differences between FILEl.MAC and FILE2.MAC on your
terminal.
If you type the equal sign but give no output file
specification, only the total number of differences is output to
your terminal. For example:
CMP>=FILE1.MAC;l,FILE2.MAC;l
10 differences found

/sw •••
Switches that you apply to the output file specification.
Some
of the switches can be negated and some are mutually exclusive.
Section 12.1 contains this information.
infilel
The file specification for the
inf ile2.
The file name of
default file type is .MAC.

input file to be compared to
this file must be specified. The

infile2
The file specification for the input file to be compared to
infilel.
You do not have to have a complete file specification.
The specifications for infilel are used as defaults for any
unspecified portions of infile2.
For example:
CMP> DB2: (42,lO]EXEC,;2
CMP interprets the second input file as DB2: [42,10]EXEC.MAC;2.
If you do not specify a file version number, the default is
recent version of the file.
You can invoke CMP using any of the methods
described in Chapter 1.

12.1

for

invoking

the
a

most

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
after the output file in 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 switch.

/CB
/-CB

Specifies that CMP list infile2 with change bars, in the
form of exclamation marks (!), to denote which lines do not
have a corresponding line in infilel. When a section of
lines in infilel has been deleted in infile2
(the output
listing file),
the first line not deleted is marked. /-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 later.

/CO
/-CO

Specifies that CMP include comments (that is, text preceded
by a semicolon) in compare processing. /CO is the default
switch.
12-2

THE FILE COMPARE UTILITY (CMP)
/DI
/-DI

Specifies that CMP list
the differences between the two
files (rather than marking the lines in infile2).
/DI is
the default 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 switch.

/LI:n

Specifies that a number
(n)
of lines must be identical
before CMP recognizes a match. /LI:3 is the default switch.
When it encounters a match, CMP lists 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, /LN is unnecessary.

/MB
/-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 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 inf ilel identical to
infile2.
If a 1- to 8-character alphanumeric symbol is
included after the /SL switch
(:au), an audit trail is
specified for SLP input.
Section 12.2.3, gives an example
of how CMP generates SLP command input.
(For information on
how SLP processes source files, refer to Chapter 13.) /-SL
is the default switch.

/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
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 switch.

/VB:nnn

Specifies an octal character code for the character you want
to 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:l74 for a vertical bar (if
your printer is capable of printing the vertical bar
character).
/VB:041 for an exclamation mark is the default
switch.

CMP default switch settings are listed in Table 12-1.

12-3

THE FILE COMPARE UTILITY (CMP)
Table 12-1
Summary of CMP Default Switch Settings
/-BL
/-CB
/CO
/DI
/-FF
/LI:3
/LN
/MB
/-SL
/-SP
/TB
/VB:041

12.2

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

FORMATS OF CMP OUTPUT FILES

CMP uses the two input files you specify on the command line to
create an output file.
CMP compares each line in infilel to its
sequential counterpart in inf ile2.
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 the
examples in the subsequent sections, the following files are used as
infilel (TESTl.DAT;l) and infile2 {TEST2.DAT;l):
DBO: [7,7]TEST1.DAT;l

DB0:[7,7]TEST2.DAT;l

LINEl
LINE2
LINE3
LINE4
LINES
1234S
234S6
3 4S67
LINE9
LINElO
LINEll
EXTRA

LINEl
LINE2
LINE3
LINE4
LINES
4S678
S6789
67891
LINE9
LINElO
LINEll
EXTRA
EXTRA
EXTRA
EXTRA

12-4

THE FILE COMPARE UTILITY {CMP)
12.2.1

Differences Format

If you enter a command line and do not specify any switches, CMP lists
the differences between the two files on your terminal or in an output
file.
The differences are listed in pairs;
first,
the lines from
infilel that do not have counterparts in infile2 are listed, then the
lines from infile2 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 format of output generated without any
switches. The output file is generated with the CMP command:
CMP>TESTDIF.DAT=TEST1.DAT,TEST2.DAT

*********************************************
1)

DB 0 : [ 7 , 7 ] TEST 1. DAT ; 1
12345
23456
34567
LINE9

6
7
8
9

*****************
2)

DBO: [7,7]TEST2.DAT;l
45678
56789
67891
LINE9

6
7
8
9

*********************************************
1)

DB 0 : [ 7 , 7] TEST 1. DAT ; 1

*****************
2)

13
14
15

DBO: [7,7]TEST2.DAT;l
EXTRA
EXTRA
EXTRA

2 differences found
The input files are TESTl.DAT and TEST2.DAT, which are shown in
Section 12.2.
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 a long line of asterisks.) The
short line of asterisks separates the pair of differences that
comprise the set.
Note that because /LI:n was not specified, the number of lines
Thus, CMP found two differences.
required for a match defaults to 3.

12.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 the format of output with change bars
applied to lines from two files that do not match line for line. The
output file is generated with the CMP command:
CMP>TESTDIF.DAT/CB=TEST1.DAT,TEST2.DAT
Notice that the change bar is applied to the first line of match (line
9) •

12-5

THE FILE COMPARE UTILITY (CMP)
1
2

3
4

5
6
7
8
9
10
11

12
13
14
15

LINEl
LINE2
LINE3
LINE4
LINES
45678
56789
67891
LINE9
LINElO
LINEll
EXTRA
EXTRA
EXTRA
EXTRA

2 differences found

12.2.3

SLP Command Input Format

You 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 infilel 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 13 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

CMP>TESTDIF.DAT/SL:BLSOOl=TESTl.DAT,TEST2.DAT
-6, 8, /; BLSOOl/
45678
56789
67891
-1 2' ' I ; B LS 001 I
EXTRA
EXTRA
EXTRA

12.3

CMP MESSAGES

This section lists the CMP messages, gives a brief description of the
condition that causes each message, and suggests a response to the
condition.
CMP -- n differences found
Explanation:

CMP found n differences between the two files.

User Action:

This is an informational message.

12-6

THE FILE COMPARE UTILITY (CMP)
CMP

Command syntax error
Explanation:

CMP found an error in the command line syntax.

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

while

User Action:

Reenter the command line.

CMP

was

reading

CMP

was

writing

the

Check

this,

CMP -- Error writing output file
Explanation:
output file.

An I/O error occurred while

User Action: The output device may be full or bad.
then reenter the command line.
CMP -- Illegal /LI value
Explanation: You specified a negative value for
lines required for a match.

the

User Action:
specified.

with

legal

Explanation: An illegal switch or switch value
the command line.

was

entered

User Action: Reenter the command line using a
switch value.

legal

switch

Reenter

the

command

line

number

value

CMP -- Illegal switch or switch value

CMP -- Open failure on input file #1
Explanation:

CMP could not open the first input file.

User Action: Check the file specification for first input
and
reenter
the
command
line
using
the correct
specification.

file
file

CMP -- Open failure on input file #2
Explanation:

CMP could not open the second input file.

User Action: Check the file specification for second input
and
reenter
the
command
line
using
the correct
specification.

12-7

file
file

THE FILE COMPARE UTILITY {CMP)
CMP -- Open failure on output file
Explanation:

CMP could not open the specified output file.

User Action: Check the file specification for the output
and
reenter
the
command
line
using
the correct
specification.

file
file

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 description of the INSTALL command in the
RSX-llM/M-PLUS MCR Operations Manual.)

12-8

CHAPTER 13

SOURCE LANGUAGE INPUT PROGRAM (SLP)

The Source Language Input Program (SLP) is a utility used to maintain
and audit source files.
The optional audit trail in the output files
allows you to keep a record of maintenance changes.
SLP is invoked by edit command statements
command statements allow you to:

and

switches.

SLP

•

Update (delete, replace, add) lines in an existing file

•

Create source files

•

Run indirect files containing SLP edit commands

edit

Input to SLP is a 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 line numbers or character strings that you specify. Command
input can come directly from your terminal or from an indirect command
file containing commands and text lines to be inserted into the file.
SLP accepts data from any Files-11 volume.
Output from SLP is a listing file and the updated
input file.
SLP
provides an optional audit trail that helps you keep track of the
update status of each line in the file.
If an audit trail
is not
suppressed, it is shown in the listing file and permanently applied to
the output file.
You can control SLP processing
switches allow you to:

with

SLP

control

switches.

These

•

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

•

Spool files to a Files-11 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 f ilespec
Also, you should not specify TI: as your output file, because when
you finish editing, you will not have a copy of the output file and
the input file will be the same as before you began editing.
13-1

SOURCE LANGUAGE INPUT PROGRAM (SLP)
13.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 made
to the file.

13.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, these changes are noted in the output files.

13.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, where the first
line entered must be the command line defining the files to be
processed.
When SLP accepts this 1 ine, it initializes the files you
want processed. Once these files are initialized, SLP enters edit
mode, where 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, ,/;BJ007/
CMP {Rl) +I B
-4,4
DEC R2
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 8(10);
no more than 14(10) characters may be
specified.
(See Section 13.4.2 for more
information about the audit trail.)

13-2

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The first line is the command line, where you define the output file,
the listing file,
and the input file.
The next four lines comprise
the SLP edit commands and input lines.
Note that the input and output files in the example 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 command line. Wildcards cannot be
used in any of the file specifications.
You can also calculate the checksum
Specify the checksum switch with
specification in the format:

value for the edit commands.
either the input or output file

/CS[:n]
The checksum value can be calculated for all SLP edit command
The checksum value cannot be calculated for the following:
•

The command line specifying the input and output files

•

Comments in the edit command lines

lines.

Any spaces and/or tabs between characters included
in the
• 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 the first character of the
last audit trail string before the current 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 in Section 13.5.2)

13.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 this chapter contain samples of listing files.

13.1.4

The SLP Output File

The SLP output file is the updated input file.
All of the updates
specified by 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.

13-3

SOURCE LANGUAGE INPUT PROGRAM (SLP)
13.2

HOW SLP PROCESSES FILES

Figure 13-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
CMP (Rl)+,B
-4,4
DEC (R2)

I
Input File

Listing File

MYFILE.MAC;1

MYFI LE.LST;1

SLP
Processor

Command Input
From Primary
Input Device

From Indirect File
INFI LE.SLP;1

@U
or

Output File

MYFILE.MAC;2

ZK-198-81

Figure 13-1

Input Files and Output Files Used During SLP Processing

This is the input file (MYFILE.MAC;l) before SLP processes the files:
MOV
MOV
CALL
TST
BEQ
CLR
MOV
CMPB
BNE
INC

#BUFl,RO
#S IZ I Rl
READ
R2
END
Rl
R2, NUMC
(RO)+,A
20$
Rl

13-4

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The following is the listing file
processing of these files:
1.
2.
3.

4.
5.

6.
7.
8.
9.
10.
11.

MOV
MOV
CALL
CMP
DEC
BEQ
CLR
MOV
CMPB
BNE
INC

#BUF 1, RO
#S IZ, Rl
READ
(Rl) +, B
(R2)
END
Rl
R2, NUMC
(RO)+,A
20$
Rl

(MYFILE.LST;l)

resulting

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 Figure 13-1, SLP processes an 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 modifies the line, notes the change by means of the audit
trail,
and then continues writing lines to the output file until
another command is encountered or until end-of-file is reached.

13.3

USING SLP

This section describes how to:
•

Specify the SLP edit commands

•

Update files using the SLP edit commands

•

Enter SLP commands interactively
command files

•

Create a source file using SLP

13.3.1

and

means

indirect

Specifying SLP Edit Commands

The SLP edit commands allow you to update source files by adding,
deleting, and
replacing lines in a file.
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. You enter SLP
edit commands after invoking SLP and specifying an edit command line.
The general format of the SLP edit command line is as follows:
-[locatorl] [,locator2] [,/audittrail/] [; comment]
inputline

13-5

SOURCE LANGUAGE INPUT PROGRAM (SLP)
- {dash)
Identifies a SLP edit command line.
locatorl
A line locator that causes SLP to move the current line pointer
to a specified line. If you specify only locatorl, 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 later in this section.
locator2
A line locator that defines a range of lines (that is, the range
beginning with locatorl and ending with locator2, inclusive) to
be deleted or replaced. This field can be specified using any of
the locator forms described later in this section.
/audittrail/
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
default 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]
string
A string of ASCII characters. SLP locates the line where the
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 where the two character strings delimit a larger
character string abbreviated by an ellipsis ( ••• ).
number
A decimal line number where the current line pointer is to be
moved. The largest line number that can be specified is 9999.

13-6

SOURCE LANGUAGE INPUT PROGRAM (SLP)
• {period)
The current line.
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.
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 lines.

13.3.2

the

Entering SLP Edit Commands

Once you have invoked SLP, you can enter SLP
edit
commands
interactively or by specifying indirect command files.
In both cases,
the first command you must enter is the command line defining the
files to be processed during this SLP session. This section gives
examples of how to use both methods of entering SLP commands.
The following file (BASE.MAC;l) is used as
examples in this section:
MOV
CLR
CLR
CLR
MOV
MOV
MOV
CLR
DEC
BNE

the

input

file

for

the

i$SWTCH, R3
$ERFLG
$CRCVL
$CSSV
SPSAV, SP
i$CFNMB,RO
i<$HDSIZ-$CFNMB>/2+1,Rl
(RO)+
Rl
5$

13.3.2.1 Entering SLP Commands Interactively - To alter the example
file
interactively, first invoke SLP by using any method described in
Chapter 1 (except >SLP f ilespec).
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 command line
defining the files you want processed during this session:
BASE.MAC;2/AU:48./TR,BASE.LST=BASE.MAC;l

13-7

SOURCE LANGUAGE INPUT PROGRAM (SLP)
Then you enter the edit commands and input lines:
-3
TST
Rl
-4,4
BEQ
10$
-6 , , I ; JM o1 oI
CLR
R2

I
In this example, the edit commands instruct SLP to do the following:
-3
inserts a new line after line 3;
-4,4 deletes line 4 and replaces
it with a new line;
-6,,/;JMOlO/ inserts a line after line 6 with a
new audit trail value.
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
file and begin another editing session.

enter

another

input

The listing file (BASE.LST;l) resulting from SLP processing appears as
follows:
1.
2.
3.

4.
5.
6.

7.
8?
9.
10.
11.
12.

MOV
CLR
CLR
TST
BEQ
MOV
MOV
CLR
MOV
CLR
DEC
BNE

#$SWTCH, R3
$ERFLG
$CRCVL
Rl
10$
SPSAV, SP
#$CFNMB,RO
R2
#<$HDSIZ-$CFNMB>/2+1,Rl
(RO)+
Rl
5$

;**NEW**
; **NEW**
;**-1
; JMOlO

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 (.) after the line number for 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.

13.3.2.2 Entering SLP Commands Using Indirect Command Files - To
alter the example file by using the SLP edit commands in the indirect
command file, BASE.SLP, you invoke SLP and SLP responds with the
prompt:
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

13-8

SOURCE LANGUAGE INPUT PROGRAM (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
interactively.
Indirect command files can be nested to a maximum level of
This permits indirect command files to reference a text file.

three.

13.3.2.3 Using SLP Operators - In addition, you can enter special
characters called operators, which perform specific functions. Table
13-1 lists the operators and the function each performs.
Enter
operators, in edit mode, as the first character of an input line.
Table 13-1
SLP Operators
Function

Operator

Identifies the first character of a SLP edit
line.

13.3.3

command

Suppresses audit-trail processing.

Reenables audit-trail processing.

Invokes an indirect command file for SLP processing.

Terminates the SLP edit session, and then returns
SLP command mode.

Enables 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.
This character can be used with all SLP
operators.

Updating Source Files With 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.

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

13-9

line
they

SOURCE LANGUAGE INPUT PROGRAM (SLP)

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:
,listfile=infile

I
In this format, listfile is the name you assign to the listing file
SLP will produce and infile is the name of the input file whose lines
are to be numbered.
The slash (/) terminates edit mode.
For example,
suppose the input file is:
MOV

Rl,-(SP)
#177770,@SP
#60,@SP
(SP)+,-(RO)
Rl
Rl
Rl
R2
30$
#MSG,RO

BIC

ADD
MOVB
ASR
ASR
ASR
DEC

BNE
MOV

SLP processes each
file;l):
1.
2.

MOV

3.
4.
5.

ADD
MOVB
ASR
ASR
ASR

6.
7.

BIC

DEC

9.
10.

BNE
MOV

line

generate

numbered

list

file

(list

Rl,-(SP)
#177770,@SP
#60,@SP
(SP)+,-(RO)
Rl
Rl
Rl
R2
30$
#MSG, RO

13.3.3.2 Adding Lines to a File - The three SLP edit command
for adding lines to a file are:
-locator!
inputline

or
-locator!,,
inputline

or
locatorl,,/audittrail/
inputline

13-10

formats

SOURCE LANGUAGE INPUT PROGRAM (SLP)

The following example shows how to add lines to a file.
input consists of the following lines:

The

command

MYFILE.MAC;2/AU:48. :10./TR,MYFILE.LST/-SP=MYFILE.MAC;l
-3
CMP
(Rl)+,B
-4, 4
DEC
R2
-6,, ,/;JMOlO/
INC
R3
-9, ,/;BJ008/
BEQ
10$

I
The next example uses text rather than line numbers to indicate
new lines should be added or deleted:

where

MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;l
-/BEQ/
CALL
WRITE

I
In this example, the edit command /BEQ/ instructs SLP to insert a line
after the line with the first occurrence of BEQ.
SLP processing generates the following listing file (MYFILE.LST;l):
1.

2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

MOV
MOV
CALL
TST
BEQ
CALL
CLR
MOV
CMPB
BNE
INC

#BUF 1, RO
#S IZ, Rl
READ
R2
END
WRITE
Rl
R2, NUMC
(RO)+,A
20$
Rl

;**NEW**

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
BEQ.
The next example uses the
command lines:

same

input

file

and

the

following

MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;l
-/#SIZ/+2
CMP
(Rl)+,B

I
SLP processing generates the following listing file (MYFILE;l):
1.

2.
3.
4.
5.
6.
7.

8.
9.

10.
11.

MOV
MOV
CALL
TST
CMP
BEQ
CLR
MOV
CMPB
BNE
INC

#BUF 1, RO
#S IZ, Rl
READ
R2
(Rl)+,B
END
Rl
R2, NUMC
(RO)+,A
20$
Rl

;**NEW**

13-11

new

SOURCE LANGUAGE INPUT PROGRAM (SLP)

Again, SLP has numbered the lines and this time the new input line is
inserted so that it is two lines beyond the line containing the first
occurrence of the string /#SIZ/.

13.3.3.3 Deleting Lines from a File - The SLP edit command format for
deleting lines from a file is:
-[locatorl], [locator2], [/audittrail/] [; comment]
In this format, locatorl and locator2 can be any of the forms of the
locator fields described
in Section 13.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
input file consists of the following lines:
MOV
MOV
CALL
TST
BEQ
CLR
MOV
CMPB
BNE
INC

from

file.

The

#BUFl, RO
#S IZ, Rl
READ
R2
END
Rl
R2, NUMC
(RO)+,A
20$

The command input consists of the following commands and text lines:
MYFILE.MAC;2/AU:SO,MYFILE.LST=MYFILE.MAC;l
-/MOV ••• Rl/,/NUMC/

I
SLP processing generates the following listing file (MYFILE;l):

1.
2.
3.

MOV
CMPB
BNE

#BUFl,RO
(RO)+,A

INC

20$

;**-6

In this example, the ellipsis ( ••• ) abbreviates the larger string MOV
#SIZ,Rl.
Assuming the two strings bracket a larger string, SLP
searches for the first occurrence of the string MOV and then the first
occurrence on the same line of the string Rl, in thts case the string
MOV #SIZ,Rl.
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 NUMC.
SLP applies the audit-trail count
of the lines it deleted to the next line from the input file.
Using the same input file as used in the previous example, the
following example shows how to delete a single line using the period
locator. The command input for this example is:
MYFILE.MAC;2/AU:SO,MYFILE.LST=MYFILE.MAC;l
-/MOV #S IZ, Rl/,.

13-12

SOURCE LANGUAGE INPUT PROGRAM {SLP)
SLP processing generates the following listing file
1.
2.
3.
4.
5.
6.

7.
8.

MOV
CALL
TST
BEQ
CLR
MOV
CMPB
BNE
INC

#BUF 1, RO
READ
R2
END
Rl
R2, NUMC
(RO)+,A
20$
Rl

(MYFILE;l):

;**-1

SLP moves the current line pointer to the line containing the string
MOV #SIZ,Rl 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.

13.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
deleted 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.

and

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:
MOV
MOV
CALL
TST
BEQ
CLR
MOV

#BUF 1, RO
#S IZ, Rl
READ
R2
END
Rl
R2, NUMC

The command input is:
MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;l
-2,. +l
CMP
(Rl)+,B
INC
R2

I
In this example, the edit command, -2,.+l,
lines 2 and 3 and insert two new lines.

instructs

SLP

SLP processing generates the following listing file (LISTING;l):

1.
2.

MOV
CMP

INC

4.
5.
6.
7.

TST
BEQ
CLR
MOV

#BUF 1, RO
(Rl)+,B
R2
R2

;**NEW**
; **NEW**
;**-2

END
Rl
R2, NUMC
13-13

delete

SOURCE IANGUAGE INPUT PROGRAM (SLP)
13.3.4

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. An interactive editor, such as EDI or
EDT, is 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]]
outf ile
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).
default device is implied by the output file specification.

The

primary input device:
Specifies that input for the file being created is coming from
this device, for example, a terminal. The default device is your
primary input device.
/SW

Specifies any optional SLP switches.
The following file specification creates a new file called
from the terminal and puts it on SYO:.

MYFILE.MAC

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.

13.4

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 listing
file and the output file.

13.4.l

SLP Switches

SLP output consists of two files -- a listing file and the output
file, which is the modified version of the input file.
You can use
the SLP switches to control the audit trail and print options
associated with the two files.
13-14

SOURCE LANGUAGE INPUT PROGRAM (SLP)

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 13-2 lists the SLP
switches and gives a brief description of the functions each performs.
Table 13-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 trail. /AU is the
default value. See the following sections for more
information about the /AU switch.

/BF
/-BF

Positions 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.
See Section 13.4.6 for more information
about the /CM 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.
The procedure SLP uses to
calculate the checksum value for the edit commands is
described in Section 13.1.2.

/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.
(continued on next page)

13-15

SOURCE LANGUAGE INPUT PROGRAM (SLP)
Table 13-2 (Cont.)
SLP Switches
Switch
/SQ

Function
Sequences the lines in the output file so that the
numbers reflect the line numbers of the original
input file. New lines added to the file have the
same number as the preceding line. This allows the
MACRO Relocatable Assembler to output listing files
that contain the original line numbers, thus easing
the process of updating correction files.
If you specify a listing file, SLP preserves the line
numbers of the input file but does not display
numbers for the new lines that have been inserted.

/RS

Resequences the lines in the output file so that the
line numbers are incremented for each line written to
the output file. The /RS switch overrides the /SQ
switch.

/NS

Does not sequence the lines in the output file.
New
lines
are
indicated
by
the audit trail
(if
specified). The /NS switch is the default condition
and overrides the /SQ and /RS switches.

13.4.2

Controlling the Audit Trail

The /AU switch allows you to generate, suppress, and set the length
and contents of the audit trail. To suppress generation of the audit
trail, specify the /-AU switch in either the input or output file
specification.
For example, either of the following command lines generates an output
file with no audit trail:
DKl:MYFILE.MAC;3/-AU,LP.LST:=MYFILE.MAC;2
DKl:MYFILE.MAC;3,LP.LST:=MYFILE.MAC;2/-AU

LP.LST will be spooled automatically.
By default, SLP automatically generates an audit trail; that is, you
need not explicitly specify the /AU switch in your command line
(unless you want to specify the beginning position and length of the
a ud i t tr a i1 ) •

13-16

SOURCE IANGUAGE INPUT PROGRAM (SLP)
13.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).
NO'fE
Numeric values given for switches default to octal.
De~imal
values must be followed by a period (.). The
default position for the audit trail is 80(10)
and its
default length is 8(10); no more than 14(10) characters
may be specified.
(See Section
13.4.2
for
more
information about the audit trail.)
length
The default value for length
than 14(10)
characters may

is
be

The following example shows how to specify the beginning position
length of the audit trail. The input file for this example is:

and

The length of the audit trail.
8 (10)
characters;
no more
specified.

MOV
MOV
CALL
TST
BEQ

#BUF 1, RO
#S IZ, Rl
READ
R2
END

The command input is:
MYFILE.MAC;2/AU:30.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;l
-2,.+l,/;CHANGEOOl/
CMP
(Rl) +, B
DEC
R2

I
The listing file MYFILE. LST; 1 resulting from SLP processing is:
1.
2.
3.
4.

13.4.4

MOV
CMP
DEC
TST
BEQ

#BUF 1, RO
(Rl)+,B
R2
R2
END

;CHANGE 001
;CHANGEOOl
;**-2

Changing the Value of the Audit Trail

To change the value of the audit trail, specify:
-[locatorl],[locator2],/;new value/

13-17

SOURCE LANGUAGE INPUT PROGRAM (SLP)
The following example shows how to change the audit trail values.
input file consists of the following lines:
MOV
MOV
CALL
TST
BEQ
CLR
MOV
CMPB
BNE
INC

The

#BUF 1, RO
#S IZ, Rl
READ
R2
END
Rl
R2, NUMC
(RO)+,A
20$
Rl

The command input consists of the following commands and text lines:
MYFILE.MAC;2/AU:48. :10./TR,MYFILE.LST/-SP=MYFILE.MAC;l
-3

CMP
-4,4
DEC

(Rl)+,B
R2

INC

-6, , I; JM o1 oI
-9, ,/;BJ008/

BEQ
I

10$

In this example, the edit commands instruct SLP to insert a line after
line 3, to delete and replace line 4, and to insert new lines after
lines 6 and 9 with new audit trail values.
The listing file (MYFILE.LST) resulting from SLP processing appears as
follows:
1.

2.
3.
4.
5.
6.
7.

8.
9.
10.
11.

12.
13.

13.4.5

MOV
MOV
CALL
CMP
DEC
BEQ
CLR
INC
MOV
CMPB
BNE
BEQ
INC

#BUFl, RO
#S IZ, Rl
READ
(R 1) +, B
R2
END
Rl
R3
R2,NUMC
(RO)+,A
20$
10$
Rl

; **NEW**
; **NEW**
; **-1
;JMOlO

;BJ008

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 the
/-AU switch in the SLP command line.)

13-18

SOURCE LANGUAGE INPUT PROGRAM (SLP)
Both operators are entered in the command input. The backslash (\} is
specified in column 1 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 1 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
.IDENT
-23,23
; VERSION 05.03
-3 7, ,
J. MATTHEWS
JMOll

/05.03/

ll-NOV-80
CORRECT OUT-OF-BOUNDS CONDITION FOR INPUT-BUFFER
SIZE

;
%

-106,106,/;JMOll/
CMP
U 32., R3
BLT
30$

IS INPUT-BUFFER SIZE IN RANGE?
IF LT, NO

I
The lines between the backslash (\} and the percent sign (%} are not
affected by audit-trail processing. The lines following the percent
sign (%} are affected.

13.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: [n]

A number designating the beginning character
audit trail (or other text} to be deleted.

position

the

For example:
S LP>S LPR 11. MAC; 12/CM :.119. =S LPR 11. MAC; 11

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
13-19

30URCE LANGUAGE INPUT PROGRAM (SLP)
tab stop 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 following example, SLP truncates input
position of the audit trail, column 80(10).

lines

the

default

SLP>SLPR11.MAC;l2=SLPR11.MAC;ll/CM

13.5

SLP MESSAGES

SLP messages are divided into two groups:
information and error. The
messages and suggested responses are given in the following sections.
Section 13.5.1 describes the information message and Section 13.5.2
describes the error messages.

13.5.1

SLP Information Message

SLP

COMMAND FILE CHECKSUM IS ######
Explanation: By specifying the /CS[:n]
switch in the command
line, you requested SLP to calculate the checksum value tor the
edit commands.
User Action: This message is
action is required.

13.5.2

for

your

information

only.

SLP Error Messages

This section lists the SLP error messages.
Following each message is
an explanation of the error and recommended user action to correct the
error.
SLP error messages are issued in two formats:
•

SLP followed by a dash, 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/CF

•

SLP followed by a dash, the type of error message, the error
message, and the name of the file with which the error is
associated. For example:
S t.P -- *FATAL*-OPEN FAILUR.E LINE LIST ING FILE filename

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.

13-20

SOURCE LANGUAGE INPUT PROGRAM (SLP)
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.

syntax

User Action:
syntax.

the

proper

Explanation: The device specified was not a legal device.
files were closed and SLP was reinitialized.

Open

User Action:
device.

legal

specified.

Open

Reenter the command

line,

specifying

SLP -- *FATAL*-ILLEGAL DEVICE NAME
command line

Reenter

the

command

line,

specifying

SLP -- *FATAL*-ILLEGAL DIRECTORY
command line segment
Explanation: The directory was not legally
files were closed and SLP was reinitialized.
User Action:
directory.

Reenter

the

command

line,

specifying

legal

the

SLP

SLP -- *FATAL*-ILLEGAL ERROR/SEVERITY CODE pl p2 p3
Explanation:
program.

This error message indicates an error

User Action: Reenter the command line. I f the
submit a Software Performance Report (SPR)
dialog and any other related information, such
listings.

error persists,
with the console
as programs or

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

Reenter the command line, specifying a

legal

file

SLP -- *FATAL*-ILLEGAL GET COMMAND LINE ERROR
Explanation: The system was unable to read a command line. This
error message indicates an internal system failure or an error in
the SLP program.
User Action: Reenter the command line. If the
submit a Software Performance Report (SPR)
dialog and any other related information.

13-21

error persists,
with the console

SOURCE LANGUAGE INPUT PROGRAM (SLP)
SLP -- *FATAL*-ILLEGAL SWITCH
command line segment
Explanation: The switch was not a legal SLP switch or a legal
switch was used in an illegal manner. Open files were closed and
SLP was reinitialized.
User Action:
switch.

Reenter the

command

line,

specifying

the

legal

SLP -- *FATAL*-INDIRECT COMMAND SYNTAX ERROR
command line
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:
syntax.

Reenter the command

line,

specifying

the

proper

SLP -- *FATAL*-INDIRECT FILE DEPTH EXCEEDED
command line
Explanation: More than three levels of indirect command files
were specified in an indirect command file. Open files were
closed and SLP was reinitialized.
User Action: Correct the indirect command file and
command line.

reenter

the

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
number of characters.

•

The file is corrupted or the format is incorrect.

than

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

13-22

the

allowed

message

and

SOURCE LANGUAGE INPUT PROGRAM (SLP)
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 on-line}.

•

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.

These errors cause
reinitialized.

open

files

(for

closed

example,

and

User Action: Determine which condition caused the
correct that condition. Reenter the command line.

SLP

the

message

and

SLP -- *FATAL*-LINE NUMBER ERROR
command line
Explanation: The command line printed
specified numeric line locator.

contained

illegally

User Action: Terminate the SLP edit session and refer to the
rules for specifying numeric line locators in Section 13.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
indirect command file or from the terminal;
was specified for an 800-line file.

specified in an
for example, -990

User Action:
Terminate the current editing session.
Restart
the editing session, and enter the edit command line, specifying
the correct line number.

13-23

SOURCE LANGUAGE INPUT PROGRAM (SLP)
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 prompts {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 enter the edit command lines directly from
the terminal, 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.
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.

13-24

CHAPTER 14
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, PAT
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 14-1 shows the processing steps
involved in generating an updated task file using PAT.

14.1

SPECIFYING THE PAT COMMAND LINE

Specify the PAT command line in the following format:
[outfile]=infile[/CS[:number]],correctfile[/CS: [number]]
outf ile
The file specification for the output file.
If
specify an output file, PAT does not generate one.

14-1

you

not

OBJECT MODULE PATCH UTILITY (PAT)
infile
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 to be applied to one module in the input

/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 14.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. You must then rerun PAT,
specifying the correct checksum.
CORRECT.SAC

TEXT
EDITOR

Generate a correction file using
the Text Editor.

CORRECT.SAC

LJ
LJ
LJ

->LJ
->LJ

CORRECT.OBJ

Execute the assembler (or compiler)
to generate an object module
version of the file.

CORRECT.OBJ

MY FILE.OBJ

MY FILE.OBJ
3.

Execute PAT using as input the
correction file and the module to
be updated.

Execute the Task Builder to
resolve new addresses and
generate an executable task.

->LJ
MYFILE.TSK

TASK
BUILDER

ZK-199-81

Figure 14-1

Processing Steps Required to Update a
Module Using PAT

14-2

OBJECT MODULE PATCH UTILITY (PAT)
14.2

HOW PAT APPLIES UPDATES

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.

14.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
you execute PAT, 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.

14.2.2

The Correction File

The correction file contains the patches to be applied to the input
file.
PAT assumes a file type of .OBJ for the correction file.
If
you use a file type other than .OBJ, you must specify it explicitly in
the command line.
As shown in Figure 14-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
.!DENT updatenum
inputline
inputline

inputname
The name of the module to be corrected by the PAT update.
must specify the module that you are updating for inputname.

You

updatenum
Any value acceptable to the MACR0-11 .!DENT assembler directive.
Generally, this value reflects the updated version of the file to
be processed by PAT (as shown in the examples given in Section
14.2.3}.
NOTE
The .!DENT assembler di~ective is a
required part of the correction file.
Failure to include an .!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.
14-3

OBJECT MODULE PATCH UTILITY (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 absolute.
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.

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

14.2.3.l Overlaying Lines in a Module - The
following
example
illustrates a technique using a patch file to overlay lines in a
module.
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

MOV
CALL
RETURN
.END

A,C

/01/

ABC::
XYZ

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

A,B

~TOON

.END

14-4

OBJECT MODULE PATCH UTILITY (PAT)
You use the MACR0-11 assembler to assemble the correction file. After
assembly,
PAT processes the resulting object module and the input
object module. The result of PAT processing appears as follows:
• TITLE
• IDENT

ABC
/01.01/

MOV
CALL
RETURN

A,C

ADD
RETURN
• END

A,B

ABC::
XYZ

.=ABC
.=.+12

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
• IDENT

ABC
/01. 01/

MOV
CALL
ADD
RETURN
• END

A,C

ABC::
XYZ

A,B

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
RETURN

A, B

14.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 at an appropriate location in the subroutine. The CALL
instruction directs the program to branch to the new code, execute
that code, and then return to in-line processing.
The input file for this example is:
• TITLE
• !DENT

ABC
/01/

MOV
CALL
MOV
RETURN

A,B

ABC::
XYZ

C,RO

• END

14-5

OBJECT MODULE PATCH UTILITY (PAT)
The correction file for this example is:
• TITLE
• !DENT
CALL
NOP
• PSECT

ABC

MOV
MOV
ASL
RETURN
• END

A,B
D,RO
RO

/01. 01/

PATCH
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
• !DENT

ABC

CALL
NOP
CALL
MOV
RETURN

PATCH

/01. 01/

ABC::
XYZ

C,RO

• PSECT

PATCH

MOV
MOV
ASL
RETURN
• END

A,B
D,RO
RO

PATCH:

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

14.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 to 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

14-6

OBJECT MODULE PATCH UTILITY (PAT)
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
After 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
error:
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.FOB CHECKSUM
Checksum processing always results in an octal, nonzero value.

14.3

PAT 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 that describe fatal errors (errors
terminate), PAT uses the prefix:

that

caused

PAT

type,

PAT -- *FATAL*-error message
The following messages are
follows:

grouped

•

Information messages

•

Command line errors

•

File specification errors

•

Input/Output errors

•

File content or format errors

•

Internal software error

•

Storage allocation error
14-7

according

message

OBJECT MODULE PATCH UTILITY (PAT)
14.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
Explanation: When you
specify
/CS
in
the
input
file
specification, PAT informs you of the file's checksum value. The
value is given in octal.
User Action:

14.3.2

No response necessary.

Command Line Errors

The following error messages result from
command line syntax rules.

failure

adhere

the

COMMAND LINE ERROR command line
Explanation: The system standard command line processor
detected an error in the command line.

(.GCML)

User Action:
information.

correct

Reenter

the

command

line

using

the

COMMAND SYNTAX ERROR command line
Explanation:

The command line contained a syntax error.

User Action:

Reenter the command line using the correct syntax.

ILLEGAL INDIRECT FILE SPECIFICATION command line
Explanation: You specified an indirect
contains one of the following errors:

command

file

•

A syntax error

•

A specification for a nonexistent indirect command file

that

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.

14-8

OBJECT MODULE PATCH UTILITY (PAT)
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.

14.3.3

File Specification Errors

The following error messages are caused by errors in the specification
of input or output files or related file switches.
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 using the correct syntax for the
device or volume specification.
ILLEGAL DIRECTORY SPECIFICATION directory name
Explanation:
error.

The

directory

specification

User Action: Check the rules for
reenter the command line using
directory specification.

contained

syntax

specifying a directory and
the correct syntax for the

ILLEGAL FILE SPECIFICATION filename
Explanation:

The file specification contained a syntax error.

User Action: Reenter the command line using the
for the file specification.

correct

syntax

ILLEGAL SWITCH SPECIFIED filename
Explanation: An unrecognized
specified with the file.
User Action:
reenter the
value.

switch

value

was

Check the rules for specifying the switch and
command line using the correct switch or switch

14-9

OBJECT MODULE PATCH UTILITY (PAT)
INVALID FILE SPECIFIED filename
Explanation: You specified a
following errors:

file

that

contains

one

the

•

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 specifying the correct filename.

14.3.4

Input/Output Errors

The following error messages are caused by faults detected
was performing I/O to the specified file.

14-10

while

PAT

OBJECT MODULE PATCH UTILITY (PAT)
ERROR DURING CLOSE:

FILE:

filename

Explanation: This error is most likely to occur while PAT is
attempting to write the remaining data into the output file
before deaccessing 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-file.

PAT

attempted

position

the

file

beyond

User Action: Submit a Software Performance Report along with the
related console dialog 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/0 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

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.

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

14-11

the

OBJECT MODULE PATCH UTILITY (PAT)
ERROR IN FILE filename CHECKSUM
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.

14-12

OBJECT MODULE PATCH UTILITY (PAT)
UNABLE TO LOCATE MODULE module name
Explanation: AAT 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.

14.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 Action:
If these messages persist, submit a Software
Performance Report along with related console dialog and any
other pertinent information.

14.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-listhead
Explanation: Not enough contiguous task memory was available
satisfy a request 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 description
of the INSTALL command in the RSX-llM/M-PLUS MCR Operations
Manual.)

14-13

CHAPTER 15
TASK/FILE PATCH PROGRAM (ZAP)

The Task/File Patch Program (ZAP) allows you to directly examine and
modify task image and data files on a Files-11 volume.
Using ZAP, you
can patch these files interactively
without
reassembling
and
rebuilding the task.

ZAP supports four types of task image files:
•

Regular task image files, which include
resident and supervisor mode libraries

those

•

Multiuser task image files

•

I- and D-space (instruction and data space) tasks

•

Resident libraries

mapped

I
These types of task image files are discussed
switch (Section 15.1.1).

fully

with

the

/List

ZAP performs many of the functions performed by the RSX-11 on-line
debugging utility, ODT. Thus, working knowledge of ODT is helpful in
using ZAP.
See the IAS/RSX-11 ODT Reference Manual for
more
information on ODT.
ZAP provides the following features:
•

Operating modes that allow you to access specific words and
bytes in a file, modify locations in a file, list the disk
block and address boundaries for each overlay segment in a
task image file on disk, and open a file for reading only

•

A set of internal
Registers

•

Single-character commands that, with other command
line
elements, allow you to open and close locations in a file and
to display and manipulate the values in those locations

registers

that

include

eight

Relocation

Except in read-only mode, the results of ZAP commands are permanent.
Thus, the best way to use ZAP is with a hard-copy terminal so that you
have a record of the changes you make.
Although the ZAP program is relatively straightforward to use,
patching locations in a task image file requires knowing how to use
the map (or memory allocation file) generated by the Task Builder and
the listings generated by the MACR0-11 assembler.
These maps and

15-1

April 1983

TASK/FILE PATCH PROGRAM (ZAP)

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 11st1ngs, see the-p{)P-11 MACR0-11 Language Reference Manual.

15.1

ZAP OPERATING MODES AND SWITCHES

ZAP provides two addressing modes and two access modes.
The
addressing modes are task image mode and absolute mode. Task image
mode is the default mode.
The access modes are read/write mode and
read-only mode.
Read/write is the default mode. Either addressing
mode can be used with either access mode.
The modes and their
associated switches are as follows:
•

Task image mode is the default addressing 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.
See Section 15.2 for more information on
using task image mode.

•

In absolute mode, specified with the /AB switch, ZAP processes
the addresses you enter in ZAP command lines as absolute byte
addresses within the file.
You must use absolute mode for any
files that are not task images. See Section 15.2 for more
information on using absolute mode.

•

Read/write mode is the default access mode for ZAP.
In
mode, ZAP opens a file for reading and/or modification.

•

In read-only mode, specified with the /RO switch, ZAP opens a
file for reading but not modification.
That is, you can
execute ZAP functions that change the contents of locations,
but these changes are not actually made to the file. When ZAP
exits, the original values in the file are still there.

15.1.1

this

The List Switch (/LI)

When using ZAP in task image mode (but not absolute), you can also
specify the /List switch
(/LI).
The /List switch directs ZAP to
display the overlay segment table for the task image file on disk that
you are working with.
The table lists the starting disk block and
address boundaries for each overlay segment in the file.
The segment
table lists are in a different format for each type of task image
file.
(The formats are discussed later in this section.) You use this
table and the Task Builder map to locate the task segments being
changed.
The /LI switch displays
following format:

ssssss:

the

overlay

segment

aaaaaa-bbbbbb [nnnnnn]

[dddddd]

boundaries

the

ssssss:
The starting block in octal.

aaaaaa
The lower address boundary in octal.

15-2

April 1983

TASK/FILE PATCH PROGRAM (ZAP)
bbbbbb

The upper address boundary in octal.
nnnnnn

The segment name that appears for I- and D-space tasks; manually
loaded overlays
($LOAD); memory-resident overlays; tasks that
link to the library with memory-resident overlays;
or for any
combination of the previous conditions.
dddddd

The description of the segment type string which appears next
the segment name in the segment table.

The following sections describe the /List switch formats for the
different kinds of task image files.
Section 15.7 gives examples of
the segment table lists.

15-2.1

April 1983

TASK/FILE PATCH PROGRAM (ZAP)
15.1.1.1 The /LI
Switch and
Regular Task Image Files
For
regular task image files
(including those mapped to resident and
supervisor mode libraries), the /LI switch displays the task's overlay
segments in the order of their location in the file.
Each segment in
these files begins on an even block boundary.

15.1.1.2 The /LI Switch and
Multiuser
Task
Image
Files
For multiuser tasks,
the /LI switch lists the starting disk block
number and address boundaries of each segment.
In addition, the
address boundaries of the shared read-only segment are listed.
The
block number that is used to reference the multiuser segment is the
same as the root segment. The multiuser segment is an extension of
the root segment.
The segment list disk block numbers have a
corresponding entry in the Task Builder map.
See the RSX-llM/M-PLUS Task Builder Manual
multiuser tasks.

for

information

15.1.1.3 The /LI Switch and
Resident
Libraries For resident
libraries, the /LI switch displays each of the task's segments as
beginning on a new block boundary.
However, the segments may not
actually begin on even boundaries because of compression by the Task
Builder. Resident libraries can be overlaid, but each overlay segment
must also be resident in memory.
To avoid the possibility that two or more segments in a single block
could have the same virtual address, ZAP treats the resident library
in the same way that the Task Builder does. The Task Builder builds
the library with each segment beginning on an even block boundary, but
then compresses the segments in the task file itself.
The Task
Builder map is generated before the segments are compressed, so the
boundaries given in the map do not necessarily correspond to the
actual location of the segments.
The disk block boundaries given in the Task Builder map file are the
ones that ZAP uses to address locations in the resident library and
that the /LI switch displays in its segment table. They do not use
the actual starting blocks of the segments.
(You should be aware of
this when you are working with resident libraries in absolute mode.
However, also remember that you cannot use the /LI switch in absolute
mode.)
You should also note that ZAP cannot know the physical starting
addresses for the segments of an overlaid resident library because its
overlay structure is stored in the symbol definition (.STB) file,
not
with the task image file itself.
For ZAP, each segment's starting
address is 000000.
See the RSX-llM/M-PLUS Task Builder Manual
resident 11brar1es.

for

information

15.1.1.4 The /LI Switch and I- and 0-Space Tasks - For I- and 0-space
tasks,
the /LI switch lists the starting block number and the address
boundaries of each segment. The I-space or 0-space segment may be
suppressed in the listing when,
for example, a segment with only
I-space code does not include a listing for a 0-space segment.
If the
segments are not suppressed, the segment list disk block numbers have
a corresponding entry in the Task Builder map.

15-3

April 1983

TASK/FILE PATCH PROGRAM (ZAP)
15.2

ADDRESSING LOCATIONS IN FILES

To address locations in a file,
ZAP provides two addressing modes
(task image and absolute, described above)
and a set of internal
registers, which includes eight Relocation Registers.
This section
first introduces the concept of relocation biases· and the use of the
Relocation Registers, then explains how to use the addressing modes.

15.2.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 assembler
listing, all locations in the program section are shown relative to
this base address.
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 program sections 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.

15.2.2

ZAP Addressing Modes

As explained in Section 15.1, ZAP's two modes for addressing locations
in a file are task image mode and absolute mode.
Task image mode is
the default mode for ZAP. The next two sections explain how to use
these modes.
The following examples show excerpts from a MACR0-11 listing of the
module MYFILE and a Task Builder map.
These excerpts and the
accompanying text show how to use ZAP in task image mode.
The
following lines represent assembled instructions from a MACR0-11
source listing:
71 000574
72 000602

73
74
75
76
77

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

#FE.MUP,$FMASK
2$
30$
$TKTCB,RO
T.UCB(RO) ,RO
RO,UCB
#U2.HLD,U.CW2(RO)

The following lines from a Task Builder map give the information you
need to address locations in the task image file as they appear in the
above MACR0-11 listing:

15-4

TASK/FILE PATCH PROGRAM (ZAP)
R/W MEM
DISK BLK

LIMITS: 120000 123023 003024 01556.
LIMITS: 000002 000005 000004 00004.

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 Task Builder map, 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 program code 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 following command line:
2:120232+574/(ffi)
ZAP responds by opening the location and displaying its contents:
002:121026/ 032767
Section 15.4 describes the ZAP command line formats.

15.2.2.1 Using the Task Image Addressing Mode - In task image mode,
ZAP allows you to address locations in a task image file by using the
addresses the MACR0-11 assembler displays in its listing and the
starting block number and byte offset listed in the Task Builder map.
Unlike absolute mode, task image mode is useful for working with
locations in an overlaid file because the Task Builder and ZAP perform
the calculations necessary to relate the file's disk structure to its
run-time memory structure.

15.2.2.2 Using the Absolute Addressing Mode - In absolute mode, ZAP
processes the addresses you enter in the command lines as absolute
byte addresses within the file.
To use ZAP in absolute mode,
invoke
ZAP and enter the /AB switch with the file specification.
ZAP interprets the first address in the file you are changing as
virtual block 1, 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 data or task image file as
well as the label and header blocks of a task image file on disk.
However, to modify a disk task image, you must know the disk layout of
the task image. Generally, absolute mode is practical only for data
files or for task image files that are not overlaid.

15.3

INVOKING AND TERMINATING ZAP

You invoke ZAP using any of the methods described in Chapter 1.
However, you cannot enter a file specification on the same line that
you use to invoke ZAP unless the file is an indirect command file (see
Section 15.3.1).

15-5

TASK/FILE PATCH PROGRAM (ZAP)
When ZAP prompts you, enter the file specification for the file
want to change. You enter the file specification in the format:

you

dev: [ufd]filename.filetype;version[/sw ••• ]
The default file type
is
.TSK.
After
you
specification, ZAP prompts with an underscore (_).

enter

the

file

You terminate ZAP by entering the X command
(explained
in Section
15.6.1).
This command exits you from ZAP and returns control to your
command line interpreter.

15.3.1

Using Indirect Command Files with ZAP

An indirect command file contains the specification for the file you
want to work with and the appropriate ZAP commands. You can specify
the indirect command file in the same command line in which you invoke
ZAP.
(called
CHANGE.CMD)
The following sample indirect command file
contains ZAP commands. The commands will change the default priority
The V command
(explained
of the despooler from 70 to 80 (120 octal).
in Section 15.6.5)
is used to verify that 70 (106 octal) is what is
actually in the location to be changed.
The command file has the
following ZAP commands:
LPP.TSK/AB
0:346/
106V
120

To use the indirect command file (in thi~ case, from
following:

MCR),

type

the

>ZAP @CHANGE
This command invokes ZAP, which then
file.

executes

the

commands

The commands being used first open the task image file
(LPP.TSK)
in
absolute mode (/AB). The next two commands open the desired location
(byte 346 in block 0) and verify its contents (106).
The next command
changes the contents to 120, which will be the new default priority
for the despooler.
The X command exits you from ZAP and
returns
control to MCR.

15.4

THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS

ZAP commands perform functions that allow you to examine and modify
the
contents of locations in a file.
Command lines comprise
combinations of the following elements:
•

Commands

•

Internal registers

15-6

TASK/FILE PATCH PROGRAM (ZAP)
•

Arithmetic operators

•

Command line element separators

•

The current location symbol

•

Location-specifier formats

The command elements can be combined 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 15.5 and 15.6 describe how to
elements to execute ZAP functions.

15.4.1

command line elements.
combine the command line

ZAP Commands

There are three types of ZAP commands:
•

Open/close location commands

•

General purpose commands

RETURN Key

The following sections describe each type of command.

15.4.1.1 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 15.4.2)

contents

•

Close the location after (optionally) modifying
another location as specified by the command

and

Section 15.5 describes the format for specifying
commands.

open/close

open

location

15.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 15.6 describes the format for
specifying these commands.

15.4.1.3 RETURN Key - Unless there is another value or command on the
line, the RETURN key closes the current location as modified and opens
the next sequential location. ZAP commands take effect only after you
press the RETURN key.

15-7

TASK/FILE PATCH PROGRAM (ZAP)
15.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 program section
to change the contents of locations in the program section.
You load the registers with the base address of the program
section that has been relocated by the Task Builder.

•

The Constant Register (C). You set this register to contain a
16-bit value, which you can specify as an expression in the
ZAP command line.

•

The Format Register (F). This register controls the format of
the displayed address.
If the value of the F Register is 0
(the initial 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 byte format.

•

The Quantity Register (Q). ZAP sets the value in the register
to be the last value displayed at your terminal.

To access the contents of a register, specify a dollar sign ($)
preceding the register name
(in this case, C) in the command line.
For example:
$C/~

$C/ 000000
This command line directs ZAP to display the contents of the Constant
Register. The slash (/) is an open command described in Table 15-3.

15.4.3

ZAP Arithmetic Operators

Operators are single-character command line elements that define an
arithmetic operation.
Generally, ZAP evaluates these expressions as
addresses. Table 15-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+1 70/@

This method for calculating such a displacement
accurate than doing it manually.

15-8

faster

and

TASK/FILE PATCH PROGRAM (ZAP)
Table lS-1
ZAP Arithmetic Operators
Operator

Function

The plus sign adds a value to another value. Used in
an expression that ZAP then evaluates to be a command
line element.
The minus sign subtracts a value from another value.
Used in an expression that ZAP then evaluates to be a
command line element.
The asterisk multiplies a value by S0(8) and adds it
to another value. Used to form a Radix-SO string.

The following example shows how to use the asterisk
(*)
to form
Radix-SO strings.
Section lS.4.4 explains the use of the colon and
comma; the percent sign is an open command described in Table lS-3.
0,40/00)

002:0,000040/
1*3300'.)

000001

-/00)

002:0,000040/

000103

%00)

002:0,000040%

In this example, the first command opens the locations that is 40
bytes offset from the location address contained in Relocation
Register 0 and displays in octal format the contents of the new
location. The location contains the value 000001. The second command
converts 000001 to Radix-SO and adds 33 to the Radix-SO value.
The
slash
(/)
command again displays in octal the value contained in the
offset location. The value is now 103. The percent sign (%) command
displays 103 in Radix-SO format.

lS.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. See Table lS-2.
Table 15-2
ZAP Command Line Element Separators
Function

Separator

The
comma
separates
a
Relocation
Register
specification from another command line element.
The semicolon separates an address from an internal
register specification.
Used in expressions that set
values for Relocation Registers.
The colon separates a block number base value from a
byte offset into the block.
Used in most of the
references to locations in a file.
lS-9

TASK/FILE PATCH PROGRAM {ZAP)
15.4.5

ZAP Command Line Location-Specifier Formats

ZAP has three formats for specifying locations in a command line.
Each provides a means of indexing into a file. The formats are:
•

Current location symbol

•

Byte off set

•

Block number:byte offset

•

Relocation register,byte offset

15.4.5.1 The Current Location Symbol - In command line expressions
that ZAP evaluates as addresses, a period (.) represents the last open
location.

15.4.5.2
follows:

Byte Offset Format - You specify the byte offset

format

location
If you are using ZAP in absolute mode, ZAP
interprets
this
specification as a byte offset from block 1, location 000000.
This
format is generally useful only when you are using absolute mode.
The following ZAP command line opens
displays its contents in octal format:

absolute

location

664

and

_664/(BTI)

15.4.5.3 Block Number:Byte Offset Format - This format allows you to
specify a byte offset from a specific block in the file.
Specify the
format as follows:
blocknum:byteoffset
You can use this format for addressing locations whether
enter the /AB switch with the file specification.

not

you

In task image mode, ZAP allows you to enter the block number and byte
offset displayed in the Task Builder map. The map gives information
on the overlay segments in a task image file.
See Section 15.2 for
more information.

15.4.5.4 Relocation Register,Byte Offset Format - This format allows
you to load a Relocation Register with the address of a location. The
address 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
address loaded in the Relocation Register. For example:

15-10

TASK/FILE PATCH PROGRAM (ZAP)

2: 001254; 3Rfil]
-3, 64/fil]
002:3,000064/ 037334
The first command loads the address 001254 into Relocation Register 3,
then the second command opens the location that is 64 bytes offset
from block 2, location 001254.
The contents of that location are
037334.

15.5

USING ZAP OPEN AND CLOSE COMMANDS

This section gives examples of how to use the ZAP open and close
commands.
These commands allow you to open locations in a file,
modify those locations, and close the locations.
Table 15-3 summarizes the open and close commands.
Table 15-3
ZAP Open and Close Commands
Character

Function

Designation

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 mark

Opens
a
location,
displays
the
contents of the location as two ASCII
characters, and stores the contents of
the location in the Quantity Register
(Q) •

Percent sign

Opens
a
location,
displays
the
contents of the location in Radix-50
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).

Apostrophe

Opens
a
location,
displays
the
contents as one ASCII character, and
stores the contents of the location in
the Quantity Register (Q).
(continued on next page)

15-11

TASK/FILE PATCH PROGRAM (ZAP)
Table 15-3 (Cont.)
ZAP Open and Close Commands
Designation

Function

RETURN Key

Closes
the
current
location
as
modified and opens the next sequential
location if no
other
values
or
commands are on the command line. ZAP
commands take effect only after you
press the RETURN key.

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 and opens the new 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
the target location of the
opens
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.

Character

15.5.1

Opening Locations in a File

Use any of the ZAP open commands -- slash (/), quotation mark ("),
percent sign (%), backslash (\), or apostrophe (') -- to open a
location in a file. The format ZAP uses to display 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 continually press the RETURN
key, consecutive locations are displayed in Radix-SO format until you
change the format by entering a different special-character open
command.

15-12

TASK/FILE PATCH PROGRAM (ZAP)
15.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
pressing the RETURN key.
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.
/(BIT}
002:120000/ 000000
44444lBITJ

-;ru

002:120000/ 44444
The first command (/) displays in octal format the contents
(000000)
of the current location.
The contents are changed by entering the
value 44444 and then the location is closed as modified by pressing
the RETURN key.
The slash (/) and RETURN key display the new contents
of the location (last line of example).

15.5.3

Closing Locations in a File

ZAP uses the RETURN key
closing a location in
functions:

and
a

other special-character commands for
file.
The close commands perform three

•

Close the current location

•

Direct ZAP to another location (such as the preceding location
or a location referred to by the current location)

•

Open the new location

The following sections give examples of how each command works.

15.5.3.1 Closing a
Location and Opening the Preceding Location
Use the circumflex (~) or up-arrow (t) 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
following sequence of ZAP commands and
responses shows how this
command works:
2: 120100/ffil
002:120100/ 000000

002:120102/ 000111

002:120104/ 000222

002:120106/ 000333
~ru

002:120104/ 000222
The RETURN key closes the first three open locations and then opens
the next location.
The circumflex command closes location 120106 and
directs ZAP to open the preceding location, 120104.

15-13

TASK/FILE PATCH PROGRAM (ZAP)
15.5.3.2 Closing a Location and Opening an Offset Location
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 the new location.
The following sequence of ZAP commands and responses shows how this
command works:
2: 120100/(BTI)
002:120100/ 000000
@

002:120102/ 111111
@

002:120104/ 222222
@

002:120106/ 000022
@

002:120132/ 123456

The RETURN key closes the first three open locations. The underscore
command closes location 120106, directs ZAP to us~ the contents (22)
of the current location as the offset from the current location
(120110), and then opens that offset location (120132).

15.5.3.3 Closing a Location and Opening an Absolute Location
Use
the at sign (@) command to close the current 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/@
002:120100/ 000000
@

002:120102/ 111111
@

002:120104/ 120114

@@
002:120114/ 114114

The RETURN key closes the first three open locations.
The at sign
command 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.

15.5.3.4 Closing a Location and Opening a Branch Target Location
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 for the address of the next
location, and then to open that location. The following sequence of
ZAP commands and responses shows how this command works:
2:120100/@
002:120100/ 005000
@

002:120102/ 005301
@

002:120104/ 001020
>@

002:120146/ 052712

15-14

TASK/FILE PATCH PROGRAM (ZAP)
The RETURN key closes the first three open locations. The right angle
bracket command closes location 120104, directs ZAP to use the
low-order byte (020) of its contents as the branch offset for the
address of the next location (120146), and then opens that location.

15.5.3.5 Closing a Location and Opening a Previous Location - 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 then
to open that location. The following sequence of ZAP commands and
responses shows how this command works:
1 2 0 2 ; OR 00)
-0,10/~

002:0,000010/ 005212
~

002:0,005224/ 001020
>~

002:0,005266/ 000000
@00)

002:0,000000/ 000000

<00)

002:0,000012/ 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.

15.6

USING ZAP GENERAL PURPOSE COMMANDS

This section explains the functions of ZAP general purpose commands
and shows the formats for specifying them. Table 15-4 describes the
commands.
Table 15-4
ZAP General Purpose Commands
Function

Command

Exits from ZAP;
interpreter

Calculates the offset in bytes between an address and
the
value
contained in a Relocation Register,
displays the offset value, and stores it in the
Quantity Register (Q)

Displays the jump and branch displacements
current location to a target location

returns control to your command line

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

15-15

TASK/FILE PATCH PROGRAM (ZAP)

The X Command

15.6.1

Use the X command to exit from ZAP and then
command line interpreter.

return

control

your

Specify the X command in the format:

x
15.6.2

The K Command

Use the K command to calculate the offset in bytes between an address
and the value contained in a Relocation Register, to display the
offset value, and to store it in the Quantity Register (Q).
You can enter the K command in the following formats:
K

Calculates the offset in bytes between the address of the
currently open location and the value of the Relocation
Register whose contents are equal to or closest to (but less
than) the value of that address

Calculates the offset in bytes between
location and Relocation Register n

a;nK

Calculates the offset
Relocation Register n

bytes

the

between

currently
address

open
a

and

ZAP responds to the K command by displaying the Relocation Register it
used and the offset value it calculated in the format:
=reg,offset
The following example shows how to use the K command:
2 : 11 72 ; OR (BIT)

-2: 1232; lR (BIT)
-2: 1202/ 00)
002:000020/ 000111
K@

;;0,000010
0, 100; lK (BIT)
;;l,000040
The first command sets the value of Relocation Register 0 to 001172.
The second command sets the value of Relocation Register 1 to 001232.
The slash command displays in octal format the contents of location
001202
(000111).
The K command calculates the physical distance
(offset) between the address of the currently open location
(001202)
and the value of the Relocation Register whose contents are equal to
or closest to (but less than) the value of the address.
ZAP then
displays the number of the Relocation Register it used (0) and the
offset (00010=001202-001172).
The last command adds 100 to the
address in Relocation Register 0
(001172) and then calculates the
offset between the new address 0 (001272) and the contents of
Relocation Register 1 {001232). ZAP then displays the number of the
specified
Relocation
Register
(1)
and
the
offset
(000040=001272-001232).

15-16

TASK/FILE PATCH PROGRAM (ZAP)
15.6.3

Theo Command

Use the O command to display the jump and branch displacements from
the current location to a target location. A jump displacement is the
offset between the open location and the target location.
The jump
displacement is used in the second word of a jump instruction if the
instruction uses relative addressing. A branch displacement is the
low-order byte of a branch instruction which, when executed, branches
to the target location.
You can enter the 0 command in the following formats:
aO

Displays the jump and branch displacements from the
location to the target of the branch (a)

a;rO

Displays the jump and branch displacements from
to target location r

current

location

The following example shows how to use the O command:

o, 4534/IBm
0,4534/ 1234
45660 (@]
-000030> 000014
-4534; 45660 (@]
-000030> 000014
The first number (000030) is the jump displacement;
(000014) is the branch displacement.

15.6.4

The Equal Sign

(=)

the second number

Command

Use the equal sign command (=) to display (in octal) the value of
expression to the left of the equal sign.

the

Specify the equal sign command in the format:
expression=
The following example shows how to use the equal
that 177777 equals -1):

sign

command

(note

2: 30/IBDJ
002:000030/ 000000
• +l 77756= (BIT)
000006

The first command displays in octal format the contents of location
000030, which are 000000.
The next command adds 177756 to the address
of the currently open location (000030). ZAP then displays the value
of the specified expression (6=30+177756 or 6=30-22).

15.6.5

The V Command

Use the V command to verify
value.

that

Specify the V command in the format:
contentsV

15-17

location

contains

specified

TASK/FILE PATCH PROGRAM (ZAP)
You use the V command 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 issues an error
message 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
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 exits.

15.6.6

The R Command

Use the R command to specify the value for a Relocation Register.
As
explained in Sections 15.2 and 15.4.2, ZAP uses these registers to
index into a program section so that you can change the contents of
locations in the program section.
Specify the R command in the format:
_contents;nR
The variable n is the number of the Relocation Register (0 through 7).
For example:
$ 3R/ ID)
$3R/ 1 77777
125670; 3R ID)

-$3R/ ID)

$3R/ 125670
The first command accesses the contents of Relocation Register 3,
which ZAP displays in octal format as specified by the slash. The
contents of the register are 177777. The next command changes the
contents of the register to 125670. The last command again displays
the contents of the register, which have been changed correctly.

15.7

EXAMPLES

This section gives examples of ZAP usage. The examples show the /LI
switch segment table format and how you would use some of the ZAP
commands.
All of the ZAP examples in this section are based on information
contained in the following excerpts from a sample Task Builder memory
allocation map and from the program code for some of the modules in
the task. Each example follows the section of program code associated
with it.

15-18

TASK/FILE PATCH PROGRAM (ZAP)

Excerpts from Task Builder map:
MAINMEO.TSK;l

Memory allocation map TKB M40.10
14-MAR-83
16:01

Page 1

Task
name
••• MEO
Partition name
GEN
Identification
MOO
Task UIC
[31,102]
Stack
limits: 000300 001277 001000 00512.
PRG xfr address: 020520
Task attributes: ID
Total address windows: 2.
Task image size
9184. words, I-Space
3520. words, D-Space
Task Address limits: 000000 043647 I-Space
000000 015507 D-Space
R-W disk blk limits: 000002 000102 000101 00065.
MAINMEO.TSK;l Overlay description:
Base

Top

000000
000000

023135
014123

022140
014124

Length

-----'023136

09822. I
06228. D

MAINO

014124

043645
015507

021506
001364

09030. I
00756. D

INPUT

022140
014124

022307
014167

000150
000044

00104. I
00036. D

CALC

022310
014170

022437
014173

000130
000004

00088. I
00004. D

AADD

022310
014170

022437
014173

000130
000004

00088. I
00004. D

SUBB

022310
014170

022437
014173

000130
000004

00088. I
00004. D

MULL

022310
014170

022441
014173

000132
000004

00090. I
00004. D

DIVV

022140
014124

023725
014251

001566
000126

00886. I
00086. D

OUTPUT

MAINMEO.TSK;l
MAINO

Memory allocation map TKB M40.10
16:01
14-MAR-83

Page 2

*** Root segment: MAINO
R/W mem

limits: 000000 023135 023136 09822. I-Space
000000 014123 014124 06228. D-Space

Disk blk limits: 000002 000024 000023 00019. I-Space
000025 000041 000015 00013. D-Space

15-19

April 1983

TASK/FILE PATCH PROGRAM (ZAP)
Memory allocation synopsis:
Title

Ident

File

000300 000216 00142 •
000300 000216 00142. CBTA

04.3

SYSLIB.OLB;7

Section
• BLK.:(RW,I,LCL,REL,CON)

MAINMEO.TSK;l
INPUT

Memory allocation map TKB M40.10
16:01
14-MAR-83

Page 4

*** Segment: INPUT
R/W mem

limits: 022140 043645 021506 09030. I-Space
014124 015507 001364 00756. D-Space

Disk blk limits: 000042 000063 000022 00018. I-Space
000064 000065 000002 00002. D-Space

Page 5

*** Segment: CALC
limits: 022140 022307 000150 00104.
014124 014167 000044 00036.

I-Space
D-Space

Disk blk limits: 000066 000066 000001 00001.
000067 000067 000001 00001.

I-Space
D-Space

R/W mem

Page 7

*** Segment: AADD
R/W mem

limits: 022310 022437 000130 00088.
014170 014173 000004 00004.

I-Space
D-Space

Disk blk limits: 000070 000070 000001 00001.
000071 000071 000001 00001.

I-Space
D-Space

Page 8

*** Segment: SUBB
limits: 022310 022437 000130 00088.
014170 014173 000004 00004.

I-Space
D-Space

Disk blk lirni ts: 000072 000072 000001 00001.
000073 000073 000001 00001.

I-Space
D-Space

R/W mern

15-20

April 1983

TASK/FILE PATCH PROGRAM (ZAP)
Page 9

*** Segment: MULL
R/W mem

limits: 022310 022437 000130 00088.
014170 014173 000004 00004.

I-Space
D-Space

Disk blk limits: 000074 000074 000001 00001.
000075 000075 000001 00001.

I-Space
D-Space

MAINMEO. TSK; 1
DIVV

Page 10

Memory allocation map TKB M40.10
14-MAR-83
16:01

*** Segment: DIVV
limits: 022310 022441 000132 00090.
014170 014173 000004 00004.

I-Space
D-Space

Disk blk limits: 000076 000076 000001 00001.
000077 000077 000001 00001.

I-Space
D-Space

R/W mem

Page 11

*** Segment: OUTPUT
limits: 022140 023725 001566 00886.
014124 014251 000126 00086.

I-Space
D-Space

Disk blk limits: 000100 000101 000002 00002.
000102 000102 000001 00001.

I-Space
D-Space

R/W mem

Memory allocation synopsis:
Section

-------

. BLK.:(RW,l,LCL,REL,CON)

022140
022140
022202
022276
022424

000374
000042
000074
000126
000110

00252.
00034.
00060.
00086.
00072.

Title

I dent

File

SAVAL
CATB
CDDMG
C5TA

00
03
00
02

SYSLIB.OLB;7
SYSLIB.OLB;7
SYSLIB. OLB; 7
SYSLIB.OLB;7

Example 1:

In this example, the segment table for task MAINMEO is requested.
Note that the segment table corresponds exactly to the overlay
description list given in the Task Builder map. The sequence of ZAP
commands is as follows:

15-20.1

April 1983

TASK/FILE PATCH PROGRAM (ZAP)

>ZAP~

ZAP>MAINMEO/L I ~
ZAP Version V02.0l COPYRIGHT (c) DIGITAL EQUIPMENT CORPORATION 1983
Segment Table
000002: 000000-022137 MAINO I-space root
000025: 000000-014123 MAINO D-space root
000042: 022140-043647 INPUT
I- and
D-space
000064: 014124-015507 INPUT
000066: 022140-022307 CALC
I- and
D-space
000067: 014124-014167 CALC
000070: 022310-022347 AADD
I- and
D-space
000071: 014170-014173 AADD
000072: 022310-022437 SUBB
I- and
D-space
000073: 014170-014173 SUBB
000074: 022310-022437 MULL
I- and
D-space
000075: 014170-014173 MULL
000076: 022310-022443 DIVV
I- and
000077: 014170-014173 DIVV
D-space
000100: 022140-023727 OUTPUT I- and
000102: 014124-014253 OUTPUT D-space

In Example 1, the first command line invokes ZAP and the second
command line requests the segment table for the task MAINMEO.
The
/List switch directs ZAP to give the starting disk block for the root
segment of the task
(in this example, MAINO) and for each segment
overlaid on the root of the task.
The /List switch also lists the
base and top addresses, plus the segment text string for each segment.
Because this is an I- and D-space overlaid task, there is an I-space
root segment and a D-space root segment and each is a part of the root
segment of the task MAINO.
In this example, the I-space root segment
begins at disk block 2.
The addresses for the I-space root segment
range from 000000 to 022137.
The next line of numbers is for
the
D-space root segment which begins at disk block 25.
The addresses for
the D-space root segment range from 000000 to 014123.
The next line
of numbers is for the segment INPUT.
That I-space segment begins at
disk block 42 and the D-space segment begins at disk block 64.
The
I-space addresses range from 022140 to 043647 and the D-space
addresses range from 014124 to 015507.
The table continues for
the
remaining overlaid segments in the task MAINMEO.

Example 2:
In this example, the contents of a location in another task module
(TEST.MAC)
are being changed.
The following excerpt from the module
shows the associated code.
TEST - TEST MACRO FILE
1269
1270
1271
1272
1273
1274 010132
1275 010134
1276 010140
1277 010142
1278 010146
1279 010150

MACRO Mlll3

18-MAR-81 07:48

PAGE 8-1

THIS IS A PART OF THE MODULE
TEST.MAC
WHICH IS IN THE ROOT SEGMENT:
TEST
010146
012704
005003
010146
012704

MOV
MOV
CLR
CALL
MOV
MOV

041114

050123

15-20.2

Rl,-(SP)
#"LB,R4
R3
$FNDUB
Rl,- (SP)
#"SP,R4

April 1983

TASK/FILE PATCH PROGRAM (ZAP)

The first command line invokes ZAP and the second command line
requests the segment table for TST.
The /List switch gives the
starting disk block for the root task and for each task overlaid to
the root task. The switch also lists the base and top addresses for
each of the tasks.
In this example, TEST {the root task) begins at disk block 42 and its
addresses range from 120000 to 151513. The next line of numbers is
for the task module TSTCl.MAC.
That task begins at disk block 74 and
its addresses range from 151514 to 153133. The table continues for
the remaining tasks.
Example 2:
In this example, the contents of a location in another task module
{TEST.MAC)
are being changed. The following excerpt from the module
shows the associated code.
TEST - TEST MACRO FILE
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279

MACRO Mlll3

18-MAR-81 07:48

PAGE 8-1

THIS IS A PART OF THE MODULE
TEST.MAC
WHICH IS IN THE ROOT SEGMENT:
TEST
010132
010134
010140
010142
010146
010150

010146
012704
005003
010146
012704

MOV
MOV
CLR
CALL
MOV
MOV

041114

050123

Rl,-{SP)
#"LB, R4
R3
$FNDUB
Rl,-{SP)
#"SP,R4

The sequence of ZAP commands is:
4 2 : 121 2 4 4 ; OR (ffi)
-0, 10136"IB.rn
0 4 2 : 131 4 0 2" LB
I

(ffi)

042:131402' L
I

(ffi)

042:131403' B
120 (5ITl
-0, 10136" (ffi)
042:131402" LP
The first command line loads the starting address of TEST.MAC
(121244
in disk block 42) into Relocation Register o.
The second command line
displays as an ASCII word the contents of location 10136 of the
module.
The contents are LB.
The first apostrophe command (')
displays the first byte of the word
{L)
and the second command
displays the second byte (B). The following command line changes the
contents of the second byte to 120, which is the ASCII code for the
letter P.
The last command displays the new contents of location
10136, which are now LP.
Example 3:
In this example, the contents of a location are also being changed.
This time, the location is in the module TSTVBl.MAC. The following
excerpt is the associated code.

15-21

TASK/FILE PATCH PROGRAM (ZAP)
TSTVBl - TSTVBl MACRO FILE
153
154
155
156
157
158
159
160

MACRO Mlll3

18-MAR-81 07:52

PAGE 4-2

PART OF MODULE TSTVBl.MAC
WHICH IS ALSO IN THE ROOT SEGMENT:
TEST
000334
000336
000340
000346

005702
001404
052767
000403

TST
000060

BEQ
BIS
BR

1 72516

R2
70$
#60, SR3
75$

The sequence of ZAP commands is:
42:133470;1R<RET>
-1,342/<RET>
042:134032/ 000060
lOO<RET>
-1,342/<RET>
042:134032/ 000100
The first command line loads the starting address of TSTVBl.MAC
(133470 in disk block 42)
into Relocation Register 1. The second
command line displays in octal the contents of location 342 in the
module.
The third command line changes the contents of this location
from 60 to 100. The last command line displays the new contents
(again in octal).
Example 4:
In this example, the operation code
(op code)
for one of the
instructions in another module is being changed.
The module is
TSTCM.MAC, and the following excerpt is the associated code.
TSTCM - TSTCM MACRO FILE
402
403
404
405
406
407

MACRO Mll13

18-MAR-81 07:47

PAGE 3-7

PART OF THE MODULE TSTCM.MAC
WHICH IS IN THE SEGMENT: TSTCM
001272
001276
001302

073127
01003 7
062 701

ASHC
MOV
ADD

1 77766
OOOOOG
140002

#-10.,Rl
RO,@#KISAR6
#140000+2,Rl

The sequence of ZAP commands is:
113: 154530; R2 IB_ITl
-2 I 13 0 2/ (B_ITJ

113:156032/ 062701
162701IB_IT1
-2 I 1302/ fill
113:156032/ 162701

x
The first command line loads the starting address of TSTCM.MAC (154530
in disk block 113)
into Relocation Register 2.
The second command
line displays in octal the current instruction contained in location
1302.
The instruction includes the op code 06 for the ADD operation.
The third command line changes the op code to 16, which signifies the
SUBTRACT operation. The fourth command line displays the new contents
of the location and the X command ends the ZAP session.

15-22

TASK/FILE PATCH PROGRAM (ZAP)
15.8

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
segment specified.
User Action: Reenter the command line,
address or overlay segment number.

within

the

overlay

specifying

the

correct

ZAP -- CANNOT BE USED IN BYTE MODE
Explanation: The at sign (@),underscore ( ), and right angle
bracket
(>) commands cannot be used when a-location is opened as
a byte.
User Action:
If the
location as a word.

location

even

address,

open

the

ZAP -- ERROR IN FILE SPECIFICATION
Explanation:

The file specification was entered incorrectly.

User Action: Reenter the command line, using
specification.

the

correct

file

ZAP -- ERROR ON COMMAND INPUT
Explanation: An I/O error occurred while a
being read. This could be a hardware error.

command

line

was

User Action: Ensure that the hardware is functioning properly.
If it is, reenter the command line.
If not, call your DlGITAL
Field Service representative.
ZAP -- I/O ERROR ON TASK IMAGE FILE
Explanation: An I/O error occurred while the file being modified
was being read or written.
This could be a hardware error.
User Action: Ensure that the hardware is functioning properly.
If it is,
reenter the command line.
If not, call your DIGITAL
Field Service repres~ntative.
ZAP -- NO OPEN LOCATION
Explanation:
location.

You attempted to modify the contents

User Action:

Open the location to perform the modification.

15-23

closed

TASK/FILE PATCH PROGRAM (ZAP)
ZAP -- NO SUCH INTERNAL REGISTER
Explanation: The character following a dollar
valid specification for the internal register.
User Action:
value.

Reenter the command line,

sign

was

not

specifying

the

correct

ZAP -- NO SUCH RELOCATION REGISTER
Explanation:
Register.

An invalid number was specified

for

Relocation

User Action: Relocation Registers are numbered 0 through 7. Any
other numbers are illegal. Reenter the command line, specifying
a valid Relocation Register number.
ZAP -- NO SUCH SEGMENT
Explanation: The starting disk block was not the
segment in the task image file on disk.
User Action: Reenter the command line,
disk block address.

specifying

start
the

any

correct

ZAP-- NOT A TASK IMAGE OR NO TASK HEADER
Explanation: An error occurred while the segment tables were
being constructed.
Possibly, the file is not a task image, the
/AB switch was not specified, or the task image is defective.
User Action: Terminate the ZAP session, then
with the /AB switch specified.
ZAP

try

invoking

ZAP

NOT IMPLEMENTED
Explanation: You entered a command that is
but not implemented.
User Action:

recognized

ZAP,

Ensure that you entered the command correctly.

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 specification for errors;
ensure
that the volume is properly mounted; or use PIP to check your
file access privileges (see Chapter 3).

15-24

TASK/FILE PATCH PROGRAM (ZAP)
ZAP -- SEGMENT TABLE OVERFLOW
Explanation: ZAP does not have enough room in its
construct a segment table.

partition

User Action: Install ZAP in a larger partition or with a larger
address space.
(See the description of the INSTALL command in
the RSX-llM/M-PLUS MCR Operations Manual or the RSX-llM/M-PLUS
Command Language Manual.)
ZAP -- TOO MANY ARGUMENTS
Explanation:
are allowed.

You entered more arguments on the command line than

User Action:
syntax.

Reenter the command line,

specifying

the

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, then reenter the command line, specifying the correct
syntax.
ZAP -- VERIFY FAILURE
Explanation: The V command determined that the contents of
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 reenter the command
line.
Ensure that you are correcting the right file or file
version.

15-25

APPENDIX A
COMMANDS AND SWITCHES

A.1

INTRODUCTION

This appendix presents a summary of the commands and switches used by
the RSX-llM/M-PLUS utilities described in this manual.
Each section
number of the appendix corresponds to the chapter discussing that
utility.
For example, Chapter 3 and Section A.3 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

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 to the line preceding the top line
block buffer or input file.

the

BLock[ON] or [OFF]
Switches text access modes.
BO[TTOM]
Sets the current line pointer to the bottom of the
or input file.

block

buffer

[n]Change /stringl/string2[/]
Replaces stringl with string2 n times in the current line
CLose [filespec]
Transfers the rema1n1ng lines in the block buffer and the input
file
into the output file, then closes both the input file and
the output file.
If filespec
is given, the output file is
renamed.

A-1

COMMANDS AND SWITCHES

CLOSES
Closes the secondary input file.
CDL [filespec]
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

Closes files and terminates the editing session.
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.
[-n] is valid in block mode only.
DP [n] or [-n]
Same as DELETE, except that the new current line is printed.
End
Same as the BOTTOM command.
ERASE [n]
Erases the current line or the block
blocks.

buffer

and

the

n-1

Prints the previous line, makes it the new current line, and
<ESCAPE> is the same as
exits from input mode (block mode only).
NP-1.
EXi t

[ filespec]
Closes files, renames the output file, and terminates the editing
session.

EDx [ f ilespec]
Transfers remaining lines in block buffer and
input file to
output file,
and closes the file.
If filespec is given, the
output file is renamed. The command then deletes the input file
and terminates the editing session.
FF
Inserts a form feed into the block
page).

buffer

(used

delimit

file

and

File filespec
Transfers lines from the input file to both the output
the file specified by filespec.

A-2

COMMANDS AND SWITCHES
[n]Find [string]
Finds the line starting with string or, if n
nth line starting with string.

specified,

the

!Nsert [string]
Inserts string immediately following the current line.
is not specified, EDI enters input mode.

If string

KILL

Closes the input and output files, and deletes the output file.
[n]LC /stringl/string2[/]
Changes all occurrences of string! in current line and n-1
to string2.

lines

Prints on the user terminal all lines rema1n1ng
in
buffer or input file, starting with the current line.

the

block

Lists the text in the block buffer or input file
device CL:, starting with the current line.

the

pseudo

LI st

LP
on

[n] Locate string
Searches for string or, if n is specified, the nth occurrence of
string.
In block mode, the search stops at end of the current
block.
MACRO x definition
Defines macro number x to be definition.
2, or 3.

The value x may

MCall
Retrieves macro definitions stored in the file MCALL;n.
[n]Mx [a]
Executes macro x for n times, passing it the numeric argument a.
[n]<definition>

(MACRO IMMEDIATE)

Allows you to define and execute a macro n
The macro is stored as macro number 1.

times

one

step.

lines

from

the

new

current

line

Next [n] or [-n]
Establishes a new current line plus or minus
current line.
NP [n] or [ -n]
Same as NEXT
printed.

command,

except

A-3

that

the

COMMANDS AND SWITCHES

OPens f ilespec
Opens the specified secondary input file.
output [ON] or [OFF]
Continues or discontinues writing to
mode) •

output

file

(line-by-line

Overlay [n]
Deletes the current line and the next n-1 lines, enters input
mode, and inserts new lines as typed in place of original lines.
PAGe [n]
Enters block mode, if not already in block mode, and reads page n
into the block buffer.
[n]PFind (string)
Searches successive block buffers until
the nth occurrence
string is found.
The string must begin in column 1.

[ n] P Locate ( st ring )
Searches successive block buffers for
the nth occurrence
string.
The string can occur anywhere in the line.

PAste /stringl/string2 [/]
Same as the LINE CHANGE (LC) 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.
printed becomes the current line.

The

1 ast

1 ine

REAd [n]
Reads the next n blocks of text into the block buffer.
RENew [n]
Writes the current block to the output file and reads new block n
from the input file (block mode only).

Prints the next line, makes it the current line, and exits
input mode.
Pressing the RETURN key is the same as NP+l.

from

Retype string
Replaces the current line with the text of string.
not specified, the line is deleted.
SAve [nJ

If string

[filespec]

Saves the current line and the next n-1 lines in the file
specified by filespec.
If filespec is not given, the lines are
saved in SAVE.TMP.

A-4

COMMANDS AND SWITCHES
SC /stringl/string2[/]
Locates stringl and replaces it with string2.
SP
Reestablishes the primary file as the input file.
SS
Selects the secondary file that will be the input file.
SIZE n
Specifies the maximum number of lines to be read into
buffer.

the

block

TAb [ON] or OFF
Turns automatic tabbing on or off.
Top
Same as BEGIN command.

In block mode, returns to the top of the input file and saves all
pages edited.
TOF reads in a new block after writing the
previous block to the output file.
TYpe [n]
Prints next n lines.
Same as PRINT command in line-by-line mode.
In block mode,
the current line pointer does not change unless
EOB is reached.
UNSave [filespec]
Inserts all lines from the specified file following
line.
If filespec is not given, SAVE.TMP is used.
UC

the

current

[ON] or OFF
Turns uppercase conversion of lowercase characters on or off.

Verify [ON] or OFF
Specifies whether locator and change commands are verified.
Write
Writes the contents of the current block
file and then erases the block buffer.

A.3

buffer

the

output

PIP COMMAND SUMMARY

outfile=infilel[,infile2 ••• ,infilen]/AP[/FO]
Opens an existing file (outfile) and appends the input file(s)
the end of it.
(/FO is the File Owner subswitch.)

A-5

COMMANDS AND SWITCHES
outfile/BS:n=infilel[ ••• ,infilen]
Defines the block size for magnetic tapes.
outf il e= inf il el [,inf ile 2 ••• , inf i l en] [[/ME] [/subswi tch (es) ] ]
Creates a copy of a file on the same or another device. The /ME
(Merge)
switch creates a new file from two or more existing
files.
Subswitches are one or more of the following:
/BL:n[.]
/CO
/-CO
/FO
/NV
/SU

Block allocated
Contiguous output
Output can be noncontiguous
File Owner
New Version
Supersede

outfile/CD=infilel[,infile2 ••• ,infilen]
outfile=infilel/CD[,infile2 ••• ,infilen]
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) and/or with an output magnetic tape device.
/DD:startdate:enddate
Restricts file searches
per i o d o f t i me •

files

created

during

specified

infilel[,infile2 ••• ,infilen]/DE[/LD]
Deletes files from a UFD.
(/LD is the List Deleted files
subswitch.)
See the sections on Delete
{3.2.2.5)
and Purge
(3.2.2.17) for a complete description of the List Deleted files
subswitch.
ddnn: [ufd]/DF or ddnn:/DF or [ufd]/DF or /DF
Changes the default device and/or UFD for the current PIP task.
outfile=infilel[,infile2 ••• ,infilen]/EN[/NV]
Enters a synonym for a file in a directory or directories on the
same device 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 subswitch.)
infilel/EOF [:block :byte] [ ••• , infilen/EOF [:block :byte]]
Specifies the end-of-file pointers for a file.
f ilespec/EX
Excludes all the files
during a file search.

specified

A-6

with

the

file

specification

COMMANDS AND SWITCHES
outfile=/FI:filenum:seqnum
Accesses an existing file by its file identification number.
[ddnn:] /FR
Displays the amount of available space on a specified volume, the
largest contiguous space on that volume, the number of available
headers, and the number of headers used.
If ddnn:
is not
specified, it defaults to SYO:.
/ID
Identifies the version of PIP being used and if PIP is linked
ANSFCS.

[listfile=]infilel[ ••• ,infilen]/LI[subswitch]
Lists one or more files contained in a
UFO 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 subswitches:
/BR
Brief format
/FU[:n[.]] Full format
/TB
Total blocks format
infilel[,infile2 ••• ,infilen]/sw/NM
Deletes certain PIP error messages, for example, NO SUCH FILE{S).
/sw can be /LI
(List directory), /DE {Delete files), or /PU
{Purge files), or any of their respective subswitches, or /UN
{Unlock files).
inf il e/PR [/SY [: RWED]] [/OW [: RWED]] [/GR [: RWED]] [/WO [: RWED]] [/FO]
Sets the protection status for a file.
/SY
/OW
/GR
/WO
/FO

The switches are:

system access rights
owner access rights
group access rights
world access rights
File owner subswitch

The privileges are:
R

w
E
D

Read
Write
Extend
Delete

You can specify any of the letters in any order.
inf i l e 1 [,inf ile 2 ••• , inf il en] /PU [: n] [/LD]
Deletes a specified range of obsolete versions of a file.
(The
switch never deletes the latest version of a file.) {/LD is the
List Deleted files subswitch.)
A-7

COMMANDS AND SWITCHES

outfile=infilel[,infile2 ••• ,infilen]/RE[/NV]
Changes the name of a file with an option to
force the version
number of outfile to be one greater than the latest version for
the file.
(/NV is the New Version subswitch.)
infilel[,infile2 ••• ,infilen]/RM
Removes an entry from a UFO,
associated with that entry.

but

does

not

delete

the

file

outf ile/RW=infile or outf ile=infile/RW
Rewinds a magnetic tape. When you specify /RW with the output
file specification, PIP begins writing the file at the beginning
of the tape.
When you specify /RW with the input
file
specification, PIP rewinds the tape before searching for the
input file.
outdsk:outfile/SB=inmag:infile
The file copied to disk from magnP.tic tape may have records
crossing block boundaries.
(/SB is the default.) If you specify
/-SB, the records will not cross block ~oundaries.
infilel[,infile2 ••• ,infilen]/SD
Prompts for user response before deleting files.
infilel[,infile2 ••• ,infilen]/SP[:n]
Specifies a list of files to be printed on a line printer
the number of copies) •

Allows shared reading of a file that has already been opened
writing.

for

outf ile=infile/SR

/TD
Restricts file searches to files created on the current day.
infilel[,infile2 ••• ,infilen]/TR
Truncates files to their logical end-of-file point.
outfile/UF[/FO]=infilel[,infile2 ••• ,infilen]
Creates a User File Directory entry in the Master File
of the volume specified with outfile.

A-8