Digital PDFs

AA-0002A-TC

May 1977

207 pages

Original

8.4MB

Document:	IAS/RSX-11M RMS-11 MACRO Programmer's Reference Manual
Order Number:	AA-0002A-TC
Revision:	0
Pages:	207
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11d/RSX11D_V6.2_Feb77/AA-0002A-TC_RMS-11_MACRO_Programmers_Reference_Manual_197705.pdf

OCR Text

IAS/RSX-11M
RMS-11 MACRO Programmer's
Reference Manual
Order No. AA-0002A-TC
,~----------------------------

:<~:,

IAS/RSX-11M

RM$i:i1 MACRO Programmer's
Re·ference Manual
Order No. AA-0002A-TC

digital equipment corporation • maynard. massachusetts

First Printing, May 1977

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

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
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM

DECsystem-lO
DEC tape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECsystem-20

7/78-14

MASSBUS
OMNIBUS
OS/8
PHA

RSTS
RSX
TYPESET-8
TYPESET-lO
TYPESET-II

CONTENTS

Page
xi

PREFACE
CHAPTER 1
1.1
1.1.1
1.1.2
1.1.3
1.1.4
1.2
CHAPTER 2

INTRODUCTION

1-1

RMS-ll OVERVIEW
Declaring RMS-ll Facilities
Accessing Fields in Control Blocks
Allocating and Initializing Control Blocks
Performing File and Record Operations
ORGANIZATION OF INFORMATION IN THIS MANUAL

1-1
1-1
1-2
1-2
1-2
1-2

THE PROGRAM INTERFACE WITH RMS-ll

2-1

2.1
RMS-ll RUNTIME PROCESSING MACROS
2.1.1
RMS-ll File Processing Macros
2.1.2
RMS-ll Record Processing Macros
USER CONTROL BLOCKS
2.2
The File Access Block (FAB)
2.2.1
The Record Access Block (RAB)
2.2.2
Extended Attribute Blocks (XABs)
2.2.3
The Name Block (NAM)
2.2.4
FILE AND RECORD OPERATIONS
2.3
File Operations
2.3.1
New Files and Extended Attribute Blocks
2.3.1.1
Existing Files and Extended Attribute Blocks
2.3.1.2
Record Operations
2.3.2
Record Access Streams
2.3.2.1
Specifying a Record for Access
2.3.2.2
2.3.2.2.1 Sequential Access Mode
2.3.2.2.2 Random Access Mode
2.3.2.2.3 Record's File Address (RFA) Access Mode
CHAPTER 3
3.1
3.2
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.4
CHAPTER 4
4.1

DECLARING RMS-ll FACILITIES
.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED
MACRO DEFINITIONS
ORG$ - DECLARING THE PROCESSING ENVIRONMENT
DECLARING SPACE POOL REQUIREMENTS
POOL$B/POOL$E - Space Pool Declaration
P$BDB - Number of Buffer Descriptor Blocks
P$FAB - Number of Files Open Simultaneously
P$RAB - Non-indexed Record Access Streams
P$RABX - Indexed Record Access Streams
P$IDX - Number of Defined Keys
P$BUF - I/O Buffers
$INIT OR $INITIF - INITIALIZING THE RMS-ll
SYSTEM

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

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME

4-1

$COMPARE - COMPARING THE CONTENTS OF A FIELD

4-2

iii

CONTENTS (CONT.)

Page
4.2
4.3
4.4
4.5
4.6
CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
5.2.6
5.2.7
5.2.8
5.2.9
5.2.10
5.2.11
5.2.12
5.2.13
5.2.14
5.2.15
5.2.16
5.2.17
5.2.18
5.2.19
5.2.20
5.2.21
5.2.22
5.2.23
5.2.24
5.2.25
5.2.26
5.2.27
5.2.28
5.2.29
5.2.30
CHAPTER 6
6.1
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.2.5
6.2.6
6.2.7
6.2~8

6.2.9
6.2.10
6.2.11
6.2.12

$FETCH - COPYING THE CONTENTS OF A FIELD
$OFF - RESETTING BITS WITHIN- A FIELD
$SET - SETTING BITS WITHIN A FIELD
$STORE - CHANGING THE CONTENTS OF A FIELD
$TESTBITS - TESTING BITS WITHIN A FIELD

4-3
4-5
4-5
4-6
4-7

THE FILE ACCESS BLOCK

5-1

ALLOCATING A FILE ACCESS BLOCK
FIELDS IN THE FI~E ACCESS BLOCK
ALQ - Allocation Quantity
BID - Block Identifier
BKS - Bucket Size
BLN - Block Length
BLS - Block Size
BPA - Buffer Pool Address
BPS - Buffer Pool Size
CTX - User Context Area
DEQ - Default File Extension Quantity
DEV - Device Characteristics
DNA - Default Name String Address
DNS - Default Name String Size
FAC - File Access
FNA - File Name String Address
FNS - File Name String Size
FOP - File Processing Options
FSZ - Fixed Control Area Size
IFI - Internal File Identifier
LCH - Logical Channel Number
MRN - Maximum Record Number
MRS - Maximum Record Size
NAM - Name Block Address
ORG - File Organization
RAT - Record Attributes
RFM - Record Format
RTV - Retrieval Window Size
SHR - File Sharing
STS - Completion Status Code
STV - Status Value
XAB - Extended Attribute Block Pointer

5-4
5-4
5-6
5-7
5-7
5-9
5-9
5-10
5-11
5-12
5-13
5-14
5-14
5-15
5-16
5-17
5-18
5-18
5-20
5-20
5-21
5-21
5-22
5-23
5-24
5-24
5-25
5-26
5-26
5-27
5-27
5-27

THE RECORD ACCESS BLOCK

6-1

ALLOCATING A RECORD ACCESS BLOCK
FIELDS IN THE RECORD ACCESS BLOCK
BID - Block Identifier
BKT
Bucket Code
BLN
Block Length
CTX
User Context Area
FAB
File Access Block Address
lSI
Internal Stream Identifier
KBF
Key Buffer Address
KRF
Key of Reference
KSZ
Key Size
MBC
Multi-block Count
MBF
Multi-buffer Count
RAC
Record Access Mode

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

CONTENTS (CONT.)

Page
6.2.13
6.2.14
6.2.15
6.2.16
6.2.17
6.2.18
6.2.19
6.2.20
6.2.21
CHAPTER 7
7.1
7.2
7.3
7.4
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
7.4.9
7.4.10
7.4.11
7.4.12
7.5
7.5.1
7.5.2
7.5.3
7.6
7.6.1
7.6.2
7.6.3
7.6.4
7.6.5
7.6.6
7.6.7
7.6.8
7.7
CHAPTER 8
8.1
8.2
8.2.1
8.2.2
8.2.3
CHAPTER 9
9.1
9.1.1
9.1.2

RBF RFA RHB ROP RSZ: STS STV UBF USZ -

Record Address
Record's File Address
Record Header Buffer
Record Processing Options
Record Size
Completion Status Code
Status Value
User Record Area Address
User Record Area Size

6-11
6-11
6-12
6-12
6-14
6-15
6-15
6-15
6-16

EXTENDED ATTRIBUTE BLOCKS

7-1

ALLOCATING AN EXTENDED ATTRIBUTE BLOCK
LINKING AND ORDERING EXTENDED ATTRIBUTE BLOCKS
DATE AND TIME EXTENDED ATTRIBUTE BLOCKS
KEY DEFINITION EXTENDED ATTRIBUTE BLOCKS
DAN - Area Number for Data Buckets
DFL - Data Bucket Fill Size
FLG - Key Options
IAN - Area Number for Index Buckets
IFL - Index Bucket Fill Size
KNM - Key Name Address
LAN - Lowest Index Level Area Number
NUL - Null Key Value
POS - Key position
REF - Key of Reference
RVB - Root Virtual Block Number
SIZ - Key Size
FILE PROTECTION SPECIFICATION EXTENDED
ATTRIBUTE BLOCK
PRG - Programmer Number
PRJ - Project Number
PRO - System File Protection Value
ALLOCATION EXTENDED ATTRIBUTE BLOCKS
AID - Area Identification Number
ALN - Alignment Boundary Type
ALQ - Allocation Quantity
AOP - Allocation Options
BKZ - Bucket Size
DEQ - Default Area Extension Quantity
LOC - Allocation Starting Point
VOL - Relative Volume Number
SUMMARY EXTENDED ATTRIBUTE BLOCK

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

THE NAME BLOCK

8-1

ALLOCATING A NAME BLOCK
FIELDS IN THE NAME BLOCK
ESA - Expanded String Address
ESL - Expanded String Length
ESS - Expanded String Size

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

PERFORMING FILE AND RECORD OPERATIONS

9-1

FILE AND RECORD OPERATION MACRO CONVENTIONS
Format of File and Record Operation Macros
The RMS-11 Calling Sequence

9-1
9-2
9-3

7-16
7-17
7-17
7-18
7-19
7-21
7-21
7-22
7-23
7-24
7-24
7-25
7-26
7-26

CONTENTS (CONT.)

Page
Completion Routine Conventions
Register Usage Conventions Within
Completion Routines
Issuing RMS-ll Macro Calls Within
9.1.3.2
Completion Routines
Returning From a Completion Routine
9.1.3.,3
Control Block Field Usage
9.1.4
Status Codes .
9.1.5
PERFORMING FILE OPERATIONS
9.2
$CREATE - Creating an RMS-ll File
9.2.1
$OPEN - Opening an Existing File for
9.2.2
Processing
$DISPLAY - Obtaining Attributes of a File
9.2.3
$ERASE - Deleting a File
9.2.4
$EXTEND - Extending Allocated Space
9.2.5
$CLOSE - Terminating File Processing
9.2.6
PERFORMING RECORD OPERATIONS
9.3
Record Access Streams
9.3.1
$CONNECT - Establishing a Record Access
9.3.1.1
Stream
$DISCONNECT - Terminating a Record Access
9.3.1.2
Stream
Record Operations and File Sharing
9.3.2
File Organizations and File Sharing
9.3.2.1
Program Sharing Information
9.3.2.2
Bucket Locking
9.3.2.3
Current Context of Record Operations
9.3 .. 3
Understanding the Current Record
9.3.3.1
Understanding the Next Record
9.3.3.2
Synchronous and Asynchronous Record
9.3.4
Operations
Accessing Records
9.3.5
Specifying an Access Mode
9.3.5.1
Specifying a Record Transfer Mode
9.3.5.2
The RBF and RSZ Fields of the RAB
9.3.5.2.1
The UBF and USZ Fields of the RAB
9.3.5.2.2
Record Operation Macros
9.3.6
$FIND - Locating and Obtaining the RFA of a
9.3.6.1
Record
$FIND and the Sequential File Organization
9.3.6.1.1
9.3.6.1.2
$FIND and the Relative File Organization
9.3.6.1.3
$FIND and the Indexed File Organization
9.3.6.2
$GET - Retrieving a Record
9.3.6.2.1
$GET and the Sequential File Organization
9.3.6.2.2
$GET and the Relative File Organization
9.3.6.2.3
$GET and the Indexed File Organization
9.3.6.3
$PUT - Writing a New Record to a File
9.3.6.3.1
$PUT and the Sequential File Organization
$PUT and the Relative File Organization
9.3.6.3.2
$PUT and the Indexed File Organization
9.3.6.3.3
$UPDATE - Rewriting an Existing Record
9.3.6.4
$UPDATE and the Sequential File Organization
9.3.6.4.1
$UPDATE and the Relative File Organization
9.3.6.4.2
$UPDATE and the Indexed File Organization
9.3.6.4.3
$DELETE - Deleting a Record
9.3.6.5
$REWIND - Positioning to the Beginning of
9.3.6.6
a File

9.1.3
9.1.3.1

9-4
9-4
9-4
9-5
9-5
9-6
9-6
9-7
9-9
9-12
9-13
9-14
9-16
9-17
9-17
9-18
9-19
9-20
9-20
9-20
9-21
9-23
9-25
9-25
9-26
9-28
9-28
9-28
9-29
9-29
9-30
9-31
9-32
9-32
9-32
9-33
9-35
9-35
9-35
9-35
9-37
9-37
9-37
9-38
9-39
9-39
9-39
9-40
9-41

CONTENTS (CONT.)

Page
9.3.6.7
9.3.6.8
9.3.6.9
APPENDIX A
A.l
A.2
A.3
A. 3.1
A.3.2
APPENDIX B
B.l
B.2
B.3
B.4
APPENDIX C

$TRUNCATE - Truncating a Sequential File
$FLUSH - Writing Out Modified I/O Buffers
$NXTVOL - Continue Processing on Next Volume
COMPLETION STATUS CODES

A-I

SUCCESSFUL COMPLETION STATUS CODES
ERROR COMPLETION STATUS CODES
FATAL ERROR CRASH ROUTINE
Fatal User Call Errors
RMS-ll Inconsistent Internal Conditions
Errors

A-2
A-2
A-13
A-13

PERFORMING BLOCK I/O

B-1

SPECIFYING BLOCK ACCESS
$READ - RETRIEVING VIRTUAL BLOCKS
$WRITE - WRITING VIRTUAL BLOCKS
$SPACE - FORWARD AND BACKWARD SPACING OF
MAGNETIC TAPE FILES

B-1
B-2
B-3

MAGNETIC TAPE HANDLING

C-l

MAGNETIC TAPE FILE PROCESSING
C.l
Access to Magnetic Tape Volumes
C.l.l
Rewinding Volume Sets
C.l.2
Positioning to the Next File Position
C.l.3
Single File Operations
C.l.4
Multiple File Operations
C.l.S
C.2
VOLUME AND FILE LABELS
Volume Label Format
C.2.1
Contents of Owner Identification Field
C.2.1.1
User Volume Labels
C.2.2
File Header Labels
C.2.3
File Identifier Processing by RMS-ll
C.2.3.1
C.2.4
End-of-Volume Labels
File Trailer Labels
C.2.S
User File Labels
C.2.6
C.3
FILE STRUCTURES
C.3.1
Single File Single Volume
Single File Multi-Volume
C.3.2
C.3.3
Multi-File Single Volume
C.3.4
Multi-File Multi-Volume
C.4
END OF TAPE HANDLING
C.S
ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS
COMPATIBLE)
APPENDIX D

9-42
9-42
9-43

A-14

B-4

C-l
C-l
C-l
C-2
C-2
C-3
C-3
C-3
C-4
C-5
C-5
C-8
C-9
C-9
C-9
C-9
C-9
C-10

C-IO
C-IO
C-10
C-10

FORMULAS

D-l

SEQUENTIAL FILES - AVERAGE RECORDS PER BLOCK
RELATIVE AND INDEXED FILES - AVERAGE DATA
RECORDS PER BUCKET
INDEXED-FILES - AVERAGE ENTRIES PER INDEX
AND ALTERNATE KEY DATA LEVEL

0-1

APPENDIX E

SAMPLE CODE SEGMENTS

E-l

APPENDIX F

ASSEMBLING AND TASK BUILDING

F-l

D.l
D.2
D.3

vii

0-2
0-3

CONTENTS (CONT.)

Page
INDEX

Index-l
FIGURES

FIGURE

7-1
7-2
9-1
C-l

Format of PRO Field
File Access Bits
Argument List Format
ANSI Magnetic Tape File Header Block (FCS
Compatible)

7-18
7-18
9-3
C-ll

TABLES
TABLE

2-1
2-2
2-3
3-1
3-2
4-1
5-1
6-1
6-2
7-1
7-2
7-3
7-4
7-5
7-6
8-1
9-1
9-2
9-3
9-4
9-5
9-6
9-7
9-8
9-9
9-10
9-11
9-12
9-13
9-14
9-15
9-16
9-17
9-18
9-19
9-20
9-21
9-22
A-I
A-2
B-1

RMS-ll File Processing Macros
RMS-ll Record Processing Macros
User Control Blocks
Minimum Set of .MCALL Directives
Space Pool Declaration Macros
Runtime Field Access Macros
File Access Block Fields
Record Access Block Fields
Minimum and Maximum Number of Buffers
Date and Time XAB Fields
Key Definition XAB Fields
Key Option Combinations
File Protection Specification XAB Fields
Allocation XAB Fields
Summary XAB Fields
Name Block Fields
RMS-ll File Operation Macros
$CREATE FAB Fields
$OPEN FAB Fields
$DISPLAY FAB Fields
$ERASE FAB Fields
$EXTEND FAB Fields
$CLOSE FAB Fields
$CONNECT RAB Fields
$DISCONNECT RAB Fields
$FREE RAB Fields
Record Access Stream Context After Record
Operations
$WAIT RAB Fields
RMS-ll Record Processing Macros
$FIND RAB Fields
$GET RAB Fields
$PUT RAB Fields
$UPDATE RAB Fields
$DELETE RAB Fields
$REWIND RAB Fields
$TRUNCATE RAB Fields
$FLUSH RAB Fields
$NXTVOL RAB Fields
Successful Completion Status Codes
Error Completion Status Codes
$READ RAB Fields
viii

2-2
2-3
2-4
3-2
3-5
4-1
5-5
6-2
6-9
7-3
7-4
7-7
7-16
7-20
7-26
8-2
9-7
9-8
9-10
9-13
9-14
9-15
9-16
9-18
9-19
9-23
9-23
9-27
9-30
9-31
9-33
9-36
9-39
9-41
9-41
9-42
9-43
9-44
A-2
A-2
B-2

CONTENTS (CONT.)

TABLES
B-2
B-3
C-l
C-2
C-3
0-1
0-2
0-3

$WRITE RAB Fields
$SPACE RAB Fields
Volume Label Format
File Header Label (HOR1)
File Header Format (HOR2)
Average Records Per Block in Sequential Files
Average User Data Records per Bucket
Average Entries Per Index and Alternate Key
Oata Level Bucket

B-4
B-4
C-3
C-6
C-7
0-1
0-2

0-3

PREFACE

This manual contains a complete description of RMS-Il
(Record
Management Services for the PDP-II)
as implemented on the lAS and
RSX-llM operating systems.
Because the file and record services
described herein apply to MACRO-II programs, you should be familiar
with both the RSX-ll MACRO-II REFERENCE MANUAL and an appropriate
PDP-II
PROCESSOR
HANDBOOK.
Additionally, you should read the
INTRODUCTION TO RMS-ll MANUAL before us~ng this manual.
Throughout this manual, the following
description of RMS-Il macro syntax.

conventions

are

used

the

Upper case words and letters, and punctuation marks other
than those described in this preface, are written as shown.

Lower case words indicate that a value is to be substituted.
The accompanying text specifies the nature of the item to be
substituted.

Square brackets ([]), unless used
enclose optional items.

An ellipsis ( ••• ) indicates that the preceding item
bracketed group may be repeated any number of times.

OIC

specification,

Lastly, unless otherwise noted, decimal radix is used for
values in all examples and accompanying explanatory text.

numeric

CHAPTER 1
INTRODUCTION

1.1

RMS-ll OVERVIEW

Record Management Services for PDP-II operating systems (RMS-ll) is a
set of routines that enables programs to process files and records
within files. RMS-ll's variety of file organizations and record
access modes gives you the ability to choose processing methods best
suited to your application.
RMS-ll
files
can
be
organized
sequentially, relatively, or with embedded indexes. Using these file
organizations, you can access records in a number of ways:
1.

Sequentially.

Randomly by relative record number, key
file address (RFA).

Dynamically through a mixture of sequential and random access
modes.

value,

record's

Through control blocks allocated in your program at assembly time, you
transmit file and record operation requests to RMS-ll. Through these
same control blocks, RMS-ll returns to you the data contents of files,
attribute information about files, and status codes.
To utilize RMS-ll facilities, you must understand how to:

1.1.1

Declare the RMS-ll facilities that your program requires.

Access fields in control blocks at runtime.

Allocate and initialize control blocks.

Perform file and record operations.

Declaring RMS-ll Facilities

Before processing an RMS-ll file, you must declare the RMS-ll
facilities that your program requires and allocate space in your
program for I/O buffers and internal RMS-ll control structures.
RMS-ll provides a set of macros that allows you to calculate buffer
and control structure requirements and provide for the selective
linking of only those portions of RMS-ll actually required by your
program.

1-1

INTRODUCTION
1.1.2

Accessing Fields in Control Blocks

You communicate with RMS-ll through control blocks.
Control blocks
are formatted areas in your program. Each control block consists of
individual data fields. At runtime, you can access control block data
fields through special RMS-ll macros.

1.1.3

Allocating and Initializing Control Blocks

You must allocate space in your program for control blocks at
assembly-time. Additionally, you can establish initial values for the
fields in these blocks through assembly-time initialization macros.

1.1.4

Performing File and Record Operations

In combination with control blocks, a set of RMS-ll file and record
operation macros forms the complete runtime program interface with
RMS-ll. Each such macro represents a request for a particular file or
record service provided by RMS-ll.
The fields of control blocks
further describe the request. Using particular RMS-ll macros, you
can:

1.2

•

Create new files

•

Process existing files

•

Extend or delete files

•

Read, write, update, or delete records within files

ORGANIZATION OF INFORMATION IN THIS MANUAL

The organization of this manual corresponds to the areas discussed in
the previous overview.
However, an additional chapter is provided.
Chapter 2 provides an overview of the program interface with RMS-ll,
including runtime processing macros and user control blocks and the
interaction between these elements to produce file and
record
operations.
Chapter 3 describes the declaration of RMS-ll facilities.
It includes
descriptions of macros that declare the use of other macros, cause the
initialization of the RMS-ll system at runtime, declare buffer and
control structure space requirements, and specify the processing
environment.
Chapter 4, on accessing control block fields at runtime, describes a
set of general-purpose macros. These macros result in the generation
of code that, at runtime, manipulates the contents of control block
fields.
Chapter 5 discusses the allocation of the user control block known as
the
File
Access
Block (FAB).
This chapter further provides
descriptions of the function of each field in the FAB and the macros
provided by RMS-ll to initialize these fields at assembly-time.
Chapter 6 describes the user control block known as the Record
Block (RAB).

1-2

Access

INTRODUCTION
Chapter 7 details control blocks known as
(XABs).

Extended

Attribute

Blocks

Chapter 8 discusses the Name Block (NAM).
Chapter 9 details file and record operations.
In addition to
describing the macros that cause these operations, this chapter also
discusses establishing and terminating a record aGcess stream, the
current context of record operations, file sharing, synchronous and
asynchronous operations, and record transfer modes.
Additionally, a number of appendixes provide detailed information of
further ·interest.
Appendix A lists the status codes returned by
RMS-ll. Appendix B describes block I/O, a facility that allows your
program to bypass entirely the record processing capabilities of
RMS-ll. Appendix C summarizes the handling of ANSI-labeled magnetic
tapes.
Appendix D contains formulas enabling you to calculate the data
capacities of RMS-ll files. Sample code segments demonstrating the
program interface to RMS-ll are shown in Appendix E.
Finally, Appendix F summarizes the steps you must take to assembly and
task build programs that use RMS-ll facilities.

1-3

CHAPTER 2
THE PROGRAM INTERFACE WITH RMS-ll

To obtain RMS-ll services at runtime, your program must contain
processing macros and user control blocks. This chapter introduces
these macros and control blocks and summarizes their role in the
processing
of
RMS-ll
files.
Subsequent chapters expand this
introductory material and provide the detailed information necessary
to write programs that use RMS-ll facilities.
RMS-ll processing macros are expanded at assembly-time. The resulting
code is executed at runtime to perform the desired operation.
Each
macro represents a program request for
a file or record related
service.
With every request for a service,
information is exchanged between
your program and RMS~ll.
User control blocks are the means by which
this exchange occurs.
Prior to issuing a request for an RMS-ll
service, your program must place information detailing the request in
a control block.
For example, a request to open a file must be
accompanied by the name of the file, information on how the file will
be accessed, and details on how the file is to be shared. As another
example,
a program request to read a record from a file must specify
an access mode and,
if appropriate,
a key value identifying the
desired record.
After a request for service has been processed, RMS-ll uses the same
control block to return information to your program. When a file has
been successfully opened, RMS-ll provides attribute information such
as the organization of the file and the format of the records in the
file.
After successfully obtaining a record from a file,
RMS-ll
provides your program with the location in memory and length of the
record retrieved.
The amount of information exchanged between RMS-ll and your program
varies with the nature of the request and the attributes of the file
being processed.
Detailed information on the input to and output from
each type of runtime processing macro is provided in Chapter 9 of this
manual.
This current chapter emphasizes only the general interface
used by a program when requesting RMS-ll services. This interface is
described in three sections:
•

Runtime processing macros

•

User control blocks

•

File and record operations

2-1

THE PROGRAM INTERFACE WITH RMS-II
Table 2-3
User Control Blocks
Block Name

Function

File Access Block (FAB)

Describes a file and contains
file-related information.

Record Access Block (RAB)

Describes
a
contains
information.

Extended Attribute Blocks (XABs)

Contain
file
attribute
information beyond that in the
FAB.

Name Block (NAM)

Describes
a
location
containing the expanded file
specification resulting from
the
application of default
values to a
primary
name
string.

The sUbsections that follow describe
Table 2-3.

2.2.1

each

control

record
and
record-related

block

listed

The File Access Block (FAB)

At runtime, a File Access Block (FAB) represents a particular file.
The
fields of the FAB are used to contain such file-related
information as:

2.2.2

•

The name of file

•

The organization of the file

•

The operations your program will perform on the file

•

The format of records within the file

•

Record size information

•

Allocation information

The Record Access Block (RAB)

A Record Access Block (RAB) is needed whenever individual records in a
file are to be accessed.
A RAB describes an individual record.
It is used to communicate
information about that record between your program and RMS-II. Once a
file has been opened, you will use the fields of the RAB to describe a
record to be accessed.

2-4

THE PROGRAM INTERFACE WITH RMS-II
2.2.3

Extended Attribute Blocks (XABs)

There are several types of Extended Attribute Blocks
(XABs).
Each
type contains fields that represent one attribute of a file. These
attributes supplement those attributes in a File Access Block.
Specifically, there are Extended Attribute Blocks that describe:
•

File creation and revision dates

•

Primary and alternate key definitions for indexed files

•

File protection specification

•

Allocation information

You may use Extended Attribute Blocks when you:
1.

Create a new file.

Request that RMS-Il transmit the extended
existing file to your program.

attributes

In the first instance, your program uses XABs to pass file definition
information to RMS-ll.
In the second instance, RMS-Il requires XABs
in order to pass attribute information to your program.

2.2.4

The Name Block (NAM)

A Name Block (NAM) is an optional user control block.
It is used to
contain the full file specification resulting from the merger of
explicit file name information with program- and system-provided
defaults.

2.3

FILE AND RECORD OPERATIONS

To obtain any RMS-Il service, your program uses a combination of a
runtime processing macro call and a user control block. The primary
argument of every runtime processing macro, therefore, is the address
of a user control block.
In the following sections, the division of RMS-ll services into file
and rec?rd operations is continued to show the relationship of runtime
processlng macros with particular user control blocks. For each type
of operation, the relationship among control blocks is described.

2.3.1

File Operations

The primary argument of a file processing macro call is the address of
a FAB.
The macro call itself represents the type of file service
requested (e.g., $OPEN, $DISPLAY, $CLOSE, etc.) and the FAB identifies
a specific file associated with the request. The combination of macro
call and FAB results in a file operation.
Since each FAB represents a single file, your program must contain one
FAB for each file that is open simultaneously.

2-5

THE PROGRAM INTERFACE WITH RMS-ll
You can optionally associate a Name Block
(NAM) with a FAB.
This
association involves setting the address of the NAM in a data field of
the FAB before the file is opened. While opening the file, RMS-ll
places the results of the merger of explicit and default file
specification information in an area described by the Name Block.
Your program can also associate Extended Attribute Blocks (XABs) with
a File Access Block. The presence and purpose of associated XABs are
related to whether a new file or an existing file will be processed.
In both instances, the presence of associated XABs is indicated by the
address of the first such block in a data field of the FAB.
When
multiple XABs for the same file are present, they are chained together
through address fields in the XABs themselves.

2.3.1.1 New Files and Extended Attribute Blocks - You create a new
RMS-ll file through a combination of the $CREATE macro call and a File
Access Block. You will use the FAB to pass to RMS-ll a description of
the primary attributes of the file, such as the file's organization
and the format and size of the records the file will contain.
However, there are no fields
in a FAB that allow you to specify
optional file attributes such as a protection specification, nor does
the FAB allow you to define keys for an indexed file. Therefore, you
will use XABs to pass to RMS-ll descriptions of file attributes beyond
those contained in the FAB.

2.3.1.2 Existing Files and Extended Attribute
Blocks - Extended
attribute blocks are never used to define or alter the attributes of
an existing file. The attributes of a file are fixed at the time you
create the file.
Thereafter, these attributes cannot be altered.
However, there are two occasions when XABs are associated with a FAB
that represents an existing file:
1.

Your program contains a $DISPLAY macro.

You wish automatically to obtain extended file attributes
additional outputs of the $OPEN macro.

When your program issues a $DISPLAY macro call, RMS-ll retrieves the
address of an XAB from a field in the FAB associated with the call.
This XAB may be the first of a chained list of such blocks.
Further,
each block is self-identifying.
That is, a field in the block
specifies the type of information the block can contain, e.g., key
definition, file protection specification, etc. Based on the types of
XABs present, RMS-ll obtains the specified attribute information from
the file and stores it in the appropriate XABs.
When your program issues an $OPEN macro call, RMS-ll examines the FAB
associated with the call for the address of an XAB.
If this block
(possibly a chain of blocks) is present, RMS-ll automatically returns
the appropriate attribute information into the fields of the block.

2-6

THE PROGRAM INTERFACE WITH RMS-ll
2.3.2

Record Operations

The primary argument of a record processing macro (e.g., $GET, $PUT,
etc.)
is the address of a Record Access Block. The macro call
represents the type of record service requested and the RAB identifies
a record associated with the request. The combination of macro call
and RAB results in a record operation.
Once a file has been opened by a $OPEN or $CREATE file operation, your
program must activate a record access stream before performing record
operations. After a record access stream has been activated, your
program can specify a record for access through the use of three
RMS-ll access modes. The following subsections, therefore, describe:
•

Record access streams

•

Specifying a record for access

2.3.2.1 Record Access Streams - A record access stream is
the
association of a RAB with a FAB. This association occurs through the
issuance of a $CONNECT macro call. Once this association has been
established, your program can process records in the file represented
by the FAB. When processing a relative or indexed file, you can
associate more than one RAB with the same FAB. Each association
represents an independent record access stream to the same file.
For
example, your program could access records within an indexed file by
primary key while, through a second record access stream, accessing
records within the same file through the index associated with an
alternate key.
At any point in time, a particular RAB can be associated with only a
single FAB.
The number of RABs required by a program, therefore,
depends on the maximum number of record access streams active
simultaneously.

2.3.2.2 Specifying a Record for Access - The organization of a file
establishes the techniques (called access modes) that can be used to
specify records for access. The organization of a file is fixed at
the time the file is created. The access mode used to process records
in a file, however, can be different each time the file is opened.
Further, your program can dynamically switch from one access mode to
another during the runtime processing of a file.
RMS-ll supports three record access modes:
1.

Sequential

Random

Record's File Address (RFA)

The following subsections describe each access mode.

2.3.2.2.1 Sequential Access Mode - When using sequential access mode,
your program issues a series of requests for the next record. RMS-ll
interprets these requests in the context of the organization of the
file being processed.
Thus, the order in which records are read or
written is governed by the structure, or organization, of the file.

2-7

THE PROGRAM INTERFACE WITH RMS-ll
2.3.2.2.2 Random Access Mode - In random access mode, your program,
rather than the organization of the file being accessed, determines
the order in which records are processed. Each program request for a
record specifies, through fields in the RAB, the identification of the
record of interest. Thus, when using random access mode, your program
does not read or write the next record.
Rather, your program
identifies a particular record. The identifier associated with the
request allows RMS-ll to locate the record within the file.
The
random access mode cannot be used with sequentially organized files.
Both the relative and indexed file organizations, however, permit
random access to records.

2.3.2.2.3 Record's File Address (RFA) Access Mode - Record's file
address
(RFA) access mode is similar to random access mode in that it
allows a specific record to be identified for retrieval.
It can be
used with any file organization so long as the file resides on a disk
device.
It cannot, however, be used for write operations.
The term record's file address is meant to convey the notion that
every record within a file has a unique address. The actual format of
this address depends on the organization of the file.
In all
instances, however, only RMS-Il can interpret this format.
The most important feature of record's file address access is that the
RFA of any record remains constant while the record exists in the
file. After every successful $GET, $PUT, or $FIND operation, the RFA
of the desired record is returned by RMS-ll in a field of the Record
Access Block associated with the operation.
Your program can then
save this RFA to be used again later to retrieve the same record.
It
is not required that an RFA be used for subsequent retrieval only
during the current execution of the program.
During a file's
existence, RFA's can be used at any subsequent point in time.

2-8

CHAPTER 3
DECLARING RMS-ll FACILITIES

Every program that processes RMS-ll files must contain directives and
special-purpose macros that declare the RMS-ll facilities required at
assembly-time and at runtime. This chapter describes these directives
and macros.
To declare RMS-ll facilities that are used by your program,
do the following:

List RMS-ll macros in .MCALL directives.

Declare the processing environment.

Declare space pool requirements.

Issue an $INIT or an $INITIF macro.

you

must

The sections of this chapter describe each of these requirements.
NOTE
Unless otherwise
use decimal as
numeric values.

3.1

noted, RMS-ll macros
the default radix for

.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO DEFINITIONS

All macro calls issued in your program must be listed as arguments in
an • MCALL directive. Listing the macro calls in this way allows the
corresponding macro definitions to be read in from macro libraries
during assembly.
Each .MCALL directive takes the following form:
• MCALL

argl,arg2, ••• ,argn

where
argl,etc.

represents a list of symbolic names of the macro
definitions
required in the assembly of the
program. Macro names may be listed in any order.

The number of .MCALL directives needed for RMS-ll macros can be
minimized.
Table 3-1 lists a set of macro names. The definitions in
the system macro library for most of these macros contain embedded
.MCALL directives. These embedded .MCALL directives list as arguments
the names of additional RMS-ll macros.
Thus, by providing .MCALL
3-1

DECLARING RMS-ll FACILITIES
directives with the names of the macros in Table 3-1, you effectively
can provide .MCALL directives for any and all RMS-II macros used in a
program.
Table 3-1
Minimum Set of .MCALL Directives
Us.er Supplied
.MCALL Argument

Embedded .MCALL Arguments

ORG$

(none)

POOL$B

Space pool declaration macros
Section 3.3).

$INIT or $INITIF

(none)

$GNCAL

Runtime field manipulation macros
(described
in Chapter 4) and completion routine macros
(described in Chapter 9).

FAB$B

File
Access
initialization

(described

Block
allocation
and
macros
(described in Chapter

5) •

RAB$B

Record
Access
Block
allocation
and
initialization macros
{described in Chapter
6) •

XAB$B

Extended Attribute Block
allocation
and
initialization macros
(described in Chapter
7) •

NAM$B

Name Block allocation and
initialization
macros (described in Chapter 8).

$FBCAL

File processing macros

(described in

Chapter

9) •

$RBCAL

Record processing
Chapter 9).

macros

{described

As shown in Table 3-1, you can ensure that all RMS-ll macros used in a
program appear as arguments
in .MCALL directives by coding the
following sequence of .MCALL directives and macro calls.
• MCALL
.MCALL
• MCALL
$GNCAL
$FBCAL
$RBCAL

ORG$,POOL$B,$INIT
$GNCAL,FAB$B,RAB$B,XAB$B,NAM$B
$FBCAL,$RBCAL

In the preceding example, the $GNCAL, $FBCAL and $RBCAL macro calls
are issued after being listed in .MCALL directives.
By issuing these
macro calls, you will cause the embedded • MCALL directives to take
effect.
Naturally, you can omit any macro names from • MCALL
directives that do not apply to a particular program.
If Name Blocks
or Extended Attribute Blocks are not used, for example, there would be
no need for listing the NAM$B or XAB$B macros.
Further, you may
choose not to use the $RBCAL or $FBCAL macros, for example, but rather
3-2

DECLARING RMS-ll FACILITIES
to list separately each record processing and
actually appearing in your program.

3.2

file

processing

macro

ORG$ - DECLARING THE PROCESSING ENVIRONMENT

You must include one or more ORG$ macros within the set of modules
that you will link together through the Task Builder to produce an
executable task.
NOTE
All ORG$ macros must be in modules that
are part of the root of your task. An
ORG$ macro for
a
particular
file
organization must be present even if no
record operations are performed when
such a file is opened.
The presence of ORG$ macros in your source modules allows the Task
Builder to select for linking only those portions of RMS-Il actually
required by your program.
Each ORG$ macro declares a
unique
combination of file organization and record operations.
The ORG$ macro takes the following form:
ORG$ org[,<recop[,recop ••• ]>]
where
org

is the type of file organization to be processed.
One of the following symbolic values must be
specified:
lOX - indexed file organization
REL - relative file organization
SEQ - sequential file organization

recop

is a symbolic value identifying a
type
of
operation that will be performed on a file of the
specified organization.
If a single value is
specified, the angle brackets are not needed.
If
multiple values are specified, you must enclose
them in angle brackets and use commas to separate
each value from the preceding value. One or more
of the following may be specified in any order:
eRE - indicates a file of the
organization may be created
DEL - indicates $OELETE operations
FIN - indicates $FINO operations
GET - indicates $GET operations
PUT - indicates $PUT operations
UPD - indicates $UPOATE operations
3-3

specified

DECLARING RMS-ll FACILITIES
The following is an example of the use of
module:
ORG$
ORG$
ORG$

ORG$

macros

source

SEQ,<CRE,PUT)
IDX,<GET,UPD,FIN)
REL

In this example, the user declares that one or more sequential files
will be created and $PUT operations performed. One or more indexed
files will be opened and $GET, $UPDATE, and $FIND operations will be
performed on such files.
Finally, one or more relative files will be
opened but no record operations will be performed (possibly such files
will be opened only for the purpose of issuing an $EXTEND or $DISPLAY
file operation).

3.3

DECLARING SPACE POOL REQUIREMENTS

RMS-li requires a collection of I/O buffers and internal control
structures to support file processing at runtime. The area in your
program occupied by these buffers and control structures is known as
the space pool. RMS-ll provides facilities that ensure that the space
pool is large enough to accommodate only the requirements of the
largest number of files that can be open simultaneously. By using
these facilities at assembly-time, your program provides information
that allows RMS-Il to calculate the minimum size requirements of the
space pool.
The major portion of the space pool is composed of I/O buffers.
To
the user program, record processing under RMS-il appears as the
movement of records directly between a file and the program itself.
Transparent to the user program, however, RMS-il actually reads and
writes either virtual blocks or buckets into I/O buffers.
When the
organization of a particular file is sequential, RMS-ll reads or
writes virtual blocks.
For relative and indexed files,
RMS-ll reads
or writes buckets.
The size of I/O buffers depends on the organizations of the files
being processed, the number of files open simultaneously, and the
number of simultaneously active record access streams.
In providing
the information needed to calculate the size requirements for the I/O
buffers portion of the space pool, you have two choices:
1.

A completely centralized space pool.

Private I/O buffers for one or more files.

In a completely centralized space pool, all I/O buffers as well as the
internal
control
structures
required for file processing are
inaccessible to your program. RMS-li totally manages the space within
the pool and allocates portions, as needed, for buffer space and
control structures for open files.
Unlike a completely centralized space pool, the use of private I/O
buffers allows you some measure of control over I/O buffer space. You
can allocate private I/O buffers on a per-file basis by specifying the
address and total size of these buffers in fields of the File Access
Block associated with a file. When the file is open,
this buffer
space is completely managed by RMS-ll and your program must not access
it. However, when the file is closed, the private I/O buffer space is
available for use by your program.

3-4

DECLARING RMS-ll FACILITIES
is
avoidance
of
The major advantage of private I/O buffers
fragmentation
of
a
completely centralized space pool.
Since
particular files have varying buffer requirements based on their
organization, a centralized space pool can reach the point where there
is sufficient total space available for the opening of an additional
file but the space is not contiguous. When such a situation arises,
the desired file cannot be opened.
Whether you choose a completely centralized space pool or private I/O
buffers, RMS-ll always requires certain internal control structures
that must be allocated in the space pool to support file processing.
Unlike the handling of I/O buffers, your program can never access
these control structures or recover the space they occupy.
The number of internal control structures required by RMS-ll in the
space pool is based on the organizations of the files being processed,
the maximum number of files open simultaneously, and the maximum
number of simultaneously connected record access streams. Once again,
your program must provide, at assembly-time, the information needed to
determine the size requirements of the internal control structures
that must be allocated in the space pool.
The presence in your source modules of the macros listed in Table 3-2
allows RMS-ll to determine the size requirements for your program's
space pool. The descriptions following the table identify those
macros that are always required and those that are needed only in
specific instances. If you want private I/O buffers for one or more
files, you must also refer to the descriptions of the BPA (buffer pool
address) and BPS (buffer pool size) fields in Chapter 5.
Table 3-2
Space Pool Declaration Macros
Description

Macro

3.3.1

POOL$B

Beginning of space pool declaration

P$BDB

Number of buffer descriptor blocks

P$FAB

Number of files open simultaneously

P$RAB

Non-indexed
record
simultaneously

P$RABX

Indexed record access streams active simultaneously

P$IDX

Number of defined keys

P$BUF

Input/output buffer requirements

POOL$E

End of space pool declaration

access

streams

active

POOL$B/POOL$E - Space Pool Declaration

The POOL$B macro is required.
space pool definition macros.

It marks the beginning of a sequence of
This macro takes the form:

POOL$B

3-5

DECLARING RMS-ll FACILITIES
The POOL$E macro is also required.
It marks the end of a sequence
space pool declaration macros.
It takes the form:

POOL$E
The remaining macros listed in Table 3-2 can be coded in any order
following the POOL$B macro and before the POOL$E macro. Multiple
instances of such space pool declarations can occur among the set of
source modules that you will link together through the use of the Task
Builder. The Task Builder will sum the size requirements indicated by
all such space pool declarations.

3.3.2

P$BDB - Number of Buffer Descriptor Blocks

The P$BDB macro is required.
It ensures that the space pool contains
sufficient space for
internal RMS-II control structures known as
buffer descriptor blocks.
The format of this macro is:
P$BDB bdbnum
where
bdbnum

is a numeric value or symbol representing the
number of buffer descriptor blocks required to
support the file processing performed by your
program.
To determine this value, you must apply
the following formula:
bdbnum = maxbuf + maxrel + (2

* maxidx)

where

3.3.3

maxbuf

is the maximum number of I/O buffers ever in use
for simultaneously open files.
You calculate this
value by totaling the multi-buffer counts in the
MBF
fields of RABs for all combinations of
simultaneously connected record access streams.
The maximum value among all such combinations is
the desired maxbuf value.

maxrel

is the maximum number of record access streams
ever connected simultaneously for write operations
to relative files (whether or not an actual write
operation is performed).

maxidx

is the maximum number of record access streams
ever active simultaneously for write operations to
indexed files (whether or not an actual write
operation is performed).

P$FAB - Number of Files Open Simultaneously

The P$FAB macro is required.
It ensures that there will be sufficient
storage in the space pool for
internal RMS-II control structures
related to File Access Blocks. The format of this macro is:
P$FAB number

3-6

DECLARING RMS-ll FACILITIES
where
number

is a numeric value representing the maximum number
of files that can be open simultaneously at run
time.

An example of the P$FAB macro follows:
POOL$B

P$FAB 4

POOL$E
In this example, the user specifies that a maximum of four
be open simultaneously at run-time.

3.3.4

files

can

P$RAB - Non-indexed Record Access Streams

The P$RAB macro ensures that there will be sufficient storage in the
space pool to accommodate internal control structures related to
Record Access Blocks for relative or sequential files.
This macro can
be omitted, therefore,
if no record operations are performed on
relative or sequential files.
The format of the P$RAB macro is as follows:
P$RAB rabs
where
rabs

is a numeric value representing the maximum number
of Record Access Blocks that will be connected
simultaneously for relative and sequential files.

In the following example, the user declares that a maximum of three
Record Access Blocks,
representing access streams to non-indexed
files, will be connected simultaneously.
POOL$B

P$RAB 3

POOL$E

3.3.5

P$RABX - Indexed Record Access Streams

The P$RABX macro ensures that there will be room in the space pool for
internal RMS-ll control structures related to indexed files.
This
macro is required, therefore, if the program accesses records in any
indexed file.
The format of this macro is as follows:
P$RABX rabs,ksize,ckeys
3-7

DECLARING RMS-Il FACILITIES
where
rabs

is a numeric value representing the maximum number
of Record Access Blocks that will be connected
simultaneously for indexed files.

ksize

is a numeric value representing the size
(in
bytes)
of the largest key field within all the
files represented by the first argument.

ckeys

is a numeric value representing the number of keys
that can change when a $UPDATE operation is
performed on an indexed file. This value must be
specified whenever an indexed file is accessed for
$UPDATE operations (i.e., the FAC field in the FAB
for the associated file contains FB$UPD), whether
or not a $UPDATE is actually performed.

The following is an example of the P$RABX macro:
POOL$B

P$RABX 1,32

POOL$E
In this example, the user specifies that there will be at most a
single Record Access Block connected for processing an indexed file at
any point during program execution. The size of the largest key field
in any such file is 32 bytes and no keys can change during a $UPDATE
operation.

3.3.6

P$IDX - Number of Defined Keys

The P$IDX macro reserves storage in the space pool for control
structures containing internal key summary information. This macro is
required if any indexed file is accessed by your program.
Its format
is as follows:
P$IDX keys
where
keys

is a numeric value representing the total number
of all keys defined for all indexed files opened
simultaneously. This total must be specified even
if certain keys within one or more files are never
used for retrieval operations.

The following is an example of the P$IDX macro:
POOL$B

P$IDX 3

POOL$E
3-8

DECLARING RMS-Il FACILITIES
In this example, the user declares that a total of three keys
defined among all indexed files that are open simultaneously.

3.3.7

are

P$BUF - I/O Buffers

The P$BUF macro ensures that the space pool is large enough for I/O
buffers required to support the file and record processing performed
by your program.
If you choose to allocate private I/O buffers for
all files, this macro can be omitted. If, however, one or more files
will be processed without associated private I/O buffers, this macro
is required.
The amount of buffer space required depends on the following:
•

The maximum number of
streams.

•

The bucket size or block size of
each stream.

•

The multi-block count (MBC) specified in
Blocks representing streams connected
files.

•

The multi-buffer count (MBF) specified in each Record
Block representing each stream.

To calculate buffer
formula:
buffsize

space

simultaneously

requirements,

the

you

active

record

access

file

associated

with

the Record Access
to disk sequential

employ

the

Access

following

stmsizel[+stmsize2 .•• +stmsizen]

where
stmsizel,
stmsize2,
etc.

are the I/O buffer space requirements (in bytes)
for each simultaneously active
record access
stream associated with a file without private I/O
buffers. The requirements of each such stream are
determined as follows:
FOR DISK FILES
stmsize=BKS*{SI2*MBC)*MBF
where
BKS

is the number of virtual blocks in the
largest
size
bucket of the file
associated with the
stream.
For
sequential files, BKS equals I in this
formula.

3-9

DECLARING RMS-ll FACILITIES
MBC

is the
value
contained
in
the
multi-block count
(MBC) field of the
Record Access Block associated with
the stream.
This value is used only
with
sequential
files.
For
non-sequential files, MBC equals 1 in
this formula.

MBF

is the
value
contained
in
the
multi-buffer count (MBF) field of the
Record Access Block associated with
the stream.

FOR MAGNETIC TAPE FILES
stream-size=BLS*MBF
where
BLS

is the size
(in bytes)
of
each
physical block of the file associated
with the stream.
The default block
size for magnetic tape files is 512
bytes.

MBF

is the
value
contained
in
the
multi-buffer count (MBF) field of the
RecordAccess Block associated with
the stream.

The format of the P$BUF macro is as follows:
P$BUF buffsize
where
buffsize

is a numeric value representing the total size (in
bytes) of the I/O buffers required to support
files without private I/O buffers. The specified
value must be a multiple of 4.

In the following example of the P$BUF macro, the user specifies that a
total of 8192 bytes of I/O buffer space is required:
POOL$B

P$BUF 8192

POOL$E

3.4

$INIT OR $INITIF - INITIALIZING THE RMS-ll SYSTEM

You must include either an $INIT or an $INITIF macro in the
initialization code of any program that uses RMS-ll facilities. When
encountered at runtime, the
$INIT
macro
call
attempts
the
initialization of the RMS-ll system.
The $INITIF macro performs
initialization if RMS-ll is not presently initialized.
RMS-ll uses
the C-Bit of the Processor Status Word to indicate success or failure
3-10

DECLARING RMS-II FACIBITIES
of the initialization procedure.
initialization was successful.

the

C-Bit

cleared,

The formats of these macros are:
1.

label: $INIT

label: $INITIF

where
label

is an optional user-specified symbol that allows
control to be transferred to this location during
program execution.
Other instructions in the
program may refer to this label, as in the case of
a program that has been written so that it can be
restarted.

NOTE
The
$INIT
macro
will
not
cause
initialization if any files are open.

3-11

CHAPTER 4
ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME

This chapter describes RMS-ll runtime macros that retrieve,
and test the contents of data fields in user control blocks.

modify,

Runtime field access macros expand into code that affects the contents
of data fields during execution of your program. Using one or more of
these macros, you can perform any of the following actions during
program execution:
•

Store values into control block data fields before the
control block is used for the first time. You will perform
this action frequently since there are no runtime defaults
for any fields in control blocks.

•

Alter the contents of a control block data field to suit the
logic of your program, e.g., dynamically changing the access
mode used to process a file from random to sequential.

•

Test or compare the contents of control block data fields
returned by RMS-ll to your program, e.g., the status field
(STS) of a Record Access Block or File Access Block.

The runtime macros that perform the preceding functions are listed in
Table 4-1.
RMS-ll limits all but two of these macros to use with 1
byte or 1 word fields. The following table, therefore, also includes
the size of control block data fields that can be accessed by the
specified macro.
Table 4-1
Runtime Field Access Macros
Macro Name

Field Size

$COMPARE

1 byte or 1 word

Compares the contents of a
with a user-specified value.

$FETCH

Any size

Copies the contents of a field into
a user-specified location.

$OFF

1 byte or 1 word

Resets one or more
bit string field.

$SET

1 byte or 1 word

Sets one or more bits within a
string field.

$STORE

Any size

Changes the contents of a field.

$TESTBITS

1 byte or 1 word

Tests one or
field.

Function

4-1

bits

field

within

a
bit

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
The macros in Table 4-1 are provided so that you need not be aware of
the specific placement
(and, to a large extent, size) of the fields
within RMS-Il control blocks.
The placement of these fields may
differ from release to release. There are instances, however, when
knowledge of placement is desirable (e.g., during debugging).
This
information can be derived from the symbol table of an assembly
listing file of any module containing the control block(s)
of
interest. Offset values are represented by symbols beginning with the
two characters '0$'.
For one-word and one-byte fields,
the offset
symbol is simply the concatenation of '0$' with the three-character
field name. For example, O$STS represents the offset
(in bytes)
of
the STS field from the beginning of a FAB or RAB.
For multi-word
fields (such as ALQ in the FAB or in an allocation XAB) and multi-byte
fields (such as SIZ in the key definition XAB), each word (or byte) is
represented by an offset symbol that is the concatenation of
'0$',
plus the 3-character field name, plus a digit in the range 0 to n,
where n is I less than the number of words (or bytes)
in the field.
For example, the ALQ field is represented by the offset symbols O$ALQO
(the less significant word) and O$ALQI (the more significant word);
the SIZ field is represented by the symbols O$SIZO (the size of the
first, most significant, key segment), O$SIZI, ••• , 0$SIZ7
(the size
of the last, least significant, key segment).
The sections that follow describe each of the macros listed in Table
4-1.
The 3-character names of fields in control blocks and the
symbolic values that can be used to test and set these fields are
specified in Chapters 5 through 8.
NOTES

4.1

Octal radix is assumed for all numeric
values used as operands in the macros
described in this chapter.
You can
indicate decimal radix through the use
of an explicit decimal point following a
numeric value.

In all instances in which a control
block field is 2 words in length and
contains a numeric value, the least
significant bits appear
in the first
word of the
field
and
the
most
significant bits in the second word.

$COMPARE - COMPARING THE CONTENTS OF A FIELD

The $COMPARE macro compares a I-byte or I-word control block data
field with a user-specified value and sets PDP-II condition codes.
The format of the $COMPARE macro is as follows:
label:$COMPARE

source,fnm,reg

where
label

is an optional user-specified symbol referring
the $COMPARE macro.

4-2

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
source

is a user-specified operand representing a value
to be compared with the contents of a control
block data field.
You may express this operand
using any valid addressing mode.
If the operand
is specified as #0, a TST (or TSTB) instruction is
generated and condition codes set accordingly.
The operand must be word aligned for comparison
with I-word data fields.

fnm

is the 3-character name of a I-byte or I-word data
field within a user control block.
The assembler
will generate an error message if the specified
field name represents a multi-word field.
The
user-specified source operand will be compared
with the contents of this field.

reg

is a general register, RO through RS, loaded with
the address of the user control block containing
the desired data field.

The following are examples of the $COMPARE macro:
$COMPARE

#SU$SUC,STS,Rl

$COMPARE

2(Rl),RSZ,RS

In the first example, the user compares the status field
(STS)
of a
control block with the symbolic value SU$SUC. The address of either a
File Access Block or Record Access Block (both contain a status field)
is in general register 1. In the second example, the user specifies
that the record size field (RSZ) is to be compared with the operand
expressed using indexed addressing mode. Since the RSZ field exists
only in Record Access Blocks, general register RS must contain the
address of aRAB.

4.2

$FETCa - COPYING THE CONTENTS OF A FIELD

The $FETCH macro copies the contents of a control block data field
into a user-specified location. This macro can be used to access any
data field, regardless of size.
The format of the $FETCH macro is as follows:
label:$FETCH

destination,fnm,reg

label

is an optional user-specified symbol referring
the $FETCH macro.

destination

is a location within the user program into which
the contents of a control block field are to be
copied. The following restrictions apply to this
operand:

where

1. You cannot use immediate mode or
deferred addressing mode.

any

form

2. If the field name specified as the second
argument is POS or SIZ (refer to description of
key definition XAB$ in Chapter 7), you cannot
use register mode addressing to express the
destination operand.

4-3

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
3. For multi-word fields other than POS and SIZ,
you
must
use
care
when expressing the
destination
operand
with
register
mode
addressing.
The expanded code of the $FETCH
macro will
use
successive
registers
as
destination operands for successive words of
the data field.
Depending on the length of the
data field and the register specified as the
destination operand, this code could use the
register containing the control block address
as a destination operand.
4. If the data field to be copied is one or more
words in length,
the specified destination
location must be word aligned.
fnm

is the 3-character name of any data field within a
user control block.
Regardless of length, the
contents of this field are
copied
to
the
user-specified location.
The following conventions apply if the $FETCH
macro is used to reference the key size (SIZ) or
key position (POS) fields of a key definition XAB
(refer to Chapter 7 for a description of key
definition XABs):
•

You specify the 3-character name, SIZ or POS,
to access the entire 8-element array. The
following example shows all eight words of the
POS field copied into successive locations
beginning with the user-specified destination:
$FETCH (RO)+,POS,R3

•

To access a single element in the 8-element
array, you specify the 3-character field name
immediately followed by a numeric
element
number from 0 to 7.
In the following example,
the user fetches the first element of the POS
field:
$FETCH R4,POSO,R3

reg

is a general register, RO through RS, loaded with
the address of the user control block containing
the desired data field.

The following are examples of the $FETCH macro:
$FETCH

R2,RBF,R4

$FETCH

8. (R3) ,MRN ,RI

In the first example, general register R4 contains the address of a
Record Access Block.
The user copies the contents of the record
address field (RBF) into general register R2.
In the second example,
general register RI contains the address of a File Access Block. The
user copies both words of the maximum record number field
(MRN)
into
successive words beginning with the specified location.

4-4

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
4.3

$OFF - RESETTING BITS WITHIN AFIELD

The $OFF macro resets one or more bits within
string data fields.

I-byte

I-word

bit

label

is an optional user-specified symbol referring
the $OFF macro.

value

is an expression or location specifying the
within the data field that are to be reset.

bits

fnm

is the 3-character name of a I-byte or I-word data
field within a user control block. The assembler
will generate an error message if the specified
field name represents a multi-word field.

reg

is a general register, RO through R5, loaded with
the address of the user control block containing
the desired data field.

The format of the $OFF macro is as follows:
label:$OFF

value,fnm,reg

where

In the following example, general register R2 contains the address of
a Record Access Block. The user resets the bit in the record options
field (ROP) that specifies greater than or equal key searches.
"$OFF

4.4

#RB$KGE,ROP,R2

$SET - SETTING BITS WITHIN A FIELD

The $SET macro sets one or more
string data fields.

bits

within

I-byte

I-word

bit

label

is an optional user-specified symbol referring
the $SET macro.

value

is an expression or location specifying the
within the data field that are to be set.

bits

fnm

is the 3-character name of a I-byte or I-word data
field within a user control block. The assembler
will generate an error message if the specified
field name represents a multi-word field.

reg

is a general register, RO through R5, loaded with
the address of the user control block containing
the desired data field.

The format of the $SET macro is as follows:
label:$SET

value,fnm,reg

where

The following are examples of the $SET macro:
$SET
$SET

#FB$GET!FB$UPD,FAC,R4
#RB$EOF,ROP,RI
4-5

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
In the first example, general register R4 contains the address of a
File Access Block.
The user sets the bits within the file access
field
(FAC) that indicate $GET and $UPDATE operations will be
performed on the associated file.
In the second example, general
register RI contains the address of a Record Access Block.
The user
sets the bit within the record options field (ROP) that specifies
positioning to end of file.

4.5

$STORE - CHANGING THE CONTENTS OF A FIELD

The $STORE macro changes the contents of an entire control block data
field by storing values from a user-specified location. This macro
can be used with any size data field.
For multi-word fields,
successive locations, beginning with the user-specified location, will
be used as the source of values to be stored into the data field. For
bit string data fields, the entire field will be altered. Therefore,
if you want to change bit settings selectively in a bit string field,
you should use the $OFF or $SET macro.
The format of the $STORE macro is as follows:
label:$STORE

source,fnm,reg

label

is an optional user-specified symbol referring
the $STORE macro.

source

is a location within the user program containing
values to be stored into a control block data
field. When this operand is expressed as #0, the
expanded code of this macro will clear the entire
data field to zero.
The following restrictions
apply to this operand:

where

1. You cannot use
addressing mode.

any

form

deferred

2. Immediate mode addressing can be used
with I-byte or I-word fields.

only

3. If the field name specified as the second
argument
is
POS
or
SIZ
(refer to
description of key definition XABs
in
Chapter 7), you cannot use register mode
addressing to express the source operand.
4. For multi-word fields other than POS and
SIZ, you must use care when expressing the
source
operand
with
register
mode
addressing.
The expanded code of the
$STORE macro will use successive registers
as source operands for successive words of
the data field. Depending on the length of
the data field and the register specified
as the source operand, this code could use
the register containing the control block
address as a source operand.
5. Word alignment of source
operands
required
when setting the contents
fields one or more words in length.
4-6

is
of

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
is the 3-character name of any data field in a
user control block. The $STORE macro will change
the contents of this field,
regardless of its
length.

fnm

The following conventions apply if the $STORE
macro is used to change the contents of the key
position CPOS) or key size (SIZ) fields of a key
definition
XAB
(refer to description of key
definition XABs in Chapter 7):
•

You specify the 3-character name, POS or
SIZ, to change the contents of the entire
8-element array.
The following example
shows the changing of contents of all 8
words of the POS field with values taken
from successive locations beginning with
the user-specified source location:
$STORE

•

To access a single
element
in
the
8-element
array,
you
specify
the
3-character
field
name
immediately
followed by a numeric element number from
o to 7. In the following example, the
user changes the contents of the first
element of the POS field:
$STORE

reg

(RI)+,POS,R3

R2,POSO,RI

is a general register, RO through R5, loaded with
the address of the user control block containing
the desired data field.

The following are examples of the $STORE macro:
$STORE

iO,ALQ,R3

$STORE

iINPUT,FAB,RI

In the first example, general register R3 contains the address of a
File Access Block.
The user clears the 2-word allocation quantity
field (ALQ) in the block to zero.
In the second example, general
register RI contains the address of a Record Access Block. The user
stores the address of a File Access Block in the FAB field of the
Record Access Block.

4.6

$TESTBITS - TESTING BITS WITHIN A FIELD

The $TESTBITS macro compares one or more bits within a I-byte or
I-word control block data field with a user-specified value and sets
PDP-II condition codes.
The format of the $TESTBITS macro is as follows:
label:$TESTBITS

source,fnm,reg

where
label

is an optional user-specified symbol referring
the $TESTBITS macro.
4-7

ACCESSING CONTROL BLOCK FIELDS AT RUN-TIME
source

is an expression or location indicating which bits
of the specified data field are to be tested.

fnm

is the 3-character name of a I-byte or I-word bit
string data field containing the bits to be
tested. The assembler will generate an error
message if the specified field name represents a
multi-word field.

reg

is a general register, RO through R5, loaded with
the address of the user control block containing
the desired data field.

In the following example of the $TESTBITS macro, the address of a File
Access Block is in general register R3. The user tests the file
access (FAC) field of the block to determine if the current program
can issue $UPDATE or $PUT operations:
$TESTBITS

#FB$UPD!FB$PUT,FAC,R3

If neither bit is set in the FAC field, condition code Z will be
if either or both bits are set in SHR, code Z will be off.

4-8

set,

CHAPTER 5
THE FILE ACCESS BLOCK

This chapter describes the File Access Block (FAB), the fields in a
FAB, and the assembly-time macros that allocate FABs and initialize
fields in FABs.
Certain conventions apply to the assembly-time macros presented in
this chapter and In Chapter 6 (The Record Access Block), Chapter 7
(Extended Attribute Blocks), and Chapter 8 (The Name Block).
For
example, two macros are always required to allocate space for a user
control block. These macros take the general form:
1.

label:xyz$B

xyz$E

where
label

is the user-specified
particular block.

names

this

xyz

is the three character name of the control
to be allocated (i.e., FAB, RAB, XAB, NAM).

block

symbol

that

An xyz$B macro causes the allocation of space for the specified block
and delimits the beginning of an optional sequence of assembly-time
initialization macros for the fields of the block.
The xyz$E macro
performs three functions:
1.

Stores the values specified by intervening
macros in appropriate locations in the block.

initialization

Sets assembly-time default values in
initialized.

not

Terminates the definition of the block.

fields

explicitly

Each field within a user control block has a three character name.
These three character names are always part of the name of the
associated assembly-time initialization macros. The following is the
format of initialization macros:
x$fnm arg
where
x

is the first character of the name of the block
containing the field to be initialized, e.g., F
for File Access Block, R for Record Access Block.

5-1

THE FILE ACCESS BLOCK
fnm

is the three character name of
initialized.

arg

is the value
field.

loaded

the
into

field
the

specified

The following are examples of assembly-time initialization macros:
F$FAC
R$ROP

arg
arg

The F$FAC macro initializes the file access field (FAC) of the File
Access Block.
The R$ROP macro initializes the record options field
(RaP) of the Record Access Block.
Assembly-time initialization macros can appear only between the xyz$B
and xyz$E macros that define and allocate the control block containing
the field to be initialized.
The following are examples of the placement
macros:

field

initialization

INFILE:FAB$B
F$FAC arg
FAB$E
INP:

RAB$B
R$ROP arg
RAB$E

Depending on the nature of the field being initialized, three types of
arguments may appear on initialization macros:
1.

Symbolic values.

Labels.

Numeric values.
NOTES
1.

You cannot use global symbols or labels
as
arguments
to
the assembly-time
initialization macros described in this
chapter. All symbols and labels used as
arguments must be defined locally.

The default radix for numeric values in
assembly-time initialization macros is
decimal.

When symbolic values are provided by RMS-ll, they take
form:

the

following

xz$nam
where
xz

are the first and last
characters
of
the
associated three-character block name, e.g. FB
for File Access Block, RB for Record Access Block.

5-2

THE FILE ACCESS BLOCK
is a two- or three-character
representing the value to be
specified field.

nam

The following are examples of symbolic values
initialization macros:

used

symbolic
name
loaded into the
as

arguments

INFILE:FAB$B
F$FAC FB$PUT
FAB$E
INP:

RAB$B
R$ROP RB$EOF
RAB$E

In the above examples, the file access field (FAC) of the File Access
Block named INFILE is initialized with the symbolic value FB$PUT.
This value indicates that the user requires write access to the file
associated with the block.
The record options field (ROP) of the
Record Access Block INP is initialized with the value RB$EOF.
This
value indicates that the file is to be positioned to end of file.
When several symbolic values are used to initialize a field, each
value must be separated by an exclamation point (1), as shown below:
INFILE:FAB$B
F$FAC FB$GETIFB$PUT!FB$DEL
FAB$E
The preceding example initializes the file access field (FAC) of the
File Access Block INFILE with values indicating that the user requires
read, write, and delete access to the contents of the associated file.
Certain fields in user control blocks can contain the address of
another
block
or
program
work area.
The argument used in
initialization macros for these fields is the label specified by the
user for the second block or program work area.
INFILE:FAB$B
FAB$E

INP:

RAB$B
R$FAB INFILE
RAB$E

The preceding example shows the File Access Block address field
(FAB)
of the Record Access Block INP initialized with the address of the
File Access Block named INFILE.
Lastly, certain fields within structures may be initi~lized at
assembly-time by macros that allow numeric values or user defined
symbols as arguments:
1.

INFILE:FAB$B
F$MRS 132
FAB$E

MAXSIZ=132.

INFILE:FAB$B
F$MRS MAXSIZ
FAB$E
5-3

THE FILE ACCESS BLOCK
In the preceding examples, the maximum record size field
(MRS) of a
File Access Block named OTFILE is initialized with a value of 132,
representing the size, in bytes, of the largest record that will be
written in the file.

5.1

ALLOCATING A FILE ACCESS BLOCK

The FAB$B macro allocates space for a File Access Block and delimits
the beginning of an optional sequence of assembly-time initialization
macros for the fields of the block.
The format of the FAB$B macro is as follows:
label:FAB$B
where
label

is a user-specified symbol that
names
this
particular File Access Block.
You must assure
that the address assigned to this label
is
word-aligned. Therefore, a .EVEN directive should
immediately precede the FAB$B macro.

The FAB$E macro delimits the end of an optional sequence
of
assembly-time initialization macros and stores any specified initial
values in the appropriate fields of the block. At assembly-time, all
fields not explicitly initialized are set to their default values.
The FAB$E macro must always appear subsequent to an associated FAB$B
macro, even when no intervening initialization macros are coded. This
macro takes the form:
FAB$E
The following example shows the allocation
named MASTER:
• EVEN
MASTER: FAB$B
FAB$E

File

Access

Block

iALLOCATE MASTER FAB
iEND OF MASTER FAB

The following example shows the allocation of the same block with the
assembly-time initialization of two fields -- the file access (FAC)
and logical channel number (LCH) fields •
• EVEN
MASTER: FAB$B
F$FAC
F$LCH
FAB$E

5.2

iALLOCATE MASTER FAB
FB$PUT iACCESS FOR $PUT OPERATIONS
2
iACCESS FILE ON CHANNEL 2
iEND OF MASTER FAB

FIELDS IN THE FILE ACCESS BLOCK

Table 5-1 summarizes the fields in the File Access Block:

5-4

THE FILE ACCESS BLOCK
Table 5-1
File Access Block Fields
Field
Name

Field
Size

ALQ

2 words

Allocation quantity.

BID

1 byte

Block identifier.

BKS

I byte

Bucket size.

BLN

I byte

Block length.

BLS

I word

Block size.

BPA

1 word

Private buffer pool address.

BPS

I word

Private buffer pool size.

CTX

I word

User context area.

DEQ

I word

Default file extension quantity.

DEV

I byte
(bit string)

DNA

I word

Default name string address.

DNS

I byte

Default name string size.

FAC

I byte
(bit string)

FNA

I word

File name string access.

FNS

I byte

File name string size.

FOP

I word
(bit string)

File processing options.

FSZ

I byte

Fixed control area size.

IFI

I word

Internal file identifier.

LCH

I byte

Logical channel number.

MRN

2 words

Maximum record number~

MRS

I word

Maximum record size.

NAM

I word

Name block address.

ORG

I byte

File organization.

I byte
(bit string)

Record attributes.

RAT

RFM

I byte

Description

Device characteristics.

File access.

Record format.
(Continued on next page)

5-5

THE FILE ACCESS BLOCK
Table 5-1 (Cont.)
File Access Block Fields
Field
Name

Field
Size

RTV

1 byte

SHR

1 byte
(bit string)

STS

1 word

Completion status code.

STV

1 word

Status value.

1 word

Extended attribute block pointer.

Description
Retrieval window size.
File sharing.

The subsections that follow describe the purpose of each of the fields
listed in Table 5-1.
RMS-ll provides macros that allow you to
initialize most of these fields at assembly-time. These macros, when
provided, are discussed at the conclusion of each field description.

5.2.1

ALQ - Allocation Quantity

The allocation quantity (ALQ) field is used with three file processing
macros - $OPEN, $CREATE, and $EXTEND:
1.

As output from the $OPEN macro call, RMS-ll sets the ALQ
field to indicate the highest numbered virtual block
currently allocated to the file.

Before creating a new file by issuing a $CREATE macro
call, you can set the ALQ field of the FAB describing
the file.
The value you place in ALQ
will
be
interpreted by RMS-ll as the number of virtual blocks to
be contained in the initial extent of the file. If you
set ALQ equal to zero, RMS-ll will determine the minimum
number of virtual blocks that must be allocated for
initial extent of the file. For sequential files, no
blocks will be allocated.
For relative and indexed
files, the minimum number of virtual blocks is based on
·the attributes of the file.

Before extending a file by issuing a $EXTEND macro call,
you must set ALQ equal to the number of virtual blocks
to be added to the file.
NOTE
The function of the ALQ
field
during
the $CREATE and $EXTEND
macro calls is different from the
preceding
descriptions
if
allocation XABs are present during
the operation.
Refer to Section
7.6 in Chapter 7 for a description
of allocation XABs and their effect
on ALQ during $CREATE and $EXTEND
operations.
5-6

THE FILE ACCESS BLOCK
The F$ALQ macro allows you to initialize the
ALQ
assembly-time. The format of this macro is as follows:

field

F$ALQ quantity
where
is a numeric value in the range of 0 to 16,777,215
representing a number of virtual blocks.

quantity

The following example of the F$ALQ macro shows an allocation
of 132 virtual blocks.

quantity

MASTER: FAB$B

F$ALQ 132

FAB$E

5.2.2

BID - Block Identifier

The block identifier (BID) field identifies the block as a FAB.
This
field, automatically set by the FAB$B macro, contains the value
FB$BID. You must never alter this field.

5.2.3

BKS - Bucket Size

The bucket size (BKS) field is used only for relative and indexed
files.
When you open an existing relative or indexed file by issuing
the $OPEN macro call, RMS-II sets the BKS field to the defined SIze of
buckets in the file. When, however, you wish to create a relative or
indexed file, you can specify the size of buckets in the file by
setting a value in this field before issuing the $CREATE macro call.
For sequential files, RMS-II ignores the BKS field during a $CREATE
macro call and zeroes the field during a $OPEN macro call.
NOTE
The function of the BKS field during the
$CREATE
and
$OPEN
macro calls is
different from the preceding description
if allocation XABs are present during
the operation. Refer to Section 7.6 in
Chapter
7
for
a
description
of
allocation XABs and their effect on BKS
during $CREATE and $OPEN operations.
In specifying a bucket size, you must be aware of the relationship
between bucket size and record size. Since RMS-il does not allow
records to cross bucket boundaries, you should ensure that the number
of virtual blocks per bucket conforms to one of the following
formulas:

5-7

THE FILE ACCESS BLOCK
1.

Indexed files with fixed length records:
Bnum=«Rlen+7)*Rnum)+15/512
where

Bnum

is the number of virtual blocks per bucket
rounded up to the next higher integer. The
result must be in the range of from 1 to 32.

Rlen

is the fixed record length.

Rnum

is the number of records
each bucket.

that

you

want

Indexed files with variable length records:
Bnum=«Rmax+9)*Rnum)+15/512
where

Bnum

is the number of virtual blocks per bucket
rounded up to the next higher integer. The
result must be in the range of from 1 to 32.

Rmax

is the maximum size
file.

Rnum

is the number of records, of the
size, that you want in each bucket.

any

record

the

maximum

Relative files with fixed length records:
Bnum = «Rlen+l)*Rnum)/512
where

Bnum

is the number of virtual blocks per bucket
rounded up to the next higher integer. The
result must be in the range of from 1 to 32.

Rlen

is the fixed record length.

Rnum

is the number of records
each bucket.

that

you

want

Relative files with variable length records:
Bnum = «Rmax+3)*Rnum)/512
where
Bnum

is the number of virtual blocks per bucket
rounded up to the next higher integer. The
result must be in the range of from 1 to 32.

Rmax

is the maximum size
file.

Rnum

is the number of records that you want in
each bucket.
Variable length records in a
relative file bucket always occupy Rmax+3
bytes.

5-8

any

record

the

THE FILE ACCESS BLOCK
5.

Relative files with VFC format records:
Bnum = «Rmax+Fsiz+3)*Rnum)/512
where
Bnum

is the number of virtual blocks per bucket
rounded up to the next higher integer.

Rmax

is the maximum size of the data
any VFC record in the file.

Fsiz

is the size of the fixed control area portion
of the VFC records.

Rnum

is the number of records that you want in
each bucket. VFC records in a relative file
bucket always occupy Rmax+Fsiz+3 bytes.

The F$BKS macro allows you to initialize the
BKS
assembly-time. The format of this macro is as follows:

portion

field

F$BKS bucket-size
where
bucket-size

is a numeric value, in the range of 0 to 32,
representing
the
number
of
virtual blocks
contained in each bucket of the file.
The
assembly-time default is o. RMS-ll interprets a
value of 0 as identical to a value of 1.

The following is an example of the F$BKS macro
specification of four virtual blocks per bucket:

showing

the

MASTER: FAB$B

F$BKS 4

FAB$E

5.2.4

BLN - Block Length

The block length (BLN) field specifies the length of the FAB.
This
field,
automatically set by the FAB$B macro, contains the value
FB$BLN. You must never alter this field.

5.2.5

BLS - Block Size

The block size (BLS) field is used for files on magnetic tape.
When
you open an existing file on magnetic tape by issuing a $OPEN macro
call, RMS-Il sets the BLS field to the size of the physical blocks in
the file.
When, however, you are creating a file on magnetic tape,
you can specify the physical block size by setting a value in this
field before issuing the $CREATE macro call.

5-9

THE FILE ACCESS BLOCK
The F$BLS macro allows you
assembly-time.
Its format is:

initialize

the

BLS

field

F$BLS block-size
where
block-size

is a numeric value representing the size
(in
bytes)
of the physical blocks on a tape. This
value must be either 0 or in the range of 18 to
8192
bytes.
At runtime,
a value of 0 is
interpreted as the operating system default of 512
bytes.
The assembly-time default is o.

An example of the F$BLS macro follows:
MASTER: FAB$B

F$BLS 4096

FAB$E
In this example, the user specifies that
magnetic tape file will be 4096 blocks.

each

physical

block

NOTE
To allow data interchange with other DEC
systems, you should specify a block size
less than or equal to 512 bytes.
To
allow
data interchange with non-DEC
systems, you should specify a block size
that is less than or equal to 2048
bytes.

5.2.6

BPA - Buffer Pool Address

The buffer pool address (BPA) field can contain the address of a
private I/O buffer pool for all record access streams for the file
represented by the FAB.
If you wish to use a private I/O buffer pool,
you must set the address of the pool in this field before issuing a
If you do not want to use a
$CREATE or $OPEN macro call for the file.
private I/O buffer pool for the file, you must assure that this field
is zero before you issue the $CREATE or $OPEN macro.
If this field is
zero at the time a $CREATE or $OPEN macro call is issued, RMS-ll
allocates I/O buffers for the file from the centralized space pool
(refer to Section 3.3.7 in Chapter 3).
The F$BPA macro allows you to initialize the
BPA
assembly-time. The format of this macro is as follows:
F$BPA address

5-10

field

THE FILE ACCESS BLOCK
where
is the symbolic address of the starting location
of a private I/O buffer pool. This address must
be on a double-word boundary.
The assembly-time
(i.e., no
default for the BPA field is zero
private I/O buffer pool).

address

In the following example, the user sets, at assembly-time, the address
of a private I/O buffer pool in the File Access Block called MASTER •
• EVEN
INBUF: .BLKB 4096.

MASTER: FAB$B

F$BPA INBUF

FAB$E

5.2.7

BPS - Buffer Pool Size

You use the buffer pool size (BPS) field to specify the size of a
private I/O buffer pool. You specify this size only if you placed a
valid address in the BPA field of the same FAB before issuing a $OPEN
or $CREATE macro call.
The F$BPS macro allows you
assembly-time. Its format is:

initialize

BPS

the

field

F$BPS poolsz
where
poolsz

is a numeric value representing the total size (in
bytes) of the private I/O buffer pool.
The
specified value must be a multiple of 4.

To calculate the size of the
formula:

private

pool,

you

use

the

following

poolsz = stmsizel[+stmsize2 .•• stmsizen]
where
stmsizel,
stmsize2,
etc.

are the I/O buffer space requirements (in bytes)
for each
simultaneously active record access
stream associated with the file. The requirements
of each such stream are determined as follows:
FOR DISK FILES
stmsize=BKS*(512*MBC)*MBF

5-11

THE FILE ACCESS BLOCK
where
BKS is the number of virtual blocks in the largest
size bucket of the file associated with the
stream.
For sequential files,
BKS equals 1 in
this formula.
MBC is the value contained in the multi-block
count
(MBC)
field of the Record Access Block
associated with the stream. This value is used
only with sequential files.
For non-sequential
files, MBC equals 1 in this formula.
MBF is the value contained in the
count
(MBF)
field of the Record
associated with the stream.

multi-buffer
Access Block

FOR MAGNETIC TAPE FILES
stmsize=BLS*MBF
where
BLS is the size (in bytes) of each physical block
of the file associated with the stream. The
default block size for magnetic tape files is 512
bytes.
MBF is the value contained in the
count
(MBF)
field of the Record
associated with the stream.

multi-buffer
Access Block

In the following example, the user defines the address and size
private I/O buffer pool:

• EVEN
INBUF: .BLKB 4096.

MASTER: FAB$B

F$BPA INBUF
F$BPS 4096

FAB$E

5.2.8

CTX - User Context Area

The user context area (CTX) is never used in any way by RMS-ll.
It is
intended exclusively for the user. Therefore, you can set any value
you choose in this I-word field.
You might,
for example, use this
field as a means of communicating with a common completion routine in
your program.
The F$CTX macro allows you to initialize the
CTX
assembly-time. The format of this macro is as follows:
F$CTX argument
5-12

field

THE FILE ACCESS BLOCK
where
argument

represents any user-selected value.

The following are two examples of the F$CTX macro, showing a numeric
value placed in the user context area in the first case, and a
symbolic value in the second case.
1.

MASTER: FAB$B

F$CTX 3

FAB$E
2.

MASTER: FAB$B

F$CTX INPUT

FAB$E

5.2.9

DEQ - Default File Extension Quantity

The default file extension quantity (DEQ) field contains the number of
virtual blocks to be used when RMS-ll must automatically extend the
file. This automatic extension occurs whenever your program attempts
a $PUT or $UPDATE operation that cannot be accommodated within the
space currently allocated to the file.
When you create a new file, you can specify a default extension
quantity by setting the desired value in the DEQ field before issuing
the $CREATE macro call.
RMS-ll saves the specified value as a
permanent attribute of the file. A value of zero indicates that the
default extension quantity for the file is the volume default.
When you are processing an existing file, you can temporarily override
the default extension quantity specified when the file was created.
To do this, you set the desired value in the DEQ field before issuing
the $OPEN macro call.
When RMS-ll finds a non-zero value in this
field during $OPEN processing, it uses the specified value for any
automatic extension operations needed while the file is open. Once
you close the file, the default extension quantity reverts to that
specified at create time.
The F$DEQ allows you to initialize the
Its format is:

DEQ

field

assembly-time.

F$DEQ quantity
where
quantity

is a numeric value representing a number of
virtual blocks. This number must be in the range
of from 0 to 65,535.
For relative and indexed
files,
the quantity you specify should be a
multiple of bucket size.
The
assembly-time
default is O.
5-13

THE FILE ACCESS BLOCK
The following example of the F$DEQ macros shows the user specifying
default extension of 80 virtual blocks.

MASTER: FAB$B

F$DEQ 80

FAB$E

5.2.10

DEV - Device Characteristics

When you open a file by issuing a $OPEN or $CREATE macro call, RMS-ll
sets the device characteristics (DEV) field.
This field allows RMS-ll
to communicate to your program the generic characteristics of the
device on which the file resides. After the file is open, you can use
appropriate runtime field accessing macros (refer to Chapter 4)
to
test for the following characteristics:
FB$CCL

Carriage control
terminals.

FB$MDI

Multiple directory structured device,
volumes.

FB$REC

Record oriented device, e.g.,
terminal,
line
printer, etc.
All record oriented devices are
considered sequential in nature.

FB$SDI

Single directory device,
i.e., a master file
directory is used but no user file directories are
present.

FB$SQD

Sequential and
tape).

FB$TRM

Terminal with both keyboard and printer.

5.2.11

device,

block

e.g.,

oriented

printers
e.g.,

device

and
disk

(magnetic

DNA - Default Name String Address

The default name string address (DNA)
field allows you to provide
program defaults for any missing components of the file name string
addressed by the FNA field.
You can specify defaults for one or mote
of the following file specification components:
1.

Device

Directory

Filename

File type

File version number

5-14

THE FILE ACCESS BLOCK
You can use the F$DNA macro to initialize
assembly-time. The format of this macro is:

the

DNA

field

F$DNA address
where
is the symbolic address of an ASCII
string
representing one or more components of a file
specification. The components (e.g., device, file
type) must be specified in the order in which they
would occur in a complete file specification
string.
If this field is zero, RMS-ll assumes
that there is no default name string.

address

As an example of the use of a default name string and the F$DNA macro,
assume that a user's program contains the following directive:
DFNAM:

.ASCII /SY:.DAT/

The following use of the F$DNA macro would associate the default
string with a particular File Access Block:

name

MASTER: FAB$B

F$DNA DFNAM

FAB$E
During a $OPEN or $CREATE macro call, RMS-ll uses the ASCII string
whose address is DFNAM to provide the device (SY:) and file type (DAT)
components of the file specification of the file to be accessed -- if
these components are missing from the string whose address is stored
in the FNA field.

5.2.12

DNS - Default Name String Size

The default name string size (DNS) field is used to specify the size
of the default name string whose address is contained in the DNA field
of the same File Access Block.
The F$DNS macro
assembly-time:

allows

you

initialize

the

DNS

field

F$DNS size
where
size

is a numeric value representing the size of the
default name string expressed in bytes.
The
specified value must be in the range of zero to
255.
If this field is zero, RMS-Il assumes that
there is no default name string.

Assume that a user's program contains the following directive:
DFNAM:

.ASCII /SY:.DAT/

5-15

THE FILE ACCESS BLOCK
The following example shows the
relationship to the F$DNA macro:

use

the

F$DNS

macro

and

its

MASTER: FAB$B

F$DNA
F$DNS

DFNAM
7

FAB$E

5.2.13

FAC - File Access

You must ensure that the file access (FAC) field contains indications
of operations you intend to perform on the file. After you open a
file, RMS-Il rejects any of the seven operations listed below if that
operation was not specified in the FAC Field during execution of the
$OPEN or $CREATE macro call for the file.
$DELETE
$GET
$PUT
$TRUNCATE
$ UPDATE
$READ (block I/O)
$WRITE (block I/O)
If, for example, a $DELETE record operation macro appears in your
program for the file associated with this File Access Block, the
symbolic value FB$DEL must be present in the file access field before
you open the file.
The F$FAC macro allows you to initialize the
FAC
assembly-time. The format of this macro is as follows:

field

F$FAC operation[!operation ••• ]
where
operation

is a symbolic value representing a type of file or
record operation that may be performed on the
file. One or more values may be listed in any
order. Allowable values are:
FB$DEL

$DELETE operations.

FB$GET

$GET
and/or
$FIND
(assembly-time default).

FB$PUT

$PUT operations. You must specify
value if you are creating a file.

FB$REA

$READ block I/O operations
(refer to
Appendix B for a description of block
I/O).

5-16

operations
this

THE FILE ACCESS BLOCK
FB$TRN

$TRUNCATE operations.
You should not
specify this value unless the associated
file is sequential.

FB$UPD

$UPDATE operations.

FB$WRT

(refer to
$WRITE block I/O operations
Appendix B for a description of block
I/O) •

The following are two examples of the F$oFAC macro, indicating $GET
operations for the associated file in the first case, and $DELETE,
$GET, and $PUT operations in the second case.

MASTER: FAB$B

F$FAC FB$GET

FAB$E
2.

MASTER: FAB$B

F$FAC FB$DEL!FB$GET!FB$PUT

FAB$E

5.2.14

FNA - File Name String Address

In combination with the file name string size field
(FNS) , the FNA
field describes an ASCII string that represents the file specificaiton
of the file associated with the File Access Block.
If this string
does not contain all the components of a full file specification,
RMS-ll will use the defaults supplied in the default name string
described by the DNA and DNS fields.
If no default name string is
present or if the file specification is still incomplete, RMS-ll will
apply system defaults, if any, for the missing components.
The F$FNA macro allows you
assembly-time.
Its format is:

initialize

the

FNA

field

F$FNA address
where
address

is the symbolic address of an ASCII
string
representing the file specification of the file
associated with the File Access Block.
If this
field is zero, RMSll assumes that there is no file
name string.

5-17

THE FILE ACCESS BLOCK
The following is an example of the F$FNA macro:
FLNAM: .ASCII /PAYROLL/

MASTER: FAB$B

F$FNA FLNAM

FAB$E

5.2.15

FNS - File Name String Size

The file name string size (FNS) field contains the size of the ASCII
string file specification whose address is in the FNA field of the
block.
The F$FNS macro allows you to initialize
assembly-time. The format of this macro is:

the

FNS

field

F$FNS size
where
size

is a numeric value representing the size {in
bytes) of the file name string. The specified
value must be in the range of zero to 255.
If
this field is zero, RMS-ll assumes that there is
no file name string.

The following example shows the
relationship to the F$FNA macro:

use

the

F$FNS

macro

and

its

FLNAM: .ASCII /PAYROLL/

MASTER: FAB$B

F$FNA FLNAM
F$FNS 7

FAB$E

5.2.16

FOP - File Processing Options

The file processing options
(FOP)
field
contains
indicators
representing your requests for optional file handling operations.
This field can contain one or more of the following values:

5-18

THE FILE ACCESS BLOCK
FB$CTG

indicates that, during a $EXTEND or
$CREATE
operation, RMS-II is to allocate contiguously the
amount of space specified in the
allocation
quantity field
(ALQ).
For an existing file,
RMS-II returns this value in the FOP
field
following a $OPEN if the corresponding file is
contiguous.

FB$DLK

indicates that the file is not to be locked from
further access if it is not closed in the normal
manner.

FB$NEF

inhibits positioning to end of file when an ANSI
tape file is opened and the file access field
(FAC) contains the symbolic value FB$PUT.

F2$POS

indicates that the magnetic tape volume set should
be positioned to immmediately after the most
recently closed file when the file represented by
this File Access Block is created. The FB$RWO
value takes precedence over FB$POS.
The default
operation is to position to the end of the volume
set.

FB$RWC

specifies that the magnetic tape volume set is
be rewound when the file is closed.

FB$RWO

indicates that the magnetic tape volume set is to
be rewound before the file associated with this
File Access Block is opened or created.

FB$SUP

causes any corresponding existing file to be
superseded during a $CREATE macro call if an
explicit version number is present in the full
file specification of the file associated with
this File Access Block.

FB$TMD

indicates that the file associated with the File
Access Block is to be created as a temporary file
and deleted when the file is closed.
This value
takes, precedence over the value FB$TMP, if both
are present.

FB$TMP

indicates that a temporary file is to be created
and retained after closing. The file name will
not be entered in the directory.

The F$FOP macro allows you
assembly-time. Its format is:
F$FOP

initialize

the

FOP

field

option[loption ••• ]

where
option

is a symbolic value representing a processing
option to be applied to the file represented by
the FAB. One or more of the options listed above
can be specified.

5-19

THE FILE ACCESS BLOCK
In the following example of the F$FOP macro, the user requests that
the magnetic tape volume is to be rewound when the file is closed.
MASTER: FAB$B

F$FOP FB$RWC

FAB$E

5.2.17

FSZ - Fixed Control Area Size

The fixed control area size (FSZ) field is used only when the records
of the file represented by the FAB are in VFC format. When you create
such a file, you can set the desired value in the FSZ field before
issuing the $CREATE macro call. When you open an existing file that
contains VFC format records, RMS-II will set this field equal to value
specified when the file was created.
You can initialize this field at assembly-time
macro. Its format is as follows:

using

the

F$FSZ

F$FSZ size
where
size

is a
numeric
value,
expressed
in
bytes,
representing the size of the fixed control area of
each record of the file. The specified value must
be in the range of from I to 255. The default
size is 2 bytes.
If this field is zero, RMS-ll
assumes that the default size is desired.

An example of the F$FSZ macro follows:
- - MASTER: FAB$B

F$FSZ 8

FAB$E
In this example, the user specifies that each record of the file
VFC format records) contains an 8-byte fixed control area.

5.2.18

(with

IFI - Internal File Identifier

The internal file identifier
(IFI)
field is used by RMS-li to
associate the File Access Block with a corresponding internal control
structure in the space pool. RMS-li sets this field during a $OPEN or
$CREATE operation. It is cleared to zero during a $CLOSE macro call.
Your program must never alter this field.

5-20

THE FILE ACCESS BLOCK
5.2.19

LCH - Logical Channel Number

The LCH field is used to indicate a logical channel number.
Every
File Access Block representing an open file must contain a unique
logical channel number. All I/O operations performed on the file
represented by a FAB will use this number.
You can initialize the LCH field at assembly-time by using
macro. The format of this macro is as follows:

the

F$LCH

F$LCH channel
where
is a numeric value from I to 255.

channel

In the following example, the user assigns a logical channel number of
4 to the associated File Access Block:
MASTER: FAB$B

F$LCH 4

FAB$E

5.2.20

MRN - Maximum Record Number

The maximum record number (MRN) field is meaningful only for relative
files.
When creating a relative file, you can use this field to
specify the highest numbered record that can ever be written into the
file.
Thereafter, if any program attempts to write a record whose
relative number exceeds the specified limit, RMS-Il will return an
illegal maximum record number error (ER$MRN). Conversely, if you do
not want to limit the number of records that can be written into a
relative file,
you set the MRN field to zero before is·suing the
$CREATE macro for the file.
If the MRN field contained a value of
zero at the time the file was created, RMS-ll will not perform limit
checks when records are written.
When you open an existing relative file by issuing a $OPEN macro call,
RMS-ll returns to your program the MRN value specified when the file
was created. If no MRN was specified, RMS-ll returns the default
value.
You can initialize the MRN field at assembly-time by using
macro:

the

F$MRN

F$MRN max-rec-num
where
max-rec-num

is a numeric value representing the
highest
numbered record that can be written into the file
associated with the File Access Block.
The
assembly-time default is zero. RMS-Il converts a
value of zero to the highest positive integer for
the length of the field.
It is this latter value
that will be returned during a $OPEN operation if
MRN was defaulted during a $CREATE operation.
5-21

THE FILE ACCESS BLOCK
The following are two examples of the F$MRN macro.
In the first
example, the user indicates that the highest numbered record that can
be written into the file is record 10,000. In the second example, the
user explicitly specifies that no limit checks are to be performed.

MASTER: FAB$B

F$MRN 10000

FAB$E
2.

MASTER: FAB$B

F$MRN

FAB$E

5.2.21

MRS - Maximum Record Size

When you create a file you should set the MRS field before issuing the
$CREATE macro. The value you set in this field is based on the format
of records in the file you are creating.
Fixed format records - the specified value represents the actual
size of each record in the file. When creating a new file with
fixed format records, you must place a non-zero value in the MRS
field.
Variable and stream format records
the specified
value
represents the size of the largest record that can be written
into the file. A value of zero means no limit on record size.
The assembly-time default value is zero.
However, if the
organization of a file is relative, you must create the file with
a non-zero maximum record size, which establishes the size of the
record cells in the file.
VFC format records - the specified value must not include the
size of the fixed control area. Rather, the specified value
represents only the remaInlng data portion of VFC records.
Non-zero and zero values are interpreted by RMS-ll in the same
manner as in variable format records.
When you open an existing file by issuing a $OPEN macro call, RMS-ll
returns,
in the MRS field, the maximum record size specified when the
file was created.
The F$MRS macro allows you to initialize
assembly-time. This macro takes the form:
F$MRS size

5-22

the

MRS

field

THE FILE ACCESS BLOCK
where
size

is
a
numeric
value
expressed
in
bytes,
representing record size. This value must be in
the range of 0 to 16,383.

In the following example, the user specifies a maximum record size
1024 bytes:

MASTER: FAB$B

F$MRS 1024

FAB$E

5.2.22

NAM - Name Block Address

The Name Block address (NAM) field is always an optional field.
You
will place an address in this field only when you have allocated a NAM
block in your program and want the facilities provided by such a block
when you open a file
(refer to Chapter 8 for a description of the
purpose of a NAM block).
You can initialize the NAM field at
macro. This macro takes the form:

assembly-time

with

the

F$NAM

F$NAM address
where
address

is the symbolic address of an optional name block
associated with this File Access Block. A value
of zero indicates no NAM block. The assembly-time
default is zero.

An example of the F$NAM macro follows:
NMBLK: NAM$B

NAM$E

MASTER: FAB$B

F$NAM NMBLK

FAB$E

5-23

THE FILE ACCESS BLOCK
5.2.23

ORG - File Organization

The organization (ORG) field identifies the organization of the file
represented by the File Access Block. When you open an existing file,
RMS-II will set this field. When you create a new file, your program
must set this field before issuing the $CREATE macro call.
The F$ORG macro allows you
assembly-time. Its format is:

initialize

the

ORG

field

F$ORG organization
where
organization

is a symbolic value representing the organization
of the file.
One of the following values must be
specified:
FB$IDX - indexed
FB$REL - relative
FB$SEQ - sequential (assembly-time default)

The following is an example of the F$ORG macro:
MASTER: FAB$B

F$ORG FB$IDX

FAB$E
In this example, the user specifies that the new file associated
the File Access Block is to have an indexed organization.

5.2.24

with

RAT - Record Attributes

The record attributes (RAT) field specifies characteristics of the
records in the file. When you open an existing file, RMS-II sets this
field with the characteristics specified at create time.
When you
create a new file, your program sets desired values in this field
before issuing the $CREATE macro call.
The

F$RAT

macro allows you to initialize
It has the following format:

the

RAT

field

assembly~time.

F$RAT attribute[!attribute]
where
attribute

is a symbolic value used to define an attribute of
the records of the file. One or more values may
be listed in any order. Allowable values are:
FB$BLK

indicates that records will not cross
block boundaries.
This value can be
specified for sequential files only.

5-24

THE FILE ACCESS BLOCK
FB$CR

indicates that each record, when written
to a line printer or terminal, is to be
preceded by a line feed character and
followed by a carriage return character.

FB$FTN

specifies that the first byte
record
contains
a FORTRAN
control character.

of each
carriage

In the following example, the user specifies that records do not cross
block boundaries and each record is to be preceded by line feed and
followed by carriage return when written to a carriage control device:
MASTER: FAB$B

F$RAT FB$BLK!FB$CR

FAB$E

5.2.25

RFM - Record Format

The record format (RFM) field indicates the format of the records in
the file represented by the File Access Block. When you create a
file, your program should ensure that the desired value is present in
the RFM field before issuing the $CREATE macro. When you open an
existing file, RMS-II sets this field with the value specified when
the file was created.
You can initialize the RFM field at
macro. This macro takes the form:

assembly-time

with

the

F$RFM

F$RFM record-format
where
record-format

is a symbolic value defining the format of all
records contained within the file. One of the
following values can be specified:
FB$FIX

indicates fixed format records.

FB$STM

indicates ASCII stream record format.
This value can be specified only for
sequential files on disk devices.

FB$UDF

indicates no record format is defined
for the file. When creating a new file
or accessing an existing file
with
undefined records, your program must use
block I/O (refer to Appendix B).
When
creating such a file, the ORG field must
specify sequential file organization.

FB$VAR

specifies
variable
format
(assembly-time default).

5-25

records

THE FILE ACCESS BLOCK
FB$VFC

indicates VFC format records.
This
value can be specified for sequential
(on disk devices only) or
relative
files.

The following is an example of the F$RFM macro:
MASTER: FAB$B

F$RFM FB$FIX

FAB$E

5.2.26

RTV - Retrieval Window Size

The retrieval window size
(RTV)
field identifies the number of
retrieval pointers you want RMS-ll to maintain in memory for the file
represented by the File Access Block.
The F$RTV macro allows you to initialize
assembly-time. This macro takes the form:

the

RTV

field

F$RTV number
where
is either a positive integer in the range of 0 to
127 or a -1. A value of 0 (assembly-time default)
indicates that RMS-ll is to determine a minimum
window size. A non-zero positive value represents
the actual number of retrieval pointers to be
maintained in memory.
A -1 indicates that the
entire file is to be mapped through a window
maintained in memory.

number

In the following example, the user requests a retrieval window
retrieval pointers.

MASTER: FAB$B

F$RTV 10

FAB$E

5.2.27

SBR - File Sharing

The file sharing (SHR) field allows you to indicate whether you are
willing to let other programs write to the file while your program has
the file open at runtime (for either reading or writing).
Note that
sequentially organized files can be shared for reading only. However,
RMS-ll permits relative and indexed files to be shared for both
reading and writing.
5-26

THE FILE ACCESS BLOCK
You can initialize the SHR field at assembly-time by using
macro. Its format is:

the

F$SHR

F$SHR value
where
is a symbolic value or O.
A value
of
0
(assembly-time default) indicates that you do not
want to share the file at runtime with any program
that will write to the file.
If, in contrast, you
are willing to share the file with one or more
programs that will write to the file, you can set
this field with the following symbolic value:

value

FB$WRI - allow shared writers.
In the following example, the user indicates willingness to share
file with programs that write to the file:

the

MASTER: FAB$B

F$SHR FB$WRI

FAB$E

5.2.28

STS - Completion Status Code

Before returning control to your program, RMS-II always sets the
completion status code (STS) field to indicate success or failure of
the file operation. Appendix A contains a complete list of symbolic
completion codes that your program can use to test the contents of
this field.

Based on the type of operation performed and the contents of the STS
field, RMS-II may use the status value (STV) field to communicate
additional completion information to your program (refer to Appendix A
for a complete listing of the instances in which RMS-II uses the STV
field).

5.2.30

XAB - Extended Attribute Block Pointer

When a particular operation requires the association of Extended
Attribute Blocks with a File Access Block, you set the address of the
first associated block (of a potential chained list of such blocks) in
the XAB field of the FAB. For example, when you create an indexed
file, you must always provide at least one XAB -- a key definition XAB
for the primary key.
The F$XAB macro
assembly-time:

allows

you

initialize

F$XAB xab-address
5-27

the

XAB

field

THE FILE ACCESS BLOCK
where
xab-address

is the symbolic address of the first Extended
Attribute Block associated with this File Access
Block. A value of zero
(assembly-time default)
indicates no XABs are present for a particular
operation involving this FAB.

The following is an example of the F$XAB macro:
KEYDEF: XAB$B XB$KEY

XAB$E

MASTER: FAB$B

F$XAB KEYDEF

FAB$E
In this example,
Attribute Block.

KEYDEF

the

label

5-28

(address)

Extended

CHAPTER 6
THE RECORD ACCESS BLOCK

This chapter describes the Record Access Block (RAB), the fields in a
RAB, and the assembly-time macros that allocate RABs and initialize
fields in RABs.
Record Access Blocks are the second type of control structure that you
allocate at assembly-time and use at runtime to communicate with
RMS-ll. During program execution, you associate (by issuing $CONNECT
macro call) a Record Access Block with a File Access Block. The
association of a RAB and a FAB is known as a record access stream.
Once you have established a record access stream, you use the fields
of the Record Access Block to define to RMS-ll the next logical record
you want to access in the file.

6.1

ALLOCATING A RECORD ACCESS BLOCK

The RAB$B macro allocates space for a Record Access Block and delimits
the beginning of an optional sequence of assembly-time initialization
macros for the fields of the block.
The format of the RAB$B macro is as follows:
label:RAB$B [type]
where
label

is a user-specified symbol that
names
this
particular Record Access Block. You must ensure
that the address assigned to this label
is
word-aligned. Therefore, a .EVEN directive should
immediately precede the RAB$B macro.

type

indicates whether or not the Record Access Block
can support asynchronous I/O operations (refer to
Section 9.3.4 of Chapter 9 for a description of
asyncronous
record
operations).
One of the
following values can be specified:
SYN

indicates synchronous record
only (default).

operations

ASYN

indicates that the RAB can support both
synchronous
and
asynchronous record
operations.

The RAB$E macro delimits the end of an optional sequence
of
assembly-time initialization macros and stores any specified initial
values in the appropriate fields of the block. At assembly-time, all
6-1

THE RECORD ACCESS BLOCK
fields not explicitly initialized are set to their default values.
The RAB$E macro must always appear subsequent to an associated RAB$B
macro, even when no intervening initialization macros are coded.
This
macro takes the form:
RAB$E
The following example shows the allocation for synchronous
of a Record Access Block named INPUT:
• EVEN
INPUT: RAB$S
RAB$E

operations

iALLOCATE INPUT RAB
iEND OF INPUT RAB

The following example shows the allocation of the same block with the
assembly-time initialization of two fields--the File Access Block
address and Record Access (RAC) fields of the block •
• EVEN
INPUT: RAB$S
R$FAB MASTER
R$RAC RB$SEQ
RAB$E

6.2

iALLOCATE INPUT RAB
iADDRESS OF ASSOCIATED FAB
iSEQUENTIAL ACCESS
iEND OF INPUT RAB

FIELDS IN THE RECORD ACCESS BLOCK

Table 6-1 summarizes the fields in the Record Access Block:
Table 6-1
Record Access Block Fields
Field
Name

Field
Size

BID

BKT

2 words

Bucket code.

BLN

1 byte

Block length.

CTX

1 word

User context area.

FAB

I word

File Access Block address.

lSI

1 word

Internal stream identifier.

KBF

1 word

Key buffer address.

KRF

1 byte

Key of reference.

KSZ

1 byte

Key size.

MBC

1 byte

Multi-block count.

MBF

1 byte

Multi-buffer count.

RAC

1 byte

Record access mode.

Description
Block identifier.

byte

(Continued on next page)
6-2

THE RECORD ACCESS BLOCK
Table 6-1
(Cont.)
Record Access Block Fields
Field
Name

Field
Size

RBF

1 word

Record address.

RFA

3 words

Record's file address.

RHB

1 word

Record header buffer.

ROP

1 word
(bi t string)

RSZ

1 word

Record size.

STS

1 word

Completion status code.

STV

1 word

Status value.

UBF

1 word

User record area address.

USZ

1 word

User record area size.

Description

Record processing options.

The sUbsections that follow describe the purpose of each of the fields
listed in Table 6-1.
RMS-ll provides macros that allow you to
initialize most of these fields at assembly-time. These macros, when
provided, are discussed with the description of the associated field.

6.2.1

BID - Block Identifier

The block identifier (BID) field identifies the block as a RAB.
This
field, automatically set by the RAB$B macro, contains the value
RB$BID. You must never alter this field.

6.2.2

BKT - Bucket Code

The bucket code (BKT) field is used in two instances:
1.

When the record access stream represented
performing I/O on a relative file.

the

RAB

When the record access
performing block I/O.

the

RAB

stream

represented

When the record access stream is performing I/O on a relative file,
RMS-ll sets the BKT field to the relative record number of the record
accessed by an operation (e.g., $GET, $PUT). This feature is valid
only when your program is using sequential access mode.
When performing block I/O, your program uses the BKT field to specify
the virtual block number of a block to be read or written (refer to
Appendix B for a description of block I/O).
THE R$BKT macro initializes the BKT field at assembly-time:
R$BKT vbn

6-3

THE RECORD ACCESS BLOCK
where
vbn

is a numeric value representing
number.

virtual

block

In the following example, the user specifies that the tenth virtual
block of the file will be accessed when the program performs its first
block I/O operation at runtime.
INPUT:

RAB$B

R$BKT

RAB$E

6.2.3

BLN - Block Length

The block length (BLN) field specifies the length of the RAB.
This
field, automatically set by the RAB$B macro, contains the value RB$BLN
for a synchronous RAB and the value RB$BLL for an asynchronous RAB.
You must never alter this field.

6.2.4

CTX - User Context Area

The user context area (CTX) is never used in any way by RMS-ll.
It is
intended exclusively for the user. Therefore, you can set any value
you choose in this I-word field.
You might, for example, use this
field as a means of communicating with a common completion routine in
your program.
The R$CTX macro allows you to initialize the
CTX
assembly-time. The format of this macro is as follows:

field

R$CTX argument
where
argument

represents any user-selected value.

The following are two examples of the R$CTX macro, showing a numeric
value placed in the user context area in the first case, and a
symbolic value in the second case.
1.

INPUT:

RAB$B

R$CTX

RAB$E

6-4

THE RECORD ACCESS BLOCK
2.

INPUT:

RAB$B

R$CTX

MASTER

RAB$E

6.2.5

FAB - File Access Block Address

The FAB field must contain the address of a File Access Block
associated with an open file at the time a $CONNECT macro call (refer
to Section 9.3.1) is issued for the current Record Access Block.
The R$FAB macro allows you to initialize
assembly-time.
Its format is as follows:

the

FAB

field

R$FAB fab-address
where
fab-address

is the symbolic address of a File Access Block.

The following is an example of a R$FAB macro:
MASTER:

FAB$B

FAB$E

INPUT:

RAB$B

R$FAB

MASTER

RAB$E

6.2.6

lSI - Internal Stream Identifier

The internal stream identifier
(lSI)
field is used by RMS-Il to
associate the Record Access Block with a corresponding internal
control structure in the space pool.
RMS-ll sets this field during a
$CONNECT operation. Your program must never alter this field.

6.2.7

KBF - Key Buffer Address

The key buffer address (KBF) field contains the address of a loc~tion
in your program.
You will use this location during certain operations
in random access mode to indexed and relative files.

6-5

THE RECORD ACCESS BLOCK
Before issuing a $GET or $FIND operation in random mode to an indexed
file, you place in KBF the address of a location containing a
character s~ring key value. The size of this character string must be
specified in the KSZ field.
During execution of the $GET or $FIND
operation, RMS-ll uses the character string described by the KBF and
KSZ fields to search an index (which you specify through the contents
of the KRF field of the RAB) and locate the desired record in the
file.
The type of match
(i.e., exact, generic, approximate, or
approximate and generic) that RMS-ll attempts between the character
string you specify and key values in records of the file is determined
by the KSZ field and the ROP field.
Before issuing a $GET, $FIND, or $PUT operation in random mode to a
relative file, you must place in KBF the address of a location
containing a relative record number (note that relative record numbers
for a relative file begin with 1). The size of this location must be
in the KSZ field and must always equal 4.
The R$KBF macro allows you to initialize
assembly-time. The format of this macro is:

the

KBF

field

R$KBF address
where
address

is the symbolic address of a location containing
the key value or relative record number of a
record. RMS-Il does not require that this address
be word-aligned.
The size of this field is
specified by the KSZ field. When a relative file
is being accessed,
the address in KBF points to
the least significant bits of the desired relative
record number.

The following is an example of the R$KBF macro:
INKEY:

BLKB

INPUT:

RAB$B

R$KBF

32.

INKEY

RAB$E

6.2.8

KRF - Key of Reference

The key of reference (KRF) field is meaningful only when
file is being processed.
It is used when your program:
random

access

indexed

Issues $GET or $FIND operations
indexed files.

Issues $CONNECT,or $REWIND operations for indexed files.

6-6

mode

THE RECORD ACCESS BLOCK
During random $GET or $FIND operations, the contents of the KRF field
specify which key field is described by the KBF and KSZ fields, e.g.,
primary key, first alternate key, etc. Thus, KRF tells RMS-II which
index in the file to search seeking a match on the character string
key value you described through the contents of the KBF and KSZ
fields.
During $CONNECT or $REWIND operations, RMS-II uses the contents of the
KRF field to determine the current context of the record access stream
(refer to Section 9.3.3 in Chapter 9 for a discussion of current
context).
In this case, KRF identifies an index of the file which, in
turn, identifies the next record for the stream.
The R$KRF macro can be used to initialize the KRF
assembly-time. The following is the format of this macro:

field

R$KRF key-number
where
key-number

is a numeric value representing a key within the
records of the file. A value of zero indicates
the primary key. Values of I through 254 indicate
the desired alternate keys.
The assembly-time
default value is zero (primary key).

In the following example, the user specifies that the contents of
location called INKEY represent a first alternate key value.
INKEY:

BLKB

INPUT:

RAB$B

the

32.

R$KBF
R$KRF

INKEY
I

RAB$E

6.2.9

KSZ - Key Size

The key size (KSZ) field contains the size
address is in the KBF field of the block.

the

location

whose

When you access an inoexed file in random mode, you use the contents
of the KSZ and ROP fields to specify the type of match that RMS-II is
to perform on the character string key value addressed by the KBF
field.
If the size in KSZ equals the length of the key field as
defined when the file was created, RMS-II attempts an exact match
(if
neither RB$KGE or RB$KGT is present in ROP) or an approximate match
(if RB$KGE or RB$KGT is present in ROP). If, however, the size in KSZ
is less than the defined key length, RMS-II attempts a generic match
(RB$KGE or RB$KGT not in ROP) or a generic-approximate match
(either
RB$KGE or RB$KGT present in ROP).
When you access a relative file in random mode, you must
KSZ contains the value 4.

6-7

ensure

that

THE RECORD ACCESS BLOCK
The R$KSZ macro allows you to initialize this field at
The format of this macro is as follows:

assembly-time.

R$KSZ size
where
size

is a numeric value representing the size (in
bytes) of the record key. The specified value
must be in the range of 1 to 255.

The following is an example of the R$KSZ macro:
INKEY:

BLKB

INPUT:

RAB$B

R$KBF
R$KSZ
R$KRF

32.

INKEY
32
1

RAB$E
In this example, the user specifies that the first alternate key value
in location INKEY is 32 bytes in length.

6.2.10

MBC - Multi-block Count

Use of the multi-block count (MBC) field is optional. It applies only
when the stream represented by the RAB is accessing a sequentially
organized file on disk.
The contents of the MBC field, examined by RMS-ll during execution of
the $CONNECT macro, represent the number of virtual blocks you want
transferred as a single entity during I/O operations between the file
and each of the stream's buffers. Effectively, therefore, the MBC
field defines the size of each buffer supporting the stream's access
to the file while the MBF field (refer to Section 6.2.11) specifies
the number of such buffers RMS-ll is to allocate for the stream.
The primary use of the MBC field is for throughput optimization.
It
in no way effects the structure of the file being accessed. Rather,
it minimizes the number of disk accesses required to support your
program's record operation requests.
In particular, if your program
issues all read requests {$GETs} or all write requests
($PUTS), you
can increase execution speed by specifying at $CONNECT time an MBC
value that is greater than 1. In combination with this value, you
must ensure that the central space pool (refer to Section 3.3.7 in
Chapter 3) or your private I/O buffer pool (refer to Section 5.2.7 in
Chapter 5) contains sufficient space for the larger buffers.
The R$MBC macro initializes
format is:
R$MBC

the

MBC

blocks

6-8

field

assembly-time.

Its

THE RECORD ACCESS BLOCK
where
is a numeric value from 0 to 255 representing the
number of blocks to be transferred during I/O
operations and, therefore, the number of virtual
blocks contained in each I/O buffer supporting the
stream. The assembly-time default is O.
Both 0
and 1 indicate 1 block per buffer.

blocks

In the following example, the user specifies that 8 virtual blocks are
to be transferred during each I/O operation between the stream's
buffers and the file.
INPUT:

RAB$B

R$MBC

RAB$E

6.2.11

MSF - Multi-buffer Count

The contents of the multi-buffer count
(MBF)
field represent the
number of I/O buffers you want RMS-ll to allocate when your program
issues a $CONNECT operation for this Record Access Block.
RMS-ll
allocates these buffers either from the centralized space pool or, if
the BPA and BPS fields are non-zero in the FAB associated with this
RAB, from the private I/O buffer pool associated with the file.
The minimum number of buffers that RMS-ll requires for a record access
stream is based on the organization of the file. Table 6-2 lists the
minimum number of buffers for each file organization and the maximum
number of buffers that you can specify.
Table 6-2
Minimum and Maximum Number of Buffers
File
Organization

Minimum
MBF

Maximum
MBF

Sequential

Relative

No maximum

Indexed

No maximum

The R$MBF macro allows you to initialize
assembly-time. The format of this macro is:
R$MBF buffers

6-9

the

MBF

field

THE RECORD ACCESS BLOCK
where
buffers

is a numeric value representing the number of
buffers to be allocated to the record access
stream upon execution of a $CONNECT macro call.
The specified value must be in the range of 0 to
255.
A value of 0
(assembly-time
default)
indicates the minumum number of buffers based on
the file's organization. If the user specifies
less than the minimum required by the organization
of the file, RMS-ll ignores the user specification
and allocates the minimum required.
If the user,
for a sequential file,
specifies more than the
maximum, RMS-ll allocates the maximum number (2).
If the user specifies more buffers than are
available, RMS-ll allocates as many as possible.

In the following example, the user specifies the
buffers:
INPUT:

allocation

four

RAB$B

R$MBF

RAB$E

6.2.12

RAC - Record Access Mode

The RAe field specifies the access mode to
store a record.
The R$RAC macro allows you
assembly-time. Its format is:

used

retrieve

initialize

the

RAC

field

R$RAC access-mode
where
access-mode

is a symbolic value representing the type of
access desired.
One of the following may be
specified:
RB$KEY

indicates random
access.
You
can
specify this value only with relative or
indexed files.

RB$RFA

indicates access
by
record's
file
address
(for files on disk devices
only). When you specify this value,
RMS-ll uses the record's file address
(RFA) field of this RAB to access the
record.

RB$SEQ

indicates sequential access.
specify
this
value
with
organization.

6-10

You can
any file

THE RECORD ACCESS BLOCK
The following is an example of the
indicates random access:
INPUT:

R$RAC

macro

which

the

user

RAB$B

R$RAC

RB$KEY

RAB$E

6.2.13

RBF - Record Address

The record address (RBF) field is used to pass the address of a record
between RMS-ll and your program. As output from a successful $GET
operation, RMS-ll always places the memory address of the retrieved
record in RBF. Conversely, your program, prior to a $PUT or $UPDATE
operation, must place in RBF the memory address of the record to be
written out to the file.
In both instances, the RSZ field describes
the size of the record. Refer to Section 9.3.5.2.1 in Chapter 9 for
further details on the RBF and RSZ fields.
You can initialize the RBF field at assembly-time
macro. The format of this macro is as follows:

with

the

R$RBF

your

R$RBF address
where
address

is the symbolic
program.

address

area

In the following example, the user initializes the RBF field with the
address of a program location that, at runtime, will contain a record
to be written to the file.
RECBUF:

.BLKB

INPUT:

RAB$B

R$RBF

150.

RECBUF

RAB$E

6.2.14

RFA - Record's File Address

The record's file address (RFA) field is used to pass the RFAs of
records between RMS-ll and your program. After successful $GET, $PUT,
and $FIND operations, RMS-ll returns to your program the RFA of the
record successfully operated upon.
Your program can then save the
contents of this field for subsequent retrieval of the record using
RFA access mode.
Before retrieving a record using RFA access, your
program must load the RFA of the desired record in the RFA field.
6-11

THE RECORD ACCESS BLOCK
6.2.15

RHB - Record Header Buffer

RMS-ll uses the record header buffer (RHB) field only when the record
format field
(RFM) of the associated File Access Block indicates VFC
format records. When RHB is non-zero, RMS-ll interprets its contents
as the address of a buffer for the fixed control area portion of VFC
records. On $GET operations, RMS-ll strips the fixed control area
portion of VFC records and places it in the buffer whose address is in
the RHB field. On $PUT and $UPDATE operations, RMS-ll prefixes the
data portion of the record with the fixed . control area portion
described by the RHB field before the entire record is written to the
file.
For all such operations, the size of the fixed control area
portion is a defined attribute of the file.
During a $OPEN macro
call, RMS-ll returns this size in the FSZ field of the associated File
Access Block. When your program processes the fixed control area
portion of VFC records, you must ensure that the buffer described by
the RHB field is at least as large as the value in FSZ.
When you do not want to process the fixed control area portion of VFC
records, you zero the RHB field. When RHB is zero, RMS-ll does the
following:
1.

Skips the fixed control area portion of the
operations.

record

$GET

Writes out
operations.

area

$PUT

Leaves the original fixed control area unaltered
operations.

zero-filled

You can initialize the RHB
macro:

field

fixed

control

assembly-time

with

$ UPDATE

the

R$RHB

R$RHB header-address
where
header-address is the symbolic address of an area within your
program.
An address of zero in the RHB field
indicates the nonexistence of the buffer.

6.2.16

ROP - Record Processing Options

The record processing options
(ROP)
field allows you to request
optional functions during the execution of a record operation.
The R$ROP macro allows you to initialize the
ROP
assembly-time. The format of this macro is as follows:

field

R$ROP option[!option ••• ]
where
option

is a symbolic value representing record processing
options. One or more of the following options may
be specified in any order.

6-12

THE RECORD ACCESS BLOCK
RB$ASY

indicates asynchronous operation.
When
this value is set, RMS-ll can return
control to your program before
the
specified record operation is completed
(assuming that the RAB has been defined
as asynchronous in the RAB$B macro).

RB$EOF

indicates that RMS-ll is to position to
end of file when the $CONNECT macro call
is issued for the record access stream.
This option applies only to sequential
files on disk devices.

RB$FDL

indicates fast delete
(indexed files
only).
When this value is present,
$DELETE operations will mark records in
the file as deleted but RMS-ll will not
remove pointers to the record from the
indexes.

RB$KGE

indicates that RMS-ll is to search for
the first record containing a value in
the key specified by the KRF field that
is greater than or equal to the value
described by the KBF and KSZ fields.
This option applies only to indexed
files and is one form of the approximate
match facility (see also RB$KGT).

RB$KGT

specifies the second
form
of
the
approximate match facility
(see also
RB$KGE).
It indicates that RMS-ll is to
search for the first record containing a
value in the key specified by the KRF
field that is greater than the value
described by the KBF and KSZ fields.
This option applies only to indexed
files.

RB$LOA

indicates that RMS-ll is to
follow
bucket fill sizes for record insertions
to indexed files.
The fill sizes for a
file are specified by the user at file
creation time in the DFL and IFL fields
of
key
definition
XABs.
The
assembly-time default is
to
ignore
bucket fill sizes (i.e., buckets will be
completely filled).

RB$LOC

indicates locate mode. Locate mode on
$GET operations is supported for all
file organizations. Locate mode on $PUT
operations
is
supported
only
for
sequential files.
Locate mode is not
permitted if the file was opened for
$UPDATE operations
(i?e., the
value
FB$UPD was present in the FAC field of
the FAB during the $OPEN or $CREATE
operation).

6-13

THE RECORD ACCESS BLOCK
RB$UIF

indicates that if a $PUT operation to a
relative file encounters an existing
record in the target record cell, the
existing record is to be updated.
If
RB$UIF is not set, RMS-ll returns an
ER$REX (record already exists) error if
a $PUT operation to a relative file
encounters an existing record.

The following are two examples of the R$ROP macro.
In the first
example, the user specifies positioning to end of file and locate mode
operations. In the second example, the user specifies an approximate
key search, i.e., RMS-ll is to search for a record containing a key
value equal to or greater than the key described by the KBF, KSZ, and
KRF fields.
1.

INPUT:

RAB$B

R$ROP

RB$EOF!RB$LOC

RAB$E
2.

INPUT:

RAB$B

R$ROP

RB$KGE

RAB$E

6.2.17

RSZ - Record Size

The record size (RSZ) field contains the size (in bytes) of the record
whose address is in the RBF field.
Following a successful $GET
operation, RMS-ll places the size of the retrieved record in the RSZ
field.
Conversely, your program, before issuing a $PUT or $UPDATE
operation, must ensure that the RSZ field contains the size of the
record to be written.
The R$RSZ macro can be used to initialize
assembly-time. The format of this macro is:

the

RSZ

field

R$RSZ record-size
where
record-size

is a numeric value representing the size
(in
bytes) of the record whose address is in the RBF
field. The value specified must range from 1 to
16383.

6-14

THE RECORD ACCESS BLOCK
The following is an example of the R$RSZ macro:
RECBUF:

.BLKB

INPUT:

RAB$B

R$RBF
R$RSZ

150.

RECBUF
150

RAB$E
In this example, the user specifies a record size of 150 bytes.

6.2.18

STS - Completion Status Code

RMS-ll always sets the completion status code (STS) field to indicate
success or failure of the record operation. Appendix A contains a
complete list of symbolic completion codes that your program can use
to test the contents of this field.

6.2.19

STY - Status Value

Based on the type of operation performed and the contents of the STS
field, RMS-li may use the status value (STV) field to communicate
additional completion inf~rmation to your program (refer to Appendix A
for a complete list of the instances in which RMS-ll uses the STY
field).

6.2.20

UBF - User Record Area Address

The user record area address (UBF) field must contain a valid address
regardless of the data transfer mode
(i.e., move or locate mode)
associated with the record access stream. Refer to Section 9.3.5.2.2
in Chapter 9 for details on the function of the UBF field.
The R$UBF macro allows you to initialize
assembly-time. The format of this macro is:

the

UBF

field

R$UBF address
where
address

is the symbolic address of a work area within your
program.
You must specify the size of this work
area in USZ.

6-15

THE RECORD ACCESS BLOCK
The following is an example of the R$UBF macro.
WAREA:

.BLKW

INPUT:

RAB$B

R$UBF

1024.

WAREA

RAB$E

6.2.21

USZ - User Record Area Size

The USZ field contains the size of the user record area whose
is in the UBF field.
You can initialize the USZ
macro:

field

assembly-time

with

address

the

R$USZ

R$USZ area-size
where
area-size

is a numeric value representing the size (in
bytes) of the user record area whose address is in
the UBF field.
The value specified must range
from 1 to 16383.

In the following example, the user specifies a user record
bytes in size.
WAREA:

.BLKW

INPUT:

RAB$B

R$UBF
R$USZ

1024.

WAREA
2048

RAB$E

6-16

area

2048

CHAPTER 7
EXTENDED ATTRIBUTE BLOCKS

This chapter describes Extended Attribute Blocks, the fields in
Extended Attribute Blocks, and the assembly-time macros that allocate
XABs and initialize fields in XABs.
Extended Attribute Blocks contain
file
and
record
attribute
information beyond that specified in the associated File Access Block.
XABs are generally required only when a file is being created
(particularly an indexed file) or when the $DISPLAY macro call is used
to retrieve file attributes.
When more than one Extended Attribute Block is required, they are
linked together. The XAB field of the File Access Block points to the
first block in the linked list.
There are five types of Extended Attribute Blocks:
1.

Date and time XABs

Key definition XABs

File protection specification XABs

Allocation XABs

Summary XAB

After descriptions of XAB allocation and linking, the subsections that
follow describe each type of XAB.

7.1

ALLOCATING AN EXTENDED ATTRIBUTE BLOCK

The XAB$B macro allocates space for an Extended Attribute Block and
delimits the beginning of an optional sequence of assembly-time
initialization macros for the fields of the block.
The format of the XAB$B macro is as follows:
label:XAB$B

type

where
label

is a user-specified symbol that
names
this
particular Extended Attribute Block.
You must
ensure that the address assigned to this label is
word-aligned. Therefore, a .EVEN directive should
irnmedi ate ly pr.ecede the XAB$B macro.

7-1

EXTENDED ATTRIBUTE BLOCKS
type

is a symbolic value representing the type of
attribute information contained in the block. At
assembly-time, the specified value is stored in
the COD field of the block. At runtime, the value
in the COD field determines how RMS-ll interprets
the remainder of the Extended Attribute Block.
One of the following values must be
assembly-time.

specified

XB$DAT

indicates a date and time XAB.

XB$KEY

indicates a key definition XAB.

XB$PRO

indicates
a
specification XAB.

XB$ALL

indicates an allocation XAB.

XB$SUM

indicates a summary XAB

file

protection

The XAB$E macro delimits the end of an optional sequence
of
assembly-time initialization macros and stores any specified initial
values in the appropriate fields of the block. At assembly-time all
fields not explicitly initialized are set to their default values.
The XAB$E macro must always appear subsequent to an associated XAB$B
macro, even when no intervening initialization macros are coded. This
macro takes the form:
XAB$E
The following example shows the allocation
Extended Attribute Block named KEYDEF:
KEYDEF:

7.2

• EVEN
XAB$B
XAB$E

key

definition

XB$KEY

LINKING AND ORDERING EXTENDED ATTRIBUTE BLOCKS

Regardless of the type of information contained (e.q., key definition,
protection specification, etc.), every XAB has an NXT field. The NXT
field links one XAB with another. When multiple XABs are needed for a
particular operation (e.g., $CREATE, $DISPLAY), the address of the
first XAB is placed in the XAB field of the File Access Block.
The
address of the second XAB is placed in the NXT field of the first XAB,
and so forth.
The NXT field of the last XAB in the linked chain is
set to zero to indicate the end of the chain.
Within a chain of XABs, there is no mandatory ordering of blocks based
on XAB type (i.e., contents of the COD field). Assume, for example,
that you want to obtain the attributes of a single-key indexed file.
At assembly-time, you could allocate a date and time XAB, a key
definition XAB, a file protection XAB, and a summary XAB.
Then,
either at assembly-time or at runtime, ·you could link these XABs in
any order by appropriately setting the contents of the NXT field in
each block.
Finally, you would issue a $DISPLAY macro call and RMS-ll
would fill attribute information into each block -- the type of
information going into each block being determined by the COD field of
the block.

7-2

EXTENDED ATTRIBUTE BLOCKS
While different types of XABs can appear in any order in a chain,
multiple instances of the same type must appear in a particular order.
This rule applies to key definition and allocation XABs, since these
are the only ones that RMS-ll permits multiple instances of in a
chain. Key definition XABs must be linked together in ascending order
based on the contents of the key of reference (REF) field (refer to
Section 7.4.10). Allocation XABs must be linked together in ascending
order based on the contents of the area identification number (AID)
field (refer to Section 7.6.1). In both instances, there cannot be
any intervening XABs of another type in the sub-chain of XABs of the
same type. Further, the ope.ration for which these XABs are present
determines whether or not the ascending order must be dense. For
$CREATE operations, key definition and allocation XABs,
if present,
must appear in densely ascending order by,
respectively, key of
reference (REF) and area identification number
(AID).
For $OPEN,
$EXTEND, and $DISPLAY operations, key definition and allocation XABs,
if present, must be in ascending order but need not be dense.
You use the X$NXT macro to initialize the NXT field of an
assembly-time. The format of the X$NXT macro is as follows:

XAB

X$NXT xab-address
where
xab-address

7.3

is the symbolic address of the next XAB within the
current chain of XABs. A value of zero indicates
the last (or only) XAB in a chain.

DATE AND TIME EXTENDED ATTRIBUTE BLOCKS

Date and time Extended Attribute Blocks contain fields specifying the
date and time the associated file was created and the date and time
the file was last updated. There are no initialization macros for the
fields in this XAB since you can only examine, but not alter, the date
and time attributes of a file.
The allocation of this XAB at
assembly-time causes the fields of the block to be initialized to
zero.
Table 7-1 describes the fields of a date and time XAB.
Table 7-1
Date and Time XAB Fields
Description

Field Name

Field Size

COT

4 words

The date and time
created, expressed
binary number.

COD

1 byte

Code field.
XB$DAT.

NXT

1 word

Next XAB.

ROT

4 words

The date and time the file was last
updated, expressed as an 8 byte
binary number.

RVN

1 word

the
Revision number.
Contains
number of times the file was opened
(via a $OPEN macro call) for write
operations.
7-3

the file was
as an 8 byte

Contains

the

value

EXTENDED ATTRIBUTE BLOCKS
The 8-byte binary numbers (in which the lowest-addressed byte is the
least significant)
in the COT and ROT fields represent the number of
hundreds of nanoseconds elapsed since the beginning of November 17,
1858.

7.4

KEY DEFINITION EXTENDED ATTRIBUTE BLOCKS

Each key definition Extended Attribute Block describes one key of an
indexed file.
When you create an indexed file, you must set the
contents of the fields of this XAB before you issue the $CREATE macro
call.
You must, further, provide one key definition XAB for each key
you want the file to have. Since every indexed file has at least one
key
(the primary key) you will always require at least one key
definition XAB.
When you open an existing indexed file or issue a $DISPLAY operation
for such a file, you use key definition XABs only if you want RMS-ll,
as output from the macro call, to provide your program with one or
more of the key definitions specified when the file was created.
Table 7-2 summarizes the fields of a key definition XAB.
Table 7-2
Key Definition XAB Fields
Description

Field Name

Field Size

COD

1 byte

Code field.
XB$KEY.

DAN

1 byte

Area number for data buckets.

DFL

1 word

Data bucket fill size.

FLG

1 byte
(bi t string)

IAN

1 byte

Area number for index buckets.

IFL

1 word

Index bucket fill size.

KNM

1 word

Key name address.

LAN

1 byte

Area number
index.

NUL

1 byte

Null key value.

NXT

1 word

Next XAB.

P~S

8 words

Key position.

REF

1 byte

Key of reference.

RVB

2 words

Root virtual block number.

SIZ

8 bytes

Key size.

Contains

the

value

Key options.

7-4

for

lowest

level

EXTENDED ATTRIBUTE BLOCKS
The following sUbsections describe the fields listed in Table 7-2 that
are unique to the key definition XAB.

7.4.1

DAN - Area Number for Data Buckets

You set a value in the DAN field only if both
true:

the

following

You are creating a new indexed file.

You are using allocation XABs (described in Section
control the placement and structure of the file.

7.6)

are

If both of the above are true, then you use the DAN field to assign
the buckets of the data level of the index defined by this XAB to one
of the areas defined by an allocation XAB.
When the key definition XAB describes the primary key, the data level
of the index consists of those buckets containing the actual data
records of the file. When, however, the XAB describes an alternate
key, the data level of the index consists of buckets in which RMS-ll
maintains pointer arrays describing the data records.
The X$DAN macro allows you
assembly-time. Its format is:

initialize

the

DAN

field

X$DAN

aid

is a numeric value from 0 to 254 representing an area
identification number contained in the AID field of an
allocation XAB present in the same
chain.
The
assembly-time default is 0 (i.e., area 0).

where

In the following example, the user assigns the data level of
defined by the XAB called KEYDEF to area 1.
AREAl:

XAB$B

X$AID

XB$ALL

XAB$E

KEYDEF:

XAB$B

XB$KEY

X$DAN

XAB$E

7-5

the

key

EXTENDED ATTRIBUTE BLOCKS
7.4.2

DFL - Data Bucket Fill Size

At $CREATE time, you can use the DFL field to specify how many bytes
you want used in each data level bucket of the associated index. By
specifying less than the total bucket size, you indicate that the data
buckets are not to be completely filled but are to contain some amount
of free space. At runtime, RMS-li adheres to the fill size specified
at $CREATE time only if the RB$LOA value is present in the record
processing options (ROP) field of the RAB.
When the key definition XAB describes the primary key, the OFL field
describes space in buckets containing the actual user data records.
When the XAB describes an alternate key, the OFL field describes space
in buckets of the alternate index containing pointers to the user data
records.
You may want to use the facility provided by the OFL field
(and the
similar facility provided by the IFL field, described in Section
7.4.5) in the following situation: If you expect to perform numerous
$PUT and $UPDATE operations on the file after it has been initially
populated, you can minimize the resultant movement of records
(known
as bucket splitting) by specifying a less than maximum bucket fill
size at $CREATE time. To utilize the free space thereby reserved in
the buckets, programs that perform $PUT or $UPDATE operations on the
file should not place, at $CONNECT time, the value RB$LOA in the ROP
field of the RAB.
The X$DFL macro allows you to initialize
assembly-time. The format of this macro is:

the

DFL

field

X$DFL space
where
space

is a numeric value representing the maximum number
of bytes to be used in the data buckets. The
assembly-time default value is 0,
which
is
interpreted at runtime by RMS-II as meaning the
bucket size in bytes (i.e., no unused space).

The following is an example of the X$DFL macro:
KEYDEF:

XAB$B

XB$KEY

X$DFL

256

XAB$E
In this example, the user specifies that each bucket in the data level
is to be filled to a maximum of 256 bytes.

7-6

EXTENDED ATTRIBUTE BLOCKS
7.4.3

FLG - Key Options

The key options (FLG) field defines optional characteristics
key represented by the XAB. These characteristics are:
1.

Duplicate key values are allowed.

Key values can change.

Null key value.

You use the X$FLG macro to initialize the FLG field at
Its format is:

the

assembly-time.

X$FLG option[!option.~.]
where
option

is a symbolic value specifying a characteristic of
the key field defined by the Extended Attribute
Block. The following values may be specified:
XB$CHG

indicates that the associated key within
any record can be changed by a program
during a $UPDATE operation. This option
can be specified only for alternate keys
and only in conjunction with XB$DUP.

XB$DUP

indicates that records within the file
may have the same values within the key
field associated with this XAB.
The allowed combinations of XB$CHG and
XB$DUP depend on the type of key (i.e.,
primary or alternate) represented by the
extended attribute block.
Table 7-3
summarizes these combinations.

XB$NUL

indicates that the NUL field of this XAB
contains a null key value.
You can
specify this characteristic only for
alternate keys.

Table 7-3
Key Option Combinations
Key Type

Combination
CHANGE

CHANGE

NO CHANGE

DUPLICATES

NO DUPLICATES

DUPLICATES

NO DUPLICATES

Primary

Error

Allowed

Default

Alternate

Default

Error

Allowed

The assembly-time default values for the FLG field depend on the type
of key (i.e., primary or alternate) defined by the XAB. The defaults
for a primary key are:

7-7

EXTENDED ATTRIBUTE BLOCKS
1.

Duplicate key values are not allowed.

Key values cannot change.

No null key value.

The defaults for alternate keys are:
1.

Duplicate key values allowed.

Key values can change.

No null key value.

The symbolic values you specify using the X$FLG assembly-time macro or
the $STORE runtime macro are mapped into bit settings in the FLG
field.
When a bit is set, it means that
the
corresponding
characteristic was specified (e.g., key values can change or duplicate
key values allowed or null key value defined). Conversely, when a bit
is zero, it means that the corresponding characteristic is not defined
for the key (e.g., key values cannot change, or duplicate keys not
allowed or null key not defined). Both the X$FLG and the $STORE macro
affect the entire FLG field, setting those bits specified and clearing
to
zero
those
not
specified.
Therefore, when defining the
characteristics of a key, you should specify exactly what you want the
field to contain, expressing bit settings as symbolic values. Any
symbolic values you omit will result in a zero in the corresponding
bit position. As examples, consider the following:
1.

KEYDEF:

XAB$B

XB$KEY

X$FLG

XB$DUP1XB$NUL

XAB$E
2.

KEYDEF:

XAB$B

XB$KEY

X$FLG

XB$NUL

XAB$E
3.

STORE

#O,FLG,R3

In the first example, the user specifies that duplicate keys are
allowed, a null key value is defined, and (through the absence of
XB$CHG) that key values cannot change. In the second example, the
user specifies that a null key value is defined but duplicate key
values are not permitted and key values cannot change. In the third
example, the user sets the FLG field to indicate that duplicate key
values are not permitted, key values cannot change, and no null key is
defined.

7-8

EXTENDED ATTRIBUTE BLOCKS
7.4.4

IAN - Area Number for Index Buckets

You set a value in the area number for index buckets (IAN) field
if both of the following are true:
1.

You are creating a new indexed file.

You are using allocation XABs
(refer to Section
control the placement and structure of the file.

7.6)

only

If both of the above are true, then you use the IAN field to assign
the buckets of the index level of the index defined by this XAB to one
of the areas defined by an allocation XAB.
When the key definition XAB describes the primary key, the index level
of the index consists of all levels of the tree-structured primary
index down to and including the level containing pointers to the user
data
records themselves.
When, however,
the XAB describes an
alternate key,
the index level consists of all levels of the
tree-structured alternate index down to, but not including, the level
containing buckets in which RMS-ll maintains pointer arrays describing
the user data records
(refer to the LAN field description for an
additional facility in index bucket assignment).
The X$IAN macro allows you
assembly-time.
Its format is:

initialize

the

IAN

field

X$IAN

aid

is a numeric value from 0 to 254 representing an area
identification number contained in the AID field of an
allocation XAB present in the same
chain.
The
assembly-time default is 0 (i.e., area 0).

where

In the following example, the user assigns the index level of the
defined by the XAB called KEYDEF to area 2.
AREA2:

XAB$B

XB$ALL

X$AID

XAB$E

KEYDEF:

XAB$B

XB$KEY

X$IAN

XAB$E

7-9

key

EXTENDED ATTRIBUTE BLOCKS
7.4.5

IFL - Index Bucket Fill Size

At $CREATE time, you can use the IFL field to specify how many bytes
you want used in each index level bucket of the associated index. By
specifying less than the total bucket size, you indicate that the
index buckets are not to be completely filled but are to contain.some
amount of free space. At runtime, RMS-II adheres to the fill size
specified at $CREATE time only if the RB$LOA value is present in the
record processing options (ROP) field of the RAB.
When the key definition XAB describes the primary key, the IFL field
describes space in buckets in all levels of the tree-structured
primary index down to and including the level containing pointers to
the user data records themselves. When the XAB describes an alternate
key, IFL applies to all levels of the tree-structured alternate index
down to, but not including, the level containing buckets in which
RMS-II maintains pointer arrays describing the user data records.
You may want to use the facility provided by the IFL field
(and the
similar facility provided by the DFL field, described in Section
7.4.2) in the following situation: If you expect to perform numerous
$PUT and $ UPDATE operations on the file after it has been initially
populated, you can minimize the resultant movement of index entries
(known as bucket splitting) by specifying a less than maximum bucket
fill size at $CREATE time. To use the free space thereby reserved in
the index buckets, programs that perform $PUT or $UPDATE operations on
the file should not place, at $CONNECT time, the value RB$LOA in the
ROP field of the RAB.
You can initialize the IFL field at assembly-time
macro. The format of the X$IFL macro is as follows:

with

the

X$IFL

X$IFL space
where
space

is a numeric value representing the maximum number
of bytes to be used in the index buckets. The
assembly-time default is 0, which is interpreted
at runtime by RMS-II as meaning the bucket size in
bytes (i.e., no unused space).

The following is an example of the X$IFL macro:
KEYDEF:

XAB$B

XB$KEY

X$IFL

300

XAB$E
In this example, the user specifies
bucket are to be used.

7-10

that

300

bytes

each

index

EXTENDED ATTRIBUTE BLOCK,S
7.4.6

KNM - Key Name Address

The Key Name Address (KNM) field can contain the address of a
32-character ASCII string.
When you are defining a key, you can
associate any 32-character string you choose with the key field
represented by the XAB. RMS-ll never examines this character string
but retains it in the file as part of the key definition information.
You can initialize the KNM
macro. Its format is:

field

assembly-time

with

the

X$KNM

X$KNM address
where
is the symbolic address of a buffer. This buffer
should alwa~s be at least 32 bytes in length. A
value of 0 in this field indicates that no key
name is defined ($CREATE) or is to be displayed
($OPEN or $DISPLAY).

address

7.4.7

LAN - Lowest Index Level Area Number

You set a value in the LAN field only when both of the
true:

following

You are creating a new indexed file.

You are using allocation XABs
(refer to Section
control the placement and structure of the file.

are

7.6)

If both of the above are true, then the LAN field allows you to
separate the lowest level of the index from all higher levels by
specifying a different area number than that specified by the IAN
field.
However, the bucket size of the area specified by the LAN
field must be the same as that of the area identified by the IAN
field.
You can initialize the LAN
macro:

field

assembly-time

with

the

X$LAN

aid

is a numeric value from 0 to 254.
A value of 0
indicates that the lowest level of the index is to
occupy the same area as the remainder of the index.
Values from I to 254 represent an area identification
number contained in the AID field of an allocation XAB.
The assembly-time default is o.

where

7.4.8

NUL - Null Key Value

The NUL field can contain any user-selected character value. When you
create an indexed file, however, RMS-Il examines and saves the
contents of this field only if the value XB$NUL is present in the FLG
field of the block. F~rther, the null key facility is available only
for Extended Attribute Blocks that define an alternate key.

7-11

EXTENDED ATTRIBUTE BLOCKS
When writing a record into an indexed file, RMS-ll normally updates
all
indexes of the file to reflect the values found in the
corresponding key fields of the record. However, if a null key value
is defined for a particular alternate key, RMS-ll examines the
contents of the key field in the record.
If this field consists
solely of the null key characters specified in the NUL field of the
XAB that defined the key at $CREATE time, RMS-ll will not make an
entry in the associated alternate index for the record.
The X$NUL macro can be used to initialize the NUL
assembly-time. The format of this macro is as follows:

field

X$NUL value
where
value

is any user-selected character value.

The following are two examples of the X$NUL macro:
1.

KEYDEF:

XAB$B

XB$KEY

X$FLG
X$NUL

XB$NUL
<IZ>

XAB$E

KEYDEF:

XAB$B

XB$KEY

X$FLG
X$NUL

XB$NUL
<"'0177>

XAB$E
In the first example, the user specifies that any record containing
all ZI S in the key field defined by the current XAB is not to have an
entry made for it in the associated alternate index.
In the second
example, the user specifies the same action but the null key value is
the ASCII character DEL.

7.4.9

POS - Key Position

In combination with the SIZ field, the POS field defines the location
of the key within each record of the file. The POS field is eight
words in length because two types of keys can be defined
simple
keys and segmented keys.
A simple key is a single string of contiguous bytes in the record.
The first word of the POS field specifies the starting position of the
string and the remaining words contain zeros.
A segmented key consists of two to eight strings of bytes in the
record.
Each individual string
(segment)
is a set of contiguous
bytes, but the strings need not be contiguous with each other, nor
7-12

EXTENDED ATTRIBUTE BLOCKS
need they be in any particular order. Each successive word of the POS
field specifies the starting position of one of the segments.
When
processing records that contain segmented keys, RMS-ll treats the
individual segments of the key as a single, logically contiguous
string beginning with the first segment and ending with the last.
The X$POS macro can be used
assembly-time.
The format of
follows:

to initialize the POS
this macro for simple

field
at
keys is as

X$POS position
where
position

is a numeric value representing the starting
position of the key within each record. The first
byte of a record is represented by a value of 0,
the second by a value of 1, etc.

For segmented keys, the format of the X$POS macro is as follows:
X$POS

<posO,posl[,pos2 ••• ,pos7]>

where
posO,posl,etc. are numeric values representing starting positions
of each segment of the segmented key. Up to eight
values can be specified. It is not necessary that
the
list of values represent ascending byte
positions in the record. To define a segmented
key, the POS field and the SIZ field must contain
an equal number of successive values.
Three examples of the X$POS macro follow:
1.

KEYDEF:

XAB$B

XB$KEY

X$POS

XAB$E
2.

KEYDEF:

XAB$B

XB$KEY

X$POS

XAB$E
3.

KEYDEF:

XAB$B

XB$KEY

X$POS

<19,0,13,28>

XAB$E
7-13

EXTENDED ATTRIBUTE BLOCKS
In the first example, the user defines a simple key that begins in the
first byte of each record. The second example shows the specification
of a simple key beginning in the ninth byte of each record.
To
complete the definition of these simple keys, the user must establish
a corresponding value in the key size (SIZ) field of the block.
In
the third example,
the user specifies a segmented key. The first
segment of the key begins in the twentieth byte,
the second segment
begins in the first byte, the third segment in the fourteenth byte,
and the fourth segment in the twenty-ninth byte.
To complete the
definition of this segmented key, the user must establish four values
for the size field
(SIZ)
corresponding to these four
segment
positions.

7.4.10

REF - Key of Reference

The key of reference (REF) field identifies which key (i.e., primary,
first alternate, second alternate, etc.) is defined by the XAB.
The X$REF macro allows you to initialize the
REF
assembly-time. The format of this macro is as follows:

field

X$REF value
where
value

is a numeric value, in the range of 0 to 254,
indicating which key is represented by the current
block. A value of 0 indicates the primary key,
1
indicates the first alternate key, etc.
The
assembly-time default value for the REF field is
zero (i.e., primary key).

The following are two examples of the X$REF macro, showing
specification
of
a
primary key in the first case, and
specification of a third alternate key in the second case.
1.

KEYDEF:

XAB$B

XB$KEY

X$REF

XAB$E
2.

KEYDEF:

XAB$B

XB$KEY

X$REF

XAB$E

7-14

the
the

EXTENDED ATTRIBUTE BLOCKS
7.4.11

RVB - Root Virtual Block Number

When a key definition XAB is present during an $OPEN or $DISPLAY
operation, RMS-ll sets RVB to the number of the virtual block of the
file that contains the root of the index for the key described by the
XAB.

7.4.12

SIZ - Key Size

The key size (SIZ)
field specifies the length of the key whose
starting position is contained in the POS field of the same block.
The X$SIZ macro
assembly-time.

can

used

initialize

the

SIZ

field

For simple keys, the format of the X$SIZ macro is as follows:
X$SIZ size
where
size

is a numeric value representing the length
(in
bytes)
of the key defined by the block. Allowed
values for the SIZ field are 1 to 255.

For segmented keys, the format of the X$SIZ macro is as follows:
X$SIZ <sizeO,sizel [,size2 ••• size7]>
where
sizeO,sizel,etc. are numeric values representing the length of
each segment of the segmented key.
Up to eight
values can be specified.
The
total
size
specified must be less than 256. To define a
segmented key, you must provide an equal number
of values for the SIZ and POSfields of the
block.
For example, the first value specified
on an X$POS macro will be combined with the
first value on an X$SIZ macro to define the
location and length of the first segment of the
segmented key, etc.
Two examples of the X$SIZ macro follow:

KEYDEF:

XAB$B

X$SIZ

XB$KEY

XAB$E
2.

KEYDEF:

XAB$B

XB$KEY

X$SIZ

<8,2,5,32>

XAB$E
7-15

EXTENDED ATTRIBUTE BLOCKS
In the first example, the user specifies a key length of 8 bytes.
In
the second example,
the user specifies the lengths of the four
segments of a segmented key. Assume that the following initialization
macro is also present for the same block:
X$POS <19,0,13,28>
The following is the full definition of the segmented key:
Start position

Length

20th byte
1st byte
14th byte
29th byte

8 bytes
2 bytes
5 bytes
32 bytes

Total Key Length

7.5

47 bytes

FILE PROTECTION SPECIFICATION EXTENDED ATTRIBUTE BLOCK

A file protection specification Extended Attribute Block contains
protection information for the associated file. Wh~n you create a
file, you can use this type of XAB to explicitly ass1gn protection
codes.
When you open an existing file, you can use this type of XAB
to obtain the protection codes specified when the file was created.
Table 7-4 describes the fields of this type of XAB.
Table 7-4
File Protection Specification XAB Fields
Description

Field Name

Field Size

COD

1 byte

Code field
XB$PRO.

NXT

1 word

Next XAB.

PRG

1 word

Programmer
number
portion
owner's user identification
(Ule).

PRJ

1 word

Project number portion of owner's
user identification code (UlC).

PRO

1 word

System
value.

contains

dependent

file

the

value

of
code

protection

The following sUbsections describe the fields listed in Table 7-4 that
are unique to the file protection specification XAB.

7-16

EXTENDED ATTRIBUTE BLOCKS
7.5.1

PRG - Programmer Number

The PRG field contains the programmer
owner's user identification code.

number

portion

the

file

The X$PRG macro can be used to initialize the PRG field
assembly-time. The format of the X$PRG macro is as follows:

X$PRG number
where
number

is a numeric value representing a programmer
number.
The specified value must range from 1 to
255.

The following is an example of the X$PRG macro:
PRODEF:

XAB$B

XB$PRO

X$PRG

XAB$E

7.5.2

PRJ - Project Number

The PRJ field contains the project number portion of the file
user identification code.
The X$PRJ macro allows you to initialize the
PRJ
assembly-time. The X$PRJ macro takes the following form:

owner's

field

X$PRJ number
where
number

is a numeric value representing a project number.
The specified value must range from 1 to 255.

The following is an example of the X$PRJ macro:
PRODEF:

XAB$B

XB$PRO

X$PRG

211

XAB$E

7-17

EXTENDED ATTRIBUTE BLOCKS
7.5.3

PRO - System File Protection Value

The system file protection value (PRO) field
access privileges of four classes of users:

identifies

the

file

Group

the class of users with the same project number as
contained in the PRJ field of the current block.

Owner

the owner of the file.

System

users
executing
under
identification code.

privileged

user

World

all users not within the group, owner, and
categories.

system

The format of the one-word PRO field is as follows:

Bits

12 11

15
WORLD

GROUP

Figure 7-1

SYSTEM

OWNER

Format of PRO Field

Each of the four categories above has four bits:
following meaning with respect to file access:

Bit

DELETE

EXTEND

Figure 7-2

each

bit

has

the

o
WRITE

READ

File Access Bits

A bit value of zero (0) indicates that the respective type of access
to the file is to be allowed: a bit value of one (1) indicates that
the respective type of access to the file is to be denied.
The X$PRO macro initializes
format is:

the

PRO

field

assembly-time.

Its

X$PRO

protect

is a numeric value representing the
desired
encoding for the I-word field. The default radix
for this value is decimal. Use of the MACRO-II
octal radix unary operator will facilitate the
setting of this field.

where

7-18

EXTENDED ATTRIBUTE BLOCKS
In the following example, the user grants full access rights to the
system and owner and restricts the group and world classes to read
only privileges.
X$PRO <~0167000>

7.6

ALLOCATION EXTENDED ATTRIBUTE BLOCKS

Each allocation XAB describes one area of a file.
An area is a
portion of a file that is treated as a single entity for the purposes
of:
initial allocation
extension
placement control
bucket size
Only indexed files can contain more than one area. Multiple areas, if
present, in an indexed file are consecutively numbered beginning with
o. Sequential and relative files are always composed of a single area
(area 0).
In allowing you to define
following two purposes:

file

areas,

allocation

XABs

They allow you to control the physical placement
(of any organization) on a volume.

They allow you
indexed file.

control

the

internal

serve

the

file

structure

a
of

To control the physical placement of a file on a volume, you provide
one (for any type of file) or more (for indexed files only) allocation
XABs linked to the FAB you use to create the file.
Within each
allocation XAB are two fields -- alignment (ALN) and location (LOC).
If you set the symbolic value XB$LBN in the ALN field, and a numeric
value in the LOC field, RMS-ll considers the contents of the LOC field
as a logical block number on the volume.
RMS-ll then attempts to
allocate the initial virtual block of the area represented by the XAB
at the specified logical block. The same allocation XAB allows you to
specify the initial allocation size (ALQ) and, for indexed files only,
a default extension quantity (DEQ) for the area.
Either with or without the placement control facility, you can use
allocation XABs to control the internal structure of an indexed file.
You can define multiple areas within such a file, assign the index and
data levels associated with keys to particular areas, and vary the
size of buckets on a per-area basis.
Indeed, varying the size of
buckets among different areas of an indexed file can be the primary
motivation for your use of allocation XABs.
For example, if your
indexed
file
will
contain large data records, you may want
particularly large buckets for the data level of the primary key.
However, you may not want to use the same size buckets for the index
levels of the key. Conversely, for another indexed file, you might
want index level buckets that are larger than data level buckets in
order to minimize the number of index levels that RMS-ll must traverse
to access any record.

7-19

EXTENDED ATTRIBUTE BLOCKS
Both facilities provided by allocation XABs -- placement control and
indexed file structuring -- are completely optional.
If you do not
require either of these facilities, you do not need allocation XABs.
In the absence of allocation XABs, RMS-ll provides the following
defaults:
1.

When you create a new file
(of any organization), RMS-ll
allocates a single area
(implicitly, area 0) to the file.
The initial size of this area is specified in the ALQ field
of the FAB and the file-level default extension quantity in
the DEQ field of the FAB. The physical placement of the file
on the volume is completely under the control of the host
operating system.

For an indexed file, the absence of allocation XABs when
creating a file results in the allocation of a single area
(again, area 0) for the entire file and the use of a single
bucket size for the entire file.

When the preceding defaults are unsuitable for a particular file,
will need allocation XABs in your program.

you

Once you create (via $CREATE) a particular file using allocation XABs,
you can also use such XABs with the $EXTEND, $OPEN, and $DISPLAY macro
calls. Table 7-5 lists the fields in an allocation XAB.
The
subsections that follow describe the function of each field with each
of the macro calls.
Table 7-5
Allocation XAB Fields
Field Name

Field Size

Description

AID

1 byte

Area identification number.

ALN

1 byte

Alignment boundary type.

ALQ

2 words

Allocation quantity.

AOP

1 byte
(bit string)

BKZ

1 byte

Bucket size.

COD

1 byte

Code field.
Contains the
value XB$ALL.

DEQ

1 word

Default area extension quantity.

LOC

2 words

Allocation starting point.

NXT

1 word

Next XAB.

VOL

1 word

Relative volume number.

Allocation option.

7-20

EXTENDED ATTRIBUTE BLOCKS
7.6.1

AID - Area Identification Number

The area identification (AID) field identifies the area of the file
described by the allocation XAB.
You are always responsible for the
contents of this field.
It is never set by RMS-ll.
Rather, RMS-ll
uses this field to:
1.

Check the sequencing of allocation XABs in an XAB chain. For
all operations
(i.e., $CREATE, $EXTEND, $OPEN, $DISPLAY),
allocation XABs in an XAB chain must appear in ascending
order, based on the contents of the AID field in each.

Identify the target area
$CREATE, $EXTEND, etc.).

You can initialize the AID
macro. Its format is:

field

for

specific

assembly-time

operation

(e.g.,

with

X$AID

the

X$AID

area

is a numeric value indicating which area of the file is
described by the current block. Area identification
numbers range from 0 to 254. If the organization of
the file is sequential or relative, only a single
allocation XAB can be used for any operation and its
AID field must contain o. The assembly-time default
for this field is o.

where

In the following example, the user establishes an allocation
area 1 of an indexed file:
ARl:

XAB$B

XB$ALL

X$AID

XAB

for

XAB$E

7.6.2

ALN - Alignment Boundary Type

The alignment boundary type
(ALN)
field specifies the type of
alignment requested for the area described by the block.
If you
require placement control over the initial allocation
($CREATE)
or
explicit extension
($EXTEND)
of the area, you use this field to
specify whether the LOC field contains a logical block number or a
virtual block number.
If you do not wish to exercise placement
control during a $EXTEND or $CREATE operation, you set this field
equal to zero.
When allocation XABs are present during a $OPEN or $DISPLAY operation,
RMS-ll sets the ALN field equal to the value specified for the
corresponding area when the file was created.
You can use the X$ALN macro
assembly-time. Its format is:
X$ALN

type
7-21

initialize

the

ALN

field

EXTENDED ATTRIBUTE BLOCKS
where
type

is a symbolic value or O.
One
symbolic values can be specified:

the

following

XB$LBN

align area (or extension to area) on or near
logical block described by LOC field.

XB$VBN

perform allocation as near as possible to
the virtual block described by LOC field.
If LOC contains 0, RMS-ll will allocate
space as near as possible to the current
high virtual block of the file.
If the AID
field of the block specifies area 0, the
value XB$VBN is invalid during a $CREATE
operation.

RMS-ll interprets a value of 0 in the ALN field as
meaning no placement control is being exercised by the
user. The assembly-time default is o.
In the following example, the user indicates that no placement control
is described by the current allocation XAB.
AR1:

XAB$B

XB$ALL

X$ALN

XAB$E

7.6.3

ALQ - Allocation Quantity

The allocation quantity (ALQ) field specifies the number of virtual
blocks in the initial allocation of the area (when the allocation XAB
is used with the $CREATE operation) or the number of virtual blocks by
which the area is to be extended (when the block is part of a $EXTEND
operation). For both operations, the value you specify in this field
overrides the contents of the ALQ field in the FAB. RMS-ll neither
examines nor sets this field during $OPEN and $DISPLAY operations.
The X$ALQ macro allows you initialize the ALQ field in this
assembly-time. The format of this macro is as follows:

block

X$ALQ

quantity

is a numeric value in the range of 0 to 16,777,215
representing a number of virtual blocks.
If, during a
$CREATE operation, the user-specified quantity in the
ALQ field for allocation area 0 is less than the number
required to store necessary file attributes, RMS-ll
ignores
the user-specified value and allocates a
sufficient number of virtual blocks.

where

7-22

EXTENDED ATTRIBUTE BLOCKS
In the following example of the X$ALQ macro, the user specifies that
400 virtual blocks are to be allocated to the area described by the
block:
ARl:

XAS$B

XB$ALL

X$ALQ

400

XAB$E

7.6.4

AOP - Allocation Options

The allocation options (AOP) field allows you to qualify the action
RMS-ll is to perform when the block is present during a $CREATE or
$EXTEND operation. For $OPEN and $DISPLAY operations, RMS-ll returns
into this field the options specified when the area was created (via
$CREATE).
The X$AOP macro can be used
assembly-time. Its format is:

initialize

the

AOP

field

X$AOP

option[!option]

option

is a symbolic value representing an option to be
applied during a $CREATE or $EXTEND operation. You can
specify either or both of the following:

where

XB$HRD

Hard req~est.
This
option
should
be
specified only if the ALN field contains the
value XB$LBN. RMS-ll returns an error code
if
the initial allocation ($CREATE) or
extension ($EXTEND) of the area cannot be
aligned on the logical block specified by
the LOC field. The default is to perform
the allocation as close as possible to the
requested alignment.

XB$CTG

Contiguous
allocation
requested.
The
assembly-time default is non-contiguous.

In the following example of the X$AOP macro, the user specifies a hard
request for a contiguous allocation:
ARl:

XAB$B

XB$ALL

X$AOP

XB$CTG!XB$HRD

XAB$E

7-23

EXTENDED ATTRIBUTE BLOCKS
7.6.5

BKZ - Bucket Size

The BKZ field specifies the size of the buckets in the area described
by the allocation XAB.
This field is used for indexed files only.
During a $CREATE operation, the value you specify in this field
supersedes the contents of the BKS field in the FAB. During $OPEN and
$DISPLAY operations, RMS-ll returns into this field the
value
specified when the area was created. The primary purpose of this
field is to allow you to vary the size of buckets among the multiple
areas of an indexed file.
The X$BKZ macro allows you to initialize the
BKZ
assembly-time. The format of this macro is as follows:
X$BKZ

field

bucket-size

where
bucket-size

is a numeric value, in the range of 0 to 32,
representing
the
number
of
virtual blocks
contained in each bucket in the area of the file.
The assembly-time default is o. RMS-ll interprets
a value of 0 as identical to 1.

The following is an example of the X$BKZ macro
specification of four virtual blocks per bucket:
ARl:

showing

the

XAB$B

X$BKZ

XAB$E

7.6.6

DEQ - Default Area Extension Quantity

The default area extension quantity (DEQ)
field applies to indexed
files only.
It specifies the number of virtual blocks to be used when
RMS-ll must automatically extend the area described by the XAB.
This
automatic extension occurs whenever your program attempts a $PUT or
$UPDATE operation that cannot be accommodated within the space
currently allocated to the area.
During a $CREATE operation, RMS-ll examines the value you specified in
this field.
If this value is nonzero, RMS-ll saves it as the default
extension quantity for the area defined by the XAB. If, however, the
DEQ field in this block is zero, RMS-ll saves the FAB's DEQ as the
default extension quantity for the area defined by the XAB.
The DEQ field in the allocation XAB is neither examined nor set during
a $EXTEND operation. During a $OPEN or $DISPLAY operation, however,
RMS-ll returns into this field the value specified when the area was
created.
You can use the X$DEQ macro to initialize the DEQ field
allocation XAB at assembly-time. The format of this macro is:
X$DEQ

quantity

7-24

EXTENDED ATTRIBUTE BLOCKS
where
quantity

is a numeric value representing a number of virtual
blocks.
This number must be in the range of from 0 to
65,535. The quantity you specify should be a multiple
of the area's bucket size. The assembly-time default
is o.

In the following example, the user specifies that, when automatic
extension is necessary, RMS-ll is to extend the area by 80 virtual
blocks.
ARl:

XAB$B

X$DEQ

XAB$E

7.6.7

LOC - Allocation Starting Point

The allocation starting point (LOC)
field is used by RMS-ll only
during $CREATE and $EXTEND operations. Further, the contents of this
field are ignored during such operations if the ALN field of the same
block is zero. When, however, the ALN field contains XB$LBN, RMS-ll
interprets the contents of LOC as the starting logical block number on
the volume for the initial allocation ($CREATE) or extension ($EXTEND)
of the area. The ALQ field of the same block contains the number of
blocks to be allocated and the AOP field can optionally specify
(XB$HRD) that the allocation must begin with the specified logical
block.
When the ALN field contains XB$VBN during a $CREATE or $EXTEND
operation, RMS-ll interprets the contents of LOC as a virtual block
number within the file. For $CREATE operations, LOC must contain
zeroes since no virtual blocks as yet exist in the file. However,
during $EXTEND operations, LOC can contain the number of a virtual
block in the file near which the extension to the area is to be
allocated. Again, you use the ALQ field to specify the size of the
extension.
Note, how.ever, that the allocation options (AOP) field
cannot contain XB$HRD.
During $OPEN and $DISPLAY operations, RMS-ll neither sets nor examines
the LOC field.
The X$LOC macro allows you
assembly-time. Its format is:

initialize

the

LOC

X$LOC

number

is a numeric value interpreted as follows:

field

where

If ALN contains XB$LBN, the specified number is the
starting logical block for the allocation. The
specified number may vary from 0 to the maximum
number of blocks on the volume.

7-25

EXTENDED ATTRIBUTE BLOCKS
2.

If ALN contains XB$VBN, the specified number is a
virtual block within the file.
The specified
number may vary from 0 to the number of virtual
blocks in the file. A value of 0 (assembly-time
default) implies that allocation should occur as
near as possible to the current end of file.

The following is an example of the X$LOC macro:
ARI:

XAB$B

X$AOP
X$ALN
X$LOC

XB$HRD
XB$LBN
1024

XAB$E
In this example, the user specifies that allocation of an extent for
the area represented by the XAB must begin on logical block number
1024.

7.6.8

VOL - Relative Volume Number

The relative volume number
(VOL) field
assembly-time default for this field is o.

7.7

must

contain

The

SUMMARY EXTENDED ATTRIBUTE BLOCK

The summary XAB allows you to determine the number of keys defined for
an existing indexed file and/or the number of allocation areas defined
for an existing file.
You never use this type of XAB with a $CREATE macro call. However, a
summary XAB can be associated with a FAB at the time a $OPEN or
$DISPLAY macro call is issued. The presence of this XAB during these
macro calls allows RMS-I1 to return to your program the total number
of keys and allocation areas defined when the file was created.
Table 7-6 describes the fields of a summary XAB.
Table 7-6
Summary XAB Fields
Description

Field Name

Field Size

COD

I byte

Code field.
XB$SUM.

NOA

I byte

Number of allocation areas
for the file.

NOK

1 byte

Number
file.

NXT

1 word

Next XAB.
7-26

Contains

keys

defined

the

value
defined

for

the

CHAPTER 8
THE NAME BLOCK

The Name Block is an optional structure. After a successful $CREATE,
$OPEN, or $ERASE macro call, a location described by this block
contains the full file specification resulting from RMS-ll's merger of
the default file name string (described by the DNA and DNS fields of
the associated FAB) with the primary name string (described by the FNA
and FNS fields of the associated FAB) and system defaults. You
indicate that this service is desired by assuring that the NAM field
of the FAB contains the address of a Name Block at the time a $CREATE,
$OPEN, or $ERASE macro is issued.
The following sUbsections describe the allocation of a Name Block
assembly-time initialization macros for fields in the block.

8.1

and

ALLOCATING A NAME BLOCK

The NAM$B macro allocates space for a
beginning of an optional sequence
macros for the fields of the block.

Name Block and delimits the
of assembly-time initialization

The format of the NAM$B macro is as follows:
label:NAM$B
where
label

is a user-specified symbol that
names
this
particular Name Block. You must ensure that the
address assigned to this label is word-aligned.
Therefore, a .EVEN directive should immediately
precede the NAM$B macro.

The NAM$E macro delimits the end of the optional sequence of
assembly-time initialization macros initiated by NAM$B and stores any
specified values in the appropriate fields of the block.
This macro
must always appear subsequent to an associated NAM$B macro, even when
no intervening initialization macros are coded.
The NAM$E macro takes the following form:
NAM$E
The following example shows the allocation
FNAME:
FNAME:

• EVEN
NAM$B
NAM$E
8-1

Name

Block

called

THE NAME BLOCK
8.2

FIELDS IN THE NAME BLOCK

Table 8-1 summarizes the fields in a Name Block.
Table 8-1
Name Block Fields
Field Name

Field Size

Description

ESA

1 word

Expanded string address

ESL

1 byte

Expanded string length

ESS

1 byte

Expanded string size

The subsections that follow describe the fields listed in Table 8-1.

8.2.1

ESA - Expanded String Address

The expanded string address (ESA) field contains the address of a
user-allocated buffer.
Following a $OPEN, $CREATE, or $ERASE macro
call, RMS-ll pla~es in this buffer the file specification string
resulting from the application of default information (provided by the
default name string of the FAB and system defaults)
to the original
file string
(file name string of the FAB). The ESA buffer must be
present if the block itself is input to an operation
(i.e., the NAM
field of the FAB is nonzero).
The N$ESA macro allows you to initialize the
ESA
field
assembly-time. The following is the format of the N$ESA macro:

N$ESA address
where
is the symbolic address of a buffer
program.

address

The following is an example of the N$ESA macro:
NAMBUF: .BLKB

FNAME:

32.

NAM$B

N$ESA

NAMBUF

NAM$E

8-2

the

user

THE NAME BLOCK
8.2.2

ESL - Expanded String Length

The expanded string length (ESL) field is set by RMS-II after a $OPEN,
$CREATE, or $ERASE macro call. This field contains the actual length
of the expanded file specification whose address is in the ESA field.

8.2.3

ESS - Expanded String Size

The expanded string size
(ESS) field contains the size of the
user-allocated buffer whose address is in the ESA field of the block.
You can initialize the ESS field at assembly-time
macro. The format of the N$ESS macro is as follows:

with

the

N$ESS

N$ESS size
where
size

is a numeric value representing the size
(in
bytes) of the buffer whose address is in the ESA
field. The specified value must range from I to
255.

In the following example, the user specifies an expanded
of 32 bytes:
FNAME:

NAM$B
N$ESA

NAMBUF

N$ESS

NAM$E

8-3

string

area

CHAPTER 9
PERFORMING FILE AND RECORD OPERATIONS

This chapter describes the RMS-ll macros used to access and manipulate
files and records within files.
As described in Chapter 2,· file and record processing macros in
combination
with user control blocks form the runtime program
interface with RMS~ll. The primary argument of a file processing
macro call is the address of a File Access Block. The primary
argument of a record processing macro call is the address of a Record
Access Block.
Certain fields within these blocks must contain
appropriate values at the time a particular file or record processing
macro call is issued.
Following such macro calls, RMS-Il returns
information to your program within fields of the same control block.
The detailed descriptions of file and record processing macros in this
chapter, therefore, list all control block fields used as input to a
macro call and every field that may contain information returned to
your program by RMS-Il.
The remainder of this chapter is divided into three sections:
1.

File and record operation macro conventions (i.e., macro
formats, the RMS-ll calling sequence, completion routines,
control block field usage, and status codes).

Performing file oper.ations (i.e., $CREATE,
$ERASE, $EXTEND, $CLOSE).

Performing record operations (i.e., record access streams,
record operations and file sharing, current context of record
operations,
synchronous
and
asynchronous
operations,
accessing records, and record operation macros).

$OPEN,

$DISPLAY,

NOTE
When RMS-II is executing, asynchronous
system traps (ASTs) are disabled. When
RMS-ll returns to your program, ASTs are
enabled.

9.1

FILE AND RECORD OPERATION MACRO CONVENTIONS

While differing in function, file and record operation macros have the
same general format.
Furthermore, each macro call for an RMS-Il
service requires the establishment of a standard calling sequence.
Within this calling sequence, you can optionally specify the addresses
of completion routines.

9-1

PERFORMING FILE AND RECORD OPERATIONS
Before issuing the actual file or record operation macro call, your
program must ensure that the control block (i.e., FAB or RAB) contains
appropriate values in the fields that will be examined by RMS-Il.
Following execution of the macro call, your program should examine the
status code returned by RMS-ll in the control block to ascertain the
success or reason for failure of the operation.
The following
subsections, therefore, describe:
format of file and record processing macros
• The
The
RMS-ll
sequence
• Completion calling
routine
conventions
•
block field usage
• Control
Status
codes
•
9.1.1

Format of File and Record Operation Macros

You can code file and
following two formats:

record

operation

macros

either

the

referring

the

label:$macro
or

label:$macro

block[,error[,success]]

where
label

is an optional user-defined
macro.

$macro

is one of the file or record operation macros described
in this chapter.

block

is the address
operations) or
operations.)

of
a

symbol

a File Access Block
(for file
Record Access Block
(for record

error

is the address of a user completion routine
called if the requested operation fails.

success

is the address of a user completion routine to be
called
if
the
requested
operation
completes
successfully.
This argument is ignored for
file
processing macro calls.

In the second format, the presence of arguments causes the macro
expansion to build an argument list on your program's stack.
In the
first format above, however, no arguments appear following the macro
name.
In this format, therefore, you must create the argument list in
your program. The following sUbsection describes this process.
NOTE

The first format of RMS-ll file and
record operation macros (i.e., without
an argument list) generates less code
and uses less stack space than the
second format.

9-2

PERFORMING FILE AND RECORD OPERATIONS
9.1.2

The RMS-ll Calling Sequence

At the time an RMS-ll routine is called, general register R5 must
contain the address of a word-aligned formatted argument list. Figure
9-1 shows the format of this list:
UNDEFINED

ARGUMENT COUNT

BLOCK

ADDRESS

ERROR

ADDRESS

....--RS

SUCCESS ADDRESS
Figure 9-1

Argument List Format

RMS-ll interprets the fields within the argument list as

foll~ws:

Argument Count

is a binary value from 1 to 3 representing
the
number of arguments present 1n the
argument list. This count field must equal 1
if the user does not specify completion
routine addresses.

Block Address

is the address of a File
file operations) or a
(for record operations).

Error Address

is the address of a user completion routine
to be called if the requested operation
fails.

Success Address

is the address of a user completion routine
to be called if the requested operation
completes successfully.
This argument is
ignored for file processing macro calls.

Access Block
(for
Record Access Block

The preceding argument list is automatically generated whenever you
specify a file or record processing macro with arguments. When
specifying these macros without arguments, your program must construct
the argument list. For example, if you want to read a record from a
file and specify both an error and a success completion routine,
the
equivalent of the following sequence must be coded:
MOV #LIST,R5
$GET

LIST: .WORD
• WORD
• WORD
• WORD

iADDRESS OF ARGUMENT
iLIST TO REGISTER 5
iRECORD PROCESSING MACRO
iTO READ A RECORD

iNUMBER OF ARGUMENTS

INRAB
ERRI
SUCCI

iRECORD ACCESS BLOCK ADDRESS
iERROR ROUTINE ADDRESS
iSUCCESS ROUTINE ADDRESS

If you wanted to specify a success routine without specifying an error
routine, you would use the following code for the argument list:
LIST: .WORD
• WORD
.WC;>RD
• WORD

iNUMBER OF ARGUMENTS

INRAB

iRECORD ACCESS BLOCK ADDRESS

-1

i-I MEANS NO ERROR ROUTINE

SUCCI

iSUCCESS ROUTINE ADDRESS

9-3

PERFORMING FILE AND RECORD OPERATIONS
If neither a success nor an error routine is specified,
list is constructed as follows:
LIST: .WORD
• WORD

~NUMBER

INRAB

~RECORD

argument

OF ARGUMENTS
ACCESS BLOCK ADDRESS

Finally, if only an error routine is specified,
the argument list as follows:
LIST: .WORD
• WORD
• WORD

the

you

would

construct

OF ARGUMENTS
ACCESS BLOCK ADDRESS
~ERROR ROUTINE ADDRESS

~NUMBER

INRAB
ERRI

~RECORD

Regardless of the macro format used to invoke an RMS-Il routine,
RMS-ll preserves all general registers (RO-RS) across a macro call.

9.1.3

Completion Routine Conventions

The use of completion routines is always optional. If a corresponding
address is present in the argument list, RMS-Il invokes an error or
success completion routine based on the results of the operation
attempted.
When employing completion routines, you must be aware of
conventions in the areas of:
•
•
•

The subsections that follow discuss each convention.

9.1.3.1 Register Usage Conventions Within Completion Routines - When
RMS-Il calls a user-specified completion routine, the following
register conventions are used:
1.

General register R5 contains the address of the same argument
list, or a copy of the argument list, that was part of the
calling sequence to RMS-Il itself. Therefore, you can use
the control block address at 2(RS) to access fields of the
control block.

General registers RO-R4 are undefined.

9.1.3.2 Issuing RMS-ll Macro Calls Within Completion Routines - As
part of a completion routine, your program can issue an additional
RMS-Il file or record processing macro call.
RMS-Il considers each
such additional macro call as an extension of the original request
that caused the completion routine to be invoked.
The
only
restriction RMS-Il enforces is that a synchronous operation request
cannot be issued within a completion routine called as a result of an
asynchronous record operation.

9-4

PERFORMING FILE AND RECORD OPERATIONS
9.1.3.3 Returning From a Completion Routine - To return control
a completion routine to RMS-ll, your program must:

from

Restore the stack pointer SP to its original value at the
time of entry to the completion routine. Your program must
not attempt to cause control flow changes by modifying the
stack.

Issue a $RETURN macro.

The format of the $RETURN macro is as follows:
label:$RETURN
where
label

9.1.4

is an optional user-defined macro referring
$RETURN macro.

this

Control Block Field Usage

The fields within the control block associated with a particular macro
call are the means by which you qualify or further define the
requested file or record operation. For each particular operation,
some number of control block fields will be used as input by RMS-il.
The tables that accompany each macro description in this chapter
enumerate these fields. You must ensure, before your program issues a
macro call, that the appropriate fields in your control block contain
the necessary values.
You have three choices on how to set values in control block fields:
1.

Assembly-time initialization.

Assembly-time defaulting.

Runtime initialization.

At assembly-time, you can explicitly initialize a field or, when a
default is defined, allow the assembly-time expansion of the block
allocation macros to set a default value in the field.
At runtime,
you can initialize or alter a control block field through use of the
$STORE, $SET, or $OFF macros.
You must understand, however, that
there are no runtime defaults for any field in any control block. "If
you fail to set (at assembly-time or runtime) every field in a control
block that is defined as input to a particular operation, the
ope-ration may fail.
Consider the following example. You write a program that creates an
indexed file and a sequential file. To save storage, you decide to
allocate a single File Access Block.
Therefore, your program will
first create one file, close it, and then reuse the FAB to create the
second file. You allocate a single key definition XAB (assuming your
indexed file has only a single key). To create the indexed file
first, you initialize all the appropriate fields of the FAB (e.g., ORG
contains FB$IDX, RFM contains, perhaps, FB$VAR, etc.). You place the
address of the key definition XAB in the XAB field of the FAB.
Then
you define the primary key of the file through the fields of the XAB
and you set the NXT (next XAB) field in the XAB to zero to indicate
that there are no additional XABs. Finally, you issue the $CREATE
macro call and, if RMS-ll indicates successful completion, you close
the new file by issuing a $CLOSE macro call.
9-5

PERFORMING FILE AND RECORD OPERATIONS
Now your program is ready to create the sequential file.
Using the
$STORE macro, you alter the ORG field of the FAB so that it contains
the value FB$SEQ. You further alter additional fields (RFM, FNA, FNS,
MRS, etc.) so that they accurately describe your sequential file.
However, you neglect to zero the XAB field in the FAB. When you issue
the second $CREATE macro call, RMS-II will find a valid address in the
XAB field.
It will then examine the XAB addressed by this field and
find that it is a key definition XAB. Since sequential files do not
have keys, RMS-Il will reject the create operation and return an error
status code to your program.
As the preceding example shows, you must appropriately set every field
in a control block that RMS-II may use during execution of an
operation. RMS-Il assumes that every value found in an input field
was intentionally placed there for use during the current operation.
Since there are no runtime defaults for control block fields, you are
responsible for the contents of all input fields prior to issuing a
file or record operation macro call.

9.1.5

Status Codes

Before returning to your program from a file or record operation macro
call, RMS-Il always indicates the success or failure of the requested
operation by setting the STS field of the control block associated
with the call.
Through the use of the $COMPARE macro and the mnemonic status codes
listed in Appendix A, your program can check for successful completion
(SU$SUC) or particular error conditions.
While particular error status codes are mentioned in certain sections,
there is no attempt to list all possible error codes that can occur
for every individual file or record operation. Such lists would tend
to duplicate most of the list found in Appendix A.
In writing
programs, therefore, you must examine Appendix A and determine which
error conditions you particularly want to test for following a macro
call. For example, in reading a file, you always want to be prepared
for the ER$EOF error status code (end of file). Whether you test for
other error codes, such as ER$RLK (bucket is locked by another program
or another stream in your own program) depends on the requirements and
logic of your program.
With certain error status codes, RMS-ll returns to your program
additional
information in the STY field of the control block
associated with an operation. The descriptions of error status codes
in Appendix A indicate those instances in which the STY field contains
such information.

9.2

PERFORMING FILE OPERATIONS

A file operation macro call causes RMS-Il to perform some action
related to an entire file.
The macro call itself (e.g., $CREATE,
$OPEN, $CLOSE) indicates the type of action desired.
The fields of
the File Access Block associated with the macro call identify the file
or further qualify the requested action.

9-6

PERFORMING FILE AND RECORD OPERATIONS
Table 9-1 summarizes the file operation macros provided by RMS-ll:
Table 9-1
RMS-ll File Operation Macros
Description

Macro Name
$CREATE

Creates and opens a
organization.

new

RMS-ll

any

$OPEN

Opens an existing RMS-ll file making
contents available for processing.

its

$DISPLAY

Returns attributes of an
user program.

the

$ERASE

Deletes an RMS-ll file and
from a directory.

$EXTEND

Extends the allocated space of an RMS-ll file.

$CLOSE

Closes an open RMS-ll file.

RMS-ll

file

removes

its

entry

The subsections that follow describe the action caused by each file
operation macro and the control block fields that are input to and
output from each operation.

9.2.1

$CREATE - Creating an RMS-ll File

The $CREATE macro creates anew RMS-ll file with the attributes you
specify in the File Access Block and any Extended Attribute Blocks
chained to the FAB.
When key definition or allocation XABs are
present, they must be grouped in densely ascending order (i.e., 0, 1,
2, 3, 4... in the REF or AID fields) without gaps or intervening XABs
of other types. Otherwise, RMS-ll returns an ER$ORD error code. An
illogical XAB type in the chain
(e.g., a summary XAB or a key
definition XAB for a sequential file) causes the ER$COD error
condition. If a NAM Block is also chained to the FAB, RMS-Il sets the
ESL field of the block and places the expanded file specification in
the area addressed by the ESA field of the NAM block.
The $CREATE operation leaves the file open.
the file by issuing a $CLOSE macro call.

Therefore, you must close

NOTE
The $CREATE operation requires 1 BDB and
512 bytes of I/O buffer space, all of
which are released when the operation
completes.
You reserve space for BDBs
through the use of the P$BDB macro
(refer to Chapter 3) and space for I/O
buffers through the P$BUF macro
(refer
to Chapter 3) or the BPA and BPS fields
of the FAB (refer to Chapter 5).
The
calculation of BDB and buffer space
requirements
is
related
to
the

9-7

PERFORMING FILE AND RECORD OPERATIONS
performance of record operations on the
file.
Since any
record
operations
require at least 1 BDB and a buffer at
least 1 virtual block in size, the BDB
and buffer requirements for this file
operation are typically met
without
specific attention on the part of the
user.
The formats of the $CREATE macro are as follows:
1.

label:$CREATE

fab[,error]

where
label

is an optional user-defined symbol referring
$CREATE macro.

fab

is the address of a File
the file to be created.

error

is the address of a user completion routine
called if the $CREATE operation fails.

Access

Table 9-2 lists the fields of the File Access Block
$CREATE macro call.

Block

used

the

representing
to

during

the

Table 9-2
$CREATE FAB Fields
Description

Name
Input

ALQ

Allocation quantity (this field is ignored if
more allocation XABs are present).

one

BKS

Bucket size (this field is ignored for indexed
if one or more allocation XABs are present).

BLS

Block size (magnetic tape files only).

BPA

Buffer pool address.

BPS

Buffer pool size.

DEQ

Default file extension quantity.

DNA

Default name string address.

DNS

Default name string size.

FAC

File access (must contain at least the value FB$PUT).

FNA

File name string address.

FNS

File name string size.

files

(Continued on next page)

9-8

PERFORMING FILE AND RECORD OPERATIONS
Table 9-2 (Cont.)
$CREATE FAB Fields
Description

Name
Input
(Cont. )

Output

9.2.2

FOP

file processing options.

FSZ

Fixed control area size (files with VFC format records
only).

LCH

Logical channel number.

MRN

Maximum record number (relative files only).

MRS

Maximum record size.

NAM

Name block pointer.

ORG

File organization.

RAT

Record attributes.

RFM

Record format.

RTV

Retrieval window size.

SHR

File sharing.

XAB

Extended Attribute Block pointer.

DEV

Device characteristics.

IFI

Internal file identifier.

STS

Completion status code.

STV

Status value.

$OPEN - Opening an Existing File for Processing

The $OPEN macro makes an existing file available for processing by
your program. RMS-ll returns the basic attributes of the file in the
fields of the File Access Block associated with the request.
If
Extended Attribute Blocks are chained to the FAB, RMS-ll fills in the
attribute information represented by each XAB (e.g., key definition
XAB, protection XAB, etc.). When either key definition or allocation
XABs are present, they must be grouped in ascending order (by REF or
AID, respectively) but need not be dense. No other intervening types
are permitted. If this sequencing is violated, RMS-Il returns an
ER$ORD error. Further, RMS-ll does not verify that the number of key
definition or allocation XABs does not exceed the number of actual
keys or areas defined for the file. Any such excess XABs are ignored.
An illogical XAB type in the chain (e.g., key definition XAB for a
sequential file) is similarly ig"nored. Additionally, if a NAM Block
is chained to the FAB, RMS-II sets the ESL field in the NAM Block and
places the expanded file specification of the open file in the
location specified by the ESA field of the NAM Block.

9-9

PERFORMING FILE AND RECORD OPERATIONS

NOTE
The $OPEN operation requires 1 BDB and
512 bytes of I/O buffer space, all of
which are released when the operation
completes.
You reserve space for BDBs
through the use of the P$BDB macro
(refer to Chapter 3) and space for I/O
buffers through the P$BUF macro (refer
to Chapter 3) or the BPA and BPS fields
of the FAB (refer to Chapter 5).
The
calculation of BDB and buffer space
requirements
is
related
to
the
performance of record operations on the
file.
Since any
record
operations
require at least 1 BDB and a buffer at
least I virtual block in size, the BDB
and buffer requirements for this file
operation are typically met
without
specific attention on the part of the
user.
The formats of the $OPEN macro are:
1.

label:$OPEN

fab [ ,er ror]

where
label

is an optional user-defined symbol referring
$OPEN macro.

fab

is the address of a File Access Block representing
file to. be opened.

error

is the address of a user completion
called if the $OPEN operation fails.

during

the

Table 9-3 lists the fields of the File Access Block
$OPEN macro call.

routine
used

the

Table 9-3
$OPEN FAB Fields
Description

Name
Input

BPA

Buffer pool address.

BPS

Buffer pool size.

DEQ

Default extend quantity.

DNA

Default name string address.

DNS

Default name string size.

FAC

File access.
(Continued on next page)
9-10

PERFORMING FILE AND RECORD OPERATIONS
Table 9-3
(Cont.)
$OPEN FAB Fields
Description

Name
Input
(Cant.)

Output

FNA

File name string address.

FNS

File name string size.

FOP

File processing options.

LCH

Logical channel number.

NAM

Name block pointer.

RTV

Retrieval window size.

SHR

File sharing.

XAB

Extended Attribute Block Pointer.
This field is
optional.
If present, RMS-ll will fill the indicated
block (and any XABs chained to the first block) with
the file attribute information indicated by the type
of block present.

ALQ

Allocation quantity. Contains the highest
virtual block allocated to the file.

BKS

Bucket size. Supplied for relative and indexed files
and zeroed for sequential files. When multiple areas
have been defined for an indexed file, BKS contains
the size of the largest bucket in the file.

BLS

Block size (sequential files on magnetic tape only).

DEV

Device characteristics.

FOP

File processing options.
is contiguous.

FSZ

Fixed control area
format is VFC.

IFI

Internal file identifier.

MRN

Maximum record number.
organization is relative.

MRS

Maximum record size.

ORG

File organization.

RAT

Record attributes.

RFM

Record format.

STS

Completion status code.

STV

Status value.

size.

9-11

numbered

Contains FB$CTG if the

file

Supplied

only

record

Supplied

only

file

PERFORMING FILE AND RECORD OPERATIONS
9.2.3

$DISPLAY - Obtaining Attributes of a File

The $DISPLAY macro retrieves file attribute information that you
request and places the information in the fields of Extended Attribute
Blocks. You must open the file in order to obtain attributes.
RMS-ll determines the type of attribute information desired through
examination of the types of Extended.Attribute Blocks associated with
the File Access Block by the XAB field. When either key definition or
allocation XABs are present, they {must be grouped in ascending order
(by REF or AID, respectively) but need not be dense.
No other
intervening types are permitted.
If this sequencing is violated,
RMS-ll returns an ER$ORD error. Further, RMS-ll does not verify that
the number of key definition or allocation XABs does not exceed the
number of actual keys or areas defined for the file. Any such excess
XABs are ignored.
An illogical XAB type in the chain (e.g., key
definition XABs for a sequential file) are similarly ignored.
NOTE
For the duration of its
operation,
$DISPLAY requires 1 BDB (refer to the
P$BDB macro description in Chapter 3)
and 512 bytes of I/O buffer space (refer
to the P$BUF macro
description
in
Chapter 3 or the BPS field description
in Chapter 5). These requirements are
in addition to the BDB and buffer space
requirements for any streams that are
connected at the time the $DISPLAY call
is issued.
The formats of the $DISPLAY macro are as follows:
1.

label:$DISPLAY

fab[,error]

where
label

is an optional user-defined symbol referring
$DISPLAY macro.

fab

is the address of a File Access Block representing a
file whose attributes are to be returned to the user
program.

error

is the address of a user completion routine
called if the $DISPLAY operation fails.

Table 9-4 lists the fields of the File Access Block
$DISPLAY macro call.

9-12

used

the

during

the

PERFORMING FILE AND RECORD OPERATIONS
Table 9-4
$DISPLAY FAB Fields
Description

Name
Input

Output

9.2.4

XAB

Extended Attribute Block pointer.

IFI

Internal file identifier.

STS

Completion status code.

STV

Status value. Contains a system error code
address of the XAB that caused an error.

the

$ERASE - Deleting a File

The $ERASE macro deletes an RMS-ll file and removes its directory
entry.
The space occupied by the file is returned at a system
dependent time. You can issue a $ERASE ope'ration for a file currently
accessed by another program or by your own program (so long as you are
accessing it on a different logical channel).
The file is not
deleted, however, until all accessors close it. You cannot delete
files on unit record or sequential (e.g., magnetic tape) devices.
NOTE
The $ERASE operation requires 1 BOB and
512 bytes of I/O buffer space, all of
which are released when the operation
completes.
You reserve space for BOBs
through the use of the P$BDB macro
(refer to Chapter 3) and space for I/O
buffers through the P$BUF macro (refer
to Chapter 3) or the BPA and BPS fields
of the FAB (refer to Chapter 5).
The
calculation of BOB and buffer space
requirements
is
related
to
the
performance of record operations on the
file.
Since any
record
operations
require at least 1 BOB and a buffer at
least 1 virtual block in size, the BOB
and buffer requirements for this file
operation are typically met
without
specific attention on the part of the
user.
The formats of the $ERASE macro are:
1.

label:$ERASE

fab[,error]

9-13

PERFORMING FILE AND RECORD OPERATIONS
where
label

is an optional user-defined symbol referring
$ERASE macro.

fab

is the address of a file access block representing
file to be deleted.

error

is the address of a user completion routine
called if the $ERASE operation fails.

during

the

Table 9-5 lists the fields of the File Access Block
$ERASE macro call.

used

the

Table 9-5
$ERASE FAB Fields

Input

Output

9.2.5

Name

Description

BPA

Buffer pool address.

BPS

Buffer pool size.

DNA

Default name string address.

DNS

Default name string size.

FNA

File name string address.

FNS

File name string size.

LCH

Logical channel number.

STS

Completion status code.

STV

Status value.

$EXTEND - Extending Allocated Space

The $EXTEND macro extends the amount of space allocated to an RMS-II
file.
The file must be open and any record access streams connected
to the file must be inactive before the extension is attempted.
Before you open the file, the FAC field in your FAB must specify at
least one type of write operation (i.e., FB$PUT, FB$UPD, or FB$DEL).
You cannot extend a file residing on magnetic tape.
If no allocation XABs are present, RMS-II extends, by default, area 0
of the file or
(for sequential or relative files) the file itself.
The allocation quantity field (ALQ) of the File Access Block must
contain the number of virtual blocks to be added to the file.
In the
FOP field of the FAB, you can request a contiguous extent
(FB$CTG).
If RMS-II cannot allocate a contiguous extent, the $EXTEND operation
will fail.

9-14

PERFORMING FILE AND RECORD OPERATIONS
If you created an indexed file using allocation XABs (refer to Section
7.6 in Chapter 7), you can selectively extend one or more areas of the
file by providing appropriate allocation XABs as input to the $EXTEND
operation.
In this case, RMS-ll obtains the amount by which each area
is to be extended from the ALQ field of each XAB.
If you attempt to
extend an area that has a currently unused extent, RMS-ll returns on
ER$LEX error. Allocation XABs, when present, must be in ascending
order by AID (area identification number) but need not be dense.
The formats of the $EXTEND macro are:
1.

label:$EXTEND

fab[,error]

where
label

is an optional user-defined symbol referring
$EXTEND macro.

fab

is the address of a file access block representing
file to be extended.

error

is the address of a user completion routine
called if the $EXTEND operation fails.

during

the

Table 9-6 lists the field of the File Access
$EXTEND macro call.

Block

used

the

Table 9-6
$EXTEND FAB Fields
Description

Name
Input

Output

one

ALQ

Allocation quantity.
Ignored
allocation XABs are present.

FOP

File processing options.
You can specify FB$CTG.
This value will be ignored, however, if one or more
allocation XABs are present.

IFI

Internal file identifier.

XAB

Extended Attribute Block Pointer (optional).

ALQ

Allocation quantity.
This field will contain the
actual number of virtual blocks added to the file.

STS

Completion status code.

STV

Status value.

9-15

PERFORMING FILE AND RECORD OPERATIONS
9.2.6

$CLOSE - Terminating File Processing

The $CLOSE macro closes an open RMS-ll file.
You should issue $DISCONNECT macro calls (refer to Section 9.3.1.2)
for each record access stream associated with a file before issuing
the $CLOSE macro. If you do not issue these $DISCONNECTs, RMS-ll will
effectively disconnect all the file's record access streams. However,
the $CLOSE operation will fail if there is an outstanding I/O request
on any such stream.
Further, the lSI (internal stream identifier)
field in each RAB representing a stream will not be zeroed. Only the
$DISCONNECT macro call zeroes this field. This action is desirable
since it ends the association of a RAB with an internal RMS-ll
structure in the space pool.
If RMS-ll returns a write error (ER$WER) in the STS field of the
it has still closed and deaccessed the file.

FAB,

The formats of the $CLOSE macro are as follows:
1.

label:$CLOSE

fab [, error]

where
label

is an optional user-defined symbol
$CLOSE macro.

referring

fab

is the address of a File Access Block representing the
file to be closed.

error

is the address of a user completion
called if the $CLOSE operation fails.

Table 9-7 lists the fields of the File Access Block
$CLOSE macro ca~l.

routine
used

the

during

the

Table 9-7
$CLOSE FAB Fields
Description

Name
Input

Output

FOP

You
File processing options.
(rewind tape volume on close).

IFI

Internal file identifier.

IFI

Internal file identifier.
",

STS

-Completion status code.

STV

Status value.

9-16

can

(Zeroed)

specify

FB$RWC

PERFORMING FILE AND RECORD OPERATIONS
9.3

PERFORMING RECORD OPERATIONS

After you open a file through a $OPEN or $CREATE macro call, you can
perform record operations on the file.
To perform such record
operations, you must understand in detail the following:
•
•
•
•
•
•

Record Access streams
Record operations and file sharing
Current context of record operations
Synchronous and asynchronous record operations
Accessing records
The actual record operation macros (e.g., $GET, $PUT, $UPDATE,
etc. )

The following subsections describe each of these facilities.

9.3.1

Record Access Streams

To process records in a file, you must establish a record access
stream. A record access stream is the logical association of a Record
Access Block with a File Access Block. Once you have established a
record access stream, you can issue operations on records in the file
represented by the File Access Block.
RMS-ll permits only one record access stream for sequential files.
Thus, when you open or create a sequential file, you can associate
only one RAB with the FAB representing the file.
When you open or
create a relative or indexed file, RMS-Il permits you to establish
multiple record access streams by associating more than one RAB with
the same FAB.
When you establish a single record access stream for a file, your
program uses the stream to issue a sequence of record operations.
Within the stream, these record operations are executed serially.
In
other words, you can process only one record at a time. When you
establish multiple record access streams for a file, your program can
process more than one record of the file in parallel. Thus, such
multiple streams represent independent and
concurrently
active
sequences of record operations to the same file.
After you open a file by issuing a $OPEN or a $CREATE macro
establish a record access stream by:

call~

you

Placing the address of the File Access Block in the FAB field
of the appropriate Record Access Block. You can perform this
action at runtime by using the $STORE
macro
or
at
assembly-time by using the R$FAB initialization macro.

Issuing a $CONNECT macro.

When you have completed the desired sequence of record operations, you
terminate a record access stream by issuing a $DISCONNECT macro.
The following
macros.

sUbsections

describe

9-17

the

$CONNECT

and

$DISCONNECT

PERFORMING FILE AND RECORD OPERATIONS
9.3.1.1 $CONNECT - Establishing a Record Access Stream - The $CONNECT
macro establishes a record access stream by associating a Record
Access Block with a File Access Block.
During the macro call, RMS-ll
allocates I/O buffers for the stream. These buffers are allocated
from the file's private buffer pool (if such a pool was described by
the BPA and BPS fields of the FAB during the $OPEN or $CREATE
operation) or from the centralized space pool.
Additionally, RMS-ll
allocates,
within the centralized space pool,
internal control
structures needed to support the stream.
The formats of the $CONNECT macro are:
1.

label:$CONNECT

rab[,error[,success}1

where
to

the

Block

error

is the address of a user completion routine
called if the $CONNECT operation fails.

success

is the address of a user completion routine
called if the $CONNECT operation succeeds.

Table 9-8 lists the fields of the Record Access Block used during
$CONNECT operation.

the

referring

label

is an optional user-defined symbol
$CONNECT macro.

rab

is the address of a Record Access
associated with a File Access Block.

Table 9-8
$CONNECT RAB Fields
Description

Name
Input

Output

FAB

File access block address.

KRF

Key of reference.

MBC

Multi-block count (sequential disk files only).

MBF

Multi-buffer count.

ROP

Record processing options.

UBF

User record area address (see RBF field below).

lSI

Internal stream identifier.

RBF

Record buffer address.
Supplied only if locate mode
for a sequential file was specified in the ROP field.
RBF is set equal to UBF.

STS

Completion status code.

STV

Status value.

Needed for indexed files only.

9-18

PERFORMING FILE AND RECORD OPERATIONS
9.3.1.2 $DISCONNECT - Terminating a
Record
Access
Stream - The
$DISCONNECT macro terminates a record access stream. The association
of the specified Record Access Block to a File Access Block is ended.
System buffers and internal control structures reserved for record
processing by the stream are returned to the buffer pool.
NOTE
The $DISCONNECT macro does not have the
effect of an implicit $REWIND operation
(refer to Section 9.3.6.6) for magnetic
tape files.
If you want to ensure that
a magnetic tape file will be positioned
to
the
beginning
of
file for a
subsequent $CONNECT to the same open
file, you must issue an explicit $REWIND
operation before issuing the $DISCONNECT
for the current stream.
The formats of the $DISCONNECT macro are:
1.

label:$DISCONNECT

rab[,error[,success]]

where
label

is an optional user-defined symbol
$DISCONNECT macro.

referring

rab

is the address of a Record Access Block
whose
association with a File Access Block is to be ended.

error

is the address of a user completion routine
called if the $DISCONNECT operation fails.

success

is the address of a user completion routine
called if the $DISCONNECT operation succeeds.

Table 9-9 lists the fields of the Record Access Block used during
$DISCONNECT operation.

the

Table 9-9
$DISCONNECT RAB Fields
Name

Description

Input

lSI

Internal stream identifier.

Output

lSI

Internal stream identifier (zeroed) •

STS

Completion status code.

STV

Status value.

9-19

the

PERFORMING FILE AND RECORD OPERATIONS
9.3.2

Record Operations and File Sharing

RMS-ll allows your program to share access to a file with other
concurrently executing programs.
The manner in which a particular
file can be shared is based on its organization. Whether a particular
file is shared at runtime depends on information provided to RMS-ll by
the
file.
RMS-ll
your program and other programs accessing
coordinates record operations to a shared file through a bucket
locking mechanism. The following subsections, therefore, describe:
1.

File organizations and file sharing.

Program sharing information.

Bucket locking.

9.3.2.1 File Organizations and File Sharing - With the exception of
files on unit record devices and magnetic tape, which cannot be
shared, every RMS-ll file can be shared by any number of programs that
are reading, but not writing, the file. Relative and indexed files
(but not sequential files) can be shared by multiple readers and one
or more writers. Your program can read or write records in a relative
or indexed file while other programs are similarly reading or writing
records in the file.
Thus, the information in such files can be
changing while your program, or other programs, are accessing them.

9.3.2.2 Program Sharing Information - While a file's organization
establishes whether it can be shared by readers only or by multiple
readers and writers, your program specifies whether such sharing
actually occurs at runtime. You control the sharing of a file through
information your program provides RMS-ll in the File Access Block used
to open the file.
Two fields in the File Access Block provide RMS-ll with file sharing
information--the file sharing
(SHR) field and the file access (FAC)
field. The SHR field specifies what type of sharing you will allow.
If the SHR field contains the value FB$WRI, you have indicated that
you are willing to share the file with programs that are writing to
the file.
The absence of FB$WRI (i.e., SHR equals O) indicates that
you are willing to share the file with readers, but not writers.
The
FAC field declares the record operations that your program can itself
perform on the file it is accessing_ The presence of one or more of
the values FB$PUT, FB$DEL, FB$UPD, or FB$TRN indicates that your
program intends to write to the file.
The contents of the SHR and FAC fields in the FAB you use to open a
file are critical in the sharing of a file for the following reasons:
1.

If your program is the first to open a file, it can perform
any record operation on the file as long as the organization
of the file supports the operation and the operation is
declared in your FAC field.
However, the contents of your
SHR field establish whether any other program desiring to
write the file can also gain access.

9-20

PERFORMING FILE AND RECORD OPERATIONS
2.

If your program is not the first to access a file, RMS-ll
allows you to open the file only if the contents of your FAC
and SHR fields are compatible with the intentions of all
programs that currently have access to the file.
That is,
a.

If your FAC field indicates write operations and your SHR
field indicates no one else can write, then:
• All current accessors of the file must
have
specified FB$WRI in their SHR fields, and
• All current accessors must have indicated read only
operations in their FAC fields.

If your FAC field indicates read only operations and your
SHR field indicates no one else can write, then:
• All current accessors of the file must
have
indicated read only operations in their FAC fields.

If your FAC field indicates read only operations and your
SHR field allows writers, then:
• There cannot be any current accessor who is writing
and has disallowed writers.

If your FAC field indicates write operations and your SHR
field allows writers, then:
• There cannot be any
disallowed writers.

current

accessor

who

has

9.3.2.3 Bucket Locking - RMS-ll uses a bucket locking facility to
control operations to a relative or indexed file that is being
accessed by one or more writers. The purpose of this facility is to
ensure that a program can add, delete, or modify a record in a file
without another program, or another record access stream within the
same program, simultaneously accessing the same record.
RMS-ll employs bucket locking in either of the following instances:
1.

The SHR field in the FAB of the first program to open a
specifies shared writing (i.e., FB$WRI).

file

The SHR field in the FAB of the first program to open a file
specifies shared reading only (i.e., SHR contains 0) but the
FAC field in the same FAB declares one or more output
operations (i.e., FB$PUT, FB$UPO, or FB$OEL).

In the first instance, RMS-ll locks any bucket accessed by a
successful $GET or $FINO operation issued from within any record
access stream in any program processing the file. This lock prevents
a second record access stream, in the same program or another program,
from accessing any record in the same bucket.
In the second instance,
RMS-ll locks buckets accessed by $GET or $FINO operation issued by the
program whose FAC field indicates write operations.
These locks,
however, can be encountered only by other record access streams within
the same program.

9-21

PERFORMING FILE AND RECORD OPERATIONS
RMS-II retains the
that caused the
lock is in effect,
error status code
the bucket.

lock on a bucket until the record access stream
locking issues another ~ecord operation. While the
RMS-Il returns an ER$RLK
(target bucket locked)
to other record access streams attempting to access

For greatest flexibility at runtime, you should always assume that any
record your program attempts to access may be denied because of the
target bucket locked
(ER$RLK)
condition.
The bucket that
you
attempted to access can have been locked by another record access
stream in your own program or a record access stream in another
program. To deal with this condition, you should employ the following
procedures when you write programs:
1.

Never allow a lock to be retained on a bucket longer than is
necessary.
That is, after you issue a successful $GET or
$FIND operation, you have caused RMS-Il to lock a bucket.
You should issue a second record operation in the same record
access stream so that RMS-Il will unlock the bucket.
Any
record operation (e.g., $PUT, $UPDATE, $DELETE, or another
$GET or $FIND) will cause unlocking. Alternatively, you can
explicitly unlock the bucket by issuing the $FREE macro (see
below).

If you are using a single record access stream to access a
file and you encounter the ER$RLK error, you can reissue the
record operation that
failed
until
RMS-Il
indicates
successful completion.

If you are using multiple record access streams to access a
file, you must not merely reissue the record operation that
failed. Since one of your own record access streams may have
caused locking of the target bucket, you could place your
program in an infinite loop if you continue to issue the same
operation.
Therefore, you should issue a $FREE (see below)
for all other record access streams to the same file in your
program.
You can then safely reissue the original record
operation until RMS-Il indicates successful completion.

The $FREE macro unlocks a bucket that RMS-ll has locked on behalf of
the record access stream. If no bucket is locked, RMS-ll returns on
ER$RNL (no bucket locked) error status code.
The formats of the $FREE macro are as follows:
1.

label:$FREE

rab[,error[,success]]

where
label

is an optional user-defined symbol
$FREE macro.

rab

is the address of a Record Access Block representing a
record access stream.

error

is the address of a user completion
called if the $FREE operation fails.

routine

success

is the address of a user completion routine
called if the $FREE operation succeeds.

9-22

referring

the

PERFORMING FILE AND RECORD OPERATIONS
Table 9-10 lists the fields of the Record Access Block used during the
$FREE operation.
Table 9-10
$FREE RAB Fields
Description

Name

9.3.3

Input

lSI

Internal stream identifier

Output

STS

Completion status code

STV

Status value

Current Context of Record Operations

Transparent to your program, RMS-ll maintains
current
context
information for each record access stream you establish. This context
information identifies where, in a file, each record access stream is
positioned at any point in time. As your program performs record
operations on a record access stream, RMS-ll modifies, as necessary,
the current context of that stream.
At any point in time, the current context of a record access stream is
represented by, at most, two records:
1.

The Current Record

The Next Record

The type of record operation you issue establishes whether or not,
after the operation, there is a Current Record for the stream.
Furthermore, the type of record operation and the access mode you use
establish whether the identity of the Next Record is changed or
unchanged. Table 9-11 summarizes the effect each successful record
operation has on the current context of a stream. The sUbsections
that follow describe the purpose and importance of the notions of
Current and Next Records.
Table 9-11
Record Access Stream Context
After Record Operations

.Record Operation

Current
Record

Access Mode

Identity of
Next Record

$CONNECT

None

First Record
(for indexed files,
established by index
represented by KRF)

$CONNECT
(ROP=RB$EOF)

None

End-of-file
(sequential
disk only)

files,

(Continued on next page)
9-23

PERFORMING FILE AND RECORD OPERATIONS
Table 9-11 (Cont.)
Record Access Stream Context
After Record Operations

Record Operation

Access Mode

Current
Record

$FIND

Sequential

New

New Current Record +1

$FIND

Random or RFA

New

Unchanged

$GET
(not immediately
preceded by $FIND)

Sequential

New

New Current Record +1

$GET
( immediately
preceded by $FIND)

Sequential

Unchanged

Current Record +1

$GET

Random or RFA

New

New Current Record +1

$PUT

Sequential

None

1. Sequential file EOF.
2. Relative
file
relative
next
record position.
file
3. Indexed
undefined.

$PUT

Random

None

Unchanged

None

Unchanged

$DELETE

None

Unchanged

$TRUNCATE

None

End-of-file

$REWIND

None

First record

$FREE

None

Unchanged

None

Unchanged

$ UPDATE

Unsuccessful
record operations
(except ER$RTB)

(any)

Identity of
Next Record

NOTES
1.

Except for the $TRUNCATE
operation,
RMS-ll establishes the Current Record
(if
any)
before
establishing
the
identity of the Next Record.

The notation "+1" indicates the next
sequential record as determined by the
organization of the file.
For indexed
files, the current key of reference is
part of this determination.

9-24

PERFORMING FILE AND RECORD OPERATIONS
9.3.3.1 Understanding the Current
Record - The
Current
Record
associated with a record access stream represents the target record
for an $ UPDATE , $DELETE, or $TRUNCATE operation. RMS-Il rej.ects any
$UPDATE, $DELETE, or $TRUNCATE operation you issue for a stream that
does not have, at that point, a Current Record.
To establish (or maintain) a Current Record for
successfully issue one of the following:
1.

A $FIND operation.

A $GET operation
ER$RTB).

(including

$GET

stream,

operations

you

that

must

return

As Table 9-11 shows, either of these two operations,
if successful,
establishes or retains a Current Record as part of the stream's
context. Note that a successful, sequential $GET operation that was
immediately preceded by a successful $FIND does not change the Current
Record. Your program simply reads the record located by the preceding
$FIND but that record continues to be the stream's Current Record.
All other types of $GET operations and all $FIND operations establish
new Current Records.
In contrast to $FIND and $GET operations, all other record operations,
upon completion, leave the stream without a Current Record. Further,
any unsuccessful record operation (excluding a $GET that returns
ER$RTB)
leaves the stream without a Current Record. Therefore, any
$ UPDATE , $DELETE, or $TRUNCATE operation your program issues must be
immediately preceded by a successful $FIND or $GET operation. If you
do not follow this procedure, RMS-II rejects the $ UPDATE , $DELETE, or
$TRUNCATE operation and returns the ER$CUR (No Current Record) error
code.

9.3.3.2 Understanding the Next Record - RMS-Il utilizes the Next
Record for sequential mode processing.
A stream's Next Record
represents the target record for:
•

A sequential $GET operation
operation was not $FIND)

(if

the

immediately

preceding

•

A sequential $FIND operation

•

A sequential $PUT operation to a sequential or relative file

For the preceding operations, RMS-Il uses its internal knowledge of
file organization and structure to determine the next record to be
processed. This look ahead ability significantly decreases sequential
mode access times.
Initially, RMS-Il determines the Next Record as follows:
The $CONNECT operation leaves the Next Record as:
•

The first record in a sequential disk file (unless the record
processing options
(ROP)
field in the Record Access Block
contains the value RB$EOF).

•

End of file in a magnetic tape file that has been opened
$PUT operations.

9-25

for

PERFORMING FILE AND RECORD OPERATIONS
•

The first record in a magnetic tape file if this is the first
$CONNECT for a file opened for read only. Note that if there
has been a previous $CONNECT followed by a $DISCONNECT for
the open tape file, the $REWIND operation should be used to
position the stream to beginning of file.

•

The first record in a relative file.

•

The first record in the collating sequence of
key of reference in an indexed file.

the

specified

Thereafter, RMS-ll alters the identity of Next Record as follows:
•

•

The $GET operation in any access mode, and the $PUT and $FIND
operations in sequential mode leave the identity of the Next
Record as that of the record following the one on which the
operation was performed. This record is:
1.

The next record within sequential or relative files, or

The next record as determined by the collating sequence
of the specified key of reference in indexed files.

The $TRUNCATE operation, which is allowed only on sequential
files,
sets the Next Record to point to the end of file.
RMS-ll does not write EOF indicators in the file as a result
of a $TRUNCATE.

The following operations have no effect on the Next Record:
1.

$UPDATE.

$DELETE.

$PUT or $FIND in random access mode.

All unsuccessful record operations (except ER$RTB).

9.3.4

Synchronous and Asynchronous Record Operations

Within each record access stream, your program can perform any record
operation either synchronously or asynchronously.
When a record
operation is performed synchronously, RMS-ll returns control to your
program only after the record operation request has been satisfied
(e.g., a record has been read and passed to your program).
When a
record operation is performed asynchronously, RMS-ll can return
control to your program before the record operation request has been
satisfied.
Your program, then, can utilize the time required for the
physical transfer between the file and memory of the block or bucket
containing the record to perform other computations.
To perform asynchronous record operations, you must:
1.

Allocate, at assembly-time, an asynchronous Record Access
Block to represent the stream in which you will issue
asynchronous
requests.
You
must
allocate
multiple
asynchronous Record Access Blocks if you intend to issue
asynchronous requests in parallel.
(Refer to Section 6.1 in
Chapter 6 for the details of allocating an asynchronous RAB.)

9-26

PERFORMING FILE AND RECORD OPERATIONS
2.

Ensure that the value RB$ASY is present in the record
processing options (ROP) field of the asynchronous RAB before
you issue the desired record operation. You can initialize
the ROP field at assembly-time with this value or set the
field at runtime with the $SET macro.
Further, during
execution,
you
can
switch
between
synchronous
and
asynchronous operations in a stream by using the $SET and
$OFF macros to set and reset the value RB$ASY in the ROP
field. Note, however, that RMS-ll ignores the value RB$ASY
if the RAB is not asynchronous.

When you issue an asynchronous record operation, you can specify a
completion routine to be called if the operation succeeds. You can
also specify an error completion routine to be called if the operation
fails.
Within such completion routines, you can issue additional
operations. These additional operations, however, should also be
asynchronous operations. If you issue a synchronous operation from an
asynchronous completion routine, you may receive an ER$AST error if
the completion routine was called at AST level in the task.
While an asynchronous operation is in
stream, you must:

progress

record

access

Record

Access

Block

Never modify the contents
representing the stream.

the

Never issue a second record operation request in the same
stream until the first operation is completed.
RMS-ll
returns an ER$RSA (record stream active) error status code if
you issue a record operation to a stream which has a record
operation in progress.

To determine when an asynchronous record operation has completed, you
issue the $WAIT macro. Upon completion of the asynchronous request
for the associated RAB, RMS-ll returns control to your program at the
point following the $WAIT macro
(after calling the appropriate
completion routine, if specified).
The formats of the $WAIT macro are as follows:
1.

label:$WAIT

rab

where
label

is an optional user-defined
$WAIT macro.

symbol

referring

the

rab

is the address of an asynchronous Record Access Block
representing
a
record
access
stream
with
an
asynchronous request in progress.

Table 9-12 lists the fields of the Record Access Block used during the
$WAIT operation.
Table 9-12
$WAIT RAB Fields
Name

Description

Input

lSI

Internal stream identifier

Output

(var ies)

(dependent on operation waited upon)
9-27

PERFORMING FILE AND RECORD OPERATIONS
9.3.5

Accessing Records

To process a record in a file, you must specify an access mode in the
Record Access Block representing a stream connected to the file. Your
program can use one of two record transfer modes to access the subject
record in memory after it has been read from the file or before your
program writes it to the file. The following subsections, therefore,
describe:
•

Specifying an access mode

•

Specifying a record transfer mode

9.3.5.1 Specifying an Access Mode - You use the record access mode
(RAC) field of the Record Access Block to specify the access mode that
RMS-ll is to employ for a particular record operation.
During the
execution of your program, you can switch access modes within a stream
by changing the contents of this field.
Within the RAC field, you can specify one of three values:
1.

RB$SEQ

sequential access mode.

RB$KEY

random access mode.

RB$RFA

record's file address access mode.

You can specify sequential access mode with any file organization.
Random access mode, however, is restricted to relative and indexed
files. RFA access mode is limited to retrieval operations (i.e.,
$GET, $FIND) to files residing on disk devices.
RMS-ll examines the contents of the RAC field in a RAB only during the
execution of a $GET, $FIND, or $PUT operation. The $UPDATE, $DELETE,
and $TRUNCATE operations do not require an access mode specification.
You cannot issue these operations unless you have already accessed a
record by issuing a $GET or $FIND operation.

9.3.5.2 Specifying a Record Transfer Mode - While the RAC field
specifies how RMS-ll accesses a record in a file on behalf of your
program, the record processing options (ROP) field in the RAB allows
you to specify how your program (for $GET operations) or RMS-ll (for
$PUT or $UPDATE operations) accesses the target record in memory.
In
the ROP field, you can specify one of two record transfer modes - move
mode or locate mode. During execution of your program, you can switch
record transfer modes within a stream by changing the contents of this
field.
Within the ROP field, you indicate:
•

Move mode through the absence of the bit value RB$LOC

•

Locate mode through the presence of the bit value RB$LOC

Move mode requires that RMS-ll move individual records between I/O
buffers and the user program. For $GE~ operations, RMS-ll reads a
virtual block (sequential files) or bucket (relative or indexed files)
into an I/O buffer.
RMS-ll then locates the desired record in the
buffer and moves it to a program-specified location.
For $PUT or
$ UPDATE operations, your program first builds a record in any desired
program location. Your program then stores the address and size of
9-28

PERFORMING FILE AND RECORD OPERATIONS
the record in the RAB and issues the appropriate macro call. During
execution of the macro call, RMS-II moves the record from its
specified location to an I/O buffer.
When the buffer is filled,
RMS-ll writes it to the file.
Locate mode enables your program to access records directly in an I/O
buffer.
Therefore, there is normally no need for RMS-Il to move
records between I/O buffers and the user program.
RMS-Il does not
permit the use of locate mode if a file was opened for update
operations (e.g., FAC contains the value FB$UPD).
If a file has not
been opened for update operations, then locate mode is supported for
$GET operations for all file organizations.
For $PUT operations,
locate mode is supported for sequentially organized files only.
The record transfer mode you select for a particular record
determines the use of the following fields of the RAB:
1.

Record address (RBF) and record size (RSZ).

User record area address (UBF)
(USZ) •

and

user

record

operation

area

size

The use of these fields is described in the following subsections.

9.3.5.2.1 The RBF and RSZ Fields of the RAB - The RBF
(record
address)
and RSZ (record size) fields of the RAB always describe the
location in memory and the size of the target record for a $GET, $PUT,
or $UPDATE operation. These fields are set as follows:

For $PUT and $UPDATE operations, your program must always
ensure that RBF and RSZ describe the location and size of the
record to be written.

After a successful $GET operation, RMS-ll always sets RBF to
the address of the retrieved record and RSZ to the size of
the record.

Additionally, when your program is writing records to a sequential
file in locate mode, RMS-ll returns an address in the RBF field after
each $PUT operation. This address is the location where your program
can build the next record. It is not required that this location be
used. If it is used, your program need only set the RSZ field to
describe the size of the next record to be written. If it ~is not
used, your program must, again, set both RBF and RSZ.

9.3.5.2.2 The UBF and USZ Fields of the RAB - The USF
(user record
area address) and USZ (user record area size) fields described a fixed
work area in your program. Regardless of record transfer mode, you
must always provide this work area.
Further, it should be large
enough to contain the largest record in the file accessed by the
stream.
RMS-Il uses the work area described by UBF and USZ as
follows:
1.

For $GET operations in move mode, RMS-II moves the retrieved
record from the I/O buffer to the location described by UBF.
RBF (set equal to UBF) and RSZ describe the moved record.
If
the work area is not large enough to contain the entire
record, RMS-II moves as much of the record as possible (i.e.,
up to the amount specified in USZ), updates the current
context of the stream, and returns the ER$RTB error code.
9-29

PERFORMING FILE AND RECORD OPERATIONS

9.3.6

For $GET operations to any file in locate mode, RMS-ll will
normally set RBF to the address of the record in an I/O
buffer. However,
if RMS-ll determines that locate mode
cannot be used for a particular operation, RMS-ll will
actually use move mode. That is, the record will be moved to
the location described by UBF when move mode must be used,
RMS-ll may return ER$RTB, as described above,
if the user
record area is too small.

For $UPDATE operations and $PUT operations in move mode,
RMS-ll ignores the UBF and USZ fields.
You must describe the
record to be written in the RBF and RSZ fields.

For $PUT operations on sequential files in
RMS-ll uses the UBF and USZ fields as follows:

locate

mode,

•

If the space remaining in the I/O buffer after the
$PUT operation has been performed is equal to or
greater than USZ, RMS-ll sets RBF to the location
within the buffer where your program can build the
next record.

•

If the space rema1n1ng in the I/O buffer is less
USZ, RMS-ll sets RBF equal to UBF.

than

Record Operation Macros

Table 9-13 summarizes the record processing macros provided by RMS-ll:
Table 9-13
RMS-ll Record Processing Macros
Macro Name

Description

$FIND

Locates a record in a file and returns its RFA.

$GET

Retrieves a record from a file.

$PUT

Writes a new record into a file.

$UPDATE

Rewrites an existing record within a file.

$DELETE

Deletes a record from a relative or indexed file.

$REWIND

Positions to the beginning of a file.

$TRUNCATE

Truncates a sequential file.

$FLUSH

Writes out modified I/O buffers.

$NXTVOL

Causes processing of a magnetic tape file
continue on the next volume of a volume set.

The subsections that follow describe each of the record processing
macros listed in the preceding table. Appendix A contains a complete
list of completion status codes that can result from the issuance of
these and other RMS-ll macros.

9-30

PERFORMING FILE AND RECORD OPERATIONS
9.3.6.1 $FIND - Locating and Obtaining the RFA of a Record - The
$FIND macro locates a specified record in a file and returns its
record's file address into the RFA field of the RAB.
Additionally,
RMS-ll sets the record pointer and, for $FIND operations in sequential
access mode, the next record pointer.
The record pointer after a
$FIND specifies which record will be the subject of the next
sequential $GET operation or a $DELETE, $UPDATE, or
$TRUNCATE
operation.
The main uses of the $FIND operation are as follows:
1.

Skipping records when in sequential access mode
successive $FIND operations).

Establishing a random starting point in a file for sequential
access.

Establishing a current record
$TRUNCATE operation.

for

$DELETE,

(by

issuing

$UPDATE,

The formats of the $FIND macro are as follows:

label:$FIND

label:$FIND rab[,error[,success]]

where
label

is an optional user-defined
$FIND macro.

the

rab

is the address of a Record Access Block containing
specification of a record to be found.

the

error

is the address of a user completion
called if the $FIND operation fails.

routine

success

is the address of a user completion routine
called if the $FIND operation succeeds.

symbol

referring

Table 9-14 lists the fields of the Record Access Block used during the
$FIND operation.
Table 9-14
$FIND RAB Fields
Name
Input

Description

lSI

Internal stream identifier.

KBF

Key buffer address.
In combination with KSZ, KBF
describes a record identifier for random access to
a relative or indexed file.

KRF

Key of reference.
indexed files.

KSZ

Key size.

RAC

Record access mode.

Used

only

for

random

access

(Continued on next page)
9-31

PERFORMING FILE AND RECORD OPERATIONS
Table 9-14
(Cont.)
$FIND RAB Fields
Description

Name
Input
(Cont.)

RFA

Record's file address.

Used for RFA access only.

ROP

Record processing options.

output

BKT

Bucket code. When you access a relative file in
sequential access mode, RMS-ll sets this field
equal to the relative record number of the found
record.

RFA

Record's file address.

STS

Completion status code.

STV

Status value.

The following sUbsections describe characteristics
relative,
and
the
sequential,
operation
for
organizations.

of the
indexed

$FIND
file

9.3.6.1.1 $FIND and the
Sequential
File
Organization - Either
sequential or RFA access mode can be used with the $FIND operation to
a sequential file.
RFA access, however, is permitted only' for
sequential files on disk devices.

9.3.6.1.2 $FIND and the Relative File Organization - For the relative
file organization, you can employ any of the three supported access
modes with the $FIND operation -- sequential, random, or RFA.
When you specify sequential access mode, RMS-ll will locate the next
existing record in the file.
If no record exists in any remaining
record positions, RMS-ll will return the ER$EOF error code
(End of
File) in the STS field of the RAB.
Normally, you would not use RFA access mode with the $FIND macro since
the output of the operation would be the identical record's file
address used as input. However, a $FIND operation in RFA access mode
could return a ER$DEL (Record Deleted) error code. This error code
indicates that the record described by the user-supplied record's file
address once existed in the file but was subsequently deleted.
Finally, random access mode can also be used for $FIND operations to
relative files. Such an operation can result in an ER$RNF (Record Not
Found) error if no record exists in the record position you specified
through the KBF and KSZ fields of the RAB.

9.3.6.1.3 $FIND and the Indexed File Organization - For the indexed
file organization, you can use any of the three supported access
modes -- sequential, random, and RFA.
In random access mode, RMS-ll
uses the key of reference field (KRF) of the RAB to determine the
index to be used to locate the record.

9-32

PERFORMING FILE AND RECORD OPERATIONS
In a $FIND operation in sequential access mode, RMS-ll will locate the
next record in the sequence established by the index associated with a
particular key of reference.
RMS-ll uses the key of reference used by
the most recent successful $GET or sequential $FIND operation or the
key of reference contained in the KRF field at $CONNECT time.
If a
different index is desired for sequential processing, you should first
issue a $REWIND operation specifying the new key of reference or issue
a $GET in random access mode with the desired key of reference.
$FIND operations in random access mode require the KRF field.
You can
specify any valid key of reference. If no record exists in the file
that will satisfy the $FIND request, RMS-ll returns an ER$RNF
(Record
Not Found) error.
During $FIND operations in RFA access mode, RMS-ll ignores the KRF
field.
The ER$DEL error code may be returned if the desired record
once existed in the file but had been deleted subsequently.

9.3.6.2 $GET - Retrieving a Record - The $GET macro retrieves a
record from any of the RMS-ll file organizations. The RBF and RSZ
fields always describe the record retrieved after a successful
operation.
Further, RMS-ll sets the record pointer to the record's
file address of the retrieved record and returns this value in the RFA
field of the Record Access Block. These fields are valid only until
the next operation on the RAB is issued.
The formats of the $GET macro are as follows:
1.

label:$GET

label:$GET rab[,error[,success]]

where
label

is an optional user-defined
$GET macro.

symbol

referring

the

rab

is the address of a Record Access Block containing
specification of the record to be accessed.

the

error

is the address of a user completion
called if the $GET operation fails.

routine

success

is the address of a user completion
called if the $GET operation succeeds.

routine

Table 9-15 lists the fields of the Record Access Block used during the
$GET operation.
Table 9-15
$GET RAB Fields
Description

Name
Input

lSI

Internal stream identifier.

KBF

KSZ,
KBF
Key buffer.
with
In combination
describes a record identifier for random access to
a relative or indexed file.
(Continued on next page)
9-33

PERFORMING FILE AND RECORD OPERATIONS
Table 9-15
(Cont.)
$GET RAB Fields
Description

Name
Input
(Cont. )

Output

KRF

Key of reference.
indexed files.

Used only for'random access

KSZ

Key size.

RAC

Record access mode.

RFA

Record's file address.

RHB

Record header buffer.
Used for
VFC
format
records.
If this field equals 0, RMS-ll skips the
fixed control area portion of the record.

ROP

Record processing options.

UBF

User record area address.

USZ

User record area size.

BKT

Bucket code. When you access a relative file in
sequential access mode, .RMS-ll sets this field
equal to the relative record number of the record
retrieved.

RBF

Record address. This field contains
of the retrieved record.

RFA

Record's file address.

RSZ

Record size. This field contains the size of
record whose address is in RBF.

STS

Completion status code.

STV

Status value.

Used for RFA access only.

the

address

See note below.
NOTE

After a successful $GET operation from a
unit record or terminal device, the low
order byte of the STV field is used to
report the terminating character for the
input record.
This byte is set as
follows:
Octal
Contents

Terminating
Character

15
33
32

CR
ESC
CTRL/Z
other

Except when the low order byte of STV is
0, the terminating character is never in
the record described by the RBF and RSZ
fields of the RAB.
9-34

the

PERFORMING FILE AND RECORD OPERATIONS
The following sUbsections describe the characteristics of the
operation
for
the
sequential,
relative,
and
indexed
organizations.

$GET
file

9.3.6.2.1 $GET and
the
Sequential
File
Organization - Either
sequential or RFA access mode can be used with the $GET operation to a
sequential file.
RFA access, however, is permitted
only
for
sequential files on disk devices.

9.3.6.2.2 $GET and the Relative File Organization - For the relative
file organization, you can employ any of the three supported access
modes -- sequential, random, or RFA.
When you specify sequential access mode, RMS-ll returns the next
existing record in the file (or the Current Record if the immediately
preceding operation was a successful $FIND). If no record exists in
any remaining record positions, RMS-ll returns the ER$EOF error code
(End of File) in the STS field of the RAB.
When you use random access mode, RMS-ll returns an ER$RNF (Record Not
Found) error if no record exists in the record position you specified
through the KBF and KSZ fields of the RAB.
RMS-ll may return an ER$DEL (Record Deleted) error code for $GET
operations in RFA access mode. This error code indicates that the
desired record once existed in the file but was subsequently deleted.

9.3.6.2.3 $GET and the Indexed File Organization - For the indexed
file organization, you can employ any of the three supported access
modes -- sequential, random, and RFA.
In a $GET operation (not preceded by a $FIND)
in sequential access
mode, RMS-ll retrieves the next record in the sequence established by
the index associated with a particular key of reference. RMS-ll uses
the key of reference of the most recent successful $GET or $FIND
operation or the key of reference contained in the KRF field at
$CONNECT time.
If a different index is desired for sequential
processing, you should first issue a $REWIND operation specifying the
new key of reference or issue a $GET or $FIND in random access mode
with the desired key of reference.
$GET operations in random access mode require the KRF field.
You can
specify any desired key of reference. If no record exists in the file
that will satisfy the $GET request, RMS-ll returns an ER$RNF
(Record
Not Found) error.
During $GET operations in RFA access mode, RMS-ll ignores the KRF
field.
The ER$DEL error code may be returned if the desired record
has been deleted.

9.3.6.3 $PUT - Writing a New Record to a File - The $PUT macro writes
a new record into any RMS-ll file organization. The RBF and RSZ
fields must describe the record to be written. RFA access mode cannot
be used.
Note that $PUT operations in random access mode do not
change the next record pointer.

9-35

PERFORMING FILE AND RECORD OPERATIONS
The following are the formats of the $PUT macro:
1.

label:$PUT

rab[,error[,success]]

where
label

is an optional user-defined
$PUT macro.

symbol

referring

the

rab

is the address of a Record Access Block containing
specification of the record to be written.

the

error

is the address of a user completion
called if the $PUT operation fails.

routine

success

is the address of a user completion
called if the $PUT operation succeeds.

routine

Table 9-16 lists the fields of the Record Access Block used during the
$PUT operation.
Table 9-16
$PUT RAB Fields
Description

Name
Input

Output

lSI

Internal stream identifier.

KBF

Key buffer.
Used
relative files.

only

KSZ

Key size. Used
files only.

random

RAC

Record access mode.

RBF

Record address.

RHB

Record header buffer. Used for VFC records only.
If this field equals 0, RMS-ll zeroes the fixed
control area portion of the record written.

ROP

Record processing options.

RSZ

Record size.

UBF

User record
sequential
9.3.5.2.2).

USZ

User record area size.
sequential files only.

BKT

Bucket code. When you access a relative file in
sequential access mode, RMS-llil sets this field
equal to the relative record number of the record
written.

for

area.
files

Used
only

for

random
access

access
to

relative

for locate mode for
(refer
to
Section

Used for locate

mdde

for

(Continued on next page)
9-36

PERFORMING FILE AND RECORD OPERATIONS
Table 9-16
(Cont.)
$PUT RAB Fields

Output
(Cont.)

Name

Description

RBF

Record address. This field lndicates where the
record may be built.
(locate mode on
next
sequential files only)

RFA

Record's file address.

STS

Completion status code.

STV

Status value.

The following subsections describe the characteristics of the
operation
for
the
sequential,
relative,
and
indexed
organizations.

$PUT
file

9.3.6.3.1 $PUT and the Sequential File Organization - You must ensure
that the value RB$SEQ is present in the record access field (RAC) of
the RAB at the time a $PUT macro call is issued for a sequential file.
Further, RMS-ll does not permit new records to be added to a file at
any place but the end of file.
Therefore, if you intend to add
records to a sequential file that already contains records, either the
value RB$EOF (position to end-of-file) must be present in the record
options field
(ROP) of the RAB at the time you issue the $CONNECT
macro call for the stream or you must position to end-of-file through
$FINDs and/or $GETs prior to issuing any $PUT requests.
You cannot write any record whose length is greater than
record size specified when the file was created.

the

maximum

9.3.6.3.2 $PUT and the Relative File Organization - You can use
either sequential or random access mode during $PUT operations to a
relative file. For both access modes, three restrictions apply.
First, no record can be written to the file whose length is greater
than the maximum record size specified when the file was created.
Second, the target record position cannot already contain a record.
Third, the target record position cannot represent a relative offset
from the beginning of the file whose value is greater than the maximum
record number, if such a number was specified at the time the file was
created.

9.3.6.3.3 $PUT and the Indexed File Organization - You can use either
sequential or random access mode during $PUT operations to an indexed
file.
For both access modes, two restrictions apply to the length of
the record to be written.
First, the length of the record cannot
exceed the maximum record size specified when the file was created.
Second, every record written must be large enough to contain a
complete primary key field.
It is not required, however, that records
be large enough to contain all defined alternate key fields.
If such
alternate key fields are partially or completely missing because of
record length, RMS-ll makes no entries for the new record in the
associated alternate indexes.
9-37

PERFORMING FILE AND RECORD OPERATIONS
$PUT operations to an indexed file do not require a key value or a key
of reference.
RMS-ll determines where to write the record by
examining the contents of the primary key field in the record. Before
writing the record, RMS-ll compares the key values (pri~ary and
alternate) in the record with the key values of records already
existing in the file. This comparison determines if the writing of
the record would result in the presence of duplicate key values among
records of the file.
If duplicates would occur, RMS-ll verifies the
defined characteristics for the key field(s)
being duplicated.
If
duplicates are not allowed for a particular key field, RMS-ll rejects
the operation with an ER$DUP error code. However, if duplicates are
allowed, RMS-ll performs the $PUT operation and returns a success code
of SU$DUP. Subsequent sequential $GET operations on a given index
will always retrieve records with identical key values in the order in
which the records were written •.
When you issue a series of $PUT operations in sequential access mode,
RMS-ll checks that the primary key in each record is equal to (if
duplicate primary key values are allowed) or greater than the primary
key of the previous record written. An ER$SEQ (key out of sequence)
error status code is returned if the primary key of the current record
fails this check.
This checking is suppressed, however, if the
immediately preceding operation was not a successful
$PUT
in
sequential access mode.

9.3.6.4 $UPDATE - Rewriting an Existing Record - The $UPDATE macro
rewrites an existing record within a file.
The Current Record
associated with the stream will be rewritten.
Therefore,
the
operation immediately preceding a $UPDATE must be a successful $GET or
$FIND. Otherwise, RMS-ll returns an ER$CUR (No Current Record) error
code.
The address and size of the replacement record must be in the
RBF and RSZ fields respectively. Errors indicating an illegal input
value in the RAB (e.g., ER$RSZ - illegal record size) do not effect
the original record in the file.
Other types of errors
(e.g.,
ER$WER - file write error), however, can mean that the original record
is lost.
The following are the formats of the $UPDATE macro:
1.

label:$UPDATE

rab[,error[,success]]

where
label

is an optional user-defined
$UPDATE macro.

the

rab

is the address of a Record Access Block.

error

is the address of a user completion
called if the $UPDATE operation fails.

routine

success

is the address of a user completion routine
called if the $UPDATE operation succeeds.

9-38

symbol

referring

PERFORMING FILE AND RECORD OPERATIONS
Table 9-17 lists the fields of the Record Access Block used during the
$UPDATE operation.
Table 9-17
$UPDATE RAB Fields
Name
Input

Output

Description

lSI

Internal stream identifier.

RBF

Record address.

RHB

Record header buffer. Used for VFC format records
only.
If no address is specified in this field,
RMS-ll leaves the fixed control area portion of
the original record unaltered.

ROP

Record processing options. Note that locate
is not supported for $UPDATE operations.

RSZ

Record size.

RFA

Record's file address.

STS

Completion status code.

STV

Status value.

The following sUbsections describe
operation
for
the
sequential,
organizations.

mode

characteristics of the $UPDATE
indexed
file
relative,
and

9.3.6.4.1 $UPDATE and the Sequential File Organization - RMS-ll does
not permit the $UPDATE operation for sequential files residing on
magnetic tape or unit record devices. Furthermore, for disk files,
the format of the records in the file cannot be stream and you cannot
change the length of the record being rewritten.

9.3.6.4.2 $UPDATE and the Relative File Organization - If the format
of records is variable,
the length of the replacement record can
differ from the length of the original record.
In all instances,
however,
you
cannot issue a $ UPDATE macro call specifying a
replacement record whose length is greater than the maximum record
size defined when the file was created.

9.3.6.4.3 $UPDATE and the Indexed File Organization - On an $ UPDATE
operation to an indexed file that allows duplicate primary keys, you
cannot change the length of the original record (RMS-II returns ER$RSZ
is you attempt such a change). For indexed files that do not allow
duplicate primary keys, however, the length of the replacement record
to be written by the $UPDATE macro call can differ from the length of
the original record. Two restrictions, however, apply to the length
of the replacement record.
First, the length of the replacement
record cannot exceed the maximum record size defined when the file was
9-39

PERFORMING FILE AND RECORD OPERATIONS
created.
Second, e!ery replacement record must be large enough to
contain a complete prlmary key field.
It is not required, however,
that the replacement record be large enough to contain all defined
alternate key fields.
If an alternate key field is partially or
completely missing in the replacement record but was present in the
original record, the key field must have the characteristic that key
values can change.
This is also true if the replacement record
contains a key field missing in the original record.
Before writing the record, RMS-II compares the key values of the
original record with the key values of the replacement record. This
comparison takes into account the defined characteristics of each key.
For example, if a particular key is not allowed to change, RMS-Il will
reject the $UPDATE operation with a ER$CHG error code if the
replacement record contains an altered value in the associated key
field. Similarly, if duplicates are not allowed for a particular key,
RMS-II rejects the operation with a ER$DUP error code if writing the
replacement record would cause duplicate values for the particular
key.
Conversely,
if duplicates are allowed and writing the record
results in the presence in the file of duplicate values for a
particular key, RMS-II performs the write operation and returns a
success code of SU$DUP.

9.3.6.5 $DELETE - Deleting a Record - The $DELETE macro deletes an
existing record from a relative or indexed file.
This macro is an
illegal operation for records in a sequential file.
The $DELETE operation always applies to
the
Current
Record.
Therefore, the operation immediately preceding a $DELETE must be a
successful $GET or $FIND. Otherwise, RMS-II returns an ER$CUR (No
Current Record) error code.
The formats of the $DELETE macro are as follows:
1.

label:$DELETE

rab[,error[,success]]

where
label

is an optional user-defined
$DELETE macro.

rab

is the address of a Record Access Block.

error

is the address of a user c9mpletion
called if the $DELETE operation fails.

success

symbol

referring

the

routine

is the address of a user completion routine
called if the $DELETE operation succeeds.

Table 9-18 lists the fields of the Record Access Block used during the
$DELETE operation.

9-40

PERFORMING FILE AND RECORD OPERATIONS
Table 9-18
$DELETE RAB Fields
i

Name

Description

lSI

Internal stream identifier.

ROP

Record processing options.

STS

Completion status code.

STV

Status value.

Input

Output

9.3.6.6 $REWIND - Positioning to the Beginning of a
File - The
$REWIND macro sets the current context of a stream to the beginning of
a file.
Following the operation, there is no Current Record.
The
Next Record is the first record in the file (for indexed files, the
KRF field establishes the index to be used).
The following are the formats of the $REWIND macro:
1.

label:$REWIND

rab[,error[,success]]

where
label

is an optional user-defined
$REWIND macro.

symbol

referring

the

rab

is the address of a Record Access Block associated with
a file.

error

is the address of a user completion
called if the $REWIND operation fails.

routine

success

is the address of a user completion routine
called if the $REWIND operation succeeds.

Table 9-19 lists the fields of the Record Access Block used during the
$REWIND operation.
Table 9-19
$REWIND RAB Fields
Description

Name
Input

Output

lSI

Internal stream identifier.

KRF

Key of reference.

STS

Completion status code.

STV

Status value.

9-41

Used for indexed files only.

PERFORMING FILE AND RECORD OPERATIONS
9.3.6.7 $TRUNCATE - Truncating
macro truncates a sequential
relative and indexed files.

a Sequential File - The
$TRUNCATE
file.
This operation is illegal for

$TRUNCATE deletes the Current Record and all records following that
record. The immediately preceding operation must be a successful $GET
or $FIND. Otherwise, RMS-II returns an ER$CUR (No Current Record)
error code.
RMS-Il declares an end-of-file at the position formerly occupied by
the Current Record. Additionally, the $TRUNCATE operation causes the
Next Record to point to this end-of-file. Therefore, you can extend
the file by issuing $PUT operations in sequential mode following the
$TRUNCATE operation.
The following are the formats of the $TRUNCATE macro:
1.

label:$TRUNCATE

rab[,error[,success]]

where
label

is an optional user-defined
$TRUNCATE macro.

symbol

referring

the

rab

is the address of a Record Access Block associated with
a sequential file.

error

is the address of a user completion routine
called if the $TRUNCATE operation fails.

success

is the address of a user completion routine
called if the $TRUNCATE operation succeeds.

Table 9-20 lists the fields of the Record Access Block used during the
$TRUNCATE o-pe~ation.
Table 9-20
$TRUNCATE RAB Fields
Name

Description

Input

lSI

Internal stream identifier.

Output

STS

Completion status code.

STV

Status value.

9.3.6.8 $FLUSH - Writing Out Modified I/O Buffers - The $FLUSH macro
writes out all modified I/O buffers associated with a record access
stream, thus ensuring' that all record activity up to a point in time
is actually reflect~d in the file.
If the file is relative or
indexed, any bucket c~rrently locked by the stream remains locked.

9-42

PERFORMING FILE AND RECORD OPERATIONS
The formats of the $FLUSH macro are as follows:
1.

label:$FLUSH

rab[,error[,success]]

where
label

is an optional user-defined
$FLUSH macro.

symbol

referring

the

rab

is the address of a Record Access Block representing
stream to be flushed.

error

is the address of a user completion
called if the $FLUSH operation fails.

routine

success

is the address of a user completion routine
called if the $FLUSH operation succeeds.

Table 9-21 lists the fields of the Record Access Block used during the
$FLUSH operation.
Table 9-21
$FLUSH RAB Fields
Name

Description

Input

lSI

Internal stream identifier.

Output

STS

Completion status code.

STV

Status value.

9.3.6.9 $NXTVOL - Continue Processing on Next Volume - The $NXTVOL
macro can be used only when the stream is accessing a file on magnetic
tape. You issue this macro when you want to continue processing the
file on the next volume of a volume set before the end of the current
volume is reached. RMS-ll will then open the first file section on
the next volume. File sections occur when a file is written on more
than one volume. The portion of the file on each of the volumes
constitutes a file section. For input files, the following processing
occurs when you issue a $NXTVOL macro:
1.

All records in I/O buffers for the current file
skipped.

If the current volume is the last volume in the set, i.e.,
there is no next volume, RMS-ll reports end-of-file to your
program.

If another file section exists, the current volume is rewound
and the next volume is mounted. A request to the operator is
printed if necessary.

The header label (HDRl) of the first file section is read and
checked.

9-43

section

are

PERFORMING FILE AND RECORD OPERATIONS
5.

If all required fields check, the operation continues.

If any check fails, the operator is requested
correct volume.

mount

the

For output files, the following processing occurs.
1.

I/O buffers that are currently in memory are written on the
current file section (i.e., an implicit $FLUSH is performed).

The current file section is closed with EOVI and EOV2
and the volume is rewound.

The next volume is mounted.

A file with the same name and the next higher section number
is opened for write. The file set identifier is identical
with the volume identifier of the first volume in the volume
set.

labels

The formats of the $NXTVOL macro are as follows:
1.

label:$NXTVOL

rab[,error[,success]]

where
label

is an optional user-defined
$NXTVOL macro.

symbol

referring

the

rab

is the address of a Record Access Block associated with
a file on a magnetic tape volume set.

error

is the address of a user completion
called if the $NXTVOL operation fails.

routine

success

is the address of a user completion routine
called if the $NXTVOL operation succeeds.

Table 9-22 lists the fields of the Record Access Block used during the
$NXTVOL operation.
Table 9-22
$NXTVOL RAB Fields

Input

Output

Name

Description

lSI

Internal stream identifier.

ROP

Record processing options.

STS

Completion status code.

STY

Status value.

9-44

APPENDIX A
COMPLETION STATUS CODES

This appendix describes completion status codes that can
by RMS-II to your program.

returned

All RMS-II file and record operations return a completion status code
into the status field (STS) of the control block (i.e., FAB or RAB)
associated with the operation. A symbolic name is defined for each
such code. The symbolic names for successful completion status codes
take the following form:
SU$xxx
where
xxx

is a mnemonic
operation.

value

describing

the

successful

Symbolic names for error completion status codes take the form:
ER$xxx
where
xxx

is a mnemonic value representing
operation failed.

the

reason

the

For certain error conditions, RMS-II uses the status value (STV) field
to communicate additional information to your program. The tables in
this appendix list all instances in which a particular symbolic value
in the STS field indicates the presence of further information in the
STV field.
NOTE
When the tables
in
this
appendix
indicate that the STV field contains an
ACP error code, you should refer to the
description of such codes in Appendix I
of
the
IAS/RSX-II
I/O
Operations
Reference Manual.
A limited number of severe error conditions cause RMS-II to invoke a
fatal error crash routine.
Section A.3 of this appendix describes
these conditions and the crash routine itself.
The sections that follow describe, respectively, successful completion
status codes, error completion status codes, and the RMS-II fatal
error crash routine.
A-l

COMPLETION STATUS CODES
A.I

SUCCESSFUL COMPLETION STATUS CODES

Table A-I describes successful completion
RMS-II routines.

status

codes

returned

Table A-I
Successful Completion Status Codes
Symbolic
Name

Decimal
Value

SU$SUC

Operation successful.

SU$DUP

A record written into an indexed file as a
result of a $PUT or $UPDATE operation contains
at least one key value that was already present
in another record.

SU$IDX

During a $PUT or $UPDATE operation on an
indexed
file,
the record was successfully
written.
The record can
be
subsequently
retrieved but RMS-II was not able to optimize
the structure of the index at the time the
record was inserted. Several indirections will
occur, therefore, on retrieval.
In
some
instances, RMS-II may also return an error code
(e.g., ER$RLK) in the STV field of the control
block.

SU$RRV

During a $PUT or $UPDATE operation on an
indexed
file,
the record was successfully
written.
However, RMS-II was unable to update
one or more Record Retrieval Vectors (RRVs) and
the records associated with the RRVs cannot be
retrieved
using
alternate indexes or RFA
addressing mode.

A.2

Description

ERROR COMPLETION STATUS CODES

Table A-2 describes error completion status codes returned
routines.

RMS-II

Table A-2
Error Completion Status Codes
Symbolic
Value

Octal
Value

Decimal
Value

STV

Description

ER$ABO

177760

-16

ER$STK
or
ER$MAP

out of
Operation aborted:
stack save area or in core
data structures corrupted.

ER$ACC

177740

-32

ACP error
code

Files-II ACP could not access
the file.
(Continued on next page)

A-2

COMPLETION STATUS CODES
Table A-2 (Cont.)
Error Completion Status Codes
Symbolic
Value

Octal
Value

Decimal
Value

ER$ACT

177720

-48

ER$AID

177700

-64

XAB address

Bad
area
identification
number
(AID)
field
in
allocation XAB (i.e., out of
sequence).

ER$ALN

177660

-80

XAB address

Illegal value in alignment
boundary type (ALN) field of
allocation XAB.

ER$ALQ

177640

-96

(XAB address)

Value in allocation quantity
(ALQ)
field
in
FAB
(or
allocation
XAB)
exceeds
maximum
or,
during
an
explicit $EXTEND operation,
equals zero.

ER$ANI

177620

-112

ER$AOP

177600

-128

ER$AST

177560

-144

ER$ATR

177540

-160

ACP error
code

Read error
attributes.

file

header

ER$ATW

177520

-176

ACP error
code

Write error
attributes.

on file

header

ER$BKS

177500

-192

ER$BKZ

177460

-208

ER$BLN

177440

-224

STV

Description

File
activity
precludes
action
(e.g., attempting to
close a file with outstanding
asynchronous
record
operation) •

Records in a file on ANSI
labeled
magnetic tape are
variable length but not in
ANSI D format.
XAB address

Illegal value in
options
(AOP)
allocation XAB.

allocation
field
in

Invalid operation
at
AST
level: attempting to issue a
synchronous operation from an
asynchronous record operation
completion routine.

Bucket size
(BKS)
field in
FAB contains value exceeding
maximum.
XAB address

Bucket size
(BKZ)
field in
allocation XAB contains value
exceeding maximum.
Block length (BLN) field in a
FAB or RAB is incorrect.
(Continued on next page)

A-3

COMPLETION STATUS CODES
Table A-2
(Cont.)
Error Completion Status Codes
Description

STV

Symbolic
Value

Octal
Value

Decimal
Value

ER$BOF

177430

-232

Beginning of file detected on
$SPACE operation to magnetic
tape file.

ER$BPA

177420

-240

Private buffer pool address
not a double word boundary.

ER$BPS

177400

-256

Private buffer pool size
a multiple of 4.

ER$BUG

177360

-272

Internal error detected in
RMS-ll
(refer to Section A.3
of
this
Appendix);
no
recovery possible; contact a
Software Specialist.

ER$CCR

177340

-288

Can't connect RAB (i.e., only
one
record
access stream
permitted
for
sequential
files).

ER$CHG

177320

-304

$UPDATE attempting to change
a key field that does not
have the change attribute.

ER$CHK

177300

-320

Index file bucket check-byte
mismatch.
The bucket has
been corrupted. No recovery
possible for the bucket.

ER$CLS

177260

-336

RSTS/E
error code

Close function failed (RSTS/E
operating system only).

ER$COD

177240

-352

XAB address

Invalid COD field in XAB or
XAB type is illegal for the
organization or operation.

ER$CRE

177220

-368

ACP error
code

Files-II ACP could not create
file.

ER$CUR

177200

-384

ER$DAC

177160

-400

ACP error
code

Files-II ACP
during $CLOSE

ER$DAN

177140

-416

XAB address

Invalid area number in DAN
field of key definition XAB.

ER$DEL

177120

-432

not

No current record: operation
not immediately preceded by a
successful $GET or $FIND.
deaccess error

Record accessed by RFA access
mode has been deleted.
(Continued on next page)

A-4

COMPLETION STATUS CODES
Table A-2
(Cont.)
Error Completion Status Codes
Symbolic
Value

Octal
Value

Decimal
Value

ER$DEV

177100

-448

1. Syntax
error in device
name.
2. No such device.
3. Inappropriate device for
operation
(e.g.,
attempting to create an
indexed file on magnetic
tape) •

ER$DIR

177060

-464

Syntax error
name.

ER$DME

177040

-480

Dynamic
memory
exhausted:
insufficient
space
in
central space pool
or
private buffer pool.

ER$DNF

177020

-496

Directory not found.

ER$DNR

177000

-512

Device not ready.

ER$DPE

176770

-520

ER$DUP

176740

-544

ER$ENT

176720

-560

ER$ENV

176700

-576

Environment error: operation
or file organization not
specified in ORG$ macro.

ER$EOF

176660

-592

End of file.

ER$ESS

176640

-608

Expanded string area
block too short.

ER$EXP

176630

-616

File

ER$EXT

176620

-624

ER$FAB

176600

-640

STV

Description

ACP error
code

Device