Digital PDFs

AA-D781C-TE

March 1980

91 pages

Original

3.9MB

Document:	VAX-11 Record Management Services User’s Guide
Order Number:	AA-D781C-TE
Revision:	000
Pages:	91
Original Filename:

OCR Text

VAX-11
Record Management Services
User's Guide
Order No. AA-D781C-TE

March 1980

This document contains detailed information on using the capabilities of
VAX-11 Record Management Services efficiently. Typical examples are provided to illustrate programming concepts.

VAX-11
Record Management Services
User's Guide
Order No. AA-0781 C-TE

SUPERSESSION/UPDATE INFORMATION: This document supersedes
the document of the same name,
Order No. AA-D781 B-TE,
published February 1979.
OPERATING SYSTEM AND VERSION:

VAX/VMS V2.0

SOFTWARE VERSION:

VAX/VMS V2.0

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, August 1978
Revised, January 1979
Revised, 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.

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

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

DECsystem-lo
DECtape
DIBOL
EDU SYSTEM
FLIP CHIP
FOCAL
IND AC
LAB-8
DECSYSTEM-20
RTS-8
VMS
!AS
TRAX

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

CONTENTS

Page
v

PREFACE
CHAPTER

CHAPTER

FILE GUIDELINES: DETERMINE YOUR NEEDS

1-1

1.1

THE RATIONALE FOR RECORD MANAGEMENT

1-1

VAX-11 RMS STRUCTURES AND INTERFACE

2-1

2.1
2.2

USER CONTROL BLOCKS
VAX-11 RMS ROUTINES

2-1
2-2

SPECIFYING THE FILE TO BE PROCESSED

3-1

FILE SPECIFICATIONS
3.1
Network Nodes
3. l . l
Devices
3. l . 2
Directories
3. l . 3
Alphanumeric Character String Format
3.1.3.l
UIC Format
3.1.3.2
Subdirectories
3.1.3.3
3.1.4
File Names, File Types, and Version
Numbers
3. l. 5
Wild Card Characters
3.2
DEFAULT FILE SPECIFICATIONS
3.3
LOGICAL NAMES
3.3.l
Logical Name Tables
Logical Name Translation and Recursion
3.3.2
Defaults for File Names
3.3.3
Bypassing Logical Name Translations
3.3.4
Default Process Logical Names
3.3.5
3.4
PROCESS-PERMANENT FILES
CHAPTER

CHAPTER

PROCESSING FILES WITH SEQUENTIAL RECORD
ACCESS MODE

3-1
3-2
3-3
3-4
3-4
3-4
3-4
3-5
3-8
3-8
3-10
3-11
3-11
3-12
3-13
3-13
3-14
4-1

4.1
THE USE OF SEQUENTIAL FILE ORGANIZATION
4.1.l
Reading Records
4.1.2
Creating a Sequential File
4.1.2.l
Dynamically Creating a Sequential File
4.2
THE USE OF RELATIVE FILE ORGANIZATION
4.2.l
Reading a Relative File
Creating a Relative File
4.2.2
Dynamically Creating a Relative File
4.2.2.l
THE USE OF INDEXED FILE ORGANIZATION
4.3
Reading an Indexed File
4.3.l
4.3.2
Creating an Indexed File

4-1
4-1
4-4
4-5
4-7
4-7
4-8
4-9
4-10
4-11
4-14

PROCESSING FILES WITH "RANDOM RECORD ACCESS

5-1

5.1
5. l. l

RANDOM ACCESS TO SEQUENTIAL FILE ORGANIZATION
Random Read of a Record

5-1
5-1

iii

CONTENTS

Page
5.2
5.2.1
5.3
5.3.1
APPENDIX A
A. l
A.2
A.3
A.4
APPENDIX B
B.l
B.2

RELATIVE FILE ORGANIZATION
Random Read of a Record in the Relative
File Organization
INDEXED FILE ORGANIZATION
Random Read of a Record in the Indexed
File Organization

5-9

PROGRAM EXAMPLES

A-1

SEQUENTIAL RECORD ACCESS MODE -- SEQUENTIAL
FILE ORGANIZATION
RANDOM RECORD ACCESS -- RELATIVE FILE
ORGANIZATION
SEQUENTIAL RECORD ACCESS MODE -- INDEXED FILE
ORGANIZATION
RANDOM RECORD ACCESS MODE -- INDEXED FILE
ORGANIZATION

5-6
5-h
5-9

A-2
A-6
A-10
A-14

US ING THE RMS FILE ANALYZER

B-1

USES OF RMSANLZ
OPERATING RMSANLZ

B-1
B-2

INDEX

Index-1

FIGURES
FIGURE

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

Program to Count Records in a Sequential
File
Program to Copy a Sequential File
Program to Copy a Sequential File, Setting
the Output Control Blocks Dynamically
Creating a Relative File
Creating a Relative File Dynamically
Program to Count Records in an Indexed File
Program to Create an Indexed File by Copying
an Existing File
Random Read of a Sequential File
Random Read of a Relative File
Random Read of an Indexed Fi le
Sample File Attribute Listing
Sample Key Information Listing
Sample Key Analysis Listing

4-3
4-6
4-8
4-9
4-10
4-13
4-17

5-4
5-7
5-12
B-2
8-3
B-4

TABLES
TABLE

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

File Organizations: Advantages and
Disadvantages
Control Blocks
Macro Instructions for Run-Time Processing
Device Names
Default File Types
File Specification Defaults
Default Process Logical Names

1-2
2-2
2-3
3-3
3-5
3-9
3-13

PREFACE

MANUAL OBJECTIVES

The intent of this manual is to present some of the different uses of
the VAX-11 Record Management Services (VAX-11 RMS), so you can tailor
the various components and routines to suit your record management and
record processing needs.

INTENDED AUDIENCE

This manual is intended for VAX/VMS users who want to develop a basic
understanding of how to use VAX-11 RMS I/O routines within their
programs. VAX-11 MACRO programmers generally use the VAX-11 RMS
routines
directly
within
their programs.
High-level language
programmers normally use the I/O facilities of their particular
language to utilize a subset of VAX-11 RMS facilities. However, they
may also use VAX-11 RMS directly through a call facility within their
language.
This manual is aimed at VAX-11 MACRO programmers. It is assumed that
you are familiar with and understand the VAX-11 MACRO conventions for
constructing symbols and the use of
numbers,
operators,
and
expressions.

STRUCTURE OF THIS MANUAL

The information in this document is structured as follows:
Chapter 1 provides an overview of the salient features of the data
record
file organizations that can be created, displayed, and
maintained by using VAX-11 RMS. This information will help you to
determine the type of file organization best suited to your data
record management requirements.
Chapter 2 describes the VAX-11 RMS routines and the user control
blocks defined within your program, which are used to communicate
between your program and the VAX-11 RMS routines.
Chapter 3 describes file
specification defaults.

specification

syntax

and

the

file

Chapter 4 describes how you create and process data record
sequential access mode with three file organizations.

files

Chapter 5 describes how you create and process .data
using random access mode.

files

Appendix A provides additional programming examples.
Appendix B describes the RMS File Analyzer.

record

ASSOCIATED DOCUMENTS

A prerequisite to this manual is the Introduction to VAX-11 Record
Management Services M9J}_y_~_!, which describes in de ta i 1 the concepts of
file organization, record access modes, record formats, and other
concepts
required
for
your understanding of VAX-11 RMS file
construction. You should have available a copy of the VAX-11 Record
Management Services Reference ~a!!!:IE._!.
This document cont a ins the
complete description of the components of VAX-11 RMS, and therefore
constitutes a source reference for the materials presented in this
user's guide.
Other manuals allied to this document are:
•

VAX/VMS Primer

•

VAX-11 MACRO

•

VAX-11 BLISS Language --~-~~-~~_ence Manual

~aEgl.!~9-~---~~~erence

Manual

SUMMARY OF TECHNICAL CHANGES

This manual has been revised to reflect VAX-11 RMS support
card characters and uppercase translation of logical names.

vii

for

wild

CHAPTER 1
FILE GUIDELINES: DETERMINE YOUR NEEDS

The VAX-11 Record Management Services (VAX-11 RMS) are system routines
that provide an efficient and flexible means of accessing files and
their records. The VAX-11 RMS routines speed up and simplify the task
of program development.

1.1

THE RATIONALE FOR RECORD MANAGEMENT

As a user writing application programs, you need to create programs
that will
(1) accept new input, (2) read or modify data, and/or (3)
produce output in some meaningful form. These programs can be, at
times, somewhat difficult to produce, because the operations required
in handling the data can be complex.
However, many of these
operations are basically the same, with only minor modifications
needed depending on the operation.
Therefore, generalized routines
that encompass a wide variety of functions can be very useful to you
in dealing with your file and record management programming needs.
VAX-11 RMS provides such generalized routines.
VAX-11 RMS routines are an integral part of the operating system;
they are always there. You need not perform any special linking or
declaring of global entry points to access the routines since a simple
reference to a routine generates the appropriate call. Calls to
VAX-11 RMS routines are consistent with the VAX/VMS calling standard;
arguments are passed and results and errors are returned in the
standard VAX/VMS fashion.
Because the file organization is fixed for the life of the file, it is
very important that you decide, before you begin to write your
program, which file organization best meets your requirements.
The
following questions should help you determine your file organization
requirements.
•

How will the records be accessed? Will the whole file or only
selected records be processed? Will the records be accessed
randomly? Will the records be accessed by other nodes in a
network?

•

What kind of record maintenance is needed?
updated, added, or deleted?

•

What is the record format? How large are the records;
they all the same size? What is their maximum size?

•

What is the total size of the file?
it be extended?

1-1

Must

records

be
are

Is this size fixed or can

FILE GUIDELINES: DETERMINE YOUR NEEDS
will the file reside? Will the medium be tape, disk, or
• Where
cards.
Will the file be written to a line printer or
terminal?
As these questions indicate, many issues affect your choice of file
organization.
Often, the choice is not clear-cut. Table 1-1 lists
some of the advantages and disadvantages of the three types of file
organizations: sequential, relative, and indexed.
Table 1-1
File Organizations: Advantages and Disadvantages
File
Organization
Sequential

Disadvantages

Advantages

Uses disk and memory
efficiently:
minimum disk overhead,
block-boundary crossing

All-0ws sequential
access only
for some high-level
languages

Provides optimal usage
if the application
accesses all records
sequentially on each run

Allows records to be
added only to end of
file

Provides flexible record
format
Allows data to be stored
on many different types
of media, in a deviceindependent manner
Allows easy file
extension
Relative

Allows sequential and
random access by record
number for all
languages
Allows random record
deletion and insertion
Allows records to be
read- and write-shared

Allows sharing by
multiple, concurrent
users, but only with
user's implemented
synchronization.
(The exception is
512-byte fixed-length
records; VAX-11/RMS
manages the
synchronization for
such files).
Allows data to be
stored on disk only
Requires that programs
contain a record cell
for each relative
record number
allocated; therefore,
files may be
sparsely populated
Requires that record
cells be the same size
Allows record
insertion only to
empty cells (or
at the end of
the file)
(continued on next page)

1-2

FILE GUIDELINES: DETERMINE YOUR NEEDS
Table 1-1 (Cont.)
File Organizations: Advantages and Disadvantages

..----------------------------......------,-File
Organization
Indexed

Advantages

Disadvantages

Allows sequential and
random access by key
value for all languages
Allows random record
deletion and insertion
Allows records to be
read- and write-shared
Allows variable-length
records to change length
on update
Allows easy file
extension

1-3

Allows data to be
stored on disk only
Requires more disk
space
Uses more of the
central processing unit
to process records.
Generally requires
mulitple disk accesses
to prrocess a record.

CHAPTER 2
VAX-11 RMS STRUCTURES AND INTERFACE

The facilities of VAX-11 Record Management Services (VAX-11 RMS) are
available at run time through the calling of record management
procedures. Communication with the VAX-11 RMS routines is by means of
user control blocks defined within your program.
This chapter
provides an introduction to these routines and control blocks, and the
macro instructions that facilitate their use.

2.1

USER CONTROL BLOCKS

VAX-11 RMS uses data structures called control blocks
between your program and the VAX-11 RMS routines.

communicate

The VAX-11 RMS routines also create their own
internal
data
structures, reflecting the information in your control blocks. These
internal data structures reside in the process control region, in what
is called the I/O segment.
You set up fields in the control blocks to reflect exactly what
operations you want to perform, and then call the routine. The
routine uses these fields as input to perform the requested action
and, as necessary, uses these fields again to return status and other
related information. The amount of information your program exchanges
with VAX-11 RMS (both as input and output) depends on the nature of
your request and the file attributes.
Table 2-1 lists the control blocks
interface with VAX-11 RMS.

that

are

part

your

program

You must allocate space for these control blocks within your program.
You can do this either at assembly time or run time. VAX-11 RMS
provides macro instructions for the assembly-time allocation and
initialization of the control blocks, shown in the Macro Name column
of Table 2-1. At run time, you can directly manipulate the control
blocks through either the defined symbolic offsets or the "store"
macro instructions. For efficiency, and to prevent a warning message
from the assembler, align each control block on a longword boundary.
In general, you must allocate one File Access Block (FAB)
for every
open file in your program, and one Record Access Block (RAB) for each
individual record stream connected to a FAB.
(More than one RAB can
be connected to each FAB simultaneously.) The Extended Attribute
Blocks (XABs) and the Name Block (NAM) are optional, depending on
whether you need the information they provide and the functions they
perform.

2-1

VAX-11 RMS STRUCTURES AND INTERFACE

Table 2-1
Control Blocks

Structure

Macro
Name

Function

File Access
Block (FAB)

Describes a file and contains
file-related information

$FAB

Record Access
Block (RAB)

Describes a record and contains
record-related information

$RAB

Extended
Attribute
Blocks (XAB)

Contain file attribute information
beyond that in the File Access
Block

$XABxxx 1

Name Block (NAM)

Contains file specification
information beyond that in the
File Access Block

$NAM

1. The variable xxx is a 3-character XAB-type specification.

2.2

VAX-11 RMS ROUTINES

The VAX-11 RMS routines execute in executive mode.
VAX-11 RMS
protects its internal data structures and buffers from destruction by
user programs, and ensures that files will be left in an orderly
state.
When your program exits, an I/O rundown routine closes all
files, writing buffers and file attributes as required, even when the
exit is the result of a severe error.
VAX-11 RMS routines are integrated in a straightforward manner.
Within your program, you place a call to the appropriate routines.
Generally you make these calls with run-time macro instructions.
At
run time, the expanded code of these macro instructions causes calls
to be made to the appropriate routines, which refer to the appropriate
control blocks.
These calls are consistent with the VAX-11 calling
standard. You can specify the parameters with keywords; you can list
them in any order or omit the keywords entirely.
When you call a routine, you set up an argument list to define the
associated control block (FAB or RAB) and any optional completion
routines to be called if an error occurs.
The operations performed by VAX-11 RMS routines are classified as
either file oriented or record oriented, requiring the address of a
FAB and RAB respectively as the control block argument in a call to
any of them.
Table 2-2 summarizes the essential
processing.

macro

2-2

instructions

for

run-time

VAX-11 RMS STRUCTURES AND INTERFACE

Table 2-2
Macro Instructions for Run-Time Processing
Category

File
Processing

Macro Name

Service

$CREATE

Creates and opens a new file of any organization
(sequential, relative, or indexed)

$OPEN

Opens an existing file and initiates file processing

$DISPLAY

Returns the attributes of a file to user program

·------

$EXTEND

Extends the allocated space of a file
Terminates file processing and closes the file

-----t-

$CLOSE

--·--·- --------

·-----·
$ERASE

Deletes a file and removes its directory entry
-

Record
Processing

$GET

Retrieves a record from a file

$PUT

Writes a new record to a file

r------------

$UPDATE

----------Rewrites an existing record in a file

$DELETE

Deletes a record from a relative indexed file

$FIND

Locates and positions to a record and returns its RFA

$CONNECT

Connects record stream to a file

--·-·---------~

-- ·--·~- ..

--------t-

$DISCONNECT
----+·

$RELEASE

··-----

·-----

~--

-- Disconnects a record stream from a file
-~·-

----

-----·----- -------- ----

Unlocks a record by its RF A
----·

SFREE

Unlocks all previously locked records

$WAIT

Determines the completion of an asynchronous record
operation

$REWIND

Positions to the first record of a file

$TRUNCATE

Truncates a sequential file

$FLUSll

Write modified 1/0 buffers and file attributes

------~·-----

·---------

---

-------· - -·

-----------.--- -- -----t-·
.

SNXTVOL

Causes processing of a magnetic tape file to continue to
the next volume of a volume set
F·

Block 1/0

--~-".

$READ

Retrieves a specified number of bytes from a file

$WRITE

Writes a specified number of bytes to a file

-------.-

$SPACE

---·- -

Spaces forward or backward in a file
---

---~:..t:=··

File
Naming

----

----- - - - - - - - - -

$ENTER

Enters a file name into a directory

$PARSE

Parses a file specification

$REMOVE

Removes a file name from a directory

$RENAME

Assigns a new name to a file

--~

--·-

Searches a directory for a file name
--- ----- ,_

-- --- -------------

2-3

----------

---- - - - -

$SEARCH

--- -

CHAPTER 3
SPECIFYING THE FILE TO BE PROCESSED

A file is a logically related collection of records.
All the
information that the operating system reads and writes on behalf of
users' requests is defined in terms of files and records.
File processing is influenced by the hardware device that performs the
actual data transfer (reading or writing). Devices are classified as:
•

Mass storage devices

•

Record-oriented devices

Mass storage devices provide a way to save the contents of files on a
magnetic medium, called a volume. Files that are thus saved can be
accessed at any time and updated, modified, or reused.
Disks and
tapes are mass storage devices.
Record-oriented devices read and/or write only single physical units
of data at a time, and do not provide for permanent storage of the
data. Terminals, printers, and card readers are record-oriented
devices.
Printers and card readers are also called unit record
devices. In certain cases, magnetic tapes are treated as record
oriented devices.

3.1

FILE SPECIFICATIONS

File specifications provide the system with
needs to identify a unique file or device.

all

the

information

File specifications have one of the following formats:
•

node::device: [directory]filename.type;version

•

node::"foreign-file-spec"

•

node::"task-spec"

You must use the punctuation marks and brackets to separate the fields
of the file specifi6ation. Either matching square brackets or angle
brackets may delimit the directory specification.
The type and
version specifications may be separated by either a period (.) or a
semi-colon (;). The fields and their contents are listed below.

3-1

SPECIFYING THE FILE TO BE PROCESSED
Field

Contents

node
device
directory
filename
type
version

Node name and optional access control string
Device name
Directory name and optional subdirectory names
File name
File type
File version number
Designates a program to communicate with on a remote
node or designates a file specification that is not to
be parsed locally.

Directory names, file names, file types, and version numbers apply
only to files on disk or tape devices. For record-oriented devices
(terminals, printers, and card readers), only the device name field of
the file specification is required; fields following it are ignored.
Blanks, tabs, and null characters are accepted but ignored in file
specifications.
You may use wild card characters in file specifications.
These are
more fully discussed in Section 3.1.5. The ellipsis [ ••• ) and minus
sign [-] wild card characters can be used only in the directory name
field of a file specification. The asterisk (*) and percent sign (%)
wild card characters can be used in the following fields of a file
specification:
•

Directory name

•

File name

•

File type

•

File version number

Appendix C of the VAX-11 Record Management Services Reference Manual
contains a rigorous explanation of the entire syntax for file
specifications. The following sections, however, provide sufficient
information for you to have a basic understanding of how to supply
file specifications.

3.1.1

Network Nodes

Each computer system in a DECnet network is uniquely identified by a
1- through 6-alphanumeric character node name. Optionally, a node
name may be followed by an access control string encl9sed in quotes
(") and the entire node specification is identified by two colons
(::). An access control string consists of a username, password, and
optional account name separated from each other by one or more spaces
and/or tabs. Its total length is 3 through 42 characters.
You
include an access control string in a node specification when you want
to login at the remote node as a specific user for the file access
operation.
If you omit the access control string, the default DECnet
account (if established) is used. The following are examples of node
specifications.
BOSTON::
BOSTON"COWENS CELTICS"::
BOSTON"COWENS CELTICS NBA"::
In addition, you may define a logical name for a node specification
and then use it in file specifications. Logical names are described
in detail in Section 3.3.

3-2

SPECIFYING THE FILE TO BE PROCESSED
For complete details on the use of node name specifications,
DECnet-VAX User's Guide.

3 .1. 2

see

the

Devices

Each physical hardware device
identification, in the format:

the

system

has

unique

devcu:
In this format, dev is a mnemonic for the device
controller designation and u is a unit number.

type,

Table 3-1 lists the valid device types and their mnemonics.
The controller and unit number identify the location of the actual
device within the hardware configuration of the system. Controllers
are designated with alphabetic letters A through z. Unit numbers are
decimal numbers from 0 through 65535.
The maximum length of the device name field, including controller and
unit number, is 15 characters. You must follow a device name with a
colon(:).
A complete device name specification is called a physical device name.
You can specify physical device names to indicate an input or output
device for a program. Or, you can equate a physical device name to a
logical name and use a logical name to refer to a device. Logical
na-mes are described in detail in Section 3.3-.
Table 3-1
Device Names
Mnemonic

Device Type

1---------+-----------·------------~-------l

CR
CS
DB
DD
DL
DM
DR
DY
LA
LP
MB
MS
MT
NET
OP
RT
TT
XA
XF
XJ
XM

Card Reader
Console Storage Device
RP04, RP05, RP06 Disk
TU58, Cassette Tape
RL02, Cartridge Disk
RK06, RK07 Cartridge Disk
RM03, RM05 Disk
RX02 Floppy Diskette
LPAll-K Laboratory Peripheral Accelerator
Line Printer
Mailbox
TS-11 Magnetic Tape
TE16, TU45, TU77 Magnetic Tape
Network Communications Logical Device
Operator's Console
Remote Terminal
Interactive Terminal
DRll-W General Purpose DMA Interface
DR32 Interface Adapter
DUPll Synchronous Communications Line
DMCll Synchronous Communications Line

3-3

SPECIFYING THE FILE TO BE PROCESSED
3.1.3

Directories

A user file directory (UFD) is a file that lists the identifications
and locations of files on a disk device that belong to a particular
user. The UFD is listed in the volume's master file directory (MFD).
The MFD is the root of the volume's directory structure, and also
lists the reserved files for the volume.
Directory names apply to files on magnetic tape and disk devices.
They are expressed in one of three formats where each format requires
that you enclose the directory name in either square brackets ([ and
]) or angle brackets (< and >). The closing bracket must match the
opening bracket. The formats for specifying directory names are as
follows:
a 1- through 9-alphanumeric character string representing a
• As
UFD name.
a two-part number separated by a comma (,) in the format of
• As
a user identification code (UIC).
a UFD name followed by one or more subdirectory names, each
• As
preceded· by a period (.). Each subdirectory name represents a
unique subdirectory level of the UFD and has the
as a UFD name.

same

syntax

3.1.3.1 Alphanumeric Character String Format - The character string
used to specify a UFD can be the same as your user name or account
name, or any valid character string that you request or the system
manager assigns you.
For example, if you specify a directory as
[OlOPAY] the directory OlOPAY.DIR;l is searched.
(DIR is the file
type for a directory, and 1 is the version number.)

3.1.3.2 UIC Format - You can refer to a UFD in a format similar to
that for a UIC: for example, [abc,xyz], where "abc" is a group number
and "xyz" is a member number.
To specify a UFD in this format,
separate the group number from the member number with a comma. If you
specify less than three characters for either "abc" or "xyz", they are
left zero-filled. Therefore, if you specify a UFD in a urc format as
[26,1], the directory searched is 026001.DIR;l.
UIC directories have corresponding names in alphanumeric format.
The
group and member numbers are each left zero-filled (if necessary).
For example:
[122001]
The directory name for the UFD specified in this command is equivalent
to the specification [122,1].
A directory in this format is usually owned by a user with a
corresponding urc.
However, this may not always be the case, as UIC
and directory ownership are independent.

3.1.3.3 Subdirectories - When UFDs are referenced using the character
string format,
further hierarchical levels of directories can be
expressed as subdirectories. A subdirectory level is expressed by
adding a period (.) to the character string for the UFD, followed by

3-4

SPECIFYING THE FILE TO BE PROCESSED

the specification for the subdirectory. For example, [OlOPAY.DED]
is
the specification for the UFO named OlOPAY.DIR;l and a subdirectory of
DED. DIR; 1.
The maximum number of directory levels is eight: one UFD and seven
subdirectories.
(Combined with the master file directory, this is, in
effect, a 9-level hierarchy.)
In
the
directory
specification
[OlOPAY.DED.YTD],
OlOPAY
is the UFO, DED is the first level
subdiiectory, and YTD is the second level subdirectory.
There is no maximum number of different hierarchies of directories you
can create or access.
The master file directory is created when the volume is initialized.
Subdirectories and UFOs are created with the CREATE command using the
DIRECTORY qualifier.l

3.1.4

File Names, File Types, and Version Numbers

File names, file types, and version numbers
within directories.

uniquely

identify

files

A file name is a 1- through 9-alphanumeric character string that
identifies a file. When you create a file, you can assign it a file
name that is meaningful to you.
A file type is a 1- through 3-alphanumeric character string that
extends a file name. usually, a file type name is chosen to suggest
the contents of the file.
File types must be preceded with a period (.).
The system uses a set of standard file types, by convention, to
identify various classifications of files, and to provide default file
types in many commands. Table 3-2 is a list of file types.
Table 3-2
Default File Types

. - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - -- ------------··
File Type

Contents

1-------------1------------·----·- -·· ···-·--· ·-·

ANL

Output file for the ANALYZE command

BAS

Input source file for the VAX-11 BASIC compiler

B2S

Input
source
file
BASIC-PLUS-2/VAX compiler

for

the

PDP-11

B32 or BL!

Input source
compiler

the

VAX-11

BLISS-32

CBL

Input file containing source statements for
PDP-11 COBOL-74/VAX compiler

file

for

the

(continued on next page)
1. See the VAX/VMS Command Language User's Guide for an explanation of
this command and any others that appear throughout this manual.

3-5

SPECIFYING THE FILE TO BE PROCESSED
Table 3-2 (Cont.)
Default File Types
File Type

Contents

CMD

Compatibility mode indirect command file

COB

Input file containing source statements for
VAX-11 COBOL-74 compiler

COR

Input source file for the
compiler

COM

Command procedure file to be executed with the @
(execute procedure) command, or to be submitted
for batch execution with the SUBMIT command

DAT

Input or Output data file

DIF

Output listing
command

DIR

Directory File

DIS

Distribution list for the MAIL command

DMP

Output form the DUMP command

EDT

Initialization command input file for EDT

EXE

Executable program image created by the linker

FOR

Input file containing source statements for
VAX-11 FORTRAN compiler

FTN

Compatibility Mode FORTRAN IV PLUS source file

HLB

Help text library file

HLP

Help text source file

JNL

Journal file output form PATCH utility

JOU

Journal file/audit trail from EDT

L32

Precompiled Librrary for VAX-11 Bliss-32

LIB

Input file containing VAX-11 COBOL-74 source
Statements to be copied into another file during
compilation

LIS

Listing file created by a language compiler or
assembler;
default input file type for PRINT
and TYPE commands

LOG

Batch job output file

LST

Compatibility mode listing file

MAC

MACR0-11 source file

created

PDP-11

the

CORAL

the

nn/VAX

DIFFERENCES

the

{continued on next page)

3-n

SPECIFYING THE FILE TO BE PROCESSED
Table 3-2 (Cont.)
Default File Types
File Type

Contents

MAI

Mail message file

MAP

Memory allocation map created
invoked by the LINK command

MAR

VAX-11 MACRO source file

MDL

Maynard
Definition
Language
independent structure definitions)

MLB

Macro library

NEW

Any new source file

OBJ

Object file created by a
assembler

ODL

Overlay descriptor file

OLB

Object module library

OLD

Any old source file

OPT

Options for input to the LINK command

PAR

A SYSGEN parameter file

PAS

Input file containing source statements for
VAX-11 PASCAL compiler

the

R32 or REQ

VAX-11 BLISS-32
compilation

for

STB

Symbol table file created by the linker

SYS

System image

TEC

TECO indirect command input file

TLB

Text library

TMP

Temporary file

TMx

SOS temporary file ("x" is a digit)

TXT

Input file for text libraries or output file for
mail command

UPD

Update file of changes for a VAX-11 source
program; also input to the SUMSLP editor

source

the

(Language-

language

file

linker,

compiler

required

Version numbers are decimal numbers from 1 through 327~7 that
differentiate between versions of a file. When you update or modify a
file, the system saves the original version for backup and increments
the version number of the modified file by 1.
Version numbers must be preceded with a semicolon (;) or a period (.)

3-7

SPECIFYING THE FILE TO BE PROCESSED
3.1.5

Wild Card Characters

As noted in the VAX/VMS Record Management Se~yices Reference Manual,
wild card characters can be used in the directory name, file name,
file type, and file version number fields of a file specification,
when given to a program designed to accept them. One purpose of wild
card characters is to refer to a group of files by a more general file
specification,
rather
than
by
each
of
the
specific file
specifications. There are four characters (or strings of characters)
that can be used as wild card characters. These are the asterisk (*),
the percent sign (%), the ellipsis ( ••• ), and the minus sign (-).
An asterisk is used to match the missing component of a file
specification with an alphanumeric character string of any length
(including the null string). A percent sign is used to match any
single alphanumeric character in that particular position (the null
string does not match). The asterisk and the percent sign can be
combined in many ways. For example, the sequence:
A*E%B*.B*;*
matches a group of file specifications in which the file name starts
with an "A" followed by a string of zero to "n" characters, followed
by an "E", followed by a single character, followed by a "B", followed
by a string of zero to "n" characters. The file type begins with a
"B" and is followed by a string of zero to two characters.
Finally,
the version number in this group will be any and all versions of that
file, beginning with the highest version number.
The ellipsis and minus sign wild card characters are aids to
searching, or traversing, directory hierarchies. Both the ellipsis
and the minus sign allow you to refer to directori&s in a relative
positional sense, rather than by an absolute name for the first
directory or group of directories. The ellipsis enables you to select
files from all directory levels from a specified level downward. The
minus sign, on the other hand, enables you to search up the hierarchy,
rather than down.
A single minus sign will send the search back up
one level from the current default directory level.

3.2

DEFAULT FILE SPECIFICATIONS

Defaults are valuable because they are easy to use, and they let you
enter as short a file specification as possible. The less you enter,
the less chance you have of making a syntax error, or an incorrect or
invalid specification. The default values were selected because they
conform to the most applicable and frequently used practices.
When you enter a file specification and omit fields in it, the
supplies values for these fields.

system

The node name defaults to your local node. The device and directory
names, if omitted, default to your current default disk and directory
name. These are initially established when you log in to the system,
based on an entry under your user name in the system authorization
file.
You can find your default disk and directory name by
DEFAULT command. For example:
$ SHOW DEFAULT

DBAl: [ PAYOl]

3-8

using

the

SHOW

SPECIFYING THE FILE TO BE PROCESSED
The response to the command indicates that the current' default disk is
DBAl, and the directory name is PAYOl.
You can change the disk and
DEFAULT command.

directory

name

defaults

with

the

SET

System defaults also apply for fields other than the device and
directory name. Table 3-3 summarizes the defaults that apply to each
field in the file specification.
Table 3-3
File Specification Defaults
Field

Defaults

node

Local system

device

Default device established at login, or
SET DEFAULT command;
almost always
device

by the
a disk

If a controller designation is omitted,
it
defaults to A. If a unit number is omitted, it
defaults to O.
(The ALLOCATE and SHOW DEVICES
commands, however, treat a device name that does
not contain controller and/or unit numbers as a
generic device name.)
directory

Directory name established at login or by the
SET DEFAULT command, or next higher level in a
subdirectory

file name

No defaults are applied to file names in input
file specifications, except for those commands
accepting multiple input file specifications,
where, for specifications other than the first,
the file name
(as well as
node,
device,
directory, and file type)
is often defaulted
from the previous input file specification.
Most commands default output file names based on
the file name of an input file

file type

Various commands apply defaults for file types,
based on the standard file type conventions
summarized in Table 3-2

file version

For input files, the system assumes the most
recent version (that is, the highest number)
For output files,
the system increases the
version number by 1 for existing files, and
supplies a version number of 1 for new files

File specification defaults can be applied in other ways as well.
Chapter 8 of the VAX-11 Record Management Services Reference Manual
describes an advanced method for
applying
defaults
to
file
specifications.
This method involves the use of defaults built into
your program, the default file specification string address and size
fields of the FAB, and the related file NAM block.

3-9

SPECIFYING THE FILE TO BE PROCESSED
3.3

LOGICAL NAMES

The use of logical names is an effective technique for achieving
device independence within a program. The logical names provide a
convenient shorthand method for specifying files that you refer to
frequently.
The ASSIGN command equates a file specification to a logical name.
For example, assume that, external to your program code, you specify
the following:
$ ASSIGN DBAO: [PAYROLL] MASTER.DAT OLD MASTER:
$ASSIGN DBAl:[PAYROLL]MASTER.DAT NEW-MASTER:
The ASSIGN command equates the logical name OLD MASTER to file
MASTER.DAT on disk device DBAO in th~ directory PAYROLL. The logical
name NEW MASTER equates to file MASTER.DAT on disk device DBAl in the
directory PAYROLL on that device.
(This file specification is known
as the equivalence string for the logical name.) Subsequently, within
your program, you can specify these files as follows:
INFILE:
OUTFILE:

$FAB FNM=<OLD MASTER:>
$FAB FNM=<NEW-MASTER:>

Alternatively, you can make the following external assignments:
$ ASSIGN
$ ASSIGN
$ ASSIGN
$ ASSIGN

INDEVICE: [PAYROLL] OLD MASTER:
OUTDEVICE: [PAYROLL] NEW-MASTER:
DBAO: INDEVICE:
DBAl: OUTDEVICE:

Note in the example above that logical name equivalence strings are
not always full file specifications. Furthermore, note that the use
of logical names is recursive; that is, the equivalence string for a
given
logical name may contain a further logica·1 name.
This
assignment would require a slight modification to the program to
specify the same files. You would have to indicate the file name and
file type in the FAB file specification. For exampl~:
INFILE: $FAB FNM=<OLD MASTER:MASTER.DAT>
OUTFILE: $FAB FNM=<NEW MASTER:MASTER.DAT>
Depending on the degree of flexibility you need, numerous other
alternatives are possible in assigning logical names.
The best
alternative is determined according to individual circumstance.
Logical names and their equivalence name strings can each have a
maximum of 63 characters, and can be used to form all or part of a
file specification. If only part of a file specification is a logical
name, specify the logical name in place of the devic~ name in
subsequent file specifications.
For example, a logical name can be
follows:
$ ASSIGN DMAl:

assigned

device

name,

BACKUP

After this ASSIGN command, you can use the logical name BACKUP in
place of the device name field when referring to files on the disk.

3-10

SPECIFYING THE FILE TO BE PROCESSED
You may also create a logical name for a node name or node
specification.
This is useful for reducing the length of a long node
specification and for protecting the password field of an access
control string. For example:
$DEFINE DAVE "BOSTON""COWENS CELTICS""::"
$TYPE DAVE::DBB2:[REPORT]JAN80.DOC
The logical node name DAVE, defined above, has an equivalence string
of BOSTON"COWENS CELTICS"::
which is substituted for the node name
DAVE in the TYPE command.
RMS does not allow the use of lowercase logical names in file
specifications.
If you try to use a lowercase logical name, RMS will
convert to uppercase the entire string prior to attempting translation
and will continue to do so on each successful translation thereafter.
RMS will accept and ignore the use of blanks, tabs, and null
characters in file specifications and logical name assignments. Such
characters will be ignored by RMS, unless they are enclosed in quotes.

Logical Name Tables

3.3.1

Logical names and their equivalence
logical name tables:

names

are

maintained

•

Process logical name table -- contains entries that are local
to a particular process. When you equate a file specification
to a logical name with the ASSIGN or DEFINE command, the
logical name, by default, is placed in this table.

•

Group logical name table
contains entries that
are
qualified by a group number. These entries can be accessed
only by processes that execute within the same group number in
their UIC. To make an entry in the group logical name table,
you use the /GROUP qualifier with the ASSIGN or DEFINE
command.

•

System logical name table -- contains entries that can be
accessed by any process in the system. To make any entry in
this table, use the /SYSTEM qualifier with the ASSIGN or
DEFINE command.

You must have user privileges to place entries in the group or
logical name tables.

3.3.2

three

system

Logical Name Translation and Recursion

When the system reads a file specification, it examines the file
specification to see if the left-most component is a logical name. If
it is, the system substitutes the equivalence name in the file
specification. This is called logical name translation.
When the system translates logical names, it searches the process,
group, and system tables, in that order, and uses the first match that
it finds.

3-11

SPECIFYING THE FILE TO BE PROCESSED
When RMS translates logical names in file sp~cifications, the logical
name translation is recursive. This means that after RMS translates a
logical name in a file specification, it repeats the process of
translating the file specification. For VAX-11 RMS, the parse routine
will perform up to 10 logical name translations in an effort to
identify the actual file name. For example, consider logical name
table entries made with ASSIGN commands as follows:
$ ASSIGN DBAl:

DISK

$ ASSIGN DISK:WEATHER.SUM REPORT

The first ASSIGN command equates the logical name DISK to device DBAl.
The second ASSIGN command equates the logical name REPORT to the file
specification DISK:WEATHER.SUM. In subsequent requests for this file,
you can refer to the logical name REPORT. In translating the logical
name REPORT, the system finds the equivalence name DISK:WEATHER.SUM.
It then checks to see if the portion on the left of the colon in this
file specification is a logical name;
if it is (as DISK is in this
example)
it translates that logical name also. When the logical name
translation is complete, the translated file specification is:
DBAl:WEATHER.SUM
Note that when you assign one logical name to another logical name,
you must terminate the equivalence name with a colon (:) if you are
going to use the logical name in a file specification in place of a
device name. For example:
$ ASSIGN DBAl:
$ ASSIGN TEST:

TEST
GO

Logical node name translation is also recursive to 10 levels.
The
equivalence string produced from a logical node name must be another
node specification. That is, it cannot supply other missing elements
of a file specification.

3.3.3

Defaults for File Names

When the system completes the translation of a logical name, it must
use defaults to fill in the still-unspecified fields in the file
specification.
Many system commands create output files automatically and provide
default file types for the output files. When you use a logical name
to specify the input file for a command, the command uses the logical
name to assign a file specification to the output file as well. Thus,
if the equivalence name contains a file name and file type, the output
file is given the same file name and file type as the input file.
For example, the LINK command creates, by default, an executable image
file that has the same file name as the input file and a default file
type of EXE. However, if you make a logical name assignment and
invoke the LINK command as shown below, the results are not as you
would expect:
$ ASSIGN RANDOM.OBJ TESTIT
$ LINK TESTIT

The linker translates the logical name TESTIT and links the file
RANDOM.OBJ.
When it creates the output file, it also uses the same
logical name for the output file.
Because the equivalence name
includes a file type, the LINK command does not use the default file
type of EXE. The executable image is named RANDOM.OBJ and has a
version number one higher than the version number of the input file.
3-12

SPECIFYING THE FILE TO BE PROCESSED
3.3.4

Bypassing Logical Name Translations

The system always checks a file specification to see if it contains a
logical name. When you enter a device name or file specification, you·
can request that no translation is to take place.
You do this by
preceding the device name or file specification with an underscore
character ( ) • (If the file specification contains a node name, then
both
the -node name and devic~ name may be prefixed with an
underscore.) For example, if you do not want the system to check
whether DMA2 is a logical name on an ALLOCATE command, you would enter
the following:
$ ALLOCATE

3.3.5

DMA2:

Default Process Logical Names

When you log in to the system, the system creates logical name table
entries for your process. The logical names, which all have a prefix
of SYS, are listed in Table 3-4.
Table 3-4
Default Process Logical Names
Logical Name

Equivalence Name

SYS$INPUT

Default input stream for the process.
For an
interactive user, SYS$INPUT is equated to the
terminal. In a batch job, SYS$INPUT is equated
to the batch input stream

SYS$0UTPUT

Default output stream for the process.
For an
interactive user, SYS$0UTPUT is equated to the
terminal. In a batch job, SYS$0UTPUT is equated
to the batch job log file

SYS$ERROR

Default device to which the system
writes
messages For an interactive user, SYS$ERROR is
equated to the terminal.
In a batch job,
SYS$ERROR is equated to the batch job log file

SYS$COMMAND

Original SYS$INPUT
user or batch job

SYS$DISK

Default disk device most recently established by
the SET DEFAULT command

SYS$SYSDISK

System disk used to boot VMS

SYS$LOGIN

Default disk and directory established at login

SYS$NET

Is defined only for the target process in DECnet
task-to-task
communication.
The equivalence
string for SYS$NET identifies the source process
that invoked the target process. SYS$NET, when
opened, represents the logical link over which
the target process can exchange data with its
partner.
(For additional information, see the
DECnet-VAX User's Guide)

SYS$NODE

Identifies the local node name on which
system is running, if DECnet is installed

3-13

device

for

interactive

your

SPECIFYING THE FILE TO BE PROCESSED

3.4

PROCESS-PERMANENT FILES

Process-permanent files are an important feature of the VAX/VMS
operating system.
They exist over the life of a process: hence the
term process permanent. In contrast, most files accessed from an
image are closed when the image exits, and any control blocks that
describe them are deallocated.
You can use VAX-11 RMS to open or create a process-permanent file of
your own definition only in supervisor or executive mode. You set the
PPF bit in the file processing options field (FOP) of the FAB.
This
allocates internal data structures, maintained by VAX-11 RMS. These
structures reside in the process control region until the end of the
process.
You cannot directly access a process-permanent file in user mode.
However, you can gain indirect access to a subset of all the available
functions of process-permanent files by use of the logical name
mechanism.
When you log in to the system, a process-permanent file
corresponding to the process's input, output, and error message
streams is opened.
(This means that the most commonly accessed files
need not be reopened by each image that executes in the context of a
process.) These process-permanent files have a logical name created
for them in the process logical name table (see Table 3-4).
The
specific format of the names in the process logical name table
indicates a correspondence between the logical name and the related
process-permanent file.
VAX-11 RMS recognizes these names and thus
pr9vides easy access to the process-permanent files.

3-14

CHAPTER 4
PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

The sequential record access mode is the way to retrieve or store
records by starting at a designated point in the file and continuing
to the end of the desired area. Records are accessed in the order in
which they logically appear in the file.
Section 4.1 deals with sequential access to the sequential file
organization.
Section 4.2 deals with sequential access to the
relative file organization. Section 4.3 deals with sequential access
to the indexed file organization.

4.1

THE USE OF SEQUENTIAL FILE ORGANIZATION

This section explores various ways to use sequential file organization
with sequential record access mode. Some basic programming examples
will be used to illustrate this simple, flexible, and easy-to-use file
organization.
Once you understand sequential file organization, you
can use it where it best suits your needs, and build on the techniques
described in this chapter to use this file organization to its fullest
capabilities.

4.1.1

Reading Records

This section describes a sample program that illustrates how records
are read from a sequentially organized file.
Each record is a
fixed-length, 50-byte record, as follows:
Byte

Contents

0-4

Part number
Discount type code
Part description
Quantity on hand
Reorder quantity
Last reorder date (dd mon yy)
List price

6-25
26-29

30-33
34-42
43-49

The purpose of this program is to count the records that have
character A as the fifth byte of the record (discount type code).

4-1

the

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
Assume that, external to the program, the following assignment will be
made:
$ ASSIGN

18SEP78.INV

IN FILE:

First, you need a FAB to describe the file. You thus issue a $FAB
macro call, using parameters to set values in the FAB fields. In some
cases, the fields you use for a file can have the value applied by
default, so you need not specify these fields.
For example, the file access field indicates the type of operation you
want to perform on the file. In this example, you want to open the
file for read access (with a $GET macro instruction).
Normally, you
do so by setting FAC=GET on the $FAB macro instruction. However,
FAC=GET is the default when you are opening a file, so you need not
specify it. If you were going to perform some other type of operation
when you opened the file, such as delete, you must specify that
operation explicitly.
In addition, defaults can change depending on
the operation (see Section 4.1.2; the default is write access when
you create a file).
In this example, the file has no special characteristics, such as file
processing options.
In any case, most FAB fields used for an open
operation are only returned as output. Therefore, the only field you
need specify as input is the file specification. In the external
assignment, the logical name INFILE:
is equated to 18SEP78.INV.
Therefore, with the FNM parameter, you can indicate the file as
follows:
INFAB:

$FAB FNM=<INFILE:>

Note that the label field contains INFAB. This lets you refer to this
FAB in the $RAB macro instruction, to connect the record stream, and
define the address of the FAB for the run-time macro instructions in
your program.
Next, you need a RAB to describe the records and how you intend to
access the file. You must associate the RAB with the FAB (using the
FAB parameter) and set up a buffer area (UBF and USZ parameters).
Access to this file will be sequential, which is the default record
access mode, and therefore need not be specified.
The $RAB macro
instruction would be as follows:
INRAB: $RAB

FAB=INFAB,UBF=REC BUFFER,USZ=REC-BUFFER SIZE

The label field contains the value INRAB, g1v1ng you a means of
referring to this RAB in your run-time macro instructions. Note also
the use of the continuation hyphen (-) to continue the instruction on
the next line.
To process this file, you need certain VAX-11 RMS run-time processing
macro instructions to perform the operations. First, because this is
an existing file, you must open it for access with a $OPEN macro
instruction and specify the FAB that describes the file, as follows:
$OPEN

FAB=INFAB

Next, you must establish the record stream for this file
$CONNECT macro instruction indicating the. RAB, as follows:
$CONNECT RAB=INRAB

4-2

with

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
Once you open the file and connect the record stream, you must
indicate
what
operations you are going to perform.
In this
application, you want to retrieve records from a file. The $GET macro
instruction performs this function. This macro instruction uses the
RAB.
$GET

RAB=INRAB

After you have read all the records, and processing is finished, you
must close the file with the $CLOSE macro instruction indicating the
FAB for the file, as follows:
$CLOSE

FAB=INFAB

The $CLOSE macro instruction also disconnects the record stream for
all RABs.
If you want to disconnect the record stream for a
particular RAB connected to a FAB (more than one RAB can be connected
to a single FAB), you can use the $DISCONNECT macro instruction,
specifying the RAB to disconnect.
Figure 4-1 lists the program code to count the discount type code A
records.
The VAX-11 RMS m~cro instructions are shown in red. Note
that this program, in effect, produces no worthwhile result because
the program does not communicate the record count to you •
1
2 ,
3
4

COUNT • COUNTS

• TITLE

PROGRAM TO READ I~VENTORY FILE
TYPf 'A' DISCOUNT RECORDS

5 '

.PSECT

DATA,LONG

7 INFABI

$FAB
$RAB

FAB:J~FAB,•

INRA~t

A OISCOUNT

TY~E

cou~TI~G

FNM:<INFlLE:>
U~F:REC . . .

AUFFER,•

US 7:Rf C...,P.IJF FE t~J...S I Z E

.BLK8 5~
11 REC~BUFFER:
12 REC~BUFFER"'"SIZE=.• ~F.C.,.AUFFER
.woRO ~
13 COUNT:
14
OPEN FILE, CO~NECT STREAM
15
16 f
17
.PSECT COOE
• wQRD
1tJ
18 l3EGIN1
1q
$OPEN
FARsINFAB
21?!
BLBC
R0,0JT
$CO~JNE'CT
21
BLRC
R~,EXIT
22

23
24

READ RECORDS,

25 '

COU~T!NG

Rtil, D(ltJE

CMPB

3121

REC 4 8UFFE~+5,4•A/A/

BNEf.,;

REAO

INCi'!

COUNT

~EAOI

27
28

ALL DONE,

COUNT OF TYPE

OPE~J

I~~PUT

'~'

RECORDS

FILE

ARAl\JCH ON ERROR

Cnf,1 ~J EC T S rn EA "1

PQANCH ON ERROR

READ A RECORD

RA~=INRAP,

BQB

32
33
34
35
36 ,

USER RECORD HUFFER

TYPE 'A' RECOROS

!GET
BLBC

~ECORDS

ElRANCH ON F.RROR

CERROP MAY BE EOF)
D1SCOU~T TYPE :
'A'?
BRA~CH IF NOT
cnJNT TYPE 'A' QECORD
GO GET T~E NEXT RECORD
I~

RE.AO

CLOSE FILE ANO EXIT.

37 OONE I
38 EX tT:
3q

SCLOSE

FAB:INFAB

CLOSE Tl-iE

~nIT.s

RCll

EXIT WITH STATUS

.END BEGIN

FIL~

Figure 4-1 Program to Count Records in a Sequential File

4-3

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

4.1.2

Creating a

Sequential File

This section describes a sample program that illustrates how you can
use the sequential file organization to create a new file by copying
an existing file. The format and contents of the records in the file
are the same as those described for the example in Section 4.1.1.
Assume that, external to the program, the following
be made:
$ ASSIGN
$ ASSIGN

18SEP78.INV
18SEP78.CPY

assignments

will

INFILE:
OUTFILE:

Because this program uses two files, one for input and one for output,
two separate FABs are required to describe the files. For the input
file, you need only define the file specification.
In the external
assignment, it was equated to INFILE:.
Therefore, with the FNM
parameter, you indicate the file as follows:
INFAB:

$FAB FNM=<INFILE:>

For the output file, you must also define the file specification.
In
the external assignment, it was equated to OUTFILE:. Because you are
creating this file, you use the $PUT macro instruction to write
records to the new file. The default is write access when creating a
file; therefore, you need not specify FAC=PUT.
When you create a
file, you must indicate the record format. In this file, the records
are fixed length, so the specification is RFM=FIX.
You also must
specify the maximum record size.
For fixed-length records, the
maximum record size indicates the actual length of each record in the
file.
The records for this file are each 50 bytes long. You can
specify this record size either by indicating MRS=SO, or by defining a
record size within your program and referring to this definition, for
example, REC_SIZE=50 and MRS=REC SIZE. Defining the record size in
your program also lets you make other references to this record size
within your program, for example, in defining the size of the buffer
areas for the RAB.
As an option, you can indicate that each record is to be preceded by a
line feed and followed by a carriage return whenever the record is
output to a line printer or terminal. Set the record attributes field
with RAT=CR. The FAB for the output file is then defined as follows:
OUTFAB:

$FAB

FNM=<OUTFILE:>,RFM=FIX,MRS=REC SIZE,RAT=CR -

You must also define RABs for both files.
The FAB parameter
associates a RAB with the appropriate FAB. Because the sequential
record access mode is the default, you can omit the RAC parameter.
Both files also need a buffer area. In fact, they both can use the
same buffer area, since you will read a record into a buffer, and then
write it from the buffer before you read another record into the
buffer. The output RAB, however, uses the RBF and RSZ parameters to
define the buffer, rather than the UBF and USZ parameters. The reason

4-4

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
is that the $PUT macro instruction does not use UBF and USZ as
input;
it uses RBF and RSZ.
The $RAB macro instructions would be as follows,
with the input RAB shown first.
INRAB:

$RAB

FAB=INFAB,UBF=REC BUFFER,USZ=REC-SIZE

OUTRAB:

$RAB

FAB=OUTFAB,RBF=REC BUFFER,RSZ=REC-SIZE

The run-time processing macro calls for the input file
consist of a
$OPEN,
a $CONNECT,
a $GET, and a $CLOSE.
For the output file, you
must specify a $CREATE macro instruction (rather than an $OPEN}, which
opens and constructs a new file.
In this macro instruction, you
indicate the FAB that contains the attributes for
the new file,
as
follows:
$CREATE FAB=OUTFAB
As with the input file, you must also specify the $CONNECT macro
instruction to connect the
record stream and the $CLOSE macro
instruction to close the file.
However, before the file is closed, it
must be processed.
In the case of a copy operation, records must be
written to the new file.
Use the $PUT macro instruction,
specifying
the RAB, as follows:
$PUT RAB=OUTRAB
Figure 4-2 lists the program code to copy
macro instructions appear in red.

file.

The

VAX-11

RMS

4.1.2.1 Dynamically Creating a Sequential File - The example in this
section produces results
identical to the results of the program
listed in Figure 4-2. The difference between the two,
however,
is
that the allocation and initialization of the control blocks for the
output file (FAB and RAB} is dynamic, performed at run time
rather
than at assembly time.
The
"store" macro instructions let you
dynamically set fields.
The values you supply with the "store" macro instructions expand
into
code that affects the contents of data fields during the execution of
your program.
Figure 4-3 lists the program code for this example.
Note that only
minor changes have been made to the program listed in Figure 4-2.
Lines 11 through 19 in Figure 4-2 have been replaced in Figure 4-3
with lines 12, 13, and 14 to begin the definition of the output FAB
and RAB and to provide a .ASCIC directive to specify the character
string for the file specification.
OUTFAB:
$FAB
OUTRAB:
$RAB FAB=OUTFAB
OUT FILESPEC: .ASCIC
/OUTFILE:/

4-5

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
, TITLE

1
2 '
3 r

COPYFILE •

MA~E

PROGRAM TO MAKE A COPY OF

COPY OF INPUT FILE

TH~

INPUT FILE

a '
'5 REC...,S IZE•S0

,PSECT

b
7 Il\lFAF31

SFAB

8 INRABI

SRAB

RECORD SIZE

DAT.Ar LONG
FNMe<INFILE1>
FABaPJFAB,•

UBF•REC..,BUFFER 1 •
USZ:aREC ... S IZE
Fl\jM=<OUTFILE1>,•
RFM:aFIXr•
""~S•REC..,S IZE, •

11 OUTFABI 'fFAB
12
13
11.1

OUTPUT FILE HAS FIXED
LENGTH RECORDS, S~ BYTES
IN LENGTH, ~ITH IMPLIED
NEw LINE CARRIAGE CONTROL

RATaCR
F.AB:OUTFABr•
RBF•REC..,BUFFER,•
~SZ•REC..,S IZE

15 OUTRABI $RAB
1~

17
18

NOTE1

1q
2~

SA~E

,8LK8

REC~BUFFERt

,PSECT

21
22 '

23 '
26
27
28

REC...,SIZE

CCDE,N~~RT

INITIALIZATION •

21.1 '
25 START:

.~ORD

INPUT AND OUTPUT FILES AND CONNECT

OPE~

FA8:TNF&B

BLBC

Ri2',EltIT1

~CREATE

F~8:0UTFAA

BLBC

R0,ElCIT1

31
32

8L8C

nPEN INPUT FILE
BRANCl1 ON ERROR
OPEN OUTPUT FILE
BRANCH ON E.HRO~
CONNECT INPUT RAB

RAB:aINRAB

sco~NECT

BRANCH ON ERROR

R__,,EXIT1

CONNECT OUTPUT RAB
BRANCH ON ERROR

RAB•OUTRAB

iCONNECT

BL8C

RQl,EXIT1

COPY RECORDS
35
36 I
ruezINRAB
37 REA!11
SGET
38

RLBC

R0,DONE

$PUT

RAB:sOUTUB

BL~S

Ret,REAO

42 EXITt:

BRB

EXIT

READ A RECORD
BRANCH ON ERROR
wRITE THE RECORD TO
THE OUTPUT FILE
BRANCH ON SUCCESS
GET OUT ON ERROR

LI~

Ll3 '

ALL SET • CLOSE FILES ANO EXlT

LIS t
I.lb

L19

CLOSE INPUT FILE
CLOSE OUTPUT FILE

FAB•INFAB
FAB•OUTFAB

DONES

SC LOSE
SC LOSE

EXITI

SEX IT ,.S R0

47
48
5171

STREA~S

$JPEl\l

?q
3Vl

33
3LI

OUTPUT RAB USES
RECORD BUFFER AS Il\lPUT MA8

EXIT

~ITH

STATUS

,END START

Figure 4-2

Program to Copy a Sequential File

A $FAB STORE macro instruction has been inserted in lines 23 through
28 of- Figure 4-3 to initialize the output FAB and set the needed
values.
(Note that the FNM parameter has been replaced by two
parameters:
FNA and FNS.
This is because you cannot use the FNM
parameter to provide the file specification dynamically; you must use
the FNA and FNS parameters.)
$FAB STORE

FAB=OUTFAB,FNA=OUT FILESPEC+l,FNS=OUT-FILESPEC,RFM=Frx-;MRS=#REC SIZE,RAT=CR -

4-6

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
The $CREATE macro instruction (line 28 in Figure 4-2) has been
replaced in Figure 4-3 with a new $CREATE macro instruction (now on
line 30). This opens and constructs the output file,
indicating the
register containing the address of the FAB--RO.
(Note that the
FAB STORE macro instruction loaded the FAB address into register 0 by
default.)
$CREATE

FAB=RO

A $RAB STORE macro has been inserted in lines 34, 35, and 36 of.Figure
4-3 to-initialize the output RAB and set the needed values.
$RAB STORE

RAB=OUTRAB,RBF=REC BUFFER,RSZ=#REC SIZE

The $CONNECT macro instruction (line 32 in Figure 4-2) has been
replaced with a new $CONNECT macro instruction (now on line 38). This
instruction establishes the record stream for the output file,
indicating the register of the RAB--RO.
$CONNECT

4.2

RAB=RO

THE USE OF RELATIVE FILE ORGANIZATION

Relative file organization is available for use on disk devices only.
This organization affords more capabilities than the sequential file
organization, but, in most cases, requires additional planning and
coding to implement (see Chapter 1).
Relative file organization uses a fixed-length cell for
the file (or as a space for a record to be inserted).
all the cells are fixed-length, the individual records
they
can
be variable length, fixed length, or
fixed-length control.

each record in
However, while
need not be;
variable with

The relative file organization allows random retrieval of records by
means of keys (a key in a relative file is the relative record number
assigned to each record). The fixed-length cell allows for a direct
calculation of the record's actual position.

4.2.1

Reading a Relative File

The program described in this section produces the same result as the
program listed in Figure 4-1. The program counts discount type code A
records in the file. The record contents are the same, and so are the
external assignments.
The only difference is that the file is a
relative file.
You need not specify a file organization in the FAB for the file when
you open it because the file organization already is assigned. In
addition, you do not need to specify sequential file organization for
a create; since it is the default. Therefore, the program code would
be identical to the one for a sequential file (Figure 4-1).

4-7

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

.TITLE

23 't

PROGRA~

",
Ci REC SIZE•50
4

COPVFILE1 • MAKE COPY OF INPUT FILE

TO MAKE A COPY OF TME INPUT FILE

RECORD SIZE
DA TA, LONG

7 tNFAB:

.PSECT

$FAA

t".;QAR1

$RA~

FNM::a<lNFILEz>
FABzINFAB,•
USF:REC 4 BUFFER,•

6
.~

USZ:REC.SIZE

11 '

12 0UTFA81 t.FA8
13 l')UTRARs iRAR
111 OUT ~FILESPEC1

15 REC 4 AUFFER:
16
.?SFCl

OUTPUT FILE FA8
OUTPUT FILE RAA

FABzOUTFAR
.ASCIC /OUTFILf :/
.BLK~
~EC.SIZE
coo~.~O~PT

RECORD

BiJFFE~

1 ii,

• 0PEN

l~ITIALIZAT!ON

I~PUT

ANO OUTPUT FILES ANO CONNECT

STREA~S

2;?! START:

.1110RD

$OPE~

FAB:I~FAB

8LBC

R0,EkIT1

$FAR~STORE

OPE.N INPUT FILE
BR A NC H 0 ~J ERR 0 P
INITIALIZE OUTPUT FA!i
SET OUT FILE SPEC 4~DRE55
SET OUT FILE SPEC LENGTH
SET RECO~D FORMAT
SET MAX!~UM RECORD SIZE
N~w LINE CARWIAGE CO~TPOL

F~A:OUTFAB,•

FNAaOUT.FILESPEt+l1•

2/J
2C)

F~S:OUl.FILESPEC,•

2"'

PF~zFIX,•

27
2P.

iH T:CR

Pol~~=*l(fC . . . SIZE,•

OPEN OUTPUT FILE
BRANCH ON ERROR

$CREATE FAf3:r:R0

H'
31

~l8C

32
33

eL8C

RVl,EXITl

$CO~NECT

tRAB~STORE

CONNECT I~PUT RA8
BRANCH O~ ERROR
INITIALIZE OUTPUT FILE RAB
SET USER BUFFER ADDRESS
SET USER BUFFER SIZE

RAP=IN~AA

R0,EXIT1
~ABcOUT~A8,•

R8F=~EC.BUFFER 1 •

35
36

RSZUREC .. SIZE

8LBC

u~ '
~1

R0,EXIT1

COPY RECORDS

42 '

43 REAOz

SGET

RAB•INRAB

t.J4

BLBC

R01DONE

45
4&

SPUT

RA8•0UTRAB

Bl.BS

R01REAO

48 EXIT11
4q

ALL

51
52 DONEi
53

54
55 EX IT I
56

BRB

READ A RECORD
BRANCH ON ERROR
WRITE THE RECORD TO
THE OUTPUT FILE

BRANCH ON SUCCESS
GET OUT ON ERROR

EXIT

SET • CLOSE FILES ANO EXIT
SCLOSE
ICLOS!

,AB•IN,AB

CLOSE INPUT FILE
CLOSE OUTPUT FILE

,A8•0UT,A8

1un...1 Ra

!XlT WITH STATUS

,!ND START

Figure 4-3

4.2.2

CONNECT OUTPUT RA6
BRANCH ON ERROR

RA6•R0

$CO~NECT

38
3q

Program to Copy a Sequential File, Setting the
output Control Blocks Dynamically

Creating a Relative File

When you create a file, you must specify the type of file organization
you want, either by default for sequential or by an explicit
specification for relative.

4-8

PROCESSING FILES WITH .SEQUENTIAL RECORD ACCESS MODE
You indicate that you want the relative file organization assigned to
the file by specifying ORG=REL on the $FAB macro call that applies to
the file.
If you use the same example as in Section 4.1.2 (and Figure 4-2), but
create a relative file rather than a sequential file, only the output
file $FAB macro instruction changes, as indicated by an arrow in the
portion of code shown in Figure 4-4. Everything else in the program
remains the same.
5 REC ...SIZE:i:S0
b
.PSECT
7 INFABI $FA8
e INRABI $QA~

q
10
11
12 OUTFABI
13
14

$FA~

15
lb
17 OUTRABI $RAb

1q
20
21

22 REC ... BUFFER1
,PSECT

RECORD SIZE

DATA,LONG
F"'M:1<I"1FlLf1>
FAB:I"JFAB,•
UAF:REC.a.AUFFER,•
USZ:REC.SIZE:

OUTPUT FILE HAS FIXED
50 BYTES
IN
WITH IMPLIED
LINE
CONTROL

F~M=<OUTF!LEs>,•

RFM:zFIX,•

LE~GTH R~COROS,
LENGT~,
NE~
CAP~IAGE

MRS:REC.,,.SIZE,-

RAT:CR,n~G:REL
-·F
AA:OUTFAB,
• ---RE;F:REC""AUFFER,•
RSZ:REC.SIZE

hOTE: IJUTPUT RAB USES
SAME P.ECQRO BUFFER AS INPUT RAB
,RLK~

REC.SIZE

CODE,~O~RT

Figure 4-4

Creating a Relative File

4.2.2.1 Dynamically Creating a Relative
File - Section
4.1.2.1
described how to dynamically specify the parameters to create a file
with the sequential file organization. Section 4.2.2 described how to
create a file with the relative file organization specified at
assembly time. By combining what was discussed about the output FAB
in both of these sections, you can specify dynamically, at run time,
the parameters to create a relative file.
At assembly time, the
$FAB
macro
instruction
included
the
specification of ORG=REL (see Figure 4-4).
By adding this same
specification to the $FAB STORE macro instruction (see Figure 4-3),
you specify the parameters dynamically, at run time.
Figure 4-5 lists a section of code, showing the inclusion
to the $FAB STORE.macro instruction.

Appendix A contains an additional example of
record access mode.

sequential

4-9

the

use

ORG=REL

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

.PSECT

DATA,LO>.JG

1 INFABI

SF.lB

FN"1:cI"'l~ILE1>

8 INRABI

SRAB

FAB:INF.\13,•
URF:REC.8UFFER,•
USZ:PEC .... SIZE

10
11

12 OUTFABI Sl'AB
13 OUTRAB1 SRAB
1Q OUT .._FI LESPEC 1

OUTPUT FILE FAB
OUTPUT FILE RAH

FAB:aOUTFAB
,ASCIC /OUTFILE:/

15 REC.._SUFFERt
,BLKB
REC.._SIZE
Rf CORD RUFFER
16
COOE,~OwRT
1 PSECT
17
18 S INITIALIZATIO~ • OPE~ INPUT AND OUTPUT FILES AND CO~N~CT STREAMS
19
0
20 START I .11,10RD
SOPEN
FA8:I~FA8
21
OPEN INPUT FILE
BLBC
Rl2!,EXIT1
22
BRANCH ON ERROR
SFAB~STORE
FAB=OllTFAB, •
23
INITIALIZE OUTPUT FAB
FNA:OUT.FILESPEC+l1•
24
SF.T OUT FILE SPEC ADDRESS

'
'

26
27
28
29
30
31
32
l3

34
3'5
36

FNS=OUT 6 FILESPEC,•
RFM:FIX,•
MRS:#REC.,.S I2E, •
RAT=CR,•
ORG:REL

SET OUT FILE SPEC LENGTH

SET R~CORO FORMAT
SET MAXI~U~ RECORD SIZE
SET I~PLIEO CARRIAGE CONTROL
RELATIVE FILE ORGANIZATION

$CREATE FAB:R"'
BLBC
R0,EXIT1
!CONNECT
RA6:INRAB
BLBC
?'11,EXITl
tRAB~STO~E
RA8:0UTRAB,•

OPEN OUTPUT FILE
ARANC!-4 01'\ ERROR
CONNECT INPUT RAB
BRANCH OllJ ERROR
l~ITIALlZE OUTPUT FILE RAB
SET USEP BUFFER ADDRESS
SET USE~ BUFFER SIZE

RBF:PEC~BUFFER,•

RSZuREC .... SIZF

37
38

!CONNECT

Figure 4-5

4.3

CO~NECT

OUTPUT RAB

Creating a Relative File Dynamically

THE USE OF INDEXED FILE ORGANIZATION

Indexed file organization is available for use on disk devices only.
This organization affords more capabilities than the sequential or
relative file organization.
The indexed file allows the use of truly variable-length records.
Their lengths are limited only by the size of the bucket or by a
maximum ~ecord size that you establish. Since variable-length records
may change size on an update, there is no need to pad records to their
maximum size. The record size may be increased or decreased later
with an update operation.
Indexed files allow random access to either fixed- or variable-length
data records by a key value.
A key in an indexed file can be a
character string, a packed decimal number, a 2- or 4-byte signed
integer, or a 2- or a 4-byte unsigned binary number within the record.
This type of file organization stores the records by ascending key
value.
These records can then be retrieved sequentially in ascending
order or randomly by supplying a specific key value to retrieve.
When an indexed file is created, a key is defined by its location

and
length within each recard. At least one key, called a primary key,
must be defined for an indexed file.
Optionally, additional keys
referred to as alternate keys, may be defined.

4-10

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
As your program puts records into an indexed file, VAX-11 RMS uses the
values of the primary and alternate keys to build indexes. An index
is the structure which allows the records to be retrieved randomly.
Each data record is placed in the file in sorted order by primary key.
In alternate indexes, the sort sequence is established by pointers to
the actual data record. These mechanisms enable the data records to
be read sequentially in sorted order by any key.
Because VAX-11 RMS completely controls the placement of records in an
indexed file, location of the records in the file is transparent to
your program.

4.3.1

Reading an Indexed File

The program described in this section produces the same result as the
program listed in Figure 4-1 and described in Section 4.1.1. The
program counts discount type code A records in the file.
The record
contents are the same and so are the external. assignments. The
difference is that the file is an indexed file. In this example, the
discount type field within the record has been defined as the first
alternate key. This will allow random access to the first record
containing
discount type code A and sequential access to all
succeeding type A records. This eliminates the need to read all of
the records in the file and, in fact, simplifies the program logic.
Though some of the program code is identical to that for sequential
files, some is unique to indexed files (see Figure 4-n).
Assume that, external to the program, the following assignment will be
made:
$ ASSIGN

18SEP78.INV

INFILE:

First, you need a FAB to describe the file.
$FAB macro instruction, using arguments
fields.

You therefore issue a
to set values in the FAB

For example, the file access field indicates the type of operations
allowed when the file is opened. You want to open the file for read
access only. Normally, you do so by setting FAC=GET on the $FAB macro
instruction.
However, FAC=GET is the default when you are opening a
file, so you need not specify it. If you were going to perform some
other type of operation when you opened the file, such as delete, you
would have to specify that operation explicitly.
The only field you need specify as input is the file specification.
In the external assignment, the logical name INFILE:
is equated to
18SEP78.INV. Therefore, with the FNM parameter, you can indicate the
file as follows:
INFAB:

$FAB FNM=<INFILE:>

Note that the label field contains INFAB. This lets you refer to this
FAB in the $RAB macro instruction, to connect the record stream, and
define the address of the FAB for the run-time macro instructions in
your program.
Next, you need a RAB to describe the access to the records and to the
file.
You must associate the RAB with the FAB
(using the FAB
parameter) and set up a buffer area (UBF and USZ parameters).
You
must also specify the buffers for the key value, and the size of the
key value (KBF and KSZ parameters). Specifying KRF=l causes the first
alternate index to be used when retrieving records from the file.

4-11

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

Then you specify the record processing options ROP=LIM to compare the
key value described by the KBF and KSZ fields with the value in the
record accessed on sequential get operations. When the key value in
the record exceeds that value in the key buffer on a sequential get
operation, a success code of RMS$ OK LIM will be returned.
Finally,
the initial record access mode-is-to be by key (RAC=KEY). The $RAB
macro instruction would be as follows.
INRAB:

$RAB

FAB=INFAB,UBF=REC BUFFER,USZ=REC-BUFFER SIZE,KRF=l ,-KBF=KEY BUFF,KSZ=KEY-BUFF SIZE,ROP=LIM~RAC=KEY

The label field contains the value INRAB, giving you a
referring to this RAB in your run-time macro instructions.

means

Then you must set up the user buffer and the key buffer as follows:
REC BUFFER:
.BLKB
50
REC-BUFFER SIZE=.-REC BUFFER
KEY BUFF:
.BLKB
l'
KEY-BUFF SIZE=.-KEY BUFF
To ,process this file, you need certain VAX-11 RMS run-time processing
macro instructions. First, because this is an existing file, you must
open it with a $OPEN macro instruction and specify the FAB that
describes the file, as follows:
$OPEN

FAB=INFAB

Next, you must establish the record stream for this file
$CONNECT macro instruction indicating the RAB, as follows:

with

$CONNECT RAB=INRAB
Now you specify that the key you want is the first record containing
discount type code A. To position to the first record with discount
type code A, you issue a $FIND macro instruction (with RAC=KEY set by
the $RAB macro instruction); then you change the record access mode
to sequential with the record access mode parameter option (RAC=SEQ on
the $RAB_STORE macro instruction).
Now that you have established the logical starting point in the file
(the first record with discount type A), you want to retrieve that
record and all succeeding records with discount type A.
The $GET
macro instruction performs that function. This macro instruction uses
the RAB.
$GET

RAB=INRAB

When the success code RMS$ OK LIM is returned from a $GET macro
instruction, you will have retrieved all records in the file with a
discount type A. The current record and any succeeding records (if
not at the end of file) will have a higher key value, such as B.
After record processing is finished, you must close the file with a
$CLOSE macro instruction, indicating the FAB for the file, as follows:
$CLOSE

FAB=INFAB

4-12

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
The $CLOSE macro instruction also disconnects the record stream for
all RABs.
If you want to disconnect the record stream for a
particular RAB connected to a FAB (more than one RAB can be connected
to a single FAB), you can use the $DISCONNECT macro instruction,
specifying which RAB to disconnect.
Figure 4-6.lists the program code to count the discount type code A
records in an indexed file. The VAX-11 RMS macro instructions are
shown in red.
Note that this program, in effect, produces no
worthwhile result, because the program does not communicate the record
count to you; the program serves only as an example.

• TITL.!

2
3

COUNT • COUNTS TYPE A DISCOUNT RECORDS

PROGRAM TO READ INVENTORY FILE COUNTING
TYPE 'A' DISCOUNT RECORDS

5
6

7 I~FABI
e Il'IJRA.81

.PSECT
SFAB
UH8

12
13
1a

OAH,1.0NG
FN"1uINFILE:1>
FAS•Il\lFAB,•
UBF•REC.BUFFER,•
USZ•REC.9UFFER.SIZE1•
l<RF•11•
KBF•l<EY.EIUFF 1 •

t<EY TO SEARCH ON
BUFFER to HOLD KEY VALUE
SIZE OF KEY VAl.UE

KSZ•l<EY.BUFF~SIZE1•

ROr:t•LIM1•
•UC•KEY

16 REC.BUFFER1

17
1 A.
lq
2P'

.ALK~
5~
REC.RUFFER_._SIZ~•.•REC.BUFFER
KEV~AUFFt

COUNT1

.,,;ORD

OPEN FILE, CONNECT

22
2l
2a

.eLK9

KEY.AUFF~SIZE•,•KEY.8UFF

STREA~

25 ~EGI°'JI

,PSECT
.~ORD

CODE
0

~Or:>EN

FAB:I~FAB

8LBC

R~1EXIT

A1.8C

RPl I EX IT

31?1
31
32 J
33
31J

BRANCH ON ERROR
CONNECT STREAM
BROICH ON ERROR

$CONNECT

QEAD RECOPOS, COUNTING TYPE 'A' RECORDS
#•A/A/,l<EY_._BUFF
RAB11l11JRA8

SPECIFY KEY wf'RE SEARCHING FOR
POSITION TO FIRST TYPE 'A' REC
NOTEa THIS IS THE RECORD THAT
WILL BE ACCESSED ON FIRST GET
BRANCH ON ERROR·
CHANGE RECORD ACCESS MOOE TO SEQ,

35
36

37
38

3Q
tJ'11 READ I

BLBC
R0, EX IT
$RA8_._STORE
RAB•INFUA 1 •
RAC•SEQ
iGET
RA8•1NRA6
R0,DONE
Bl.BC

READ A RECORD
BRANCH ON ERR-OR
(ERROR MAY BE EOF)
IS RETREIVED RECORD'S KEV
> THAN KEY VALUE IN KEY BUFF
Al.L DONE
COUNT TYPE 'A' RECORD
GO GET THE NEXT RECORD

42
43

CMPL

R~, U"1S$.._OK..,LI~

BEQL
INC(lj
BRB

COUlllT

LILI

as
Lib

DONE
READ

aA
49
ALL DONE, CLOSE FILE ANO EldT,
50 I
51 DONEi
SCLOSE FAB•INFAB

52 ElC IT

Cl.CSE THE FILE
EXIT WITH STATUS

se:xn ...s Rei
.ENO

BEGIN

Figure 4-6

Program to Count Records in an Indexed File

4-13

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
4.3.2

Creating an Indexed File

The sample program in this section illustrates how to create a new
indexed file by copying an existing file of any organization. The
format and contents of the records in the file are the same as those
described in Section 4.1.1.
Assume that, external to the program, the following
be made:
$ ASSIGN
$ ASSIGN

18SEP78.INV
18SEP78.CPY

assignments

will

INFILE:
OUTFILE:

$FAB FNM=<INFILE:>

For the output file, you must also define the file specification.
In
the external assignment, it was equated to OUTFILE:• Because you are
creating this file, you use the $PUT macro instruction to write
records to the new file. The default is write access when creating a
file;
therefore, you need not specify FAC=PUT.
When you create a
file, you must indicate the record format. In this file, the records
are variable length, so the specification is RFM=VAR.
You also must specify the maximum record size.
For fixed-length
records, the maximum record size indicates the actual length of each
record in the file. For variable-length records, the maximum record
size specifjes the size limit for a record being written initially
into the file, or an existing record being updated.
If you do not
specify the maximum record size, it is limited only by bucket size.
In this example, the maximum record size and record size are
identical. The records for this file are each 50 bytes long. You can
specify this limit either by indicating MRS=SO or by defining a record
size within your program, for example, REC SIZE=SO and MRS=REC SIZE,
and referring to this definition defining the record size in- your
program also lets you make other references to this record size within
your program, for example, in defining the size of the buffer areas
for the RAB.
You must specify that the file is an indexed file and you must specify
the
initial
extended
attribute blocks of the chain, so the
specifications are ORG=IDX and XAB=KEYO.
As an option, you can indicate that each record is to be preceded by a
line feed and followed by a carriage return whenever the record is
output to a line printer or terminal. Set the record attributes field
with RAT=CR. The FAB for the output file is then defined as follows:
OUTFAB:

$FAB

FMN=<OUTFILE:>,RFM=VAR,MRS=REC SIZE,ORG=IDX~

XAB=KEYO,RAT=CR
You must also define RABs for both files.
The FAB parameter
associates a RAB with the appropriate FAB. Because the sequential
record access mode is the default, you can omit the RAC parameter.

4-14

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE
Both files also need a buffer area. In fact, they both can use the
same buffer area, since you're going to read a record into a buffer,
and then write it from the buffer before you read another record into
the buffer.
The output RAB, however, uses the RBF and.RSZ parameter
to define the buffer, rather than the UBF and USZ parameters.
The
reason is that the $PUT macro instruction does not use UBF and USZ as
input;
it uses RBF and RSZ. The $RAB macro instructions would be as
follows, with the input RAB shown first.
INRAB:

$RAB

FAB=INFAB,UBF=REC BUFFER,USZ=REC-SIZE

OUTRAB:

$RAB

FAB=OUTFAB,RBF=REC BUFFER,RSZ=REC-SIZE

Since you are creating an indexed file, you must specify the primary
key and the alternate keys, if any. In this example the primary key
(key 0) and two alternate keys (key 1 and key 2) are defined.
They
are defined by the key definition extended attribute blocks $XABKEY
REF=O, $XABKEY REF=l,
and
$XABKEY
REF=2
macro
instructions
respectively.
The position of the keys within each record and the
length of key must be specified with the POS and SIZ parameters.
In the sample program, the primary and alternate keys are simple keys
(that is, not segmented); hence, only one position parameter value
and one size parameter value is defined for each key.
Simple keys
consist of a single string of contiguous bytes. You should note that
if segmented keys are specified, the key position and key size fields
must define an equal quantity of key position values and key size
values. The key position value is the starting (byte) position of the
key within each record (with the first byte being byte O, the second
being 1, etc.). The key size value is the length (in bytes) of the
key;
in the sample program, the primary key is a simple key, starting
in the first byte of the record and is five bytes long;
this is
defined as follows:
KEYO:

$XABKEY

REF=O,POS=O,SIZ=S,NXT=KEYl

Note that the NXT parameter points to the next XAB in the chain, which
has a label of KEYl.
The alternate keys (key 1 and key 2) likewise are defined as being in
byte positions 6 and 7, respectively, and as being 1 and 20 bytes in
length, respectively. They are defined as follows:
KEYl:

$XABKEY

REF=l,POS=S,SIZ=l,NXT=KEY2

KEY2:

$XABKEY

REF=2,POS=6,SIZ=20

and

Note that the NXT parameter is omitted from the XAB with a label of
KEY2;
therefore the default is O, which indicates there are no more
XABs in the chain.

4-15

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

In the sample program, the alternate keys may change values (on an
update) and there may be duplicate alternate keys. Changes and
duplications can be defined by FLG=<DUP,CHG>;
this is also the
default for alternate keys and, therefore it is not necessary to
actually define this parameter.
The default for the primary key is no duplicates allowed.
key is never allowed to change key value on update.

The primary

The run-time processing macro instructions for the input file consist
of a $OPEN, a $CONNECT, a $GET, and a $CLOSE. For the output file,
you must specify a $CREATE macro instruction (rather than an $OPEN),
which opens and constructs a new file. In this macro instruction, you
indicate the FAB that contains the attributes for the new file, as
follows:
$CREATE FAB=OUTFAB
As with the input file, you must also specify the $CONNECT macro
instruction to connect the record stream and the $CLOSE macro
instruction to close the file. However, before the file is closed, it
must be processed. In the case of a copy operation, records must be
written to the new file. Use the $PUT macro instruction, specifying
the RAB, as follows:
$PUT RAB=OUTRAB
Figure 4-7 lists the program code to copy
macro instructions appear in red.

4-ln

file.

The

VAX-11

RMS

PROCESSING FILES WITH SEQUENTIAL RECORD ACCESS MODE

•TITLE

1
2 '

3 r
I.I

?ROGRAM TO MAK! A COPY OF THE INPUT FILE

5 REC.a.S IZE•50
b
.PSECT
7 !Nfl'ABI
P. I NIUB I

q
H'l

SFAB
SIUB

11 OUTFAB 1 SF AB

RECORD SIZE
DATA1LONG
FNMacINFILEI>
FAB•INFAB,•
UBF•REC.BUFFER,•
US Z•REC.S IZE

13
11.i
15

OUTRABI $RAB

RdF•REC..,RUFF~R,•

RSZ:aREC..,S I ZE

cli'I

NOTE1 OUTPUT RAB USES
SAME RECORD BUFFER AS INPUT RAB

CREATE NEW FILE WITH PRIMARY KEY•PART#, AND T~O ALTERNATE KEYS

22 '

KEYJI

$XABKEY REF•'1', •
P05•0,•
s1z115,.

t-JXT=l<EV 1

27 l<E\'11

REF111,•
PQS:5, ..
SIZ•l,•

OUTPUT FILE HAS FIXED
LENGTH RECORDS, 50 BYTES
IN LENGTH, WITH IMPLIED
NEW LINE CARRIAGE CONTROL,
WITH INDEXED FILE ORG,,
AND A CHAIN OF ~EV XABS

FN~•cOUTl'ILE1>,•

RF"1•VAR 1 •
MRS•REC..,SIZE,•
ORG•IOX,•
00:sKEY0,•
IUhCR
FAB•OUTFAB,•

lb
17

MAKE COPY OF INPUT l'ILf

COPYl'ILE

25
28

2Q
3r,l

"'i)(T:11<EV2

31 l(E, y 21

32
33

$XABKEY REF:2,•
POS•6,SIZ11212!

31.i r

35 REC,,,.BUFFERI
36

.BLKB

,PSECT

CODE, "IOwRT

INITIALIZATION

3q
IH'I

41 STARTt

OPE~

INPUT AND OUTPUT FILES AND CONNECT STREAMS

, WORD
12!
SOP0
FAB•INFAB
R0,EXIT1
Al.RC
'CREATE: FA6•0UTFAB
R0,EXIT1
BLBC
!CONNECT
IH811INRAB
RP!,EXIT1
BLBC
!CONNECT
IUB•OUTRAB
IH'l,EXIT1
BLBC

OPEN INPUT FILE
BRANCH ON ERROR
OPEN OUTPUT FILE
BRANCH ON ERROR
CONNECT INPUT RAB
BRANCH ON ERROR
CONNECT OUTPUT RAB
BRANCH ON ERROR

43
/JI.I

45
4b

lJ7
4E\
I.IQ

5~ '
COPY RECORDS
51
52
!GET
RAB•INRA8
53 REAOI

'
5lJ

55
Sb

Bl.SC
!PUT

READ A RECORD
BRANCH ON ERROR
WRIT! THE R!CORD TO
THI: OUTPUT 'IL!
IRANCH ON SUCC!ll
HT OUT ON EltltOR

R0,DONE
RAB•OUTRAB

Rl,RUD
57
9LH
!XIT
58 UIT11 IRS
5•
ALL S!T
CLOSE l'IL.!S AND !X IT
b0
b1
b2 DON[1
ICLOS! 'AB•INl'AB
SCLOI! l'Al•OUTl'AB
u

,,'

65 !XIT I

Cl.OU: INPUT l"IL!
CL.OS! OUTPUT I'll..!

l!XIT ..,I Rt

.!ND

EXIT WITH SUTUI

ITART

Figure 4-7 Program to Create an Indexed File
by Copying an Existing File

4-17

CHAPTER 5
PROCESSING FILES WITH RANDOM RECORD ACCESS

Two different modes provide random access to records:
•

Random by key

•

Random by record's file address

In the random by key access mode, you retrieve or store a record by
specifying a key value. In the random by record's file address access
mode, the retrieval or storage of the record is based on a unique
address returned to the user by VAX-11 RMS.
Section 5.1 deals with random access to the
sequential
file
organization.
Section 5.2 deals with random access to the relative
file organization. Section 5.3 deals with random access to the
indexed file organization.

5.1

RANDOM ACCESS TO SEQUENTIAL FILE ORGANIZATION

The sequential file organization provides for random access to records
only if the file containing the records is on a disk device.
The sequential file organization
allows
random
retrieval
of
fixed-length records by means of keys only (a key in a sequential file
is the relative record number assigned to each record).
To gain
random access to variable-length records in a sequential file, you
must use the random by record's file address mode.

5.1.l

Random Read of a Record

This section describes a sample program that accepts the key (relative
record number)
from the operator, finds the requested record in a
file, and then displays the contents of the record.
Assume that the following external assignment will be made:
$ ASSIGN

18SEP78.INV

INFILE:

5-1

PROCESSING FILES WITH RANDOM RECORD ACCESS
OUTPUT FILE
The first file that must be defined is the output file, SYS$0UTPUT:,
which is a process logical name assigned for the output stream. For
an interactive user, SYS$0UTPUT is a terminal. The FAB for this file
only need provide this name, and also an optional record attribute
that induces a line feed before and a carriage return after printing
the record at the terminal.
TYPE FAB:

$FAB

FNM=<SYS$0UTPUT>,RAT=CR

At assembly time, the $RAB macro instruction only need
RAB with the FAB.
TYPE RAB:

$RAB

associate

·the

FAB=TYPE FAB

The actual contents of the RAB are defined dynamically, at run time
rather than assembly time with a $RAB STORE macro instruction. The
reason for this is that the record to be-output varies.
On the one
hand, records from the input file are displayed {see lines 83 through
86 of Figure 5-1), while on the other hand, a number of fixed strings
are output using the "TYPE" macro {see lines 82, 92, and 94; the
macro definition itself appears on lines 7 through 17). Each of the
different outputs requires that the RSZ and RBF parameters be set
dynamically to indicate the record to be written.
The $R~B STORE macro instruction indicates the symbolic address of the
RAB allocated at assembly time. It must also define the location and
size of the buffer that contains the record to be printed on
SYS$0UTPUT.
When displaying records read from the input file, the
location and size are at the address of INRAB {the input RAB) plus the
offset to each field {RAB$L RBF for the address and RAB$W RSZ for the
size).
$RAB STORE

RAB=TYPE RAB,RBF=@INRAB+RAB$L RBF,RSZ=INRAB+RAB$W RSZ

REQUEST FILE
The second file that must be defined is the request file, which
prompts a message to solicit information from the operator and accepts
the requested record number from the terminal.
This file
is
SYS$INPUT:, which is a process logical name.
Note that for an
interactive process, SYS$INPUT and SYS$0UTPUT both refer to
a
terminal.
In this example, it would be possible to use the same file
{either SYS$INPUT or SYS$0UTPUT) to accept requests and display
output.
In so doing, however, you would lose the ability to run the
program within a batch stream.
{As the program currently stands, you
could do this.)
PROMPT FAB:

$FAB

FNM=<SYS$INPUT:>

The RAB you connect to this FAB defines a buff er area and associates
the RAB with the FAB. The RAB also defines a record processing option
of ROP=PMT. This option indicates that the contents of the specified
prompt buffer {filled as part of the expansion of the "PROMPT" macro),
are to be output to the terminal operator in order to indicate what
data is being requested for output.
PROMPT RAB:

$RAB

FAB=PROMPT FAB,UBF=PROMPT-BUFF ,USZ=l32,- ROP=PMT
5-2

PROCESSING FILES WITH RANDOM RECORD ACCESS
INPUT FILE
The third file that must be defined is the input
provide the file specification.
The external
18SEP78.INV to INFILE:.
INFAB:

$FAB

file, which must
assignment equates

FNM=<INFILE:>

The RAB associated with this file must name its FAB and define a
buffer area. The record stream of this RAB will deal with records by
their relative record number, so you must set a value in the key
buffer address field.
This value points to a buffer you set up to
contain the relative record number of the record you want.
In the
program listed in Figure 5-1, the address of the buffer is KEY;
therefore you set KBF=KEY. Access to the records in this file is
through the random by key mode (the relative record number is the key
for sequential files). You indicate this by setting RAC=KEY.
(The
specification of KEY in this case should not be confused with KBF=KEY,
explained previously. The specification of KEY for the record access
mode is defined by VAX-11 RMS to indicate key value, which is the
relative record number.
In KBF=KEY, the KEY specification
is
user-defined.)
INRAB:

$RAB

FAB=INFAB,UBF=REC BUFFER,USZ=REC-BUFFER SIZE,KBF=KEY~RAC=KEY

When the three files are defined, you must use run-time
instructions to call the routines that act on these files.

macro

You must open the input file (INFILE) and the request file (SYS$INPUT)
with $OPEN macro instructions.
The output file for the terminal
(SYS$0UTPUT) uses a $CREATE macro instruction, since this is an output
file to be created. However, since SYS$0UTPUT is a logical name, the
file was created for you when you logged into the system.
Therefore,
this $CREATE macro instruction acts as a $OPEN macro instruction, so
you could, in fact, use the $OPEN macro instruction for SYS$OUTPUT in
this program.
Each file you open in the program must have a RAB
appropriate FAB with a $CONNECT macro instruction.

connected

the

For the input file, use a $GET macro instruction to retrieve the
record.
For the output file, use a $PUT macro instruction to place
the record in SYS$0UTPUT so it can be printed at the terminal.
All open files must be closed when you finish processing.
you must use three $CLOSE macro instructions.

Therefore,

Figure 5-1 lists the program code that accepts the key (relative
record number)
from the operator and displays the contents of that
record on the terminal.
Note that in this program, two macro
definitions appear. The first builds the string that is displayed on
the terminal.
The second macro definition accepts input
from
SYS$INPUT and prompts with the string specified as its argument.
Notice that both of these macro definitions make use of run-time macro
instructions ($PUT and $GET) in their construction.
You will also note that this program is written in subroutines.
Therefore, for some files, the $CLOSE macro instruction appears before
the $OPEN or $CREATE macro instruction.

5-3

PROCESSING FILES WITH RANDOM RECORD ACCESS

,TITLE

DISPLAY • DISPLAY SPECIFIED RECOPO

PRDGRA~ TO ACCEPT RECORD
CORPESPONnING PEC0RO

NU~BER

FROM OPERATOR ANO DISPLAY

5 '

TYPE.
I

SHdNG

MAC~O TO TVPE "ST~P;G"
SAvE CUR~ENT PSECT
CHANGE TO TYPE STRINGS PSECT

SHE

PSECT

•

TYCE .... STR!NGS, NOWRT
f"tPA::.
,ASCII \STi:?PJG\

11'
t 1

~OTE

000 l~PL: 0

1'3
1 Ll

.~ESTC1RE

~OVL

~ •• ,T~PA,

~ov~

lh
1 7 • E r-.'n ~'.

iPUT

~
T~PL,
RAA:TYPE~QA~

•

••

1 TMP~

•••

ADD~ESS

STORE STRING
~OTE

TYP~ ... RAB+RABJL .... RRF
TVPE .... RAB+RAB~w .... R~Z

LENGTH

RACK TO ORIGINAL PSECT
SET STRJ\IG ADl)~ESS
SET STRI.~G LENGTH
~RITE THE RECORD

pi
\Q

r-<4CC:1

MACRO Tn ACCEPT INPUT
SYS~!NPUT, PROMPTING
"'ITH "STRil'l:t;"

211

FRO~

,SAVE
.PSECT

22
2.3
2/J

0 ,

?5
2h

SAVE CURRENT PSECT
TYPE .... ST~I~GS, NOWRT

CHHJGf TO TYPF:

T'-'PA: 0

.~YTE

• A5 C 1 I

'-'OTE

\3, P
\ 5 T ;.: I •,, r, \

••• r~PL=. - ••• r~~~

n
2>1

,"1ESTOPE

..., 0 V L

1t 0 1 0

T 11 P ~ ,

P i1 0 ;-•PT ..... RA f; +QA~ t L .•.P 8 F

7,0

t-1QV8

a,,,T"PL,

PRIJMPT ... RAR+~A~$i; .... PSZ

31
)2

JGET

RA~

MOVZHL

P~O~PT

"3'

~OVL

P~n~Pf~QAH+~AB'L ... RBF,~2

,PSfCT

r)ATA1LOl\/G
iFAR
FNM:<SYSJOUTPUT:>,R4T:CR
r;- AF3: TYPE.JAB

'!.i •E: D
~.

P~O~PTLRAR

.... qAR+RA8$w .... RSZ,~l

!17

TYPE ... FAqJ

_5Q

l'f•OE.~qAR:

.:.!?'

C~(lr.1PT~FAE:

I~\

PKQMPT.._~A~S

cA!'.< 1-( I AGE p ETlJ "' •J I L p, E F Ef-. D
STORE STRJ"Jr,
'-JJTE L.ENGTH
eAC~ TO ORIGI~AL PSECT
S€T PRO~PT BUFFER AOQRESS
SET PRO~PT BUFFER SIZE
Gf.T THE !NPIJT
GET I~PUT LENGTH
G~T ! ... PUT ADD~ESS

FNl-':<SVSUNPUT :>
FAB:PR()~PT ... FA8,•

UHF:PR()MPT~AUFF,•

USZ:132,•
ROP:PMT
!32

IJ5 PRl"!"1PT ... BUFF I
4l-i

Pst.CT

~·

3'i

SP~Jr.GS

ADD~F.SS

• 8LKJ:I

FNM:1<Plif'ILF.1>
FA8:INFA8,•
4q
UliF:REC .... 9UFFER,•
USZ•REC.BUFFER .... SIZE,•
5"'
1<8F•KEY,•
51
RACcKEY
52
50
53 REC.SUFFER I
1 BLKB
51.1 REC.BUFFER .... SIZE• •REC.BUFFER
ALIGN LONG
55
,BLKL
1
5& KEYi
57 '
i.J7

!NF~B:

t~B

INIHB:

USER RECORD BUFFER

5q
bV.
61

OPE~

RECORD NUMBER TO RETRIEVE

FILE,CONNECT STREAM

.PSECT

63 8EGP;:

r,IJ

.woRD

$OPE~

FA8:INFA8

COOE,NO~PT

OPE"l INPLJT FILE
tj~A1'1C~ 01\i ERRO~

BL8C
R01E:XIT1
$CONNECT
RAB: I NRA~

.,7

R L8 S

q 0 , CNi T 1

BRANCH

68 EXIT1:

~Rw

EXJT

~RANCH

858~

I~JT.TYPf

l"JJTIALIZE TYPE AND

GET RfCQkO NUMBER
BRANCH QN SLJCCFSS
8~ANCH (Jr• E.RROR

C Q~IT 1 I

CO~·"JECT

STREA~

"~
Q\j

SUCCESS
ERROR

JV'
71

72
73 GET.REC"'NO:
DR(IMPT
71.1
RL~S
75
7b

q" I c 0~1T 2

CIONE

Figure 5-1

Random Read of a Sequential File

5-4

PR~MPT

FILES

PROCESSING FILES WITH RANDOM RECORD ACCESS

77 C0"•T2:

858~

7e,

AL~C

CONVE~T~KFY
RJ,RA~~KEY

7'I
P.V1

MOvL
$GET

RA8:!NRA~

BLH~

R0,8AD.PART

C~~VERT KEY TO AINARY
BRA•JCH !F BAD
SET RECORD NUM~ER
GET RfCO~O FO~ PART
BRA>..JCH Or~ ERi:<OR

~3,r<U

$RA8~STORF

RAB:TYPE~~AA,•

All
RS

RHF:•I~~AB+RAB$L~~~F,•

PRit<T

RA R:P ~)
Rrt1,0IT

~!:\

C:ET ,,,.F<EC.NO

LOOP

RSZ=I~~AB+PAA!w.RSZ
~ECORD

BR At·JC H ON

F.~Q OR

REPORT

E~RORS

q2 RAD.._KFY:
RRW
93
94

TYPE
<ijAD KEY VALUE1>
GET .Rc:c.r-.o
TYPE
<RECORD nOES NOT EXIST,>
GET~REC ... NO

8A!),._PART t
13Rlli

Q6
97

,' ALL DONE • CLOSE FILES AND EXIT

98 r
Qq
1~0

DONEi

1~1

102

1J3 EX IT I
105 t++
10b

!CLOSE
'CLOSE
SCLOSE

$EXIT.a.S R0

,,'
10q , INPUTS

SUBROUTl~E

107
108

FABzINFAB
FABaTYPE.FAB
FABmPROMPT.FAB

TO CONVERT ASCII INPUT

STRI~G

~!NARY

Rt, R2 : LENGTH AND ADDRESS OF INPUT STRING

110
111

OUTPUTSI ~~ • STATUS CODE
~3 • BINARY VALUE
112
Rt, P2 1 RI.I DESTROYED
113
114
115 CONVERT.._KEYI
CLRQ
R3
11b
BRB
2~S
117
ilj 1 Q! I
R3
MULL2
116 10$1
llq
BVS
30f.
11j•A/0/, (R2)+, RLI
SUBB3
120

,..

BLSS

121

CMPB
BGTRU
ADDL2

122
123

124

DECL

125
12b
127
128

BGEQ
MOVL

INITIALIZE OUTPUT VALUE
GO CHECK IF ANY CHARACTERS
SHIFT PARTIAL ~ESULT
BRANCH ON OVERFLOW
GET BINARY VALUE FOR CHARACTER
BRMJCH IF BAD
CHARACTER > q ?
BRANCH IF BAD
ADD IN CHARACTER
ANY MORE INPUT?
BRANCH IF MORE
SHOW SUCCESS

31i1S

F'i.11* .. A/9/••A/0/
3~$

Rll,

Rt
1~$

ti 1 1

RSl3

12q
130
131 t++
132

CLRL

SHO!'I

FAILU~E

RSB

,,'..

133 f SUBROUTINE TO INITIALIZE THE TYPE AND PROMPT FILES
134
135
t3b INIT.._TYPE'I
JCREATE FAB:TYPE.FAA
137
SOPEN
FAB:PROMPT.._FAB
138
SCONNECT
RA8:TYPE.._RAB
1H
SCO~NECT
RAB : PROMPT.._RAB
1 '10
RS8
141
142
,ENO 8EGIN
143

Figure 5-1 (Cont.)

Random Read of a Sequential File

5-5

PROCESSING FILES WITH RANDOM RECORD ACCESS
5.2

RELATIVE FILE ORGANIZATION

Random access to the relative file organization, like any access
the relative file organization, is available on disk devices only.

Relative file organization, unlike sequential file organization, does
not require that records be fixed-length in order to use random
access. Therefore, the relative file organization provides more
flexibility
for
random
access than does the sequential file
organization. However, it does cost more in space requirements, since
all record cells are the same size, and some (or all) may not be
completely filled.

5.2.1

Random Read of a Record in the Relative File Organization

This section describes a sample program illustrated in Figure 5-2 that
builds on the program listed in Figure 5-1. The only difference
between the programs is that the input file in this program uses the
relative file organization.
Since it is an input file, you do not
have to indicate the file organization when you open a file and you do
not have to change the FAB to indicate the relative file organization.
(Note, however, that you do have to change the input file FAB when you
specify the $DELETE macro instruction. See the following discussion.)
This program, besides accepting the key (relative record number)
from
the operator and displaying the contents of the record on the
terminal, also queries the operator as to whether or not the record
should
be
deleted.
Therefore, you must use a $DELETE macro
instruction within the code that handles record deletion (lines 93
through 101 of Figure 5-2).
$DELETE

RAB=INRAB

This $DELETE macro instruction points to the RAB for the input file.
The relative file organization lets you delete a record from anywhere
in the file, thereby leaving the record cell free to accept another
record.
You do not have to create a new file;
the input file, in
effect, is also the output file.
(You cannot use the $DELETE macro
instruction with the sequential file organization. To remove a record
from a sequential file, you must use the $TRUNCATE macro instruction,
but it is limited to removing a record, and any succeeding records,
from the end of a file. There cannot be empty space in the sequential
file organization, because it does not use the concept of record
cells.)
When you specify the $DELETE macro instruction, you also must make a
change to the input file FAB to indicate, in the file access field,
that a delete operation can occur. Do this by adding FAC=<DEL> to the
$FAB macro instruction.
You can omit the angle brackets from DEL;
you only need them if more than one operation applies.
(In reality,
more than one operation does apply to this file. For example, since
you are also going to retrieve
records,
you
could
specify
FAC=<DEL,GET>, to indicate the get operation. However, GET is implied
by DEL, so you can omit it.)
INFAB:

$FAB

FNM=<INFILE>,FAC=<DEL>

Figure 5-2 lists the program code that accepts the key (relative
record number) from you and displays the contents of that record on
the terminal, with the option to delete the record.
Appendix A contains additional
relative file organization.

examples
5-6

random

access

the

PROCESSING FILES WITH RANDOM RECORD ACCESS

• TITl.E

2
3

PROGRAM TO ACCEPT RECORD NUMBER FROM OPERATOR ANO DISPLAY
CORRESPONDING RECORD

u
5

DISPLAY • OISPl.AY SPECIFIED RECORD

b t

t-!ACRO

.s•ve:

STRING

PSECT TYPE ..... STRINGS, NOwRT
TMPA•.
,ASCII \STRING\
• 111 TMPA
111 TMPLm 1
,RESTORE
MOVL
# 111 TMPA, TYPE ..... RAB+RABSL ..... RBF
MQVw
# 111 TMPL, TYPE . . . RAB+RABSw .... RSZ
$PUT
RABcTYPE.._RAB

111

11
12

13
1 (j

15
16

TYPE

,E"'JD~,

18 '

1q ,MACRO

PROMPT

STRING

,SAVE
,PSECT TYPE . . . STRJNGS, NQWRT
111 TMPAm 1
.BYH
13, !l-1
,ASCII \STRING\
111 T~PLm 1 • , • • TMPA
,RESTORE
MOVL
#. 1 ,TMPA, PROMPT ..... RAB+RA8$L .... PBF
~OVB
# 11 ,TMPL, PROMPT ..... RAR+RA~$B ..... PSZ
$GET
RA~ : PROMPT ..... RAB
~OvZ~L
PROMPT .... RAB+RAA$w . . . RSZ, Rl
MOVL
PROMPT . . . RAA+PAA$L . . . R8F,R2

22
23

21.1
2S
?.b

27
28
2q
3fi'

31
~2

33
3'1

MAC~O TO TYPE "STRING"
SAVE CURRENT PSECT
CHANGE TO TYPE STRINGS PSECT
NOTE ADDRESS
STORE STRING
NOTE LENGTH
BACK TO· ORIGINAL PSF.CT
SET STRING ADDRESS
SET STRING LENGTH
WRITE THE RECORD

MACRO TO ACCEPT INPUT
FROM SYS$INPUT, PRO~PTING
wITi.t "STRING"
SAVE CURRENT PSECT
CHANGE TO TVPESTRINGS PSECT
NOTE AOD~ESS
CARRIAGE RETURN, LINE FEED

s TORE s r~u NG

NOTE LENGTH
BACK TO ORIGINAL PSECT
SET PRO~PT BUFFER ADDRESS
SET PROMPT BUFF~R SIZE
GET T"1£ INPUT
GET I~PUT LENGTH
GET INPUT ADDRESS

• ENDl-1

35 '

36 ,MACRQ
37
38

ON.._ER~OR

MACRO TO BRANCH ON ERROR
BRANCH ON SUCCESS
LONG FORM OF BRANCH

"F.:ST,?L

BL~S

R~,L

B~W

DEST

3q
(jp!

1.11

f:"ll)M

42 '

,PSECT
41.1 TYPE ..... FABI
45
Lib TYPE ..... RAB I
47 PROMPT.._FAAI
48 PROMPT..._RABI

IJ3

50
51

52 ,
53 INFABI

SFAB

FNM•<INFILE1>,•
FACuDEt.>
FAB•INFAB,•

55 INRABI

DA TA, LONG
!FAB
FNM:<SYSJOUTPUT1>,•
RAT:CR
~RAB
F.AB•TYF'E 4 FAB
$FAS
FNMm<SYSUNPUTI>
$RAB
FAB•PROMPT ..... FAB,•
UBF•PROMPT 4 BUFF,•
USZ-132,•
ROP•PMT

SUB

UBF•REC..,BUFFER,•
USZ•REC..,BUFFER.SIZE1•

KBF•KEY1•
RACmKEY

Ml
.BLKB
132
bl PRO~PT ..... BUFFI
,BLKB
50
&2 REC 4 BUFFERt
63 REC.BUFFER 4 SIZE= 1 •REC.BUFFER

bl.I

&5 KEYi
bb '

71
72
73

7/J

LONG

BLl<L

RECORD NUMBER TO RETRIEVE

OPEN FILE,CONNECT STREAM

1)8
bq
11/'

.ALIGN

USER RECnRD BUFFER

REGIN1

,PSECT CODE,NOwPT
l'IORD
~
SOPEN
FAB•I~FAB
ON . . . ERROR
EXIT
I

$CONNECT
ON.ERROR

OPEN INPUT FILE
BR•NCH Or.J ERROR
CONNECT STREAM
BRANCH ON ERROR

RAB=I~RA8

EXIT

Figure 5-2

Random Read of a Relative File

5-7

PROCESSING FILES WITH RANDOM RECORD ACCESS
INIT.._TVPE

75
76

INITIALIZE TYPE AND

PRO~PT

FILES

77 r ACCEPT ~U~BER OF RECORD TO BE DISPLAYED
r
7q GET .a.RE:C..,NO s
~~
PRO~PT
<ENTER RECORD NUMBER1>
b1
ON.._ERROR
DONE
82
BSBW
CONVERT.KEY
~3
ON~ERROR
8AD 4 KEY
sa
MOVL
RJ,KEV
85
$GET
RABcINR4B
Bb
ON.ERROR
BAD.a.PART
A7
TYPE
<RECORO ISi>
88
$RAB.._STORE
RAB•TYPE~RAB,•
8Q
RBF••INRAB+RAB$L.._RBF,•
7B

GET qECORD NU~BER
BRANCH ON ERROR CE.G., EOF)
CONVERT KEY TO eI~ARY
BRANCH IF RAD
SET RECO~D NU~~EH
GET RECORD FOR PART
e1UNCH o~ ERROR

~SZ•I~RAB+RABSW..,RSZ

JPUT
RA8•R0
ON.._ERROR
EXIT
PROMPT <OELETE RECORD (YIN)?>
ON.._ERROR
DONE
TSTW
Rl
BEQL
GETNXT
CMPB
CR2)r#.A/Y/
BNEQ
GETNXT
SDELETE RAB•INRAB
ON.ERROR
!XIT
TYPE
<RECORD DELETEO.>

q2
q3

q5
qb

qq
100

101

PRINT RECORD
BRANCH ON ERROR
ASK IF RECORD SHOIJLD BE OfLETEC.
BRO!CH ON ERROR
ZERO LENGTH INPUT?
BFUt>.ICH IF YES
ANSWER START WITH 'Y'?
BRANCH IF NOT
DF.LFTE RECORD
BRANCH ON FAILURE

1~2 GETNXTt
RRW
103
uia
REPORT ERRORS
105
11116
TYPE
<SAO KEY VALUEI>
107 '3AD.a.KEY I
BRW
GET.REC..,NO
108
uq 8AD.PART1
TYPE
<RECORD DOES NOT EXIST,>
BRW
GET.REC..,NO
110

LOOP

111

112 ,
113 t ALL OONf • CLOSE FILES ANO EXIT
114 t
SCLrySE FA8sI~F49
115 OO~EI
!CLO~E

116

FABsTYP~iFA~

SCLOSE F~B•P~O~PT~FAB
117
SEXIT.S R~
118 EXITI
11q r++
120 '
121 ' SU eR0 UTI NE T 0 C0 NV ER T AS C I I I ~PUT. S TR Pl G TQ t3 1 "J A R Y
122 '
Rl, ~2 : LENGTH AND ADDRESS OF I~PUT STRING
INPUT St
123
124
OUTPUTS I R~ - ST HUS conF.
125
R3 • BINARY VALUE
126
Rt, R2 1 Ra DESTROYED
127
128
12q CONVERT.KEYi
I~ITIALIZf OUTPUT VALUE
R3
CLRQ
130
GO CHECK IF ANY CHARACTERS
2~S
8~6
131
SHIFT PARTIAL RESULT
•1~, ~3
132 1051
"'ULL2
BRANCH ON OVERFLO~
30$
BVS
133
GfT AINARY VALuE FOR CHARACTER
t1•A1ei1, CR2)+, R4
SUBB3
13U

,..

135
136
137
138
13q 2~SI
14~

BLSS
CMPB
BGTRU
ADOL2
DECL
BGEQ

30S
R4 1 t1•1i1q1.•A101

BRA~CH IF
CHARACTE~

3~$

RRA~CH

BAD
> q 1

IF BAD
ADD IN CHARACTER TO PARTIAL RESUL
ANY MORE INPUT?
BRANCH IF ~ORE
SHO~ SUCCESS

Ra, R3
Rl
1~$

141
~OVL
*1, R~
142
RSB
143 30tt
CLRL
R~
SHO~ FAILuQE
14U
RS8
11.15 '++
14b '
ta7 r SUBROUTI~E TO INITIALIZE THE TYPE AND PROMPT FILES

Figure 5-2 (Cont.)

Random Read of a Relative File

5-8

PROCESSING FILES WITH RANDOM RECORD ACCESS

148 '
14q , ••

150 INIT 4 TVPE1
151
SCREATE FAB:TVPE 4 FA8

152
153

SOPEN

tsa

FAB:PRO~PT 4 FAB
RAB:TYPE~RAA
SCONNECT
RAB
PRG~PT~RA~

155

RSB

SCON~ECT

15b

157

.END BEGIN

Figure 5-2 (Cont.)

5.3

Random Read of a Relative File

INDEXED FILE ORGANIZATION

Random access to the indexed file organization, like any access to the
indexed file organization, is available on disk devices only.
In an indexed file, random access by key is independent of the record
format
(either fixed or variable).
Therefore, the indexed file
provides more flexibility for random access than does the relative or
sequential file organizations.

5.3.1

Random Read of a Record in the Indexed File Organization

This section describes a sample program, illustrated in Figure 5-3,
that builds upon the program listed in Figure 5-1.
The major
difference between the programs is that the input file in this program
uses the indexed file organization. Since it is an input file, you do
not have to indicate the file organization when you open a file.
This program, besides accepting the key (the part number)
from the
operator and displaying the contents of the record on the terminal,
also modifies the discount type field of that record to contain an A.
Then this program sequentially accesses and displays any subsequent
records containing part numbers in which the first four characters
match those of the first record accessed. Therefore, you must use a
$UPDATE macro instruction within the code that handles record updating
(lines 94 through 103 of Figure 5-3).
$UPDATE

RAB=INRAB

This $UPDATE macro instruction points to the RAB for the input file.
Assume that the following external assignment will be made:
$ ASSIGN

18SEP78.INV

INFILE:

You must provide this program with definitions for three files:
an
output file, a file to accept the request, and an input file (where
you define that the record access mode is random, since the input file
is the one you search for the records).
OUTPUT FILE
The first file that must be defined is the output file, SYS$0UTPUT:,
which is a process logical name assigned for the output stream. For
an interactive user, SYS$0UTPUT is a terminal. The FAB for this file

5-9

PROCESSING FILES WITH RANDOM RECORD ACCESS
only has to provide this name and an optional record attribute that
induces a line feed before and a carriage return after printing the
record at the terminal.
TYPE FAB:

$FAB

FNM=<SYS$0UTPUT:>,RAT=CR

At assembly time, the $RAB macro instruction only has to associate the
RAB with the FAB.
TYPE RAB:

$RAB

FAB=TYPE FAB

The actual contents of the RAB are defined dynamically, at run time
rather than at assembly time, with a $RAB STORE macro instruction.
The reason for this is that the record to be output varies.
On one
hand, records from the input file are displayed (see lines 111 through
114 of Figure 5-3), while on the other hand, a number of fixed strings
are output using the "TYPE" macro (see lines 124,128, and 134; the
macro definition itself appears on lines 11 through 22). Each of the
different outputs require that the RSZ and RBF parameters be set
dynamically to indicate the record to be written.
The $RAB STORE macro instruction (see line 111) indicates the symbolic
address -of the RAB allocated at assembly time. It must also define
the location and size of the buffer that contains the record to be
printed on SYS$0UTPUT.
When displaying records read from the input
file, the location and size are at the address of INRAB (the input
RAB) plus the offset to each field (RAB$L RBF for the address and
RAB$W_RSZ for the size).
$RAB STORE

RAB=TYPE RAB,RBF=@INRAB+RAB$L RBF,RSZ=INRAB+RAB$W RSZ

REQUEST FILE
The second file that must be defined is the request file, which
prompts a message to solicit information from the operator and accepts
the requested record number from the terminal. This file
(see line
52)
is SYS$INPUT:, which is a process logical name. Note that for an
interactive process, SYS$INPUT and SYS$0UTPUT both refer to
a
terminal.
In this case, it would be possible to use the same file
name (either SYS$INPUT or SYS$0UTPUT) to accept requests and display
output.
In so doing, however, you would lose the ability to run the
program within a batch stream.
PROMPT FAB:

$FAB

FNM=<SYS$INPUT:>

The RAB you connect to this FAB defines a buffer area and associates
the RAB with the FAB. The RAB also defines a record processing option
of ROP=PMT. This option indicates that the contents of the specified
prompt buffer (filled as part of the expansion of the "PROMPT" macro)
are to be output to the terminal operator in order to indicate what
data is being requested for output.
PROMPT RAB:

$RAB

FAB=PROMPT FAB,UBF=PROMPT-BUFF,USZ=l32,- ROP=PMT

INPUT FILE
The third file that must be defined is the input file (see line 60),
which must provide the file specification. The external assignment
equates 18SEP78.INV to INFILE:.
5-10

PROCESSING FILES WITH RANDOM RECORD ACCESS

When you specify the $UPDATE macro instruction, you also must make a
change to the input file FAB to indicate, in the file access field,
that an update operation can occur. Do this by adding FAC=<UPD> to
the $FAB macro instruction. You can omit the angle brackets from UPD;
you need them only if more than one operation applies.
(In reality,
more than one operation does apply to this file. For example, since
you are also going to retrieve
records,
you
could
specify
FAC=<UPD,GET> to indicate the get operation. However, GET is implied
by UPD, so you can omit it.)
INFAB:

$FAB

FNM=<INFILE:>,FAC=UPD

When the three files are defined, you must use run-time macro
instructions to call the routines that act on these files the same as
described in Section 5.1.1 for the program listed in Figure 5-1.
Each file you open in the program must have a RAB
appropriate FAB with a $CONNECT macro instruction.

connected

the

Therefore,

You switch from random to sequential access mode (see line lln, Figure
5-3)
in order to access and display any subsequent records containing
part numbers (the primary key) in which the first four characters
match those of the first record accessed as follows:
$RAB_STORE

RAB=INRAB,RAC=SEQ

Since you are accessing an existing indexed file, you do not have to
specify the position or size of the key. However you must specify the
key to search on. In this example, the primary key (key 0)
is
specified by default.
Figure 5-3 lists the code for this program.
Appendix A contains additional examples of random access to an indexed
file.

5-11

PROCESSING FILES WITH RANDOM RECORD ACCESS
• TITLE

2
3

DISPLAY

DISPLAY RELAT!D RECORDS

PROGRAM TO ACCEPT PART # ,RO~ OPERATOR ANO DISPLAY
CORRESPONDING RECORD AS WELL AS ALL SUBSEQUENT RECORDS THAT
MATCH THE FIRST FOUR CHAR•CTERS
THE PART NUMBER.
MODIFY THE DISCOUNT TVP! ,IELO OF THE ~IRST RECORD ACCESSED
TO CONTAIN AN 'A'.

b
7
~

l QJ
11 .MACRO
12
13
1 ti

15
lb

17
18
lq
2~

21
22 , ENrH1
23
24 .MACRO
25
26

29
3P

31
32

STRING

~ACRO

.SAVE
.PSECT TYPE 4 STRINGS,NO~RT
,,,TMPAa,
,ASCII \STRING\
,,,TMPL•,•,,,TMPA
,RESTORE
MOVL
•,,,TMPA,TVPE.RAB+RAB,L.RB~
MOVw
•,,.TMPL,TYPE~RAB+RABsw.RSZ
SPUT
RAA•TYPEiRAB
P~O"IPT

STRING

.SAVE
,PSECT TVPE 4 STRINGS,~OWRT
,,,TMPA:,
.BYTE
13110
,ASCII \STRING\
,,,T~PL•,•.,,T~PA

.RESTORE
MOVL
#,,,TMPA,PRO~PT.RA~+RAB,L.P8F
MOVS
#,,.TMPL,PROMPT.RAB+RABSB.PSZ

3l.I

35
36

~GET

3e
39 • E"J0"1
40
l.11
l.12
l.13

TYPE

MOVZWL
MOVL

MACRO TO ACCEPT INPUT
FROM SYSSINPUT, PROMPTING
1111ITH "STRING"
SAVE CURRENT PSECT
CHANGE TO TYPE STRINGS PSECT
NOTE ADDRESS
CARRIAGE RETURN1LINE FEED
STORE STRING
NOTE LENGTH
BACK TO ORIGINAL PSECT
SET PROMPT BUFFER ADDRESS
SET PROMPT ~UFFER SIZE

PROMPTLRA8+RABSLiRBF,R2

"'" LI• E"'IOM

SAVE CURRENT PSECT
CHANGE TO TYPE STRING
NOTE ADDRESS
STORE STRING
NOTE LENGTH
BACK TO ORIGINAL PSECT
SET STRING ADDRESS
SET STRING LENGTH
lllR ITE THE RE CORO

RAB•P~OMPTLRAB
PRO~PTLRAB+RABl~..._RSZ,R1

.MACRO

MACRO TO BRANCH ON ERROR

OEST, ?L
13LBS
BRW

TO TVP! "STRING"

CONTINUE ON SUCCESS
BRANCH LONG ON ERROR

R01L
OEST

l.15
46

l.17 t
l.18
lJQ

.PSECT
TYPE..._F AB I

DATA,LONG
SFAB
FNMacSVSSOUTPUT1>1•

TVPE ...JUB I

SIUB
JFAB

IUT~CR

50
51

52 PRO~PT 4 FAB1

53 PROMPT.A.RABI

tlUB

55
5b
$7 t
58 r

59
60
61
63

INRABI

&4
bS
bb

b7
b8

bQ
70
71
72
73
1a

INPUT FILE FAB AND RAB AND XABS

Il'JFABI

b2 t

FAB•TVPE.&.FAB
FNMuSYSSINPUT1>
FAB•PROMPT.._FAB 1•
UBF•PROMPT ... BUFF,•
USZ•1321•
ROP•PMT

Sfl'AB

FNMuINFILE1>1•
FAC•UPD

SRAB

FAB•INFAB1•
UBF•REC ...BUFFER,•
USZ•REC.BUFFER.A.SIZE1•
KBF•l<EV ... BUFF,•
KSZ•KEY.BUFF.&.SIZE

PROMPT.&.BUFF1
.Bl.KB
132
REC.BUFFER I
,9LK8
5~
REC.~UFFER ... SIZE•,•REC 4 BUFFER
DISCOU~T 4 TVPE•REC 4 BUFFER+5

Figure 5-3

Random Read of an Indexed File

5-12

PROCESSING FILES WITH RANDOM RECORD ACCESS
75
76

.HIGN
KEY ..BUFFt

LONG
.BLK8

?ART # OF RECORD TO RETRIEVE

~EY.BUFF.._SIZE•.•KEY.BUFF
MATCH.PARTiNOa .~LKL
1

,
81 s OPEN FILE, CONNECT
82 ,
7q MATCH.,FLAGt

,8LKB

FIRST I.I CHARACTERS OF THE PART #
SET TO 1· IF RELATED RECORD SEEN

84 BE.GlNt

Bb
87
A8

STREA~

.?SECT

COOE,NOwRT

, wORD

Cl!

!OPEN

FA0•INFAB
ON~ERROR
EXIT
iCONNECT
RAB•INRAB
ON~ERROR
EXIT
BSRw
INIT~TvPE

OPEN I"'IPUT FIL.E
BRAl'IJCH ON ERROR
CONNECT STREAM
BRANCH ON ERROR
INITIALIZE TYPE AND ?ROMPT FILES

90 ,

Q1 1 ACCEPT PART NUMBER OF RECORD TO BE DISPLAYED
92 ,
q 3 GET .,P ART .... l\J 0 I
q4
PROMPT cF.NTER PART NUMBER1>
q5
ON .... ERROR
DONE
96
MOVC5
R11CR2)1*-Al0/,•
*51KEYiBUFF
$RAB.._STORE
RAA•INRAB,•
RAC•KEY
SGET
RA0•INRAB
ON .... ERROR
BA0 4 PART
MOVB
#•A/A/,DISCOUNT.TYPE
SUPDATE RAB:INRA8

97
98
qq
1~0

1~1

102

103
104
105
106
107
108

ON .... ERROR
EXIT
TYPE
<RECORD CHANGED T01>
CLRB
MATCH.FLAG
MOVL
•INRAB+RABSL~RBF,MATCH.PART.NO

10CI

GET PART NUMBER
BRANCH IF DONE
MOVE PART NUMBER INTO THE
KEY BUFFER, ZERO FILL.ING
KEY ACCESS TO ACCESS RECORD
WITH SPECIFIED PART #
GET RECORD WITH ?ART#•KEY
BRANCH IF RECORD NOT FOUND
MODIFV DISCOUNT TYPE TO 'A'
UPDATE RECORD, WITH NEW
DISCOUNT TYPE
BRANCH ON ERROR
SAY NO RELATED RECORDS SE!N
SAV! FIRST 4 CHARACTERS OF
PART # TO MATCH

110 OIS?LAYI
111
SRAB .... STORE
RAB•TYPE+RAB,•
112
R8F•tINRAB+RABSL .... RBF,•
113
RSZ•INRAB+RABSW.RIZ
114
!PUT
RAB•R0
115
ON .... ERROR
EXiT
116
SRAB .... STOR!
RAB•INRAB,•
117
RAC•SEQ
118
'GET
RAB•R0
11CI
BLBC
R01CHECK.._RELATED
12~
CMPL
fINRAB+RABSL~RBF,MATCH .... PART.NO
121
BNEQ
CHECK.RELAT!O
122
BBSS
#11MATCH.._FLAG10ISPLAY

SWITCH TO SEQUENTIAL. ACCESS
GET NEXT RECORD
ENO OF FILE1
IS THIS A MATCH?
ALL. DONE MATCHING
BRANCH IF HEADER HAS ALREADY

123

BE!:N PRINTED

TYPE
125
BRB
126 CHECK.RELATEDI
127
BBS
121.1

PRINT RECORD
BRANCH ON ERROR

cRELAT!O RECOROCS)1>
DISPLAY

LOOP TO GET NEXT MATCH

#1,MATCH.._FLAG,GETNEXT

BRANCM IF RELATED RECORDS PRINTED

128
TYPE
cNO RELATED RECORDS.>
129 GETllJEXTI
13~
BRW
GET~PART.._NO
131 1 REPORT £RRORS

~OOP

TO GET NEXT PART #

t32 ,

133 BAD.,PART1
1 31.1

135
13b '

137 1

TYPE
BRW
ALL DONE

138 J
13q DONEi
l4C/!

1£11

$CLOSE
$CLOSE
SCLOSE

<RECORD ODES llJOT EXIST.>
GET.PART.._NO
CLOSE FILES ANO EXIT
FA8•INFAB
FAB•TYPE.._FAB
FAB•PROMPT.._FAB

142
11.13 EXITS
t 41.1 '
11.1s r++

HXIT .... S R0

Figure 5-3 (Cont.)

Random Read of an Indexed File

5-13

PROCESSING FILES WITH RANDOM RECORD ACCESS

146
147

148
1aq
150
151
15l

153
151.1

155
156
157

SUBROUTINE TO INITIALIZE

,INIT
.. TYPE I

T~E

TYPE &ND PROMPT FI~ES

SC~EATE
SOPE~

FAB•TYPE..L.~A8
'ABaPROM'T..L.~AB

SCONNECT
SCONNECT
RSB

.ENO

RAB•TYPELRAB
RA8•PROMPT.RA8

BEGIN

Figure 5-3 (Cont.)

Random Read of an Indexed File

5-14

APPENDIX A
PROGRAM EXAMPLES

This appendix contains additional program examples that you can
examine to gain a better understanding of VAX-11 RMS. They are
somewhat more detailed than the examples in Chapters 4 and 5; but you
may find that a study of their construction, in conjunction with the
quite
VAX-11 Record Management Services Reference
Manual,
is
beneficial.

A-1

REORDER

• INDICATE REORDERED ITEMS

21•JUL.•1'78

1413bl23

VAX•11 MACRO X0,3.q

Page

1
( 1)

V'l00l1'
000(21
~000

000r.
000'7!

s ,

001(10
00V'V'I

b
7 ,'

8 ,

10 • M.\CRO

"'"'"'~
~HhlJ0
0000

17
1 El
1q
21l' .ENOM
21
22 REC.SIZE:r'50
23
.PSECT OATA,LONG
21.1 TYPE.._FA61
~FAS
FN~=<SYSSOUTPUTz>,•
RAT=CR
25
FAB:TYPE.._FAB
26 TYPE.._RAB:
SRAB
27 '
FNM=<INFILEI>
28 INFABI !FAB
2q INRARI SRl.B
FAB:INFAB,•
3(i'I
UBF•REC..,BUFFER~·
USZ•~EC..,SIZE
31
FNM1:<0UTFILE:>
32 OUTFABZ SFAB
FABi:OUTFAB
33 CUT RAB I !RAS
31.1 r
DEFINE FIEL.DS OF RECORD
35 '

'110~0
~0~0

1210~"'

012113 1/H!t 0 IH~
00~0

1{10li'l0
li'l0'50

;ii121q4

~0q4

00E4
~eEa

00E:4
li'l 128
0178
018C
li'l18C
<"t ~c

0!i'l001l1005

000'11001tl
li'lel!i'101210914

Vil BC
018C
V'l BC

lil00121~1iH~q

~1BC

(i'l(i'l000007

01ec
01BC
01BC
01RC
01C1
01c2

000001C1
000001C2
0000010&
00012101DA
000001DE
000012'1E7
00000lEE

0"'0(21

00Q'""

:i::ii

12
13
11.1

TYPE
STRING
.SAVE
.PSECT TYPE.STRINGS,NOWRT
••• TMPA:r.
.ASCII \STRING\
.,,TMPL•.•.,,TMPA
.RESTORE
MOVL
#,,,TMPA,TYPE.RA8+RABSL.R8F
MOVW
•.,,TMPL,TYPE.R~B+RABSW.RSZ
SPLIT
R•B•TYPE.,.RAB

01i!w'.10
QIQl()ll{I

N~:.IV'l~~32

q '

0106

010A
01DE
01E7
01EE

37 PART.._NO.LEN:r5
38 PART.._DESC.._L.EN•20
3q QTY.._LEN:rl.I
1.10 OUE.._LEN11q
1.11 PRICE..,LEN=i7
1.12 '
1.13 REC.._BUFFERI
1.1a PART.._NUMBERI
,BL.KB
45 DISCOUNT.._TYPE1 .BLKB
4b PART.._DESCRIPT1 .BLKB
47 QTY .._ON.._HAND I
,BLKB
1.18 REOROER.GITYt
.BL.KB
4q REORDER.DATEt
.BL.KB
50 LIST.._PRICEI
,BL.KB
51

PROGRAM TO READ THE OL.D INVENTORY MASTER FILE ANO CREATE A
NEW MASTER FILE, RECOGNIZING THOSE ITEMS WITH AN QN•HA~D
QUANTITY L.ESS THAN THE REORDER QUANTITY, AND SETTING THE REORDER
DATE IN THE NEW MASTER FIL.E TO TODAY'S DATE, ANO LISTING THE
RECORD ON SYSSOUTPUT,

0000

t:r:J

'3000
0121011'
liil00r2'
fll'11121l1'

1--'

,TITLE REORDER • INDICATE REORDERED ITEMS

2
3I.I ,'

.:i::ii
t:r:J

~
....

t"1

, SAVE
MACRO TO TYPE "STRING"
CURRENT ?SECT

,' CHANGE TO TYPE STRINGS PSECT
NOTE ADDRESS
,' STORE
STRING
NOTE LENGTH
BACK
TO
PSECT
,,'' SET STRINGORIGINAL
AQDRESS
SET
LENGTH

t:r:J

(')

(')
(')

t:r:J

, l'iRITE THE RECORD

en
en

RECORD LENGTl'1

3
0
0

STRI~G

, FAB FOR USE
'

TYPE

~ACRO

RAB FOR USE NITH TYPE

~ACRO

~ITH

t:r:J

I
I

:>4

t:r:J

>
3

t"1

t:r:J

21
~

....
>

t"1

....l"ZJ
t"1
t:r:J

G'l

>
21

PART .._NO.._L.EN
1
PART.DESC.._LEN
QTY.._LEN
QTY .._L.EN
DATE.._L.EN
PRICE.._L.EN

0
G'l

....

>
~

....
0
2':

t:r:J

REORDER

• INDICATE REORDERED ITEMS

20
~00001F4

20
00wH'l021t'19
20 20 20 20 20
0121000212
20 20 20 20 20
00e0021B

00000020
00

01EE
01EE
01EE'
~1EE

01EF
01F4
lll1FS
0209
020E
0212
0217
ra21e
0218
021C
021c

~'11000008

~0000224"

!0'!0000228
00000220
~000~22F

021c
e220
022a
;J122B
0220

00000000
0000

0000
ld000
0000
121000

21•JUL•1978

14136123

VAX•11 MACRO xe.3•9

Page

c1)

53 '
54 ,

BUFFER TO FORMAT PRINT RECORD
55 '
56 TYPE.._BUFI
.ASCII I I
57 TYPE.,,_PART I
PART ...NO ... LEN
aBLKB
58
•ASCII I I
59 TYPE.._DESC1
PART ...oEsC.LEN
.BLK8
I
&0
•ASCII I
&1 ON.._HAlllD I
QTY ...LEN
.BLKB
I
&2
•ASCII I
63 REORDERS
QTY ... LEN
.BLl<B
&4 TYPE.._LEN•.•TYPE ... BU,
&S HEADINGS
.BYTE 0
b&
.ALIGN LONG
BUFFER TO GET CURRENT DATE
&7 '
LENGTH OF BUFFER
c8 OATE.,,_BUFI
.L.ONG
11
ADDRESS OF BUFFER
TODAYS.,,_DATE
&9
.L.ONG
OO•MON•
7
70 TOOAYS~DUEI
.BLKB
VY
71 VR~CENTURYI
.BLKB
2
YV
72 YEARS
.BLi<8
2
.PSECT COD!,NOWRT
74
75 ' INITIALIZATION • OPEN INPUT AND OUTPUT FILES, CONNECT STREAMS, AND
76 '
GET TODAY'S DATE
77 I
78
79

,,,'
'

t'(j
~

Ci)

tlJ

>
3

t'(j

t1
tZl

REORDER

• INDICATE REORDERED ITEMS
00CIJ0
36

'50

0000
'1111102

000F
0~12

0012
0'-1112
0012
113

Sit

0!3

50
01"F

001'!'110228' EF

~~000220'EF

P'"13D

~04A

0040
~'1150

q"
q1

~07E

<:11089

S;3

00q8

~08E
~eqE

00qE

000001Dti'EF

00000224'EF
011!12100218'EF

svi

0QIC2
(114
000001DA'EF
03
00qc
0q
000001DE'EF
01

000011llBC'EF
000001C2'EF
001H020E'EF

05
000"01EF'EF
14
011J0H1F5'EF
00000106'EF

1~5

000C

10b ,

tl!QJDC

111!7 ,
108 t
10q J

~0EC

lt'l0EF

00Fb

28
28

1t.12
103

"'00C

qq
U0
Hit

E13

1q
31
28

0000

000C
00DC
000C
0oiEq

ia~73

5.-a

qt EXIT1:
q2
q3 cor..iT11
q5

.i::i.

1110b0

~121FB

3
( 1)

OPEN INPUT FILE

ON ERROR
'' BRANCH
INITIAL.IZE OUTPUT FAB FROM INPUT
FORMAT
' SET RECORD
RECORD SIZE
,'' SET
SET RECORD ATTRIBUTE

RAT•FABSB.RAT+INFAB
SCPEATE l'AB•R0
R0,EXIT1
BL.BC
SCONNECT
RAB•INRAB
R'11 1 CONT1
BL.BS
BRl'f
EXIT

OPEN OUTPUT FILE
', BRANCH
ON ERROR

INPUT RAB
' CONNECT
BRANCH ON SUCCESS

'' BRANCH ON ERROR
OUTPUT RAB
$CONNECT
RAB•OUTRAB
' CONNECT
BRANCH ON ERROR
R0,EXIT1
BL.BC
GET CURRENT DATE
USCTIM.A.S
TIMBUF•DATE.BUF
'' MAKE
•yy• FORMAT
MOVlli
YEAR,YR,..CENTURY
' (RATHERINTOTHAN
•yyyy•)
SOP EN
OPEN REPORT FIL.E
FAS.TVPE.FAB
'
BRANCH ON ERROR
R0,EXIT1
BL.BC
'' CONNECT
REPORT RAB
RAB•TVPE..,RAB
SCONNECT
R0,EXIT1
BLBC
'' BRANCH ON ERROR
<LIST OF INVENTORY ITEMS BEL.Ow REORDER
TYPE

tO
~

Ci)

31
ti:!

:>4

COPY RECORDS FROM OL.D MASTER TO NEW MASTER CHECKING QUANTITY
ON HANO VS, REORDER QUANTITY

111

112
113 10s1
11"

115

0100

117 2:21S I

116

118

,WORD
SOP EN
!"AB•INll'AB
R0,EXIT1
BL.BC
FAS.OUTFAB,•
SF AB.A.STORE
RFM•FABSB.RFM+INFAB,•

Paa•

POI~T>

110 ~E•D1

11q

VAX•11 MACRO xe.3-~

TYPE

00FB
00FD
0107
01"1'C
li'l10C
0113
0114
0133
0152
0152
0159
tll15E
0165
0161

141311123

~RS•FABSW.MRS+INFA81•

003A

007E

Bll

'11031

~05111

Sfil

80 START I
81
82
83

0050

21•JUL•1'78

READ A RECORD
BRANCH ON SUCCESS
FINISH BRANCH ON ERROR

SGET
BLBS
8Rlrl
CMPC3

IUB•INRAS
R0, US
DONE
#QTY.A.LEN,QTY..,ON.HAND,REORDER.QTY

BLSS
BRW
MOVC3

20s
J
OMIT REOROER PROCESSING 1F NOT
WRITE
I
#DATE.L.EN,TODAYS..,DATE,REORDER.DATE

B8SS

#11HEADING,REPORT.ITEM

TYPE
120
TYPE
121
122 REPORT.ITEMS
MOVC3
123

<PART #

PART DESCRIPTION

,''
, ON•HAND
LESS THAN REORDER QTY!
BRANCH IF YES
REORDER DATE TO TODAY'S DATE
,' SET
BRANCH IF HEADING ALREADY PRINTED

ON HAND REORDER PT.>

BUILD REPORT RECORD

#PART.NO.LEN,PART.NUMBER,TYPE.PART

121

MOVC3

#PART.DESC.L.!N 1PART.DESCRIPT,TYP!.DESC

125

MOVL

QTY.ON.HAND,ON.HAND

31
tO
t1

ti:!

REORDER

• INDICATE REORDERED

21•J"UL• 1978

ITE~S

1413&123

VAX•11 MACRO xa.3•9

P~ge

4
( 1)

00000217'EF

000C'!01DA'EF

121175
0180
~180

0160

n
:;i:.i
I

50
51
FF2B

E8
11
31

lJ1

0193
01qc
01Aq
01AC
tatAE
0181
0181
0181
tiHB1

0000021~"EF

01
1F

0181
01BE
01CB
0102
01D3
01F2
01F2
01F'
0208
0208

126

127
128
129
130

131 wRITE1
132
133

134 READ11

REORDER..,QTY,REORDER
MOVL
RAB•TYPE,.RAB,•
SRAB.&.STORE
RBF•TYPE,.BUF 1•
RSZ•#TYPE..,LEN
SPUT
RAB•FUI
RAB•OUTRAB
SPLIT
R01READ1
BLBS
EXIT
BRB
BRiii
RUD

135
13~ '

137 ' ALL SET • CLOSE FILES AND EXIT
138 '
13q DONEi
SCLOSE FAB•INFAB
140
SC LOSE FAB•OUTFAB
#11~EADING1CLOSE..,TYPE
BBS
141
cNONE>
TYPE
142
143 CLOSE..,TYPEI
144
SCLOSE FAB•TYPE,.FAB
SEXIT..,S FUJ
145 EXITI
146
141
.END START

tti

,'
'''

PRINT REPORT RECORD
WRITE NE~ MASTER RECORD
BRANCH TO READ
BRANCH ON ERROR
BRANCH ON SUCCESS

0
Gl

!e31:
tSJ

l>4

>
31:
BRANCH IF HEADING PRINTED

'
NO ITEMS REORDERED
,' INDICATE
INDICAT! NO ITEMS REORDERED

t'CI
I:"'
tSJ
Ol

DISPLAY

• DISPLAY RELATED RECORDS

14•JUL•ln8

12153113

VAX•11 MACRO Xlll,3•11

Page

Cll
000111
11!000
0000
01110(1!
0000
0000
0000
0Cll00
t'l000
111000
(10rt0

0000

b '

001210

0000
00'11111

12100lll
11lCll00
~0~0

001.10
000111
01110G'I
lil0~0

0000
0000
1'100111
00"10
0000
0000
011100
0000

001ii0
001110
0000011100
0000
0000
t'l050
00q4
00E4
0111E4
00E4
00E4
0128
012&
01&?8
0128

0 MACRO

17
l"

20 0 E'-iDM
21 '
22 0 MACRO
23
24
25
26

27
2e

30
31
32
33

DISPLAY • DISPLAY RELATED RECORDS

~
z

PROGRAM TO ACCEPT RECORD NUMBER FROM OPERATOR AND DISPLAY
CORRESPONDING RECORD AS WELL AS ALL SUBSEQUENT RECORDS THAT
MATCH THE FIRST FOUR CHARACTERS OF THE PART NUMBER.
MODIFY THE DISCOUNT TYPE FIELD OF THE FIRST RECORD ACCESSED
TO CONTAIN AN 'A' 1

11
12

~0.00

0000

'
t

7 '
8q '

IHH'IQI

~00!!11

O'I

4
5

:!1000

2 '
3 '

0(1!i1!0
000"'

00C'l0
i!l000
tl0;'10
'11000
<'1000

,TITLE

.>
0
0
3

t:i:J

TYPE
STRING
,SAVE
.PSECT TYPE.STRINGS, NOWRT
1 0 1 TMPA• 0
•ASCII \STRING\
• 001 TMPA
1 0 0 TMPL• 0
,RESTORE
MOllL
# 111 TMPA, TYPE.RAB+RABSL.R~F
'401/lll
# 000 TMPL1 TYPE..,RAB+RA8SW.RSZ
SPUT
RAl!l•TYPE..,RAR
?ROMPT

STRING

'
'

'''
''

,,'

MACRO TO TYPE "STRING"
SAVE CURRENT PSECT
CHANGE TO TYPE STRINGS PSECT
NOTE ADDRESS
STORE STRING
NOTE LENGTH
BACK TO ORIGINAL PSECT
SET STRING ADDRESS
SET STRING LENGTH
~RITE THE RECORD

MACRO TO ACCEPT IN?UT
' FROM
SYSSINPUT,
to1ITH "STRING"
'' SAVE
CURRENT PSECT

PROMP~ING

SAVE
.PSECT TYPE.STRINGS, NOWRT
1 0 0 TMPA• 0
.SYTE
131 10
,ASCII \STRING\
• 111 TMPA
001 TMPL• 1
1 RESTORE
MOVL
# 100 TMPA, PROMPT.&.RAB+RABSL.?BF
MOVB
# 01 .THPL1 PROMPT.&.RAB+RABSB.PSZ
SGET
RAB • PROMPT.RAB
MOVZlllL PROM?T 6 RAB+RA8SW.RSZ, Rl
MOVL
PROMPi.RAB+RABSL.RBF,R2
0

34
35
3&
37 ,ENOM
38 ,
3q 0 MACRO ON..,ERROR
DEST,?L
40
BLBS
R01L
BRiii
41
OEST
42 LI
43 1 ENDM
44 '
45
DATA, LONG
0 PSECT
4& TYPE.&.FABI
SFAB
FNM•<SYSSOUTPUT1>1•
47
RAhCR
48 TYPE..,RABI
SRAB
FAB•T'l'PE..,F AB
49 PROMPT.&.FABI
SFAB
FNM•<SYSSINPUTI>
50 PROMPT.A.RABI
SRAB
FAB•PROMPT.FAB,•
51
UBF•PROMPT.BUFF 1•
52
USZ•1321•
ROP•PMT
53
54 '
55 '
5& INFABI SFAB
FNM•<INFIL.E1>1•
FACacUPD>
57

CHANGE TO TYPESTRINGS PSECT
NOTE ADDRESS
''' CARRIAGE
RETURN, LINE FEED
STRING
,'' STORE
NOTE LENGTH

, SET ?ROMPT
TO ORIGINAL PSECT
BUFFER ADDRESS
PROMPT BUFFER SIZE
' SET
THE INPUT
,,'' GET
GET INPUT LENGTH
GET INPUT ADDRESS
SAC~

,'
'

MACRO TO BRANCH ON ERROR
BRANCH ON SUCCESS
LONG FORM OF BRANCH

(')

(')
(')

t:i:J

m
m
I

ttl

t:i:J
t"1

>
~
H

<:
t:i:J

t:i:J

>
3

.,,

t"1
t:i:J

"Ill

>
z

H
N

>
~
H

DISPLAY

• DISPLAY RELATED RECORDS

00000240
00000272
0H00032
00000245

0178
0178
0178

58 INIUBI
59

0178
01?'8
01ec

01BC
0240
02n
0272
0272
00000278 0274
0000027C 0278
0000027C 027C
027C
027C
027C
00000000
0000 0000
0002
000F
0015
ll022
020q
30 A028
A028
0'1!28

:x::oi

I
.......i

0000027il"EF

0181

0028
002B
0028
11'058
a0SE
00b1
00e7
~0bE

00&E
~079

0000"1245"EF

41 8F

0A00'127C "EF
0001!101A0"FF

0000111278"EF

008b
'l08C
00q4
00At
00A7
ill0Cb
~0CC

00D7
~0D7

3e
00000278"EF

50
000001A0"FF

E9
01

0000027C"EF

29
01

12
E2

14•JUL•U78

0007
0007
00EE
00F7
00FD
0108
011!18
0111
0114
011F
011F
0121

bl!!

SRAB

12153113

VAX~11

P•ge

2
( 1)

l'AB•INl'AB,•
U811'9REC.BUFl'!R,•
USZ•REC.BUFl'ER._SIZ!,•
KBF•l<EY,•
RAC•KEY

62
63 ,
64 PROMl'T.._BUFFt
.BLKB
132
65 REC.,.BUFFERI
50
.BLKB
&6 REC.,.BUFFER.._SIZE•.•REC._BUl'FER
DISCOUNT.._TYPE•REC,...BUFFER+5
&7
b8
.ALIGN LONG
b9 KEYi
.BLKL
1
70 MATCH4 PART.._NOI .BLl<L
1
71 11ATCH,...FL.AGt
0
.BLKB
12 '
73 '

MACRO X0 8 l•11

OPEN FIL.E,CONNECT STREAM
74 '
.PSECT COOE,NOWRT
75
7& 8EGINt .WORD
0
SOP EN
FAB:aINFAB
77
ON.._ERROR
78
EXIT
SCONNECT
RAB•INRAB
n
ON.._ERROR
8121
EXIT
BSBlri
INIT.._TYPE
81
82 ,
ACCEPT NUMBER OF RECORD TO BE DISl'LAYED
83 '
84 '
85 GET ._REC ... t.101
PROMPT <ENTER RECORD NUMBERt>
8&
ON.._ERROR
DONE
87
BSBlll
CONVERT 4 KEY
88
BAD._KEY
89
ON.A.ERROR
q0
IU,l<EY
MOVL
qi
SIUB.._STORE
IUB•INRAB,•
q2
RAC:al<EY
SGH
RAB•INRAB
93
q4
ON.ERROR
BAD.PART
#•A/A/,DISCOUNT._TYPE
95
"'OVB
q&
$UPDATE RAB:aINRAB
O~.&.ERROR
EXIT
97
TYPE
<RECORD CHANGED T01>
98
99
CLR8
MATCH.,.FLAG
MOVL
fINRAB+RABSL._RBF,MATCH.&.PART.&.NO
100
101 DISPLAYI
SRAB ... STOR!
RAB:aTYPE.RAB 1 •
102
RBF•fINRAB+RABSL..,.RBF,•
103
104
RSZ•INRAB+RABSW.RSZ
SPUT
RU•R0
105
ON 4 ERROR
EXIT
106
SRAB,.STORE
RAB•INRAB,RAC•S!Q
107
108 GETSEQr
109
SG!T
RAB•R0
BLBC
R0,CHECK 4 DELET!D
110
CMPL
flNRAB+RABIL.RBP,MATCH._PART,...NO
111
112
BNEQ
CH!CK.,.DELETED
113
BBSS
#1,MATCH 4 PLAG,DISP~AY
114

USER RECORD BUFFER

RECORD NUMBER TO RETRIEVE

FIRST 4 CHARACTERS OF PART NUMBER
'' SET
TO 1 IF RELATED RECORD SEEN
'

, OPEN INPUT FILE
r

8RA"ICH ON ERROR

tti

CONNECT STREA"I
ON ERROR
,'' BRANCH
INITIALIZE TYPE ANO PROMPT FILES

, GET
RECORD NUMBER
BRANCH ON ERROR CE G EOF)
CONVERT
' BRANCH IFKEYBADTO BINARY
,'' SPECIFY
SET RECORD NUMBER
l<EYEO ACCESS
,' GET
RECORD
PART
ON ERROR
,' BRANCH
MODIFY DISCOUNT TYPE
WRITE BACK MODIFIED RECORD
'' BRANCH ON ERROR
, SAY NO RELATEn RECORD SEEN
0

0 ,

~OR

SAVE PART NU,.,8ER TO "IATCH

PRINT RECORD

BRANCH ON ERROR
'' SWITCH
TO SEQUENTIAL. ACCESS
' READ NEXT RECORD
ERROR
'' BRANCH
DO FIRST 4 CHARACTERS
' OF PART NUMBER MATCH?
,' BRANCH IF HEADER ALREADY PRINTED
ON

tZJ

:><

"ti
~

tZJ

DISPLAY

• DISPLAY RELATED RECORDS
AE

0000000"'•8F

0000'1127C•tF

50
21

D1
12

CHI

"l
1F

FE80

FE6B

Ffl.lq

012l'
012q
0148
010
11110
0151
0153
0172

0174
0174
0178
11!17C
01qB
QllqS
01qf
1111qE
'111 qf
01qE
"'lBO
'111C0
01DF
01E2
01E2
01E2
01E2
IZl1E2
01EF
"'lFC
~2~q

0212
0212
0212

53
82
0q

53
13
0A
16
30
54
10
54
08

54
51
Eq

Ql1

7C
11

C4
10
83
1q
q1
1A
C0
07
18
00
05
04
05

0212
1<1212
0212
0212
0212
0212
0212
0212
0212
0214
0216
021q
0218
021E
0211'
0221
0224
0226
022q
0228
0220
0230
0231
0233
0234

14•JUL•1919

TYPE
115
BRB
11"
117 CHECK.,DELETEDI
Clo!PL
11 l'
11q
BNEQ
12r/I
TYPE
9R8
121
122 CHECK.,RELATEDI
123
BBS

12153113

PeQe

VAX•ll MACRO X0 1 3•11

3
( 1)

cRELATED RECORDCSl1>
DISPL•Y
RQl,#Rlo!Sl..,RNF
CHECK.RELATED
cOELETED RECORD SKIPPED>
GET SEQ

'' BRANCH IF NOT

#1,M•TCH..,FLAG,GETNEXT

TYPE

WAS ERROR RECORD FOUND?

GO GET NEXT RECORD

' BRANCH IF RELATED RECORDS

PRI~TED

124
cNO RELATED RECORDS,>
125 GETNEXTI
BRW
12fl
GET ..REC .. NO
LOOP
127 '
128 ' REPORT ERRORS
12q '
130 FJAD...,t<EV I
TVPE
cBAD KEY VALUEl>
SR;.j
131
GET ..REC.,NO
TYPE
132 l3AD...,PART1
cRECORD DOES NOT EXIST 0 >
BRlti
GET.,REC.,NO
133
134
135 I
136 ' ALL DONE • CLOSE FILES ANO EXIT
137 t
138 DONEi
SC LOSE FAB•INFAB
11q
SC LOSE FAB•TYPE..,FAl3
140
SCLOSE FAB•PR0'4PT.._FAB
141 EXITI
SEXIT.,S R0
142 t++
143 '
144 I SU8ROUTINE TO CONVERT ASCII INPUT STRING TO BINARY
145 t
146 t INPUTS I
Rl, R2 • LENGTH ANO ADDRESS OF INPUT STRING
147 '
148 ' OUTPUTS I R0 • STATUS CODE
R3 • BINARY VAL4E
11.1q '
Rt, R2, R4 DESTROYED
150 '
151 CONVERT.._KEYI
·-·
152
CLRQ
R3
153
INITIALIZE OUTPUT VALUE
t
154
BRB
GO CHECK IF ANY CHARACTERS
2es
155 10$1
SHIFT PARTIAL RESULT
MULL2
#101 R3
BRANCH O~ OVERFLOW
15fl
BVS
301
GET BINARY VALUE FOR CH~RACTER
157
SUBB3
··•101, (A2)+, RI.I

158
15q
161!1
161
1&2 2011
1"3
164
165
16fl 1011
16'7
tf,8 J++

BLSS
CMPB
8GTRU
ADDL2
DECL
BGfQ
MOVL
ASB
CLRL
RSB

31!11
R4,# 5 A/q/• 5 A/0/
301
R4 1 R3
Rt

#tr AllJ
RllJ

,,
,,
BRANCH IF BAO
?
'' CHARACTER
IF BAD
,' BRANCH
ADO IN CHARACTER TO PARTIAL RESUL
ANY MORE INPUT?
BRANCH
IF MORE
',' SHOlll SUCCESS
SHOlol FAILURE
'
> q

"'
~

Ci)

3:
tl:J

"'
t"1
tl:J
tll

DISPLAY

• DISPLAY RELATED RECORDS
~234

0214

k'234

111234
0234
0234

"°

~,241

111'5

024E
02'58
1112b8
C!!2b9
Ql269

14•JUL•l978

12153113

VAX•11 MACRO X0.3•11

1b9
170 r SUBROUTINE TO INITIALIZE THE TYPE AND PROMPT FILES
171 ,
172 , ••

173 INIT..,TVPEI
174
$CREATE FAB•TVPE..,FAB
175
SOPEN
FAB•PROMPT..,FAB
176
$CONNECT
RAB•TYPE..,RAB
177
SCONNECT
RAB • PROMPT..,RAB
178
RSB
179
180

.END BEGIN

Page

4
c 1)

l::o

(j)

=
31:
t'l:J

t=
3C

tU
I:"'
t'l:J

REORDER

INDICATE ITEMS TO REORDER

12•D!C•1~78

17,27117

VAX•11 Macro V02.23

Peoe

>
w

0lllli!l0

011H/J0
0000
011100

0000
0000

000111
000'1!
0000
000111
11J000
rl'H0
11'00CI!
0'300

......
0

00000032

5 '
6 '
7 '

e '

10 .MACRO
11

12
15

0000

00!00!

11100111

~000

001iHl
li'l00111

!lll0A0rl!0Pl0

000a
ft'l00CI!
0050
00q"
ei0qa

0111Ea
iil0El.I
1t:eE'I
111128

33 '

3'1 I"'IFAB1
35 Il'llUft1

01BC

01BC
01BC
!'HBC

01BC
01BC

01BC
01FC

01FC
01FC

01FC
01FC
023C

t'll

!ZJ
~

BLBS
BRW

DEST I 1L
R0,L
DEST

S!l'AB
SRAB

DATA,LONG
SFAB
FNM•cSVSSOUTPUT>,•
RAT•CR
SRAB
FAB•TVPE:FAB

~ACRO

USZ•REC.S IZE.
FNM•COUTFILE1>1•
ORi;•IDX1•
XAB•KEV0
FAB•OUTFA8,•
RBF•REC.!UFFER,•
RSZ.R!C.SIZE

55
56

57 l<!V2i

)II

n
n

3
0
0

RECORD LENGTH
FAB FnR USE WITH THE

Sii•5,•

NXT•l<EYl
SXABl<EV R!l'•11•
POS•51•
Uhl,•

l'Lll•cDUP,CHQ>,•
NXh~!Y2

SXABK!Y REF•Zr•

l'tj
~

t'll

TYP~

MACRO

RAB FOR USE WITH TYPE MACRO

at OUTRABi SUB
a2
43
4'1 I
XAs•s TO ORDER THE KEYS, PART#•PRIMARV, DISCOUNT TVPE•ALT. KEY•1,
45
4b
DESCRIPTION•ALT.KEY#2
47 '
SXABKEV REF•IJ,•
48 l<EV01
49
POS•lr•

5'1

t'll

rn
rn

TO BRANCH ON E~ROR
, BRANCH ON SUCCESS
LONG FORM OF BRA~CH

FN"lacINFILEI>
FAB•INFAB1•

38 OUTFABi SFAB

52 KEY11

rot

t'll

UB~•R!C~BUFFER,•

50
51

t-4
)II

t'll

ON~ERROR

c::J

.MACRO

28 REC.._SIZE•50
2q
.PSECT
3111 TYPE~FABi
31
32 TYPELRABi

01BC

.ENOM

TVPE~STRINGS,NOWAT

25 LI
26 .ENOM
27 I

01211

t'll

MACRO TO TYPE •STRING•
SAVE CURRENT PSECT
CHANGE TO TVPE STRINGS PSECT
NOTE ADDRESS
STORE STRING
NOTE LENGTH
8ACK TO ORIGINAL PSECT
SET STRING ADDRESS
SET STRING LENGTH
WRITE THE RECORD

STAI NG

••• TMPA•,
-ASCII \S:TRlNG\
••• TMPL•.• ••• TMPA
.RESTORE
MOVL
*••aTMPA1TVPE.._RAB+RABSL.RBF
MOVW
*••aTMPLiTVPE.RAB+RABSW.RSZ
SPUT
RAB•TVPEARA8

2'1

111128
0178

0178
0178

TVPE
.SAVE

-P~ECT

13
1 'I

000111
0000

INDICATE ITEMS TO REORDER

PROGRAM TO READ THE OLD INVENTORV MASTER FILE AND CREATE
NEW MASTER FIL!, RECOGNIZING THOSE ITEMS WITH AN ON•HANO
QUANTITV LESS THAN THE REORDER QUANTITV, AND SETTING THE REORDER
DATE IN THE N!W MASTER FILE TO TODAv•s DATE, AND LISTING THE
RECORD ON SVSIOUTPUT.

q '

A!ORD!A

3
4

r/!000
000'11
000G'I

0000!
1!'000
000rll

.TITLE

t-4

5;·

!ZJ
0

rot

t'll

0
"ZJ
t-4

rot

t'll

Cl
)II

22
t-4

)II
~

t-4

0
22

l'tj

t'll

REORDER

. INDICATE IT!MS TO REOROER

0111000005
1110000014
00000004
000000n

00!000007

023C
023C
023C
023C
027C
027C
027C
027C
027C
lll27C
027C
027C
027C
~27C

:t>'
I

......

0000111281
00000282
000002qb
0000ia2qA

(1127C
0281
11282

000~02qf

02QA
029E

00011l02A7
liHH'l002AE

02qb
02-A7

02AE
02AE
1'.12AE
20 11!2lE
e2AF
000002811
2"" 0284
11!C'H"'1J02C9 0285
20 20 20 2QI it2C9
000,,0201 02co
20 20 20 2111 0201
001l100209 0205
ti1000002B 111209
00 02oq
rll20A
02DC
00000008 020C
000002Ell• 11!2E0
1'100002EB 02£4
000002ED 02EB
01.'J0002EF 02EO

12•DEC•1q79 t7J27117
58

Mec~o

vaz.23

Pe;e

POS•61•

SIZ•21!11•

FLG•cDUP,CHG> 1•
NXT•Cll

Ei0

bl
b2 '
bl I
b4

VAX•tl

DEFINE FIELDS OF RECORD

b5 PART.._N0.&.LEN•5
PART.._DESC.._LEN•20
b7 GITY.._LEN114
b8 DATE.&-LEN1:Q
6Q PRICE.._LEN•7
7121 r
71 REC.._BUFFERr
72 PART.&-NU"'1~ERI
.BLl<B
73 DISCOUNT.TYPES .BLl<B
74 PART.._O~SCRIPT1 ~BLl<B
75 QTY.._ON.._HANDI
0 BLKB
76 REOROPJ~_.QTYI
~BLKB
77 REOROER.&.DATE1
.BLKB
78 LIST.&-PRICEr
.BLKB
bb

80 '

PART>olO.._LEN

t"O
!:G
0
Cil

~.i:n:oESC.LEN

QTY.._LEN
CITY .._1,.EN
OATE ... LEN
PRICE.LEN

!:!31
t'ZJ

BUFFER TO FOR"'1AT ANO PRINT RECORD

>'
3
t"O

81 '

132 TYPE.&-BUF r
83 TYPE.&-PART1
811
85 TYPE ...OESC t
8b
87 O~J.._iolAlllDt

.ASCII I I
.BLKB
PART .... NO,,.LEN
• .&SC II I I
PART ... DESC,,.LEN
.BLKB
.ASCII I
I
QTY,,.LEN
.BLKB
as
.ASCII I
I
89 REORDERS
QTY.&.L!N
.BLKB
90 TYPE ... L!N•.•TYPE.&.BUF
Q1 1-!EAOINGI
.BYTE
0
q2
• ALIGN LONG
ql 1 BU,FER TO GET CURRENT DATE
94 OATE~BUFi
.LONG
11
•
q5
TODAYS..._DAT!
.LONG
9& T004YS .... DATE r
.BLKB
7
91 YR LCE~TURY i
.BLl<B
2
q9 YEARI
.BLl<B
2

tot

t'ZJ

LENGTH OF BUFFER

ADDRESS OF
,'' DO•l40N•
yy

' VY
I

BUFFE~

REORDER

HHHH
HH
llll!IH

1 li'IQ •
105
106 START1
107
108

11111l00

111015

10q

0LH5

11P

0015
0015

111
112
113

0U1
0047
0054

005•
011167
0060
0080

0088
0088

0M8
00qE

lll0AB
fi\081

......

0081
0000

00EF
00EF

00tEF

000002qA'EF
03

eeqc

H0002E4'EF
0000020q"EF

0q
li!ll'l0002qE"EF

HH'112CD"EF
BH002D5"EF

00011102'4"!1'

P101

OPEN INPUT FILE
BRANCH ON ERROR
INITIALIZE OUTPUT FAB FROM INPUT
SET RECORD FORMAT
SET RECORD SIZE
SET RECORD ATTRIBUTE
CREATE OUTPUT l'IL!
BROICH ON !RROR
CONNECT INPUT RAB
BRANCH ON !RROR
CONNECT OUTPUT RAB
BRANCH ON ERROR
GET CURRENT DATE
MAKE INTO YY FORMAT
(RATHER THAN •vvvv•)
OPEN REPORT FILE
BRANCH ON ERROR
CONNECT REPORT RAB
BRANCH ON ERROR

l'AB•TYPE:FAB
EXIT
SCONNECT
AAB•TYPE:RAB
ON~ERROR
!XIT

126
127
128

TVPE
TVPE

12q

CLIST OF INVENTORY ITEMS BELOW REORDER POINT>

130! •

131

COPV RECORDS 'ROM OLD 14ASTER TO NEW MASTER CHECKING QUANTITY
ON MANO VERSUS REORDER QUANTITY

135
136

SGET
RAB•INqAB
ON: ERROR
OONE
I
CMPC3
#QTY:LEN,QTVLON.HANO,AEORDER.QTYt

01 V'IE
0110

0113

137
138

READ A RECOAO
BRANCH TO DONE, IF FINISHED
ON•HANO LESS THAN REORDER QTY

13q 2011

BLSS
BRW
140VC3

20S
I
BRANCH IF YES
WRITE
I
OMIT REORDER PROCESSING IF NOT
#DATE.LEN,TODAYSADAT!1R!OADEA.DATE

01 lA
0111'

140

011F

11.11

aess

#1rH!ADING,REPORT.IT!M

142
143

TYllE

cPART #

0126

0H002Al'"EI'
14

.WORD
0
SOPEN
l'ABaINl'AB
ON:ERROA
!XIT
SFAa:sTOA!
l'AB•OUTl'AB1•
Rl'M•l'ABIB.RFM+INl'AB1•
MAS•l'ABlw.MRS+INl'AB,•
RAT•l'ABSB.AAT+INl'AB
SCREATE FAB•OUTl'AB
ON:EAROR
EXIT
SCONN!CT
RAB•INAAB
ON:!RAOR
EXIT
SCONNECT
RAB•OUTRAB
ON:EAAOA
EXIT
SASCTIM.S
TIMBUF•DATE.BUI'
MOVW
VEAR,YA.C!NTUAY
SOPEN

00FC

IH65

0HC!l02B5"EI'
0HH2•6"EI'

va2.2J

OP!N INPUT AND OUlll'UT l'ILES, CONNECT STREAMS, AND

ON~EAAOR

133 •
134 ~E4Di

01116

H000282"EI'

11q

12e
121
122
123
12G
125

132 ,

0127
D.15

117
118

00EF

ll11112

M1e~o

010q

1q
31

HH027C "EF

114
115
116

00EF

00EF
00001112qfl'EF

VAX•tl

COD!,NOWRT

INITIALIZATION
G!T TODAY'S DUE

11!12

i03

00!34

.ll'S!CT

S7S2Tll7

000F

000002EO"EF

U0
U1

0000
000111

0002

000012!2EB'EF

1Z~D!C•l•7e

INDICATE IT!MS TO REORDER

0165

TYPE
144 REPORT:IT!M1
145
MOVC3

016C
28

0171

PART D!SCRIPTION

017D
0188

01'3
010
01'3

SET REORDER DAT! TO TODAV"S DiTE
BRANCH IF HEADING ALREADY PAINTED

ON HAND REORDER PT 0 >
t

#PART.NO:L!N,PART 4 NUMBER,TYP! 4 PAAT

BUILD REPORT RECORD

146

~OVC3

#PART.DEsc:LEN,PART.D!SCRill'T,TYP!.DESC

141
148
14•

MOVL
MOVL.

QTY.oN:HAND,oN;MANO
R!ORD!R 4 QTY1R!ORDIR

0178

OB
DI

tse

151

IRAB~STOR!

~Al•TY'!~~AB,•

RB~•TY'l~IU,, •

RSZ.#TYP!.L!N

"'d

t:rJ

31
"'d

t-t

t:rJ
tll

REORDER

INDICATE ITEMS TO REORDER
01A6
0tAF
FF2•

!ll1 BC
r111c2
~1CS

......

0G'J00020q"EF

01
1F

'111C5
01cs
01CS
01C5
01D2
E0 · 01DF
01E6
01E7
020&
l'l206
0213
ei21c
021c

12•DEC•1978 17•27117
152
153 WRITE1
154
155

SPUT
SPLIT

RA8•R0
RAB•OUTRAB
ON~ERROR
EXIT
BRW
READ

156
157 r
158 r ALL SET
CLOSE FIL!S AND EXIT
1sq r
160 OONEI
SC LOSE FAB•INl'AB
161
SC LOSE FAB•OUTl'AB
BBS
162
#1.H!ADING,CLOSE:TYPE

TYPE
CNONE>
164 CL.OSE.._TVPEt
165
SCLOSE FAB•TVPE~FAB
SEXIT.._S R0
166 !XITI
167
1&8
.END
START
163

VAX•11

~•c~o

v02.21

P•ge

PRINT REPORT REtORD
WRITE NEW MASTER RECORD
BRANCH ON ERROR
BRANCH ON SUCCESS

""~

Cil

=
31
ts.:!

BRANCH IF HEAOI~G PRINTED
INDICATE NO ITEMS REORDERED

=
31

t'd
t"'
ts.:!

{IJ

AODTOFILE

ADD RECORDS TO FILE

11•D!C•l971 11132135

VAX•11 Macro VB2,2l

Page

>
.1:1-

00!00
1'1000
llJ\ll00
0000
0000
0000

000111
0000
IH'l00
0000

0000
0000

~"""
V'llJ00
110t"llJ
IA01tl0

.1:1-

6
7
8
9
10

IN ADDITION, THE UPDATE IF (UIF) OPTION IS USED ON THE $PUT MACRO.
IN THIS EXAMPLE, THE PRIMARY KEY IS THE PART NUMBER. WHEN A RECORD
WITH A NEW PART NUMBER IS INSERTED, IT WILL SIMPLY BE PUT INTO THE
FILE. WHEN A RECORD WITH AN OLD PART NUMBER IS INSERTED, HOWEVER,
IT WILL UPDATE THE EXISTING R&CORD.

11 ,MACRO
12
13
11.1
15
16

ftl0~0

2111

-"0:30

21
22 ,ENOM

18
1q

24 ,MACRO

~00111

25
26

fl(ililJllJ

~!~11111)

"011J0
"111J0QI

t1000

•N"0

40
I.I 1 ,MACRO

;;)ftl~Vl

ll000
;,l~illlil

:3000

,,ElllDM

f/1000

42
1.13
1.14 LI
I.IS • END!il
1.16 J

'.~00111

\jQl011!

MACRO TO TYPE "STRING"

,SAVE
,PSECT TYPE..,STRilllGS,NOWRT
,,,TMPA=,
I ASCII
\STRING\
1 , 1 TMPL•,• 0 ,,TMPA
,RESTORE
MOVL
•,,,TMPA,TYPE.RAB+RABSL.RBF
MOV~
M,,,TMPL,TYPE..,RAB+RABSW.RSZ
$PUT
RAB•TYPE..,RAB

SAVE CURRENT PSECT
CHANGE TO TYPE STRING
t.IOTE ADDRESS
STORE STRING
NOTE LENGTH
BAC~ TO ORIGINAL PSECT
SET STRING ADDRESS
SET STRING LENGTH
WRITE THE RECORD

PR0"1PT

STRING

,RESTORE
MOVL
•,,,TMPA 1 PROMPT 4 RAB+RABSL..,PBF
MOVB
# 1 ,,TMPL,PROMPT..,RAB+RABSB..,PSZ
SGET
RAB•PROMPT.RAB
MOVZWL PROMPT.RAB+RABsw .. RSZ,Rl
MOVL
PROMPT.RAB+RABSL 4 RBF,R2

MACRO TO ACCEPT INPUT
FROM SYSSINPUT, PROMPTING
WITH "STRING"
SAVE CURRENT PSECT
CHANGE TO TYPE STRINGS PSECT
NOTE ADDRESS
CARRIAGE RETURN,LINE FEED
STORE STRING
NOTE LENGTH
BACK TO ORIGINAL PSECT
SET PROMPT BUFFER ADDRESS
SET PROMPT BUFFER SIZE

ON 4 ERROR
BLBS
R0,L.
BRW
OEST

DEST,?L

MACRO TO BRANCH ON EHROR
BRANCH ON SUCCESS
LONG FORM Of BRANCH

DATA,LONG

4q
FABS AND RABS FOR USE WITH TYPE ANO PROMPT MACROS
50 J
TYPE..,FABI
SFAB
FNM•CSYSIOUTPUTa>,•
51
RAhCR
52

ltl0E4

(")

t'il
tll
tll

3
0
0

....

53 TVPE..,RABI
54 PROMPT..,FAB1
55 PRO,..PT ..,RAB I
56
57

SRAB
Sl'AB
SRAB

FABaTYPE_.FAB
FNM•cSYSIINPUTI>
FAB•PROMPT 4 FABr•
UBF•PRO,..PT4 BUFF,•

usz-uz,.

ttj
~

0
Cl

!:3

:ZS
0

>cl

t'il

"'Iii

....
tot

>
:ZS

....

>
t-i

....

,PSECT

0011)0
IH'l00

00E4

>
(")

1.18

til050

00~0

00q4
1110E4

1101210

t'il

(")

t'il

0002'11J000

"1000

:ZS
0
0
3

t'il

,,,TMPL:,~,,,TMPA

1-1000
i-Hl!00

TYPE..,STRING

,SAVE
,PSECT TYPE..,STRINGS,NOWRT
,,,TMPAa,
,BYTE
11110
,ASCII \STRING\

2q
30
31
32
33
34
35
36
37
38

!110f/1111
i'011JQI
i<J000
f/1000
kl<il00

ADD RECORDS TO FILE

~"0~

ADDTOFILE

THIS PROGRAM ADDS NEW RECORDS TO AN INDEXED FILE, CREATING THE
FILE INITIALLY, IF IT DOES NOT ALREADY EXIST.

0000
'-'000
:.4'1100

"C!.100
(llllJ0QI
0000

I
........

.TITLE

1
2
3
4

t'il

ttj

tot

t'il
tll

ADDTOFILE

ADD RECORDS TO FILE
l'l0f4
"'128
~128

00000032

!i'128
0128
0128
~128

0128
~128

"'12&

0128

&7
&8
70
71 '
72 !NIUBI

~~18C

lil1FC
!t1FC
lil1FC
"'1FC
1:'.11 FC

11i23C
!1-23C
~23C

00<:!0!1!005
00<!00Ql14
0011100004

b4
bS
bb

023C
023C
_,27C
027C
"27C
~~27C

SRAB

73
J

81 KEYll

82
83
.13b

l<E'l'21

87
88
89
90
91
92
93

POS•b1•

SIZs201•
FLG•<OUP,CHG>,•
NXT•0
DEFINE FIELDS OF RECORD

94 PART..,NO..,LEN•S
95 PART.... DESC..,LEN•20
96 QTY..,LEN:14
97 DATE.... LEN•9
98 PRICE..,LEN•7

0~000007

tll27C
027C

00000281

1t127C
1'127C

REC..,BUFFERI
101 PART.... NUMBER I
U2 DISCOUNT..,TYPE1
103 PART.... OESCRIPT1
104 QTY.ON..,HAN01
105 REOROER 4 QTY1
106 REORDER,,.DATEI
107 LIST.... PRICE1

0000029A
111000029E
000002A7

000002AE

0294

029E
02A7

02Af
02AE
00000334

0280

1010

108

Pege

FILE ORGANIZATION SPECIFIED
POSSIBILITY IS PRESENT
THAT IT MAY NOT EXIST
ANO THEREFORE ~AV HAVE
TO BE CREATED

FAB•INFAB1•
RAC:aKEV

HABl<EY REF:z0,•
POS•0r•
SIZ•S1•
NXT•KEVl
SXABKEY REF•l1•
POS•5,•
SIZ•11•
FLG•cOUP,CHG>,•
NXT•KEY2
SXABKEV REF=21•

13000011109

l(l281
0282
029&

V02e23

DEFINE KEY XABS, ONE PRI~ARY KEY ANO TwO ALTERNATES

kl27C
027C
027C

00000282
0000029&

FNM•<INFILE1>1•
ORG•IOX 1•
RFM•VAR,•
MRSsREC..,SIZEr•
RAT•CR,•
FlCscPUT 1 UPD>,•
XAB:KEY0r•
FOP•CIF

7b ,

77 KEV01
78
79
80

84
85

Mec~o

ROP•PMT

b2 REC..,SIZEs50
63 INFABI SFAB

74
75

VAX•11

INPUT F!LE FAB ANO RAB AND XABS

i'.'128

01BC
01BC
lil1BC
L11BC
1"1BC
'~ 1BC
.......

b0 :
bl :

"'178
0178

U'1

58
59 :

0128
l'.'1 78

;:J::ii
I

l1•0EC•1978 10132135

109
.ALIGN
110 PROMPT.... BUFF1

.BLKB
.BLKB
eBLl<B
.BLKB
eBLKB
.BLKB
.BLKB

PART.... NO..,LEN
PART.... DESC,,.LEN
QTY,,.LEN
QTY,,.LEN
DAT!:,.L!N
PRIC!,,.LEN

LONG
eBLKB

"O
~

G')

t'IJ

:>4

>
3

"O
t1
t'IJ

{ll

ADDTOFILE

ADO RECORDS TO FILE
0334
0334
0334
00111000111111
111000 "000
0002
1!100F
000F
~015

01EF

"'022
0028
0028
~026
~028

51
03
&2
0000027c•EF

.......

1u es

51
30
05

05
12
31
2C

00000281 •EF

51
2111
1111

r.'l02B
e02B
011158
~05E

0000
~002

;;,0&'5
11}0&8
00oq
00oF
Hqc
~0A0

:IJ0Ao
~0D3

0000e2qo"EF
04
02

0000029A'EF

14
.30202020 8F
51
53
I.IA
51
029o"C3

D0
Cl
1q
28

30202020 SF
51
53
03
009D

D0
Cl

51
029A"C3

20
09

18
31

00oq
00DC
000D
lll111E3
\11110
0110
~121

0124
0125
0127
IH2A
•H2D
015A
2110111
tllloB
01oE
01&1"
0171
0174
0174
t11177
011•
0170
017E
IU80

VAX•11 Mecro \102 1 23

Pege

112
PERFORM INITIALIZATION
113
114 '
115
,PSECT CODE 1 NOWRT
116 BEGINI ,WORD
8
117
SCREATE FAB•INl"AB
118
11q
ON.ERROR
EXIT
SCONNECT
RAB•INRAB
120
ON.ERROR
EXIT
1i?1
BSBW
INIT 4 TYPE
122
123 '
12G J SOLICIT DATA l"IELDS INPUT
125 '
120 GETNXTI
PROMPT <PART #I>
127
ON.ERROR
DONE
128
12q
TSTL
Rt
130
BNEQ
l0S
BRW
DONE
131
MOVC5
R1rCR2),#.A/0/1•
132 us1

GET NUMBER OF PART
BRANCH IF DO"-lE
ANY INPUT?
CONTINUE IF YES,
ELSE QUIT
MOVE PART NUMBER TO RECORD BUFFER

133
134
13'5

PROMPT
MOVC5

ZERO FILLING
GET DISCOUNT TYPE
MOVE DISCOUNT CODE TO RECORD BUFF

130
137
138
139

#lrDISCOUNT.TYPE
PROMPT <PART DESCRIPTION1>
ON.ERROR
EXIT
MOVC5
R1 1 CR2),#.A/ 11•

(BLANK IF NULL)
GET PART DESCRIPTION

140
141
142
143
144

#PART.DESC.LEN,PART 4 DESCRIPT
PROMPT <QUANTITY ON HANDS>
ON.ERROR
EXIT
MOVL
#•A/
0/ 1 QTY.ON.HAND
SUBL3
R1,#QTY 4 LEN,R3

BUFF, BLANK FILLING
GET NU~SER ON HAND

145
140

BL.SS
MO\IC3

IF FIELD TOO SMALL1 EXIT
PUT IN VALUE ~IGHT ALIGNED

147
148
149
150

PROMPT <MINIMUM REORDER QUANTITYa>
ON.ERROR
EXIT
MOVL
#•A/
0/ 1REOROER 4 QTY
SUBL3
R1,#QTY.LEN 1 R3

OETER~INE

151
152 EXITU
153 CONTl I
1'54

BGEQ
BRW

CONT1
EXIT

CONTINUE IF FIELD IS o.K,
BRANCH LONG TO EXIT

MOVC3

R11CR2)1REORDER.QTY(Rl)

FILL IN BUFFER AREA RIGHT ALIGNED

155

MOVCS

#01CSPl1#•A1 11•

BLANK REORDER DATE

#DATE.LEN, CRl)

CTAKE ADVANTAGE OF ITS
ADDRESS IN R3)
GET ~RICE

#PART 4 NO.LENrPART.NUMBER
<DISCOUNT TYPEa>
RlrCR2)1#•A1 Ir•

OPEN FILE IF IT EXISTS
ELSE CREATE IT
BRANCH ON ERROR
CONNECT INPUT RAB
BRANCH ON ERROR
INITIALIZE TYPE ANO PROMPT FIL~S

00qF

O'I

00000282'EF

1l•DEC•l971 11132135

0180
01AD
0193

156
157
158
15CJ
108

EXIT1
R11CR2) 1 QTY.ON.HANDCR3)

PROMPT <LIST 'RICEa•
ON.ERROR
!XIT
MOVC5
~11CR2)1#•A1 11•

MOVE PART DESCRIPTION TO RECORD

INITIALIZE BUFFER AREA
DETERMINE OFFSET IN ~UFFER AREA

GET MINIMUM QUANTITY
INiTIALIZE BUFFER AREA
OFFSET

MOVE PRICE TO RECORD BUFFER

""!:O0

Ci)

3:
tZl

t"'
tZl
tll

ADDTOFILE

000002A7'EF

ADO RECORDS TO FILE
20
07

'-"186
0187
~180

0160
0180
0180
0101.1
0101.1

FEl.11

lbb

167

01E1
!ti 1E7
01EA
01EA

169
170
171

:1121.l
021A
021A
021A
lil21A
021A
021A

1 f>4

165
168

01F7
0201.1
0211

SPUT

RA8•INRA8
ON~ERROR
EXIT
BRW
GETNXT

VAX•11 M•cro V02.23

173

174 DONEa
175
176

177 EXITI

178

11
J

182

,..

WRITE NEW RECORD
GET NEXT RECORD

SCLOSE FAB•INFAB
SCLOSE FAB•TYPE.FAB
SCLOSE FA8•PROMPT.FAB
SEX IT .s R0

UIS

186
187
188
19'
19"

'tt

0
Cil

31
P.I
~

31
'tt
tot
P.I

m
SUBROUTINE TO INITIALIZE THE TYPE AND PROMPT FILES

183
181.1 INIT. TYPE1

0227
!0234
0241
021.iE

I.I

IF PART # ALREADY fXISTS, UPDATE
RECORD WITH NE~ INFOR~ATIO~

179 :++
180
181

P•ge

BLANK FILLING
SET UP RAB FOR NEW RECORD

ALL SET • CLOSE l'ILE ANO EXIT

172

021A

024F

#PR ICE.LEN, LIST.PRICE
SRAB.STORE
RA8•INRA8 1•
RBl'•REC.BUFFER,•
RSZ•#REC.8IZE1•
ROP•UIF

162
163

~101.1

01EA
·01EA

.......
.....J

11•DEC•1978 10132135

SCREATE FAB•TYPE.FAB
SOPEN
FAB•PROMPT.FAB
I CONNECT
RAB•TYPE.RAB
SCONNECT
RAB•PROM,T.RAB
RH
,END
BEGIN

APPENDIX B
USING THE RMS FILE ANALYZER

The RMS File Analyzer (RMSANLZ), which is not a DIGITAL-supported
utility, enables you to inspect the file attributes and index
structure of files. With the information provided, you can analyze
characteristics of index files such as index tree depth and fill
percentages. You can also analyze file corruption problems caused by
user program errors and RMS system failures.
You can use RMSANLZ interactively or you can direct the output to a
listing file.
The following list summarizes the operations you can
perform with RMSANLZ:
•

Display file attributes,
prolog information

file

header

characteristics,

•

Display key description information for any key of an
file

and

indexed

for each index level of a key, the fill percentage,
• Display,
number of buckets, number of records, number of deleted
records, number of record reference vectors
number of deleted RRVs

B.l

(RRVs) ,

and

the

•

Print, for each bucket on each index level of the key, the
virtual block number, the number of records and RRVs, and the
record IDs of each record

•

Display, for any bucket, the bucket control
record control information, and key values

•

Displ~y

•

Print detailed bucket contents of all buckets

information,

any bucket in hexadecimal dump format

USES OF RMSANLZ

RMSANLZ has two uses:
•

To examine the characteristics of indexed files

•

To provide information on file corruption errors caused either
by application program errors or by RMS or VMS system
failures.

When examining indexed files, RMSANLZ is useful for determining the
effects of file activity, file loading, and file definition options.
For example, if file size is used in loading an indexed file, RMSANLZ
will display the actual fill percentage for further tuning in future
file loads.
B-1

USING THE RMS FILE ANALYZER
RMSANLZ can also be useful in determining the need for
file
reorganization by displaying the number of deleted records and deleted
RRVs in the file. If a large fraction of the records is deleted, then
file reorganization may be advisable.
Whenever file corruption errors occur and an RMS or VMS system failure
is suspected, the complete RMSANLZ analysis of the file should be
included with the Software Performance Report (SPR).

B.2

OPERATING RMSANLZ

The RMS File Analyzer (RMSANLZ) is executed by commands obtained from
SYS$INPUT (terminal or procedure data). The output, by default, is
sent to SYS$0UTPUT or directed to a listing file. You invoke RMSANLZ
by typing:
$ RUN SYS$SYSTEM:RMSANLZ
Control is then passed to RMSANLZ, and RMSANLZ, in turn, displays
following prompt at your terminal:

the

Name of file to analyze:
You respond by typing the
analyzed.

file

specifications

the

file

RMSANLZ then prompts for the file specification to be used for output:
Specify output file, default is SYS$0UTPUT:
You respond with the listing file
indicate SYS$0UTPUT.

specification,

with

<RET>

RMSANLZ then displays the file attribute, file header, and file prolog
information for the file. This information is in a format similar to
a full directory listing, but is more extensive and
includes
infotmation about file area allocations.
An example is shown in
Figure B-1.
DBAO: [RMS.ANLZ]ISAM.IDX:l
5rganization: Indexed with 2 defined ·keys
Record Format: Variable
Record Attributes: Carriage return
Maximum Record Size: 200 bytes
File Protection:
System:RWED Owner:RWED Group:RWE
World:R
File Owner: [011,122]
File ID: (7214~23,l)
Created: 24-JAN-1980 13:48:57.82
Revised: 24-JAN-1980 13:54:36.43 (3)
Expires: <none specified>
File Allocation: 72
Extension: O
End-of-file VBN: 52
First free_byte: O
Allocation Attributes:
Number of areas: 2
Prolog version: 1
Area ID: 0
Area bucketsize: 3
Area extendsize: 21
Alignment: CYL
Options: Contiguous
Current extent:
Start VBN:
Size: 51
Used: 21
Area ID: 1
Area bucketsize: 2
Alignment: None
Options:
Current extent:
Start VBN: 52
Figure B-1

Area extendsize: 10
Size: 21

Sample File Attribute Listing
B-2

Used:

USING THE RMS FILE ANALYZER
If the file is an indexed file, RMSANLZ then prompts for
reference to be analyzed:

the

key

Specify key of reference, default is all keys:
You respond with a key-of-reference number, or w4th <RET> to ask
RMSANLZ to cycle through all the keys starting with the primary key.
RMSANLZ displays the key description as shown in Figure B-2
prompts for the analysis operation to perform for the key:

and

then

Operation:
You respond with one of the following commands:
HELP or ?

or help

- Print this command summary

A(NALYZE)

- Print summary of each index level including
fill percentage, number of buckets, records
RRVs, deleted records, and deleted RRVs

S(HOW)

- Print detailed bucket contents for specified
buckets.
The question "Next VBN:" asks for a
VBN number until <RET> or EOF is entered

L(IST)

- Print detailed bucket contents for all buckets

D(UMP)

- Print VBNs in hexadecimal dump format for
specified buckets.
The question "Next VBN:"
asks for the VBN number until <RET> or EOF is
entered

E(XIT) or <RET>

- Exit from this key and go to command level

Key of Reference: 0
Total Key Size: 10
Number of Key Segments: 2
Key Attributes: Duplicates
Key Position:
16
42
Key Size:
8
2
Area numbers: Data:O Index:l
Data Bucketsize:
1536
Index Bucketsize: 1024
Index Depth: 1
Figure B-2

Key Name: PART NUM ID
Minimum record-length: 44
Key Data Type: String
No Changes
Lowest index level:l
Data fill size: 1200
Index fill size: ~00
Root VBN: 52

Sample Key Information Listing

During the ANALYZE operation, if you answer yes to the question:
See VBN, #Records, #RRVs for each bucket?

Y/N

the VBNs, number of records, and number of RRVs per bucket will be
printed in addition to the summary.
If you answer yes to the
question:
Want to see record IDs for each bucket?

Y/N

the record IDs for each bucket for level O will be printed.
format of the ANALYZE operation output is shown in Figure B-3.

B-3

The

USING THE RMS FILE ANALYZER
Level Number: 1
Level 1 Fill Percentage: 6
Number of buckets on this level: 1
Number of records on this level: 4
Level Number: 0
Bucket VBN Recs Del recs RRVs Del rrvs Fill%
76
1
4
10
0
3
3
2

13
19

5
9

0
0

4
0

2
14

3
1'1

4
7

9
1

10
5

13
15

1
11

3
12

4
13

5
2

6
7

Rec IDs

6
10

1
4

2
7

12
8

15 14
5 13

11
10

14 9

1
9

39
n7

Level O Fill Percentages: 56
Number of buckets on this level: 6
Number of records on this level: 42
Number of RRVs on this level: 2
Number of deleted RRVs on this level: 6

Figure B-3

Sample Key Analysis Listing

The output format for the SHOW and LIST commands includes:
•

Bucket control data including bucket type, index
number, and free space.

level,

area

•

For each record in an index bucket, the record pointer and key
value.

•

For each record in a primary data bucket, the record size
each key value.

and

•

For each record in a secondary data bucket, the key value
all duplicate-record pointers.

and

If file corruption has occurred or an invalid value is entered to
SHOW command, RMSANLZ will display:

the

***** Invalid Bucket VBN: n *****
Using the DUMP command will allow you to examine the corrupted bucket.

B-4

USING THE RMS FILE ANALYZER
If file corruption has occurred or an invalid value is entered to the
SHOW command, RMSANLZ will display:

***** Invalid Bucket VBN: n *****
Using the DUMP command will allow you to examine the corrupted bucket.

B-5

INDEX

A
Assembly-time control block initialization, 2-1
ASSIGN command, 3-10

File specifications, 3-1, 3-9
defaults, 3-8
File types, 3-2, 3-4
defaults, 3-5
File versions, 3-2, 3-4

Bypassing logical name translation, 3-13

c
Calling standard of routines,
2-2

CREATE command, 3-5
Creating an indexed file, 4-10
Creating a relative file, 4-8
dynamically, 4-9
sequential record access mode,
4-8
Creating a sequential file, 4-3
dynamically, 4-5
sequential record access mode,
4-4

Group logical names, 3-11

H
Hardware device,
mass storage, 3-1
record-oriented, 3-1
unique identification, 3-2

Identification of hardware devices, 3-2
Indexed file organization,
random access to, 5-9
sequential access to, 4-11
I/O segment, 2-1

D
Default file types, 3-6
Default process logical names,
3-13

Defaults for logical names, 3-12
Determining file organization
requirements, 1-1
Directory,
master file directory, 3-4
subdirectory, 3-4
user file directory, 3-4

E
Equivalence strings,
logical names, 3-10

L
Logical names,
defaults, 3-10
equivalence strings, 3-10
recursion, 3-9
tables, 3-11
translation, 3-11

M
Mass storage devices, 3-1
Master file directory,
MFD, 3-3
MFD,
master file directory, 3-3

F
File names, 3-2, 3-5
File organization,
advantages and disavantages,

Network node names, 3-2

1-2

determining requirements, 1-1
indexed, 4-10, 5-9
relative, 4-7, 5-6
sequential, 4-1, 5-1

Process control region, 2-1
Process logical names, 3-11
defaults, 3-10
Process-permanent files, 3-14

Index-1

INDEX

R
Random record access mode,
indexed file organization,
5-9
relative file organization,
5-6
sequential file organization,
5-1
Reading an indexed file,
randomly, 5-9
sequentially, 4-11
Reading a relative file,
randomly, 5-6
sequential record access mode,
4-7
Reading a sequential file,
randomly, 5-1
sequential record access mode,
4-2
Record-oriented devices, 3-1
Recursion of logical names, 3-11
Relative file organization,
random access to, 5-6
sequential access to, 4-7
Run-time control block
initialization, 2-1

s
Sequential file organization,
random access to, 5-1
sequential access to, 4-1
Sequential record access mode,
indexed file organization,
4-10
relative file organization,
4-7
sequential file organization,
4-1
Subdirectory, 3-4

System logical names, 3-11
SYS$COMMAND, 3-13
SYS$DISK, 3-13
SYS$ERROR, 3-13
SYS$ INPUT, 3-13
SYS$LOGIN, 3-13
SYS$NET, 3-13
SYS$NODE, 3-14
SYS$SYSDISK, 3-13

T
Translation of logical names,
3-11

bypassing, 3-14

u
UFD,
user file directory, 3-4
.User control block initialization,
assembly time, 2-1
run time, 2-1
User control blocks, 2-1
User file directory,
UFD, 3-4

v
VAX-11 RMS routines
argument list, 2-2
calling standard, 2-2

w
Wild card characters,
in file specifications, 3-8

Index-2

VAX-11
Record Management Services
User's Guide
AA-D781C-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.

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

CitY--~~----~~~~----~~~State __~~--~~-Zip Code __~~~~--nr

Do Not Tear - Fold Here and Tape
No Postage
Necessary
if Mailed in the
United States

POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS 1W/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876