Digital PDFs

AA-H781A-TE

March 1980

225 pages

Original

9.4MB

Document:	VAX-11 Utilities Reference Manual
Order Number:	AA-H781A-TE
Revision:	000
Pages:	225
Original Filename:

OCR Text

VAX-11
Utilities Reference Manual
Order No. AA-H781 A-TE

March 1980
This document describes utility programs for use on VAX-11 processors.

VAX-11
Utilities Reference Manual
Order No. AA-H781 A-TE

SUPERSESSION/UPDATE INFORMATION: This is a new document for this release.
Chapter 3 supersedes and replaces Chapter 3
and Appendixes C and D of the VAX-11 Text
Editing Reference Manual. Chapter 4
supersedes and replaces the VAX-11 Disk
Save and Compress User's Guide
OPERATING SYSTEM AND VERSION:

VAX/VMS V02

SOFTWARE VERSION:

VAX/VMS V02

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, March 1980
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 only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

1980 by Digital Equipment Corporation

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

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
CO MT EX
DDT
DEC COMM
ASSIST-11
VAX
DECnet
DATATRIEVE

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

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

CONTENTS

Page
ix

PREFACE
CHAPTER

PERSONAL MAIL UTILITY

1.1
INV OK ING MAIL
l. 2
MAIL COMMANDS
l . 2 .1
BACK Command
DELETE Command
l . 2. 2
DIRECTORY Command
l . 2. 3
l . 2. 4
EXIT Command
1. 2. 5
FILE Command
l . 2. 6
FORWARD Command
l . 2. 7
HELP Command
NEXT Command
l . 2 .8
PRINT Command
l . 2. 9
READ Command
1.2.10
1.2.11
REPLY Command
1.2.12
SEND Command
1.2.12.l Sending Messages via DECnet-VAX
1.2.12.2 Sending Messages to Distribution Lists
l. 3
MESSAGE FILES
1.4
SYSTEM MANAGEMENT AND MAIL
MAIL STATUS MESSAGES
1.5
CHAPTER

CHAPTER

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

1-n

1-7
1-7
1-8
1-9
1-10
1-10
1-10

FILE TRANSFER UTILITY

2-1

2.1
2.2
2.3
2.3.l
2.3.2
2.3.3
2.4
2.5
2.5.l
2.5.2
2.6
2.6.l
2.6.2
2.6.3
2.7

INVOKING AND TERMINATING FLX
FLX COMMAND STRING
FLX QUALIFIERS
Volume Format Qualifiers
Transfer Mode Qualifiers
Control Qualifiers
TRANSFERRING FILES WITH FLX
DOS-11 VOLUME DIRECTORY MANIPULATION
Displaying DOS-11 Directory Listings
Initializing DOS-11 Volumes
RT-11 VOLUME DIRECTORY MANIPULATION
Displaying RT-11 Directory Listings
Initializing RT-11 Volumes
Deleting RT-11 Files
FLX MESSAGES

2-2
2-2
2-4
2-4
2-5
2-6
2-9
2-9
2-9
2-10
2-10
2-10

SLP AND SUMSLP EDITING UTILITIES

3-1

SLP
3.1
Invoking SLP
3. l. l
Running SLP Indirectly
3. l. 2
The Input Source File
3.1.2.l
3.1.2.2
The SLP Command File

iii

2-11

2-12
2-12

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

CONTENTS

Page
3.1.2.3
The Output File
3.1.2.4
The Listing File
3.1. 3
Running SLP Interactively
3. J... 4
How SLP Processes Files
3 .1. 5
SLP Qualifiers
3.1.5.1
Using the /AUDIT TRAIL Qualifier
3.1.5.2
Using the /CHECKSUM Qualifier
3.1.5.3
Using the /NOOUTPUT and /LIST Qualifiers
3 .1. 6
Specifying SLP Editing Commands
3.1.6.1
SLP Operators
3.1.6.2
General Form of an Editing Command
3.1.6.3
Adding Lines to a File
3.1.6.4
Deleting Lines from a File
3.1.6.5
Replacing Lines in a File
3.1.6.n
Specifying the Audit Trail Text
3.2
SUMS LP
3.2.l
Running SUMSLP

3.2.2

SUMSLP Input And Output Files

3.2.2.1
The Input Source File
3.2.2.2
The SUMSLP Command Files
3.2.2.3
'l'he Output File
3.2.2.4
'rhe Listing File
3.2.3
How ~UMSLP Processes Files
3.3
SLP and SUMSLP MESSAGES
3.3.1
SLP Messages
3.3.1.1
SLP Information Messages
3.3.1.2
SLP Error Messages
3.3.2
SUMSLP Messages
3.3.2.1
SUMSLP Information Message
3.3.2.2
SUMSLP Error Messages

CHAPTER

DISK SAVE AND COMPRESS UTILITIES

TYPICAL USES FOR DSC UTILITIES
Backing Up the VAX/VMS System Disk
Backing Up Public or Private Disk Volumes
Compressing the Files on a Public or
Private Disk Volume
4 .1. 4
Regulating Disk Bad Block Information
4 .1. 5
Comparing the Contents of Two Volumes
4 .1. 6
Transporting Volumes
4 .1. 7
Device Transfers Supported by DSC Programs
4.2
SPECIFYING DSC COMMANDS
4.2.1
Invoking and Terminating Online DSCl and
DSC2
4.2.2
Invoking and Terminating Stand-alone DSC-2
4.2.3
Specifying the DSC Command String
4.3
USING DSC PROGRAMS
4.3.l
Setting Up for DSC Operations
4.3.2
Using File Labels
4.3.3
Using the Verify Qualifier
4.3.4
Using the Density Qualifier
4.3.5
Using the Rewind Qualifier
4.3.6
Using the Append Qualifier
4.3.7
Using the Compare Qualifier
4.3.8
Using Bad Block Qualifiers
4.3.8.1
Using the /BAD=MAN Qualifier
4.1
4 .1.1
4 .1. 2
4 .1. 3

3-4
3-4
3-4
3-4
3-fi
3-7
3-8
3-9
3-9
3-9
3-10
3-11
3-13
3-14
3-15
3-15
3-15
3-17
3-17
3-17
3-17
3-18
3-19
3-19
3-19
3-19

3-20
3-24
3-24

3-24
4-1

4-2
4-2

4-3
4-3
4-3
4-4
4-4
4-5
4-5
4-5
4-5
4-6
4-8
4-8
4-9
4-10
4-11
4-11
4-12
4-13
4-14
4-14

CONTENTS

Page
4.3.8.2
Using the /BAD=NOAUTO Qualifier
Using the /BAD=MAN:NOAUTO Qualifier
4.3.8.3
4.4
AUXILIARY PROCEDURES FOR DSC OPERATIONS
4. 4. 1
Translating File Identifications into File

4-15

4.5
4.5.1
4.5.2
4.5.3
4.5.4

Specifications
Converting Disk Addresses to Logical
Block Numbers
DSC MESSAGES AND ERROR RECOVERY PROCEDURES
DSC Message Categories
Interpreting DSC Messages
DSC Messages
DSC I/O Error Messages

BAD BLOCK LOCATOR UTILITY

5-1

5.1
5 .1.1
5 .1. 2
5.1.2.l
5.1.2.2
5.2
5.3
5.4
5.4.1

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

5.4.2
5.5
5.5.1
5.5.2
5.5.3
5.5.4
5.5.5
5.6

LOCATING AND RECORDING BAD BLOCKS
Locating Bad Blocks
Recording Bad Blocks
Location of the Bad Block Descriptor
Format of the Bad Block Descriptor
ALLOCATING BAD BLOCKS
INVOKING AND TERMINATING BAD
BAD COMMAND STRING
Running BAD Interactively from Your
Terminal
Running BAD from Command Procedures
BAD QUALIFIERS
The List Qualifier
The Manual Qualifier
The Override Qualifier
The Retry Qualifier
The Update Qualifier
BAD MESSAGES

FILE STRUCTURE VERIFICATION UTILITY

6-1

6.1
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.3
6.4
6.5
6.5.1
6.5.2
6.5.3
6.5.4
6.5.5
6.5.6
6.5.7
6.6

VALIDITY CHECKING
FILE ERROR RECOVERY
Restoring Files Marked for Deletion
Deleting Multiply-Allocated Blocks
Eliminating Free Blocks
Recovering Lost Blocks
INVOKING VFY
VFY COMMAND STRING
VFY QU'ALIFIERS
The Delete Qualifier
The Free Qualifier
The List Qualifier
The Lost Qualifier
The Read Check Qualifier
The Rebuild Qualifier
The Update Qualifier
VFY MESSAGES

n-1
n-3

LIBRARIAN UTILITY

7-1

7.1
7 .1.1

LIBRARIES
Types of Libraries

7-1
7-1

4.4.2

CHAPTER

4-15
4-15
4-15

4-Hi
4-17
4-17
4-18
4-19
4-31

5-4
5-5

5-n
5-n
5-n
5-8
5-8
5-8
5-9

h-3

n-4
n-4
n-4
n-5
n-n
f1-n

n-7
Fi-7
ri-7
Fi-8
f;-8

n-9
n-9
n-10

CONTENTS

Page
Structure of Library Indexes
THE DCL LIBRARY COMMAND
Library Command String
Command Qualifiers
HE.LP LIBRARIES
Creating Help Files
Formatting Help Files
Help Message Example
LIBRARIAN ROUTINES
LBR$CLOSE - Close a Library
LBR$DELETE DATA - Delete Text Records
LBR$DELETE-KEY - Delete a Key
LBR$FIND --Lookup a Key by its RFA
LBR$GET HEADER - Retrieve Library Header
Information
7.4.6
LBR$GET HELP - Return Help Text
7.4.7
LBR$GET INDEX - Return the Contents of an
Index 7.4.8
LBR$GET RECORD - Read a Text Record
7.4.9
LBR$INI CONTROL - Initialize a Library
Index 7.4.10
LBR$INSERT KEY - Insert a New Key
7.4.11
LBR$LOOKUP-KEY - Lookup a Library Key
LBR$0PEN --Open a Library
7.4.12
7.4.13
LBR$PUT END - Terminate a Text Sequence
Written to a Library
7.4.14
LBR$PUT RECORD - Write a Text Record
7.4.15
LBR$REPLACE KEY - Change Text Pointer or
Insert New Key
7.4.16
LBR$SEARCH - Search an Index
7.4.17
LBR$SET INDEX - Set the Primary Index
Number 7.4.18
LBR$SET MODULE - Read or Update a Module
Header
7.5
EX.AMPLE OF LIBRARIAN ROUTINES
7.6
MESSAGES FOR LIBRARY COMMAND AND LIBRARIAN
ROUTINES
7.6.1
Messages For Library Command
7.6.1.1
Informational Messages
7.6.1.2
Success Messages
7.6.1.3
Warning Messages
7.6.1.4
Error Messages
7.6.1.5
Severe Error Messages
7.6.2
Librarian Routines Messages
7.6.2.1
Success Messages
7.6.2.2
Warning Messages
7.6.2.3
Error Messages

7 .1. 2
7.2
7.2.1
7.2.2
7.3
7.3.1
7.3.2
7.3.3
7.4
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5

CHAPTER

MESSAGE UTILITY

7-2
7-2
7-3
7-4
7-13
7-13
7-13
7-15
7-18
7-20
7-21
7-22
7-23
7-24
7-26
7-28
7-30
7-31
7-33
7-34
7-35
7-38
7-39
7-40
7-42
7-44
7-45
7-47
7-57
7-57
7-57
7-57
7-58
7-59
7-IS4
7-64
7-64
7-n4
7-66
8-1

8.1
THE FORMAT OF MESSAGES
8.2
THE MESSAGE CODE AND THE MESSAGE SYMBOL
8.3
CONSTRUCTING MESSAGES
8.3.1
The Message Source File
8.3.1.1
The Facility Definition
8.3.1.2
The Severity Definition
8.3.1.3
The Message Number Specifier

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

8-n

8-7

CONTENTS

Page
8.3.1.4
The Message Definition
8.3.1.5
The Literal Directive
Listing Directives
8.3.1.6
The End Statement
8.3.1.7
8.3.1.8
Sample Message Source File
Compiling the Message Source File
8.3.2
8.3.3
Linking the Message Object Module
8.3.4
Running a Program with Messages
8.4
CHANGING MESSAGES
8.4.l
Pointers to Message Data
8.4.2
The SET MESSAGE Command
8.5
MESSAGE UTILITY MESSAGES

APPENDIX A

FILES-11 DEVICES SUPPORTED BY VAX/VMS

INDEX

8-7
8-9
8-10
8-10
8-10
8-11
8-13
8-14
8-:-15
8-15
8-10
8-18

A-1
Index-1

FIGURES
FIGURE

1-1
2-1
2-2
3-1
6-1
7-1
7-2
8-1
8-2
8-3

MAIL Message File
DOS-11 Directory Listing
RT-11 Directory Listing
Files Used During SLP Processing
VFY Index File Listing
Help Messages for LIBRARY Command
HELP LIBRARY Display
Message Code
Linking a Message Object Module
Creating a Message Pointer

1-1
2-9
2-10
3-2
6-8
7-15
7-ln
8-3
8-14
8-16

TABLES
TABLE

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

A-1
A-2

Summary of MAIL Commands
SEND and REPLY Qualifiers
FLX Volume Format Qualifiers
FLX Transfer Mode Qualifiers
FLX Control Qualifiers
SLP Qualifiers
SLP Operators
SUMSLP Qualifiers
DSC Output File Qualifiers
Error Codes in DSC Messages
BAD Qualifiers
VFY Qualifiers
LIBRARY Command Qualifier Compatibilities
Librarian Routines
Library Header Information Array Offsets
Create-Options Array
Facility Definition Qualifiers
Message Definition Qualifiers
MESSAGE Command Qualifiers
SET MESSAGE Qualifiers
Magnetic Tape Devices
Disk Devices

vii

1-3
1-8
2-4
2-5
2-7
3-6
3-9
3-16
4-7
4-18
5-6
Fi-7

7-5
7-19
7-24
7-3n
8-n
8-8
8-12
8-17

A-1
A-2

PREFACE

This reference manual describes utility programs supported by
on the VAX/VMS operating system.

DIGITAL

INTENDED AUDIENCE

This manual is intended for users who are already familiar with
VAX/VMS system concepts.
Use of the various utility programs is
appropriate for users at different levels
of
experience
and
responsibility.
The expected user group for each program is defined
below in the chapter summaries.

STRUCTURE OF THIS DOCUMENT

This manual is organized into eight chapters and one appendix.
Each chapter of this manual describes one utility program, except for
Chapter 3, which includes two related editors
(SLP and SUMSLP),
Chapter 4 includes three variants of a disk back-up program (DSC)
and
Chapter 6 describes two variants of a verification utility. Each
chapter contains a list of the messages issued by the utility.
The
following are the contents and intended audience of each chapter.
Chapter 1 describes the Personal Mail Utility, referred to as MAIL.
This program allows users to send messages to one another, within the
same system or between any VAX-11 computers that are connected by
means of DECnet-VAX. Use of MAIL is appropriate for all system users.
Chapter 2 describes the File Transfer Utility, referred to as FLX (and
generally pronounced 'FILEX'). This program transfers files from one
volume to another and performs volume format conversions.
FLX is
intended for use by all system users.
Chapter 3 describes two related batch-oriented text editors, SLP and
SUMSLP.
These editors are used to incorporate changes into source
files and to indicate these changes with an audit trail.
SLP and
SUMSLP are intended for use by all system users.
Chapter 4 describes the Disk Save and Compress Utilities, referred to
as DSCl, DSC2, and DSC-2 (stand-alone). The DSC programs are used to
back up and restore disk volumes that have been formatted and
initialized as Files-11 volumes.
These programs are intended for
VAX/VMS system
managers,
operators,
system
programmers,
and
application programmers.

Chapter 5 describes the Bad Block Locator Utility, referred to as BAD.
This program determines and records the number and location of bad
blocks on block-structured volumes.
BAD is intended for use by
VAX/VMS system managers, operators, and system programmers.
Chapter 6 describes the File Structure Verification
Utilities,
referred to as VFYl and VFY2 (and pronounced 'VERIFY'). This program
checks the readability and validity of Files-11 volumes.
It is
intended for use by VAX/VMS system managers, operators, and system
programmers.
Chapter 7 describes the Librarian Utility, referred to as the
Librarian.
This program allows you to store useful modules in a
central, easily accesBible location. It is intended for use by all
VAX/VMS users.
Chapter 8 describes the Message Utility. This program allows you to
construct your own informational, warning, and error messages, or to
customize the messages provided by VAX/VMS. The Message Utility is
intended for use by VAX/VMS system programmers and application
programmers.
Appendix A lists the Files-11 structured devices supported by VAX/VMS,
with the characteristics and device code of each device. It presents
information needed by users of several of the utilities in this
manual.

ASSOCIATED DOCUMENTS

To use the utilities described in
familiar with the following manuals:

this

document,

•

VAX/VMS Primer

•

VAX/VMS Command Language ___Y. ~~-I.~.§. __G_l!J~.~

Some of the utilities require familiarity with disk
volume concepts described in the following manuals:

•

Introduction to y_~X-_!}

•

VAX-11 Record

~~cord Ma!'?Cl_9~1-!1~~!:

~-!:1. ~9-~E:1_(::!nt

Services

you

should

structures

and

Services

13~~~E~_nc~_anual

Some of the utilities run in compatibility mode;
cons u 1 t the VAX-11 /RS~_-::__!_! M Us~-r:~-~----~-~-!~e- •

readers may wish

Note that there are other utility programs that run on VAX-11
processors - PATCH and the System Dump Analyzer, for example. These
programs are described elsewhere in the VAX-11 documentation set. For
a complete list of VAX-11 documents, including a brief description of
each, see the VAX-11 Information Directo
and Index.

CONVENTIONS USED IN THIS DOCUMENT
The following conventions are observed in this manual, as in the other
VAX-11 documents:

Meaning

Convention

used in
type the

Uppercase words
and letters

Uppercase
words
and
letters,
examples, indicate that you should
word or letter exactly as shown.

Lowercase words
and letters

Lowercase words and letters, used in format
examples, indicate that you are to substitute
a word or value of your choice.

quotation marks
apostrophes

The term quotation marks is used to refer to
double quotation marks
(").
The
term
apostrophe
(')
is used to refer to a single
quotation mark.
Square brackets indicate
item is optional.

{}

that

Braces are used to enclose lists
one element is to be chosen.

the

enclosed

from

which

A horizontal ellipsis indicates that the
preceding item(s) can be repeated one or more
times.
A vertical ellipsis indicates that not all of
the statements in an example or figure are
shown.
~

or <RET>

A
symbol
with
a
1to
3-character
abbreviation indicates that you press a key
on the terminal, for example, ~ •

(QIBIJ~

or <CTRL/x>

The phrase <CTRL/x> indicates that you must
press
the
key
labeled CTRL while you
simultaneously press another key, for example
<CTRL/C>, <CTRL/Y>, <CTRL/O>. In examples,
this control key sequence is shown as Ax, for
example AC,
AY, Ao, because that is how the
system echoes control key sequences.

Unless otherwise noted, all numeric values are represented in
notation.
Unless otherwise specified, you terminate
RETURN key.

commands

decimal

pressing

the

Where the term file-spec is used in this document, it refers to a file
specification constructed according to the following definitions, with
the format:
node::device: [directory]filename.type;version
The punctuation
required syntax
specification.

marks
(colons, brackets, period, semicolon) are
that separate the various components of the file

node
A network node name.
support DECnet-VAX.

This is applicable

only

systems

that

device
The device on which the file is stored or is to be written.
directory
The name of the directory under which the file is cataloged on
the device specified.
You can delimit the directory name with
square brackets, as shown, or with angle brackets (<>).
filename
The file by a name of up to 9 alphanumeric characters.
type
The type of data in the file;
characters.

type can be up to

alphanumeric

version
The version of the file. Versions are identified by a decimal
number, which is increased by 1 each time a new version of the
file is created. Either a semicolon or a period can be used to
separate type and version.
You need not always state all elements of a file specification
explicitly.
Frequently, only the file name is required. If you omit
other parts of the file specification, a default value is provided as
described in the following table.
Optional Element

Default Value

node

Local network node

device

User's current default device

directory

/RS)

I/O

User Action: The following responses correspond (by
the conditions listed above.

were

operation
number)

Write-enable the volume.

Respecify the volume format qualifiers
correctly.

No recovery is possible with the volume currently mounted.
Mount a volume that is in the proper format, and retry the
operation.

Retry the operation.

(/DO,

/RT,

/RS)

FLX -- FILE NOT FOUND
Explanation: The named file does not appear as specified in
requested directory.

the

User Action: Retry the operation
directory correctly specified.

and

2-13

with

the

file

name

FILE TRANSFER UTILITY
FLX -- @ FILE NESTING EXCEEDED

Explanation:
specified.

More than one level of indirect

command

file

was

User Action: Retry the operation with only one level of indirect
command file specified.
FLX -- @ FILE SYNTAX ERROR

Explanation: A syntax error occurred
file specification.

the

User Action: Edit the indirect command file.
the corrected indirect command file.

indirect
Rerun

FLX

command
using

FLX -- FMTD ASCII RECORD FORMAT BAD

or
FLX -- FMTD BINARY RECORD FORMAT BAD

Explanation: Either the file is corrupted, or the file is not of
the specified type.
User Action: If the file is corrupted, no recovery is possible.
If the file type is incorrect, retry the operation specifying the
correct transfer mode switch.
FLX -- 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:
spec i f i ed.

Reenter

the

command

line

with

legal

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

Reenter the

file

2-14

specification

with

the

proper

FILE TRANSFER UTILITY

FLX -- INVALID SYNTAX
Explanation: A qualifier was entered that is not
qualifier or does not conform to proper syntax.
User Action: Reenter the command line with a
specification.

valid

correct

FLX

qualifier

FLX -- I/O ERROR
Explanation:

One of the following conditions may exist:

•

The specified device is offline.

•

A hardware error occurred (for example, a bad tape}.

User Action: Ensure that the device is online.
Reenter the
command line. If a hardware error occurred, recovery may not be
possible.

FLX -- I/O ERROR INITIALIZING DIRECTORY
Explanation:

One of the following conditions may exist:

•

The specified directory is not online.

•

The specified volume is not mounted.

•

A hardware error occurred (for example, a bad tape).

User Action: Ensure that the device is online and is operable.
Reenter the command line with the required qualifier specified.
If a hardware error occurred, recovery may not be possible.

FLX

I/O ERROR ON COMMAND INPUT
Explanation: An unexpected
error
in
command
input
encountered
from either an indirect command file or
terminal; FLX exits.
user Action:

was
your

Restart FLX.

FLX -- I/O ERROR ON FLX TEMPORARY FILE
Explanation: FLX encountered an error condition
with
its
temporary file.
FLX creates a temporary file on your default
disk for operations involving DOS-11 magnetic tape.
This error
occurs when one of the following conditions exists:

•

Your default disk is not online and mounted.

•

Your default disk is write-locked.

•

A protection violation occurred.

•

A hardware error was encountered.

User Action:

Correct the condition and reenter the command line.

2-15

FILE TRANSFER UTILITY

FLX -- I/O ERROR ON LIST FILE
Explanation: An error occurred on the output device during a /DI
or /LI sequence.
There is a hardware problem with the output
device (for example, device powered down).
User Action:

Correct the condition and reenter the command line.

FLX -- OUTPUT DEVICE FULL
Explanation: The DOS-11 or RT-11 output volume does not
enough space for the output file.
User Action:
command line.

Delete

all

unnecessary

files

and

contain

reenter

the

FLX -- OUTPUT FILE SPEC NOT ALLOWED
Explanation: An output file specification
command that does not allow one.
User Action: Reenter
specification.

the

command

was

entered

output

without

for

file

FLX -- RECORD TOO LARGE
Explanation: FLX detected an input record in a Files-11 transfer
that is larger than the specified or implied record size for the
file, that is, the file is corrupted.
User Action:

The file in question is unusable.

FLX -- WARNING -- SPECIFIED RECORD SIZE BAD, 512.

USED

Explanation: The record size n specified with /FA:n, /FB:n, or
/IM:n is not acceptable.
A record size of 512Jl0) 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.
User Action:
command line.

Delete

all

unnecessary

2-10

the

DOS-11

files

and

Files-11

reenter

the

FILE TRANSFER UTILITY

FLX -- UNABLE TO OPEN FILE
Explanation: A specified Files-11 input or output 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 directory listing file cannot be opened under
the specified file name and directory, or the specified device
may not be a valid Files-11 volume.
User Action: Reenter the command
file name and directory.

line

specifying

the

correct

FLX -- UNDIAGNOSABLE REQUEST
Explanation:

FLX does not recognize the command line syntax.

User Action:

Reenter the command line with the proper syntax.

FLX

/CO FILES FROM INPUT DEVICE NOT ALLOWED UNLESS /BL:

SPEC

Explanation: When transferring files from magnetic tape, /CO can
only be specified when /BL is also specified.
User Action:

FLX --

Reenter the command line, specifying /BL.

* IN OUTPUT UIC NOT ALLOWED

Explanation: A wild card character was detected
identification code for the output volume.
User Action:
Reenter the command line
characters in the output specifications.

FLX

without

the

user

wild

card

* IN VERSION NUMBER NOT ALLOWED
Explanation: A wild card character was detected in
number field of a file specification.
User Action: Reenter the command line with all
explicitly specified.

2-17

the

version

numbers

CHAPTER 3
SLP AND SUMSLP EDITING UTILITIES

SLP and
Two batch-oriented text editors run on VAX-11 processors:
SUMSLP. To use either of these editing utilities, you generate a list
The
of the changes which you want to apply to your source file.
utilities effect these changes and produce an edited output file.
This chapter describes how to use these editors.

3.1

SLP

SLP is a batch-oriented editing program used for source
file
maintenance.
The term "SLP" originally meant "source language input
program." SLP allows·you to update (delete, replace, add) lines in an
existing file.
Furthermore, SLP gives you a record (audit trail) of
editing changes. The SLP command file provides a reliable way to
duplicate the changes made to a file, at a later time or on another
computer system.
Input to SLP consists of (1)
an input source file that you want
updated, and (2) a command fil~ containing text lines and edit command
lines that specify the update operations to be performed. SLP locates
lines to be changed by means of "locators" (sequence numbers or
character strings).
SLP output is an updated copy of the input source file. SLP provides
an audit trail that helps you keep track of the update status of each
line in the file. The audit trail is included permanently in the
output file. When a given file is updated with successive versions of
SLP command file, you can use different audit trails to differentiate
among the changes made at different times.
SLP output qualifiers modify the appearance of the output file.
They
let you truncate lines, create or suppress an audit trail, eliminate
an existing audit trail, create checksums, and specify the length and
beginning position of the audit trail.

3.1.1

Invoking SLP

You can run SLP either indirectly or interactively.
you invoke SLP with the command line:

either

case,

EDIT/SLP [/qualifiers(s)] infile-spec
qualifier(s)
Actions to be performed by SLP that control the generation
format of the listing and output files (see Section 3.1.4).

3-1

and

SLP AND SUMSLP EDITING UTILITIES
infile-spec
The input source file specification {see Section 3.1.2.1).
When you run SLP indirectly from a SLP command file, this command
line, preceded by a dollar sign {$), is the first line of the file, as
described in Section 3.1.2.2.
When you run SLP interactively, this command line is typed in response
to the DCL prompt {$), as described in Section 3.1.3.

3.1.2

Running SLP Indirectly

SLP requires two types of input files: an input source file and a SLP
command file.
These files are described in Sections 3.l.2.1 and
3.1.2.2.
The output file, described in Section 3.1.2.3, is the permanently
updated copy of the input file.
It shows the changes SLP makes to the
input file.
You can also generate a listing file, described in Section 3.1.2.3.
Figure 3-1 shows the relationships among the SLP output and input
files. The contents of the various files in this figure are described
in the following sections.
Listing File

Input File

MYFI LE.LIS;1

MYFI LE.TST;1

,____(
SLP
Processor

Command File

UPDATE.COM;1

Figure 3-1

Output File

MYFI LE.TST;2

Files Used During SLP Processing

3-2

SLP AND SUMSLP EDITING UTILITIES
3.1.2.1 The Input Source File - The input source file is the file
be updated by SLP. It can contain any number of lines.

To use SLP effectively, you should obtain a sequence-numbered listing
of the input file from which you can determine what editing commands
you will issue. Section 3.1.5.3 describes how to generate such a
listing using the /LIST qualifier. However, the input source file
actually updated by SLP can have any kind of line numbers.

3.1.2.2 The SLP Command File - The SLP command file is a VAX/VMS file
that contains SLP editing commands. It consists of four elements:
1.

An initialization line that invokes SLP
file to process:
$ EDIT/SLP [/qualifiers]

and

specifies

what

infile-spec

This command line is described in Section 3.1.1.
2.

SLP editing command lines that define changes
file (see Section 3.1.n).

the

input

Input lines, that is, lines of text that are to be inserted
into the output file, either as new lines or to replace old
lines.

The SLP terminator, a single slash
(/)
in column 1, that
causes SLP to begin its processing (updating) of the file.

An interactive text editor is usually used to create SLP command
files.
Once you have created the file,
you can submit it for
processing by using the DCL commands Execute Procedure (@) or SUBMIT.
The example below shows a SLP command file named UPDATE.COM.
The
numbers to the right of the example correspond to the elements listed
above.

S EDIT/SLP MYFILE.TST

(1)

-3

(2)

INSERT THIS LINE AFTER LINE 3

C3)

-4Y4

(2)

DELETE LINE 4 AND REPLACE IT WITH THIS LINE

(3)

<4)

You can execute this file by using the Execute Procedure (0)
as follows:

command,

$ @UPDATE

Because the file type is the default file type COM, it can be omitted
on the DCL command line.
See the VAX/VMS Command Language User's
Guide for information on using command procedures and running batch
jobs.
When SLP finishes its processing, the DCL prompt is issued:
$

You can request that SLP calculate a checksum value for SLP editing
commands and then use this value to determine whether you have made
the correct changes to your source file. See Section 3.1.4.2 for a
description of calculating checksums.

3-3

SLP AND SUMSLP EDITING UTILITIES
3.1.2.3 The Output File - The SLP output file is the updated input
file.
All of the updates specified by the SLP editing commands are
inserted in this file. An audit trail is applied, by default unless
suppressed, to new or changed lines (see Section 3.1.4). You can also
specify the text and length of an audit trail (see Section 3.1.n.n).
An output file is generated by default. You can suppress the output
file, however, by using the /NOOUTPUT qualifier, described in Section
3.1.4.2.

3.1.2.4 The Listing File - You can generate a listing file by using
the /LIST qualifier, described in Section 3.1.4.3. The listing file
shows the changes made to the source file. Each line in the listing
file shows the updates made to the source file. Each line in the
listing is numbered in sequence. Updates are indicated by means of an
audit trail
(unless you suppress audit-trail generation). Section
3.1.5 contains an example of a listing file.
A sequence-numbered listing of the input file can help you determine
what editing commands to use. Generating this listing is described in
Section 3.1.4.3.

3.1.3

Running SLP Interactively

To use SLP interactively, type the following command line in
to the DCL prompt:
$ EDIT/SLP [qualifier (s)]

response

infile-spec

If you do not enter the input source file specification, you
prompted for it with the prompt:

will

File:
After specifying the input source file specification, enter SLP
editing commands, one per line. Then enter the SLP terminator in the
first column of the next line.
The utility will res~ond to the
terminator with the prompt:
SLP>
To end the interactive SLP editing session, type <CTRL/Z> in
to the SLP> prompt.

3.1.4

response

How SLP Processes Files

This section uses an example to show how SLP processes files.
the following source input file, named MYFILE.TST;l.

ONE
TWO
THl:~EE

Fnu1:::

FIVE
SIX
SEVEN
EIGHT
NINE
TEN

3-4

It uses

SLP AND SUMSLP EDITING UTILITIES
This file is to be updated under the control of the following SLP
command file, named UPDATE.COM.
The editing commands used in the
command file are described in Section 3.1.6.

SEDIT/SLP/AUDIT_TRAIL:50/LIST

MYFILE.TST

.... 3

INSERT THIS LINE AFTER LINE 3

.... 4,..4

DELETE LINE 4 AND REPLACE IT WITH THIS LINE
I

Below is the listing file (MYFILE.LST) that results from
command @UPDATE.

issuing

the

MYF ILE. TST /AU: ~::;o. : t (). ,. MYF I l... E::::MYF I LE. TST

ONE
TWO

~5.

THl:~EE

INSERT THIS LINE AFTER LINE THREE
DELETE LINE 4 AND REPLACE IT WITH THIS LINE
FIVE
SIX
SEVEN
EIGHT
NINE
TEN

5.
6.
7.

8.
9+
:1.0.
:I. :L.

'**NEW**
v**NEW**
v** .... :t.

The audit trail, using the default audit trail texts described in
Section 3.1.5, shows the new lines (;**NEW**) and indicates where
lines have been removed (;**-1). In this case, a new line has been
added after line 3, and line 4 has been replaced, causing all
subsequent lines to be renumbered. The /AUDIT TRAIL qualifier in the
initialization line indicates that the audit trail is to begin at the
next tab stop after column 50.
To process the files, SLP writes each line from the input source file
into the output file until it reaches a line to be modified, as
requested in the command. When SLP reaches a line to be modified,
it
makes the indicated modification, notes the change in the audit trail,
and then continues writing lines to the output file,
in sequence,
until it encounters another command or reaches the end of the source
file.
The output file, MYFILE.TST;2, is as follows:

ONE
TWO
THF~EE

INSERT THIS LINE AFTER LINE 3
DELETE LINE 4 AND REPLACE IT WITH THIS LINE
FIVE
SIX

SEVEN
EIGHT
NINE
TEN

3-5

'**NEW**
'**NEW**

;** . . :I.

SLP AND SUMSLP EDITING UTILITIES
3.1.5

SLP Qualifiers

SLP qualifiers control the generation and format of the listing file
and the output file. You can use them to control the audit trail and
output options associated with these files. Table 3-1 describes the
SLP qualifiers and their functions. The following sections illustrate
the use of SLP qualifiers.
Table 3-1
SLP Qualifiers

---------r---------------···-Format

Function

.._._ _ _ _ _ _ _ _ _ _ · - - - - - · - + - - · - - - - · -. - · - - - - - · - - - -

/AUDIT TRAIL
[: (POSlTION:pos,SIZE:len)]
and /NOAUDIT_TRAIL

These qualifiers let you suppress
audit-trail
generation,
or
specify the beginning position and
length of the audit trail. The
de£ault is to generate an audit
trail 8 characters long, starting
in
column
80 -- that
is 1
/AUDIT_TRAIL: (POSITION:80,SI2E:8).
The maximum allowed value for
length parameter is l~.

the

The audit trail starts at the
first tab stop after the position
given (or defaulted)
for
the
/AUDIT TRAIL qualifier. Tab stops
are set every 8 columns.
/CHECKSUM [:n] and /NOCHECKSUM

The /CHECKSUM qualifier requests a
checksum calculation for SLP edit
commands. If you do not specify a
checksum value, SLP reports the
calculated
checksum
at
your
terminal.
If you do specify a
value,
SLP
will
generate
a
diagnostic
message
if
the
specified values does not match
the
checksum calculation.
The
default is /NOCHECKSUM.

/LIST [:list-file]

The /LIST qualifier causes SLP to
produce a sequentially numbered
version of the input file with the
same file name. The default file
type is LST. You can request a
different specification for the
listing
file
by
using
the
/LIST:list-file
qualifier.
....

_________ ____________

(continued on next page)

3-'l

SLP AND SUMSLP EDITING UTILITIES
Table 3-1 (Cont.)
SLP Qualifiers
Function

Format
/OUTPUT [:file-spec]
and /NOOUTPUT

By default,
SLP
genera~es
an
output file with the same file
name
and
file
type
as the
correction
input
file.
Its
version number is higher by 1 than
the
highest
version
number
existing for
the input file name
and type.
You can request
a
different specification for
the
output
file
by
using
the
/OUTPUT:file-spec qualifier.
To suppress the
specify /NOOUTPUT.

output

file,

/REPORT and /NOREPORT

The qualifier /REPORT causes SLP
to
report any line truncation hy
audit trails.
If line truncation
occurs,
SLP prints a diagnostic
message.
If you specify creation
of a listing file, a question mark
(?) replaces the period (.) in the
line
number of the truncation
line.
The default is /NOREPORT.

/TAB_FILL and /NOTAB_FILL

The qualifier /TAB FILL causes SLP
to
insert tabs at-the end of each
text line containing an
audit
trail.
The default
is to fill
such lines with spaces
(that
is,
/NOTAB FILL).
Using
/TAB FILL
saves disk space,
because fewer
tabs than spaces are required to
fill the lines in both the output
and the listing file.

/TRUNCATE [:position]
and /NOTRUNCATE

The /TRUNCATE qualifier lets you
truncate input lines to the given
column position.
If you specify /TRUNCATE but omit
position,
SLP uses the position
given
(or defaulted)
for
the
/AUDIT TRAIL qualifier;
position
is rounded to the next tab stop
before use.
Set position at or
before the start of the old audit
trail that you want to delete.
Any trailing spaces or tabs after
position are also deleted.

3.1.5.1 Using the /AUDIT TRAIL Qualifier - You may want to change the
position of the audit trail if your output device has fewer than 80
columns or if your source lines are all brief.
The following example
shows the use of the /AUDIT_TRAIL qualifier to specify the position

3-7

SLP AND SUMSLP EDITING UTILITIES
and length of the audit trail. By default, audit trail texts are
;**NEW** for new lines and ;**-n for deleted lines.
(See Section
3.1.6.6 for a description of changing the audit trail text.) The input
source file for this example is named MYFILE.TST and is made up of the
following lines:

ONE
TWO
THREE
FOUR
FIVE
The SLP command file is as follows:

$EDIT/SLP/AUDIT_TRAIL:CPOSITION:30vSIZE:10)/LISTING
-2v.+1v/!CHANGE001/
NEW LINE 2
NEW LINE 3

MYFILE.TST

The following listing file results from SLP processing.
MYFILE.TST/ALJ:Jo.:1o~vMYFILE=MYFILE+TST

1.
2.
3.

ONE
!CHANGE001
NEW LINE 2
!CHANGE001
NEW LINE 3
4. FOUR
5. FIVE
The values that you specified for position and length are
the header of the listing file.

'**-2

stated

3.1.5.2 Using the /CHECKSUM Qualifier - To obtain a checksum value,
append the qualifier /CHECKSUM to the SLP initialization line. SLP
processes the file, prints the checksum value in a message on your
terminal, and exits.
If you want to chec~ the accuracy of SLP editing commands, specify a
checksum value using the form /CHECKSUM:n, where n is the checksum
value previously calculated by SLP. If there is a mistake in the SLP
command file
(for example, if the edit command is -4,4 and you type
-4,5), the checksum value will not match the value you specified with
the /CHECKSUM qualifier.
If the two values differ, SLP prints a
diagnostic error message on your terminal, as described in Section
3.3.1.
SLP calculates a checksum value for all SLP edit commands except:
•

The SLP initialization line

•

Comments within the edit command line

•

Spaces and/or tabs between characters included in the checksum
calculation and those characters excluded from the calculation

second comma on an edit command line and
• The
following it (that is, audit trails and comments)
•

anything

The comment delimiter for an input line and any characters
following it
(the comment delimiter is defined as the first
character in the current audit trail).

1-8

SLP AND SUMSLP EDITING UTILITIES
3.1.5.3 Using the /NOOUTPUT and /LIST Qualifiers - SLP processes
input by sequence number. However, sequence numbers appear only in
the listing file;
they are not written to the output file.
To use SLP effectively, obtain an up-to-date numbered listing for use
when you create the SLP command file. Numbered listings generated by
other programs
(such as SOS and the MACRO assembler) will not
necessarily be useful in preparing an SLP command file. Generate a
SLP numbered listing by submitting an editing command in the following
form:
$EDIT/SLP/NOOUTPUT/LIST[:list-file]
Here list-file is the
that SLP produces,
whose lines are to be
processing the files.
not produce an output

3.1.6

file-spec

name you optionally assign to the listing file
and input-file is the specification of the file
numbered. The slash
(/)
tells SLP to begin
SLP generates a numbered listing file, but does
file.

Specifying SLP Editing Commands

SLP editing commands let you update source files by adding, deleting,
and replacing lines in a file.
These commands contain certain
characters that SLP interprets as operators.
This section first
describes these operators and the general form for specifying SLP
editing commands. Then, it describes the editing commands used for
specific editing functions.

3.1.n.l SLP Operators - When SLP encounters any of the characters
listed in Table 3-2 as the first character in an input line, it
interprets the character as an operator.
Table 3-2
SLP Operators
Operator

Function

(minus sign)

First character of an SLP edit command

(backslash)

Suppress audit trail generation

% (percent sign)

Reenable audit trail generation

(at sign)

Invoke a further command
processing

(slash)

Terminate the editing session

< (less than character)

file

for

SLP

Escape character

The percent sign
(%)
operator is used to reenable audit trail
generaton when generation has been suppressed by either the backslash
(\) operator or the /NOAUDIT_TRAIL qualifier, described in Section
3.1.5.

3-9

SLP AND SUMSLP EDITING UTILITIES
The at sign (@) operator tells SLP to read further input from a
another command fi.le. This second command file can contain only SLP
edit commands and new text lines.
The less-than character (<) operator is the escape character that lets
you enter characters in the command file
(in column 1) 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. You can
use the less-than character as an escape character for all SLP
operators listed in Table 3-2 (including itself).

3.1.6.2 General Form of an Editing Command - The general
SLP editing command is:

form

-locatorl [,locator2] [,/audittrail/J [;comment]
inputline

A minus-sign operator indicates
command line.

that

this

SLP

editing

locatorl
A line locator that causes SLP to move the current line pointer
to a specified line. If only locatorl is specified, the current
line pointer is moved to that line and SLP reads the next line in
the editing command file. This field can be specified using any
of the locator forms described below.
locator2
A line locator that defines a range of lines (that is, the range
beginning with locator! and ending with locator2) to be deleted
or replaced. This field can be specified using any of the
locator forms described below.
/audittrail/
A character string used to keep track of the update status of
each line in the file. This audit trail is used to mark new or
replaced lines in the file until the audit trail is either
changed or suppressed.
This argument must be delimited by
slashes (/). If there are not two locator fields in the editing
command, the audit trail specification must be preceded by two
commas.
Audit trails generated by SLP use the first character of the
specified string as a delimiter. Usually, the first character of
the audit trail is set to match the comment delimiter of the
source file being edited. Default audit trails are ;**NEW** for
new lines and ;**-n for lines that indicate where text has been
inserted.

3-10

SLP AND SUMSLP EDITING UTILITIES
inputline
A line of new text to be inserted into the file immediately
following the current line. You can enter any number of input
lines.
;comment
An optional comment.

SLP ignores any text after a semicolon.

All fields in the command line are position-dependent;
included as specified above.

commas must be

The locator fields can take one of the following forms:
/string[ ••• string]/}
number
{

[+n]

Parameters:
string
A string of ASCII characters. SLP locates the next line in which
string exists and moves the current line pointer to that line.
If the locator is specified in the form /string ••• string/ (that
is,
two different strings of characters separated by three
periods), SLP locates the line in which the first character
string is followed by the second character string, regardless of
what characters may be in between them.
number
A sequence number in the range of 1 through
current line pointer is to be moved.

9999

which

the

A decimal value used as an offset from the line specified by
locator. Note that n is always preceded by a plus sign (+).
cannot back up from the locator.

the
You

A period represents the current line.
All forms of the line locator can be specified
command line.

interchangeably

SLP can only edit files sequentially. Once the current line pointer
moves past a given line in the file, it cannot be returned to that
line.

3.1.6.3 Adding Lines to a File - The SLP editing command for
lines to a file contains only one locator field.
Its form is:

adding

-locator[,,/audittrail/] [;comment]
The locator has one of the forms defined in Section 3.1.5.2
If a numeric locator is specified, SLP inserts new line(s) after the
line specified by sequence number. Any lines you enter are inserted
as lines in the file.

3-11

SLP AND SUMSLP EDITING UTILITIES
If a string locator is specified, SLP locates the next occurrence of
the string in the file and moves the current line pointer to the line
containing the string. Any input lines following the command line are
then added to the file.
If you specify an offset (+n) SLP moves the current line pointer n
lines beyond the line specified in the locator field and then adds any
new input lines to the file.
Because there is only one locator field, the audit trail specification
must be preceded by two commas.
The example below shows how to add lines to a file.
file consists of the following lines:

The input

source

ABC

DEF
GHI
KLM
12:34~.=;6 "789

456

789

CBA
XYX
98'7

The SLP command file consists
lines:

the

followinq

commands

and

text

SEDIT/SLP/LISTING/AUDIT_TRAIL:<POSITION!32) MYFILE+TST
--l:l.2:V

INSERT THIS LINE AFTER LINE 5
I

SLP processing generates the following listing file:

MYFILE.TST,MYFILE=MYFILE.TST
1.

ABC

DEF
GHI

;3.
4.
~.).

Kl... M
:I. 2:34~.)6 '7B<?

INSERT THIS LINE AFTER LINE 5

l.
8+
9.
JO+

456
/8<_71
CBA

:1.:1. +

98"7

XYX

SLP has applied sequence numbers to the lines and added an audit trail
to the line following line 5, where SLP found the first occurrence of
the string 123.
The next example uses the same correction input file and the following
new SLP command file:

SEDIT/SLP/LISTING/AUDIT_TRAIL:CPOSITION:32> MYFILE.TST
... /DEF/+2

THIS IS NEW TEXT
I

3-12

SLP AND SUMSLP EDITING UTILITIES
SLP processing generates the following listing file:

MYFILE.TST,MYFILE - MYFILE.TST
1.

2.
3.
4.
5.

6.
7.
8.

9.
10.
11.

ABC
DEF
GHI
KLM
THIS IS NEW TEXT

;**NEW**

123456789
456
789

CBA
XYX
987

Again, SLP has numbered the lines in sequence; this time the new input
line is inserted two lines beyond the line containing the first
occurrence of the string DEF.

3.1.6.4 Deleting Lines from a File - The SLP editing command for
deleting lines from a file contains two locator fields.
Its form is
given below.
-1 o cat o r 1 , 1o cat o r 2 [ , /au d i t tr a i 1 I] [ ; comment ]
The locatorl and locator2 fields can take any of the forms described
in Section 3.1.6.2.
The first field, 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 example below shows how to delete lines from a file
The input source file consists of the following lines:

using

ABC
DEF
GHI
KL..M
123456'789
456
789

CBA
XYX
987

The SLP command file for this example is as follows:

$EDIT/SLP/LISTING/AUDIT_TRAIL:CPOSITION:32)
~-11. • +9/,/XYX/

MYFILE.TST

SLP processing generates the following listing file:
1.
2+
~~.

4.
I!!'

J+

ABC
DEF
GHI
KLM
v **""'"~;

9ff7

3-13

SLP.

SLP AND SUMSLP EDITING UTILITIES
In this example, the ellipsis ( ••• ) is used to abbreviate the larger
string 123456789. SLP searches for the first occurrence of the string
l and the first occurrence of the string 9 on the line, assuming these
two strings bracket a larger string, in this case, the string
123456789. SLP begins deleting lines at this line and continues
deleting lines until it deletes the last line, specified by the string
XYX. SLP applies the audit trail count of the lines it deleted to the
next line in the output file.
Using the same input source file, this example shows how to delete a
single line using the period locator.
The command file for this
example is as follows:

SEDIT/SLP/LISTING/AUDIT_TRAIL:CPOSITION:32> MYFILE.TST
--/DEF/,.
I

SLP processing generates the following listing:

. ABC
GHI
,., .
l. +

'**··-:I.

'')

l\LM
l. 2~34~)6 /B9

~-=·

4::56

/89
CBA

f.L
<-;.

98/

XYX

SLP moves the current line pointer to the line containing the string
DEF and then finds the period as the second locator field. Since the
second locator field is specified, SLP interprets the editinq command
as a delete operation and deletes the line containing DEF.

3.1.6.5 Replacing Lines in a File - A replacement is a deletion
followed by new text. The number of lines deleted need not match the
number of lines added. To replace lines in a file, use the full
2-locator command form, as 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, which,
for replacement operations, is the line where new text is to be
inserted.
For example, the command -4,.+4 instructs SLP to move the line pointer
to line 4 and replace line 4 and the next four lines (as represented
by .+4) with new input lines that immediately follow the command line.
This command is equivalent to -4,8.
The example below shows how to delete lines from a file and replace
them with new lines. The input source file consists of the following
lines:
ABC

DEF
GHJ
:I. 234!'56 ?B9

BCN
c1:~B

BUI:;:

3-14

SLP AND SUMSLP EDITING UTILITIES
The SLP command file is as follows:

SEDIT/SLP/LISTING MYFILE.TST
MU2,.+:1.

NEW LINE 2
NEW l... INE 3
I
~~EXIT

SLP processing generates the following listing file:
:L •

ABC

'")

NEW LINE 2
NEW LINE 3

v**NEW**
v**NEW**

:L 2~54~~i6 "7B9

~**•···::!.

Ji:...

3+
4+
5+
6+
"7.

BCN
c1:~B

BUR

3.1.6.6 Specifying the Audit Trail Text - The
command changes the text of the audit trail:

following

SLP

edit

-,,/newtrail/
Here newtrail is the new value (text) of the audit trail.
If the
length of newtrail exceeds the length specified (or defaulted) for the
/AUDIT TRAIL qualifier, the audit trail is truncated to that lenqth.
(The default audit trail, ;**NEW**, is never truncated, even if you
specify a length less that 8.)
All subsequent lines added will include the new audit trail text. All
lines that indicate where lines have been deleted will include the
first character of the new audit trail text as their first character.
For example,
if you
specify the new audit trail JANUARY, the audit
trail indicating a replaced line will be J**-2.
When you create a new audit trail, you may want to set the first
character of the string to correspond to the comment delimiter that is
used in the source file.

3.2

SUMSLP

SUMSLP is a batch-oriented editor similar to the SLP editor.
It
supplements the functions of SLP by allowinq multiple command files to
be applied to a single input file. The multiple command files are
combined according to fixed rules.

3.2.l

Running SUMSLP

SUMSLP can be run either indirectly from a command procedure or
interactively from your terminal. To invoke SUMSLP interactively, you
issue a command line in response to the DCL prompt. To invoke SUMSLP
from a command procedure, precede the command with a dollar sign ($).
The command has the following format:
EDIT/SUM[/qualifier(s)]

input-file[/qualifier]

3-15

SLP AND SUMSLP EDITING UTILITIES
/qualifier (s)
A command or file qualifier, as described in Table 3-2.
/OUTPUT and /LIST qualifiers are command qualifiers only;
/UPDATE qualifier is a file qualifier only.

The
the

input-file
The file specification for the source file to be edited.
specifications are described above in Section 3.1.2.2.

File

Table 3-3
SUMSLP Qualifiers
~---------------------------·---

..----.

Function

Format

--·-------------/LIST[=file-spec]

Controls whether a sequence-numbered
listing file, showing the original and
inserted lines and an audit trail,
is
produced during the editing process.
If you do not specify a file,
the
listing file takes the same name as
the input file, with a file type of
LIS.
You can specify another file
type for the listing file, but LIS is
the
default.
The
listing
file
described in Section 3.2.2.4.

/OUTPUT[=file-spec]

Specifies the output file to be used
in the editing operation. If you do
not specify a file,
the output file
has the same name and type as the
input file, with a version number one
higher
than
the highest existing
version. The output file is described
in Section 3.2.2.3.

/UPDATE[=(file-spec, ••• )]

Indicates the file or files containing
the editing commands and changes to be
applied to the input source file.
If
multiple
file
specifications
are
listed, they must be separated by
commas, and the list must be enclosed
in parentheses. The default file type
of
these files is initially UPD.
Default values for the other elements
of
the
file
specification
are
initially taken from the input file
specification;
after the first file
specification in
a
list,
values
default to those of the immediately
preceding file specification.
If no file specification or list of
file
specifications
given, SUMSLP
attempts to open a single update file
with the same file name as the input
file and a file type of UPD.

If you do not include the /UPDATE
qualifier in the command line, SUMSLP
will not attempt to find an update
file,
but will generate any specified
output or listing file.
Enter the
EDIT/SUM
command
with
the /LIST
qualifier but without the
/UPDATE
qualifier
to
generate a numbered
listing of your source program.
---------------------------'-- ---------------3-ltS

SLP AND SUMSLP EDITING UTILITIES
Examples
1.

$EDIT/SUM

FILEl.MAR/UPDATE

The input source file FILEl.MAR is updated
command file FILEl.UPD.
2.

$EDIT/SUM

the

SUMSLP

with

the

SUMSLP

FILE2.MAR/UPDATE=UPD2

The input source file FILE2.MAR is updated
command file UPD2.UPD.
3.

with

FILE3.MAR/UPDATE=(UPD3A,UPD3B.ENH,UPD3C)

The input source file FILE3.MAR is updated with the merged
contents of SUMSLP command files UPD3A.UPD, UPD3B.ENH, and
UPD3C.ENH. The editing commands in the three command files
are applied according to the rules given in Section 3.2.3.

3.2.2

SUMSLP Input And Output Files

SUMSLP requires two types of input files:
an input source file and
one or more SUMSLP command files.
SUMSLP produces two types of output
files:
a source output file and, if requested, a listing file. These
four types of files are described in the following sections.

3.2.2.1 The Input Source File - The input source file is the file
be updated by SUMSLP. It can contain any number of lines of code.

3.2.2.2 The SUMSLP Command Files - SUMSLP command files
similar to SLP command files, described in Section 3.1.2.2.
not, however, include an initialization line.
The editing command lines in SUMSLP command files
those used in SLP, with the following exceptions:
described

Section

are

•

the locator field,
contain strings.

•

additional command files cannot be invoked with
(@) operator.

are very
They need

identical

3.1.n.2,
the

cannot
at

sign

As in SLP, the final editing command line must be followed by a
containing the slash operator (/), which serves as a terminator.

line

3.2.2.3 The Output File - The SUMSLP output file contains the input
source file as updated by the additions and changes specified in the
SUMSLP command file(s).
It does not include an audit trail or line
numbers.
If you do not include a file specification for the output file with
the /OUTPUT qualifier in the EDIT/SUM command, the output file takes
the same file name as the input source file, with a version number one
higher than the existing version number.

3-17

SLP AND SUMSLP EDITING UTILITIES
3.2.2.4 The Listing File - The SUMSLP listing file is produced if you
specify the /LIST qualifier in the EDIT/SUM command. If you do not
specify another name for it, it takes the same file name as the input
source file, with the file type of LIS. You can specify another file
type, but LIS is the default.
The following example illustrates the generation of
The input source file, named MYFILE.TST, is:

listing

file.

ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN
EIGHT
NINE
TEN
There are two SUMSLP command files.
the following editing commands:

The first,

UPDATE.UPD,

contains

-3~3,;;21-MAR/

INSERTED LINE
I

The second SUMSLP command file, NEWLINES.UPD, contains
editing commands:

the

following

-7,~;;22-MAR/

NEW LINE
I

When the commands in these SUMSLP command files are applied to the
input source file, and the /LIST qualifier is applied, the following
listing file is produced:

ONE
TWO
'
+ 1 INSERTED LINE
4 FOUR
FIVE
J
6 SIX
7 SEVEN
+ 1 NEW LINE
8 EIGHT
01
NINE
10 TEN
1

;21-MAR
-1

An audit trail is produced automatically unless it has been suppressed
(see Section 3.1.5).
This field will also contain a marker to
indicate the number of lines deleted or replaced from the original
file.
The marker is placed on the first original line following a
deletion and has the form -n, where n is the number of lines deleted.
The line numbers of inserted lines are distinguished from those of
ori~inal
lines by being preceded by a period. Inserted line numbers
begin with .1 at the start of each group of new lines.
The source lines show the results of SUMSLP processing.

3-18

SLP AND SUMSLP EDITING UTILITIES
3.2.3

How SUMSLP Processes Files

SUMSLP applies the edits specified in the SUMSLP command file(s)
to
the source lines of the input source file. When a list of command
files is specified with the /UPDATE qualifier, the editing commands in
the various files are arranged according to the following rules:
1. The editing commands are merged into a single stream in
ascending order according to the value of locatorl
(as
described in Section 3.1.~.2). All edits that do not overlap
or conflict with any other edits are applied to the source
file without any further processing.
2. Editing commands which do conflict are resolved according to
the precedence of the SUMSLP command file in which the
commands occur.
Precedence of SU~SLP command files
is
determined
by·
the position of the file specifications
following /UPDATE. The file specification listed last after
/UPDATE has the highest precedence.
All inserts to the same source line are included in the output
file;
those from the SUMSLP command file with the highest
precedence appear first.
An operation that deletes or replaces a line will affect not
only the specified line, but also any lower precedence inserts
or replacements to the same line. A deletion that specifies a
range of lines
(for example, -10,15) will delete all lines
occurring in that range, including inserted lines from SUMSLP
command files of lower precedence.

3.3

SLP and SUMSLP MESSAGES

The following sections describe the diagnostic messages issued by
and SUMSLP.

3.3.1

SLP

SLP Messages

The following sections describe the information and error messages
issued by SLP.
Each message is followed by an explanation of its
meaning and a recommendation for user action.

3.3.1.1

SLP Information Messages

SLP -- COMMAND FILE CHECKSUM IS ######
Explanation: By specifying the /CHECKSUM qualifier in
the
command line, you requested SLP to calculate the checksum value
for the edit commands.
User Action: This message is
action is required.

for

3-19

your

information

only.

SLP AND SUMSLP EDITING UTILITIES
SLP -- *D'IAG*-ERROR IN COMMAND FILE filespec 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 message is for your information 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.

3.3.1.2 SLP Error Messages - The SLP error messages listed below
issued in two formats:
•

are

SLP followed by two dashes, the type of error message, and the
error message.
If applicable, the command line or command
line segment that caused the message is printed on the next
line. For example:
SLP -- *FATAL*-ILLEGAL SWITCH
$EDIT/SLP/TUNCATE

•

SLP followed by two dashes, the type of error message, the
error message, and the name of the file with which the error
is associated. For example:
SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename

SLP -- *FATAL*-COMMAND SYNTAX ERROR
command line
Explanation: The command line format did not conform to
rules. Open files were closed and SLP was reinitialized.
User Action:

Reenter the command line.

3-20

syntax

SLP AND SUMSLP EDITING UTILITIES
SLP -- *FATAL*-ILLEGAL DEVICE NAME
command line
Explanation: The device specified was not a legal device.
files were closed and SLP was reinitialized.
User Action:

Open

Reenter the command line.

SLP -- *FATAL*-ILLEGAL DIRECTORY
command line segment
Explanation: The directory was not specified
files were closed and SLP was reinitialized.
User Action:
directory.

correctly.

Open

Reenter the command line with a correctly specified

SLP -- *FATAL*-ILLEGAL ERROR/SEVERITY CODE pl p2 p3
Explanation: This error message indicates that an error occurred
in the SLP program.
User Action: Reenter the command line. If the error persists,
submit a Software Performance Report (SPR) along with the related
console dialogue and any other related information, such as
programs or listings.
SLP -- *FATAL*-ILLEGAL FILE NAME
command line segment
Explanation: A file specification was
longer
characters or contained a wild card character
asterisk in place of a file specification element).
were closed and SLP was reinitialized.
User Action:

30 ( 8)
than
(that is, an
Open files

Reenter the command line.

SLP -- *FATAL*-ILLEGAL GET COMMAND LINE ERROR
Explanation: The system was unable to read a command line. This
indicates an internal system failure or an error in the SLP
program.
User Action: Reenter the command line.
If the error persists,
submit a Software Performance Report (SPR) along with the related
console dialogue and any other pertinent information.
SLP -- *FATAL*-ILLEGAL SWITCH
command line segment
Explanation: Either the qualifier used was not a valid SLP
qualifier or a legal qualifier was used· in an invalid manner.
Open files were closed and SLP was reinitialized.
User Action:
specified.

Reenter the command line with the correct qualifier

3-21

SLP AND SUMSLP EDITING UTILITIES
SLP -- *FATAL*-INDIRECT COMMAND SYNTAX ERROR
command line
Explanation: The command line format specified for the SLP
command file did not conform to syntax rules. Open files were
closed and SLP was reinitialized.
User Action:

Reenter the command line.

SLP -- *FATAL*-INDIRECT FILE DEPTH EXCEEDED
command line
Explanation: More than three levels
of
indirection
were
specified in a SLP command file. Open files were closed and SLP
was reinitialized.
User Action:
line.

Correct the command file and

reenter

the

command

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
specified number of characters.

•

The file is corrupted or the format is incorrect.

was

greater

User Action: Determine which condition caused the
correct that condition. Reenter the command line.
SLP -- *FATAL*-INDIRECT FILE OPEN FAILURE
command line
or
SLP -- *FATAL*-OPEN FAILURE CORRECTION INPUT FILE filename
or

3-22

than

message

the

and

SLP AND SUMSLP EDITING UTILITIES

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
the device was not online).

•

The volume is not mounted.

•

The specified file directory does not exist.

•

The named file does not exist in the specified directory.

These errors cause
reinitialized.

open

files

closed

(for

and

example,

message

and

contained

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

SLP

SLP -- *FATAL*-LINE NUMBER ERROR
command line
Explanation: The
command
line
printed
illegally-specified numeric line locator.

User Action: Terminate the SLP edit session and refer to the
rules for specifying numeric line locators in Section 3.1.n.2.
Correct the error and reenter the command line.

SLP -- *FATAL*-PREMATURE EOF CORRECTION INPUT FILE filename
Explanation: An out-of-range line locator was specified in a
correction file or from the terminal;
for example, -1000 was
specified for an 800-line file.
User Action:

•

Terminate the current editing session.

•

Restart the editing session, entering
number.

the

correct

line

SLP -- *FATAL*-PREMATURE EOF COMMAND INPUT FILE
Explanation: This error occurs if you do not terminate SLP
command input with a slash
(/) or if you inadvertently type
<CTRL/Z> at the terminal, which sends an end-of-file to SLP
before the slash (/) character is read.
SLP prints SLP>,
indicating that a new file specification is expected.
User Action: Restart the editing session at the point where
CTRL/Z was typed.

3-23

the

SLP AND SUMSLP EDITING UTILITIES
SUMSLP Messages

3.3.2

The following sections described the information and error messages
issued by SUMSLP.
All of the error messages are warnings. Each
message is followed by an explanation of its meaning and, where
appropriate, a rrecommendation for user action.

3.3.2.1

SUMSLP Information Message

SUM-I-EDIT$CLSH, edits clash
editing commands
files specifications
Explanation: Two or more conflicting editing commands have been
entered, that is, more than one edit operation has been specified
for one line of source code. The relevant editing commands and
the file specifications of the SUMSLP command filBs are listed
following the message.
User Action: This message is
action is required.

3.3.2.2

for

your

information

only.

SUMSLP Error Messages

SUM-W-EDOUTSEQ, edits out of sequence
Explanation: The editing commands from a single SUMSLP command
file were not in ascending sequence. The edits have been moved
to the correct position.
User Action: Check output file.
you to edit the file again.

It should not be necessary

for

SUM-W-PRMEOF, premature end-of-file
Explanation: A SUMSLP command file has terminated unexpectedly.
This is probably due to the absence of a terminator (/) at the
end of the command file.
User Action: Insert a terminator (/) at the end of
file and edit again.

the

command

Explanation: The editing command did not conform to the
syntax rules. However, processing of edits continued.

SUMS LP

User Action: Check output file and,
with corrected editing commands.

again

SUM-W-SLPSYNERR, SLP command syntax error
editing command
file specification

3-24

necessary,

edit

CHAPTER 4
DISK SAVE AND COMPRESS UTILITIES

The Disk Save and Compress (DSC) utilities are used to back up and
restore disk volumes that have been formatted and initialized as
Files-11 structure Level l or Structure Level 2 volumes.
There are
three DSC utilities:
•

DSC2 saves, compresses, and restores Files-11 Structure Level
2 disk volumes.
DSC2 runs online under the control of the
VAX/VMS operating system.

•

DSCl performs the same functions as DSC2 for
Files-11
Structure Level l
disk volumes. DSCl runs online under the
control of the VAX/VMS operating system.

•

DSC-2 is a stand-alone version of the online utility DSC2.
DSC-2 is a component of the VAX-11 Diagnostic Package, and is
bootstrapped from diagnostic floppy diskettes.

This chapter describes the uses and features of the DSC utilities;
is organized into four sections:
•

Section 4.1, "Typical Uses of DSC," introduces the most common
uses of the DSC utilities.

• Section
command

4.2,
line
qualifiers.

"Specifying
format and

DSC
the

Commands," defines the DSC
functions of the DSC file

•

Section 4.3, "Using the DSC Utilities," demonstrates, with
examples, some of the typical uses for the DSC utilities.

•

Section 4.4,
"Auxiliary Procedures for
describes procedures useful to DSC users.

•

Section 4.5, "DSC Messages and Error Recovery Procedures,"
defines all DSC-generated messages and indicates how you can
recover from DSC-related error conditions.

To use the DSC utilities, you should be
familiar with the following manuals:

VAX/VMS

•

VAX-11 Software Installation Guide

•

VAX/VMS Operator's Guide

•

VAX/VMS Command Language User's Guide

You should also be familiar with BAD
utilities described in this manual.

4-1

and

VFY,

DSC

Operations,"

operator

volume

and

maintenance

DISK SAVE AND COMPRESS UTILITIES

For information about Files-11 Structure Level 1 and Structure Level 2
disk volumes, refer to:

4.1

•

VAX/VMS System Man~~-~I~r~_.§._Quide, which describes the Files-11
disk structures in the context of backing up public disk
volumes.

•

Int rod u c.t!.s:>!:!__ ~---Y~.~.::-.1 ~--- 8-~~~~~n~~-~~?'!. ~- __ -·~er vi c e ~-' which
describes the Files-11 disk structures in the context of
general disk organization

•

VAX-11 Record Ma!:l9_g_~.Jll~J}_i;: Services Reference Manual, which
explains RMS-related reco_f_d~-ffle-, and volume concepts and
formats.

TYPICAL USES FOR DSC UTILITIES

You use the DSC programs to back up and restore entire disk volumes
including the system files that define volume structure. The disk
(which
volumes can be single-device volumes or disk volume sets
consist of one or more single-device disks hound together).
One typical use of the DSC utilities is restoring volumes which were
backed up.
The purpose for using a DSC program to back up a disk
volume is to save a copy of the volume in case the data on the
original volume is corrupted.
When you back up a disk volume onto
another disk, you create a usable copy of the original disk. When you
back up a disk volume onto a tape set, you create a file which can
later be used to restore the original disk.
Another typical use of a DSC utility is copying the
VAX/VMS
distribution medium. This operation, which uses stand-alone DSC-2, is
described in the VAX-11 Software Installation Guide.
Other typical uses for
following sections, are:

4.1.1

the

DSC

utilities,

described

•

Backing up the VAX/VMS system disk

•

Backing up public or private disk volumes

•

Compressing the files on a public or private disk volume

•

Regulating disk bad-block information

•

Comparing the contents of two volumes

•

Transporting volumes

the

Backing Up the VAX/VMS System Disk

Use the stand-alone DSC-2 program to back up a VAX/VMS system disk.
Immediately after installing a new version of VAX/VMS, whether from a
DSC copy of the distribution medium or from a VAX/VMS update kit, back
up the new system using DSC-2 before you bring up the installation for
general time-sharing usage.

4-2

DISK SAVE AND COMPRESS UTILITIES

The system manager should provide schedules that define when the
VAX/VMS operating system should be shut down to back up the system
disk. On these occasions, you follow the shut-down procedures in the
VAX/VMS Operator's Guide and then use the DSC-2 program to back up the
system disk:··---"----Although you could use the online DSC2 program to back up a system
disk
(executing the procedure from any user terminal), DIGITAL
recommends that back-ups of the system disk be done when the system is
shut down.
You execute the procedure using DSC-2 from the system
console.
Note that operators at installations that have only one disk drive
must use the stand-alone DSC-2 program to back up the disk (onto
magnetic tape}.
Refer to the
VAX/VMS
Operator' ~._ _Guide
for
instructions.

4.1.2

Backing Up Public or Private Disk Volumes

To back up public or private disk volumes onto disk,
refer to the
VAX/VMS Operator's Guide.
Refer to the examples in this chapter if
you are requested to copy the contents of the volume(s)
to magnetic
tape.
Use the online DSC programs DSC2
(for Files-11 Structure Level 2
volumes) or DSCl (for Files-11 Structure Level 1 volumes) to back up
public and private disk volumes.

4.1.3

Compressing the Files on a Public or Private Disk Volume

To compress files on a disk volume (if backing up to tape} you back up
the volume and then immediately restore it. Because of the way DSC
programs execute, you cannot back up a volume without that volume
being compressed.
How much compression occurs depends upon how the
volume has been used.
For example, there may be very little
compression on a volume that has been used as a private volume; but
there may be a great deal of compression on a volume that has become
fragmented through general use.

4.1.4

Regulating Disk Bad Block Information

You may need to establish and keep current the bad
on the disk devices at your installation.

block

information

Bad block information is established for a disk when it is initialized
as a Files-11 volume.
Section 5.2 describes how the DCL command
INITIALIZE command formats and labels a disk as a Files-11 volume;
refer to the VAX/VMS Command banguage User's Guid! for a complete
description of the INITIALIZE command.

4-3

DISK SAVE AND COMPRESS UTILITIES
As a disk device is used, the probability of a disk data error
increases.
To ensure that only good data blocks are allocated to
users of a disk, you may need to establish a procedure that revises
the bad block information on a disk device. One such procedure could
be:
1.

Run a DSC program to back up a disk volume, either to
magnetic tape or to another disk (that contains up-to-date
bad block information).

Run the Bad Block Locator (BAD) utility program (described in
Chapter 5) to determine the number and location of bad blocks
on the disk which you have just bac~ed up.
You supplement
the bad block information on the disk with the bad blocks
located by BAD.

Run the DSC program again to restore the original volume.

4.1.5

Comparing the Contents of Two Volumes

You can use a DSC program to compare the contents of two disk volumes
or the contents of a disk volume and a tape set. For example, suppose
you are using DSC to make 10 copies of a disk volume.
You could
execute the DSC program 10 times, each time copying from the original
volume to a new volume, and each time specifying the Verify qualifier
to ensure that the volumes are identical.
(Refer to Section 4.3.3 for
information on the use of the Verify qualifier.)
Or, you could save time by
procedure would be:

using

original

the
volume

DSC

Compare

using

DSC

qualifier.
with

the

The

Back up the
qualifier.

Verify

Using the output volume from the previous DSC operation each
time as the input volume to the next operation, execute DSC
nine more times, without the Verify qualifier.

Finally, use DSC with the Compare qualifier to compare the
contents of the first output volume and the last output
volume. If the volumes compare successfully, all 10 copies
are good;
if the volumes do not compare, the operations must
be repeated.

You must decide whether the time saved by using this procedure is
worth
the
(slight)
risk of complementary errors being carried
throughout the operations.
NOTE
Because the DSC programs do not support
tape-to-tape transfers, they cannot be
used to compare tape sets.

4.1.6

Transporting Volumes

The DSCl program provides a way to transport the contents of Files-11
Structure Level 1 volumes between VAX/VMS installations and between
VAX/VMS and RSX-llM, RSX-llM-PLUS, and IAS installations.
For

4-4

DISK SAVE AND COMPRESS UTILITIES
example,
you may need to deliver the contents of several disk volumes
to another system.
If it is impractical
to physically deliver
the
disk volumes, you can use the DSCl program to save the volumes on tape
sets and deliver the
tape sets to
the other
installation.
The
operator at
that
installation can then restore the volumes from the
tape sets using the DSCl program.
Similarly, the DSC-2 and DSC2 programs can be used to
Files-11 Structure Level 2 volumes between VAX/VMS systems.

4.1.7

transport

Device Transfers Supported by DSC Programs

The DSC programs support single- and multivolume
file
transfers
between disk devices and between disk and 9-tr~ck magnetic tape
devices.
DSC programs do not support transfers between magnetic tape
devices.
All devices supported by VAX/VMS, as listed in Appendix A,
are supported by the DSC programs.
Note an
important distinction between disk-to-disk
transfers and
disk-to-tape transfers.
When a DSC program is used to back up a disk
to another disk, that output disk is a usable disk volume.
However, a
tape set produced by a DSC program has no use, except to be input to
another DSC operation which is used to restore a disk from that
tape
set.

4.2

SPECIFYING DSC COMMANDS

This section describes how to invoke and terminate the
enter DSC command strings, and define DSC operations.

4.2.1

DSC

programs,

Invoking and Terminating Online DSCl and DSC2

To invoke DSCl or DSC2, type one of the following commands in response
to the DCL prompt.
For DSCl:
$ RUN SYS$SYSTEM:DSC1
For DSC2:
$ RUN SYS$SYSTEM:DSC2
The utility will reply with a prompt, indicating that it is
ready to
accept a command string.
The prompts are DSC> and DSC2>.
You enter a
command string (followed by a carriage return) for the operation you
want performed.
If the operation is successful, no completion message
will be displayed, and the utility will
prompt
for
another command
string.
Terminate DSC by typing <CTRL/Z> in response to the DSC prompt.

4_.2.2

Invoking and Terminating Stand-alone DSC-2

The stand-alone DSC-2 program does not
run under control
of the
VAX/VMS operating system.
It is a component in the VAX-11 Diagnostic
Package, and is distributed on floppy diskettes with the package.

4-5

DISK SAVE AND COMPRESS UTILITIES
To invoke·DSC-2, follow the procedure "Backing Up Tape and Disk
Volumes," described in the VAX/VMS Operator's Guide. The DSC-2 prompt
is identical to the DSC2 prompt:
DSC2>
To terminate DSC-2, follow the
Operator's Guide.

4.2.3

procedure

described

the

VAX/VMS

Specifying the DSC Command String

The DSC command string specifies the operation that the DSC program is
to perform. The command string format is identical for the three DSC
programs. Note that the left side of the equal sign in this format
denotes
output
parameters,
and the right .side denotes input
parameters.
devcu:

[,devcu: ••• ] [dsclabel]
devcu:

[/qualifier(s}]=

[,devcu: ••• ] (dsclabel]

[/RW]

devcu
The physical device(s)
to or from which data is
to
be
transferred, where dev is the 2-character device code, c is the
device controller letter, and u is the device unit number,
followed by a colon (:). For example:
MTAO:
If there is more than one output device,
separate them with commas. For example:

specify

each

and

MTAO:,MTA1:,MTB3:
dsclabel
An optional file label for the DSC file created when
a
disk-to-magnetic tape operation is performed. If specified, the
label must be a 1- to 12-character alphanumeric label.
If the
label is not specified in the output specification (disk-to-tape
operation), the volume label of the input disk volume becomes the
output DSC file label.
If the label is not specified in the
input specification (tape-to-disk operation), the DSC programs
begin the operation with the first file on the first input device
in the command string.
For disk-to-disk operations, the label you specify becomes the
volume label of the output disk. If not specified, the output
disk volume label remains the same as the input disk volume
label.
Specify the label before any qualifiers.
/qualifier(s)
The output file qualifiers determine the operations to be
performed. They are defined in Table 4-1. They can be specified
in any order; for example, /DENS=l500/VE has the same effect as
/VE/DENS=l600.

4-n

DISK SAVE AND COMPRESS UTILITIES
/RW
The only valid input qualifier is /RW. When you specify /RW, the
DSC program first rewinds the tape reel mounted on the first
input device in the command string and then transfers data from
it.

Table 4-1
DSC Output File Qualifiers

-----------··---·------Format

Name and Function

1------------··---+----·----·-··--· -

/AP

- - - ..--·-·---

The Append qualifier appends files to the tape
volume specified by the first output device in
the command string. Use /AP with output tapes
only.
/AP is required if you want to preserve the
information on the output tape and the tape is
either at beginning-of-tape or you have also
specified the /RW output qualifier.

/BAD=MAN

The Add

Bad

Blocks qualifier allows you to
the output disk volume's bad block
file with manually entered bad blocks.

supplem~nt

/BAD=NOAUTO

The Ignore Bad Block File qualifier allows you
to ignore the bad block file on the output disk
for this operation.
Using
this
qualifier
results in an allocated, but empty, bad block
file on the output disk volume.

/BAD=MAN:NOAUTO

The Replace Bad Block File qualifier allows you
to replace the output disk's bad block file with
manually entered bad blocks during the DSC
operation.

/CMP

The Compare qualifier does not produce data
transfers. When you use /CMP, you are comparing
the contents of the input device with the
contents of the output device, and identifying
any differences that may be present.

/DENS=l600

The Density qualifier allows you to create
output tape volumes recorded at 1~00 bits per
inch (bpi). If not specified, output tapes are
recorded at 800 bpi.

/RW

The Rewind qualifier causes the output tape
volume to be rewound before data is written to
it. Any data on the output tape is overwritten
unless the /AP qualifier is also specified.

/VE

The Verify qualifier causes the DSC program to
compare the contents of the output and input
volumes and identify differences between them.
The verify operation occurs after the data
transfer has completed.

4-7

DISK SAVE AND COMPRESS UTILITIES
4.3

USING DSC PROGRAMS

This section demonstrates common uses of
include:
•

Setting up for DSC operations

•

Using DSC file labels

•

Using DSC qualifiers

4.3.1

the

DSC

programs.

Topics

Setting Up for DSC Operations

There are several
operations:

factors

consider

when

setting

for

DSC

•

User privileges required. If you are not the owner of a
volume that is to be backed up, you rteed the VOLPRO privilege
to mount the volume using the MOUNT/FOREIGN command.

•

Foreign mounting of output devices. All DSC output devices
(both disk and tape) must be mounted with the DCL command
MOUNT using the /FOREIGN qualifier.

•

Valid scratch devices. Ensure that all output devices are
valid scratch devices.
Remember that most DSC operations
destroy the original contents of the output volumes.

•

Physical device names. Use only physical device names in
input and output device specifications. Using logical names,
although valid, increases the risk of inadvertently specifying
an input volume as an output device. DSC programs initialize
output disks before transferring data to them.

•

Placed files. Since the DSC programs do not support files
created with placement controls, do not execute DSC to save or
compress disks unless you and the volume's owner agree that
file placement controls can be destroyed. For information
about file placement controls,
refer to the RMS-11 User's
Guide or the VAX-11 Record Management. Services Reference

Manlial.
•

Index file placement. When you use the INITIALIZE command to
initialize a disk volume, you can specify the placement of the
index file for the volume's directory structure by means of
the /INDEX qualifier.
(See the VAX/VMS Command Language
User's Guide for information on INITIALIZE.) However, when you
use DSC to initialize an output disk, it always places the
index file at the beginning of a disk volume.

•

Allocation errors when backing up a system
disk.
An
allocation error that occurs during a back-up of the system
disk usually indicates that the output disk contains too many
bad blocks and does not have enough contiguous space for some
of the larger contiguous system files. Retry the operation,
using another output disk.

•

Single disk systems. If your installation is configured with
only one disk drive, you must use the stand-alone DSC-2
program to perform the operations described in this chapter.
Once in the stand-alone environment provided by DSC-2, you can
perform all of the online DSC2 functions described in this
chapter.
4-8

DISK SAVE AND COMPRESS UTILITIES

4.3.2

Using File Labels

For disk-to-tape operations, use DSC
volumes as DSC-produced files.

file

labels

identify

tape

If you do not specify an output file label, the DSC programs use the
input disk volume label to construct DSC file label(s) for the output
tape volume(s). When you specify an output DSC file label, the DSC
programs construct output tape file labels from the label you provide.
If you do not specify an input file label during a restore operation
from tape, the DSC programs transfer the first DSC-produced file from
the first input tape device in the command string. When you specify
an input file label during a restore operation from tape, the DSC
programs search for that file and begin the operation, if the file is
found. Otherwise, the following error message is generated:
DSC -- *FATAL* 75 TAPE FILE file label NOT FOUND
For disk-to-disk operations, you may optionally use a DSC
to create a new volume label for the output disk.
Example:

file

label

Saving a Private Volume Using DSC2

You are asked to save an RP06 volume with the disk volume label
FORTVOLV3 on tape. The DSC file label for the back-up tape set is to
be FORTBACKl. The back-up is expected to consume two full
reels of
tape.
Mount the input disk on DBAl and the output tapes on MTAl and MTA2.
Invoke DSC2 and then enter the following command string in response
to the DSC prompt:
DSC2>MTAl:,MTA2:FORTBACKl=DBAl:
This operation results in
multivolume file FORTBACKl.

output

tape

set

containing

the

Had you not specified the output file label, DSC2 would have used the
input disk's volume label to construct the output file label, which
would then be FORTVOLV3.
Example:

Restoring a Private Volume Using DSC2

To restore the volume containing the file labeled FORTBACKl onto an
RP06, mount the input tape set, FORTBACKl, on MTAl and MTA2 and the
RP06 on DBA3. Invoke DSC2 and then enter the following command string
in response to the DSC prompt:
DSC2>DBA3:=MTA1:,MTA2:FORTBACK1
This operation results in a restored RPOfi on DBA3 with the disk volume
label FORTVOLV3.
Because you specified an input file label, DSC2
searched for that file before beginning the data transfers to the
output disk.
Had you not specified an input file label, DSC2 would
have attempted to transfer the first DSC-produced file it found on
MTAl.
In this case, FORTBACKl was the only DSC-produced file on the tape.
If there were more than one DSC-produced tape file on the volume,
however, you would risk copying the wrong file to the output disk by
not specifying a file label.

4-9

DISK SAVE AND COMPRESS UTILITIES
4.3.3

Using the Verify Qualifier

Use the Verify (/VE) output qualifier when you want DSC to save, then
verify the copy in the same operation. Specifying /VE directs the DSC
program to compare each logical block on the input and output volumes
and to identify blocks that do not compare.
Note the difference between the use of the Compare qualifier (refer to
Section 4.3.7) and the Verify qualifier. DSC operations involving the
Compare qualifier produce no data transfers, but an
operation
involving the Verify qualifier results in an output volume, then a
verification of that volume.
An example of using the stand-alone DSC-2 program to save and verify a
system disk is included in the VAX/VMS Operator's Guide.
Example:

Backing Up and Verifying a Disk Volume Using DSC2

You are asked to back up an RP06 disk onto a tape, verifying the copy
and using the input disk's volume label (FORTDATAl) as the output tape
file label.
Mount the RP06 on DBBS and the output scratch tape on MTA2.
Invoke
DSC2 and them enter the foliowing command string in response to the
DSC prompt:
DSC2>MTA1:/VE=DBB5:
The copy operation is completed before the verify operation begins.
When the copy is completed, the output tape is rewound, and DSC2
issues the following message as it begins the verify operation:
DSC -- 45 STARTING VERIFY PASS
As the verify operation proceeds, warning messages are issued if any
logical blocks do not compare.
The messages are similar to the
following example:
DSC -- *WARNING* VERIFICATION ERROR ON DBBS:
FILE ID 000623,000004,000000,VBN 000000,000001
Note that the output tape is not rewound at the end of the DSC
operation unless more than a single volume (tape} is required. In
that case, all tape volumes will be rewound and unloaded when the
verification is complete.
Example:

Backing Up and Verifying a Disk Volume Set Using DSC2

You are asked to back up onto magnetic tape and to verify the copy of
a disk volume set consisting of two RK07 disk volumes, mounted on DMAl
and DMA2. The volume set label is MASTER SET.
You have one tape
drive, MTAl, available. The backup will consume two reels of tape.
Invoke DSC2 and enter the following command
first volume in the set:

string

back

the

DSC2>MTAl:MASTER_SET/VE=DMAl:
The result of this operation is that the contents of DMAl are copied
to the tape on MTAl until that reel is full. Then the tape is
rewound, and the copy (to that point) is verified. The tape is then
rewound and unloaded. DSC2 issues the following message:
DSC -- 44 MOUNT REEL 2 ON MTAl:

4-10

AND HIT RETURN

DISK SAVE AND COMPRESS UTILITIES
At this point, remove the first backup tape and mount another on MTAl.
When you press carriage return, DSC resumes the backup operation and
issues the following message:
DSC -- 46 RESUME COPYING
The copy operation continues until the
transferred.
Then the verify operation
message:

rest of
resumes.

DMAl has been
DSC2 issues the

DSC -- 45 STARTING VERIFY PASS
DSC2 then verifies the rest of DMAl. At the end of the operation, the
tape on MTAl is rewound and unloaded. Mount a new tape on MTAl and
enter another command string to back up the volume that is mounted on
DMA2:
DSC2>MTAl:MASTER_SET/VE=DMA2:
This second operation transfers DMA2 to magnetic tape.

4.3.4

Using the Density Qualifier

Use the Density (/DENS=l600) output qualifier when you want output
tape sets to be recorded at 1600 bpi. If you do not specify the
Density qualifier, output tapes are recorded at the default density of
800 bpi.
Note that the DSC programs automatically read DSC-produced
the recorded density when restoring disks from tape sets.
Example:

tapes

Backing Up a System Disk to Tape at 1600 bpi

Using stand-alone DSC-2, you are to back up the system disk, an RPOn
with the volume label MYVMSRLl, onto a tape set recorded at 1~00 bpi.
The DSC file label for the tape set is to be MONDAY;
the tape drive
available for the back-up is MTA2.
Load the stand-alone DSC-2 program from the floppy diskette.
Mount
the RP06 on device DBAO and the scratch reel on MTA2. To perform the
operation, enter the following command line in response to the DSC-2
prompt:
DSC2>MTA2:MONDAY/DENS=l600=DBAO:
The result of this operation is an output tape set with the DSC file
label MONDAY, recorded at lnOO bpi. You would specify this file label
in a DSC-2 operation to restore the system disk from the tape set.

4.3.5

Using the Rewind Qualifier

Use the Rewind (/RW) qualifier as an input qualifier when you want
restore a disk from a tape set. Typically, you specify /RW when:

•

You are certain that the first DSC-produced file on the
mounted input tape is the correct file.

•

You have specified an input DSC file label in the command
string and you want the first input tape rewound and searched
for that file label before the data transfer occurs

4-11

first

DISK SAVE AND COMPRESS UTILITIES
Use the Rewind qualifier as an output qualifier when you want to save
a disk onto a tape set. Typically, you would specify /RW when you
want output tapes rewound to beginning-of-tape before any data
transfers occur.
Example:

Backing Up an RP06 Volume onto a Tape Set Using DSC-1

You are asked to back up an RP06 disk that is a Files-11 Structure
Level l volume.
THE RP06 is on DBA6, and two tape drives, MTAl and
MTA2, are available for the backup. The DSC file label for the output
tape set is to be MRPMON.
Invoke DSCl and enter the following command string in response to
DSC prompt:

the

DSC>MTA1:,MTA2:MRPMON/RW=DBA~:

The result of this operation is a copy of the RP06 on as many tape
reels as are necessary to contain the volume. The tape set created
has the DSC file label MRPMON. Because you specified /RW, the first
tape mounted on MTA2 is rewound before data is transferred to it.
Subsequent tapes mounted on MTA2 are also rewound before data is
transferred.
Example:

Restoring an RP06 Volume from a Tape Set

To restore the RP06 in the example above from the tape set, mount the
RP06 on device DBB2 and the first and second relative volumes of the
DSC-produced file labeled MRPMON on MTA2 and MTAl.
Enter the
following command string:
DSC>DBB2:=MTA2:,MTAl:MRPMON/RW
The result of this operation is a restored RP06 on device DBB2.
The
DSCl program checks for the correct DSC-produced file label and volume
sequence number after rewinding the tape on MTA2 and starts the
transfer.
The restore operation continues between tapes on MTA2 and
MTAl. When the contents of one tape are transferred,
it is rewound
and unloaded as the transfer continues from the next tape. When the
last tape volume has been transferred, it is rewound and unloaded. As
the copying proceeds from reel to reel, DSC checks the volume sequence
number to ensure that the tapes are mounted in the correct order.

4.3.6

Using the Append Qualifier

Use the Append (/AP) output qualifier to add a DSC file to a tape
volume that already contains other DSC-produced files. Typically, the
Append qualifier is used to copy the contents of several small disk
volumes to a tape set.
Note that you use /AP only when appending
separate DSC-produced files to an output tape set.
Also, you can
append DSC files to only the first volume in an output tape set.
Example:

Backing Up Three Separate Disk Volumes Using DSC!

You need to back up onto tape three RK07 disk
labels FORTVOLOl, FORTVOL02, and FORTVOL03.

volumes

with

volume

The first RK07 is mounted on the only available disk device, DMAl, and
scratch tapes are mounted on devices MTAl and MTA2.

4-12

DISK SAVE AND COMPRESS UTILITIES
Invoke DSCl and start the first of three operations required by
entering the following command string in response to the DSC prompt:
DSC>MTA1:,MTA2:/RW=DMA1:
The result of this operation is a copy of FORTVOLOl to the tape on
MTAl, with the output DSC file label FORTVOLOl. The output tape has
been rewound. At this time, physically dismount the first RK07 and
replace it with the second RK07. To begin the second operation type
the following:
DSC>MTA1:,MTA2:/AP=DMA1:
The result of this operation is a transfer of the second RK07 volume
to the tape on MTAl. If the transfer did not fill the reel, you can
append FORTVOL03 to that reel, by following the same procedure.
If
necessary, the third volume can continue onto MTA2, and onto as many
other tape volumes as necessary to complete the transfer.
If the transfer did fill the reel, that reel would be rewound and
unloaded, and the transfer of FORTVOL02 would continue on MTA2. In
this situation, you cannot append FORTVOL03 to the tape set, because
an Append qualifier can be used only to append files to the first
output volume in a tape set.

4.3.7

Using the Compare Qualifier

Use the Compare (/CMP) output qualifier to compare the contents of two
single-volume disks or a single-volume disk and a DSC-produced tape
set.
Example:

Comparing a Disk to a Tape Set Using DSC2

You have been asked to use DSC2 to compare the contents of a 2-volume
tape set which has the DSC label PAYBACKUP with the RP0h disk volume
labeled PAYMASTER.
Mount the RP06 on device DBA2 and the tape volumes on MTA2 and MTA3.
Invoke DSC2 and enter the following command string in response to the
DSC prompt:
DSC2>DBA2:/CMP=MTA2:,MTA3:PAYBACKUP/RW
The result of this operation is a listing of the blocks that do not
compare.
For each block that did not compare, a message similar to
the following is issued:
DSC -- *WARNING* 42 VERIFICATION ERROR ON DBA2:
FILE ID 000221,000050,000000,VBN 00002fi,000013
This operation produces no data transfers:
the contents of both input
and output volumes are unchanged. Thus, the same results could have
been obtained had you executed the operation by typing:
DSC2>MTA2:,MTA3:PAYBACKUP/RW/CMP=DBA2:
NOTE
When comparing a tape set with a disk
which was not the input disk when the
tape was created, it is recommended that
the tape be specified as input.
4-13

DISK SAVE AND COMPRESS UTILITIES
4.3.8

Using Bad Block Qualifiers

On occasion you may need to use a DSC program to regulate the contents
of a disk volume's bad block file before you restore that disk. On
most disks, as described in Section 5.1.2, the last several blocks
contain a description of the bad blocks on the disk. This description
is left by the formatter or by the BAD utility.
By default, DSC
constructs the volume's bad block file (BADBLK.SYS) from this data.
The bad block file includes the bad blocks and the bad block
description.
The DSC programs
manipulation.

provide

three

output

qualifiers

for

bad

block

Qualifier

Function

/BAD=MAN

Adds logical block numbers to the disk's
block file

bad

/BAD=NOAUTO

Ignores the disk's bad block information
the following DSC operation

for

/BAD=MAN:NOAUTO

Replaces the disk's bad block information
with the logical block numbers entered during
the operation
NOTE

General procedures for establishing and
maintaining the disk bad block file are
described in the VAX/VMS
Operator's
Guide·.
That
manual
defines
the
situations in which you
use
other
methods for manipulating the contents of
disk volume bad block files.
See also
the Bad Block Locator Utility (BAD),
described in Chapter 5, below.

4.3.8.1 Using the /BAD=MAN Qualifier - If you include the /BAD=MAN
qualifier in the DSC command string, the utility will prompt you for
the logical block numbers of the bad blocks that you want to add to
the volume's bad block file.
DSC>BAD=
You can enter the bad block numbers individually, pressing carriage
return after each entry, or you can enter the bad block numbers in
groups. For example:
DSC>BAD=702.:3
DSC>BAD=621.,n22.
DSC>BAD=4057.
The first command enters bad blocks numbers (in decimal) 702, 703, and
704;
the second command enter blocks n21 and 622;
the third command
enters block 4057.

4-14

DISK SAVE AND COMPRESS UTILITIES
To terminate
DSC>BAD=.

the

list,

press

return

response

the

prompt

The bad blocks entered manually become part of the disk's bad block
file;
however,
they do not become part of the permanently recorded
bad block description. This means that if the disk is later written
onto by DSC, the bad blocks that you have previously entered will be
forgotten.

4.3.8.2 Using the /BAD=NOAUTO Qualifier - Disk bad block
files
prevent data corruption by not allowing the blocks marked as bad to be
written into by user programs.
However, there may be occasions which
force you to ignore the bad block file on an output disk in order to
complete a DSC operation.
·For example,
it may be
impossible to
allocate a very large contiguous file on the output disk, due to bad
blocks.
On some disks, such as the RPOn, it is possible to use
the
bad blocks and rely on ECC correction.
(This technique is not advised
where high data reliability is of paramount importance.)
Enter the following command string:
DSC2>DBA2:/BAD=NOAUTO=DBA1:

4.3.8.3 Using the /BAD=MAN:NOAUTO Qualifier - To replace a disk's bad
block
file with a new list of bad blocks, include the /BAD=MAN:NOAUTO
qualifier in the DSC command string, as in the following example:
DSC2>DBA5:/BAD=MAN:NOAUTO=DBA6:
DSC2 prompts for the bad block numbers:
DSC>BAD=
You respond with the appropriate numbers, as shown in Section 4.3.9.1.
After the list is terminated by your responding with a
<RET> to the
DSC prompt, the bad blocks that you entered replace the bad blocks in
the bad block file.
Then disk-to-disk transfer begins.

4.4

AUXILIARY PROCEDURES FOR DSC OPERATIONS

Two procedures are useful to DSC users:

4.4.1

•

Translating file identifications into file specifications

•

Converting physical disk addresses to logical block numbers

Translating File Identifications into File Specifications

Many of the DSC messages report the
file
identification of a disk
volume's file.
While a file identification is useful to identify a
unique file in a disk volume (or disk volume set), it does not tell
you who
is the owner of the file;
what is the owner's UIC;
what is
the file name, file type, and version number;
or what protection
codes are associated with the file.

4-15

DISK SAVE AND COMPRESS UTILITIES
You may need to translate a file identification from its virtual block
number format to a more readable form. You can do this using the MCR
DUMP command.
For example, DSC-2 may issue the following message
operation:
DSC --

*WARNING~~

during

back-up

41 I/O INPUT ERROR I ON DBl: FILE ID ooooso,odooo2

This back up operation continues to completion.
To find out more
information about the deleted file (it was not copied to DBA2), use
the following procedure:
1.

Reboot the VAX/VMS operating system here on DBAl).

Enter the following command string in
prompt:

response

the

DCL

$ MCR DMP TI:=DBA1:/FI:50:2/HD/BL:O

The file header (FILE ID 000050,000002, given in the
message above) is printed at the terminal.

warning

From the record of this display, you can identify
the
file
specification and judge whether the deletion was appropriate. If not,
you may need to repeat the back-up or take some other action to
restore the file.

4.4.2

Converting Disk Addresses to Logical Block Numbers

Some disk manufacturers provide a list of bad blocks with a disk
device when it is shipped from the factory. Some disk diagnostic
programs (including the program ESRAC in the VAX-11 Diagnostics
Package) can be run to generate a list of bad blocks on a disk.
Often, these lists identify bad blocks by cylinder, track, and sector
number.
If you want to use a DSC program to enter these bad blocks into a
disk's bad block file, you must convert these physical addresses into
logical block numbers.
The /BAD=MAN
and
the
/BAD=MAN:NOAUTO
qualifiers require logical block numbers.
To convert physical addresses
following procedure:

logical

block

numbers,

use

the

If necessary, convert the cylinder,
addresses to decimal numbers.

and

sector

Use the following formula to define the logical block
of the bad block:

number

track,

LBN = (((cylinder number* tracks-per-cylinder)+ track number)
* sectors-per-track) + sector number

DISK SAVE AND COMPRESS UTILITIES
For example, a diagnostic program has reported a data error on an RPOn
disk at cylinder 198, track 5, and sector 8. An RPOn contains 19
tracks per cylinder and 22 sectors per track.
Applying the formula
produces the following result:
LB2

* 19.) + 5.) * 22.) + 8.

(((198.

(( 3762. + 5.
(3767.

* 22.) + 8.

8 28 7 4. + 8 •
8 288 2.

The logical block number 82882.

4.5

can now be used in a DSC command.

DSC MESSAGES AND ERROR RECOVERY PROCEDURES

This section defines the formats of messages displayed by the DSC
programs, explains the meaning of each message, and indicates the user
action needed (if any)
to correct the situation that caused the
message to be generated.

DSC Message Categories

4.5.l

There are four categories of DSC messages:
1.

Information messages. These messages, displayed during DSC
processing, provide the operator with information about the
current DSC operation. Fo~ example:
DSC -- 45 STARTING VERIFY PASS

Instruction messages.
These messages are displayed when
operator action is required to continue the current DSC
operation. The operation pauses until the operator performs
the requested action, then resumes. For example:
DSC -- 44 MOUNT REEL 2 ON MTAl:

AND HIT RETURN

Warning messages.
These messages are displayed when a
condition is detected that could cause a fatal error during
subsequent DSC operations or could affect the validity of the
operation.
DSC processing continues as warning messages are
displayed. For example:
DSC -- *WARNING* 56 OUTPUT DISK DBAl:

IS NOT BOOTABLE

Fatal messages. Fatal messages terminate the current DSC
operation;
the program prompts for another command string.
You must correct the condition that caused the message and
retry the DSC operation or you must terminate the DSC
program. For example:
DSC -- *FATAL* 40 I/O ERROR F ON DBA2:
PRIVILEGE VIOLATION
000360

DSC2>

4-17

DISK SAVE AND COMPRESS UTILITIES
4.5.2

Interpreting DSC Messages

Some DSC error messages, including those classified as I/O error
messages,
contain
error codes, the meanings of which provide
supplementary information about the error condition.
Table 4-2
defines these codes.
Table 4-2
Error Codes in DSC Messages
Type of Message

Code

Meaning

General
Error
Messages

CODE A

Failed to read storage map header

CODE B

Input data out of phase

CODE c

Nondata block encountered

CODE D

Input file out of phase

CODE E

File attributes out of phase

CODE F

File header out of phase

Reading index file bit map

Reading index file header

Reading storage bit map

Reading boot or home block

Reading file header

Input (or output) device

Writing index file bit map

Writing storage bit map header

Reading input device

In input tape labels

Reading file attributes

Reading file header

Reading index file data

Reading summary data

Writing file header

I/O
Error
Messages

'-------------------------·---·--

4-18

DISK SAVE AND COMPRESS UTILITIES
4.5.3

DSC Messages

The general DSC messages are listed below with explanations and
suggested user actions. Section 4.5.4 lists the DSC I/O messages.
In
both sections the following notations are used:
FILE ID n

File identifications are displayed as two or three
numbers, for example:
FILE ID 000050,000002
FILE ID 000654,00345n,000001

VBN n

VBNs are displayed as two numbers, for example:
VBN 000000,000001

aan:

The physical device

"label"

The DSC-produced file label

1 UNDEFINED ERROR
Explanation:

An unidentifiable internal error was encountered.

User Action: First, retry the operation. If the
submit a Software Performance Report (SPR).

error

recurs,

2 CONFLICTING DEV. TYPES
Explanation:
specified.

illegal

combination

device

types

was

User Action: Check
for
typographical
errors
in
device
abbreviations;
make sure that disks and tape drives are not
specified on the same side of the command string.
3 MIXED TAPE TYPES
Explanation: Two different types of tape drive were specified in
the command string.
User Action:
tape drive.

Reenter the command specifying

only

the

magnetic

with

qualifier

qualifiers

correctly

Explanation: A file label consisting of more than 12
was specified.

characters

4 ILLEGAL SWITCH
Explanation: The command string was
that cannot be used.
User Action:
specified.

entered

Reenter the command with all

5 FILE LABEL TOO LONG

User Action:

Correct the file label, and retry the operation.

4-19

DISK SAVE AND COMPRESS UTILITIES
6 SYNTAX ERROR
Explanation:

An error in the command string format occurred.

User Action: Check the command, and reenter the command
correct order.
7

DUP.

DEV.

the

NAME

Explanation: The same device was specified more than once in the
command string.

User Action:
once.

Reenter the command, specifying

each

device

only

Explanation: More than eight devices were specified on one
of the command string.

side

User Action: Reenter the command, specifying no more than
devices per side.

eight

8 TOO MANY DEV'S

9 DEV. aan: 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 in the
command string, and reenter the command.
10 DEV. aan: NOT FILES-11
Explanation: The specified input device is not
Files-11 device.

formatted

User Action: Check the input device to
desired, and reenter the command.

ensure

the

one

block

data

was

Check the command that was entered, and reenter

11 BAD BLOCK SYNTAX ERROR
Explanation: A syntax error occurred when
entered manually.

User Action:
correctly.

bad

12 BAD BLOCK COUNT TOO LARGE
Explanation: Too many bad blocks
single group.

were

manually

entered

User Action: Check the blocks being entered. If possible, enter
one large group instead of several small groups.

4-20

DISK SAVE AND COMPRESS UTILITIES
13 BAD BLOCK CLUSTER OUT OF RANGE
Explanation: A manually entered bad block or group of bad blocks
did not exist on the output disk.
User Action: Check the
reenter them correctly.

numbers

the

blocks

entered,

and

not

load

point,

and

data

cannot

14 OUTPUT TAPE aan: NOT AT BOT

Explanation:
point.

The specified continuation tape

User Action: Remount or
reenter the command.

reset

the

tape

was

15 OUTPUT TAPE aan: FULL

Explanation: The
appended to it.
User Action:

specified

tape

full;

Reenter the command, and change the output tape.

16 OUTPUT TAPE aan: NOT ONLY REEL IN SET
Explanation:

An illegal append operation was attempted.

User Action: Reenter the command, and either omit the
qualifier to write to the specified tape or change tapes.

Append

17 TAPE aan: NOT ANSI FORMAT
Explanation:
format.
If
specified.

If aan:
is an input tape, it is not in the correct
an output tape, an illegal Append qualifier was

User Action: For input, check the tape format and change the
tape,
if necessary. For output, either change tapes or omit the
Append qualifier from the command string.
18 OUTPUT TAPE aan: NOT DSC TAPE
Explanation: An append operation was attempted to
was not created by DSC.
User Action: Reenter the command, and
qualifier or change tapes.

either

omit

tape
the

that
Append

19 TAPE aan: A CONTINUATION TAPE
Explanation: If aan: is an output tape, an illegal append
operation was attempted. You can use the Append qualifier only
on the first volume of a tape set. If aan:
is an input tape,
the tape was mounted out of sequence.
User Action:
reenter the
order.

Reenter the command, and change the output tape, or
command, and specify the input tapes in the correct

4-21

DISK SAVE AND COMPRESS UTILITIES
20 CANNOT DETERMINE DENSITY OF TAPE aan:
Explanation: Either the tape is recorded at a density
cannot use or a hardware error has occurred.

that

DSC

User Action: Retry the operation. I f the error recurs, notify
the owner of the tape that it cannot be used.
I f it is
determined later that the tape is recorded at the correct
density, contact DIGITAL Field Service to report a possible
hardware error.
21 FAILED TO FIND HOME BLOCK aan:
Explanation: A read error occurred during an attempt to copy
from 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, change disk
possible, and reenter the command.

drives

22 FILE STRUCTURE LEVEL ON aan: NOT SUPPORTED
Explanation: The specified DSC utilit~ program and the structure
level of the specified volume did not agree.
User Action:

Replace the device, and retry the operation.

23 I/O ERROR A ON aan:
Explanation: One or more messages will accompany this
explaining why the specified file could not be read.
User Action:

message,

Retry the operation.

24 I/O ERROR B ON aan:
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred and explaining why the file
header on the device could not be read. The specified file was
lost.
User Action: Retry the operation after correcting the
the error on the device.

cause

25 CODE A aan:
Explanation:
not be read.

The file header for the storage bit map file

User Action:
copied.

The

disk

unusable

4-22

and

therefore

could

cannot

DISK SAVE AND COMPRESS UTILITIES
26 I/O ERROR C ON aan:
Explanation: One or more messages will accompany this message,
explaining that an I/O error occurred during an attempt to read
the specified file.
User Action:

Retry the operation.

27 I/O ERROR D ON aan:
Explanation: A diagnostic message will accompany this message,
indicating that a read error occurred during an attempt to read
the name or boot block of the disk.
User Action:

Retry the operation on a new drive.

28 RELATIVE VOLUME n OF SET NOT MOUNTED
Explanation:

The specified tape is not on the system.

User Action:

Mount the tape, and reenter the command.

29 Reserved

30 Reserved

31 I/O ERROR E ON aan: FILE ID n
Explanation: One or more messages will accompany this message,
explaining that an I/O error occurred during an attempt.to read
the specified file header.
User Action:

Retry the operation.

32 INPUT DEVICE aan: FILE ID n NOT PRESENT
Explanation: The specified file did not have a
the index file;
the file was not copied.

file

User Action: This is a warning only. If desired, the
can be retried on a different disk drive.
33 INPUT DEVICE aan:

operation

FILE ID n IS DELETED

Explanation: The specified file was found
deleted on the input disk and was not copied.
User Action:

header

This is a warning only.

4-23

partially

No action is required.

DISK SAVE AND COMPRESS UTILITIES
34 INPUT DEVICE aan: FILE ID n UNSUPPORTED STRUCTURE LEVEL
Explanation: The file's structure level recorded in the file
header
did not match the volume's structure level.
This
inconsistency is probably due to a garbled file header. There is
no such file as n.
User Action:

No user action is necessary.

35 INPUT DEVICE aan: FILE ID n FILE NUMBER CHECK
Explanation: An incorrect file header was read from disk causing
the specified file to be lost.
User Action:

Retry the operation.

36 INPUT DEVICE aan: FILE ID n FILE HEADER CHECKSUM ERROR
Explanation: Incorrect file header contents caused the specified
file to be lost ..
User Action:

Retry the operation.

37 INPUT DEVICE aan: FILE ID n SEQUENCE NUMBER CHECK
Explanation:

The sequence number was incorrect.

User Action:

Retry the operation, and/or replace the disk.

38 INPUT DEVICE aan: FILE ID n SEGMENT NUMBER CHECK
Explanation: The linkage connecting file
the specified file was lost.
User Action:

segments

was

broken;

Retry the operation.

39 DIRECTIVE ERROR - n
Explanation: An internal error occurred, usually the result of a
system overload~
User Action:

Retry the operation.

40 I/O ERROR F ON aan:
Explanation: One or more messages will accompany this message,
indicating
that the specified input or output device may
subsequently cause an error.
User Action: This message is a warning only.
No
required unless another error message is displayed.
error message is displayed, correct the cause of the
reenter the command.

4-24

action is
If another
error and

DISK SAVE AND COMPRESS UTILITIES

41 I/O ERROR I ON aan: FILE ID n, VBN n
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred that resulted in bad data
being read from the specified virtual block number on the
indicated device.
User Action: This is a warning
specified should be examined to
error.

message only.
The
block
determine the extent of the

42 VERIFICATION ERROR ON aan: FILE ID n, VBN n
Explanation: This is a warning signifying that one block of
input and output devices did not match.

the

User Action: When the operation is complete, you should decide
whether the mismatch requires that you retry the operation.

43 BAD DATA BLOCK ON aan: FILE ID n, VBN n
Explanation: A parity error occurred during an attempt to copy
the block's contents from disk.
The block specified on the
output disk contains erroneous data.
User Action: When the copy operation
contained
in
the specified block
corrected.

is completed, the data
should be examined and

44 MOUNT REEL n ON aan: AND HIT RETURN
Explanation:

This is an instruction only.

User Action: Mount the volume number requested on the
tape drive, and enter a carriage return when ready.

specified

45 STARTING VERIFY PASS
Explanation: This is simply a message informing you that the
copy operation is complete and DSC is initiating the verify pass
(/VE was specified).
User

Action~

No user action required.

46 RESUME COPYING
Explanation: This is simply a message informing you that the
verify pass is complete (/VE was specified) and DSC is continuing
the copy operation.
User Action:

No user action required.

4-25

DISK SAVE AND COMPRESS UTILITIES
47 aan: IS WRITE LOCKED. INSERT WRITE RING AND HIT RETURN
Explanationl The tape on the specified tape drive
written on until a write-enable ring is inserted.

cannot

User Action: Make sure the tape is the one you want, insert
write ring, and press return.

the

48 INPUT FILE ON aan: WILL BE RESYNCHRONIZED
Explanation: The tape position was lost during an attempt to
read the input tape. The file specified in the message, as well
as some subsequent files, may be lost.
Additional errors will
probably occur.
User Action:

Retry the operation from the beginning.

49 OUTPUT DEVICE aan: FULL FILE ID n
Explanation: The specified device is full and cannot accommodate
the data following the specified file. This may mean that more
data than anticipated was transferred due to an inconsistency in
the input tapes. Or, the output device may contain too many bad
blocks to allocate a large contiguous file.
User Action:

Reenter the command, using a larger output disk.

50 OUTPUT FILE HEADER FULL ON aan: - FILE ID n
Explanation: Too many blocks on the output disk have caused
The specified file was
inconsistencies in file header data.
lost.
User Action:

Retry the operation with a different output disk.

51 OUTPUT FILE HEADER ON aan:

NOT MAPPED - FILE ID n

Explanation: Space for the specified
allocated. The file was lost.
User Action:

Retry the operation;

file

header

was

not

a new disk may be required.

52 I/O ERROR G ON aan:
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred during an attempt to write
the specified file.
User Action:

Retry the operation.

4-2n

DISK SAVE AND COMPRESS UTILITIES
53 FAILED TO READ FILE EXTENSION HEADER ON aan: - FILE ID n
Explanation: During an attempt to copy data from the input disk,
an extension header was searched for, but not found. The
remainder of the specified file was lost. A problem may exist
with the input disk, or a previous I/O error may have caused an
inconsistency.
User Action:

Retry the operation.

54 FAILED TO ALLOCATE HOME BLOCK aan:
Explanation: The home block could not be created on
specified disk device because it has too many bad blocks.
User Action:

the

Replace the device, and reenter the command.

55 INDEX FILE ALLOCATION FAILURE aan:
Explanation: Too many bad blocks exist to allow
for the specified file.
User Action:

the

allocation

Replace the disk, and reenter the command.

56 OUTPUT DISK aan: IS NOT BOOTABLE
Explanation:
tape is bad.

Logical block number O of

User Action:

This is a warning only.

the

specified

disk

No action is required.

57 INVALID BAD BLOCK DATA aan:
Explanation:

The bad block data on the output disk is invalid.

User Action: Run the BAD utility on the disk, manually enter bad
block data, or reenter the command using a new disk.
58 BAD BLOCK FILE FULL aan:
Explanation:

Too many bad blocks exist on the output disk.

User Action:

Replace the disk, and reenter the command.

59 NO BAD BLOCK DATA FOUND aan:
Explanation:
disk.

No bad block data exists for the

specified

output

User Action: If bad block data is not desired, ignore the
message.
Otherwise, run the BAD program on the disk, manually
enter bad block data, or reenter the command using a new disk.

4-27

DISK SAVE AND COMPRESS UTILITIES
60 OUTPUT DEVICE aan: IS A DIAGNOSTIC PACK. DO NOT USE IT!
Explanation: The specified output disk is a diagnostic pack
cannot be used.
User Action:

and

Mount another output disk, and reenter the command.

61 CODE B ON aan: FILE ID n - VBN n EXPECTED, m FOUND
Explanation: The tape position was lost
read the virtual block number specified.

during an attempt to
Some data may be lost.

User Action: Determine the extent of the error.
If
try the tape on another drive or create another tape.

necessary,

62 CODE C ON aan: FILE ID n - VBN n
Explanation: The position of the tape was lost during an attempt
to read the specified data file. Data beyond the virtual block
number specified was lost.
User Action: Re-create the tape or
different tape drive.

retry

the

operation

63 CODE D ON aan: FILE ID n EXPECTED, m FOUND
Explanation: The tape position was lost during an attempt to
read the specified tape. All of "n" and some of "m" were lost.
User Action:

Retry the entire operation.

64 FAILED TO MAP OUTPUT FILE ON aan: FILE ID n, VBN n
Explanation: An inconsistency
write the specified file to the
not specify the correct number
write the file and the file was
User Action:
~5

occurred during an attempt to
output disk. The file header did
of virtual blocks required to
lost.

Retry the operation.

OUTPUT DISK aan: IS TOO SMALL - n BLOCKS NEEDED
Explanation: The output disk is not large enough to
the data to be transferred.
User Action:
disk.

Retry the

operati-0n

specifying

accommodate

larger

output

66 I/O ERROR CODE C ON aan:
Explanation: One or more messages will accompany this message,
explaining that an I/O error occurred during an attempt to read
the specified file.
User Action:

Retry the operation.

4-28

DISK SAVE AND COMPRESS UTILITIES
67 I/O ERROR CODE H ON aan:
Explanation: One or more messages will accompany this message,
explaining that an I/O error occurred during an attempt to write
the specified file.
User Action:

Retry the operation.

68 I/O ERROR CODE J ON aan:
Explanation: One or more messages will accompany this message,
explaining that an I/O error occurred during an attempt to read
the tape labels on the specified device.
User Action:

Retry the operation on a different tape drive.

69 INPUT TAPE ON aan: MUST BE AT BOT
Explanation: The specified tape must be at the beginning of the
tape (BOT) or at its load point. This message is also displayed
during a verify operation to indicate that the current volume is
rewinding to enable the verify pass.
User Action: If /VE was
remount at load point.
70 WRONG INPUT TAPE ON aan:
Explanation:

not

specified,

check

the

tape

and

EXPECTING "label", FOUND "label"

The input tapes were specified out of sequence.

User Action: Check the tapes and reenter
order after receiving mount instructions.

them

the

correct

71 CODE E ON aan: AFTER FILE ID n
Explanation: This is the result of a read error from tape.
During an attempt to read an attribute block, some other block
was accessed. The file following the file specified in the error
message was lost.
User Action:

Retry the operation.

72 I/O ERROR K ON aan: AFTER FILE ID n
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred during an attempt to read
the specified file.
User Action:

Retry the operation.

73 I/O ERROR L ON aan: AFTER FILE ID n
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred during an attempt to read
the file header.
User Action:

Retry the operation.

4-29

DISK SAVE AND COMPRESS UTILITIES
74 INPUT TAPE aan:

RESYNCHRONIZED AT FILE ID n

Explanation: The tape position was
preceding the file specified was lost.

recovered.

Some

data

User Action: This message is usually displayed with one or more
error messages, all indicating that the input tape was either
read incorrectly or recorded badly.
The tape
should
be
re-created and the operation reinitiated.
75 TAPE FILE "label" NOT FOUND aan:
Explanation: The input tape specified does not contain the
identified as "label."

file

User Action: Check the file label and the tape, and reenter
command when the correct tape and file label are specified.

the

76 EXPECTED EXTENSION HEADER NOT PRESENT ON aan: - FILE ID n
Explanation: A tape read error occurred, causing
file to be lost.

the

specified

User Action: If the error message was preceded by one or more
I/O warning messages, the operation should be retried. If not,
the input tape is bad and should be regenerated.
77 CODE F ON aan:

AFTER FILE ID n

Explanation: This is the result of a read error from tape.
During an attempt to read a file header, some other block type
was accessed. 'rhe file following the file specified in the error
message was lost.
User Action:

Retry the operation.

78 I/O ERROR M ON aan:
Explanation: One or more messages will accompany this
explaining why the specified file could not be read.
User Action:

message,

Retry the operation.

79 INDEX FILE DATA NOT PRESENT aan:
Explanation: During an attempt to read the input tape specified,
a file other than the index file was accessed due to a tape error
or an I/O error.
User Action: Re-create the tape or retry
different tape drive.

4-30

the

same

tape

DISK SAVE AND COMPRESS UTILITIES
80 I/O ERROR N ON aan:
Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred during an attempt to
restore the index and storage map files from the specified input
tape.
User Action:
drive.

Retry the operation using a

different

input

tape

81 VOLUME SUMMARY DATA NOT PRESENT aan:
Explanation: Either the input tape is
contains incomplete data.
User Action:

not

DSC

tape

Check the tape, and reenter the command.

82 I/O ERROR 0 ON aan:

FILE ID n

Explanation: One or more messages will accompany this message,
indicating that an I/O error occurred during an attempt to write
the specified file header.
User Action:

Retry the operation.

83 UNSUPPORTED DSC TAPE FORMAT ON aan:
Explanation: This tape cannot be processed with this version
the DSC program.

User Action: Retry the operation. If the same failure recurs,
contact
DIGITAL
Software
Support,
or submit a Software
Performance Report (SPR) •

4.5.4

DSC I/O Error Messages

The DSC I/O error messages are listed below.
BAD BLOCK NUMBER
Explanation: The block does not exist on the disk,
DSC error occurred, or the block is bad.

User Action:
drive.

and/or

Retry the operation with a

new

disk

internal
disk

BAD BLOCK ON DEVICE
Explanation:
data on it
information.

A device malfunction occurred or a tape with bad
was used, resulting in a block containing incorrect

User Action:

Retry the operation.

4-31

DISK SAVE AND COMPRESS UTILITIES
BLOCK CHECK OR CRC ERROR
Explanation: A parity error occurred indicating
may have been transferred.
User Action:

that

bad

data

Retry the operation.

DATA OVERRUN
Explanation: The physical tape used was larger than expected
got out of position, or was in the wrong format.

User Action:
operation.

the

Make sure the tape is the right one and

retry

DEVICE NOT READY
Explanation: The device was not ready or not up to speed,
blank tape was used as an input tape.

User Action: Retry the operation after checking that the
is online and correctly mounted.

device

DEVICE OFF-LINE
Explanation:

The device is not in the system.

User Action: Check both the device and the device
in the command string, and reenter the command.

specification

DEVICE WRITE LOCKED
Explanation:

The disk drive is write locked.

User Action:
command.

Write

enable

the

disk

drive,

END OF FILE DETECTED
Explanation:

The tape position was lost.

User Action:

Retry the operation.

END OF TAPE DETECTED
Explanation:

The tape position was lost.

User Action:

Retry the operation.

END OF VOLUME DETECTED
Explanation:

The tape position was lost.

User Action:

Retry the operation.

4-32

and

reenter

the

DISK SAVE AND COMPRESS UTILITIES
FATAL HARDWARE ERROR
Explanation:

A hardware malfunction occurred.
if

the

error

recurs

attempted,

but

DSC

User Action: Retry the operation;
DIGITAL Field Service.

call

ILLEGAL FUNCTION
Explanation:
An operation
determine what it was.

was

cannot

User Action: Retry the operation. If the same failure recurs,
contact DIGITAL Software Support or submit a Software Performance
Report (SPR).
INSUFFICIENT POOL SPACE
Explanation:

The operating system is overloaded.

User Action:

Retry the operation.

PARITY ERROR ON DEVICE
Explanation:
occurred.

device

malfunction

User Action:

Retry the operation.

media

incompatibility

PRIVILEGE VIOLATION
Explanation:

A device has been mounted as Files-11.

User Action: Dismount the disk, mount it as
and retry the operation.

UNKNOWN SYSTEM ERROR
Explanation:

An undefinable I/O error occurred.

User Action:

Retry the operation.

4-11

foreign

volume,

CHAPTER 5
BAD BLOCK LOCATOR UTILITY

The Bad Block Locator utility (BAD) determines and records the logical
block numbers and location of faulty blocks that cannot reliably store
data. BAD can be used on the following block-structured volumes:

• TU58 DECtape II data cartridge

• RK07 disk cartridges
• RL02 disk cartridge

• RM03 disk packs
• RP06 disk packs
• RXOl/02 floppy diskettes
Usually, BAD tests block-structured volumes that have not been
initialized.
After BAD locates and records the bad blocks, you issue
the DIGITAL Command Language (DCL)
command INITIALIZE so that the
operating system will allocate the faulty blocks to a special file.
In this way, users are protected from accessing these faulty blocks
for their files.
Section 5.1 below explains how BAD locates and records bad blocks;
Section 5.2 explains how the INITIALIZE command allocates bad blocks.
The remaining sections of this chapter describe now to invoke BAD, the
BAD command line format and qualifiers, and the messages BAD can
issue.

5.1

LOCATING AND RECORDING BAD BLOCKS

BAD locates bad blocks on a volume by testing whether the same data
that is written into blocks can be read out. When it finds a bad
block, BAD writes the address of that block into the bad block
descriptor (described in Section 5.1.2).

5-1

BAD BLOCK LOCATOR UTILITY

5.1.l

Locating Bad Blocks

To test the blocks on a volume, BAD:
•

Writes a test pattern onto each block

•

Reads the contents of blocks into a buffer

•

Compares the data in the buffer with the data
the blocks

wrote

into

If the data does not compare exactly, one or more blocks in the group
of blocks are bad and cannot reliably store data. In this case, BAD
will repeat the reading, writing, and comparing operations on each
block in the group to determine the bad block(s).

5.1.2

Recording Bad Blocks

When BAD locates a bad block, it records the address of the block.
Consecutive bad blocks are recorded as single entries. After it
finishes testing the disk, BAD writes the addresses of the bad blocks
into an area called the bad block descriptor.

5.1.2.l Location of the Bad Block Descriptor - The location of the
bad block descriptor depends on whether the volume is a last-track
device. Last-track devices store bad block data on the last track of
the disk.
The first half of the track is reserved for the Manufacturer's
Detected Bad Sector File (MDBSF). The MDBSF stores the bad blocks
discovered by the manufacturer when the device was
originally
formatted.
The second half of the track is reserved for the Software Detected Bad
Sector File (SDBSF). The bad block descriptor is located here.
Last-track devices are:
•

RK07, RL02 disk cartridges

•

RM03/05 disk cartridges

Other devices (non-last-track devices) do not set aside the last track
of the disk to store bad block information. Instead, BAD creates the
bad block descriptor on the last good block of the disk.
There must
be at least one reliable block in the last 256 blocks of the volume
for BAD to generate the bad block descriptor.
Non-last-track devices are:
•

RP06 disk packs

•

RXOl/02 floppy diskettes

•

TU58 DECtape II data cartridges

5-2

BAD BLOCK LOCATOR UTILITY
5.1.2.2 Format of the Bad Block Descriptor - If the volume is a
last-track device, each bad block descriptor entry contains the
cylinder, track, and sector addresses of the faulty block.
The bad
block descriptor can record a maximum of 12~ entries.
On volumes that are not last-track, bad block descriptor entries
contain the number of bad blocks minus 1 and bits O through 23 of the
logical block number (LBN) of the faulty block or sequence of faulty
blocks.
A single entry can address one bad block or several
contiguous bad blocks. The bad block descriptor on non-last-track
devices can contain a maximum of 102 entries.
For both last-track and non-last-track devices, once the maximum
number of entries is exceeded, BAD terminates with an error message.

5.2

ALLOCATING BAD BLOCKS

After you run BAD, the final step in processing bad block data is to
issue the DCL command INITIALIZE. INITIALIZE changes the volume from
unstructured format to Files-11 format and allocates the bad blocks
found by BAD to a special file on the volume called [O,O]BADBLK.SYS.
Once they are allocated to BADBLK.SYS, the faulty blocks cannot be
used by other files. For further information on Files-11 format and
the INITIALIZE command, see the VAX/VMS Command Language User's Guide.

5.3

INVOKING AND TERMINATING BAD

When running BAD to test a device, keep in mind that:
•

The device cannot be accessed by other programs

•

The device cannot be mounted as a Files-11 volume

•

The device is always purged by BAD's testing
information stored on the disk is destroyed

procedure;

any

To ensure that the device is not accessed by any other programs, you
must allocate the device with the DCL command ALLOCATE. See the
VAX/VMS Command Language User's Guide for more information on the
ALLOCATE command.
After you have allocated the device, you must give the DCL command
MOUNT with the /FOREIGN qualifier.
When the device is mounted
foreign, the operating system does not recognize it as a Files-11
volume and BAD can execute.
There is no way to test the volume for bad blocks without destroying
its contents.
However, you can update the bad block descriptor
without wiping out the volume by using the BAD qualifier /UPDATE.
This qualifier is described in detail in Section 5.5.5.
To invoke BAD, enter the following command
prompt:
$ RUN SYS$SYSTEM:BAD

The utility responds with the prompt:
BAD>

5-3

response

the

DCL

BAD BLOCK LOCATOR UTILITY
You can now enter any BAD command string (Section 5.4).
DCL at any time, type <CTRL/Z>.
You can also invoke BAD by using the RSX-llM Monitor
(MCR) command:
$

Console

Routine

same

MCR BAD [device-name]

BAD issues the prompt BAD>.
described in Section 5.4.

5.4

To return

The device name format

the

BAD COMMAND STRING

The BAD command string has the following format:
BAD> device-name: [/qualifier ••• ]
device-name
The device containing the volume on which BAD will be
device name has the form:

run.

The

de vu
where
dev = 2- character alphabetic device code
u = 1- or 2-digit octal device unit number
The colon (:) acts as the device-name terminator and must follow
the device name.
BAD does not recognize alphabetic controller
designators. You must convert them to RSX-llM unit numbers when
specifying
devices.
For information on conversion between
VAX/VMS native mode unit numbers and compatibility mode unit
numbers, see the explanation of mapping physical device names in
the VAX-11/RSX-l]._~ User's Guide.
/qualifier(s)
The BAD qualifiers that modify
BAD
operation.
Multiple
qualifiers are entered on the same command line; no separators
ar~ required.
Section 5.5 discusses the BAD qualifiers in
detail.

5.4.1

Running BAD Interactively from Your Terminal

The example below shows the sequence of commands that you
when running BAD interactively from your terminal:
$ AL.LOCATE DBA2:
_[IBA2: AL.LOCATED
S MOUNT/FOREIGN DBA2:
%MOUNT-I-MOUNTED
mounted on _DBA2:
S RUN SYSSSYSTEM:BAD
BAD>DB2:
BAD -- TOTAL NO+ OF BAD BLOCKS - 2.

5-4

should

use

BAD BLOCK LOCATOR UTILITY
The ALLOCATE command requests the allocation of a specific disk drive,
DBA2.
The response from the ALLOCATE command indicates that the
device was successfully allocated. The MOUNT/FOREIGN command mounts
the disk volume as a foreign disk.
The MOUNT command response
indicates that DBA2 was successfully mounted. The RUN SYS$SYSTEM:BAD
command invokes BAD. Specifying DB2 causes BAD to analyze each block
on the disk volume and record the bad blocks. After BAD has tested
all the blocks, it indicates that the humber of bad blocks on DBA2 is
2. You exit from BAD by entering <CTRL/Z> in response to the BAD>
prompt.

5.4.2

Running BAD from Command Procedures

You can invoke the BAD utility from a VAX/VMS command procedure.
The
following is a command procedure, named STEPS.COM, that invokes BAD
and gives other DCL commands.

ALLOCATE DBB1:
MOUNT/FOREIGN DBBl:
S RUN SYSSSYSTEM:BAD
DB2:1.: /LI
S DISMOUNT/NOUNLOAD
$ INITIALIZE DBB1:
$
$

To call the command procedure, type the following in response
DCL prompt:

the

$ @STEPS
The operating system executes the commands in the order they are given
within the command procedure.
Note that because you are calling the command procedure from DCL, the
default file type is COM and need not be specified. For a thorough
discussion of command procedures, refer to the VAX/VMS Guide to Using
Command Procedures.
BAD also allows you to use a command procedure execute a series of BAD
commands.
The following example is a command procedure, named
BADCMD.CMD, that contains the commands BAD is to execute.
These
commands are explained in Section 5.5.2.

DM2:/MAN
4~;

10~?.
©TRL/Z)

To call the command procedure, type:
$ MCR BAD
BAD> @BADCMDS
The default file type in this example is CMD because you
the command procedure from the MCR command interpreter.

are

calling

BAD is invoked, performs the requested functions, and exits.
Note
that you can omit the file type when you call the command procedure.
You can call up to three other command procedures from within one
command procedure.

5-5

BAD BLOCK LOCATOR UTILITY
BAD QUALIFIERS

5.5

BAD provides five qualifiers which, when added to the command string,
modify BAD operation. Table 5-1 lists the BAD qualifiers and gives a
summary their functions.
Table 5-1
BAD Qualifiers
...

·--~-··-- -~··--·· ---------···--~----------------.

Qualifier

Notation

Function

1---------1-----. . . .___., ____. . ,___ ·--""' - . . . . . . . . . . . -·-·-···"·-·-------. ·----·. ·----------------List

/LI

Lists logical block numbers
blocks at your terminal

Manual

/MAN

Enters specific bad blocks to the bad
block descriptor and tests the disk
volume

Override

/OVR

Converts
last-track
non-last-track devices

Retry

/Rr~TRY

Enables the device driver
soft errors

Update

/UPD

Updates the bad
block
without testing the disk

descriptor

bad

devices

correct

The following sections describe each of these qualifiers in detail.

5.5.1

The List Qualifier

The List qualifier (/LI) causes all bad blocks to be listed by logical
block number (LBN) on your terminal.
Each time BAD encounters a
faulty block, it writes the following message:
BAD -- BAD BLOCK FOUND - LBN= n
The value of n is the logical block
decimal.

number

(LBN)

the

block

This qualifier is valid for all devices. If you do not specify the
LIST qualifier, BAD will execute without listing the bad blocks at
your terminal.
Example
BAD> DB2:/LI
BAD -- DB2:

5.5.2

BAD BLOCK FOUND - LBN= 20nn3

The Manual Qualifier

The Manual qualifier (/MAN) permits you to enter specific blocks to
the bad block descriptor of an unformatted volume. You may want to
use this qualifier to allocate specific blocks or a series of blocks
so that they will not be used by other files.

s-n

BAD BLOCK LOCATOR UTILITY
When you use the Manual qualifier, BAD prompts for the
number of the blocks you want to enter:

logical

block

BAD> LBN(S)=
You can specify a single block or consecutive blocks in the form:
lbn: [count]
The value of lbn is the logical block number in decimal and count is
the number of consecutive blocks beginning at the specified LBN. You
must use the colon (:) when specifying consecutive blocks and separate
different LBNs or consecutive LBNs on a single line by a space, comma,
or tab. Both lbn and count default to decimal unless they are
preceded by the pound sign (#) to inoicate octal.
After you finish entering specific bad blocks, type <CTRL/Z> or <ESC>.
BAD enters the blocks you have specified into the bad block descriptor
and then tests the volume for bad blocks.
If you do not specify an LBN in response to the prompt but instead
press <RETURN>, BAD lists the contents of the bad block descriptor in
the format:
lbn:count
The value of lbn is the initial LBN ~f a possible sequence of bad
blocks and count is the number of bad blocks in the sequence (in
decimal). Single blocks are represented in the same format as a
sequence of bad blocks.
Examples
1.

BAD>DBO:/MAN
BAD> l...BN ( s) ::~ 4!:5 (CTRL/Z)
BAD -- DBO: TOTAi... BAD BLOCKS= 2+
BAD enters the block represented by LBN 45 into the bad block
descriptor, tests the disk for bad blocks, and reports the
total number of bad blocks that it found at your terminal.
(BAD does not include manually entered blocks in this total).
2.

BAD>DM2:/MAN
BAD> LBN <S >:::: :I. 00: ::.~ v :·~ 200: 1. 0 + @9
BAD -- DM2: TOTAi... BAD BLOCKS= 13+
BAD enters blocks 100, 101, 3, and 200 through 209
bad block descriptor.

into

the

3.
BAD> I:iM:3: /MAN

BAD> l...BN <S) ::~ (Bff)

oootoo:oo2
000003: 00:1.

()()0200: :t. 00
BAD lists all blocks in the bad block descriptor
block number and count.

5-7

logical

BAD BLOCK LOCATOR UTILITY
The Override Qualifier

5.5.3

The Override qualifier (/OVR) causes BAD to ignore
last-track
information (the MDBSF and SDBSF, described in Section 5.1.2.1).
When specified, /OVR creates a bad block descriptor on the last good
block before the last track of the disk, but does not generate a
message at your terminal. If the last track does not contain a bad
block descriptor, or if you suspect that the last track is faulty, use
/OVR.
The Override qualifier converts last-track devices to non-last-track
devices;
thus, it is valid only on last-track devices.

The Retry Qualifier

5.5.4

The Retry qualifier (/RETRY) enables the device driver to correct soft
errors.
A soft error is a type of hardware error that causes good
blocks to appear faulty. If /RETRY is not specified, BAD will prevent
the device driver from correcting soft errors, and blocks mistakenly
identified as bad will not be discovered.
There is no example for this
output when it is enabled.

qualifier

because

/RETRY

produces

The Update Qualifier

5.5.5

The Update qualifier (/UPD) enters additional blocks to the bad block
descriptor without testing the volume. Use the Update qualifier when
you want to update the bad block descriptor without destroying the
contents of the volume.
The Update qualifier prompts for additional bad blocks in the same way
as the Manual qualifier.
When you have finished specifying the
logical block numbers of the blocks you want entered to the bad block
descriptor, type <CTRL/Z> or <ESC>. BAD will update the descriptor
and exit.
If you do not specify an LBN in response to the prompt, but instead
press <RETURN>, BAD lists the contents of the bad block descriptor in
the format
lbn:

count

as described in Section 5.5.2.

Example

RUN SYSSSYSTEM:BAD
BAD> DM:l.:/UPD
BAD> LBN~~ :I. 23
BAD> tIBJIZJ
$

The Update qualifier causes BAD to enter logical block number 123 into
the bad block descriptor. Entering <CTRL/Z> returns control to DCL
without testing the device.

5-8

BAD BLOCK LOCATOR UTILITY
5.6

BAD MESSAGES

This section describes the diagnostic messages generated by BAD as
executes. Each message begins with:

BAD -- devu:
where devu:
is the device name of the
BAD is testing.

block-structured

volume

that

BAD BLOCK FILE NOT FOUND

Explanation:

The bad block descriptor cannot be read.

User Action: This message occurs when you have specified the
Update qualifier.
It means that you cannot use /UPD on the
volume without re-initializing the device.
{When the volume is
initialized, all previous data stored on the device is destroyed;
see the VAX/VMS Command Language User's Guide for information on
the INITIALIZE command.)
BAD BLOCK FILE OVERFLOW

Explanation: BAD detected more than the maximum number of bad
blocks
{12n for last~track devices and 102 for non-last-track
devices). This message usually indicates a device unit failure.
User Action:
maintenance;

Either the volume is bad or the drive requires
contact your DIGITAL Field Service Representative.

BAD BLOCK FOUND - LBN= lbn

Explanation:
specify the
decimal.

Bad blocks are reported in this format when you
List qualifier;
lbn is the logical block number in

User Action: None. This is an informational message and applies
only to the List qualifier.
BLOCK 0 BAD - DO NOT USE AS SYSTEM DISK

Explanation: This is a warning message that can be ignored on
VAX/VMS systems.
Unlike RSX-llM and IAS systems, VAX/VMS does
not use block zero for bootstrapping purposes.
User Action:

Ignore the message.

COMMAND I/O ERROR

Explanation: The
operating
system
transmission error from the keyboard.
User Action:

Retype the command.

5-9

detected

hardware

BAD BLOCK LOCATOR UTILITY

COMMAND TOO LONG
Explanation:
characters.

The command

line

you

typed

User Action:

Shorten the command line.

longer

than

DEVICE IS AN ALIGNMENT CARTRIDGE
Explanation: The factory-written label on the last track of a
last-track device indicates that the device is an alignment
cartridge.
User Action:

Mount and process another device.

DEVICE NOT IN SYSTEM
Explanation: The requested device was not made part of the
system generation or the device unit does not exist on the host
configuration.
User Action: Reconfigure the system with the SYSGEN utility (see
the VAX/VMS System Manager's Guide for details on SYSGEN).

DEVICE NOT READY
Explanation: BAD cannot access the device because the
not reached operating speed.

unit

has

User Action: Allow the unit to reach operating speed and reenter
the command line.

DUPLICATE BLOCK NUMBER - lbn
Description: The logical block number
present in the bad block descriptor.

you

User Action: Enter another block number.
only to the Manual and Update qualifiers.

entered
This

already

message

applies

FAILED TO ATTACH
Explanation:

BAD cannot gain control of the unit to be tested.

User Action: The device is allocated to another user.
disk on another device unit.

Mount the

FAILED TO READ MANUFACTURER'S BAD SECTOR FILE
Explanation: A disk-read hardware error has prevented
reading the MDBSF of a last-track device.
User Action:

BAD

from

Run BAD again and specify the Override qualifier.

5-10

BAD BLOCK LOCATOR UTILITY
FAILED TO READ SOFTWARE BAD SECTOR FILE
Explanation: BAD cannot read the Software
File with the Update qualifier enabled.
User Action:

Detected

Bad

Sector

Run BAD again and specify the Override qualifier.

FAILED TO WRITE BAD BLOCK FILE
Explanation:
descriptor.
error.

bad
block
BAD cannot make entries into the
This condition is usually caused by a disk write

User Action: Run BAD again.
should be discarded.

If the problem persists, the volume

FATAL HARDWARE ERROR
Explanation:
running.

A machine hardware problem is preventing

BAD

from

User Action:

Contact your DIGITAL Field Service Representative.

HANDLER/DRIVER MISSING
Explanation: The device driver associated with the device
that you specified is not loaded in the operating system.

unit

User Action: Load the device driver with the SYSGEN utility
(described in the VAX/VMS System Manager's Guide). For further
information on device drivers, consult the VAX/VMS Guide to
Writing a Device Driver.
ILLEGAL DEVICE
Explanation: BAD does not run on volumes
structured (for example, magnetic tapes).
User Action:

that

are

not

block

Mount and run BAD on a block-structured volume.

INVALID BLOCK NUMBER - n
Explanation:

You entered an invalid logical block number.

User Action: Type another value and reenter the command lines.
This message applies only to the Manual and Update qualifiers.
INVALID SWITCH
Explanation:

BAD does not recognize the qualifier you specified.

User Action:

Enter a valid BAD qualifier (see Section 5.5).

5-11

BAD BLOCK LOCATOR UTILITY

MANUFACTURER'S BAD SECTOR FILE CORRUPT
Explanation: The MDBSF is improperly
applies only to last-track devices.
User Action:

formatted.

This

message

Contact your DIGITAL Field Service Representative.

PRIVILEGE VIOLATION
Explanation: BAD accessed a device that was already
another user.
User Action:
device unit.

Mount the volume you want BAD to

test

mounted
on

another

SYNTAX ERROR
Explanation:

BAD detected a syntax error on the command line.

User Action:
command line.

Determine

TOTAL NO.

the

correct

syntax

and

reenter

the

OF BAD BLOCKS = n

Explanation: This message indicates the total number of bad
blocks on the volume.
This message appears when BAD finishes
testing the volume.
User Action:

Write the bad block count on the device label.

UNRECOVERABLE ERROR n
Explanation: BAD is terminated by an I/O error. The value of
represents the I/O error number returned by the device driver.
User Action:

Contact your DIGITAL Field Service Representative.

WRITE-LOCKED
Explanation:
volume.

BAD attempted

run

the

write-locked

disk

User Action: Mount the device without the Nowrite qualifier to
unlock the device. See the VAX/VMS Command Language User's Guide
for information on the MOUNT command qualifiers.

5-12

CHAPTER

FILE STRUCTURE VERIFICATION UTILITY

The File Structure Verification Utilities (VFYl and VFY2) check the
readability and validity of Files-11 Structure Level 1 and 2 volumes.
With the addition of a qualifier, VFY can also:
•

Print out the number of available blocks on a Files-11 volume

•

Search for "lost files"

•

List all files in the index file

•

Mark as "used" all blocks that appear available
are allocated to a file

•

Rebuild the storage bit map
index file

•

Restore files marked for deletion

•

Perform a read check on every allocated block on the volume

The sections that follow describe
recovery, how to invoke VFY, the
qualifiers, and VFY error messages.

6.1

reflect

but

information

validity checking
VFY command line

actually
in

the

and
error
format and

VALIDITY CHECKING

If you do not specify a qualifier on the VFY command line, VFY
performs a validity check of the volume mounted on a specified device
unit. VFY first checks the integrity of all the file headers
contained in the index file of the volume.
Each file on the volume has a file header that describes properties of
the file and its physical location on the volume. The file headers
are part of the index file [O,O]INDEXF.SYS, which is created when the
volume is initialized. VFY makes sure that blocks referenced in the
map area of each file header are reported as allocated in the storage
bit map file [O,O]BITMAP.SYS.

~-1

FILE STRUCTURE VERIFICATION UTILITY
As it verifies the volume, VFY reports any file errors either at your
terminal or in a specified listing file
(see Section ~.4). VFY
identifies different file errors. Each message is preceded by a file
identification line that identifies the file containing the error:
FILE ID n file-spec OWNER [uic]
n

The file identification number assigned
file by VAX/VMS when it creates the file

file-spec

The name, type and version number of the file that
contains the error

uic

The user identification code of the owner
file

One or more of the
identification line.

messages

listed

below

follows

the

file

VFY failed to read the file header for the specified
identification. One of the following conditions exists:

file

I/O ERROR READING FILE HEADER-ERROR CODE n

•

the device is not mounted

•

the device is offline

•

the hardware has failed

•

the header block is bad

BAD FILE HEADER
Software checks on the validity of the file header indicate that
the header has been corrupted. The file is permanently damaged.

MULTIPLE ALLOCATION n•m
The specified logical block number is allocated to more than one
file.
VFY indicates the logical block number (LBN) as two octal
integers n and m representing the low- and high- order bits of
the LBN.
If VFY detects a multiply-allocated block,
it finishes the
validity check and scans the volume again to identify which files
share each block. After it lists each multiply-allocated block,
VFY prints a summary line for the file as follows:

SUMMARY:MULT=n, FREE=n, BAD=n.
MULT

The number of multiple block allocations

FREE

The number of blocks marked free that
allocated

BAD

The number of bad retrieval pointers in the file header

should

have

For information about deleting multiply-allocated blocks, see
6.2.2.

~-2

been

Section

FILE STRUCTURE VERIFICATION UTILITY

BLOCK IS MARKED FREE nvm
The specified LBN is allocated to the indicated file but is not
marked as allocated in the storage bit map (see Section 6.2.3).

BAD BLOCK NUMBER nvm
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
The operating system failed while the specified file was being
deleted.
The deletion was not completed and the file header
still exists (see Section 6.2.l).

HEADER MAP OUT OF SYNC
VFY detected an error in the header map area which also indicates
a corrupted file header.
You can suppress VFY output on a terminal device by typing <CTRL/O>.

6.2

FILE ERROR RECOVERY

You can use the file error information obtained through the validity
check to correct file errors on the volume. The following sections
discuss how to delete and restore files marked for deletion, how to
eliminate free and multiply-allocated blocks, and how to recover lost
blocks.

6.2.1

Restoring Files Marked for Deletion

If VAX/VMS fails before it finishes deleting a file, you can
to restore the file or resume the deletion process.

use

VFY

To restore a file marked for deletion, run VFY specifying the Delete
qualifier
(Section 6.5.1) to reset the marked-for-deletion indicators
in the file headers. Once the deletion indicators has been reset, run
VFY specifying the Lost qualifier (Section ~.5.4) to scan the entire
file structure. You may not be able to restore the entire file
because the operating system may have deleted part of the file before
it failed.
Once you obtain the file identification of a marked-for-deletion file,
you can finish the deletion process by running the Peripheral
Interchange Program (PIP). Because PIP is an RSX-llM utility, you
must use the VAX/VMS MCR interface to invoke it. Enter the following
command at the DCL prompt:
$ MCR PIP

THE PIP utility responds with the prompt:
PIP>

n-3

FILE STRUCTURE VERIFICATION UTILITY
Specify the File identification you obtained from the VFY output
Section 6.1) in response to the PIP> prompt:

(see

PIP>IFI:12:20/DE
PIP -- FAILED TO MARK FILE FOR DELETE-NO SUCH FILE
In the above example, the file with file identification 12,20 is
deleted from the default device.
The PIP error message appears
because the file system denies the existence 0f files already marked
for deletion. However, the file is deleted.
If you have restored or deleted files, you should update the volume's
storage bit map by running VFY with the Rebuild qualifier (see Section
6.5.6).

n.2.2

Deleting Multiply-Allocated Blocks

VFY reports all files that contain multiply-allocated blocks (see
Section 6.1).
Once you have the file specification of these files,
you can eliminate them with PIP, as described in Section n.2.1, until
there are no more files that share blocks.
Be careful when deleting multiply-allocated files.
After you have
deleted the files, run VFY again to ensure that all of the files with
multiply-allocated blocks have been eliminated.

6.2.3

Eliminating Free Blocks

After you have purged the files of multiply-allocated
blocks,
eliminate blocks that 'are erroneously marked as free in the storage
bit map. To correct the storage bit map, run VFY again and specify
the Update qualifier (Section 6.5.7). This qualifier allocates all
blocks that should have been marked as allocated.
Once you have cleared the volume of multiply-allocated blocks and
it is safe to create new files and
blocks mistakenly marked free,
extend existing files.
However, if multiply-allocated and "free"
blocks still exist, the volume may contain files whose blocks are
overwritten by multiple allocation.

6.2.4

Recovering Lost Blocks

To determine whether any blocks on a file-structured volume have been
lost, examine the last two lines of output from the validity ch~ck.
The last two lines of output give the free space on the volume.
The
first of these two lines tells how much room is available according to
the index file (the number of blocks not in use).
The second line
specifies how much room is available according to the storage bit map.
Assuming there are no other errors, these two figures should agree.
If the index file indicates that more blocks are free than the storage
bit map, those blocks are "lost" in the sense that they appear to be
allocated, but no file contains them. Run VFY again and specify the
Rebuild qualifier (Section n.5.n) to recover these lost blocks.

~-4

FILE STRUCTURE VERIFICATION UTILITY
6.3

INVOKING VFY

When running VFY to validate a volume's structure, keep in mind that:
•

No other activity should occur 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.

•

Do not abort VFY if you have specified the Delete, Rebuild, or
Update qualifier. These qualifiers modify the index file and
the storage bit map;
if you prevent them from completing
their functions, you may seriously endanger the integrity of
the volume.

•

Before you run VFY, the volume must he mounted as a
structured volume.
The volume can be write-locked
not the system volume or if the required scratch
directed to another file-structured volume and you
running a consistency check.

To invoke VFY,
appropriate:

enter

one

the

following

command

Files-11
if it is
file is
are just

lines,

To return

Files-11 Structure Level l Format

$ RUN SYS$SYSTEM:VFY1
Files-11 Structure Level 2 Format

$ RUN SYS$SYSTEM:VFY2
The utility responds with the prompt:
VFY>
You can now enter any VFY command string (Section
DCL at any time, type <CTRL/Z>.

~.4).

You can also invoke VFY by using the RSX-llM Monitor Console Routine
(MCR)
command.
Enter one of the following command lines, as
appropriate:
$ MCR VFYl

$ MCR VFY2
Using the MCR command, you can enter a VFY command
initial command line that invokes VFY. For example:

string

$ MCR VFYl command-string
VFY will execute this command string and return control to DCL.

~-5

the

FILE STRUCTURE VERIFICATION UTILITY
6.4

VFY COMMAND STRING

The VFY command string has the following format:
VFY> [list-file-spec, scratch-device-name:=] [input-device-name:]

[/qualifier]

list-file-spec
The listing file to which VFY output will be directed.
If you
omit this parameter, VFY output is displayed at your terminal.
scratch-device-name
The device on which the scratch file produced by VFY
written. The scratch device name has the format:

devcu
where
dev
c
u

2-character alphabetic device code
I-character alphabetic controller designator
1- or 2-digit device unit number

When VFY validity checks or scans for lost files,
it creates a
scratch file.
This file is not entered in any directory, and
thus is transparent to the user. VFY automatically deletes the
scratch file when it finishes processing the volume.
If you omit this parameter, the system disk
automatically.

(SYSSDISK)

used

If you suspect that the default disk is faulty,
use this
parameter to force the scratch file to another device. VFY does
not create a scratch file if you run it with either the Free or
List qualifiers.
input-device-name
The volume to be verified.
the scratch device name.

This parameter has the same format as

/qualifier
One of the VFY qualifiers that specify the function to be
performed.
Only one qualifier can be specified per command
string. If you specify more than one, an error occurs.
If no
qualifier is specified, VFY validates the structure of the volume
mounted on the specified device. See Section ~.5 for a complete
description of each qualifier.

6.5

VFY QUALIFIERS

Table 6-1 summarizes the VFY qualifiers.
describe them in greater detail.

The

following

sections

FILE STRUCTURE VERIFICATION UTILITY
Table fi-1
VFY Qualifiers
Qualifier

Notation

Delete

/DE

Resets marked-for-deletion indicators

Free

/FR

Indicates the number of available blocks
on the volume, the number of used blocks
on the volume, and the total number of
blocks on the volume

List

/LI

Lists the entire
identification

Lost

/LO

Scans the entire file structure for files
that are not in any directory

Read Check

/RC [: n]

Checks readability of every block
every file on the entire volume

Rebuild

/RE

Recovers blocks that
appear
to
be
allocated but are not contained in a file

Update

/UPD

Allocates
available
file

6.5.1

Function

index

file

blocks that appear
to
be
but have been allocated to a

The Delete Qualifier

The Delete qualifier (/DE) resets the marked-for-delete indicator in
the file header of a file that was marked for deletion, but never
actually deleted.
The volume being deleted must be write-enabled;
access to the index file [O,O]INDEXF.SYS.

VFY

requires

write

VFY must be running under a system user identification code (UIC).
Do not abort VFY if you have specified the Delete qualifier.

6.5.2

The Free Qualifier

The Free qualifier
(/FR) displays on your terminal a
message
indicating the available space on a specified volume. The message has
the form:
devcu:

6.5.3

HAS n.

BLOCKS FREE, n.

BLOCKS USED OUT OF n.

The List Qualifier

The List qualifier (/LI)
lists the entire index file by file
identification.
The output for each file specifies the file number,
file sequence number, file name, and owner.
A typical index file
listing is illustrated in Figure 6-1.

6-7

FILE STRUCTURE VERIFICATION UTILITY
' " " _....

_._"'__

"•""•

VFY > DK: /LI
LISTING OF INDEX ON DKO:
FILE ID 000001,000001 INDEXF. SYS; l
OWNER
FILE ID 000002,000002 BITMAP.SYS;!
OWNER
FILE ID 000003,000003 BADBLK.SYS;l
OWNER
OWNER
FILE ID 000004,000004 000000.DIR;l
OWNER
FILE ID 000005,000005 CORIMG.SYS;l
FILE ID 000006,000006 001001.DIR;l
OWNER
FILE ID 000007,000007 001002.DIR;l
OWNER
FILE ID 000010,000010 EXEMC.MLB;l
OWNER
FILE ID 000011,000011 RSXMAC.SML;l
OWNER
FILE ID 000012,000012 NODES.TBL;l
OWNER
FILE ID 000013,000036 QIOSYM.MSG; 311 OWNER
FILE ID 000014,000037 F4PCOM.MSG;l
OWNER
,..,, ......

f'.igure 6-1
6.5.4

-...

·~·-·------

[ l, 1]
[ l, l]
[ 1, 1]
[ 1, 1]
[ 1, l]
[ 1, 1]
[ 1, 2]
[ 1, 1]

[ 1, 1]
[ 1, 1]
[ 1, 2]
[ 1, 2]

-·---

VFY Index File Listing

The Lost Qualifier

The Lost qualifier (/LO) scans the entire file structure looking for
files that are not in any directory and, are lost in the sense that
they cannot be referenced by file name. VFY creates a list of the
files and enters them in the lost file directory [1,3].
Before you use the /LO qualifier, see if the volume has the directory
[1,3].
If this directory does not exist on the volume, create it
using the DCL command CREATE/DIRECTORY, explained in the VAX/VMS
Command Language User's Guide.

6.5.5

The Read Check Qualifier

The Read Check qualifier (/RC[:n]) checks to ensure that
of every file on a specified volume can be read.

every

block

The optional parameter [:n] is the blocking factor which indicates the
number of file blocks to be read at a time. The default value is the
maximum number of blocks in memory that are available to VFY.
Because Read Check
write-locked.

read-only

operation,

When VFY detects an error, it identifies the
manner:
FILE ID n file-spec.

the

file

volume

can

the

following

blocks used/blocks allocated

VFY prints first the file identification line, then an error message.
If a blocking factor other than 1 is in use, VFY issues the following
message:
ERROR STARTING AT VBN n LBN n - ERROR CODE -err
VBN n is the virtual block number that marks the start of the error,
LBN n is the logical block number, and err is a negative number that
represents an error code.

n-8

FILE STRUCTURE VERIFICATION UTILITY
After VFY prints the first error message, it prints out one or more
error messages indicating the exact block or blocks in error. These
error message lines appears in the following format:
ERROR AT VBN n - ERROR CODE -err
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 all
right.
The negative number -err is -4 to indicate a device parity error.
Other error codes are contained in the VAX/VMS System Messages and
Recovery Procedures Manual.
If VFY does not display an ERROR AT line, it has failed
multiple blocks, but individual blocks are still readable.

6.5.6

read

The Rebuild Qualifier

The Rebuild qualifier (/RE) recovers lost blocks, that is, blocks that
appear to be allocated but which are not contained in any file.
Before you can specify Rebuild, you must remove all multiply-allocated
blocks from the volume.
The volume being updated must be write-enabled;
write-access to the storage bit map [O,O]BITMAP.SYS.

requires

VFY

You must be running under a system U!C, or be the owner of the volume.
Do not abort VFY if you have specified the Rebuild qualifier.

6.5.7

The Update Qualifier

The Update qualifier (/UPD) allocates all blocks
available but are actually allocated to a file.
Files with multiply-allocated blocks must be
structure before the update can be run.

that

appear

deleted

from

the

file

The volume being updated must be write-enabled;
write-access to the storage map [O,O]BITMAP.SYS.

VFY

requires

VFY must be running under a system user identification code UIC.
The scratch file should be on another volume. If this is impossible,
the volume must be dismounted immediately after VFY terminates. The
procedure you should follow is the same for Update as it is for
Rebuild. VFY issues a detailed message specifying the scratch file to
be deleted.
Do not abort VFY if you have specified the Update qualifier.

6-9

FILE STRUCTURE VERIFICATION UTILITY
6.6

VFY MESSAGES

This section describes in detail the messages generated by VFY when it
encounters various kinds of errors.
Messages are issued in the
format:
VFY -- message
COMMAND SYNTAX ERROR
Explanation: The command entered
syntax rules.
User Action:

did

not

conform

command

Retype the command line using the correct syntax.

FAILED TO ALLOCATE SPACE FOR TEMP FILE
Explanation:

The volume specified for the scratch file is full.

User Action:
rerun VFY.

Delete all unnecessary

files

the

volume

and

FAILED TO ATTACH DEVICE
or
FAILED TO DETACH DEVICE
or
ILLEGAL DEVICE
Explanation:
device.

The file specification entered contains an

invalid

User Action:
specified.

Retype the command line

device

with

the

correct

FAILED TO CLOSE DIRECTORY FILE
See I/O ERROR messages.
FAILED TO ENTER FILE
Explanation:

One of the following conditions may exist:

•

VFY is not running under a system UIC.

•

The device is not online.

•

The device is not mounted.

•

The hardware has failed.

User Action:
message and
line.

Determine which of the above conditions caused the
correct that condition, then reenter the command

6-10

FILE STRUCTURE VERIFICATION UTILITY

FAILED TO OPEN DIRECTORY FILE
See OPEN FAILURE message.
ILLEGAL SWITCH
Explanation: The qualifier you specified is not a
qualifier or you used a valid qualifier incorrectly.
User Action:
qualifier.

Reenter the command line and

specify

valid
the

VFY

correct

I/O ERROR ON INPUT FILE -- HANDLER ERROR CODE n
or
I/O ERROR ON OUTPUT FILE -- HANDLER ERROR CODE n
or
I/O ERROR READING DIRECTORY FILE -- HANDLER ERROR CODE n
or
FAILED TO CLOSE DIRECTORY FILE -- HANDLER ERROR CODE n
Explanation: In these messages, n is the handler error code
number.
For an explanation of handler error codes, see the
VAX/VMS System Messages and ~ecovery Procedures Manual.

One of the following conditions may exist:
•

The device is not online.

•

The d?vice is not mounted.

•

The hardware has failed.

User Action:
message and
line.

Determine which of the above conditions caused the
correct that condition, then reenter the command

OPEN FAILURE ON BIT MAP
or
OPEN FAILURE ON INDEX E'ILE
or
OPEN 1''AILURE ON LISTING FILE
or
OPEN FAILURE ON TEMPORARY FILE
or
FAILED TO OPEN DIRECTORY FILE

n-11

FILE STRUCTURE VERIFICATION UTILITY
Explanation:

One of the following conditions may exist:

•

VFY is not running under a system UIC.

•

The named file does not exist in the specified directory.

•

The volume is not mounted.

•

The specified directory does not exist.

User Action: Determine which of the above conditions caused the
messag~ and correct that condition, then retype the command line.

THEY ARE STILL LOST, COULD NOT FIND DIRECTORY
Explanation:
volume.

The lost file directory (1,3] is not present on the

User Action: Use the MCR UFD command to enter UFD [1,3] on the
volume.
(See the VAX-11/R~_)~_~lM U_ser~_? Guide for details on MCR
commands.)

r.-12

CHAPTER 7
LIBRARIAN UTILITY

The Librarian is a utility that allows you easy access to libraries.
Libraries are indexed files that contain frequently used modules of
code or text. There are four different types of libraries -- object,
macro, help, and text. The library type indicates the type of module
that the library contains. Section 7.1 describes the four types of
libraries.
Each library also contains indexes that store information
about the library's contents,
including the type, location, and
modification
history of the individual modules.
Section 7.1.2
describes library indexes.
The Librarian consists of two parts:
(1) the DIGITAL Command Language
(DCL)
command LIBRARY (see Section 7.2) which you use to replace and
maintain modules in an existing library, or to create a new library;
and
(2) a collection of Librarian routines (see Section 7.4) that you
can call from a program to initialize and open a library, and to
retrieve, insert, and delete modules.

7.1

LIBRARIES

The following sections describe the four library types -- object,
macro, help, and text -- and the contents of library indexes.

7.1.1

Types of Libraries

There are four types of libraries, distinguished by their file types:
•

Object libraries (file type OLB) contain frequently called
routines and are used as input to the linker. The linker
searches the object module library whenever it encounters a
reference it cannot resolve from the specified input files.
See the VAX-11 Linker Reference Manual for more information on
how the linker uses libraries:

•

Macro libraries (file type MLB) contain macro definitions used
as input to the assembler. The assembler searches the macro
library whenever it encounters a macro that is not defined in
the input file.
See the VAX-11 MACRO La~guage Reference
Manual for information on defining macros.

libraries (file type HLB) contain help modules;
that is,
• Help
modules that provide user information about a program. You
can retrieve help messages in your program hy calling the
appropriate
Librarian
routines.
See
Section 7.3 for
information about creating help modules for insertion into
help libraries.

7-1

LIBRARIAN UTILITY
•

Text libraries (file type TLB} contain any sequential record
files that you want to retrieve as data for your program.
Your programs can retrieve text from text libraries by calling
the appropriate Librarian routines. See the /INSERT qualifier
in Section 7.2.2 for information about inserting text files
into text libraries.

You use DCL commands to manipulate libraries in their entirety;
for
example, the DELETE, COPY, and RENAME commands delete, copy, and
rename libraries, respectively.
For more information
on
file
maintainance, see the VAX/VMS Command Language User's Guide.

7.1.2

Structure of Library Indexes

Every library contains a library header that describes the contents of
the library. The information in the library header includes:

• The type of library
• The number of indexes and their location in the file
• The version number of the Librarian
• The library's creation date and time
• The last update date and time
• The library's preallocated size and its current size
Each module has a module header that contains information about the
module, including its type, its attributes, and its date of insertion
into the library.
Libraries can contain more than one index. All libraries contain an
index for the module name table (MNT}. Object module libraries also
contain an index called a global symbol table (GST) that is a list of
the global symbols defined in each of the library modules.
The MNT catalogs modules by module name, rather than by the name of
the input file that contained the inserted module. The only exception
to this procedure occurs with text libraries, for which the file name
of the input file containing the text automatically becomes the module
name. See the description of the /MODULE qualifier in Section 7.2.1.

7.2

THE DCL LIBRARY COMMAND

This section describes how to create, modify, and maintain libraries
using the DCL command LIBRARY. This information also appears in the
VAX/VMS Command Language User'~ Guid~.
The purpose of the LIBRARY command is to maintain object, macro, help,
or text libraries.
The command's default operation is to replace
modules. By specifying various qualifiers, you can also use the
LIBRARY command to create and modify libraries;
and to insert,
delete, extract, and list library modules and symbols.

7-2

LIBRARIAN UTILITY
7.2.1

Library Command String

To use the LIBRARY command, enter
response to the DCL prompt:
$ LIBRARY/qualifier{s)

the

library-file-spec

following

command

string

[input-file-spec[/MODULE=module-name] [, ••• ]]

/qualifier(s)
Section

The function(s) to be performed by the LIBRARY command.
7.2.2 describes the qualifiers in detail.
library-file-spec

The name of the library you want to create or modify.
This
parameter is required. If you do not specify a library file, you
will be prompted for one as follows:
$_Library:
No wild card
specification.

characters

are

allowed

the

library

file

If the file specification or a qualifier in the command line does
not include a file type, the LIBRARY command assumes a default
type of OLB, indicating an object library.
NOTE
Any attempt to modify a library that was
created
by
the VAX-11 Version 1.0
Librarian results
in
an
automatic
compression
into
the
new
format
introduced with
Version
2.0.
The
compression occurs before the requested
modification.
(See
the
/COMPRESS
qualifier
in
Section
7.2.2.)
Furthermore, libraries created before
Version 2.0 that have not been modified
or compressed will appear in a different
format
when
listed
by
the /LIST
qualifier.
input-file-spec[, ••• ]
The names of one or more files that contain modules you
insert into the specified library.

want

Whenever you include an input file specification, the LIBRARY
command either replaces or inserts the modules contained in the
input file(s)
into the specified library.
The input file
specification is required when you specify either /REPLACE (the
LIBRARY command's default operation) or /INSERT, which is an
optional qualifier. If you do not specify an input file when you
use these qualifiers, you will be prompted for it as follows:
$ File:

When you use the /CREATE qualifier to create a new library, the
input file specification is optional. If you include an input
file specification with /CREATE, the LIBRARY command first
creates a new library, and then inserts the contents of the input
file(s) into the library.
7-3

LIBRARIAN UTILITY
Note that the /EXTRACT qualifier does not accept
specification.

input

file

If you specify more than one input file, separate the file
specifications with commas (,). The LIBRARY command will then
insert the contents of each file into the specified library.
If any file specification does not include a file type and if the
command string does not indicate one, the LIBRARY command will
assume a default file type of OBJ, designating an object library.
You
can control the default file type by specifying the
appropriate qualifier as indicated below.
Qualifier

Default File Type

/HELP
/MACRO
/OBJECT
/TEXT

HLP
MAR
OBJ
TXT

Note also that the file type you specify with the library file
specification affects the default file type of the input file
specification, provided that you do not specify the /CREATE
qualifier.
For example, if the library file type is HLB, MLB,
OLB, or TLB, the input file type default will be HLP, MAR, OBJ,
or TXT, respectively.
Wild card
characters
specification(s).

are

allowed

the

input

file

/MODULE=module-name
The module-name of a text module you want to insert or replace.
When you are inserting text modules into a library, the input
file that you specify is taken to be a single module. Therefore,
the file name of the input file specification becomes the
module-name. If you want the file you are inserting to have a
module-name different from the input file name, use the /MODULE
qualifier to name the added module.
You can also use the /MODULE qualifier to enter a text module
interactively.
If you specify the logical name SYS$INPUT as the
input file, and issue the /MODULE qualifier, the LIBRARY command
will insert the text you enter from the console into the
specified library module. To terminate the console input, press
<CTRL/Z>.
Remember that the /MODULE qualifier is an input file qualifier;
it assumes that you are either replacing or inserting a new text
module.
Therefore,
the
qualifiers
that
remove
modules -- /EXTRAtT, /DELETE, /REMOVE -- are incompatible with
/MODULE.

7.2.2

Command Qualifiers

When using the LIBRARY command, you can specify qualifiers that
request more than one function in a single command, with some
restrictions. Generally, you cannot specify multiple qualifiers that
request incompatible functions. The qualifiers that perform library
functions, related qualifiers, and qualifier incompatibilities are
summarized in Table 7-1.

7-4

LIBRARIAN UTILITY
Table 7-1
LIBRARY Command Qualifier Compatibilities
Qualifier

Incompatible
Qualifiers

Related Qualifiers

! - - - - - - - - - - - - - + - - - - - - - --·-·· ··------+--·-·····- ··-·-···----·. ··--· --··-

/COMPRESS

/OUTPUT

/CREATE, /EXTRACT

/CREATE 1

/SQUEEZE, 2
/GLOBALS 3
/SELECTIVE_SEARCH 3

/COMPRESS, /EXTRACT

/CROSS_REFERENCE

/ONLY

/EXTRACT

/DELETE

/EXTRACT

/OUTPUT

/COMPRESS, /CREATE,
/DELETE, /INSERT
/LIST, /REMOVE
/REPLACE

/INSERT

/SQUEEZE, 2
/GLOBALS 3
/SELECTIVE_SEARCH 3

/EXTRACT

/LIST

/FULL, /NAMES, 3

/EXTRACT

/ONLY

/REMOVE 3
/REPLACE
/MODULE 4

/EXTRACT
/SQUEEZE, 2
/GLOBALS 3
/SELECTIVE SEARCH 3
/TEXT
-

/EXTRACT
/EXTRACT, /DELETE
/REMOVE

1. The /CREATE, /INSERT, and /REPLACE qualifiers are not incompatible;
however,
if you specify more than one, /CREATE takes precedence over
/INSERT, and /INSERT takes precedence over /REPLACE.
The related
qualifiers for /CREATE are applicable only if you enter one or more
input files.
2. This qualifier applies only to macro libraries.
3. This qualifier applies only to object libraries.
4. This file qualifier applies only to text libraries.
/COMPRESS[=(option[, ••• ])]
Requests the LIBRARY command to perform either of
functions:

the

following

•

Recover unused space in the lihrary resulting from module
deletion

•

Reformat a library created by the VAX/VMS
Librarian into the Version 2.0 format

Version

1.0

When you specify /COMPRESS, the LIBRARY command by default
creates a new library with n version number one higher than the
existing library.
Use the /OUTPUT qualifier to specify an
alternate name for the compressed library.

7-5

LIBRARIAN UTILITY
Specify one or more of the following options to increase or
decrease the size of the library, overriding the values specified
when the library was created:
BLOCKS:n

Specifies the number of 512-byte
allocated for the library

GLOBALS:n

Specifies the maximum number of global symbols the
library can contain (for object module libraries
only}

MODULES:n

Specifies the maximum number of modules or
the library can contain

KEYSIZE:n

Changes the maximum length
global symbol names.

If you specify more than one option, separate
and enclose the list in parentheses.

blocks

module
them

macros

names

with

commas

/CREATE[=(option[, ••• ]}]
Requests the LIBRARY command to create a new library.
When you
specify /CREATE, you can optionally specify a file or a list of
files that contain modules to be placed in the library.
By default, the LIBRARY command creates an object module library;
specify /MACRO, /HELP, or /TEXT to indicate that the library is a
macro, help, or text library.
Specify one or more of the following options to control the
of the library, overriding the system defaults:

size

BLOCKS:n

Specifies the number of 512-byte blocks to be
allocated
for the library.
By default, the
LIBRARY command allocates 100 blocks for a new
library.

GLOBALS:n

Specifies the maximum number of global symbols the
library can contain initially. By default, the
LIBRARY command sets a maximum of 128 global
symbols for an object module library.
(Macro,
help, and text libraries do not have a global
symbol directory;
therefore, the maximum for
these libraries defaults to O.}

MODULES:n

Specifies the maximum number of mooules
the
library can contain.
By default, the LIBRARY
command sets an initial maximum of 512 modules for
an object module library and 25n modules for a
macro, help, or text library.

KEYSIZE:n

Specifies the maximum name length of modules or
global symbols.
By default, the LIBRARY command
limits the names of global symbols and object,
macro, and text modules to 31 characters. The
name length limit for help
modules
is
15
characters.

7-n

LIBRARIAN UTILITY
KEYSIZE:n
(Cont.)

When you specify a key-size value,
remember that
VAX-11 MACRO and the VAX-11 Linker do not accept
module names or global symbol names in excess of
31 characters.

If you specify more than one option, separate
and enclose the list in parentheses.

them

with

commas

/CROSS_REFERENCE[=(option[, ••• ])]
Requests a cross-reference listing of an object library.
If you omit this qualifier, cross-reference listings will not be
provided.
However, if you specify /CROSS REFERENCE without
specifying an option, you will obtain cross-reierence listings by
default that contain only symbols by name and symhols by value.
You can specify one or more of the following options:
ALL

Specifies that all types of cross
required

MODULE

Specifies a cross-reference listing of both the
global symbol references in the module and the
global symbol definitions

NONE

Specifies
required.

SYMBOL

Provides a cross-reference listing by symbol name

VALUE

Provides a cross-reference listing of
value

that

references

cross-reference

If you specify more than one option, separate
commas and enclose the list in parentheses.

the

listing

symbols
options

are

by
with

/DELETE=(module[, ••• ])
Requests the LIBRARY command to delete (physically remove) one or
more the modules from a library. You must specify the names of
the modules to be deleted. If you specify more than one module,
separate the module names with commas and enclose the list in
parentheses.
Wild card characters are allowed in the module specification.
If you specify the /LOG qualifier
command will issue the message:

with

/DELETE,

the

LIBRARY

%LIBRAR-S-DELETED, MODULE module-name DELETED FROM library-name
/EXTRACT=(module[ •••• ])
Copies one or more modules from an existing library into a new
file.
If you specify more than one module, separate the module
names with commas and enclose the list in parentheses.
Wild card characters are allowed in the module specification.
If you specify the /OUTPUT qualifier with /EXTRACT, the LIBRARY
command will write the output into the file specified by the
/OUTPUT qualifier. If you specify /EXTRACT and do not specify
/OUTPUT, the LIBRARY command will write the file into a file that
has the same file name as the library and a file type of OBJ,
MAR, HLP, or TXT depending on the type of library.
7-7

LIBRARIAN UTILITY

/FULL
Requests a full description of each module in the module name
table.
Use this qualifier with the /LIST qualifier to request a
list of each library module in the format:
module-name [Ident

nn]dd

Inserted dd-mrnrn-yyyy

hh:rnrn:ss

The identification number and the number of symbols
in object libraries.

[n symbols]

appear

only

/GLOBALS
/NOGLOBALS
Control, for object module libraries, whether the names of global
symbols in modules being inserted in the library are included in
the global symbol table.
By default, the LIBRARY command places all global symbol names in
the global symbol table. Use /NOGLOBALS when you do not want the
global symbol names in the global symbol table.
/HELP
Indicates that the library is a help library. When you use the
/HELP qualifier, the library file type defaults to HLB and the
input file type defaults to HLP.
/INSERT
Requests the LIBRARY command to add the contents of one or more
files to an existing library. If an object module input file
consists of concatenated object modules, the LIBRARY command will
each
create a separate entry for each object module in the file;
module name table entry reflects an individual module name. If a
macro or help file specified as input contains more than one
definition, the LIBRARY command will create a separate entry for
each one, naming the module name table entries according to the
names specified on the .MACRO directives or in the key-1 name in
the HELP format (see Section 7.3.l).
In text libraries, unlike object, macro, and help libraries, the
input
file
contains
data records of undefined contents.
Therefore, the Librarian catalogs the entire input file as a
single module using the input file specification as the module
name. If you want to rename the inserted module, use the /MODULE
qualifier described in Section 7.2.l.
When the LIBRARY command inserts modules into an existing
library, it checks the module name table before inserting each
module. If a module name or global symbol name already exists in
the library, an error message will be issued and the module or
symbol will not be added to the library.
To insert or replace a module in a library regardless of whether
there is a current entry with the same name, use the /REPLACE
qualifier (the default operation).

7-8

LIBRARIAN UTILITY
/LIST[=file-spec]
/NO LIST
Control whether the LIBRARY command
contents of the library.

creates

listing

the

By default, no listing is produced. If you specify /LIST without
a file specification, the LIBRARY command will write the output
file to the current SYS$0UTPUT device. If you include a file
specification that does not have a file type, the LIBRARY command
will use the default file type of LIS.
If you specify /LIST with qualifiers that perform additional
operations on the library, the LIBRARY command will create the
listing after completing all other requests;
thus, the listing
reflects the status of the library after all changes have been
made.
When you specify /LIST, the LIBRARY command provides, by default,
the following information about the library:
Directory of OBJECT library DBBO: [LIBRAR]LIBRAR.OLB;l on 14-NOV-1979 10:08:28
Creation date:
12-NOV-1979 T9:40:3o
Creator: VAX-11 Librarian VOl.02
Revision date:
14-NOV-1979 16:04:58
Library format:
1.1
Number of modules:
15
Max. key length:
31
Other entries:
73
Preallocated index blocks:
35
Recoverable deleted blocks:
15
Total index blocks used:
12

/LOG
/NO LOG
Control whether the LIBRARY command verifies each
library
operation. If you specify /LOG, the LIBRARY command will display
the module name, followed by the library operation performed,
followed by the library file specification. Examples of the /LOG
qualifier appear ip the descriptions of /DELETE and /REPLACE.
/MACRO
Indicates that the library is a macro library. When you specify
/MACRO, the library file type defaults to MLB and the input file
type defaults to MAR.
/NAMES
/NON AMES
Controls, when /LIST is specified for an object module library,
whether the LIBRARY command lists the names of all global symbols
in the global symbol table as well as the module names in the
module name table.
The default is /NONAMES, which does not list the global symbol
names.
If you specify /NAMES, each module entry name will be
displayed in the format:
module

"module-name"

global-symbol

If the library is a macro, help, or text library and you
/NAMES, no symbol names will be displnyed.

7-9

specify

LIBRARIAN UTILITY

/OBJECT
Indicates that the library is an object module library. This is
the default condition.
The LIBRARY command assumes a lihrary
file type of OLB and an input file type of OBJ.
/ONLY=(module[ •••• ])
Specifies the individual modules on which the LIBRARY command can
operate.
When you use the /ONLY qualifier, the LIBRARY command
lists or cross references only those modules specified.
If you specify more than one module, separate the
with commas and enclose the list in parentheses.

module

names

Wild card characters
specification.

module

name

allowed

are

the

/OUTPUT=file-spec
Specifies, when
qualifiers are
file.

the /EXTRACT, /COMPRESS, or /CROSS REFERENCE
specified, the file specification of the output

For /EXTRACT, the output file contains the modules extracted from
a
library;
for /COMPRESS, the output file contains the
compressed library;
for /CROSS REFERENCE, the output
file
contains the cross-reference listing.
No wild card characters are allowed in the file specification.
If you omit the file type in the file specification, a default
will be used depending on the library function qualifier and, in
some cases, the library type qualifier as shown below.

Qualifier

/COMPRESS

Library
Type
Qualifier
/HELP

/MACRO
/OBJECT
/TEXT
/CROSS_REFERENCE
/EXTRACT

Default File Type

HLB
MLB
OLB

TLB
LIS

/HELP
/MACRO
/OBJECT
/TEX'f

HLP
MAR
OBJ
TXT

/REMOVE=(symbol[, ••• ])
Requests the LIBRARY command to delete one or more entries from
the global symbol table in an object library.
If you specify
more than one symbol, separate the symbols with commas and
enclose the list in parentheses.
Wild card characters are allowed in the symbol specification.
To display the names of the deleted global symhols, you must also
specify the /LOG qualifier.

7-10

LIBRARIAN UTILITY
/REPLACE
Requests the LIBRARY command to replace one or more existing
library modules with the modules specified in the input file(s).
The LIBRARY command first deletes any existing lihrary modules
with the same name as the modules in the input file. Then, the
new version of the module is inserted in the library.
If any
modules contained in the input file do not have a corresponding
module in the library, the LIBRARY command will insert the new
modules in the library.
This is the LIBRARY command's default operation. If you specify
an input file parameter, the LIBRARY command will either replace
or insert the contents of the input file into the library.
If
you use the /LOG qualifier with the /REPLACE qualifier, the
LIBRARY command will display, in the following form, the names of
each module that it replaces or inserts.
'
%LIBRAR-S-REPLACED, MODULE module-name REPLACED IN library-file-spec
%LIBRAR-S-INSERTED, MODULE module-name INSERTED IN library-file-spec

/SELECTIVE SEARCH
Defines the input files being inserted into a library as
candidates for selective searches by the linker. If you specify
/SELECTIVE SEARCH, the modules will be selectively searched by
the linker when the library is specified as a linker input file:
only the global symbol(s) in the module(s)
referenced by other
modules are included in the symbol table of the output image
file.
/SQUEEZE
. /NOSQUEEZE
Control whether the LIBRARY command compresses individual macros
before adding them to a macro lihrary.
When you specify
/SQUEEZE, which is the default, trailing blanks, trailing tabs,
and comments are deleted from each macro before insertion in the
library.
Use /SQUEEZE with the /CREATE, /INSERT, and /REPLACE qualifiers
to conserve space in a macro library. If you want to retain the
full macro, specify /NOSQUEEZE.
/TEX'f
Indicates that the library is a text library. When you use the
/TEXT qualifier, the library file type defaults to TLB and the
input file type defaults to TXT.
/WIDTH=n
Controls the screen display width
(in characters)
for listing
global symbol names.
Specify the /WIDTH qualifier with the
/NAMES qualifier to limit the line length of the /NAMES display.
The default display width is the width
The maximum width is 132.

7-11

the

listing

device.

LIBRARIAN UTILITY
Examples
1.

$ LIBRARY/CREATE TESTLIB ERRMSG,STARTUP

The LIBRARY command creates an object module library named
TESTLIB.OLB and places the modules ERRMSG.OBJ and STARTUP.OBJ
in the library.
2.

$ LIBRARY/INSERT TESTLIB SCANLINE
$ LINK TERMTEST TESTLIB/LIBRARY
The LIBRARY command adds the module SCANLINE.OBJ to the
library TESTLIB.OLB.
The library is specified as input to
the linker by using the /LIBRARY qualifier on the LINK
command.
If the module TERMTEST.OBJ refers to any routines
or global symbols not defined in TERMTEST, the linker will
search the global symbol table of library TESTLIB.OLB to
resolve the symbols.

$ LIBRARY/EXTRACT=(ALLOCATE,APPEND)/OUTPUT=MYHELP SYS$HELP:HELPLIB.HLB

The LIBRARY command specifies that the modules ALLOCATE and
APPEND be extracted from the help library HELPLIB.HLB and
output to the file MYHELP.HLP.
4.

$ LIBRARY/CROSS_REFERENCE=ALL/OUTPUT=SYS$0UTPUT LIBRAR
The LIBRARY command requests a cross-reference listing of the
object library LIBRAR.OLB.
The cross-reference listing is
output
on
the
terminal.
The
listing
includes
cross-references by symbol, by value, and by module.

$ LIBRARY/REMOVE=(LIB_EXTRCT_MODS,,LIB_INPUT_MAC)/LOG LIBRAR
The LIBRARY command requests the removal of the global
symbols LIB EXTRCT MODS and LIB INPUT MAC from the object
library LIBRAR.OLB. The /LOG qualifier- requests that the
removal of the symbols be confirmed by messages.

$ LIBRARY/MACRO/CREATE=(BLOCKS:40,MODULES:l00) MYMAC TEMP
$ MACRO MYMAC/LIBRARY,CYGNUS/OBJECT
The LIBRARY command creates a macro library named MYMAC.MLB
from the macros in the file TEMP.MAR. The new library has
room for 100 modules in a 40-block file.
If the input file
contains multiple macros, each macro will be entered in the
new library.
The MACRO command assembles the source file CYGNUS.MAR;
the
/LIBRARY qualifier specifies the library MYMAC.MLB as an
input file.
If the source file CYGNUS contains any macro
calls not defined within the file, the assembler will search
the library.

$ LIBRARY/LIST=MYMAC.LIS/FULL MYMAC.MLB
The LIBRARY command requests a full listing of
library MYMAC;
the output is written to a
MYMAC.LIS.

the macro
file named

$ LIBRARY/INSERT/TEXT TSTRING SYS$INPUT/MODULE=TEXT1

The LIBRARY command inserts a module named TEXTl into the
text library TSTRING.TLB. The input is taken from SYS$INPUT.

7-12

LIBRARIAN UTILITY

$ LIBRARY/LIST/NAMES/ONLY=$0NE/WIDTH=80 SYMBOLIB
The LIBRARY command requests a full listing of the module
$ONE, contained in the object library SYMBOLIB.OLB. The
/WIDTH qualifier requests that the global-symbol display be
limited to 80 characters per line.

7.3

HELP LIBRARIES

Help messages are a convenient means of providing specific information
about a program to an interactive user. The help messages are stored
as modules in help libraries.
Your programs can access the help
modules by calling the appropri~te Librarian routines described in
Section 7.4. In this way, users of your program can quickly retrieve
relevant information about using your program.
You create help libraries in the same manner that you create object,
macro, and text libraries, using the LIBRARY/CREATE command des~ribed
in Section 7.2.2. However, before you can insert modules into a help
library, you must format the input file so that the Librarian can
catalog its individual modules. This section describes how to create
input files containing help modules.

7.3.1

Creating Help Files

The input file that you insert into a help library is a text file that
you build with a text editor. Each input file may contain one or more
help modules. A help module is a qroup of help messages that relates
to the same topic, or key.
Each module within a help library contains a group of related key
names, or topics, numbered key-1 through key-n.
The key-1 name
identifies the main topic of help information; for example, the name
of a command in your program that requires explanation. The key-2
through key-n names identify subtopics that are related to the key-1
name;
for example, the command's parameters and/or qualifiers. This
organization enables users of your program to find a general message
describing how to use the command, and then optionally to select
subtopics that provide additional information about the command's
parameters and qualifiers.

7.3.2

Formatting Help Files

Each key-1 line in the module consists of the key number
(1)
in the
first column, followed by the name of the key. Subsequent subkey
lines, key-2 through key-n, consist of the suhkey number followed by
the name of the subkey.
For example, a help module for a command
might have the following two key lines:
1 Command name

help message text

2 Parameters

7-13

LIBRARIAN UTILITY
Each help source file can contain several modules.
The Librarian
recognizes an individual module as a group of key-I and subkey lines,
and their associated message text. A module is terminated either by
another key-1 line or an end-of-file (EOF} record.
The format of a help source file is:
1 key-1 name

help message text

2 key-2 name

help message text

n key-n name

1 key-1 name
The Librarian stores the key-1 name in its module name table;
therefore, the name of the module is the same as the key-1 name. The
subsequent numbers in the first column indicate that the line is a
subkey.
A module can have several subkeys with the same number. For
example, a help module describing a command might have the following
key-2 lines:
2 parameters
2 arguments
You can insert comments anywhere in a module.
When the Librarian
encounters an exclamation mark as the first character on a line, it
assumes that the line is for comments. Comment lines that follow a
key-1 line are included in the module. However, when your program
retrieves help text, the Librarian does not output the comment lines.
The text of the help message may be any length;
the only restriction
to the text is that it cannot contain a number or a slash (/) in the
first column of any line. A number in the first column of a line
indicates that the line is a key. A slash {/} in the first column
indicates a qualifier line.
A qualifier line is similar to a key line, except that the Librarian
returns a list of all the qualifier lines when you request help either
on a key-1 or on the key containing the qualifiers
(usually a key-2
named "Qualifiers").
Therefore,
if your help module describes a
command that has qualifiers, the Librarian will provide a list of all
the command's qualifiers whenever you request help on the command.

7-14

LIBRARIAN UTILITY
7.3.3

Help Message Example

The help module in Figure 7-1 shows the organization of help
for the DCL LIBRARY command.

messages

DescriPtion of DCL LIBRARY command
1 LIBRARY
Creates or modifies an obJect module librarY or a macro librarhl~ or
inserts, deletesv rePlacesv or lists modulesv macrosv or Slobal s~mbol
names in a library.
Format
LIBRARY library-file-spec CinPut-file-specv ••• J
! This section lists the Parameters to the LIBRARY command
2 Parameters
library-file-spec
Specifies the name of the library to be created or modified
Wild cards are not allowed in the library file specification. If
the file specification does not include a file tYPev the LIBRARY
command assumes a default file tYPe of OLB if /OBJECT is
specified either exPlicitlY or bY default; a default file
tYPe of MLB if /MACRO is sPecifiedO a default file type of HLB
if /HELP is specifiedv or a default file tYPe of TLB if /TEXT
is specified+
inPut-file-sPecv •••
Specifies the names of one or more files that contain modules to
be inserted in the specified library.
Wild cards are allowed in the inPut file sPecifications. If
anw file sPecification does not include a file tYPev the LIBRARY
command assumes a default file tYPe of OBJ when /OBJECT is
specified either imPlicitlY or by default; a file tYPe of MAR
when /MACRO is sPecified and /RSXll is not specifiedP and a file
tYPe of MAC when /MACRO and /RSX11 are specified.
!This section lists the aualifiers to the LIBRARY command.
2 Qualifiers
/COMPRESSC=oPtionsv ••• J
Remuests the LIBRARY command to recover unused space in the
library resultins from module deletion.
Options to override initial defaults for library:
BLOCKS:n
GLOBALS:n
MODULES:n
/CREATEC=oPtions, ••• J
Remuests the LIBRARY command to create a new library. When You
sPecifY /CREATE, YOU can also sPecifw a file or a list of
files that contain modules to be Placed in the library.

Figure 7-1

Help Messages for LIBRARY Command

7-15

LIBRARIAN UTILITY
/GLOBALS CD>
/NOGLOBALS
Controls, for obJect module libraries' whether the
names of Slobal shlmbols in modules bein~ inserted
in the librarhl are included in the Slobal Shlmbol
table.

BY default, the LIBRARY command Places all Slobal
symbol names in the slobal symbol table+
/NOGLOBALS when hlOU ~o not want Slobal
shlmbol names in the slobal svmbol table+

Use

/TEXT
Indicates that the librarv is a text librar~. The default
librarhl extension is TLB and the default file extension is
TXT.
/WIDTH=n
Specifies that the width of the listins of Slobal shlmbols
(re~uested bv /NAME~3) should be of the Siven width+
The Librarian
will determine the width of the listins device if /WIDTH is
not specified.

Figure 7-1 (Cont.}

Help Messages for LIBRARY command

When you retrieve help messages, you specify the key-1 level, followed
The
by any subkeys that contain appropriate help information.
Librarian returns the help message associated with the key path you
specified.
To retrieve the LIBRARY command's key-1 help information, you would
type the DCL command HELP LIBRARY. The Librarian would return the
associated help message, followed by the
message,
"Additional
information available:" and a list of all the key-2 names in the
module. In this case, the Librarian also returns a list of all the
qualifiers specified in the qualifier lines. Figure 7-2 rlisplays the
message returned from the HELP LIBRARY command.
LIBRAl~Y

nr modifi.es an ob,ject "•C>~.l•.Jle librar!,J or a
macro lib1•ar!,J;
or i.ns£!rts. delc~tes. rePlaces• or lists modtJles• n1acros• cir slobal
(;;~mbol names in a l ibrar~:I.

Creatf.)~;

Format
LIBl~AflY

li.brarY [file···spec.,,, J

1"l<:Jdittonal information availc)ble:
Param~:~ter!5 Qualtfiers
/COMF"l'lES!'il>•oF-tions,,. • J
/EX rl'lACT=mw:.lu lt', , , ,
/FULL

/NOLI ST <D)
/LOG
/ONL.Yc(module• module)
/SlrnEEZE
/TEXT
/WIDTH~n

/CREATE["'<JF•ti ons, , , , J /CROSS C"OPt ion, , , , J
/GLOBALS <[I)
/NOGLOBALS
/MACRO
/MODUL.E=mod1Jle._r1ameJ /NAMES
/OUTF'LIT,=f i 1 e···spec:
/REMOVE,=s,,,mbo l • , , ,

Figure 7-2

< D~SYMBOL,

VALUE)
/HELP
/INSEFn
/NONAMES (fl)
/REPl...ACE <D)

HELP LIBRARY Display

7-16

/DEl..ETE'"lll0'1u le, , ••
/LISl r'"fi le··st>ec1
/Ol:C •.Jf:CT ([I)
/l~GX11

/SEL.ECTIVE._!3EAllCH

LIBRARIAN UTILITY
Note that you could not retrieve the key-2 level,
"parameters," by
typing HELP PARAMETERS.
The Librarian searches for a subkey only
after successfully finding the higher-level keys.
In other words,
if
you want to retrieve a key-3 message, you would have to specify the
key-1 and key-2 lines that are associated with the key-3 line.
Note also that if you request help information on the /GLOBALS
qualifier, the Librarian wil return /NOGLOBALS as well. As shown in
Figure 7-2, you can provide information on a qualifier that has more
than one form by associating two qualifier lines with a single help
message.
When the Librarian successfully searches the key path to the requested
key,
it displays all the key names in that path, followed by the help
message associated with the last specified key. For example:
SHELP LIBRARY/HELP
LIBRARY
/HELP
Indicates that the library is a HELP library. The
default library file t~Pe is HLB and the inPut file tYPe
is HLP+
If you try to retrieve a help message that does not have a
corresponding key in the module name table, the Librarian will issue a
message.
For example:
SHELP FIRE
SorrYv no documentation on FIRE
Additional information available:
This message will be followed by a list of all the module names in the
module name table.
If you have correctly specifiect the key-1 line, but have requested a
subkey that does not exist, the Librarian will print a message. For
example:
$HELP LIBRARY/FIRE
Sorry, no documentation on LIBRARY/FIRE
Additional information available:
Parameters Qualifiers
/COMPRESSC=oPtions ••• J

/CREATEC=options ••• J

The message will include a list of all the subkeys associated with the
last correctly specified key.
The help library serves as the repository for all your help messages.
You can include help messages in your programs by calling the
appropriate Librarian routines described in the next section.

7-17

LIBRARIAN UTILITY
7.4

LIBRARIAN ROUTINES

The Librarian provides a set of 18 routines
call to:

that

your

programs

can

• Initialize a library
•
•

Open a library
Look up a key in a library

• Insert a new key in a library
• Return the names of the keys
• Delete a key and its associated text
• Read text records
•

Write text records

Your programs can call the Librarian routines using the VAX-11
standard calling sequence provided in all languages that produce
VAX-11 native-mode instructions.
When your program
calls
the
Librarian routines,
it must furnish whatever arguments that the
routine requires. When the routine completes execution, it returns
control to your program. Your program should then analyze the success
or failure of the requested operation. See Section 7.5 for an example
of calling Librarian routines from a program.
When you link programs that contain calls to the Librarian routines,
you must specify an options file to the input file parameter of the
LINK command. The options file must contain the following file
specification and qualifier:
SYS$LIBRARY:LBRSHR/SHARE
See Section 7.5 for an example of linking a
the Librarian routines.

program

that

references

For detailed information on linker option files, see the VAX-11 Linker
Reference Manual.
Table 7-2 lists each Librarian routine and its function.
The following sections describe, in detail, each of the Librarian
routines.
The routines appear in alphabetical order. The order in
which you call them in your program depends upon the library
operations you need to perform. However, in all cases, you must call
LBR$INI CONTROL, followed by LBR$0PEN, before calling any other
routine:
Each description of a routine provides the general format for calling
the routine from your program. Spaces between arguments are included
for readability, and are not part of the syntax. Following the format
is a description of each of the arguments.
Each section lists the possible return status codes for the specific
routine, with an explanation of the code.
Success codes appear
alphabetically before an alphabeticar listing of the warning and error
codes. For more information on return status codes, see Section 7.6.
In addition, each section provides further information, under "Notes,"
about the routine,
including specific information about arguments.
Any information that does not appear in another category appears under
"Notes."
7-18

LIBRARIAN UTILITY
Table 7-2
Librarian Routines
Routine name

Function

LBR$ !NI CONTROL

Initializes a library index
other routines

LBR$0PEN

Opens an existing library or creates a new one

LBR$GET HEADER

Retrieves information from the library header

LBR$CLOSE

Closes an open library

LBR$SET INDEX

Sets the index number to
processing of the library

LBR$SET MODULE

Reads, and optionally updates, a module header

LBR$LOOKUP KEY

Looks up a key in the current index in
preparation for reading the key's associated
text

LBR$FIND

Looks up a key by its record identification in
preparation for reading the key's associated
text

LBR$ INSERT KEY

Inserts a new key in the current library index

LBR$REPLACE KEY

Replaces an existing
library index

LBR$DELETE KEY

Deletes a key from a library index

LBR$DELETE DATA

Deletes all the text records associated with a
specified module

LBR$GET RECORD

Reads a text
specified key

LBR$PUT RECORD

Writes a text record to be associated
specified key

LBR$PUT END

Terminates a sequence of records written
LBR$PUT RECORD

LBR$SEARCH

Finds index keys that point to specified text

LBR$GET INDEX

Calls a user-supplied routine to return the
contents of an index optionally qualified by a
key

LBR$GET HELP

Retrieves help text

7-19

record

key

for

use

used

the

associated

all

during

current

with

LIBRARIAN UTILITY

LBR$CLOSE
LBR$CLOSE - Close a Library

7.4.1

The LBR$CLOSE routine closes an open library.
Format

LBR$CLOSE (library-index)
library-index
A pointer to a longword that contains the library index returned
by the LBR$INI_CONTROL routine. The library must be open.
Return Status

LBR$ LIBNOTOPN
The specified library is not open.
LBR$ ILLCTL
The specified library index is not valid.
Notes

If the library index is O,
success.

LBR$CLOSE

immediately

Upon successful completion, LBR$CLOSE closes
and deallocates all of the memory used
library.

7-20

the
for

returns

with

open library,
processing the

LIBRARIAN UTILITY

LBR$DELETE~DATA
7.4.2

LBR$DELETE DATA - Delete Text Records

The LBR$DELETE DATA routine deletes all the
with the speciried module.

text

records

associated

Format

LBR$DELETE DATA (library-index, txtrfa)
library-index
A pointer to a longword that contains the library index returned
by the LBR$INI_CONTROL routine. The library must be open.
txtrfa
A pointer to a 2-longword array that contains the
address {RFA) of the text you want to delete.

record's

file

therefore,

the

Return Status

LBR$_ILLCTL
The specified library index is not valid.
LBR$ INVRFA
The specified RFA is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ STILLKEYS
Keys in other indexes still point at the
specified text was not deleted.

text;

Notes

If the reference count of the text is 0 {there are no other
indexes pointing at the text), LBR$DELETE DATA will delete the
specified text records. If the reference count is not 0 (there
are keys in other indexes pointing at the text), the Librarian
returns the error LBR$ STILLKEYS.
The Librarian reuses data blocks that contain no text.

7-21

LIBRARIAN UTILITY

LBR$DELETE_KEY
LBR$DELETE_KEY - Delete a Key

7.4.3

The LBR$DELETE KEY routine deletes a key from a library index.
Format
LBR$DELETE KEY (library-index, key-name)
library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine. The library must be open.

the

key-name
A longword that contains one of the following:
1.

The value of the key (for libraries with binary keys)

The address of a string descriptor for the key (for libraries
with ASCII keys)

Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ KEYNOTFND
The specified key has not been found.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ UPDURTRAV
The specified index update is not valid as an embedded routine.
Notes
If LBR$DELETE KEY finds the key specified
current index~ it deletes the key.

k~y-name

the

You cannot call LBRSDELETE KEY within the user-supplied routine
specified in ei~her the LB~$SEARCH or LBRSGET INDEX routines.

7-22

LIBRARIAN UTILITY

LBR$FIND
LBR$FIND - Lookup a Key by its RFA

7.4.4

The LBR$FIND routine looks up a library key by its record's
address (RFA) and prepares to read the key's associated text.

file

Format
LBR$FIND (library-index, txtrfa)
l i bra ry-i ndex

A pointer to a longword that contains the lihrary index returned
by the LBR$INI CONTROL routine. The library must be open.
txtrf a
A pointer to a 2-longword array that contains the RFA returned by
the LBR$LOOKUP KEY routine.
Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLIDXNUM
The specified index number is not valid.
LBR$ INVRFA
The specified RFA is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
Notes
If the specified RFA is valid, LBR$FIND initializes
tables so that you can read the associated text.

7-23

internal

LIBRARIAN UTILITY

LBR$GET_HEADER
LBR$GET_HEADER - Retrieve Library Header Information

7.4.5

The LBR$GET HEADER routine returns information from
to the caller.

library's

header

Format
LBR$GET HEADER (library-index, retary)
library-index
The pointer to a longword that
returned by the LBR$INI CONTROL
open.

contains
routine.

the library index
The library must be

retary
An array of 128 longwords that receives the library header.
information in the returned array is shown in Table 7-3.

The

Table 7-3
Library Header Information Array Offsets

_____________ __
,,

Offset in
Longwords

Contents

Symbolic Name

-----------. -----------------....i
0

LHI$L TYPE

Library type

LHI$L NINDEX

Number of indexes

LHI$L MAJORID

Library format major identification

LHI$L MINORID

Library format minor identification

LHI $'I' LBRVER

ASCIC version of Librarian

LHI$L CREDAT

Creation date/time

LHI$L UPDTIM

Date/time of last update

LHI$L UPDHIS

Virtual Block Number (VBN) of start
of update history (reserved)

LHI$L FREEVBN

First logically deleted block

LHI$L FREEBLK

Number of deleted blocks

LHI$B NEXTRFA

Record's File Address (RFA) of end
of library

LHI$L NEXTVBN

Next VBN to allocate at end of file

LHI $L FREIDXBLK

Number of free pre-al.located index
blocks
(continued on next page)

7-24

LIBRARIAN UTILITY
Table 7-3 (Cont.)
Library Header Information Array Offsets
Offset in
Longwords

Symbolic Name

LHI$L FREEIDX

Listhead for pre-allocated index
blocks

LHI$L HIPREAL

VBN of highest pre-allocated block

LHI$L IDXBLKS

Number of index blocks in use

LHI $ L IDXCN'I'

Number of index entries (total)

LHI$L MODCNT

Number of entries in index 1 (module
names)

LHI$L MHDUSZ

Number of bytes of additional information reserved in module header

29-128

Contents

Reserved to DIGITAL

Return Status

LBR$ LIBNOTOPN
The specified library is not open.
LBR$ ILLCTL
The specified library index is not valid.
Notes

Upon successful completion, LBR$GET HEADER
header information into the array.

7-25

places

the

library

LIBRARIAN UTILITY

LBR$GET_HELP
7. 4. 6

LBR$GET_HELP -· Return Help Text

LBR$GET HELP returns help text
program.

help

library

the

calling

[routine],

[data],

Format:
LBR$GET HELP (library-index,
key-1, key-2, ••• ,key-n)

[line-width],

library-index

A pointer to a longword that contains the index returned
LBR$INI_CONTROL routine. The library must be open.

the

line-width
The address of a longword that contains the width of the
line.

listing

routine
The address of specified routine to call for each
you want output.

line

text

data
The address of a longword of data
specified in the routine argument.

pass

the

routine

The address(es) of one or more string descriptors for the
that define the text to be output.

key(s)

key-l,key-2, ••• ,key-n

Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ NOTHLPLIB
The specified library is not a help library.
Notes
The optional line-width argument controls the width of the
listing line when available help topics are printed. If you do
not supply a line-width, or if you specify O, the line-width
defaults to 80 characters per line.

7-2()

LIBRARIAN UTILITY
If you do not supply a routine argument, LBR$GET HELP calls the
Run-Time Library procedure LIB$PUT OUTPUT to send the help text
lines to the current output device (SYS$0UTPUT). However, if you
want SYS$0UTPUT for you program to be a disk file, rather than
the terminal, it is recommended that you supply a routine to
output the test.
If the key-1 descriptor is O, or if it is not present,
LBR$GET HELP will assume that the key-1 name is "HELP," and it
ignores all the other keys.
For key-2 through key-n,
a
descriptor address of O, or a length of O, or a string address of
0 will terminate the list.
The key argument may
character strings:

contain

any

String

the

following

special

Meaning

Return all first-level help text in the library

KEY •••

Return all help text
associated
specified key and its suhkeys

Return all help text in the library

with

the

LBR$GET HELP returns all help text in the same format as the
output -returned by the DCL command HELP. If you do not want the
help text indented to the appropriate help level, you must supply
your own routine to change the format.
The routine that you specify to output each
contains an argument list of four longwords:

help
of

text

line

string

The first argument contains the address
descriptor for the line to be output.

The second argument contains the address of a longword
that points to one or more flag bits.
The flags
describe the contents of the text being passed.
The
possible flags are:
HLP$M NOHLPTXT

- The specified help text cannot be
found.
HLP$M KEYNAMLIN - The text contains the key names of the
printed text.
HLP$M OTHERINFO - The text is part of the information
provided on additional help available.

Note that if no flag bit is
passed.

set,

help

text

being

The third argument is the address specified in the data
argument in LBR$GET HELP (or the address of a 0 constant
if no argument has been supplied).

The fourth argument is the address
containing the current key level.

longword

The routine that you specify must return with success or failure
status.
A failure status (low bit = 0) terminates the current
call to LBR$GET HELP.

7-27

LIBRARIAN UTILITY

LBR$GET_I NDEX
7.4.7

LBR$GET INDEX - Return the Contents of an Index

LBR$GET INDEX calls a user-supplied routine to return the contents
an index optionally qualified by a key.

Format:

LBR$GET INDEX
[match-de sc] )

(library-index,

routine-name,

index-number,

library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine. The library must be open.

the

index-number
A pointer to a longword that contains the number of
index you want to return.

the

primary

routine-name
The name of a routine that you
element in the index.

supply

called

for

each

descriptor

that

identifies

selected

LBR$GET INDEX calls with two arguments the routine you
in the ~outine-name argument. The two arguments are:

specified

match-desc
The address of
entries.

string

Return Status

LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLIDXNUM
The specified index number is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ NULIDX
The specified

inde~

is empty.

Notes

Either address of a string descriptor for the entry (for
libraries with ASCII keys) or the address of a value (for
libraries with binary keys)

7-28

LIBRARIAN UTILITY

Address of a 2-longword array containing the entry's RFA

If the routine returns a false value (low bit= 0), LBR$GET INDEX
stops searching the index.
Note that the string descriptor passed to your routine is valid
only for the duration of the supplied routine. If you need to
use the string descriptor in later processing, you must first
copy the string.
If you include the rnatch-desc argument, LBR$GET INDEX supplies
only entries that match the specified string. The string can
contain embedded asterisks (*) and percent signs (%)
that serve
as wild card characters in the string description. If you do not
supply the match-desc argument, LBR$GET INDEX uses an asterisk
and matches all entries. The match-desc argument is supported
only in libraries with ASCII keys.
The routine that you specify in routine-name cannot contain calls
to either the LBR$DELETE or LBR$INSERT KEY routine.

7-29

LIBRARIAN UTILITY

LBR$GET_RECORD
LBR$GET RECORD - Read a Text Record

7.4.8

The LBR$GET RECORD routine returns the
with a key.

text

record

associated

Format

LBR$GET RECORD {library-index, inbufdes [, outbufdes])
library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine.
The library must he open
LBR$LOOKUP KEY routine must have b.een called.

by the
and the

inbufdes
A pointer to a string descriptor for the user-supplied buffer.
outbufdes
A pointer to a string descriptor for the actual recard returned.
Return Status

LBR$ ILLCTL
The specified library index is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ LKPNOTDON
The requested key lookup has not been done.
RMS$ EOF
An attempt has been made to read past the logical end of text.
Notes

Before calling LBR$GET RECORD, you must first find the key by
calling
LBR$LOOKUP KEY
or
LBR$FIND.
When
you
call
LBR$GET RECORD, the Librarian fills the input buffer
(described
by inbufdes) with the text record.
If you have optionally
specified the output buffer string descriptor
(outbufdes), the
Librarian fills it with the actual length an<l address of the
data.

7-30

LIBRARIAN UTILITY

LBR$1Nl_CONTROL
LBR$INI_CONTROL - Initialize a Library Index

7.4.9

The LBR$INI CONTROL routine initializes a library index for use by all
other Librarian routines. You must call this routine before calling
any other Librarian routine.

Format
LBR$INI CONTROL (library-index, func,

[type, namblk])

library-index
A pointer to a longword that
library.

will

receive

the

index

for

the

f unc
The address of a longword that contains the library function to
be performed. Valid functions are LBR$C_CREATE, LBR$C_READ, and
LBR$C UPDATE.
type
The address of a longword that contains the library type. If you
specify a library type, LBR$0PEN will check for the correct
library type.
namblk
The address of a VAX-11 Record Management Services
(VAX-11 RMS)
NAM block.
If the NAM block has a file identification in it
because it was used before, the Librarian will use the VAX-11 RMS
open-by-NAM block option.
The Librarian will fill in the
information in the NAM block so that it can be used at a later
time to open the library. This argument is optional and should
be used if the library will be opened many times during a single
run of the program. For a detailed description of VAX-11 RMS NAM
blocks, see the VAX-11 Record Management Services Reference
Man u a 1 •
----·--·--------·--------------·-------·--------------

Return Status
LBR$ NORMAL
The library index was initialized successfully.
LBR$ ILLFUNC
The function requested is not valid.
LBR$ ILLTYP
The specified library type is not valid.
LBR$ INVNAM
The specified VAX-11 RMS NAM block is not valid.

7-31

LIBRARIAN UTILITY
LBR$ TOOMNYLIB
An attempt was made to allocate more than lo control indexes;
is the maximum allowed.

Notes:
After you initialize the library index, you must open the
library, or create a new one using the LBR$OPEN routine. You can
then call other Librarian routines that you need. Once you have
completed working with a library, close it with the LBR$CLOSE
routine.
LBR$INI CONTROL initializes a library by filling the longword
referenced by the library-index argument with the index of the
library. Upon completion of the call, the index can be used to
refer to the current library in all future routine calls.
Therefore, your program must not alter this value.

7-32

LIBRARIAN UTILITY

LBR$1NSERT_KEY
7.4.10

LBR$INSERT_KEY - Insert a New Key

The LBR$INSERT KEY routine inserts a new key in
index.
-

the

current

library

Format
LBR$INSERT KEY (library-index, key-name, txtrfa)
library-index
A pointer to a longword that contains the lihrary index returned
by the LBR$INI CONTROL routine. The lihrary must be open.
key-name
A longword that contains one of the following:
1.

The address of the value
binary keys)

the

key

(for

lihraries

with

The address of a string descriptor for the key (for libraries
with ASCII keys)

txtrf a
A pointer to a 2-longword array that contains the RFA of the
associated text. You must use the RFA returned by the first call
to the LBR$PUT RECORD routine.
Return Status
LBR$ IDXFUL
The specified index is full.
LBR$ ILLCTL
The specified library index is not valid.
LBR$ INVRFA
The specified RFA does not point to valid text.
LBR$ KEYINDEX
The index already contains the specified key.
LBR$ LIBNOTOPN
The specified lihrary is not open.
LBR$ UPDURTRAV
The specified index update is not valid as an embedded routine.
Notes
You cannot call LBR$INSERT KEY within the user-supplied routine
specified in either the LBR$SEARCH or LBRSGET INDEX routines.

7_·:n

LIBRARIAN UTILITY

LBR$LOOKUP__ KEY
7.4.11

LBR$LOOKUP_KEY - Lookup a Library Key

The LBR$LOOKUP KEY routine looks up a key in the library's
index and prepares to read the text associated with the key.

current

Format
LBR$LOOKUP KEY (library-index, key-name, txtrfa}
library-index
A pointer to a longword that contains the index returned
LBR$INI_CONTROL routine. The library must be open.

the

libraries

with

key-name
A longword that contains one of the following:
1.

The address of the value
binary keys)

the

key

(for

The address of a string descriptor for the key (for libraries
with ASCII keys)

txtrfa
A pointer to a 2-longword array that receives the RFA of the text
you want to read.

Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ KEYNOTFND
The specified key was not found.
LBR$ LIBNOTOPN
The specified library is not open.

Notes
If LBR$LOOKUP KEY finds the specified key,
it
initializes
internal tablei so that you can read the associated text.
The Librarian returns the RFA (consisting of the VBN and the byte
offset)
to the 2-longword array pointed to by txtrfa. Note that
the array contains an RFA of only 48 bits.

7-34

LIBRARIAN UTILITY

LBR$0PEN
7.4.12

LBR$0PEN - Open a Library

The LBR$0PEN routine opens an existing library or creates a new one.
This routine must be called after you call LBR$INI CONTROL and before
you call any other Librarian routine.
Format

LBR$0PEN (library-index [,fns, create-options, dns,
rnslen])

rlfna,

rns,

returned

library-index
A pointer to a longword
LBR$ IN I CONTROL.

that

contains

the

index

f ns

The address of a string descriptor for the file name strinq.
This argument must be included unless the VAX-11 RMS NAM block
address was previously supplied in the LBR$INI CONTROL routine
and it contained a file identification. Otherwise, an error
(LBR$_NOFILNAM) will result.
create-options
If you are creating a library with LBR$C CREATE, you must include
the create-options argument. The create-options argument is an
array of 20 longwords that describes the characteristics of the
library you want to create. Table 7-4 shows the entries that the
array must contain.
dns
The address of a string descriptor
string.

for

the

default

file

name

rlfna
The address of a VAX-11 RMS NAM block for the related file name.
If you do not specify rlfna, no related file name processing
occurs. See the VAX-11 Record . Management Services Reference
M a~~l f 0 r de ta i 1 s
s s'fng-··rrne's-.--------~

-0ri·-p-roC'e

eTatea-n-re--na

rns
The address of a string descriptor for the resultant file name
string.
If an error occurs during an attempt to open the
library, the expanded name string will he returned.
rnslen
A pointer to a longword that receives the length of the resultant
file name string
(or the length of the expanded name string if
there was an error in opening the library1.

7-35

LIBRARIAN UTILITY
Table 7-4
Create-Options Array

--------·---·----·---·-· ·-··--------·-·-----· .. ·-------Offset in
Longwords

Symbolic Name

---·-----+----··-------- . ·-------- --·--------- ____. _________ _

-~-----·-··--·--,.-----·-------

CRE$L TYPE

Contents
_____________. _________________

Library type

LBR $C TYP UNK ( 0)

Unknown/unspecified

LBR_$C_TYP_OBJ ( 1)

Object and/or shareable
image

LBR $C TYP MLB (2)

Macro

LBR $C TYP HLP (3)

Help

LBR $C TYP TXT (4)

Text

(5-127)

Reserved to DIGITAL

- -

LBR $C TYP USR (128-255)

User-defined

CRE$L KEYLEN

0
non-0

32-bit unsigned keys
Maximum length of ASCII
keys

CRE$L ALLOC

non-0

Initial library file
allocation

CRE$L IDXMAX

Number of primary indexes
(maximum of 8)

CRE$L UHDMAX

Number of additional bytes
to reserve in module
header

CRE$L ENTALL

Number of index entries to
pre-allocate

6-20

Reserved to DIGITAL

Return Status
LBR$ OLDLIBRARY
The specified Version 1.0 library has been opened.
LBR$ ILLCREOPT
The requested create options are not valid or not supplied.
LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLFMT
The specified library format is not valid.

LIBRARIAN UTILITY
LBR$ ILLFUNC
The specified library function is not valid.
LBR$ INSVIRMEM
No virtual memory is available for the specified function.
LBR$ LIBOPN
The specified library is already open.
LBR$ NOFILNAM
The fns argument was not supplied, or the VAX-11
was not filled in.

RMS

NAM

block

LBR$ OLDMISMCH
The library function requested conflicts
type specified.

with

the

old

library

with

the

library

LBR$ TYPMISMCH
The library
specified.

type

requested

conflicts

type

Notes

When the library is successfully opened, the Librarian reads the
library header into memory, sets the default index to 1, and
updates the library index.
If the library cannot be opened because it is already open for a
write operation, LBR$0PEN will retry the open operation every one
second for a maximum of 30 seconds before returning the VAX-11
RMS error, RMS$_FLK, to the caller.

7-37

LIBRARIAN UTILITY

LBR$PUT_END
7.4.13

LBR$PUT_END - Terminate a Text Sequence Written to a Library

The LBR$PUT END routine terminates a
library by the LBR$PUT_RECORD routine.

text

sequence

written

Format
LBR$PUT END (library-index)
library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine. The library must be open.

the

Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ LIBNOTOPN
The specified library is not open.

Notes
Call LBR$PUT END after you have written text records to the
library with the LBR$PUT RECORD routine. LBR$PUT END terminates
a text sequence by attachTng a three-byte logical end-of-file
record (hexadecimal 77,00,77) to the text.

7-38

LIBRARIAN UTILITY

LBR$PUT_RECORD
7.4.14

LBR$PUT_RECORD - Write a Text Record

The LBR$PUT RECORD routine writes a text record beginning at the
free location in the library.

Format

LBR$PUT RECORD (library-index, bufdes, txtrfa)
library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine. The library must be open.

the

buffer

buf des
A pointer to a string descriptor
receive the record output.

that

contains

the

txtrfa
A pointer to a 2-longword array that
newly created module header.

receives

the

RFA

the

Return Status

LBR$ ILLCTL
The specified library index is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
Notes

If this is the first call to LBR$PUT RECORD, the Librarian first
writes a module header and returns its RFA to the 2-longword
array pointed to by txtrfa.
LBR$PUT RECORD then writes the
supplied text record to the library.

LIBRARIAN UTILITY

LBR$REPLACE __ KEY
7. 4 .15

LBR$REPLACE __KEY -

Change Text Pointer or Insert New Key

The LBR$REPLACE KEY routine inserts a new key in an index by changing
the pointer associated with an existing key, or by inserting a new
key.
Format

LBR$REPLACE KEY (library-index, key-name, oldrfa, newrfa)
library-index
A pointer to a longword that contains the index returned
LBR$INI_CONTROL routine. The library must be open.

the

key-name
A longword that contains one of the following:
1.

The address of the key's value
keys)

(for

libraries

with

binary

The address of a string descriptor for the key (for libraries
with ASCII keys)

oldrfa
A pointer to a 2-longword array that contains the RFA of the
text.

old

newrf a
A pointer to a 2-longword array that contains the RFA of the
text.

new

Return Status

LBR$ ILLCTL
The specified library index is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
LBR$ INVRFA
The specified RFA is not valid.
Notes

If LBR$REPLACE KEY does not find the key in the current index, it
calls the LBR$TNSERT KEY routine to insert the key.

LIBRARIAN UTILITY
If LBR$REPLACE KEY finds
following:
-

the

specified

key,

performs

the

Decreases by 1 the reference count for the old text
to by oldrfa)

(pointed

Increases by 1 the reference count for the new text
to by newrfa)

(pointed

Modifies the entry for the key so that it now points
new text

7-41

the

LIBRARIAN UTILITY

LBR$SEARCH
7.4.16

LBR$SEARCH - Search an Index

The LBR$SEARCH routine finds index keys that point
text.

the

specified

Format
LBR$SEARCH (library-index, index-number, rfa-to-find, routine-name)
library-index
A pointer to a longword that contains the index returned
LBR$INI CONTROL routine. The library must be open.

the

index-number
A pointer to a longword that contains the number of
index you want to search.

the

primary

rf a-to-find
A pointer to a 2-longword array that contains the RFA of the
you want to find.

key

routine-name
The name of a routine that you
containing the matching RFA.

supply

call

for

each

key

Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLIDXNUM
The specified index number is not valid.
LBR$ KEYNOTFND
The Librarian did not find any keys with the specified RFA.
LBR$ LIBNOTOPN
The specified library is not open.
Notes
Use LBR$SEARCH to find index keys that point to some specified
text.
For example, you can call LBR$SEARCH to find all the
global symbols associated with an object module in an object
library.
If LBR$SEARCH finds an index key,
it calls a user-supplied
routine with two arguments. The two arguments are:
1.

Either the address of a string descriptor for an ASCII key or
the address of the value of a binary k~y

Address of a 2-longword array that points to the RFA
associated text
7-42

the

LIBRARIAN UTILITY

If the specified routine returns a false value
then the index search terminates.

(low

bit

0),

Note that the key-name argument is valid only for the duration of
the call to the user-supplied routine. If you want to use the
key-name argument later, you must copy it.
The routine that you specify in routine-name cannot contain
calls to either the LBR$DELETE or LBR$INSERT KEY routine.

7-43

any

LIBRARIAN UTILITY

LBR$SET_INDEX
7.4.17

LBR$SET_INDEX - Set the Primary Index Number

The LBR$SET INDEX routine sets the index number to
processing o1 libraries that have more than one index.

use

during

Format
LBR$SET INDEX (library-index, index-number)
library-index
A pointer to a longword that contains the library index returned
by the LBRSINI_CONTROL routine. The library must be open.
index-number
A pointer to a longword that contains the number of the index you
want to set.
Return Status
LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLIDXNUM
The index number specified is not valid.
LBR$ LIBNOTOPN
The specified library is not open.
Notes
You call LBR$SET INDEX when working with libraries that contain
mo re than on E! - i n de x •
Mac r o , he 1 p , and text 1 i bra r i es cont a i n
only one index;
therefore, you
do
not
need
to
call
LBR$SET INDEX.
Object libraries contain two indexes. If you
want to-access the global symbol table, you must call the
LBR$SET INDEX routine to set the index number. User-developed
librariis can contain more than one index;
therefore, you may
need to call LBR$SET INDEX to set the index number.
Upon successful completion, LBR$SET INDEX sets the current index
to the requested index numher. -The Librarian numbers indexes
starting with l.

7-44

LIBRARIAN UTILITY

LBR$SET_MODULE
7.4.18

LBR$SET_MODULE - Read or Update a Module Header

The LBR$SET MODULE routine reads, and optionally updates, the
header associated with a given record's file address (RFA).

module

Format
LBR$SET MODULE (library-index, rfa,

[bufdesc,buflen,updatedescl)

library-index
The address of a longword that
returned by the LBR$ !NI CONTROL
open.

contains
routine.

the library index
The library must be

rf a
A pointer to the RFA associated with the module header.
The
Librarian returns the RFA as a result of either the first call to
the LBR$PUT RECORD routine, or a
previous
call
to
the
LBR$LOOKUP KEY routine.
For a description of record access by
RFA, see the VAX-11 Record Management Services Reference Manual.
bufdesc
A pointer to a string descriptor for the buffer that receives the
module header.
buf len
The address of a longword to contain the length of
module header.

the

returned

updatedesc
A pointer to a string descriptor of additional data that the
Librarian stores with the module header. If you include this
argument, the Librarian will update the module header with the
additional information.

Return Status
LBR$ HDRTRUNC
The buffer supplied to hold the module header was too small.
LBR$ ILLCTL
The specified library index is not valid.
LBR$ ILLOP
The updatedesc argument was supplied and the library was a
Version 1.0 library or the library was opened only for read
access.
LBR$ INSVIRMEM
No virtual memory is available for the specified function.

7-45

LIBRARIAN UTILITY
LBR$ INVRFA
The specified RFA does not point to a valid module header.
LBR$ LIBNOTOPN
The specified library is not open.
Notes

If you specify bufdesc, the Librarian will return the module
header into the buffer.
If you specify buflen, the Librarian
will also return the buffer's length. If you specify updatedesc,
the Librarian will update the header information.
You define the maximum length of the update information when you
create the library. The Librarian will zero-fill the information
if it is less than the maximum length, or truncate
the
information if it exceeds the maximum length.

7-4n

LIBRARIAN UTILITY
7.5

EXAMPLE OF LIBRARIAN ROUTINES

This section describes LBRDEMO, a VAX-11 FORTRAN program example that
illustrates the use of the Librarian routines. LBRDEMO contains calls
to the Librarian routines that perform the following operations:

• Name and initialize a text library
• Open or create a text library
• Replace or insert text modules
• Extract text modules
• List the help topics in the system help library
• Retrieve help text from the system help library
The sample program LBRDEMO is shown below. 'fhe circled numbers in the
program are keyed to the descriptions that follow •
• TITLE DEMOMAC
macros
$credef
$dscdef
$lbrdef
$lbrctltbl
$namdef

def
def
def
def
def

ne create options array offsets
ne string descriptor offsets
ne librarian parameters
ne library control table offsets
ne NAM block offset

set up FORTRAN COMMON block to allow FORTRAN main program tot»
access librarian data
.PSECT

lbrdata, PIC, OVR, REL, GBL, SHR, NOEXE, RD, WRT, LONG

.long
.long
.long
• long
• long
.long
• long

lbr$c read
lbr$c-create
lbr$c-update
lbr$c-typ txt
lbr$c-typ-hlp
rms$ .eof dsc$k_class_d

.long
.long
• long
.long
.long
• long

; offsets· into create options array:
; values are divided by 4 to convert byte
; offsets into longword offsets
cre$1 type/4
type of library
cre$1-keylen/4
max key length
cre$1-alloc/4
initial library disk allocation
cre$1-idxmax/4
number of indices
cre$1-uhdmax/4
size of additional module header data
cre$l=entall/4
number of index entries to preallocate

.SBTTL

NAM INIT - initialize RMS NAM block

func read
func-create
func-update
type-text
type-help
rmseof
class_dynamic

initialize array to be an RMS NAM blockf,)
Calling sequence:
Call nam init (nam_array, result_desc)
Inputs:

7-47

LIBRARIAN UTILITY

nam_array

Address of array of S6 bytes to be initialized
as a NAM block

result desc

Address of string descriptor for resultant name
string.

Outputs:
the nam array is initialized as a NAM block, with the expanded
and resultant name strings pointing to the string described by
result_desc.
Routine value:
Always success

.PSECT

$code$, PIC, REL, SHR, EXE, RD, NOWRT

.ENTRY nam_init,AmR2, R3, R4, RS, Rh)
movl
4(AP), Rh
moves
#0, (SP), #0, #namSc_bln, (rh)
movl
8(AP), RO
$NAM_STORE NAM = R6,BLN
#nam$c bln,#nam$c-bid ,BID
RSS
dscSw lenqth(RO) ,dsc$w-length(RO) ,ESS
RSA
tadscSa pointer (ROI,ESA
@dscSa=pointer (RO),movl
#1, rO
ret
.SBTTL

Get address of NAM block
Zero the NAM block
Get address of resultant name string descriptor
Initialize the NAM fields
block length
block id
resultant name string size
expanded name string size
resultant name string address
expanded name string address
return with success

retrieve rmsstv

Retrieve the RMS STV returned from the last Librarian operation@)
Calling sequence:
istv

retrieve rmsstv (0)

Inputs:
NONE
Implicit inputs:
The library must be open.
Outputs:
NONE
Routine value:
The RMS STV from the last libr.arian operation

.ENTRY

retrieve_rmsstv,AM<>

movl

g!Lbr$gl rmsstv,rO

ret

;get the STV value
;and return with that as the function value

7-48

LIBRARIAN UTILITY
.SBTTL

set locate mode

;++
Set the current library to read in locate mode
Calling sequence:
call

set locate mode

Inputs:
NONE
Implicit inputs:
An operation must have been done n the desired library
(i.e. LBR$0PEN) before calling th s routine.
Outputs:
NONE
;--

.ENTRY

set_locate_mode,~M>

movl
g~lbr$gl control,rO
bisl2
#lb~$m l~cate,lbr$l_usrflg(r0)
movl l,RO
ret

;get address of control block
;set locate mode
;return success

.END

c
c
c

Demo program for library access procedures
PROGRAM LBRDEMO

c
c
c

IMPLICIT INTEGER (A-Z)
EXTERNAL list module
The common block is declared in a MACRO source module to gain
access to system definitions not available to FORTRAN.
COMMON /lbrdata/ func read, func create, func update,
1 type text, type help, rmseof, class dynamic~ create type,
2 create keylen, create alloc, create-idxmax, create uhdmax,t»
3 create-entall
CHARACTER*l28 library name, library rsn, module name
CHARACTER*l28 input lTne
CHARACTER*32 keyl, key2, key3
BYTE help_namblk

(56), string_desc_bytes (8), dyn_desc_bytes

DIMENSION create options (0:49), old module rfa
1 dyn_string (2)~ string_desc (2)
-

(8)

(2), module rfa

(2),

c
c

The equivalence of the STRING DESC array with the STRING DESC BYTES
array is done to access the string descriptor class field.
-

7-49

LIBRARIAN UTILITY
EQUIVALENCE (string desc, string desc bytes),
1 (dyn_string, dyn_aesc_bytes) library open = .false.
have_name = .false.

c
C

Initialize NAM block for use with HELP library

CALL nam_init (help_namblk, library_rsn)"

c
C

Allocate a

c
c
c

dynami~

string and initialize string descriptors

dyn string (1) = O
dyn-string (2) = 0
dyn-desc bytes (4) = class dynamic
strTng desc (1) = o
string-desc (2) = 0
string-desc bytes (4) = class_dynamic
status-=
1 lib$sgetl dd (2048, string_desc)
IF (status)-GOTO 100
CALL lib$signal (%VAL (status))
STOP

!allocate 2048 byte string

Main dispatch loop -- Get action and dispatchG»
100

200

c
c

TYPE 9000
READ (5, *, END=300) action
GOTO (1000, 2000, 3000, 4000, 5000, 6000, 7000), action+ 1
GOTO 100
CALL lib$signal (%VAL (status))
GOTO 100
Close library and exit

300

c
c

IF (library open) THEN
status = lbr$close (text index)
IF (.NOT. status) GOTO 10
END IF
STOP
Give some help

c
1000

TYPE 9020
GOTO 100
Name new library

c
c
c

If there is a library open, it will be closed.
is accepted.

2000

2050

c
c
c

IF (library open) THEN.
status = lbr$close (text index)
IF (.NOT. status) CALL lfb$signal (%VAL (status))
library open = .false.
END IF TYPE 9040
READ (5, 9110, END=lOO) name length, library name
library name =library name (l:name_length)/7'.TLB'
have name = .true.
GOT0-100
Open or Create a TEXT libraryC9

3000

The new library name

IF (.NOT. have __name) GOTO 8000

7-50

LIBRARIAN UTILITY

3010
3020
3050

c
c
c

TYPE 9540
READ (5, *, END = 100) create flag
IF (create flag) THEN
TYPE 9060
READ ( 5, *, END=lOO) max key length f)
function = func create create options (create type} = type text
create-options (create-keylen) = max key length
create-options (create-alloc) = 100 create-options (create-idxmax)
1
create-options (create-uhdmax)
0
create-options (create-entall) = 100
ELSE function = func update
END IF
Initialize librarian for this library
status = lbr$ini control (text index, function, type_text)
IF (.NOT. status) GOTO 200

Open or create the library

c
3070

status = lbr$open (text index, library_name, create_options).,
IF (.NOT. status) GOTO 200
library_open = .TRUE.
Note:

if using locate mode for record transfer, call set locate mode here.

GOTO 100

c
c

Insert or replace a module in the text library

c
4000
4020

4100
4120

c
c
c

IF (.NOT. library_open) GOTO 8020«9
TYPE 9080
READ (5, 9110, END=lOO) name length, module name
replacing = lbr$lookup key (text index,
1 module name (l:name length), old module rfa)
TYPE 9100
READ (5, 9110, END = 4200) line length, input line
status = lbr$put record (text index,
1 input line (l:Tine length),-module rfa)
IF (.NOT. status) CALL lib$signal (%VAL (status))
GOTO 4100
Module text has been inserted into the library. Terminate the module

4200

c
c
c

status = lbr$put end (text index)
IF (.NOT. status) CALL libSsignal (%VAL (status))f)
status = lbr$replace key (text index,
1 module name (l:name length),-old module rfa, module rfa)
IF (.NOT:- status) CALL lib$sigal (%VAL (status))
status = .TRUE.
IF (replacing) status = lbr$delete data (text index,
1 old module rfa)
IF (.NOT status) GOTO 200
GOTO 100
Extract module from library and type on terminal

5000

5100

IF (.NOT. library open) GOTO 8020«D
TYPE 9400
READ (5, 9050, END = 100) module name
status = lbr$lookup key (text index, module_name, module_rfa)
IF (.NOT. status) GOTO 200
status = lbr$get_record (text index, string_desc, dyn_string)

7-51

LIBRARIAN UTILITY
IF ((.NOT. status) .AND. status .NE. rmseof)
1 CALL lib$signal (%VAL (status))
IF (status .EQ. rmseof) GOTO 100
CALL lib$put output (dyn strin)
GOTO 5100
-

c
c

List contents of index of SYS$HELP:HELPLIB.HLB
6000

c
c

status = lbr$ini control (help index, func_read, type_help)48
IF (.NOT. status) GOTO 200
status= lbr$open (help index, %descr ('SYS$HELP:HELPLIB.HLB'))
IF (.NOT. status) GOTO 200
status = lbr$get index (help index, 1, list module)
IF (.NOT. status) CALL lib$sTgnal (%VAL (status))
status = lbr$close (help index)
IF (.NOT. status) GOTO 2~0
GOTO 100
Lookup help text in SYS$HELP:HELPLIB.HLB and display on the terminal

7000

7020

7040

c
c

TYPE 9200
READ (5, 9110, END= 100) KEYlLEN, KEYlf>
IF (KEYlLEN .EQ. 0) GOTO 7020
TYPE 9220
READ (5, 9110, END = 100) KEY2LEN, KEY2
IF (KEY2LEN .EQ. 0) GOTO 7020
TYPE 9240
READ (5, 9110, END = 100) KEY3LEN, KEY3
status =
1 lbr$ini control (help index, func_read, type_help, help_namblk)
IF (status) GOTO 7040 GOTO 200
status= lbr$open (help index, %descr ('sys$help:helplib.hlb'))
IF (.NOT. status) GOTO 200
status = lbr$get help (help index, 80, , ,
1 keyl (l:keyllen), key2 c1:key2len), key3 (l:key3len))
IF (.NOT. status) CALL lib$signal (%VAL (status))
status = lbr$close (help index)
IF (.NOT. status) CALL 1Tb$signal (%VAL (status))
GOTO 100
Error routines

c
c

No library name given

c
8000

TYPE 9500
GOTO 100

c
c

No library open
8020

c
c
c

TYPE 9520
GOTO 100
Format statements

9000
9020

9040
9050

FORMAT (' Action (0 for help): ',$)
FORMAT (' Commands:',/' 1 - Name library',/,
l' 2 - Open or Create a text library',/,
2' 3 - Replace/insert module',/,
4' 4 - Extract module',/,
3' 5 - List directory of SYS$HELP:HELPLIB.HLB',/,
5' 6 - Lookup help text in SYS$HELP:HELPLIB.HLB')
FORMAT (' New library name: ',$)
FORMAT (A)

7-52

LIBRARIAN UTILITY
9060
9080
9100
9110
9200
9220
9240
9400
9500
9520
9540

FORMAT (' Maximum key length: ',$)
FORMAT ('Module name: ',$)
FORMAT (' Enter text. Terminate with a Control-Z: ')
FORMAT (Q, A)
FORMAT(' Enter KEYl: ',$)
FORMAT (' Enter KEY2: ',$)
FORMAT (' Enter KEY3: ',$)
FORMAT (' Module to extract: ',$)
FORMAT (' No library name given')
FORMAT (' No library open')
FORMAT
1 (' Open existing library (0) or create new library (1): ',$)
END
INTEGER FUNCTION list module (keyname, keyrfa)
IMPLICIT INTEGER (A-Z)
CHARACTER *(*) keyname
TYPE *,keyname
list module = .true.
RETURN
END

t»

LBRDEMO calls 11 of the Librarian routines.
To call these
routines, LBRDEMO uses a FORTRAN COMMON block to access symbols
that are unavailable to FORTRAN.
The symbols specify the
functions available for initializing a library and the options
available for creating a text library.
(See fj)
The COMMON block is initialized in the VAX-11 MACRO source module
DEMOMAC;
the symbols are accessed by linking the two programs
together. The Librarian routines are accessed by specifying an
options file that requests the linker to include the Librarian
shareable image. To assemble and link the two programs, you can
create a command procedure that contains the following commands:
$ FORTRAN /LIST LBRDEMO

$ MACRO /LIST DEMOMAC
$ LINK /EXE=DEMO /MAP=DEMO /FULL LBRDEMO, DEMOMAC, SYS$INPUT/OPTIONS
!
! OPTIONS INPUT
!

!Include librarian

SYS$LIBRARY:LBRSHR/SHARE

This command procedure produces the executable image DEMO.EXE.
DEMOMAC contains a subroutine, NAM INIT, that initializes an
array to be used as a VAX-11 RMS NAM block when retrieving help
messages from the system help library.
(See ~ for information
on how to use the NAM block option;
for an example of opening a
library without the NAM block option, see CD>
The subroutine RETRIEVE RMSSTV returns the VAX-11 RMS STV value
from the last library operation (see the VAX-11 Record Management
Services
Reference
Manual).
LBRDEMO
does
not
call
RETRIEVE RMSSTV. However, if it were to be includerl, it would be
declaredas
INTEGER*4,
and
the
call
would
be
ISTV=RETRIEVE_RMSSTV(O).

7-53

LIBRARIAN UTILITY
DEMOMAC also contains a subroutine, SET LOCATE MODE, that you can
use to specify the VAX-11 RMS locate mode of record transfer.
LBRDEMO does not call this subroutine.
However, if
this
subroutine were to be included, it would be called after the
LBR$0PEN routine (see the program comment following line 3070}.
For more information on using locate mode, see the VAX-11 Record
Ma~age~~~~-~.l'.'~~.?es Refere_~E..~--!i~nual.

The main part of LBRDEMO, beginning at line 100, asks what
library operation you want to perform. By typing "0" (for help},
you request an operation menu that lists the program's six
library functions:
1.

Name library

Open or create a text library

Replace/insert module

Extract module

List directory of SYS$HELP:HELPLIB.HLB

Lookup help text in SYS$HELP:HELPLIR.HLB

Each operation on the menu references at least one of the
Librarian routines.
After the Librarian performs the requested
operation, it returns you to this menu. At this point, you can
either perform another operation by typing the appropriate
number, or you can terminate the program by typing <CTRL/Z>.
Typing <CTRL/Z> performs the following functions:
a. Calls the LBR$CLOSE routine
previously opened text library

(line

300}

b. Executes the STOP instruction to terminate the program
The first operation on the menu allows you to name the library
you want to access.
If a text library has been previously
opened, LBRDEMO calls the LBR$CLOSE routine (line 2000} to close
the library. LBRDEMO then prompts you for the library name (line
2050}, appends the text library file type TLR to the name you
specify, and assigns the string to the symbol LIBRARY NAME. The
variable HAVE NAME is set to true, and LBRDEMO returns to the
operations menu.

The second operation on the menu opens or creates a library using
the library name you specify in 1. LBRDEMO asks whether you are
opening an existing library or creating a new one
(line 3010}.
If you want to create a library, the variable FUNCTION will take
the value stored in FUNC CREATE;
if you are opening a library,
the variable FUNCTION wTll take the value stored in FUNC UPDATE.
In either case, LBRDEMO calls the LBR$INI CONTROL routine to
initialize the text library index.
The three arguments to the LBR$INI CONTROL routine specify that
the library index is named TEXT INBEX, the library function to he
performed is contained in the viriable FUNCTION, ~nd the library
type is TEXT.
The variable FUNCTION is accessed through the
COMMON block. Note that the call to LBR$INI CONTROL initializes
a library index without using the .. NAM block option. Inste?d, the
call to LBR$0PEN
(line 3070} opens a library
using
the
specifications contained in the LIBRARY_NAME argument.
Note also that the call to the LBR$INI CONTROL routine ~oes not
enable you to access a library;
it merely initializes a library
7-54

LIBRARIAN UTILITY
index to which the other Librarian routines can refer.
The
subsequent call to LBRSOPEN opens the library for access. If you
try to perform a library operation before initializing a library
index and opening a library file, LBRDEMO will print "No library
name given" (line 4000) and will return you to the operations
menu.

If you are opening an existing library, the LBR$0PEN routine will
open for access the library specified in LIBRARY NAME. If you
are creating a new library, the LBR$0PEN routine will use the
information in the CREATE OPTIONS array (line 3070) to create the
library. The symbols in the create options array are accessed
through the COMMON block. You must supply the maximum key length
of the library (line 3050); the rest of the create options are
predefined by the program.

Ci)

After you have initialized and opened (or created) a library, you
can insert or replace a text module (the third operation on the
menu). The method by which the Librarian inserts a module
depends on whether the key to the module already exists in the
library index.
In the sequence beginning at line 4000, the variable REPLACING is
associated with the status of the LBR$LOOKUP KEY routine. This
variable is later used to test whether the module being inserted
already exists in the library (seeC!)).
LBRDEMO creates the new text module by promptino you to specify
the module name and enter the text
(lines 4020 and 4100,
respectively). As you enter the text records, LBRDEMO calls the
LBR$PUT RECORD routine to write the text records to the module
you specified. Note that the first call to LBR$PUT RECORD fills
1n the MODULE RFA argument with the address of tne module. In
this way, the fTrst call to LBR$PUT RECORD provides a mechanism
for
accessing the new module In subsequent calls to the
Librarian. After the module is written, LBRDEMO calls the
LBR$PUT END
routine
(line 4200)
to terminate the writing
sequence.
LBRDEMO inserts the module into
the
library
using
the
LBR$REPLACE KEY routine.
If the key you are inserting does not
already exist in the module name table, LBR$REPLACE KEY will
insert the key into the index. The new key will poTnt to the
inserted module.
If the key you are inserting already exists, LBRSREPLACE KEY must
perform a replace operation.
In a replace operation, the
Librarian changes the index key from the address specified in
OLD MODULE RFA to the address specified by MODULE RFA. The key
then points to the new module, but the old module -still exists
physically
in the library.
Therefore, after the call to
LBR$REPLACE_KEY, LBRDEMO must delete the old module.
If the value of REPLACING is true, the call to LBR$LOOKUP KEY
will find a module with the same name and return its address in
the location spec}fied by the argument OLD MODULE RFA.
LBRDEMO
then calls the LBR$DELETE DATA routine -(line 4300) to delete
physically the old module from the library.

7-55

LIBRARIAN UTILITY

«!)

The fourth operation on the menu extracts a module from the
currently open library and displays it on the terminal. LBRDEMO
first prompts you for the module you want to extract, then calls
LBR$LOOKUP KEY.
The call to LBR$LOOKUP KEY searches TEXT INDEX
for the ke~ specified by the MODULE NAME irqument. If the fey is
found, LBR$LOOKUP KEY will fill -in the array specified by
MODULE RFA with thi record's file address (RFA) of the module you
want to read.
Once the module is found,
LBRDEMO calls the LBR$GET RECORD
routine to retrieve the text records. The first arqument-to the
routine, STRING DESC, specifies the input buffer that receives
the text record7 The second argument, DYN STRING, is an optional
argument that receives the actual length a~d address of the text
record read.
The program sequence beginning at line 5100 constitutes a read
loop. As LBR$GET RECORD returns each text record, LBRDEMO checks
for the end of file (RMSEOF). If it is not at the end of the
file,
LBRDEMO
will
call
the Run-Time Library procedure
LIB$PUT OUTPUT to output the text record described by the string
descrip£or DYN_~TRING.
After LBR$GET RECORD retrieves all the text records
module, LBRDEMO returns you to the operations menu.

the

The fifth operation on the menu, beginning at line nOOO, lists
the contents of the system help library, SYS$HELP:HELPLIB.HLB.
The LBR$INI CONTROL routine initializes the library index, called
HELP INDEX.- The second argument, FUNC READ, indicates that the
library is initialized for reading. Therefore, any attempt to
modify the library in subsequent calls will result in an error.
The symbol FUNC_READ is accessed through the COMMON block.
The call to LBR$0PEN opens system help library for read access.
The
second
argument
to
the
routine contains the file
specification for the library.
The call to LBR$GET INDEX retrieves the contents of the library
index specified by the first argument, HELP INDEX, which was
returned by the preceding call to LBR$INI CONTROL.
The second
argument tells the routine to qet index number 1. The third
argument, LIST MODULE, is the name of the user-supplied routine
(at the end -of the program) that LBR$GET INDEX calls to return
the list of index entries.
The final call in this sequence, LBR$CLOSE, closes the index
returned by the LBR$INI CONTROL routine and deallocates all of
the space for processing the library.
The sixth and last operation on the menu retrieves help text from
the system help library, SYS$HELP:HELPLIB.HLB. After prompting
you f~r the help keys
(line
7000),
LBRDEMO
calls
the
LBR$INI CONTROL routine to initialize an index for the help
library7
Note that this call to LBR$INI CONTROL uses the VAX-11 RMS NAM
block option to initialize a~d open the help library. When you
first select operation 6, the Librarian fills in the NAM block,
HELP NAMBLK, with the file identification of the system help
library. Thereafter, when you select operation n, the Librarian
uses the HELP NAMBLK argument containing the file identification
to reopen the library. Using the NAM block method for opening a
library
is much faster because no directory accesses are
required. Although the NAM block argument is optional in the
7-Sn

LIBRARIAN UTILITY
LBR$INI CONTROL
routine,
you
should
repeatedly open and close a library.

use

whenever

you

The LBR$0PEN routine opens the system help library in preparation
for the call to LBR$GET HELP. LBR$GET HELP retrieves the help
text associated with the key path specified in the argument list.
The number 80 before the list of help keys optionally requests
that the text be displayed in 80-character lines.
After printing the help text, LBRDEMO calls the LBR$CLOSE routine
to close the library.
You then return to the operations menu
where you can terminate LBRDEMO by typing <CTRL/Z> {see 4).

7.6

MESSAGES FOR LIBRARY COMMAND AND LIBRARIAN ROUTINES

This section lists messages issued by the LIBRARY command and
Librarian routines, and provides an explanation of each message and
suggestions for user action in response to error and severe-error
messages.
The messages appear in decreasing order of severity.
Informational and success messages inform you that the Librarian has
performed the specified request. Warning messages indicate that the
command may have performed some, but not all of your request, and that
you need to verify command or program output. Error messages indicate
that the command or program output is incorrect, although the system
may attempt to continue execution. Severe-error messages tell you
that the error required the system to stop execution of the command or
program.

Messages For LIBRARY Command

7.6.1

This section lists the information, success,
severe-error messages for the LIBRARY command.

7.6.l.l

warning,

error,

and

Informational Messages

CNVRTING, library file-spec is a copy of old library file-spec
Explanation: Any modification to
a
Version
1.0
automatically converts it to the new library format.

7.6.l.2

Success Messages

NORMAL, success
INSERTED, module module-name inserted in library file-spec
DELETED, module module-name deleted from library file-spec
REPLACED, module module-name replaced in library f:ile-spec
REMOVED, symbol symbol-name removed from library file-spec
EXTRACTED, module module-name extracted from library file-spec

7-57

library

LIBRARIAN UTILITY
7.6.1.3

Warning Messages

DIFTYP,

expected library file-spec to be library type

Explanation: The referenced library is actually of
type from that specified in the command string.
User Action: No action is necessary.
on the actual library type.

Processing

different

continu~s

based

CLOSEIN, error closing input file
Explanation:

This is an error detected by VAX-11 RMS.

User Action: Reenter the command line after
action based on the accompanying message.

taking

corrective

CLOSEOUT, error closing output file
Explanation:

This is an error detected by VAX-11 RMS.

User Action: Reenter the command line after
action based on the accompanying message.

taking

corrective

COMCOD, compilation error in module module-name file lihrary file-spec
Explanation: The object module you are inserting contains
compilation error, a warning, or an invalid compilation code.
User Action:
string.

Recompile the module before reentering the

command

ENDWRNGMAC, .ENDM doE~s not end macro macro-name in library file-spec
Explanation: The macro name following the .ENDM
not match the name of the macro it should end.
User Action:

statement

does

Reformat the macro source file.

EXTRAENDM, extraneous .ENDM in library file-spec
Explanation: The specified library contains
that does not terminate any macro.
User Action:

.ENDM

statement

Reformat the macro source file.

NOHLPTXT, no level 1 help text found in input file-spec
Explanation: The specified input
properly formatted help file.

contain

User Action: Reformat the help input file before reentering
command line.

the

7-58

file

does

not

LIBRARIAN UTILITY
NOMACFOUND, no .MACRO found in input file-spec

Explanation: The specified
properly formatted macro.
User Action:
NOMTCHENDM, no
file-spec

input

file

not

contain

name

lihrary

contain

matching

macro-name

library

matching

.ENDM

for

macro

macro
not

Reformat the macro source file.

NOMTCHENDR, number missing
file-spec

.ENDR

for

macro

Explanation: The Librarian found a matching
before finding the required .ENDR statement.
User Action:

Reformat the macro source file.

Explanation: The specified macro does
.ENDM statement.
User Action:

does

.ENDM

statement

Reformat the macro source file.

NOMTCHFOU, no matches found for module-name

Explanation: The module specified with the
not in the module name table.
User Action:

/ONLY

qualifier

Make sure that the specified module exists.

TOOMNYENDR, too many .ENDR in macro macro-name in library file-spec

Explanation:
statement.

The specified macro contains

User Action:

Reformat the macro source file.

7.~.1.4

nonmatching

.ENDR

Error Messages

DELKEYERR, error deleting module-name from library file-spec

Explanation: The module you want to delete does not appear in
the module name table; or a VAX-11 RMS error occurred; or there
was not enough virtual memory.
User Action:

Correct the problem and reenter the command line.

DELDATERR, error deleting data from library file-spec

Explanation: An error occurred during an attempt to aelete the
text;
or a VAX-11 RMS error occurred; or there was not P.nouqh
virtual memory.
User Action: Compress
specified text.

the

old

7-59

library

before

deletinq

the

LIBRARIAN UTILITY
DUPGLOBAL, global symbol symbol name from
already in library library file spec.

file

library

file-spec

Explanation: An attempt was made to insert an object module
containing a global symbol that was already in the global symbol
table.
·
User Action: Replace the module rather than insert it;
or
remove the global symbol from the library before inserting the
module.

DUPMOD, module module-name from
library file-spec

file

library

file-spec

Explanation: 'rhe module you are inserting
already exists in the module name table.
User Action: Change the name of
existing module with the new one.

the

mod~le,

into
or

already
the

library

replace

the

FAOFAIL, system service failure
Explanation:

This is an unexpected internal consistency check.

User Action:

Submit a Software Performance Report.

GSDTYP, module module-name file library file-spec has an
record record type
Explanation:

illegal

GSD

The specified object module is invalidly formatted.

User Action: Recompile the object
into the library.

module

before

ILLKEYLVL, illegal key level number key keyname in
expected key number

inserting

library

file-spec

Explanation: The help module you want to insert into the library
is not formatted properly.
User Action:
library.

Reformat the module before inserting

into

the

INDEXERR, index error in library file-spec
Explanation: An error occurred during an attempt to search the
index;
or a VAX-11 RMS error occurred; or there was not enough
virtual memory available.
User Action:
string.

Compress the library before reentering the

command

LIBRARIAN UTILITY
INSERTERR, error inserting module name in library file-spec
Explanation: The LIBRARY command could not insert the specified
modules into the library for one of the following reasons:
•

The modules are not formatted properly

•

The organization of the input file is incorrect

•

A VAX-11 RMS error occurred

•

There was not enough virtual memory

User Action:

Correct the error and insert the file.

KEYNAMLNG, key key-name name length illegal in library file-spec
Explanation: The name of the module you
the name length limit for the library.

are

User Action:
library.

inserting

Rename the module

before

inserting
it

exceeds
into

the

LOOKUPERR, error looking up module-name in library file-spec
Explanation: The Librarian could not find the requested module
in the module name table; or a VAX-11 RMS error occurred; or
there was not enough virtual memory available.
User Action:
module name.

Reenter the command

line

specifying

existing

MACNAMLNG, macro macro-name is too long in library file-spec
Explanation: The name of the macro you are
library exceeds the name length limit.

inserting

into

the

User Action: Either rename the macro
name length limit.

extend

the

lihrary's

MODNAMLNG, illegal module name module-name
library file-spec

numher

characters

Explanation: The name of the object module you
into the library exceeds the name length limit.

are

inserting

User Action:
library.

into

Rename the module

hefore

NESTLEVEL, nesting level exceeded in macro
file-spec

inserting

macro

name

file

library

Explanation:
of n3.

The specified macro has exceeded the nesting

User Action:
library.

Change the

macro

7-nl

before

insertinq

the

into

limit
the

LIBRARIAN UTILITY
NOEOM, module module-name is not terminated with EOM record in library
file-spec
Explanation: The object module you want to
library does not contain a legal EOM record.
User Action:

insert

into

the

Recompile the object module.

NOMODNAM, no module name found for input-file-spec
Explanation: An attempt was made to insert unnamed text
into a text library.
User Action:

mooules

Use the /MODULE qualifier to name the text modules.

NOTOBJLIB, not an object library
Explanation: An attempt was made to cross reference a lihrary or
to use the /REMOVE qualifier in a macro, help, or text li~rary.
User Action: Reenter the command line, specifying
library that contains the requested symbol.

object

input

file

OPENIN, input file open error
Explanation: The LIBRARY command could not open the
for one of the followinq reasons:
•

The user directory or file is protected against read access

•

A physical device problem;
mounted

•

The specified directory does not exist

•

The specified file does not exist

•

On create and compress operations, there is not
to allocate the new library file.

User Action:

for example,

the

volume

enough

not

space

Correct the problem and reenter the command line.

READERR, error reading file file
Explanation:

This is an error detected hy VAX-11 RMS.

User Action: Check that the file exists and that you
privilege to it.

have

RECLNG, illegal record length number in module module-name in
file-spec

read

library

Explanation: The specified module contains records exceeding the
maximum record length of 2048 bytes.·
User Action: Correct the
module in the library.

record

7-n2

length

before

inserting

the

LIBRARIAN UTILITY
RECTYP, illegal record type type
file-spec

module

module-name

The specified object

illegal

User Action:
string.

Recompile the module before reentering the

command

Explanation:
formatted.

sequence

module

contains

library

Explanation:
record type.

SEQNCE, illegal record
file-spec

module

module-name

The object module you want to insert

User Action: Recompile the object
into the library.

module

before

in
is

library
illegally

inserting

SPNAMLNG, PSECT module module-name file library file-spec has
length number

illegal

Explanation: The program-section name lenqth exceeds the maximum
length of 31 characters.
User Action:
line.

Recompile the module before reentering the

STRLVL, object structure level
number
module-name in library file-spec
you

are

unsupported
inserting

command

module

Explanation:
formatted.

The object file

User Action:
the library.

Recompile the object file before inserting it

SYMNAMLNG, module type module module-name file library
illegal length number
Explanation:
limit.

The specified module name exceeds the

invalidly
into

file-spec
name

has

length

User Action: Make sure that all the symbol names in the module
are less than the library's name length limit; or compress the
library with a larger key length.
WRITEERR, error writing file
Explanation:

This is an error detecteo by VAX-11 RMS.

User Action: Make sure that the file is open and that
write privilege to it.

7-63

you

have

LIBRARIAN UTILITY
7.6.1.5

Severe Error Messages

BADKEY, illegal key
Explanation:

The specified module is not valid.

User Action:
module.

Reenter

the

command

line,

specifying

valid

MHDERR, module header error for module name in library-file-spec
Explanation:
header.

The specified module

has

invalidly

formatted

User Action:
line.

Compress the library hefore reentering the

command

INITERR, error initializing library-file-spec.
Explanation:

There is not enough virtual memory available.

User Action:

Increase your working set limit.

OPENOUT, error opening output file
Explanation:

This is an error detected by VAX-11 RMS.

User Action: Make sure that the file is open and that
write privilege to it.

you

have

Librarian Routines Messages

7.6.2

This section lists the success, warning, nnd error messages for the
Librarian routines.
Note that any of the Librarian routines may
produce VAX-11 RMS errors. On a VAX-11 RMS I/O error, the variable
LBR$GL RMSSTV is the VAX-11 RMS STV value of the failing operation.
On a successful call to LBR$0PEN, the VAX-11 RMS STV (Status Value) is
the type of library opened. For more detailed information on VAX-11
RMS errors, see the VAX-11 Record Management Services Reference
Man u a 1 •
-----····-- ·· ··--·-. ------"""·------ --------· --·----·----·--·--·----·~· ..

··--

7.6.2.1

Success Messages

NORMAL

success

OLDLIBRARY

old format library opened

7.6.2.2

Warning Messages

LBR$_HDRTRUNC, header truncated
Explanation: The buffer supplied to
than the header information.
User Action:

LBR$SET MODULE

Supply a larger buffer to LBR$SET MODULE.

7-fi4

smaller

LIBRARIAN UTILITY
LBRS_LIBOPN, library already open
Explanation:

The library you attempted to open is already open.

User Action:

No action is necessary;

processing continues.

LBR$_NOMATCHFOU, no match found
Explanation:
name table.

The specified module does not nppear in the

module

User Action:
library.

Make sure that the module

current

exists

the

LBR$_NULIDX, index is empty
Explanation:
empty.

On a call to LBR$GET_INDEX, the specified index

User Action:

No actibn is necessary;

processing continues.

LBR$_OLDMISMCH, old format library type mismatch
Explanation: The requested Version 1.0 library is of a different
type from that expected.
User Action: No action is necessary;
on the actual library type.

processing continues hased

LBR$_RECTRUNC, record truncated
Explanation:
the record.

The buffer supplied in the routine is too small for

User Action:
record.

Supply a sufficiently large huffer to

contain

the

LBR$_STILLKEYS, keys still point at data
Explanation: Keys in other indexes still point to the text.
Therefore, the call to LBR$DELETE_DATA did not delete the text.
User Action:

No action is necessary;

processing continues.

LBR$_TYPMISMCH, library type mismatch
Explanation: On a call to LBR$0PEN, the library type you
requested conflicts with the library type you specified in the
create-options argument.
User Action: No action is necessary;
on the actual library type.

7-~5

processing continues hased

LIBRARIAN UTILITY
7.6.2.3

Error Messages

LBR$_DUPKEY, duplicate key in index
Explanation: On a call
already exists.
User Action:

LBR$INSERT_KEY,

the

specified

key

Call LBR$REPLACE KEY to replace the existing key.

LBR$_ILLCTL, illegal control index
Explanation: Either the library is
specified an invalid library index.

not

User Action: Make sure the library
index is correct.

open,

open,
and

or
the

you

have

library

LBR$_ILLCREOPT, illegal create options
Explanation: The create options you specified for
invalid; ;r no options were specified.

LBRSOPEN

are

User Action:
routine.

calling

the

Correct

the

create

options

before

LBR$_ILLIDXNUM, illegal index number
Explanation:

The index number you specified is invalid.

User Action:
routine.

Correct

the

index

number

before

calling

the

LBR$_ILLFMT, illegal library format
Explanation: The file you specified calling LBR$0PEN is
actual library.
User Action:

not

Specify an actual library.

LBR$_ILLFUNC, illegal library function
Explanation:
invalid.

The library function you specified in

LBR$0PEN

User Action:
routine.

Correct the library

calling

the

function

before

LBR$_ILLOP, illegal operation for access requested
Explanation: You have attempted to modify a Version 1.0 library;
or you have attempted to modify a library that you opened for
read access.
User Action: Compress the library into the current
change the access privileges to the library file.

format;

LIBRARIAN UTILITY
LBR$_ILLTYP, illegal library type
Explanation:
invalid.

The type of library specified in LBR$INI CONTROL is

User Action:
routine.

Correct

the

library

type

before

calling

the

LBR$_INVKEY, invalid key
Explanation: The specified key is either of 0 length
greater than the maximum allowable length.

User Action: Either change the module name, or change
library's name length limit by compressing the library.

the

LBR$_INVNAM, invalid NAM block
Explanation:

The NAM block passed to LBR$INI_CONTROL is invalid.

User Action:

Correct the NAM block before calling the routine.

LBR$_INVRFA, invalid RFA
Explanation:
invalid.

The

specified

record's

file

address

(RFA)

User Action:

Correct the RFA before calling the routine.

LBR$_KEYNOTFND, key not found
Explanation: The Librarian could not find the key you specified
in the key-name argument to the LBR$LOOKUP KEY routine.
User Action:
routine.

Correct the key-name argument

before

calling

the

LBR$0PEN,

all

LBR$_LIBNOTOPN, library not open
Explanation: Except for LBR$INI CONTROL
routines require that the library be open.
User Action:

and

Open the library before calling the routine.

LBR$_LKPNOTDON, lookup has not been done
Explanation: Before calling LBR$GET_RECORD, you must first
LBR$LOOKUP KEY.
User Action:

call

Call LBR$LOOKUP KEY before calling LBRSGET RECORD.

LBR$_NOFILENAM, no file specification found
Explanation: In the LBR$0PEN routine, either the fns
was not supplied, or the NAM block was not filled in.
User Action:

argument

Correct the problem before calling the routine.

7-n7

LIBRARIAN UTILITY
LBR$_NOHLPTXT, help text not found
Explanation:
key path.

There is no help text associated with the specified

User Action:

Check that the help module is properly formatted.

LBR$_NOTHLPLIB, not a HELP library
Explanation: The library type specified in LBRSGET HELP is not a
help library.
Action: Make sure that the library is a help library before
calling the routine.

Us~r

LBR$_RECLNG, illegal record length
Explanation:

The record length exceeds 2048 bytes.

User Action:

Reformat the module.

LBR$_RFAPASTEOF, VBN in map block request

pas~

EOF

Explanation:

This is an internal consistency check.

User Action:

Suhmit a Software Performance Report.

LBR$_TOOMNYLIB, too many libraries open
Explanation:

Only lh libraries can be open concurrently.

User Action:
to access.

Use LBR$CLOSE to close any library you do not

need

LBR$_UPDURTRAV, index update during traverse illegal
Explanation: The routine that you specify in the routine-name
argument cannot contain any calls to either LBR$DELETE or
LBR$INSERT KEY.
User Action: Remove any embedded calls to either
LBR$INSERT KEY before calling the routine.

7-n8

LBRSDELETE

CHAPTER 8
MESSAGE UTILITY

The VAX-11 Message Utility allows
generation of messages by VAX/VMS.

programmers

control

the

Messages are produced by VAX-11 software products
under
many
circumstances -- for ·example, when a routine has run successfully,
when an error has occurred, or when a default value has been assigned.
Messages are displayed to the user as a line of alphanumeric codes and
text that explains the condition that caused the message to be issued.
A message is represented to the VAX-11 processor as a longword called
the message code. This 32-bit value can be referred to in programs by
means of a global symbol called the message symbol.
The information that appears in the message that users receive, the
values that make up the message code, and the characters that make up
the message symbol are all defined in files called message source
files.
VAX/VMS has a file of system message information-called
SYSMSG.EXE.
You can use your own message files by
Utility, following these steps:

means

the

VAX-11

Message

•

Use a text editor to create a source file that specifies the
information used in messages, message codes, and message
symbols.

•

Use the MESSAGE command to compile this source file.

•

Link the resulting object module, either by
another object module containing a program.

itself

•

Run your program so that the messages are
directly or through the use of pointers.

accessed,

with
either

You can modify messages at run time hy using the SET MESSAGE command
or by using pointers to message information. These features allow you
to suit messages to the requirements of your installation.
This chapter begins with a description of messages, the message code,
and the message symbol. It then explains the components of a message
source file, and how the file can he compiled and linked.
It
describes different methods of changing messages at run time, and
concludes with a list of the messages issued by the Message utility
itself.

8-1

MESSAGE UTILITY
8.1

THE FORMAT OF MESSAGES

Messages have the following format:
%FACILITY-L-IDENT, message-text
% and ,

The percent sign (%) and comma (,) are included as delimiters if
any of the first three fields -- FACILITY, L, or !DENT -- is
present.
FACILITY
The abbreviated name of the software product that issued the
message.
You specify the facility name to be used in your
message source file by means of the facility
definition,
described in Section 8.3.1.1. The FACILITY field can contain up
to nine characters from the character set desc~ibed in Section
8.3.1.
You can suppress the appearance of FACILITY for your
means of the /NOFACILITY qualifier on the DCL
MESSAGE, described in Section 8.4.2.

process by
command SET

L
An indicator showing the severity level of the condition that
caused the message.
There are five levels, represented by the
following codes:
Code

Function

Success
Informational
Warning
Error
Fatal or severe

w
E
F

You set the severity level of messages in your message source
file using either the severity definition, described in Section
8.3.1.2, or a severity qualifier on the message definition,
described in Section 8.3.1.4.
You can suppress the appearance of the severity level
indicator
for your process by means of the /NOSEVERITY qualifier on the DCL
command SET MESSAGE, described in Section 8.4.2.
!DENT
A symbol of up to nine characters representing the message.
Valid characters are described in Section 8.3.1. You specify the
symbol in the message definition line of your message source
file, described in Section 8.3.1.4.
You can suppress the appearance of the !DENT symbol for your
process by means of the /NOIDENTIFICATION qualifier on the DCL
command SET MESSAGE, described in Section 8.4.2.

8-2

MESSAGE UTILITY
message-text
A brief explanation of the cause of the message. You specify the
message text in the message definition line of your message
source file, described in Section 8.3.1.4.
If you suppress FACILITY, L, and !DENT, the first character of
the message text will be capitalized by the Put Message (SPUTMSG)
system service.
You can suppress the appearance of the message text for your
process by specifying the /NOTEXT qualifier on the DCL command
SET MESSAGE, described in Se~tion 8.4.2.
The message can also include up to 255 formatted-ASCII-output
(FAO)
arguments;
that is, character strings that can be used to display,
for example, the instruction at which an error occurred or a value of
which the user should be aware. The following sample message includes
the file specification as an FAQ argument:
%TYPE-W-OPENIN, error opening _DBO: [MARCEL]BBBB.FOR; as input

8.2

THE MESSAGE CODE AND THE MESSAGE SYMBOL

Messages are formatted by the Put Message
(SPUTMSG)
system service,
described in the VAX/VMS System Seryices Reference Manu~J.• The system
service finds the information to use in the message by using a message
argument vector. The message argument vector includes a 32-hit value
that uniquely identifies the message. This 32-bit value is called the
message code.
The message code is made up of the following
described individually in Section 8.3.l:
defined

the

elements,

severity

which

are

definition

•

The severity level
message definition

•

The message number assigned automatically by a
message
definition or specified with the message number specifier

•

The facility number defined in the facility definition

•

The customer facility bit of the control area, the setting
which can be inhibited in the facility definition

Figure 8-1 shows the arrangement of the bits in the message code. The
message code is described fully in the VAX-11 Architecture Handbook
description of "Condition Value."

28 27

control

16 15
message number

facility number

Figure 8-1

3 2

Message Code

8-3

0
sev

MESSAGE UTILITY
The message symbol is the symbol that represents the message code. It
appears in the object module (the compiled message file) as a global
symbol.
The message symbol is constructed of the following elements, described
in Section 8.3:

8.3

•

The symbol prefix defined in the facility definition

•

The symbol name defined in the message definition

CONSTRUCTING MESSAGES

You construct messages by creating a message source file that contains
the information that you want to include in the messaqe, the message
code, and the message symbol. You then compile the message source
file with the Message compiler and link the resulting object module
with the VAX-11 Linker. This section describes the contents of the
message source file and the use of the compiler and linker to convert
the message source file into usable form.
It concludes with a sample
program that generates messages at run time.

8.3.1

The Message Source File

The message source file contains the information that makes up the
message, the message code and the message symbol. The file is made up
of statements that establish the various fields of the message, define
symbols, and control the output listing of the file. The message
source file has the default file type MSG.
The elements of the message source file, described
sections, are:

•

Facility definition

•

Severity definition

the

following

• Message number specifier
•
•
•
•

Message definition
Literal directive
Listing directives
End statement

The format of each statement in the message source file is described
in the appropriate section below. A statement in a message source
file can take up any number of lines;
text that reaches the end of a
line and is to be continued on the next line must end with a hyphen
(-). The only exceptions to this are the listing title specified with
the .TITLE directive and the message text specified in the message
definition, which must occupy only one line.
Any line in the message source file can include a comment, delimited
by an exclamation point (!). In any line, you can freely insert extra
spaces and tabs to improve readahility.

8-4

MESSAGE UTILITY

Symbols defined in the
following characters:

Message

utility

can

include

any

the

A - Z
a -

1 - 9
$

(dollar sign)
(underline)

Expressions used in the Message utility can include any of the
following radix operators to specify the radix of a numeric value:
Operator

Radix

Example

"'x
"'o

Hexadecimal
Octal
Decimal

"XlO

"'D

"'030

"DH

The def a ult radix is decimal.
Expressions can include symbols and the unary operators plus sign (+),
which assigns a positive value, and minus sign (-), which assigns a
negative value. Expressions can also include the following binary
operators:
Operator

Function

Addition
Subtraction
Multiplication
Division
Arithmetic shift

Expressions can include parentheses as special operators. Expressions
enclosed in parentheses are evaluated first. Nested parenthetical
expressions are evaluated inside to outside.

The Facility Definition -- The texts of messages are grouped
in a message source file by the facility (software product) to which
they apply, broken down by severity levels.
Therefore, a facility
definition, specifying the facility to which messages will apply, is
the first definition in a message source file.
All of the lines
following a facility definition apply to that facility, until an end
statement or another facility statement is reached.
8.3.1.1

The facility definition has the format:
.FACILITY[/gualifier, ••• ]

facnam[,]facnum [/qualifier, ••• ]

qualifier
One of the qualifiers listed in Table 8-1.
f acnam
The facility name, which will be used as the facility field of
the message and in the symbol that represents the facility
number. It can have up to nine characters. Facility names for
VAX/VMS facilities are listed in the VAX/YM§__3~-!:_~m M~ssage~~-~~
Rec o':~EX. .~E oc-~~l!..E_':.~_.!'1_ an.~~}. •

8-5

MESSAGE UTILITY

f acnum
The facility number, a decimal value in the range of 1 to 32768,
or an expression that evaluates to a value in that ranqe.
(For
information on expressions, see the VAX/VMS Command -Language
User's Guide.) Facility numbers are usually assigned by the
system manager so that no two facilities have the same number.
The facility number is used to construct the 32-bit value of the
message code.
Note that both the facility name and the facility number are required.
They can be separated by a comma or by any number of spaces or tabs.
The facility definition creates a global symbol of the form:
facnam$ FACILITY
This symbol can be used to refer to the facility
the facility.

number

assigned

Table 8-1
Facility Definition Qualifiers

----------------·----------·-----Qualifier

Function

1 - - - - - - ----·-. --. -·-·----------··--·······---. . . - . . . . . . . . . . .__. . . . . . . .__, ______ ----------·--·-·. ··--· _,_. ___ . _
/PREFIX=pref ix

Defines an alternate symbol prefix to be used
in
the
message
symbol for all messaqes
referring to this facility.
The alternate
prefix can have up to nine characters. The
default symbol prefix is the facility name
followed by an underline ( ). If /SYSTEM is
also specified, the default prefix is the
facility name followed by a dollar sign and an
underline ($_).

/SHARED

Inhibits setting the facility specific hit in
the message codes. This qualifier is used only
for system service and shared messages.
This
qualifier is reserved for DIGITAL use.

/SYS'fEM

Inhibits setting the customer facility bit in
the message codes. This qualifier is reserved
for DIGITAL use.

8.3.1.2 The Severity Definition -- Following the facility definition,
the message source file generally contains a severity definition
specifying the severity level to be associated with the messages that
follow.
You must include a severity definition if you do not specify
the severity individually on each message definition
(see Section
8.3.1.4).

8-n

MESSAGE UTILITY
The severity definition has the format:
SUCCESS
INFORMATIONAL
WARNING
.SEVERITY
ERROR
SEVERE
FATAL
SEVERE is equivalent to FATAL and can be used interchangeably with it;
the severity level code for both of these, as descrihed in Section
8.1, is F.
If you attempt to define a message without specifying a severity
level, an error will result. A new facility definition cancels the
severity level in effect before it.

The Message Number Specifier -- The message number is a value
used in constructing the message code that represents the message (see
Section 8.2). All of the messages following a facility definition are
numbered
sequentially,
beginning
with
l after each facility
definition.
8.3.1.3

In some cases, you may need to supersede this numbering system -- for
example,
if you want to reserve some message numbers for future
assignment. You can specify a message number of your choice using the
message number specifier, .BASE, which has the following format:
.BASE

number

number
A message number to be associated with the next
message
definition, or an expression that is evaluated as the desired
number. This message number is used as a base for the sequential
numbering of all messages that follow until another .BASE is
encountered or until the end of the messages belonging to the
facility.

The Message Definition -- The message definition specifies
the body of the message symbol, the message text, and the number of
arguments that can be printed with the message. Any number of message
definitions
can
follow
the severity definition.
The message
definition has the format:

8.3.1.4

name[/qualifier, ••• ]

<message-text>[/qualifier, ••• ]

name
Up to nine characters. This symbol name is combined with the
symbol prefix defined in the facility definition to make up the
message symbol.

8-7

MESSAGE UTILITY
The symbol name is used in the !DENT field of the message
(see
Section
8.1)
unless the /IDENTIFICATION=name qualifier is
specified in the message definition, as described in Table 8-2.
/qualifier
Any of the qualifiers listed in Table 8-2.
Qualifiers
placed before or after the message text, in any order.

can

message-text
An explanation of the condition that caused the message to be
issued.
The message text can he delimited either by angle
brackets (<>), as shown above, or by quotation marks
( 11 ) .
The
text can be up to 255 bytes long; however, you cannot continue
the delimited text onto another line.
The message text can
include directives that insert ASCII strings into the resulting
message;
these directives are used by the Formatted ASCII Output
($FAO)
system service and are described in the VAX/VMS System
Services Reference Manual. If you include an FAQ directive, you
must also use the-/FAO_COUNT qualifier, described in Table 8-2.
Table 8-2
Message Definition Qualifiers
Qualifier

Function

/FAO_COUNT=n

Specifies the number of FAQ arguments to
be included in the message at execution
time.
(See the VAX/VMS System Services
Reference Manual for an explanation of FAO
arguments.) The value n must be a decimal
number in the range 0 through 255. The
$PUTMSG system service uses n to determine
how many arguments are to he given to the
SFAO system service when constructing the
final message text. The default value for
n is zero.

/IDENTIFICATION=name

Specifies an alternate character string to
be used as the !DENT field of the message
(see Section 8.1). The string can include
up to nine characters. If this qualifier
is not specified, the symbol name defined
in the message definition (see above) will
he used in the !DENT field of the message.

/USER_VALUE=n

Specifies an optional user value that can
be associated with the message. The value
n must be a decimal number in the range of
O through 255. The default is zero. The
value can be retrieved by the Get Message
(SGETMSG)
system
service for use in
classifying messages by type or hy action
to he taken.
(continued on next page)

8-8

MESSAGE UTILITY
Table 8-2 (Cont.)
Message Definition Qualifiers
Qualifier

Function

/SUCCESS

Specify the severity level to be associated with the message. You can use these
qualifiers to supersede the severity level
defined in a severity definition. You can
also use these qualifiers instead of including severity definitions in your message source file. Only one severity qualifier can he included per message definition.

/INFORMATIONAL )
/WARNING

(

/ERROR
/SEVERE
/FATAL

8.3.1.5 The Literal Dire~tive -- The literal directive allows you to
define global symbols in your message source file. You can either
assign values to these symbols or use the default values provided by
the statement. The .LITERAL directive has the form:
• LI'fERAL

symbol [=value] [, ••• ]

symbol
A symbol name.
value
Any valid expression. If value is omitted, a default value is
assigned.
The default value is 1 for the first symbol in the
statement;
for subsequent symbols in the same statement, the
default value is 1 plus the last value assigned.
You can assign default values to a list of symbols.
.LITERAL

For example:

A,B,C

The values of A,B, and C will be 1, 2, and 3.
You can use the .LITERAL directive to define a symhol as the value of
another previously defined symbol, or as an expression that results
from operations performed on previously defined symbols.
In the
following example, symbols defined in the facility and message
definitions are used to assign values to symbols created with the
.LITERAL directive.
.FACILITY
.SEVERITY
FIRST

SAMPLE,l/PREFIX=MSG$
ERROR
<first error>

LAST
.LITERAL

<last error>
LASTM$G=MSG$ LAST

.LITERAL

NUMSG={MSG$_LAST@-3)-(MSGS_FIRST@-3)

8-9

# of messages

MESSAGE UTILITY
The first .LITERAL directive defines a symbol that has the value of
the last 32-bit message code defined. The second .LITERAL directive
defines the total number of messages in the source file.

8.3.1.6 Listing Directives -- You can use two special statements to
control the output listing that is produced when you compile your
message source file. These statements are the .PAGE directive and the
.TITLE directive.

The .PAGE directive enables you to force page
listing. It has the format:

breaks

the

output

.PAGE
You can only specify one page break with any one .PAGE directive;
however, you can use the .PAGE directive as often as you like.
The .TITLE directive enables you to specify the module name and title
text that will appear on the top of each page of the listing file.
It
has the format:
• TITLE mod name [ 1 i st i n g - t i t l e ]
mod name
A character string of up to 31 characters that will appear in the
object module as the module name.
listing-title
Text to be used as the title of the listing.
The text begins
with the first nonblank character after the module name through
the end of the line. The listing title cannot he continued onto
another line.

The End Statement -- A group of message definitions is
terminated by either:
another severity definition, to begin a new
group of another severity; an end statement, which terminates the
entire list of messages for the facility;
or a new facility
statement. The end statement has the format:
8.3.1.7

.END
A new facility statement performs an implicit .END.

Sample Message Source File -- The following sample
source file illustrates the various elements described above.

8.3.1.8

.TITLE
.FACILITY
.SEVERITY

SAMPLE Error and Warning Messages
SAMPLE,l/PRF.FIX=ABC
ERROR
-

UN RE COG
AMBIG

<Unrecognized keyword !AS>/FAO_COUNT=l
<Ambiguous keyword>

.SEVERITY
.BASE
SYNTAX

WARNING
10

.END
8-10

message

MESSAGE UTILITY
The messages defined in this message source file belong to a facility
with the name SAMPLE and the facility number 1. The first two
messages have the severity level E;
the third message has the
severity level w.
The first message definition above includes the FAO directive !AS
(which inserts an ASCII string at the ehd of the message text) and the
corresponding qualifier /FAO_COUNT, as described in Section 8.3.1.4.
file
are
The message symbols defined in this message source
ABC UNRECOG, ABC_AMBIG, and ABC SYNTAX. The message numbers are 1, 2,
and-10.

8.3.2

Compiling the Message Source File

Message source files must be compiled into object modules before the
messages defined in them can be used. You compile your message source
file by issuing the MESSAGE command in response to the DIGITAL Command
Language (DCL) prompt. The MESSAGE command can also be used to create
object modules that do not contain message data;
instead, they
contain pointers to files that contain message data. These pointers
are described in Section 8.4.1:
The MESSAGE command has the following format:
MESSAGE[/qualifier, ••• ] file-spec[, ••• ]
/qualifier
Any of the qualifiers listed in Table
qualifiers are mutually exclusive.

8-3.

Note

that

some

file-spec
The message source file to be compiled.
file type, the default is MSG.

If you do not specify

You can specify more than one message source file,
separated
either commas
(,) or plus signs
(+).
The files will
concatenated and compiled as a single file.

by
be

If you specify SYS$INPUT, the message source file(s}
must
immediately follow the MESSAGE command in the input stream, an<l
both the object module name (given by the /OBJECT qualifier) and
the listing file name
(given by the /LIST qualifier) must be
explicitly stated.
For your convenience, you can put message object modules into object
module libraries.
These libraries can then be linked with facility
object modules.

8-11

MESSAGE UTILITY
Table 8-3
MESSAGE Command Qualifiers
Qualifier
/FILE NAME=file-spec
/NOFILE_NAME

Function
Specifies whether the object module contains a pointer to a file containing
messages.
{Pointers are described in
Section
8.4.1.)
The
default
is
/NOFILE NAME,
indicating that the object
module -contains only compiled
message
information, and no pointers.
Whenever you specify /FILE NAME=file-spec,
the /NOTEXT qualifier is implied; that
is, the /FILENAME and /TEXT qualifiers are
mutually exclusive. The /OBJECT qualifier
must be in effect, either explicitly or
implicitly.
The file
specification
identifies
a
nonexecutable message file, as explained
in Section 8.4.1. The default device and
directory for the file specification is
SYS$MESSAGE; and the default file type is
EXE.
No wild card characters are allowed
in the file specification.

/LIST[=file-spec]
/NOLI ST

Controls whether an output listing
is
created, and optionally provides an output
file specification for the listing.
When you compile message source files in
batch mode, the output listing is created
by default. However, in interactive mode,
the
default is to produce no output
listing.
The default file type for listing files is
LIS.

The default device and directory are your
default device and directory.
No wild
card characters are allowed in the file
specification.
/OBJECT[=file-spec]
/NOOBJECT

Controls
whether an object module is
created by the message compiler,
and
optionally provides a file specification
for the object module.
By default, the compiler creates an object
module with the same name as the first
message source file and with the file type
OBJ. The default device and directory are
your default device and directory.
No
wild card characters are allowed in the
file specification.
{continued on next page)

8-12

MESSAGE UTILITY
Table 8-3 (Cont.)
MESSAGE Command Qualifiers

...-------------·-·---.-·----- ...
Qualifier

Function

t------·-·-----·-·------·---·-·--------····--i-··--"' --·······--- -------------------·----·- --

/SYMBOLS
/NOSYMBOLS

Controls whether global symbols will be
present in the object module. By default,
object modules are created with global
symbols.
The /SYMBOLS qualifier requires that the
/OBJECT qualifier be in effect, either
explicitly or implicitly.

/TEXT
/NOT EXT

Controls whether the data portion of the
object module, containing the information
specified
in
facility, severity, and
message definitions,
is present in the
object module.
(Section 8.4.1 describes
the use of pointers, which require that
data not be present in the object module.)
The default is /TEXT.
The /TEXT and
/FILE NAME
qualifiers
are
mutually
exclusive. The /TEXT qualifier requires
that the /OBJECT qualifier be in effect,
either explicitly or implicitly.
The /NOTEXT qualifier can be used with the
/SYMBOLS qualifier to produce an object
module containing only global symbols.

8.3.3

Linking the Message Object Module

Before your messages can be used, your program must be linked by the
VAX-11 Linker.
The VAX-11 Linker resolves symbolic and library
references and assigns virtual memory addresses to the relative
addresses assigned by the compiler. It produces an executable image
file with the file type EXE, which can be run on a VAX-11 processor.
The message object module that results from compiling your message
source file can be linked in two different ways. It can be linked
with an object module from the facility to which it applies, creating
one executable image that contains both the facility code and the
message data.
Or, it can be linked by itself to
create
a
nonexecutable message file. A nonexecutable message file can be used
as a process permanent message file (see Section 8.4.2) or can be
referenced at run time hy a pointer (see Section 8.4.1).
Figure 8-2 shows the two ways of linking a message object module.
To link your message object module, issue the DCL command LINK in
Le~ponse
to the DCL prompt, as describerl in the VAX-11 Linker
Reference Manual. The following is the command that links the object
mo-au·i~c······2c-80Lco1SE. OBJ
and the message object file COBOLMSG. OBJ. The
command 2reates an image map file.
The resulting executable image
file is nam0d CCBOLCODE.EXE.
L1NK/Mi\P

CUdULCODE,COBOLMSG

8-13

MESSAGE UTILITY

MESSAGE
OBJECT
MODULE

-I

LINKER

--- ----

NONEXECUTABLE
MESSAGE
FILE

MESSAGE
OBJECT
MODULE

LINKER

EXECUTABLE
PROGRAM,
INCLUDING
MESSAGE DATA

FACILITY
OBJECT
MODULE

Figure 8-2 Linking a Message Object Module

8.3.4

Running a Program with Messages

This section shows how a program, linked with a message object module,
produces messages when run.
The program is a FORTRAN program
following lines:

named

TEST.FOR.

contains

the

EXTERNAL MSG SYNTAX,MSG ERRORS
CALL LIB$SIGNAL(MSG SYNTAX,%VAL(l) ,'ABC')
CALL LIB$SIGNAL(MSG=ERRORS)
END
This program calls the run-time procedure LIB$SIGNAL, described in the
VAX-11
Run-Time Library Ref~-!::~J]_Ce Manual.
The message symbols
MSG SYNTAX and MSG ERRORS are included as arquments in the procedure
calls. The function %VAL is a required FORTRAN compile-time function.
The first call also includes the string 'ABC' as an FAO argument.
You compile the FORTRAN program by issuing the followinq command:
$ FORTRAN TEST

This command results in an object module named TEST.OBJ.
The message source file, TESTMSG.MSG, contains the following lines:
• FACILITY
.SEVERITY
SYNTAX
ERRORS

EFG fl, 1 /PREFIX=MSG
ERROR
<Syntax error in string '!AS'>/FAO=l
<Errors encountered during processing>

.END

8-14

MESSAGE UTILITY
You compile the message source file by issuing the following command:
$ MESSAGE TESTMSG

This command results in a message object module named TESTMSG.OBJ.
You link the two object modules by issuing the following command:
LINK/NOTRACE TEST+TESTMSG
This command results in an executable program named TEST.EXE.
this program by issuing the following command:

You run

RUN TEST
The following messages are issued when the program is run:
%EFGH-E-SYNTAX, Syntax error in string 'ARC'
%EFGH-E-ERRORS, Errors encountered during processing

8.4

CHANGING MESSAGES

Under some circumstances, you may want to change the messages for a
facility that runs on your VAX-11 processor. You can make run-time
changes on two levels:
1.

per image, by using pointers to message data

per process, by using the DCL command SET MESSAGE

Using pointers is described in Section 8.4.1;
command is described in Section 8.4.2.

8.4.1

using the

SET

MESSAGE

Pointers to Message Data

If you have linked your message ohject module nirectly with the
facility
object module, you will have to alter the resulting
executable image file to change the message data included in it. This
can be time consuming and the resources needed to link the image may
not be available. To avoid having to alter the executable image, you
can use pointers to a message file instead of linking the message data
into the image.
A pointer is created by referring to a non-executable message image in
a MESSAGE command,
using the /FILE_NAME qualifier
(described in
Section 8.4). The non-executable message file
is a message source
file that has been compiled and linked by itself.
The MESSAGE/FILE NAME command results in an object module containing
only global symbols and the file specification of the message file,
which can then be linked with facility object modules.
An object module containing a pointer to message files should have a
different file name from the module that actually contains message
data.

8-15

MESSAGE UTILITY
The following command creates an object module named MESPNTR.OBJ,
which
contains
a
pointer to the non-executable message file
COBOLMF.EXE.
(COBOLMF.EXE was created by compiling the message file
COBOLMSG.MSG and linking the resulting object module by itself with
the qualifier /EXECU'rABLE=COBOLMF.) Note that it is not necessary to
include the file type EXE in the /FILE NAME qualifier, because EXE is
the default. The object module, MESPNTR.OBJ, contains the global
symbols defined in the message source file COBOLMSG.MSG.
MESSAGE/FILE_NAME=COBOLMF /OBJECT=MESPNTR COBOLMSG
When the resulting facility image file is run, the message data is
retrieved from the message file COBOLMF by the $GETMSG system service.
Figure 8-3 illustrates the relationship of the files affected hy this
command.

~---MESSAGE
SOURCE

~0~G-.~~~

MESSAGE
OBJECT
MODULE
COBOLMSG.OBJ

COMPILER

LINKER
/EXEC UT ABLE~
COBOLMF

NONEXECUTABLE
MESSAGE
FILE
COBOLMF.EXE
I

I
I $GETMSG

---COMPILER

MESSAGE
POINTER
OBJECT
MODULE
MSGPNTR.OBJ

/FILENAME~

COBOLMF
/OBJECTo
MSGPNTR

LINKER

----··-·- -

Figure 8-3

8.4.2

EXECUTABLE
PROGRAM,
INCLUDING
POINTER TO
MESSAGE DATA
~-

Creatinq a Messaqe Pointer

The SET MESSAGE Command

You can override or supplement the system messages on your system by
using the DCL command SET MESSAGE.
This command allows you to
suppress for your process the various fields of the
messages
(described in Section 8.1) or to substitute the message data in a
nonexecutable message image for the system message data.
The SET MESSAGE command has the following format:
SET MESSAGE[/qualifier ••• ]

[file-spec]

/qualifier
A qualifier listed in Table 8-4.
be used, specified in any order.

8-H

Multiple command qualifiers can

MESSAGE UTILITY

file-spec
An optional nonexecutable message file. The default file type is
EXE;
no
wild
card characters are allowed in the file
specification.
The specified message file supersedes any per-process message
file already in effect; only one per-process message file can he
in effect at any time.
The messages contained in the specified message file are searched hy
the $GETMSG system service after the per-image messages and before the
system-wide messages.
Table 8-.4
SET MESSAGE Qualifiers
,---------------.----- -·---- ···-···- ··--------·----·-··--··-

Qualifier

Function

/DELETE

Removes the process message file from your
process.
This qualifier cannot be used if
you have included a file specification in
the SET MESSAGE command; selecting a new
per-process
message
file
automatically
removes any existing process message file.

/FACI LI'fY
/NOFACILITY

Control whether the facility name field (see
Section 8.1) is displayed for all messages
that occur in your process.

/IDENTIFICATION
/NOIDENTIFICATION

Control whether the IDENT field (see Section
8.1) is included for all messages that occur
in your process.

/SEVERI'fY
/NOSEVERITY

Control whether the severity level indicator
(see Section 8.1)
is displayed for all
messages that occur in your process.

/TEXT
/NOTEXT

Control whether the message text field is
displayed for all messages that occur in
your process.

Examples

$ SET MESSAGE MYMSG

The SET MESSAGE command
information in MYMSG.EXE
messages.
2.

specifies
supplements

that
the
message
the existing system

$ TYPE BBBB. FOR

%TYPE-W-OPENIN, error opening DBl: [MARCEL]BBBB.FOR; as input
-RMS-E-FNF, file not found
$ SET MESSAGE/NOIDENTIFICATION
$ TYPE BBBB.FOR

%TYPE-W, error opening DBI: [MARCEL]BBBB.FOR; as input
-RMS-E, file not found

8-17

MESSAGE UTILITY
When the first TYPE command is entered, error messages
contain all fields.
Entering the SET MESSAGE command with
the /NOIDENTIFICATION qualifier eliminates the IDENT field
from the messages that are subsequently issued.

8.5

MESSAGE UTILITY MESSAGES

This section lists, in alphabetical order, the error messages issued
by the Message compiler, with an explanation of the condition that
caused the error and a recommended user response to the message. Most
of the user responses entail changing the message source file and
re-entering the MESSAGE command.
All of these messages have the severity level ERROR.
MESSAGE-E-BADVALUE, illegal qualifier value
Explanation:
invalid.

You

User Action:

Reenter the statement with a valid qualifier value.

MESSAGE-E-CONFFAC,
definition

have

facility

specified

definition

qualifier

value

conflicts

Explanation: You have specified the same
facility number for two different facilities.

that

with
facility

User Action: Reenter the facility definitions
facility name corresponds to one facility number.

name
that

or
each

MESSAGE-E-DATAOVFL, data area overflow in section - please submit SPR
Explanation:
detected.

internal

error

User Action: Submit a Software
DIGITAL, describing a situation.

the

compiler

Performance

has

Report

been

(SPR)

MESSAGE-E-DUPMSG, message code nn already assigned as ss
Explanation: You have assigned the same message code,
(here
represented by nn)
to more than one message symbol. The first
message symbol assigned to the message code is shown
(here
represented by ss).
User Action: Check that you have not assigned the same message
number or symbol name twice for the same facility. Reenter the
message definition(s) so that each message symbol is assigned to
one message code.
MESSAGE-E-DUPSYM, duplicate symbol definition
Explanation: You have assigned the same symbol to represent two
values.
This message may refer to symbols defined in a message
definition, a facility definition, or the .LITERAL directive.
User Action: Reenter your source
defined only once.

8-18

statements

with

each

symbol

MESSAGE UTILITY
MESSAGE-E-FACOVFL, facility table overflow in section - please
SPR
Explanation:
detected.

internal

error

the

compiler

User Action: Submit a Software Performance
DIGITAL, describing the situation.

Explanation:
detected.

internal

error

the

has

Report

MESSAGE-E-INDEXOVFL, index area overflow in section
SPR

been

(SPR)

please

compiler

User Action: Submit a Software Performance
DIGITAL, describing the situation.

submit

submit
been

has

Report

(SPR)

MESSAGE-E-NOMSGS, no messages defined
Explanation:
file.

No messages have been def ineo in the message source

User Action: Ensure that at least one message definition appears
in the message source file.
MESSAGE-E-NOSEVER, severity unspecified, ERROR used
Explanation: You have omitted defining the severity of
a
facility's messages. The Message Utility has assigned the level
ERROR to the messages.
User Action: Add the appropriate severity levels to the message
source file, either with severity definitions or with severity
qualifiers on message definitions.
MESSAGE-E-SHARCONF, /SHARED conflicts with facility number
Explanation: You have specified the /SHARED qualifier
facility definition with a facility number other than O.

User Action:
definition.

facility

Remove the

/SHARED

qualifier

from

the

MESSAGE-E-SYMTOOLNG, symbol name too long
Explanation: You have assigned
characters than are permitted.
User Action:

Shorten the symbol name.

8-19

~ymbol

name

with

APPENDIX A
FILES-11 DEVICES SUPPORTED BY VAX/VMS

Tables A-1 and A-2 list the Files-11 structured devices supported by
VAX/VMS, with their storage characteristics and the device codes used
to refer to them. Table A-1 lists magnetic tape devices;
Table A-2
lists disk devices.
See the VAX/VMS I/O User's Guide for more
information on these devices.
--Table A-1
Magnetic Tape Devices
___ ,..

·············...-··~--------~---

~--·-·-·-·-····-----~----·-··

Model

Code

No.
of
Tracks

TE16

800 or
1000

800 or
1600

800 or

TSll

TU45

--·-.. ......
,.

1. NRZI

-.-~·---.....,.,,.

-r--•r•~~-•r-·~--~·-•-,,~~

••,

,--.

.....

-·-·Recording
method

··~

Max.
data transfer
rate in bytes per
second
36,000 (for 800
bpi);
72,000 (for
lnOO bpi)

NRZI or

36,000 (for 800
72,000 (for
bpi);
lfiOO bpi)

NRZI or

60,000 (for 800
bpi) 120,000
(for le)OO bpi)

NRZI or

100,000 (for 800
bpi) 200,000
(for 1600 bpi)

NRZI or

800 or
1600

Tape
speed
(ips}

HOO

TU77

··-·--

Recording
density
(bpi}

125
-

.... ...

---~-~-

-.~.,......,._

= non-return-to-zero-inverted;

A-1

···--·-------

.... ··-----~---~-·-·-·'"

-- -----~

-- phase encoded.

PE 1

PE
~-·-----~-··--·

FILES-11 DEVICES SUPPORTED BY VAX/VMS
Table A-2
Disk Devices
-

Model

Code

Type 1

RPM

Surfaces

Cylinders

Bytes/
Track

Bytes/
Drive

·-~--··

~---·-,----··-

RL02

Cart

2400

512

10,240

10,485,760

RM03

Pack

3600

8 23

16 '38 4

67,420,HiO

RPOS

Pack

3600

411

11'264

87 ,960 ,576

RP06

Pack

3600

815

11,264

174,423,040

RK07

Cart

2400

815

11'264

27,550,480

RXOl

Flop

360

3,328

256,256

RX02

Flop

360

3,3282
6 '6 56 3

TU584

Cart

##
-

---·-

1. Pack
pack disk; Cart
diskette)

##
··'-·

-··--

·--·----------L.--

cartridge disk; Flop

256,2562
512,5123
262,144
-·-·-

floppy (flexible

2. Single density
3. Double density
4. A magnetic tape device, the TU58 operationally resembles a
disk device

A-2

INDEX

Changing the audit trail (SLP),
position and length, 3-6
through 3-8
text, 3-10~ 3-15
Changing messages (MSG), 8-15

Aborting
deletion (MAIL), 1-4
VFY, 6-5, 6-7, 6-9
Add Bad Blocks qualifier (DSC),
4-7' 4-14' 4-15

Adding lines to a file (SLP), 3-11
through 3-13
Allocating bad blocks (BAD), 5-3
Alteration of messages (MSG), 8-15
through 8-18
per image, 8-15, 8-16
per process, 8-16 through 8-18
Append qualifier (DSC), 4-7, 4-12,
4-13

/AP qualifier (DSC), 4-7, 4-12,
4-13

/AUDIT TRAIL qualifier (SLP), 3-6
through 3-8

B
BACK command (MAIL}, 1-3
Backing up disks (DSC), 4-1
through 4-3, 4-9 through 4-13
BAD, 5-1 through 5-12
invoking, 5-3 through 5-4
terminating, 5-4
Bad block descriptor file, 5-3
format, 5-3
location, 5-2
Bad Block Locator Utility, 5-1
through 5-12
invoking, 5-3 through 5-4
terminating, 5-4
Bad blocks
allocating with BAD, 5-3
locating with BAD, 5-2
recording with BAD, 5-2, 5-3
recording with DSC, 4-3, 4-7,
4-14, 4-15
/BAD qualifiers (DSC), 4-7, 4-14,
4-15

BADBLK.SYS file, 5-3
.BASE definition (MSG), 8-7
Batch-oriented text editors, 3-1
through 3-24
/BL:n qualifier (FLX), 2-7
Block-structured volumes, 5-1

through 8-18
per image, 8-15, 8-16
per process, 8-16 through 8-18
/CHECKSUM qua 1 if i er (SLP) , 3-6,
3-8

CLOSE Librarian routine (LBR),
7-20
Closing a library (LBR),
7-20
/CMP qualifier (DSC), 4-7, 4-13
Code, message (MSG) 8-3
/CO qualifier (FLX), 2-7
Command file, SLP, 3-3
Command files, SUMSLP, 3-17
Command string
BAD, 5-4
DSC, 4-6, 4-7
FLX, 2-2, 2-9 through 2-12
LBR, 7-3 through 7-13
SLP, 3-1, 3-2
SUMSLP, 3-15 through 3-17
VFY I 6-6
Commands
MAIL, 1-3
SLP editing, 3-9 through 3-11
Comments
in he 1 p f i 1 es (LB R) , 7 -14
in message source statements
(MSG), 8-4
Compare qualifier (DSC), 4-7, 4-13
Comparing volumes (DSC), 4-4, 4-7,
4-10, 4-13

Compiling message source files
{MSG), 8-11 through 8-13
/COMPRESS qualifier {LBR), 7-5,
7-6

Compressing files {DSC), 4-3
Converting physical disk addresses
(DSC), 4-16, 4-17
Copying distribution medium (DSC),
4-2

/CREATE qualifier (LBR), 7-6,
7-7, 7-12

/CROSS REFERENCE qualifier (LBR),
7-7' 7-12

c
Cancelling deletion (MAIL), 1-4
Carriage return (MAIL}, 1-7

D
DECnet-VAX, sending mail via,
1-8' 1-9

Index-1

INDEX

Default
audit trail
SLP, 3-10
SUMSLP, 3-18
file specifications (SUMSLP),
3-16
file types (LBR), 7-4
message numbers (MSG), 8-7
symbol values (MSG), 8-9
transfer qualifiers (FLX), 2-4
through 2-5
Definitions (MSG), 8-4 through 8-11
DELETE command (MAIL), 1-4
DELETE DATA Librarian routine
{LBR), 7-21
DELETE KEY Librarian routine
(LBR), 7-22
Delete qualifier (FLX), 2-8
/DELETE qualifier
LBR, 7-7
MSG, 8-17
Delete qualifier (VFY), Fi-7
Deleting
index keys {LBR) , 7-22
RT-11 files using FLX, 2-12
source lines {SLP), 3-13
through 3-14
text records (LBR), 7-21
Deletion clashes (SUMSLP), 3-19
Deletion resumed using VFY, 6-3
/DENS qualifier (DSC), 4-7, 4-11
Density qualifier
DSC, 4-7, 4-11
FLX, 2-8
/DE qualifier
FLX, 2-7
VFY, 6-7
Device specifications
BAD, 5-4
DSC, 4-6
FLX, 2-2, 2-3
Devices
disk. See Disks
DOS-11, 2-1, 2-2
Files-11, A-1, A-2
recognized by DSC, 4-5
recognized by FLX, 2-1
RT-11, 2-1, 2-2
supported by VAX/VMS, A-1, A-2
tape. See Tapes
Diagnostic messages. See Error
messages
/D I qua 1 i f i e r (FL X ) , 2- 7 , 2- 9 ,
2-10
Directives (MSG), 8'-9, 8-10
DIRECTORY command (MAIL), 1-4
Directory listings displayed via
FLX, 2-9 through 2-11
DOS-11, 2-9 through 2-10
RT-11, 2-10 through 2-11

Disk Save and Compress Utilities,
4-1 through 4-33
invoking, 4-5, 4-6
terminating, 4-5, 4-6
Disks
backing up (DSC), 4-1 through
4-3, 4-9 through 4-13
bad block information, 4-3 through
4-4, 4-14 through 4-15 5-2
through 5-3
comparing to tape (DSC), 4-4,
4-7' 4-10' 4-13
compressing (DSC), 4-3
Files-11, A-2
RT-11 format (FLX), 2-1, 2-2
supported by VAX/VMS, A-2
Displaying directory listings
(FLX), 2-9 through 2-11
Distribution lists, sending mail
to, 1-9
Distribution medium, copying
(DSC) , 4-2
/DNS:n qualifier (FLX), 2-8
/DO qualifier (FLX), 2-4
DOS-11 devices supported by FLX,
2-1, 2-2
DSC, 4-1 through 4-33
invoking, 4-4, 4-6
terminating, 4-5, 4-6

E
Editing commands (SLP), 3-9
through, 3-11
Editing mail messages (MAIL), 1-8
/ED IT qua l i f i er (MA IL ) , 1- 8
End statement (MSG), 8-10
Error messages
BAD, 5-9 through 5-12
Defining (MSG), 8-4 through 8-9
DSC, 4-17 through 4-33
FLX, 2-12 through 2-17
LBR, 7-57 through 7-n8
MAIL, 1-10, 1-11
MSG, 8-18, 8-19
SLP, 3-19 through 3-23
SUMS LP, 3-24
VFY, 6-10 through 6-12
/ERROR qualifier (MSG), 8-9
EXIT command (MAIL), 1-5
Expressions {MSG), 8-5
/EXTRACT qualifier (LBR), 7-7,
7-12

F
Facility
definition (MSG), 8-5, 8-6
field (MSG), 8-2

Index-2

INDEX

Facility, (Cont.)
name (MSG) , 8-5, 8-6
number (MSG) , 8-3, 8-5, 8-6
/FACILITY qualifier (MSG), 8-17
/FA:n qualifier (FLX), 2-5, 2-6
FAO arguments {MSG), 8-3, 8-8
/FAO COUNT qualifier (MSG)
/FATAL qualifier {MSG), 8-9
/FB:n qualifier {FLX), 2-6
/FC qualifier (FLX), 2-8
FILE command {MAIL), 1-5
File
compression {DSC), 4-3
errors {VFY), 6-2
headers, integrity checked
{VFY) , 6-1 through 6-3
identifications, translating
{DSC), 4-15, 4-16
labels {DSC), 4-9
/FILE NAME qualifier (MSG),
8=12, 8-15
File precedence (SUMSLP), 3-19
Files,
editing with SLP, 3-1 through
3-15
editing with SUMSLP, 3-15
through 3-19
help (LBR), 7-13 through 7-17
mail message, 1-10
message source (MSG), 8-4
through 8-11
nonexecutable message (MSG),
8-13 through 8-17
Files-11 devices, A-1
File specifications
converting file identifications
into {DSC), 4-15, 4-H
FLX, 2-3
File Structure Verification
Utilities, 6-1 through 6-12
invoking, 6-5
terminating, 6-5
File Transfer Utility, 2-1 through
2-17
invoking, 2-2
terminating, 2-2
FIND Librarian routine, 7-23
FLX, 2-1 through 2-17
invoking, 2-2
terminating, 2-2
Format conversion using FLX, 2-4
through 2-5
Format of help files {LBR), 7-13
through 7-16
Format qualifiers (FLX), 2-4
through 2-5
Formatted ASCII arguments in
messages {MSG), 8-3, 8-8
Formatted ASCII mode {FLX), 2-5,
2-6

Formatted Binary mode (FLX) , 2-6
Formatting help files (LBR) ,
7-13 through 7-16
FORWARD command {MAIL), 1-5
1'"' re e qua 1 i f i e r {VFY) , 6- 7
/FR qualifier {VFY), 6-7
/FULL qualifier {LBR)' 7-8, 7-12

G
Generating messages (MSG), 8-1
through 8-19
GET HEADER Librarian routine
{LBR), 7-24
GET HELP Librarian routine
(LBR), 7-26
GET INDEX Librarian routine
(LBR), 7-28
$GETMSG system service (MSG), 8-1~
8-17
GET RECORD Librarian routine
(LBR), 7-30
/GLOBALS qualifier (LBR), 7-8
Global symbol table (LBR), 7-8,
7-9

H
HELP command {MAIL), 1-5
Help libraries (LBR), 7-1, 7-4,
7-8, 7-13' 7-26
Help modules {LBR), 7-13 through
7-17
/HELP qualifier {LBR), 7-8

IDENT field {MSG), 8-2
/IDENTIFICATION qualifier
on message definition (MSG),
8-8
on SET MESSAGE command (MSG),
8-17
/ID qualifier {FLX), 2-8
Ignore Bad Block File qualifier
(DSC), 4-7, 4-15
Image mode qualifier {FLX), 2-6
/IM: n qualifier (FLX), 2-6
Index file, 6-1, 6-4, 6-7, 6-8
placement, 4-8
Index, library (LBR), 7-2, 7-22,
7-28, 7-31 through 7-34,
7-37, 7-40 through 7-44
Informational messages
defining (MSG), 8--7, 8-9
See also Error Messages
/INFORMATIONAL qualifier (MSG),
8-9

Index·-3

INDEX

INI CONTROL Librarian routine
(LBR), 7-18, 7-31
Initializing volumes using FLX,
2-8, 2-10, 2-11
DOS-11 volumes, 2-10
RT-11 volumes, 2-11
INSERT KEY Librarian routine
(LBR), 7-33
/INSERT qualifier {LBR), 7-8,
7-12
Invoking
BAD, 5-3 through 5-4
DSCl, 4-5
DSC2, 4-5
DSC-2 {stand-alone), 4-~
FLX, 2-2
MAIL, 1-2
SLP, 3-1, 3-2
SUMSLP, 3-15, 3-16
VFYl, 6-5
VFY2, 6-5
I/O error messages {DSC), 4-31
through 4-33

K
Key lines in help files
7-13 through 7-17

(LBR),

L
Last-track devices {BAD), 5-2,
5-3
/LAST qua 1 i f i er (MA IL ) , 1- 8
LBN, see Logical block numbers
LBR, 7-1 through 7-68
LBR$CLOSE routine {LBR), 7-20
LBR$DELETE DATA routine (LBR),
7-21 LBR$DELETE KEY routine {LBR),
7-22 LBR$FIND routine (LBR), 7-23
LBR$GET HEADER routine (LBR),

7-24
LBR$GET HELP routine

(LBR),

7-25
LBR$GET INDEX routine (LBR),
7-28
LBR$GET RECORD routine {LBR),
7-30
LBR$INI CONTROL routine (LBR),
7-18, 7-31
LBR$INSERT KEY routine (LBR),
7-33
LBR$LOOKUP KEY routine (LBR),
7-34
LBR$0PEN routine (LBR), 7-18,
7-35

LBR$PUT END routine (LBR), 7-38
LBR$PUT-RECORD routine {LBR),
7-3"9"
LBR$REPLACE KEY routine (LBR),
7-40
LBR$SEARCH routine (LBR), 7-42
LBR$SET INDEX routine {LBR),

7-44
LBR$SET MODULE routine

(LBR),

7-45
L field (MSG), 8-2
Librarian Utility, 7-1 through
7-68
routines, 7-18 through 7-45
LIBRARY Command (LBR), 7-3
through 7-13
Library
header (LBR), 7-24
index (LBR), 7-2, 7-22, 7-28,
7-31 through 7-34, 7-37,
7-40 through 7-44
options, creating {LBR), 7-~,
7-35 through 7-37
types, creating (LBR}, 7-3,
7-4, 7-6
LIB$SIGNAL run-time procedure
{MSG), 8-14
Linking
programs containing calls to
Librarian routines, 7-18
the message object module (MSG),
8-13, 8-14
/LI qualifier
BAD, 5-6
FLX, 2-7
VFY, 6-7 through 6-8
Listing directives (MSG), 8-10
Listing file
SLP, 3-4, 3-5, 3-6, 3-9
SUMSLP, 3-16, 3-18
Listing qualifier
BAD, 5-6
FLX, 2-7, 2-9, 2-10
VFY, 6-7 through ~-8
/LIST qualifier
LBR, 7-9, 7-12, 7-13
MSG, 8-12
SLP, 3-n, 3-9
SUMS LP, 3-lf)
Literal directive (MSG), 8-9
8-10
Locating bad blocks using BAD,
5-1, 5-2
Locators (SLP}, 3-10, 3-11
Logical block numbers
calculating (DSC), 4-1(.)
specifyinq (BAD), 5-7
/LOG qualifier (LBR), 7-9, 7-12
LOOKUP KEY Librarian routine
(LBR), 7-34

Index-4

INDEX

/LO qualifier (VFY), n-8
Lost qualifier (VFY), n-3, n-8

/NAMES qualifier (LBR), 7-9
NEXT command (MAIL}' 1-n
/NOAUDIT TRAIL qualifier (SLP}'
3-6 /NOCHECKSUM qualifier (SLP}, 3-6,

M
Macro libraries (LBR), 7-1, 7-4,
7-9

3-8

/MACRO qualifier (LBR}, 7-9, 7-12
Magnetic tape devices. See Tapes
MAIL commands, 1-3
MAIL message files, 1-10
Mail Utility, 1-1 through 1-11
invoking, 1-2
terminating (exiting), 1-5
/MAN qualifier (BAD)' 5-n
through 5-7
Manual qualifier (BAD), 5-6
through 5-7
Manufacturer's Detected Bad
Sector File (BAD}, 5-2, 5-8
MDBSF (BAD}, 5-2, 5-8
Merging command files (SUMSLP),
3-19

Message
code (MSG), 8-3
compiler (MSG), 8-11 through

/N 0 FA c I LI TY qua 1 i f i e r (MSG ) ' 8 -1 7
/NOFILE NAME qualifier (MSG}, 8-12
/NOGLOBALS qualifier (LBR), 7-8
/NOIDENTIFICATION qualifier (MSG)'
8-17

/NOLIST qualifier
LBR, 7-9
MSG, 8-12
/N 0 LOG qua 1 i f i er ( LB R} ' 7 - 9
/NONAMES qualifier (LBR}' 7-9
Nonexecutable message files (MSG),
8-13 through 8-17
Non-last-track devices (BAD}, 5-2,
5-3

/NOOBJECT qualifier (MSG}, 8-12
/NOOUTPUT qualifier (SLP)' 3-7'
3-9

/NOREPORT qualifier (SLP}, 3-7
/NOSEVERITY qualifier (MSG), 8-17
/NOSQUEEZE qualifier (LBR), 7-11
/NOSYMBOLS qualifier (MSG), 8-13
/NOTAB FILL qualifier (SLP), 3-7
/NOTEXT qualifier
on MESSAGE command (MSG), 8-13
on SET MESSAGE command (MSG),

8-13
f i 1 e s (MA I L ) , 1-1 0
format (MSG), 8-2
number (MSG), 8-3, 8-7
object module (MSG), 8-11
through 8-16
source file (MSG), 8-4
through 8-11
symbol (MSG}, 8-4
Message-text field (MSG), 8-3

8-17

/NOTRUNCATE qualifier (SLP), 3-7
Number, message (MSG), 8-3, 8-7
/NU:n qualifier (FLX), 2-8, 2-11

Message Utility messages (MSG},
8-18' 8-19

Messages
defining (MSG}, 8-4 through

Object module libraries (LBR),

8-11

deleting (MAIL}, 1-4
diagnostic and error, see Error
Messages
editinq (MAIL}, 1-8
filing (MAIL}, 1-5
forwarding (MAIL), 1-5
help (LBR}, 7-13 through 7-17
ma i 1 (MA I L ) , 1-1 , 1- 4 th rough
1-10

sending (MAIL), 1-7 throuqh 1-9
MNT. See Module name table
Module name table (LBR), 7-8,
7-9

7-1' 7-4

Object module, message (MSG), 8-11
through 8-Hi
/OBJECT qualifier
LBR, 7-10
MSG, 8-12
Offsets for library header information (LBR), 7-24, 7-25
/ONLY qualifier (LBR)' 7-10'
7-13

Opening a l'ibrary (LBR}, 7-18,
7-35

OPEN Librarian routine (LBR),

/MODULE qualifier (LBR), 7-4,
7-12

Multiply-allocated blocks (VFY),
6-2, fi-4, 6-9

7-18' 7-35

Operators
MSG, 8-5
SLP, 3-9

Index-5

INDEX

Options for libraries (LBR), 7-6,
7-35 through 7-37
Output device specifications
DSC, 4-6
FLX, 2-2, 2-3
Output from VFY, 6-2 through n-3,
n-6, n-8
/OUTPUT qualifier
LBR, 7-10, 7-12
SLP, 3-7
SUMS LP, 3-16
Override qualifier (BAD), 5-8
/OVR qualifier (BAD)' 5-8

p
.PAGE directive (MSG), 8-10
Per image alteration of messages
(MSG), 8-15, 8-lli
Per process alteration of messages
(MSG), 8-ln through 8-18
Personal Mail Utility, 1-1 throuqh
1-11
invoking, 1-2
terminating (exiting), 1-5
PIP (Peripheral Interchange
Program), 6-3 through o-4
Pointers to message data (MSG),
8-15, 8-Hi
Precedence of command files
(SUMSLP), 3-19
/PREFIX qualifier (MSG)' 8-n
Primary index number, setting
(LBR), 7-44
PRINT command (MAIL)' 1-n
Priority of messages (MSG), 8-17
PUT END Librarian routine (LBR),
-7-38
$PUTMSG system service (MSG), 8-3
PUT RECORD Librarian routine
(LBR), 7-39

a
Qualifier lines in help files
(LBR), 7-14 through 7-17
Qualifiers:
BAD qualifiers, 5-~
DSC input qualifier, 4-7
DSC output file qualifiers, 4-7,
4-10 through 4-15
Facility definition qualifiers
(MSG), 8-6
FLX control qualifiers, 2-7
through 2-8
FLX transfer mode qualifiers,

2-s, 2-n

FLX volume format qualifiers,
2-4' 2-5
LIBRARY command qualifiers,
7-4 through 7-13
LIBRARY file qualifier, 7-4
MESSAGE command qualifiers (MSG)
8-12, 8-13
Message definition qualifers (MSG)
8-8, 8-9
REPLY command qualifiers (MAIL),
1-8
SEND command qualifiers (MAIL),
1-8
SET MESSAGE command qualifiers,
(MSG), 8-17
SLP qualifiers, 3-6 through 3-9
VFY file qualifiers, n-7

R
/RC:n qualifier (VFY), 6-·9
Read check qualifier (VFY), n-8
READ command (MAIL) , 1-6 through
1-7
Reading text records (LBR), 7-30
Rebuild qualifier (VFY), 6-4, 6-9
Recovery of hardware errors using
BAD, 5-8
Reenable audit trail operator
(SLP), 3-9
Regulating bad block information
(DSC), 4-3, 4-7, 4-14, 4-15
/REMOVE qualifier (LBR), 7-10,
7-12
Replace Bad Block File qualifier
(DSC), 4-7, 4-15
REPLACE KEY Librarian routine
(LBR), 7-40
/REPLACE qualifier (LBR), 7-11
Replacing source lines (SLP),
3-14 through 3-15
REPLY command (MAIL), 1-7
qualifiers, 1-8
/REPORT qualifier (SLP), 3-7
Restoring files marked for
deletion (VFY), 6-3 throuqh
6-4
Restoring volumes using DSC, 4-2,
4-9' 4-12
/RETRY qua 1 if i er (BAD) , .5-8
Return status codes (LBR), 7-18,
7-64 through 7-68
Rewind qualifier
DSC, 4-7, 4-11, 4-12
FLX, 2-8
Routines, Librarian (LBR), 7-18
through 7-45
/RS qualifier (FLX), 2-4, 2-5

Index-6

INDEX

Stand-alone DSC-2, 4-1, 4-2, 4-5,
4-6, 4-11
Storage bit map (VFY), 6-1, 6-4,
6-9
Subkeys (LBR), 7-14, 7-10, 7-17,
7-27
Success messages (MSG), 8-2, 8-7
8-8
/SUCCESS qualifier (MSG), 8-9
SUMSLP, 3-15 through 3-19, 3-24
command files, 3-17
editing commands, 3-17
input source file, 3-17
listing file, 3-16, 3-18
merging rules, 3-19
messages, 3-24
output file, 3-16, 3-17
qualifiers, 3-16
Suppressing
audit trail (SLP), 3-6
message fields (MSG), 8-2
8-3, 8-16 through 8-18
Switches. See Qualifiers
Symbol,
definition of global (MSG),
8-4, 8-9, 8-10
message (MSG), 8-4
/SYMBOLS qualifier (MSG), 8-13
/SYSTEM qualifier (MSG) , 8-6

RT-11 devices supported by FLX,
2-1, 2-2
/RT qualifier (FLX), 2-4, 2-5
Run-time, changing messages at
(MSG), 8-15 through 8-18
/RW qualifier (DSC), 4-7, 4-11,
4-12
/RW and /-RW qualifiers (FLX),
2-8

s
Scratch file (VFY), 6-6
SDBSF (BAD), 5-2, 5-8
SEARCH Librarian routine (LBR),
7-42
Searching for lost files (VFY),
6-3 through 6-4, n-9
/SELECTIVE SEARCH qualifier
(LBR) , -7-11
SEND command (MAIL) , 1-7 through
1-9
qualifiers, 1-8
SET INDEX Librarian routine
(LBR), 7-44
SET MESSAGE command (MSG), 8-16
through 8-18
SET MODULE Librarian routine
(LBR), 7-45
/SEVERE qualifier (MSG), 8-9
Severity
definition (MSG), 8-6, 8-7
field (MSG), 8-2
levels (MSG), 8-2, 8-7, 8-9
/SEVERITY qualifier (MSG), 8-17
Severity qualifiers on message
definitions (MSG), 8-9
/SHARED qualifier (MSG), 8-6
Single-disk systems and DSC, 4-8
SLP, 3-1 through 3-15, 3-19
through 3-23
command file, 3-3
editing commands, 3-9 through

3-11

input source file, 3-3
listing file, 3-4, 3-5, 3-6, 3-9
messages, 3-19 through 3-23
output file, 3-4, 3-5, 3-7, 3-9
qualifiers 3-6 through 3-9
Soft errors (BAD), 5-8
Software Detected Bad Sector File
(BAD), 5-2, 5-8
Source file, message (MSG) , 8-4
through 8-11
Specifying message numbers (MSG),
8-7
/SP qualifier (FLX), 2-8
/SQUEEZE qualifier (LBR), 7,,ll

/TAB_FILL qualifier (SLP), 3-7
Tapes
backing up disks onto (DSC),
4-2, 4-3, 4-9 through 4-13
comparing disks to (DSC), 4-4,
4-7, 4-10, 4-13
DOS-11, 2-1, 2-2
recording density, 2-8, 4-7,
A-1
restoring disks from (DSC),
4-9, 4-12
supported by VAX/VMS, A-1
Terminating
BAD, 5-4
DSCl, 4-5
DSC2, 4-5
DSC-2 (stand-alone), 4-6
FLX, 2-2
MAIL, 1-5
SLP, 3-9
SUMSLP, 3-17
VFYl, n-5
VFY2, 6-5
Terminator (SLP), 3-9
Text libraries, 7-2, 7-4, 7-8,

Index-7

7-11

INDEX

/TEXT qualifier
LBR, 7-11, 7-12
on MESSAGE command (MSG), 8-13
on SET MESSAGE command (MSG),
8-17
Text records, manipulating (LBR),
7-21, 7-26, 7-30
.TITLE directive (MSG), 8-10
Translating file identifications
using DSC,
4-15, 4-10
Transporting Files-11 volumes
(DSC), 4-4, 4-5
/TRUNCATE qualifier (SLP), 3-7

u
/UI qualifier (FLX) ,, 2-8
/UPDATE qualifier
BAD, 5-8
SUMSLP, 3-15, 3-17
Update qualifier (VFY), 6-4, 6-9
/UPD qualifier (VFY), n-9
/USER_VALUE qualifier (MSG), 8-8

v
Validity checking (VFY), 6-1
through 6-3
/VE qualifier (DSC), 4-7, 4-10,
4-11
Verify qualifier (DSC), 4-7, 4-10,
4-11
Verifying volumes (VFY), f)-1
through 5-3

VFY, 6-1 through 6-12
invoking, 6-5
terminating, 6-5
Volume format qualifiers (FLX),
2-4' 2-5
Volumes,
block-stru~tured, 5-1
disk, backing up (DSC), 4-1
through 4-3, 4-9 through 4-13
disk, comparing (DSC), 4-4, 4-7,
4-10, 4-13
disk, compressing (DSC), 4-3
Files-11, A-1, A-2
readabi 1 i ty check (VFY), 6-8, 6-9
restoring (DSC), 4-2, 4-9, 4-12
transferring contents of (FLX),
2-9
validity check (VFY), 6-1
through 6-3
·
verification (VFY), 6-1 through
6-3

w
Warning messages
defining (MSG), 8-2, 8-7, 8-9
See also Error Messages
/WARNING qualifier (MSG)' 8-9
/WIDTH qualifier (LBR), 7-11,
7-13
Writing text records (LBR), 7-39

z
/ZE qualifier
2-11

Index-8

(FLX), 2-8, 2-10,

VAX-11 Utilities
Reference Manual
AA-H781A-TE
READER'S COMMENTS

NOTE:

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require a written reply and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.
_____ ,,.

_____ - - - - -

-- --·

-~-------

II)

- .

-·--·-----·

c:
0

Did you find errors in this manual?
page number.

---------------------·--

If so, specify the error and the

---- _,,____ - - - - - - - - - - - -

----------~--~~------

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify>----·-··----------------·-------·-----·--------

Name

- - - - - - - - - _______ Date _____,-···-----------------

Organization~-~--

Street _ _ _ _ _ _~~___ State _ _ _ __

Zip Code _ _ _ _~~or
Country

Do Not Tear - Fold Here and Tape -

No PostagE
Necessary
if Mai led in 1
United Stat1

[

-------------·

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
---~

....-

..,__ _.,,......,...._,__.,_.,...,,. .

.,.._~~=--...,...._.~

POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS

TW/A14

DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876