Digital PDFs

AA-H683A-TC

March 1979

370 pages

Original

11MB

Document:	RMS-11 MACRO-11 Reference Manual Version 1.8
Order Number:	AA-H683A-TC
Revision:	0
Pages:	370
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/5B_FileMgmt_IO/AA-H683A-TC_RMS-11_V1.8_MACRO-11_Ref_197903.pdf

OCR Text

March 1979

This manual describes the use of RMS-11 facllitles In MACR0-11 programs.

RMS-11 MACR0-11
Reference Manual
Order No. AA-H683A-TC

SOFTWARE VERSION:

RMS-11
V1 .8
RMS-11 K V1 .8

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

digitcJI equipment corporation · maynard, massachusetts

First Printing, March 1979

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

@ 1979 by Digital Equipment Corporation

The postage-paid 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:

DEC
DECnet
DECsystem-10
DECSYSTEM-20
DECtape
DEC US
DIBOL
DIGITAL

FOCAL
!AS
MAS SB US
PDP
RSX
RSTS
UNIBUS
VAX
VMS

TABLE OF CONTENTS
SECTION

TITLE

PAGE

PREFACE

DOCUMENTATION CONVENTIONS

xvii

USING RMS-11 IN A MACR0-11 PROGRAM
DECLARING
RMS-11 FACILITIES
l. l
Listing Names of Required Macro Definitions
1.1.1
Declaring the Processing Environment
1.1. 2
Declaring Buffer Pool Requirements
1.1. 3
USER CONTROL BLOCKS
1. 2
File Access Block (FAB)
1. 2.1
Allocation
1.2.1.1
Initialization
1.2.1.2
Record Access Block (RAB)
1. 2. 2
Allocation
1.2.2.1
1.2.2.2
Initialization
Extended Attribute Block (XAB)
1. 2. 3
Allocation
1.2.3.1
Initialization
1.2.3.2
Linking and Ordering XABs
1.2.3.3
1.2.3.3.1 Ordering by Type of XAB
1.2.3.3.2 Ordering Within XAB Type
1. 2. 4Name Block
1. 2. 4. l
Allocation
1.2.4.2
Initialization
CONTROL BLOCK FIELD ACCESS AT RUN TIME
l. 3
FILE .AND RECORD OPERATIONS
l. 4
Completion Routines
1. 4. 1
Calling Sequence
1. 4. 2
Your Program Supplies the Argument List
1.4.2.1
RMS-11 Generates the Argument List
1.4.2.2
File Operation Macros
1. 4. 3
Record Operation Macros
1. 4. 4
CREATING THE TASK
l. 5

CHAPTER 1

CHAPTER 2
.2. 1

2 .1. 1
2 .1. 2
2. 1. 3
2 .1. 4
2 .1. 5
2 .1. 6
:2. 2

2.2.1
2.2.1.1
2.2.1.2
2.2.2
2.2.2.1
2.2.2.2
2.2.2.3
2.2.3

PROVIDING BUFFER SPACE
CENTRAL BUFFER POOL
P$BDB
P$FAB
P$RAB
P$RABX
P$IDX
P$BUF
GET SPACE ROUTINE
Specifying a Routine
Specifying a Get Space Address at
Assembly Time
Specifying a Get Space Address at Run Time
Interfaces to Routines
RMS-11 Request For Space
RMS-11 Release Of Space
RMS-11 Pool Block Header Formats
Comments

1-2
1-3
1-5
1-6
1-8
1-8
1-8
1-9
1-10
1-11
1-11
1-13
1-13
1-14
1-14
1-14
1-16
1-16
1-17
1-17
1-18
1-19
1-19
1-20
1-20
1-22
1-22
1-23
1-23

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

iii

CHAPTER 3
3.1
3 .1.1
3 .1. 2
3 .1. 3
3 .1. 4
3.2
3.2.1
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.4
3.4.1
3.5
3.5.1
3.5.2
3.5.3
3.6
3.6.1
3.6.2
3.6.3
3.6.4
3.7
3.7.1
3.7.2
3.7.3
3.7.4
3.8
3.8.1
3.8.2
3.8.3
3.9
3.9.1
3.9.2
3.9.3
3.9.4
3.10
3.10.1
3.10.2
3.11
3.11.1
3.11.2
3.11.3
3.11.4
3.11.5
3.12
3.12.1
3.12.2
3.12.3
3.13
3.13.1
3.13.2
3.13.3
3.13.4
3.14

FILE ACCESS BLOCK
ALQ
Use
Input Values
Initialization and
Comments
BID
Use
BKS
Use
Input Values
Initialization and
Comments
BLN
Use
BLS
Use
Input Values
Initialization and
BPA
Use
Input Values
Initialization and
Comments
BPS
Use
Input Values
Initialization and
Examples
CTX
Use
Input Values
Initialization and
DEQ
Use
Input Values
Initialization and
Comments
DEV
Use
Output Values
DNA
Use
Input Values
Initialization and
Examples
Comments
DNS
Use
Input Values
Initialization and
FAC
Use
Input Values
Initialization and
Comments
FNA

Default

3-3
3-3
3-3
3-4
3-4
3-5
3-5
3-6
3-6
3-6
3-7
3-7
3-8
3-8
3-9
3-9
3-9
3-10
3-11
3-11
3-11
3-12
3-12
3-13
3-13
3-13
3-14
3-15
3-16
3-16
3-16
3-16
3-1 7
3-17
3-17
3-18
3-18
3-19
3-19
3-19
3-20
3-20
3-20
3-21
3-21
3-21
3-22
3-22
3-22
3-22
3-23
3-23
3-23
3-24
3-24
3-25

··~

....,

"-"

.,...,

'-'

3.14 .• 1
3.14 .• 2
3.14.3
3.14.4
3.15
3.15.1
3.15.2
3.15.3
3.16
3.16.1
3.16.2
3.16.3
3.16.4
3.17
3.17.1
3.17.2
3.17.3
3.17.4
3.18
3.18.1
3.19
3.19.1
3.19.2
3.19.3
3.19.4
3. 20
3.20.1
3.20.2
3.20.3
3.21
3. 21. 1
3. 21. 2
3. 21. 3
3. 21. 4
3.22
3.22.l
3.22.2
3.22.3
3.23
3.23.l
3.23.2
3.23.3
3.24
3.24.1
3.24.2
3.24.3
3.24.4
3.25
3.25.l
3.25.2
3.25.3
3.26
3.26.1
3.26.2
3.26.3
3. 27
3.27.1

Use
Input Values
Initialization and
Comments
FNS
Use
Input Values
Initialization and
FOP
Use
Input Values
Initialization and
Comments
FSZ
Use
Input Values
Initialization and
Comments
IF!
Use
LCH
Use
Input Values
Initialization and
Comments
MRN
Use
Input Values
Initialization and
MRS
Use
Input Values
Initialization and
Comments
NAM
Use
Input Values
Initialization and

Default

OHG

Use
Input Values
Initialization and Default
RAT
Use
Input Values
Initialization and Default
Comments
RFM
Use
Input Values
Initialization and Default
RTV
Use
Input Values
Initialization and Default
RTV
Use

3-25
3-25
3-26
3-26
3-27
3-27
3-27
3-27
3-28
3-28
3-28
3-30
3-30
3-31
3-31
3-31
3-31
3-32
3-33
3-33
3-34
3-34
3-34
3-34
3-35
3-36
3-36
3-36
3-37
3-38
3-38
3-38
3-39
3-39
3-40
3-40
3-41
3-41
3-42
3-42
3-42
3-42
3-43
3-43
3-43
3-44
3-44
3-45
3-45
3-45
3-46
3-47
3-47
3-47
3-48
3-49
3-49

3-49

3.27.2
3.27.3
3.28
3 •. 28. 1
3.28.2
3.28.3
3.29
3 .. 29.1
3.29.2
3.30
3.30.1
3.30.2
3.31
3. 31. 1
3. 31. 2
3. 31. 3
3. 31. 4

Input Values
Initialization and Default
SHR
Use
Input Values
Initialization and Default
STS
Use
Input Values
STV
Use
Input Values
XAB
Use
Input Values
Initialization and Default
Comments

3-50
3-51
3-51
3-51
3-52
3-53
3-53
3-53
3-54
3-54
3-54
3-55
3-55
3-55
3-55
3-56

CHAPTER 4
4.1
4 .1. 1
4.2
4.2.1
4.2.2
4.2.3
4.3
4.3.1
4.4
4.4.1
4.4.2
4.4.3
4.5
4.5.1
4.5.2
4.5.3
5.5.4
4.6
4.6.1
4.7
4.7.1
4.7.2
4.7.3
4.8
4.8.1
4.8.2
4.8.3
4.9
4.9.1
4.9.2
4.9.3
4.9.4
4.10
4.10.1
4.10.2
4.10.3
4.10.4
4.11

RECORD ACCESS BLOCK
BID
Use
BKT
Use
Input Values
Initialization and Default
BLN
Use
CTX
Use
Input Values
Initialization and Default
FAB
Use
Input Values
Initialization and Default
Comments
ISI
Use
KBF
Use
Input Values
Initialization and Default
KRF
Use
Input Values
Initialization and Default
KSZ
Use
Input Values
Initialization and Default
Comments
MBC
Use
Input Values
Initialization and Default
Comments
MBF

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

i!'~

""·

-~.

·~

'w''

._..,,..

4. 11. 1
4. 11. 2
4. 11. 3
4. 11. 4
4.12
4.12.1
4.12.2
4.12.3
4.13
4.13.1
4.13.2
4.13.3
4.13.4
4.14
4.14.l
4.14.2
4.14.3
4.15
4.15.1
4.15.2
4.15.3
4.15.4
4.16
4.16.1
4.16.2
4.16.3
4.16.4
4.17
4.17.1
4.17.2
4.17.3
4.18
4.18.l
4.18.2
4.19
4.19.l
4.19.2
4.20
4.20.1
4.20.2
4.20.3
4.21
4. 21. 1
4. 21. 2
4. 21. 3
CHAPT'ER 5
5.1
5 .1.1
5 .. Ll.l
5.Ll.2
5 .. Ll.3
5 .1.. 2
5.1.2.1
5ol.2.2
5ol.2.3
5ol.2.4

Use
Input Values
Initialization and
Comments
RAC
Use
Input Values
Initialization and
RBF
Use
Input Values
Initialization and
Comments
RFA
Use
Input Values
Initialization and
RHB
Use
Input Values
Initialization and
Comments
ROP
Use
Input. Values
Initialization and
Comments
RSZ
Use
Input Values
Initialization and
STS
Use
Input Values
STV
Use
Input Values
UBF
Use
Input Values
Initialization and

Use
Input Values
Initialization and Default

4-17
4-17
4-17
4-18
4-19
4-19
4-19
4-19
4-20
4-20
4-20
4-21
4-21
4-22
4-22
4-22
4-22
4-23
4-23
4-23
4-24
4-24
4-25
4-25
4-25
4-27
4-27
4-28
4-28
4-28
4-29
4-30
4-30
4-30
4-31
4-31
4-31
4-32
4-32
4-33
4-33
4-34
4-34
4-34
4-34

EXTENDED ATTRIBUTE BLOCKS
Allocation Extended Attribute Block
AID
Use
Input Values
Initialization and Default
ALN
Use
Input Values
Initialization and Default
Comments

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

usz

Default

vii

5 .1. 3
5.1.3.1
5.1.3.2
5.1.3.3
5.1.3.4
5 .1. 4
5.1.4.1
5.1.4.2
5.1.4.3
5 .. 1.5
5.1.5.1
5.1.5.2
5.1.5.3
5.1.5.4
5 .. 1. 6
5.1.6.1
5 .. 1. 7
5.1.7.1
So 1. 8
5.1.8.1
5.1.8.2
5.1.8.3
5.1.8.4
501. 9
5.1.9.1
5.1.9.2
5.1.9.3
5. 1. 10
5.1.10.1
5.1.10.2
5.1.10.3
5. 1. 11
5.1.11.1
5.1.11.2
5.1.11.3
5.1.11.4
5.1.11.5
5.2
5.2.1
5.2.1.1
5.2.2
5.2.2.1
s.2.2.2
5.2.3
5.2.3.1
5.2.4
5.2.4.1
5.2.4.2
5.2.4.3
5.2.5
5.2.5.1
5.2.5.2
5.2.6
5.2.6.1
5.2.6.2
5.3
5.3.1

viii

ALQ
Use
Input Values
Initialization and Default
Comments
AOP
Use
Input Values
Initialization and Default
BKZ
Use
Input Values
Initialization and Default
Comments
BLN
Use
COD
Use
DEQ
Use
Input Val ue.s
Initialization and Default
Comments
LOC
Use
Input Values
Initialization and Default
NXT
Use
Input Values
Initialization and Default
VOL
Use
Input Values
Initialization and Default
Examples
Comments
Date Extended Attribute Block
BLN
Use
CDT
Use
Output Values
COD
Use
NXT
Use
Input Values
Initialization and Default
RDT
Use
Output Values
RVN
Use
Input Values
Key Extended Attribute Block
BLN

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

,._

"-.....,

5.3.1.1
5.3.2
5.3.2.1
5.3.3
5.3.3.1
5.3.3.2
5.3.3.3
5.3.4
5.3.4.1
5.3.4.2
5.3.5
5.3.5.1
5.3.5.2
5.3.5.3
5.3.6
5.3.6.1
5.3.6.2
5.3.6.3
5.3.7
5.3.7.1
5.3.7.2
5.3.8
5.3.8.1
5.3.8.2
5.3.8.3
5.3.8.4
5.3.9
5.3.9.1
5.3.9.2
5.3.9.3
5.3.10
5.3.10.1
5.3.10.2
5.3.11
5.3.11.1
5.3.11.2
5.3.11.3
5.3.12
5.3.12.1
5.3.12.2
5.3.12.3
5.3.13
5.3.13.1
5.3.13.2
5.3.13.3
5.3.13.4
5.3.14
5.3.14.1
5.3.14.2
5.3.15
5.3.15.1
5.3.15.2
5.3.15.3
5.3.16
5.3.16.1
5.3.16.2
5.3.17

Use
COD
Use
DAN
Use
Input Values
Initialization
DBS
Use
Output Values
DFL
Use
Input Values
Initialization
DTP
Use
Input Values
Initialization
DVB
Use
Output Values
FLG
Use
Input Values
Initialization
Comments
IAN
Use
Input Values
Initialization
!BS
Use
Output Values
!FL
Use
Input Values
Initialization
KNM
Use
Input Values
Initialization
LAN
Use
Input Values
Initialization
Comments
LVL
Use
Input Values
MRL
Use
Output Values
Comments
NSG
Use
Input Values
NUL

and Default

5-29
5-30
5-30
5-31
5-31
5-31
5-32
5-33
5-33
5-33
5-34
5-34
5-34
5-35
5-36
5-36
5-36
5-37
5-38
5·-38
5-38
5-39
5-39
5-39
5-40
5-40
5-41
5-41
5-41
5-42
5-43
5-43
5-43
5-44
5-44
5-44
5-45
5-46
5-46
5-46
5-47
5-48
5-48
5-48
5-49
5-49
5-50
5-50
5-50
5-51
5-51
5-51
5-51
5-52
5-52
5-52
5-53

5.3.17.1
5.3.17.2
5.3.17.3
5.3.17.4
5.3.18
5.3.18.1
5.3.18.2
5.3.18.3
5.3.19
5.3.19.1
5.3.19.2
5.3.19.3
5.3.19.4
5.3.20
5.3.20.1
5.3.20.2
5.3.20.3
5.3.21
5.3.21.1
5.3.21.2
5.3.22
5.3.22.1
5.3.22.2
5.3.22.3
5.3.22.4
5.3.22.5
5.3.23
5.3.23.1
5.3.23.2
5.4
5.4.1
5.4.1.1
5.4.2
5.4.2.1
5.4.3
5.4.3.1
5.4.3.2
5.4.3.3
5.4.4
5.4.4.1
5.4.4.2
5.4.4.3
5.4.5
5.4.5.1
5.4.5.2
5.4.5.3
5.4.6
5.4.6.1
5.4.6.2
5.4.6.3
5.5
5.5.1
5.5.1.1
5.5.2
5.5.2.1
5.5.3
5.5.3.1

Use
Input Values
Initialization and Default
Examples
NXT
Use
Input Values
Initialization and Default
POS
Use
Input Values
Initialization and Default
Comments
REF
Use
Input Values
Initialization and Default
RVB
Use
Output Values
SIZ
Use
Input Values
Initialization and Default
Examples
Comments
TKS
Use
Input Values
Protection Extended Attribute Block
BLN
Use
COD
Use
NXT
Use
Input Values
Initialization and Default
PRG
Use
Input Values
Initialization and Default
PRJ
Use
Input Values
Initialization and Default
PRO
Use
Input Values
Initialization and Default
Summary Extended Attribute Block
BLN
Use
COD
Use
NOA
Use

5-53
5-53
5-53
5-54
5-55
5-55
5-55
5-55
5-56
5-56
5-56
5-57
5-57
5-58
5-58
5-58
5-58
5-59
5-59
5-59
5-60
5-60
5-60
5-61
5-61
5-61
5-62
5-62
5-62
5-64
5-65
5-65
5-66
5-66
5-67
5-67
5-67
5-67
5-68
5-68
5-68
5-68
5-69
5-69
5-69
5-69
5-70
5-70
5-70
5-71
5-72
5-73
5-73
5-74
5-74
5-75
5-75

,.1'

·~

"-'

~·I

'--'

'--"'

5.5.3.2
5.5.4
5.5.4.1
5.5.4.2
5.5.5
5.5.5.1
5.5.5.2
5.5.5.3
5.5.6
5.5.6.1
5.5.6.2
5.5.6.3

Output Values
NOK
Use
Output Values
NXT
Use
Input Values
Initialization and Default
PVN
Use
Output Values
Comments

5-75
5-76
5-76
5-76
5-77
5-77
5-77
5-77
5-78
5-78
5-78
5-78

CHAPTER 6
6.1
6 .1.1
6 .1. 2
6.2
6.2.1
6.2.2
6.2.3
6.3
6.3.1
6.4
6.4.1
6.4.2
6.4.3
6.5
6.5.l
6.5.2

NAME BLOCK
DVI
Use
Input Values
ESA
Use
Input Values
Initialization and Default
ESL
Use
ESS
Use
Input Values
Initialization and Default
FID
Use
Input Values

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

CHAPTER 7
7.1
7 .1. 1
7 .1. 2
7 .1. 3
7.2
7.2.1
7.2.2
7.2.3
7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.4
7.4.1
7.4.2
7.4.3
7.4.4
7.5
7.5.1
7.5.2
7.5.3
7.6
7.6.1
7.6.2

FIELD ACCESS MACROS
$COMPARE
General Form
Effect
Examples
$FETCH
General Form
Effect
Examples
$OFF
General Form
Effect
Examples
Comments
$SET
General Form
Effect
Examples
Comments
$STORE
General Form
Effect
Examples
$TES TB ITS
General Form
Effect

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

7.6.3

CHAPTER 8
8.1
8 .1. 1
8.1.1.1
8.1.1.2
8.1.1.3
8.1.1.4
8.1.1.6
8 .1. 2
8.1.2.1
8.1.2.2
8.1.2.3
8.1.2.4
8 .1. 3
8.1.3.1
8.1.3.2
8.1.3.3
8.1.3.4
8.1.3.5
8 .1. 4
8.1.4.1
8.1.4.2
8.1.4.3
8.1.4.4
8.1.4.5
8 .1. 5
8.1.5.1
8.1.5.2
8.1.5.3
8.1.5.4
8.1.5.5
8 .1. 6
8.1.6.1
8.1.6.2
8.1.6.3
8.1.6.4
8.1.6.5
8.2
8.2.1
8.2.1.1
8.2.1.2
8.2.1.3
8.2.2
8.2.2.1
8.2.2.2
8.2.2.3
8.2.3
8.2.3.1
8.2.3.2
8.2.3.3
8.2.3.4
8.2.4
8.2.4.1
8.2.4.2
8.2.4.3
xii

Examples

7-11

FILE AND RECORD OPERATION MACROS
FILE OPERATION MACROS
$CLOSE
Buffer Requirements
Input Fields
Output Fields
General Form
Comments
$CREATE
Buffer Requirements
Input Fields
Output Fields
General Form
$DISPLAY
Buffer Requirements
Input Fields
Output Fields
General Form
Examples
$ERASE
Buffer Requirements
Input Fields
Output Fields
General Form
Comments
$EXTEND
Buffer Requi rem en ts
Input Fields
Output Fields
General Form
Comments
$OPEN
Buffer Requirements
Input Fields
Output Fields
General Form
Comments
RECORD OPERATION MACROS
$CONNECT
Input RAB Fields
Output RAB Fields
General Form
$DELETE
Input RAB Fields
Output RAB Fields
General Form
$DISCONNECT
Input RAB Fields
Output RAB Fields
General Form
Comments
$FIND
Input RAB Fields
Output RAB Fields
General Form

8-1
8-2
8-2
8-2
8-2
8-3
8-3
8-4
8-4
8-5
8-5
8-5
8-6
8-6
8-6
8-7
8-7
8-7
8-8
8-8
8-9
8-9
8-9
8-9
8-10
8-10
8-10
8-11
8-11
8-11
8-12
8-12
8-13
8-13
8-14
8-14
8-15
8-16
8-16
8-16
8-16
8-17
8-17
8-17
8-17
8-18
8-18
8-18
8-18
8-18
8-19
8-19
8-19
8-19

""
~

·~-·

'-"'

...,,

'"'-./

8.2.4.4
8.2.5
8.2 .. 5.1
8.2 .. 5.2
8.2.5.3
8.2.6
8.2.6.1
8.2.6 .. 2
8.2.6 .. 3
8.2.6 .. 4
8.2.7
8.2.7.1
8.2.7 .. 2
8.2.7 .. 3
8.2 .. 7.4
8.2.8
8.2.8 .. 1
8.2.8 .. 2
8.2.8 .. 3
8.2.9
8.2.9.1
8.2.9.2
8.2 .. 9 .. 3
8.2 .. 9.4
8.2.10
8.2 .. 10.1
8.2.10.2
8.2 .. 10.3
8.2.10.4
8.2.11
8.2 .. 11.1
8.2.11.2
8.2.11.3
8.2 .. 11.4
8.2.12
8.2 .. 12.1
8.2.12.2
8.2 .. 12.3
8.2 .. 12.4
8.2.13
8.2.13.1
8.2.13.2
8.2.13.3

CHAPTER 9
9.1
9.1.1
9.1. 2
9.1. 3
9.1. 4
9.2
9.2.1
9.2.2
9.2.3
9.2.4
9.3
9.3.1

Comments
$FLUSH
Input RAB Fields
Output RAB Fields
General Form
$FREE
Input RAB Fields
Output RAB Fields
General Form
Comments
$GET
Input RAB Fields
Output RAB Fields
General Form
Comments
$NXTVOL
Input RAB Fields
Output RAB Fields
General Form
$PUT
Input RAB Fields
Output RAB Fields
General Form
Comments
$REWIND
Input RAB Fields
Output RAB Fields
General Form
Comments
$TRUNCATE
Input RAB Fields
Output RAB Fields
General Form
Comments
$UPDATE
Input RAB Fields
Output RAB Fields
General Form
Comments
$WAIT
Input RAB Fields
Output RAB Fields
General Form

8-20
8-21
8-21
8-21
8-21
8-22
8-22
8-22
8-22
8-22
8-23
8-23
8-23
8-23
8-24
8-25
8-26
8-26
8-26
8-27
8-27
8-27
8-27
8-28
8-29
8-29
8-29
8-29
8-29
8-30
8-30
8-30
8-30
8-30
8-31
8-31
8-31
8-31
8-32
8-33
8-33
8-33
8-33

PERFORMING BLOCK I/O
$READ
Input RAB Fields
Output RAB Fields
General Form
Comments
$WRITE
Input RAB Fields
Output RAB Fields
General Form
Comments
$SPACE
Input RAB Fields

9-3
9-3
9-3
9-3
9-3
9-5
9-5
9-5
9-5
9-5
9-6
9-6

xiii

9.3.2
9.3.3
9.3.4

APPENDIX A
A.l
A.2
A.3
A. 3.1
A.3.2

Output RAB Fields
General Form
Comments
RMS-11 COMPLETION CODES
SUCCESSFUL COMPLETION CODES
ERROR COMPLETION CODES
FATAL ERROR CRASH ROUTINE
Fatal User Call Errors
RMS-11 Inconsistent Internal Conditions
Errors

APPENDIX B
B.l
B.2
B.3
B.4

SAMPLE RMS-11 PROGRAMS
COPYING SEQUENTIAL FILES
COUNTING WORDS IN A SEQUENTIAL FILE
TESTING RELATIVE FILE CAPABILITIES

APPENDIX C

DATE CONVERSION ROUTINE

9-6
9-6
9-6
A-2
A-3
A-17
A-17

A-18
B-1
B-5
B-14

Index-1

INDEX
TABLES

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

xiv

Minimum Set of .MCALL Arguments
Space Pool Declaration Macros
File Access Block Fields
Record Access Block Fields
NAM Block Fields
RMS-11 Field Access Macros
RMS-11 File Operation Macros
RMS-11 Record Operation Macros
Buffer Pool Declaration Macros
File Access Block Fields
Record Access Block Fields
Allocation Extended Attribute Block Fields
Date Extended Attribute Block Fields
Key Extended Attribute Block Fields
Protection Extended Attribute Block Fields
Summary Extended Attribute Block Fields
NAM Block Fields
RMS-11 Field Access Macros
RMS-11 File Operation Macros
RMS-11 Record Operation Macros
RMS-11 Block I/O Macros
RMS-11 Successful Completion Codes
RMS-11 Error Completion Codes

1-3
1-7
1-9
1-12
1-18
1-18
1-23
1-24
2-1
3-2
4-2
5-3
5-20
5-28
5-64
5-72
6-1
7-1
8-1
8-15
9-2
A-2
A-3

PREFACE

,_,,.

Record Management Services for the PDP-11 (RMS-11)
provides powerful
data management capabilities.
The RMS-11 User's Guide tells you about
those capabilities and how to use them.
This manual is designed as a
reference for MACR0-11 programmers.
RMS-11 is a set of software routines that transfers data between a
running program, which uses data in a logical form called records, and
the file processor portion of an operating system, which maintains the
physical structure of the data on a storage device.
NOTE
You can use RMS-11 Indexed files only if you have purchased
the RMS-llK software product.
Your system manager can tell
you if your system includes this capability.

PREREQUISITES
To read this manual, you should be a MACR0-11 programmer who has
and understood the RMS-11 User's Guide.

"-"'

"-"''

read

STRUCTURE OF THE MANUAL
Chapter l

tells you how to use RMS-11 routines in a MACR0-11 program, including the minimum requirements and the order in
which you must use them.

Chapter 2

covers the means of providing buffer space for RMS-11 operations.

Chapter 3

describes the fields of the File Access Block.

Chapter 4

describes the fields of the Record Access Block.

Chapter S

describes the fields of the different types
Attribute Blocks.

Chapter 6

describes the fields of the Name Block.

Chapter 7

describes the field access macros.

Chapter 8

describes the file and· record operation macros.

Chapter 9

describes the use of Block I/O.

Extended

Appendixes

provide supplementary information, such as:
RMS-11 success and error completion codes
Sample RMS-11 programs
Routine to convert 64-bit date-time information
ASCII

ASSOCIATED DOCUMENTS
The RMS-11 documentation set contains the following manuals:
RMS-11 User's Guide
RMS-11 MACR0-11 Reference Manual
RMS-11 Installation Guide
You must also use operating system documentation.
tion Directory for your operating system.

See the

Documenta-

xvi

DOCUMENTATION CONVENTIONS

RMS-11 operates similarly on the supporting operating systems (see Appendix A of the RMS-11 User's Guide).
Therefore, it should be possible to produce a single manual describing
that operation.
However,
the differences among operating systems present a barrier to that unification.
The following conventions are designed to enable you to
hurdle that fence.

DIFFERENCES IN OPERATING SYSTEM FUNCTIONS
Details that are common to the operating systems are printed in black,
and
the details that are specific to one operating system o~ another
are printed in color as follows:
•

RSTS/E-specific information is printed in red.

•

!AS-, RSX-llM-, and VAX-specific information is printed in blue.

SYNTAX DESCRIPTIONS
In the descriptions of macro usage, this manual
includes
form for each macro, using the following conventions:
all

general

RE(~UIRED

You must include
acters as shown.

uppercase

char-

us EH-specific

You substitute for lowercase characters
information specific to your usage.

[may be used]

You can, but do not have to
include
characters in brackets.
The convention
••• ] means the series can continue until
it exhausts logical possibilities.

Punctuation

You must use punctuation as shown.

The descriptions of user control block fields that contain numeric values include m1n1mum and maximum specifications.
These are logical
values and normally, are not equal to the physical minimum and maximum
for the field.
Additionally, a portion of a field, whether byte or word, described as
"low order"
or "least significant" is the portion with the lower address.

xvii

CHAPTER 1
USING RMS-11 IN A MACR0-11 PROGRAM

Record Management Services for PDP-11 operating systems (RMS-11) is a
set of routines that enable programs to process files and records
within files.
The RMS-11 User's Guide describes the features of
RMS-11.
All capabilities supported by an operating system are available to a MACR0-11 program.
To obtain RMS-11 services at run time, your program must contain
RMS-11 processing macros and user control blocks.
The processing macros are expanded at assembly time.
The resulting code is executed at
run time to perform the specified 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 the RMS-11 routines via user control blocks.
These
blocks are:
Block Name

Function

File Access Block (FAB)

Describes a file and contains
file-related information.

Record Access Block (RAB)

Describes a Record Access Stream and the records being accessed by that stream.

Extended Attribute Block (XAB)

Contains file attribute information beyond that in the FAB.

Name Block (NAM)

Describes a location in memory
containing system-related
information about a file.

Prior to issuing a
place information
block.
Example

requ~st

for an RMS-11 service, your program must
detailing
the request in the associated control

A request to open a file must be accompanied by the name or
ID of the file,
information on how the file will be accessed, and details on how the file is to be shared.

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-11 uses the same
control block to return information to your program. When a file has
been successfully opened, RMS-11 provides attribute
information such
as the organization of the file and the format of the records in the
file.
After successfully retrieving a record from a file, RMS-11 provides your program with the location in memory of the record and the
length of the record.
The amount of information exchanged between RMS-11 and your program
varies with the nature of the request and the attributes of the file
being processed.
To use RMS-11 routines in a MACR0-11 program, you must understand
to:
1.

Declare the RMS-11 facilities that your program requires.

Allocate and initialize user control blocks designed
cate with RMS-11.

Access fields in user control blocks at run time.

Perform file and record operations.

Assemble your program modules and task build them with the
routines.

1.1

DECLARING RMS-11 FACILITIES

how

communi-

RMS-11

Every program that processes RMS-11 files must contain directives and
special-purpose macros that declare the RMS-11 facilities required at
assembly and run time.
To declare RMS-11 facilities that are used by
your program, you must do the following:
1.

List RMS-11 macros in .MCALL directives.

Declare the processing environment.

Declare buffer pool requirements and techniques.

Issue a $!NIT or $INITIF macro.

NOTE
Unless otherwise noted, RMS-11 macros use decimal radix
numeric values.

1-2

Using RMS-11 in a MACR0-11 Program

for

1.1.1

Listing Names of Required Macro Definitions

All macros used in your p(ogram must be listed as arguments in a
.MCALL directive.
Listing the macros in this way allows the actual
code of each macro to be read in from the RMS-11 source macro library
(RMSMAC.MLB) during assembly.
General form:
.MCALL arg[,arg] •• ]
where arg is a symbolic name of a macro required in the (assembly of
your program.
The macro names can be listed in ~ny order.
The number of .MCALL directives can be minimized because some macro
definitions contain .MCALL directives.
Table 1-1 contains the minimum
.MCALL arguments that provide .MCALL directives for all RMS-11 macros
that can be used in a program.
Table 1-1:

Minimum Set of .MCALL Arguments

.MCALL Arguments

Embedded .MCALL Arguments

ORG$

None.

POOL$B

Central buffer pool declaration macros.

$INIT or $INITIF

None.

$GNCAL

Run-time field access macros
(described
in
Chapter 7)
and completion routine macros (described in this chapter).

FAB$B

File Access Block allocation and
initialization
macros
(described in this chapter), field offset
macros (described in Chapter 3), and error code
macros (described in Appendix A).

RAB$B

Record Access Block allocation and initialization
macros
(described in this chapter), field offset
macros (described in Chapter 4), and error code
macros (described in Appendix A).

XAB$B

Extended Attribute Block allocation and initialization macros (described in this chapter), field
offset macros (described in Chapter 5), and error
code macros (described in Appendix A).

NAM$B

Name Block allocation and
initialization
(described
in this chapter),
field offset macros
(described in Chapter 6), and error code macros
(described in Appendix A).

$FBCAL

File operation macros (described in Chapter 9).

$RB CAL

Record operation macros (described in Chapter 9).
Using RMS-11 in a MACR0-11 Program

1-3

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

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

By issuing the $GNCAL, $FBCAL, and $RBCAL macros, you cause the embedded .MCALL directives to take effect.
You can omit any macro names from .MCALL directives that do not
to a particular program.
Example

If the program does not use Name or Extended
Blocks, do not include the NAM$B or XAB$B macros.

apply

Attribute

You may also omit the $RBCAL or $FBCAL macros and list separately each
file and record operation macros used by your program.
NOTE
If you are allocating control blocks
in one module,
but
using
field offset and/or error code macros in other modules, in those modules you must:
1.

include one or more of the following arguments in .MCALL
directives

execute the specified macros, in the form:
macnam RMS$L
except $RMSTAT, which requires no argument when executed

1-4

.MCALL Arguments

Embedded Macro Definitions

FABOF$

FAB field offsets

RAB OF$

RAB field offsets

XABOF$

XAB field offsets

NAM OF$

NAM field offsets

$RMSTAT

Error codes

Using RMS-11 in a MACR0-11 Program

1.1.2

Declaring the Processing Environment

You must include one or more ORG$ macros within the set of modules
that you link together with the Task Builder to produce an executable
task.
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 use of ORG$ macros in your source modules enables the Task Builder
to select for linking only those portions of RMS-11 required by your
program*.
Each ORG$ macro declares a unique combination of file organization and record operations.
General form:
ORG$

org[,<recop[,recop ••• ]>]

where org is the type of file organization as
symbolic values:

one

the

following

!DX = Indexed file organization
REL = Relative file organization
SEQ = Sequential file organization
recap is a symbolic value identifying a type of record operation
that will be performed on a file of the specified organization.
If a single value is included, 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 symbolic values may
fied in any order:

speci-

CRE = file of specified organization may be created
DEL = delete operation
FIN = find operation
GET = get operation
PUT = put operation
UPD = update operation
Example

The following code declares that one or more Sequential
files will be created and put operation performed by the
program.
Additionally, one or more Indexed
files will be
opened and
find,
get,
and update operations will be performed on those files.
Finally, one or more Relative files
will be opened, but no record operations will be performed:
file operations may be performed.
ORG$
ORG$
ORG$

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

*When you task build RMS-11 nonoverlaid.
If you use an RMS-11 overlay
structure,
the ODL file specifies which RMS-11 modules are linked to
your program.
However, the ORG$ macro still determines which of
those routines your program can use.
Using RMS-11 in a MACR0-11 Program

1-5

1.1.3

Declaring Buffer Pool Requirements

RMS-11 requires a collection of I/O buffers and
internal control
structures to support file processing at run time.
The. areak in your
program occupied by these buffers and control structures 1s
nown as
the buffer pool.

The major portion of the buffer pool is composed of I/O buffers.
To
your program,
record processing under RMS-11 appears as the movement
of records directly between a file and the program itself.
However,
RMS-11 actually uses I/O buffers as intermediate storage during data
transfers:
•

When your program finds or gets a record, RMS-11 moves the block or
bucket containing the record from the file to an I/O buffer.
Then,
on a get, RMS-11 moves the record from the buffer to your program.

•

When your program puts, updates, or deletes a record, RMS-11 moves
the specified data from your program to the I/O buffer.
Then, for
Relative and Indexed files, normally RMS-11 moves the bucket in the
buffer out to the file immediately.
However, for Sequential files
and for Relative and Indexed files with Deferred Write specified,
RMS-11 doesn't write out the buffer until it has to be used for
another operation.

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 buffer pool, you have three choices:
1.

A centralized buffer pool controlled by RMS-11.

Private I/O buffers for one or more files plus a centralized
controlled by RMS-11 for other requirements.

A centralized buffer pool controlled by a routine you provide.

pool

When RMS-11 controls a centralized buffer pool, RMS-11 allocates I/O
buffers as well as the internal control structures required for file
processing from a single area in your program.
Normally,
this space
is inaccessible to your program:
RMS-11 totally manages the space
within the pool and allocates portions, as needed,
for buffer space
and control structures for open files.

You can also allocate private I/O buffers on a per-file basis by specifying the address and total size of each buffer in fields of the File
Access Block associated with a file.
When the file
is open,
this
buffer space is completely managed by RMS-11 and your program must not
access it.
However, when the file ~s closed, the private I/O buffer
space is available for use by your program.
The major advantage of private I/O buffers is avoidance of fragmentation in a centralized buffer pool.
Since particular files have varying I/O buffer requirements based on their organization, a centralized
buffer pool can reach the point where there is sufficient total space
available for the opening of an additional file, but the space is not
1-6

Using RMS-11 in a MACR0-11 Program

-·

·,

contiguous.
be opened.

When

such a situation arises, the specified file cannot

Whether you let RMS-11 control a centralized buffer pool or specify
private I/O buffers, RMS-11 always requires certain internal control
structures that must be allocated in the buffer pool to support file
processing.
The number of internal control structures required by
RMS-11 in the buffer 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 centralized buffer pool.
The presence in your source modules of the macros listed in Table 1-2
allows RMS-11 to determine the size requirements for your program's
buffer pool.
The macros are described in Chapter 2.
If you want private I/O buffers for one or more files, you can allocate these on a
file-by-file basis, either statically (at assembly time) or dynamically (at run time).
Refer to the descriptions of the BPA (buffer pool
address) and BPS (buffer pool size) fields in Chapter 3.
Finally, you can assume total control over buffer space, allocating it
when RMS-11
requires it, taking it back when RMS-11 no longer needs
it.
This facility, called Get Space Address
(GSA),
is complex and
should not be used by most programmers. Chapter 2 also describes the
requirements for the GSA routine.
Table 1-2:

Space Pool Declaration Macros

Macro

Description

Required

POOL$B

Beginning of space pool declaration

Yes

P$BDB

Number of Buffer Descriptor Blocks

Yes

P$FAB

Number of files open simultaneously

Yes

P$RAB

Nonindexed streams connected
simultaneously

If Sequential or
Relative files

P$RABX

Indexed streams connected
s imul taneousl y

If Indexed files

P$IDX

Number of defined keys

If Indexed files

P$BUF

Input/output buffer requirements

If no BPA or GSA

POOL$E

End of space pool declaration

Yes

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

Using RMS-11 in a MACR0-11 Program

1-7

1.1. 4

Initializing the Processing Environment

Your program must initialize the RMS-11 processing environment at run
time before the program attempts an RMS-11 operation. You accomplish
this with the $!NIT or $INITIF macro.
General form:
$!NIT

$INITIF

The code generated by the $!NIT macro undonditionally initializes
RMS-11 internal control structures at run time.
The $INITIF code,
however, initializes the internal structures only if they have not
been initialized during the current execution of the task.
You use
the $INITIF macro in program modules that can be the first to use
RMS-11, but are not always run first.
RMS-11 clears the Processor Status Word 0-Bit to indicate that initializ:ation was successful. Therefore, normally after $!NIT, the
0-Bit is cleared; if the 0-Bit is set, an RMS-11 file was open when
the macro was initiated and no initialization occurred. Normally
after $INITIF, the 0-Bit is set; if the 0-Bit is cleared, the processing environment was previously initialized.
If your program initiates any RMS-11 file or record operation before
the environment is initialized, RMS-11 returns ER$INI error code.

1-7.1 Using RMS-11 in a MACR0-11 Program

1.2

USER CONTROL BLOCKS

User control blocks are formatted buffers in your program's address
space.
Each control block consists of data fields that are used to
exchange information between your program and the RMS-11 routines.
You must allocate space for control blocks in your program at assembly
time.
You can also establish initial values for many of the data
fields in these blocks at assembly time; or you can defer setting the
contents of control block fields until run time.
RMS-11 provides special macros that perform the functions needed to support control block
allocation, assembly-time field initialization, and run-time field access.

1.2.1

File Access Block (FAB)

A File Access Block, abbreviated FAB, represents a file during the execution of file operation macros:

~
i

$CLOSE
$CREATE
$DISPLAY
$ERASE
$EXTEND
$OPEN
FAB fields (listed in Table 1-3) must contain the proper values before
the macro is initiated, but they may be changed after the operation is
complete because RMS-11 has transferred the pertinent information
about the file to an internal (nonvisible) structure called an Internal File Access Block (IFAB).
Therefore, one FAB may be used to represent any number of files as
long as the FAB is changed appropriately before each file operation is
initiated. As a minimum you must ensure that the block is a valid FAB
(BID and BLN fields contain the proper values) and that the FAB !FI
field contains the value returned by RMS-11 when the file was created
or opened.
This value is the pointer to the IFAB.
You should also
set the FAB's fields to the values appropriate to the file operation
you are preparing for:
do not assume that the fields contain the values you set before the last use.

1.2.1.1 Allocation - Each FAB must be
The minimum syntax is:

allocated

assembly

time.

• EVEN
label: FAB$B
FAB$E
where label is the name of the FAB and not necessarily the name of the
file associated with the FAB.

,~
i

The FAB$B macro allocates space for
1-8

the

Using RMS-11 in a MACR0-11 Program

FAB,

and

the

FAB$E

macro

stores values in the individual FAB fields and terminates the definition of the block.
Table 1-3:
Field
Name

Field
Size

ALQ
BID
*BKS
BLN
*BLS
BPA
BPS
CTX
*DEQ
DEV
DNA
DNS
FAC
FNA
FNS
FOP
*FSZ
!FI
LCH
*MRN
*MRS
NAM
*ORG
*RAT
*RFM
RTV
*RTV
SHR
STS
STV

2W
lB
lB
lB
lW
lW
lW
lW
lW
lB
lW
lB
lB
lW
lB
lW
lB
lW
lB
2W
lW
lW
lB
lB
lB
lB
lB
lB
lW
lW
lW

XAB

File Access Block Fields
Default
0

N/A
1 record
N/A
0
0

0
0
0

N/A
0
0

FB$GET
0
0

0
0
N/A
0

0
0
0

FB$SEQ
0

FB$VAR
0

0
0

N/A
N/A
0

Description
Size of file
FAB identifier
Bucket size
RAB length
Block size
Location of private I/O buffer
Size of private I/O buffer
Available to user
Automatic extension quantity
Device characteristics
Location of filespec defaults
Size of filespec defaults
Types of record operations
Location of f ilespec
Size of filespec
File processing options
Size of fixed area for VFC
Pointer to IFAB
Logical channel
Maximum Record Number
Maximum Record Size
Pointer to NAM Block
File organization
Record attributes
Record format
Window size
Cl ustersi ze
File sharing
Completion code
More error information
Pointer to first XAB

*File attribute

1.2.1.2 Initialization - The value stored in a FAB field by the FAB$E
macro
is determined by an initialization macro, or in its absence, an
RMS-11 default for the field (see "Initialization and Default" in the
individual sections on the fields in Chapter 3).

Using RMS-11 in a MACR0-11 Program

1-9

If you want a field to contain a value other than its default value,
you must specify its initialization macro between the FAB$B and FAB$E
macros*. Initialization macros have the general form:
F$fnm arg
where fnm is the three-letter field name, such as ALQ, MRN, and so on,
and
arg is one or more arguments specifying the value(s) to
tered in the indicated field; arg can be a:

en-

•

symbolic value, such as FB$PUT (representing put operations), in the form FB$nam; symbolic values are joined
together with exclamation points (!).

•

label, that is, the MACR0-11 term for the name of an
dress in the program, such as the start of a buffer.

•

nhumericbvaluef 1 bsuch ashmaximum rbec ordk sizde, specifying
t e num er o
ytes, c aracters, 1 oc s, an so on.

ad-

Cautions:
•

Because initialization macros operate at assembly time, you cannot
use global symbols or labels as arguments. All symbols and labels
must be defined locally, that is, in the same module with the macros.

•

The default radix for numeric values in
dee imal.

1.2.2

initialization

macros

Record Access Block (RAB)

A Record Access Block, abbreviated RAB, represents a Record
Stream during the execution of record operation macros:

Access

$CONNECT
$DELETE
$DISCONNECT
$FIND
$GET
$PUT
$UPDATE
$REWIND
$TRUNCATE
$FLUSH
$NXTVOL
The RAB not only completely describes the format of the
volved, but also all other aspects of record operations.

records

in-

*The value of any field can also be set at run time by the
cess macros $SET and $STORE; see Chapter 7.

field

ac-

1-10

Using RMS-11 in a MACR0-11 Program

)"'1i'l!L1t,

RAB fields (listed in Table 1-4) must contain the proper values before
the stream is set up (via the $CONNECT macro) and before record operations are initiated, but they can be changed after each operation is
complete because RMS-11 has transferred
the pertinent information
about the stream to an internal
(nonvisible)
structure called an
Internal Record Access Block (!RAB).
Therefore, one RAB may be used to represent any number of streams as
long as the RAB is changed appropriately before each record operation
is initiated.
As a minimum you must ensure that the block is a valid
RAB
(BID and BLN fields contain the proper values) and that the RAB
IS! field contains the value returned by RMS-11 when the stream was
connected
to a
file.
This value is the pointer to the !RAB.
You
should also set the RAB's fields to the values appropriate to the record operation you are preparing for:
do not assume that the fields
contain the values you set before the last use.

1.2.2.1 Allocation - Each RAB must be
The minimum syntax is:

allocated

assembly

time.

.EVEN
label: RAB$B [type]
RAB$E
where label is the name of the RAB, and
type indicates if the program will attempt asynchronous I/O operations using
the RAB (see Chapter 1), with one of the
following values:
SYN

means synchronous record operations only

ASYN means both synchronous and
operations

asynchronous

record

The RAJ3$B macro allocates space for
the RAB,
and
the RAB$E macro
stores values in the individual RAB fields and terminates the definition of the block.

1.2.2.2 Initialization - The value stored in a RAB field by the RAB$E
macro
is determined by an initialization macro, or in its absence, an
RMS-11 default for the field (see "Initialization and Default" in the
individual sections on the fields).
If you want a field to contain a value other than its default value,
you must specify its initialization macro between the RAB$B and RAB$E
macros*.
Initialization macros have the general form:
*The value of any field can also be set at run time by the
cess macros $SET and $STORE;
see Chapter 7.

field

ac-

Using RMS-11 in a MACR0-11 Program

1-11

R$fnm arg
where fnm is the three-letter field name, such as KBF, RAC, and so on
arg

is one or more arguments specifying the value(s) to be
tered in the indicated field; arg can be a:
•

en-

symbolic value, such as RB$KEY, specifying a random record operation, in the form RB$nam; two or more symbolic values are joined together with exclamation points
(!) •

•

label, that is, the MACR0-11 term for the name of an address in the program, such as the start of a buffer.

•

numeric value, such as maximum record size, specifying
the number of bytes, characters, blocks, and so on.

Cautions:
•

Because initialization macros operate at assembly-time, you cannot
use global symbols or labels as arguments. All symbols and labels
must defined locally, that is, in the same module with the macros.

•

The default radix for numeric values in
decimal.

Table 1-4:

Record Access Block Fields

Field
Name

Field
Size

Default

BID
BKT
BLN
CTX
FAB
!SI
KBF
KRF
KSZ
MBC
MBF
RAC
RBF
RFA
RHB
ROP
RSZ
STS
STV
UBF

lB
2W
lB
lW
lW
lW
lW
lB
lB
lB
lB
lB
lW
3W
lW
lW
lW
lW
lW
lW
lW

N/A
None
N/A

usz

initialization

0
0

N/A
0
0
0
0
0
0
0
0
0
0
0

N/A
N/A
0
0

macros

Description
RAB identifier
Relative record number or VBN
RAB length
User area
FAB address
Pointer to !RAB
Key buffer address
Key of reference
Key buffer size
Multiblock count
Multibuffer count
Record Access Mode
Address of output record
Record's File Address
Fixed control area buffer
Record processing options
Size of output record
Completion status code
Status value
Input record buffer
Input record buffer size

1-12

Using RMS-11 in a MACR0-11 Program

1.2.3

Extended Attribute Block (XAB)

An Extended Attribute Block, abbreviated XAB, is an extension of the
File Access Block for an RMS-11 file. An XAB represents one of the
following during file operations:
Area (Indexed only)
Key (Indexed only)
Date-time information
Protection information
Summary information (Indexed only)
XABs are generally required only when a file is created, particularly
if the file is Indexed, or when the $DISPLAY macro is used to retrieve
information about a file.
XAB fields (listed by XAB type in Chapter 5) must contain the proper
values before the operation is initiated, but they may be changed
after each operation is complete because RMS-11 has transferred the
pertinent information about the file to the appropriate IFAB.

1.2.3.1 Allocation - Each XAB must be
The minimum syntax is:

allocated

assembly

time.

.EVEN
label: XAB$B type
XAB$E
"-"'

where 1 ab el is the name of the XAB, and
type indicates the type of information contained in the XAB and
therefore its structure and fields, with one of the following values:
;rn$ALL

the XAB defines a file area

XB$DAT

the XAB contains date-time information

XB$KEY

the XAB defines a key for an Indexed file

XB$PRO

the XAB specifies file protection information

XB$SUM

the XAB contains summary information about an
Indexed fi 1 e

A type must be specified, or the MACRO assembler will generate an error.
The XAB$B macro allocates space for the XAB, and the XAB$E macro
stores values in the individual XAB fields, including the type symbolic value in the COD field, and terminates the definition of the block.

Using RMS-11 in a MACR0-11 Program

1-13

1.2.3.2 Initialization - The value stored in an XAB field
by the
XAB$E macro
is determined by an initialization macro, or in its absence, an RMS-11 default for the field (see "Initialization and Default" in the individual sections on the fields).
If you want a field to contain a value other than its default value,
you must specify its initialization macro between the XAB$B and XAB$E
macros*.
Initialization macros have the general form:
X$fnm arg
where fnm is the three-letter field name, such as IAN, RDT, and so on
arg

is one or more arguments specifying the value(s)
tered in the indicated field;
arg can be a:

to be

en-

•

symbolic value, such as XB$NUL,
representing null
key
specification, in the form XB$nam;
two or more symbolic
values are joined together with exclamation points (!).

•

label, that is, the MACR0-11 term for the name of an address in the program, such as the start of a buffer.

•

numeric value,
such as fill
number, specifying
number of bytes, characters, blocks, and so on.

the

Cautions:
•

Because initialization macros operate at assembly-time, you cannot
use global symbols or labels as arguments. All symbols and labels
must be defined locally, that is, in the same module with the macros.

•

The default radix for numeric values in
decimal.

initialization

macros

1.2.3.3 Linking and Ordering XABs - Whene~er you want to include Extended Attribute Blocks in a file operation, you must link them with
the File Access Block and with each other.
This linking is done with
pointers, addresses stored
in the FAB XAB field and then in each' of
the XAB NXT fields;
the end of the chain is indicated by a
zero NXT
field.

1.2.3.3.1 Ordering by Type of XAB - Within a chain of XABs,
RMS-11
does not require any ordering by type, that is, the contents of the
COD field.

*The value of any field can also be set at run time by the
cess macros $SET or $STORE; see Chapter 7.
1-14

Using RMS-11 in a MACR0-11 Program

field

ac-

Ji!MI~

Example

To determine the attributes of a
single-key
allocate, at assembly time, one each:
Type

Label

Date XAB
Key XAB
Protection XAB
Summary XAB

DATXAB
KEYXAB
PROXAB
SUMXAB

Indexed

You can link these blocks together in several ways;
them are:
1.

file,

two

At assembly time, with initialization macros:
• EVEN
DSPFAB: FAB$B

X$XAB

DATXAB

FAB$E
DATXAB: XAB$B

XB$DAT

X$NXT

KEYXAB

XAB$E
KEYXAB: XAB$B

.
X$NXT
.
XAB$E

XB$KEY

PROXAB: XAB$B

XB$PRO

PROXAB

.
X$NXT

SUMXAB

XAB$E
SUMXAB: XAB$B

XB$SUM

POINT TO FIRST XAB

;

POINT TO NEXT XAB

;

POINT TO NEXT XAB

XAB$E
2.

At run time, with the $STORE macro:
MOV

#DSPFAB,R4

;

$STORE #SUMXAB,XAB,R4
MOV
$STORE
MOV
$STORE
MOV
$STORE
MOV
$STORE

#SUMXAB, R4
#KEYXAB,NXT,R4
#KEYXAB, R4
#DATXAB,NXT,R4
#DATXAB,R4
#P.ROXAB, NXT, R4
#PROXAB,R4
#0, NXT, R4

Finally, you issue a $DISPLAY

;

PUT FAB ADDRESS IN R4, AS
REQUIRED
MAKE DIFF XAB lST IN
CHAIN
PUT XAB ADDRESS IN R4
LINK IN NEXT XAB
PUT XAB ADDRESS IN R4
LINK IN NEXT XAB
PUT XAB ADDRESS IN R4
LINK IN NEXT XAB
PUT XAB ADDRESS IN R4
LINK IN NEXT XAB

macro

(see

Chapter

and

Using RMS-11 in a MACR0-11 Program

1-15

RMS-11 fills the XAB chain with attribute information, setting fields in accordance with the COD field of each block.

1.2.3.3.2 Ordering Within XAB Type - Multiple instances
Allocation XABs must be linked:

Key

and

•

In ascending order by contents of a numbering field, that
REF and AID fields respectively

is,

the

•

Logically contiguous, that is, there can be no XABs of other
within a series of Key or Allocation XABs

•

Densely for the $CREATE operation, that is, the XABs must be numbered 1, 2, 3, and so on;
by contrast, the numbering for $DISPLAY,
$EXTEND, and $OPEN does not have to be dense;
that is, you can select only certain keys or areas whose attributes you want set

1.2.4

types

Name Block

A Name Control Block, abbreviated NAM, contains system-specific information about a file, including:
Full File Specification
An ASCII string representing RMS-ll's merger of:
•

the primary file name string described by the FAB FNA and
FNS fields

•

the default name string described by the FAB DNA and
fields

•

the system defaults

DNS

File ID
A~

hindex that th~ file_proces~or can use to locat~ a
file
wit out consulting directories;
must be used with device
ID.

Device ID
An indicator for the device containing the
used with file ID.

file;

must

RMS-11 provides this information in NAM Block fields (listed in Table
1-5)
during create and open operations and uses this information as
input during erase and ~pen operations.
You indicate the existence of a NAM Block for these services by setting
the FAB NAM field
to the address of a properly allocated NAM
Block.
NAM Block fields must contain the proper values before the operation is initiated, but they may be changed after the operation is
complete.

1-16

Using RMS-11 in a MACR0-11 Program

1.2.4.1 Allocation - Each NAM Block must
time. The minimum syntax is:

allocated

assembly

• EVEN
label: NAM$B
NAM$E
where label is the name of the NAM Block.
The NAM$B macro allocates space for the NAM, and the NAM$E macro
stores values in the individual NAM fields and terminates the definition of the block.

1.2.4.2 Initialization - The value stored in a NAM field by the NAM$E
macro is determined by an initialization macro, or in its absence, an
RMS-11 default for the field (see ninitialization and Default" in the
individual sections on the fields).
If you want a field to contain a value other than its default value,
you must specify its initialization macro between the NAM$B and NAM$E
macros*. Initialization macros have the general form:
N$fnm arg
where fnm is the three-letter field name, such as ESA, ESL, and so on,
and
arg is one or more arguments specifying the value(s) to
tered in the indicated field; arg can be a:

en-

•

label, that is, the MACR0-11 term for the name of an
dress in the program, such as the start of a buffer.

ad-

•

numeric value, such as expanded string
the number of bytes.

size,

specifying

Cautions:

'-"':

•

Because initialization macros operate at assembly time, you cahnot
use· global symbols or 1 ab els as arguments. Al 1 symbols and labels
must be defined locally, that is, in the same module with the macros.

•

The default radix for numeric values in
dee imal.

initialization

macros

field

ac-

Using RMS-11 in a MACR0-11 Program

1-17

*The value of any field can also be set at run time by the
cess macros $SET and $STORE; see Chapter 7.

Table 1-5:
Field
Name

Field
Size

DVI
ESA
ESL
ESS
FID

lW
lW
18
lB
18

1.3

NAM Block Fields
Default
0
0
0
0
0

Description
Device ID
Expanded string address
Expanded string length
Expanded string size
File ID

CONTROL BLOCK FIELD ACCESS AT RUN TIME

RMS-11 field access macro retrieve, modify, and test the contents of
fields in the RMS-11 control blocks, FABs, RABs, and XABs, at run
time. These macros enable you to treat the control block fields as
logical entities, without regard for the placement of the fields within the control blocks and to a large degree, for the sizes of the
fields.
Table 1-6 contains a summary of the available macros.
also described in a separate section of Chapter 7.
Table 1-6:

Each

macro

RMS-11 Field Access Macros
Function

Macro Name

Field Size

$COMPARE

1 byte or 1 word

Compares the contents of
with a value you specify.

$FETCH

Any size

Copies the contents of a field into
a location you specify.

$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

Copies the contents of a
you specify into a field.

$TESTBITS

1 byte or 1 word

Tests one or more bits within a bit
string field ..

bits

a
bit

location

RMS-11 assumes octal radix for all numeric values used as
operands for the field access macros. You indicate decimal
radix with an explicit decimal point following a numeric
value.

Using RMS-11 in a MACR0-11 Program

field

within

NOTE

1-18

1.4

FILE AND RECORD OPERATIONS

You use the RMS-11 file and record operation macros to access and manipulate files and records within files.
These macros combine with the
control blocks (Chapters 3 through 6) to form your program's run-time
interface with RMS-11.
Before executing one of these macros, your program sets values in a
control block"s fields, then specifies the block as an argument to the
macro.
The macro initiates all processing involved with the indicated
RMS-11
operation.
During the operation, RMS-11 returns information
about the processing in fields of the associated control block.
If you do not initialize or set fields, relying on defaults,
RMS-11
changes the fields to contain the default or minimum values as output
from the operation.
See the RMS-11 User's Guide for a description of the operations
selves.

them-

While differing in function, the file and record operation macros use
the same general format and calling sequence. Within the calling sequence, you identify the control block associated with the operation
and optional completion routines.
Before your program initiates a file or
must:

record

operation

macro,

Ensure that the appropriate values are set in the fields used by
RMS-11 during the operation.
You do this with either initialization macros (see Chapters 3, 4, and 5) or field access macros (see
Chapter 7).

Execute the correct calling sequence.

1.4.1

Completion Routines

You can write subroutines that RMS-11 executes as an extension of a
file or record operation macro.
These completion routines can be used
after the successful completion or after error termination of an operation.
RMS-11 invokes a completion routine if you supply an address at the
appropriate point in the calling sequence for the operation. At the
end of the completion routine, RMS-11 restores the stack and other
parameters and returns control to your program at the point after the
macro was initiated.
The use of completion routines is always optional.
However, if you do
not use completion routines, your program should check the value of
the associated block's STS field after the macro has been executed.
If the status code is negative, an error occurred during the operation.
If the status code is positive, the operation was successful,
although an STS value greater than one indicates qualified success.
Using RMS-11 in a MACR0-11 Program

1-19

See Appendix A for a description of the completion codes.
field should never contain zero after an RMS-11 operation.
When using completion routines, you must be aware
the following areas:

The

STS

conventions

-""

Register Usage
General register RS contains the address of the same argument list or a copy of the argument list, that was part of
the calling sequence to the RMS-11 operation
(see Section
8.0.2). Therefore, you can use the control block address at
2(RS) to access fields in the control block.
RMS-11 Operations within Completion Routines
A completion routine can execute file and
record operation
macros.
Each operation is an extension of the original operation that caused the completion routine to be used.
See
Appendix A of the RMS-11 User's Guide for restrictions on
this capability in the RMS-11 Asynchronous Environment.}
To return control from a completion routine to
must do the following:

RMS-11,

your

program

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

Execute a $RETURN macro, in the form:

·~!

$RETURN
This macro requi.res no arguments and denotes the end of a
tion routine.

1.4.2

comple-

Calling Sequence

Each file and record operation macro requires a word-aligned formatted
argument list.
Your program can construct this list or allow RMS-11
to build it. Generally, your program generates less code and use less
stack to build the list than does RMS-11.

1.4.2.1 Your Program Supplies the Argument List - If your program
constructs the argument list, it executes RMS-11 file and record operations with the following sequence:

1-20

Using RMS-11 in a MACR0-11 Program

+!!_ _, __ _ _ _ _ _ _ _ _ _ _ _. . ._ _ _ _ _ _ _ _ _ _ _ _ _ _. , ._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

The program constructs the argument list in the
with the arguments arranged in the order shown:

following

form,

Argument

Size

RMS-11 Interpretation

Undefined
Arg um en t Count

1 byte
1 byte

Block Address

1 word

Error Address

1 word

Success Address

1 word

Not used.
Binary value from 1 through 3 representing the number of arguments to
be used from the argument list.
This field equals 1 if you do not
supply completion routine addresses.
Address of a FAB for file operations
or a RAB for record operations.
Address of a completion routine you
want called if the operation fails.
Address of a completion routine you
want called if the operation completes successfully.
Not used by
file operation macros.

Store the address of the argument 1 ist in general register RS.

Execute the file or record operation macro without
the form:

arguments,

$macnam
4.

If completion routines were specified, continue processing because
success and/or failure has been tested and handled. Otherwise,
check the STS field 6f the associated control block.

Example

The following code constructs an argument list and
to execute a get operation:

LIST:

Example

uses

MOV
$GET

#LIST,R5

;ADDRESS OF ARGUMENT LIST
;READ A RECORD FROM THE FILE

.WORD
.WORD
.WORD
.WORD

INRAB
ERR!
SUCCl

;NUMBER OF ARGUMENTS
;RECORD ACCESS BLOCK ADDRESS
;ERROR ROUTINE ADDRESS
;SUCCESS ROUTINE ADDRESS

The following code constructs an argument list specifying a
success completion routine, but no error completion routine:
LIST:

.WORD
.WORD
.WORD
.WORD

INRAB
-1
SUCCl

;NO ERROR ROUTINE

Using RMS-11 in a MACR0-11 Program

1-21

Example

The following code constructs an argument list specifying
error and
success routines, but the program determines before
the operation is initiated
that neither
routine
applies:
MOV
#1, LIST
#LIST,RS
MOV
$GET
$COMPARE #0,STS,2(R5)
SGT
NXTSTP

;SHRINK SIZE OF LIST
;ADDRESS OF ARGUMENT LIST
;READ A RECORD FROM THE FILE
;LOOK AT STATUS CODE
; SUCCESS

GETERR:

LIST:

.WORD
.WORD
.WORD
.WORD

3
INRAB
ERR!
SUCCl

;NUMBER OF ARGUMENTS
;RECORD ACCESS BLOCK ADDRESS
;ERROR ROUTINE ADDRESS
;SUCCESS ROUTINE ADDRESS

1.4.2.2 RMS-11 Generates the Argument List - Your program can execute
RMS-11 file and record operation macros with the form:
$macnam block[,error[,success]]
where block is the address of a FAB for file operations or a
record operations.

RAB

for

error is the address of a completion routine you want called
the operation fails.

"''

success is the address of a completion routine you want called
if
the operation completes successfully.
Not used by file
operation macros.
The macro builds an argument list on your program's stack from the information provided.
Then it initiates the processing appropriate to
the indicated operation.
After the macro is executed,
your
program
should check the STS field of the associated block unless completion
routines were specified.

1.4.3

File Operation Macros

A file operation macro causes RMS-11 to perform an action related
to
an entire file.
The macro name indicates the type of operation performed.
The fields of the FAB associated with the macro in the ca'lling sequence identifies the file and qualifies the operation.
Table 1-7 summarizes the RMS-11 file operation macros.

1-22

Using RMS-11 in a MACR0-11 Program

/P'Nli.

Table 1-7:

RMS-11 File Operation Macros

Macro Name

Description

$CLOSE

Closes an open RMS-11 file so that your program
longer access its contents.

can

$CREATE

RMS-11 creates and opens an RMS-11 file as described
the associated FAB and XABs, if any.

$DISPLAY

Stores attributes of an existing RMS-11 file in FAB
XAB fields.

and

$ER.1~S E

Deletes an existing RMS-11 file and removes its entry(s)
from a directory.

$EX'l~END

Increases the number of blocks allocated
file.

$OPErn

Opens an existing RMS-11 file, making its contents
ilable for processing.

1.4.4

RMS-11
ava-

Record Operation Macros

After it has created or opened ~n RMS-11 file, your program can perform
record operations on it.
These operations involve the following
concepts that are explained in the RMS-11 User's Guide and Chapter 1
of this manual.
Record Access Streams
l~ile sharing
Context, Current Record, and Next Record
Synchronous and asynchronous record operations
Table 1-8 summarizes the RMS-11 record operation macros.

1.5

CREATING THE TASK

After you have written a MACR0-11 program as described
in this
chapter, you must assemble each module with the following reference in
your command string:
LB: [l,l]RMSMAC.MLB/ML
After you have assembled all modules in your program successfully, you
must link the modules with the RMS-11 routines using the Task Builder
utility supplied with your operating system.
You can link the RMS-11
routines in your
task without overlays or with disk-resident or
memory-resident overlays.
See the RMS-11 User's Guide for a discussion of these options.

File Operation Macros

1-23

NOTE
Do not use the /SQ switch with the Task Builder.
quires PSECTS to be in alphabetical order.
Table 1-8:

RMS-11 re-

RMS-11 Record Operation Macros

Macro Name

Description

$CONNECT

Establishes a Record Access Stream.

$DELETE

Deletes a record from an RMS-11
fi 1 e.

$DISCONNECT

Terminates a Record Access Stream.

$FIND

Locates a record in an RMS-11 file.

$FLUSH

Moves all data in unwritten I/O buffers to disk.

$FREE

Unlocks a bucket locked by a Record Access Stream.

$GET

Moves a record from an RMS-11 file into your program's
user buffer.

$NXTVOL

Continues processing with the next volume of
tape multivolume set.

magnetic

$PUT

Moves a record from your program's user buffer
RMS-11 file.

$REWIND

Resets a Record Access Stream's context to the logical
beginning of an RMS-11 file.

$TRUNCATE

Deletes record at the
fi 1 e.

$UPDATE

Replaces a record in an RMS-11 file with a record from
your program's user buffer.

$WAIT

Suspends processing until an RMS-11
cord operation completes.

1-24

File Operation Macros

end

Relative

RMS-11

Indexed

Sequential

asynchronous

re-

CHAPTER 2
PROVIDING BUFFER SPACE

2.1

CENTRAL BUFFER POOL

The central buffer pool must be allocated at assembly time with the
series of macros and arguments described in this section and Table
2-1. The macro series must start with the POOL$B macro and end with
the POOL$E macro.
You can use multiple buffer pool allocations among the program modules
that you link together with the Task Builder utility. The Task Builder sums the size requirements indicated by all buffer pool declarations.
Table 2-1:
Macro

Buffer Pool Declaration Macros
Description

Required

POOL$B

Beginning of buffer pool declaration

Yes

P$BDB

Number of Buffer Descriptor Blocks

Yes

P$FAB

Number of files open simultaneously

Yes

P$RAB

Number of nonindexed streams
connected simultaneously

If Sequential or
Relative files

P$RABX

Number of Indexed streams
connected simultaneously

If Indexed files

P$IDX

Number of defined keys

If Indexed files

P$BUJ£i'

Input/output buffer requirements

If no BPA or GSA

POOL$E

End of buffer pool declaration

Yes

*************
REQUIRED

*
*
*

P$BDB

*
*
*

*************

2.1.1

P$BDB

The P$BDB macro ensures that the buffer pool contains sufficient space
for
internal RMS-11 control structures known as Buffer Descriptor
Blocks (BDBs).
General form:
P$BDB nbrbdbs
where nbrbdbs 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, use the following equation:
nbrbdbs

= maxbuf + maxrel + (2 * maxidx)

where maxbuf is the count of the I/O buffers that can be used simultaneously,
that is,
the maximum number of I/O buffers
ever in use for simultaneously open files.
You calculate this value by totaling
the multibuffer
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.
RMS-11 must allocate one BDB for each I/O
buffer being used at one time.
maxrel is the maximum number of Record Access Streams ever connected simultaneously for put operations to Relative
files (whether or not an actual put operation is performed).
RMS-11 allocates one BDB for each stream connected to a Relative file.
maxidx is the maximum number of Record Access Streams ever active simultaneously for put operations to Indexed files
(whether or not an actual put operation is performed).
RMS-11 allocated one BDB for each stream connected to an
Indexed file.

2-2

The POOL Macros

*************
REQUIRED

2.1.2

* P$FAB
*
*
*
*
*
*************

P$FAB

The P$FAB macro ensures that the buffer pool contains sufficient space
for internal RMS-11 control structures related to File Access Blocks
( FABs) •
General form:
P$FAB number
where number is a numeric value or symbol representing the maximum
number of files that are open simultaneously at run time.

The POOL Macros

2-3

*************

*
*
*

P$RAB

*
*
*

*************

2 .1. 3

P$RAB

The P$RAB macro ensures that the buffer pool contains sufficient space
for internal RMS-11 control structures related to Record Access Blocks
(RABs) for Sequential and Relative files.
You can omit this pool
macro if your program does not perform record operations on Sequential
or Relative files.
General form:
R$RAB number
where number is a numeric value or symbol
representing
the maximum
number of RABs that your program connects simultaneously
to Sequential and Relative files.

2-4

The POOL Macros

*************

*
*
* P$RABX *
***************
2. 1. 4

P$RABX

The P$RABX macro ensures that the buffer pool contains sufficient
space for internal RMS-11 control structures related to Record Access
Blocks (RABs) for Indexed files.
You can omit this pool macro if your
program does not perform record operations on Indexed files.
General form:
P$RABX rabs,keysiz,nbrkeys
where rabs is a numeric value or symbol representing
the maximum
number of Record Access Streams that your program connects
to Indexed files simultaneously.
ke~ysiz

is a numeric value or symbol representing
the size,
in
bytes, of the largest key field that can be accessed by one
of the streams.

nbrkeys is a numeric value or symbol representing
the number of
keys that can change values during an update operation on
an Indexed file.
You must specify this value whenever your
program creates or opens an Indexed file with FB$UPD set in
the FAB FAC field.
Example

The following code indicates that there will be at most one
stream connected to an Indexed file at any point during program execution.
The largest key field in any such file
is
32 bytes and no keys can change during update operations.
;BEGIN POOL DECLARATION

POOL$B
P$RABX
POOL$E

1,32

;ONE FILE AND BIGGEST KEY, NO CHANGES
;END POOL DECLARATION

'--';
The POOL Macros

2-5

*************
*
*
* P$IDX *

*************
2.1.5

P$IDX

The P$IDX macro ensures that the buffer pool contains sufficient space
for
internal RMS-11 control structures containing summary information
about an Indexed file's keys.
You can omit this pool macro
if your
program does not open Indexed files.
General form:
P$IDX number
where number is a numeric value or symbol
representing
the total
number of keys defined for all Indexed files open simultaneously.
Include all keys even if they are never used
for find or get operations.

2-6

The POOL Macros

*************

* P$BUF *
*
*
*************

2 .1. 6

P$BUF

The P$BUF macro ensures that the buffer pool contains sufficient space
for the I/O buffers required by your program.
You can omit this macro
only if you are providing private buffers for all files or a GSA routine.
General form:
P$BUF :iosi z
where iosiz is a numeric value or symbol representing the total
bytes
required
for
I/O buffers by your program.
To calculate this number,
use the following equation and round the result up to a multiple of
four.
iosiz

= strmszl + strmsz2 + •••

+ strmszn

where iosiz is the total I/O buffer requirement, and
strmszl are the I/O buffer space requirements (in bytes)
for
the
Record Access Streams associated with the file that are
strmszn active simultaneously.
You calculate the requirements for each stream as follows:
•

For Sequential files on disk:

STRMSZ = 512*MBC

•

For Sequential files on magnetic tape:

STRMSZ = BLS

where BLS is the size, in characters, of each physical block of the
magtape
file, that is, the value contained in the BLS field of the
FAB, and
MBC is the value contained in the MBC field of the
with the stream.
e

For Relative files:

RAB

associated

STRMSZ = BKS*512

where BKS is the number of blocks in a bucket of the file (from the
FAJB BKS fields).
•

For Indexed files:

STRMSZ = BKS*MBF*512

where BKS is the number of blocks in the largest bucket of the file
(selected from the FAB BKS and the Allocation XAB BKZ fields), and
MBF is the value contained in the MBF field of the
with the stream.

RAB

associated

The POOL Macros

2-7

2.2

GET SPACE ROUTINE

A Get Space routine gives you complete control over the allocation of
buffer space in your task. A single GSA routine serves all files used
by the program.

RMS-11 uses the GSA routine when it requires or releases space.
When
RMS-11 requests space,
it expects one of two outputs from your
routine:
•

the low-byte address of a contiguous block of bytes at least as big
as that requested.

•

an error indication that space is not available.
RMS-11 issues
ER$DME message and returns control to the program.

When RMS-11 releases space, it expects no output from your
routine;
it assumes that the release of space was successful if the routine
terminates successfully.
NOTES
•

Your routine must start on a word boundary: precede the
label defining
the routine's starting address with a
.EVEN directive.

•

RMS-11 trusts your routine:
it performs no parameter
checking when the routine finishes and therefore can be
lead into an error or even fatal situation if the routine
did not allocate space pr~perly.

2.2.1

Specifying a Routine

You can specify the starting address of your GSA routine at assembly
time or at run time.
Either way, your routine is used only when the
internal address maintained by RMS-11 is not zero.
Your program can
also query RMS-11 at run time for the Get Space Address it is using.

2.2.1.1

Specifying a Get Space Address at Assembly Time -

General form:
GSA$

label

where label is the name of your GSA routine as specified in the
field of a source line and followed by a colon.
Example

GSARTN:
RTS

GSA$

GSARTN

;

2-8

Get Space Routine

label

2.2.1.2

Specifying a Get Space Address at Run Time -

General form:
$SETGSA argument
where argument is suitable as an operand for a MOV instruction. Where
you use label with the $GSA macro, you use #label with
the $SETGSA macro.
You cannot use R6 as an argument;
the assembler returns the error message:
.ERROR
Example

R6 MUST BE RO - RS;

GSARTN:
RTS

$SETGSA #GSARTN

'--"

Example

$SETGSA RS

Example

$SETGSA 10 (SP)

Example

$SETGSA 10 (R 3)

2. 2.1. 3

Retr:ieving a Get Space Address at Run Time -

Gener ail form:

RMS-11 sets general register RO equal to the Get Space Address it has
stored
internally.
If you have not executed a GSA$ or $SETGSA macro,
this value is O.

'-"'

2.2.2

Interfaces to Routines

The following subsections describe the interfaces between RMS-11 and
your GSA routine as well as the format of RMS-11 pool block headers.
RMS-11 sets a value in general register 2 (R2)

to indicate whether:

•

space should be allocated for an operation (R2 = 0)

•

space is being returned after an operation (R2

<> 0)

The GSA routine is analogous to the $RQCB/$RLCB request and
release
core blocks routine as far as RMS-11 is concerned;
the interfaces are
identical.
See also "Comments" below.

Get Space Routine

2-9

2.2.2.1 RMS-11 Request For Space - RMS-11 calls the routine with
following inputs:

the

RO = address of RMS-11 Pool List Head
Rl

= amount of space requested (in bytes)

RMS-11 expects the following outputs from the user routine:
If C-bit = O, all bytes requested have been allocated and
RO = address of allocated block
If C-bit

= 1, space was not available

General registers R3, R4, RS, and R6 and the stack must contain the
same values when the user routine finishes as they did when it was
called.

2.2.2.2 RMS-11 Release Of Space - RMS-11 calls the routine
following inputs:
RO

with

the

= address of RMS-11 Pool List Head Block

Rl = size in bytes of block being released
~.

R2 = address of block being released
No outputs are expected:
the user routine must complete the release;
however, general registers R3, R4, RS, and R6 and the stack must contain the same values when the routine finishes as they did when it was
called.

2. 2. 2. 3 RMS-11 Pool Block Header Formats - The RMS-11 buffer pool
is
actually subdivided into pools for each of the different sized internal structures that RMS-11 must maintain:
Buffer Descriptor Blocks
Key Descriptor Blocks
Internal FABs and RABs
I/O Buffers
Key Buffers
Each of these pools is described with a Pool List Head that points
the first free contiguous block of bytes within the pool.

Within all pools, space is divided into contiguous sections of bytes
called blocks.
Each block starts with a block header containing a pointer to the next free block in the pool and its own size in bytes.
Each pool is therefore accessed via the Pool List Head
(which points
to the first
free block), then via a linked series of block headers
2-10

Get Space Routine

(which point to the next free block as well as tell how many bytes are
in the block) •

RMS-11 Pool List Head Block:

----------- 0 <-- (RO)
value
------------ 2
0

·----------- 4

.......,..
.

•

if value = O, there is no available space left
cribed by this List Head

•

if value
he.ad er

<> 0, value points

the

first

the

pool

des-

available

pool

block

RMS-11 Pool Block Header:

-----------

()

value
------------ 2

size

----------- 4
where value is either zero (0) or not:
•

if value = O, this is the last available block in
pool

this

•

if value
block

<> 0, value po in ts to the next available

pool

size is the size in bytes of
:four-byte header

2.2.3

this

pool

block

including

the

Comments

•

You must write the GSA routine and include it in the program.
referenced routine is NOT part of RMS-11.

•

Your routine does not have to use the RMS-11 Pool List Head
but is responsible for its upkeep if it does.
Get Space Routine

The
Block,

2-11

•

If your routine does not allocate enough space for the
impending
operation, but signals RMS-11 that it has, the operation will fail
in an unpredictable manner.

•

Since your own routine could fail to allocate enough space and signal such failure to RMS-11, causing a dynamic memory error, your
program should check for the ER$DME error code after every file and
connect operation.

•

Your routine could utilize the system routines $RQCB and
accomplish the required functions, as follows:
GSARTN: TST
BNE
JMP

2$: JMP

R2
2$
$RQCB
$RLCB

$RLCB

CHECK RMS-11 REQUEST
;
;

RMS-11 WANTS MORE SPACE
RMS-11 WANTS TO RETURN SPACE

The JMP instruction allows the system routine to return directly to
RMS-11..
•

Your routine, when requested to allocate space, could use $RQCB as
a subroutine (via JSR) to check if enough space is currently available:
if it is, $RQCB allocates it, returning with the C-bit = O
if it is not ($RQCB fails;

*
*

C-bit = 1), your routine could:

extend the task
cannibalize other pools

then allocate space out of the new room, set RO as a pointer
the allocated buffer, and return to RMS-11.
•

The space allocation and release procedures used by your routine
must be symmetrical. For instance, the system routines $RQCB and
$RLCB round all sizes up to a multiple of four bytes;
these routines are symmetrical in that respect.
If your routine employs one
of these procedures, but not the other, the substitute must conform
to this rounding standard.

2-12

Get Space Routine

~f'T:d\

CHAPTER 3
FILE ACCESS BLOCK

The initialization macros (this chapter) and the field access macros
(Chapte!r 7) are provided so that you do not have to know the specific
position and to a large extent, the size of each field in a FAB.
You
can, therefore, treat the fields as logical entities.
It is also possible that the positions and sizes of the fields will change from
release to release of RMS-11.
However, you can determine the position of any field in a
FAB as an
offset from the FAB's starting address.
RMS-11 represents these offset values with symbols in one of the following forms:
•

O$fnm
where fnm is the three-letter name of a one-byte or one-word field;
fnm
is the name used to reference the field in the initialization
and field access macros.
Example

•

O$STS for the status code field

O$fnmx
where fnm is the name of a multi word field;
fnm is the name used
to
reference the field in the initialization and field
access macros.
x is a number associated with an individual word
field, from 0 through the end of the field.
Example

the

O$ALQO for less significant word and Q$ALQ1 for the
significant word in the ALQ field

The values of these symbols can be found in the symbol table of an assembly listing file for any module containing the FAB.

Table 3-1:
Field
Name

Field
Size

ALQ
BID
*BKS
BLN
*BLS
BPA
BPS
CTX
*DEQ
DEV
DNA
DNS
FAC
FNA
FNS
FOP
*FSZ
!FI
LCH
*MRN
*MRS
NAM
*ORG
*RAT
*RFM
RTV
*RTV
SHR
STS
STV

2W
lB
lB
lB
lW
lW
lW
lW
lW
lB
lW
lB
lB
lW
lB
lW
lB
lW
18
2W
lW
lW
18
18
18
18
18
18
lW
lW
lW

XAB

File Access Block Fields
Default
0

N/A
1 record
N/A
0
0
0
0
0

N/A
0

0
FB$GET
0
0
0
0

N/A
0

0
0

FB$SEQ
0

FB$VAR
0
0
0

N/A
N/A
0

Description
Size of file
FAB identifier
Bucket size
RAB length
Block size
Location of private I/O buffer
Size of private I/O buffer
Available to user
Automatic extension quantity
Device characteristics
Location of filespec defaults
Size of filespec defaults
Types of record operations
Location of filespec
Size of filespec
File processing options
Size of fixed area for VFC
Pointer to IFAB
Logical channel
Maximum Record Number
Maximum Record Size
Pointer to NAM Block
File organization
Record attributes
Record format
Window size
Cl ustersi ze
File sharing
Completion code
More error information
Pointer to first XAB

*File attribute

3-2

File Access Block (FAB):

Introduction

*************
*
*

ALQ

*
*
*************

3.1

J~LQ

The two-word Allocation Quantity (ALQ) field contains the size
(allocation quantity) of a disk file, in blocks.
RMS-11 ignores the field
for magnetic tape files.

3. 1. 1

Use

Input to:
:$CREATE
You set the ALQ field equal to the number of
allocated in the initial extent of the file.

blocks

:$EXTEND
You set the ALQ field equal to the number of
added to the file.

blocks

Output from:
:$OPEN
RMS-11 sets the ALQ field equal to the virtual block number
of the last block in the existing file;
this is also the
number of blocks in the file.
RMS-11 obtains this information from the file attributes.
RMS-11 updates attributes
during $CREATE and an implicit or explicit file extension.
RMS-11 uses only the attributes for this information: any
blocks allocated to the file by non-RMS-11 tasks is essentially invisible to RMS-11;
however, when RMS-11 extends
the file, those blocks quickly satisfy the request.
:$EXTEND
RMS-11 sets the ALQ field equal to the number of blocks that
were added to the file.

3.1.2

Input Values

$CREA rE
1

MINIMUM

= O, meaning that the actual size of the file, when it is
created, depends on the file organization:
•

Sequential files are created with four blocks.

File Access Block (FAB):

ALQ

3-3

•

Relative and Indexed files are created
allocation four times bucket size.

with

MAXIMUM = number of free blocks on the device containing the
file;
specifying a larger value results in error code
ER$FUL

$EXTEND
MINIMUM

= 1, meaning that one block should be added to

MAXIMUM

= number of blocks on the

the file
(although a zero extent is possible, it is not logical)

device containing the file;
specifying a larger value results in error code ER$FUL

For Relative and Indexed files, RMS-11 rounds values up to multiple of
bucket size.
A value can be set in the field with the initial i za ti on macro
below or with the $STORE field access macro (see Chapter 7).

3.1.3

shown

..-...,

Initialization and Default

Macro takes the form:
F$ALQ numeric

where numeric is a number of blocks as discussed under "Values."
If there is no initialization macro, ALQ = O.

3. 1. 4

Comm en ts

If Allocation XABs are linked to the FAB, the create and extend operations ignore the FAB ALQ field and obtain allocation quantities from
the XABs; see Chapter 8. However, the open operation works as described.

3-4

File Access Block (FAB):

ALQ

*************
*
*

*
*

BID

*************

3.2

BID

The FAB$B macro sets the one-byte Block Identifier (BID) field to
File A.ccess Block identifier, with the symbolic value of FB$BID.

the

CAUTION
DO NOT CHANGE THE BID FIELD.

3.2.1

Use

Before RMS-11 uses a FAB during a file operation, it verifies that the
block is a valid FAB; one of the checks examines the BID field.
If
this field does not contain the proper code, RMS-11 aborts the operation with an ER$FAB error code.

File Access Block (FAB):

BID

3-5

*************

*
*
BKS
*
*
***************

FILE ATTRIBUTE

3.3

BKS

The one-byte Bucket Size (BKS) field contains the size of a bucket, in
disk blocks, for a Relative or Indexed file.
The field has no meaning
for Sequential files.

3.3.1

Use

Input to:
$CREATE
You set the BKS field equal to the number of disk blocks in
a bucket for the file to be created, if the ORG field contains either FB$REL or FB$IDX*.
Output from:
$OPEN
RMS-11 sets the BKS field equal to the bucket size established for the file when it was created, if the ORG field
RMS-11 obtains the
incontains either FB$REL or FB$IDX*.
formation from the file attributes.

3.3.2

Input Values

MINIMUM = O, meaning that RMS-11 calculates a size so
contains at least one record.

that

bucket

MAXIMUM - number of blocks allowed by the operating system (specifying
a larger value results in error code ER$BKS):
!AS = 32 blocks
RSTS/E = 15 blocks
RSX-llM = 32 blocks
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

*If the file is Sequential, RMS-11 ignores the
and sets it to zero during $OPEN.

3-6

File Access Block (FAB):

BKS

field

during

shown

$CREATE

3.3.3

Initialization and Default

Macro takes the form:
F:$BKS numeric
If there is no initialization macro, BKS = minimum number of blocks to
contain one record.

3.3.4

Comments

•

If Allocation XABs are linked to the FAB, the create and extend operations ignore the FAB BKS field and obtain bucket size(s) from
the XAB(s);
see Chapters 5 and 8.

•

See the RMS-11 User's Guide for a discussion on bucket sizes.

•

Records may not span bucket boundaries.

File Access Block (FAB):

BKS

3-7

*************

BLN
*
*
***************

3. 4

BLN

The FAB$B macro sets the one-byte Block Length (BLN} field to the File
Access Block length, with the symbolic value of FB$BLN.
CAUTION
DO NOT CHANGE THE BLN FIELD.

3.4.1

Use

Before RMS-11 uses a FAB during a file operation, it verifies that the
block is a valid FAB; one of the checks examines the BLN field.
If
this field does not contain the proper code, RMS-11 aborts the operation with a ER$BLN error code.

3-8

File Access Block (FAB):

BLN

*************
FILE ATTRIBUTE

3. 5

*
*
*
*
*************
*

BLS

The one-word Block Size (BLS) field contains the physical block size*
in characters for a Sequential file stored on MAGNETIC TAPE only.

3.;5.1

Use

Input to:
~>CREATE

You set the BLS field equal to the number of characters per
physical block in the magtape file to be created.
RMS-11
rounds this number up to the next multiple of four before it
creates the file and sets up an I/O buffer.
Output: from:
~>OPEN

RMS-11 sets the BLS field equal to the size of the physical
blocks in the'file existing on magtape.
RMS-11 obtains the
information from the file label on tape.
If the information
is not in the label, RMS-11 uses the default block size of
the device.

"-""

3.5.2

Input Values

If you intend to use magtape to transfer data to a non-PDP-11 computer
system, note the following:
•

If the destination is another DIGITAL system, block size should
less than or equal to 512 characters.

•

If the destination is a non-DIGITAL system, block
less than or equal to 2048 characters.

size

should

*A block on magnetic tape is the data between interblock gaps.
block
size is expressed in characters;
the representation of a character
on tape is determined by the tape formatting standard.

File Access Block (FAS):

BLS

3-9

MINIMUM - O, at run-time RMS-11 interprets a value of 0 as the operating system default:
in all systems covered by this
manual, the default is 512 characters.
- 18, the smallest valid block size allowed by magtape
driver software

device

MAXIMUM - 8192 characters
A value can be set in the field with the initialization macro shown
or with the $STORE field access macro (see Chapter 7).

3.5.3

Initialization and Default

Macro takes the form:
F$BLS numeric
If there is no initialization macro, BLS = o.

3-10

File Access Block (FAB):

BLS

below

*************

*
*
BPA
*
*
***************
3.6

BPA

The one-word Buffer Pool Address (BPA) field points to an area in your
program set aside for use as an I/O buffer for all Record Access Streams connected to the file represented by the FAB.
If the address is
zero, you are allocating
the I/O buffer
in some other way (see
Chapters 1 and 2).

3.6.1

Use

Input to:
~~CREATE/$0PEN

•

If you want to specify a private buffer for the current
file access
(open to close), store the buffer's address
in the BPA field before you open the file;
also store
the size of the buffer in the BPS field.

•

If you are not using a private buffer, ensure that the
BPA field
is zero;
otherwise,
RMS-11 interprets the
value in the field as an address and
tries to
use the
buffer indicated:
the results are unpredictable.

Output from:
$CLOSE
RMS-11 sets the BPA field equal to
the address of
private buffer pool it is returning for your use.

3.6.2

the

Input Values

BPA must contain either:
•

zero (0) = there is no private buffer for this file;
all space is
allocated by RMS-11 from the central pool or by your GSA routine

•

address of the first byte of a private buffer for
buffer must begin on a word boundary

the

file;

the

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

shown

File Access Block (FAB):

BPA

3-11

3.6.3

Initialization and Default

Macro takes the form:
F$BPA label
If there is no initialization macro, BPA =

3.6.4

Comments

•

If you are using a private buffer for the file's I/O buffer, you
still have to allocate space in the central buffer pool for the
internal structures (BDBs, IFAB, and so on)
associated with the
file;
see Chapter 2.

•

Once you have assigned a private buffer to a
file in a
FAB and
opened that file,
you cannot use that space until the file is
closed.

3-12

File Access Block (FAB):

BPA

*************

BPS

*
***************
*

3. 7

BPS

The one-word Buffer Pool Size (BPS) field contains the size, in bytes,
of the private buffer indicated by the BPA field.
RMS-11 uses this
value to calculate the ending address of the private buffer.
CAUTION
RMS-11 does no further checking of the memory area defined
by the FAB BPA and BPS fields.
RMS-11 uses all the space
allotted if it needs it.

3.7.1

Use

Input to:
$CREATE/$0PEN
If BPA is equal to zero, RMS-11 ignores the BPS field;
if
BPA is not equal to zero, that is, you are providing a private buffer, you must set the BPS field equal to size of
that buffer in bytes.
Output from:
$CLOSE
RMS-11 sets the BPS field equal to the size of
buffer it is returning for your use.

3.7.2

the

private

Input Values

BPS must contain either:
•
•

any value* if the BPA field is zero
size of the private buffer for the file, in bytes, as a multiple of
tWC>

To calculate the size of the private buffer, use the equation:
BPS= strmszl + strmsz2 + •••

+ strmszn

*Recommended value is the default, zero.
File Access Block (FAB):

BPS

3-13

where BPS is the size of the private buffer,
strmszl are the I/O buffer space requirements
(in bytes)
for
strmsz2 the Record Access Streams associated with the file that
are active simultaneously.
You calculate the requirestrmszn ments for each stream as follows:
For Sequential files on disk:

strmsz = 512*MBC

For Sequential files on magnetic tape:

strmsz

= BLS

where BLS is the size, in characters, of each physical block of the magtape file, that is,
the value contained in the BLS field of
the FAB, and
MBC is the value contained in the MBC field of
the RAB associated with the stream.
For Relative files:

strmsz = BKS*512

where BKS is the number of blocks in a bucket of the
file (from the FAB BKS fields).
For Indexed files:

strmsz

= BKS*MBF*512

where BKS is the number of blocks in the largest
bucket of the file (selected from the FAB
BKS and the Allocation XAB BKZ fields),
and
MBF is the value contained in the MBF field of
the RAB associated with the stream.
A value can be set in the field with the
initialization
below or with the $STORE field access macro (see Chapter

3.7.3

Initialization and Default

Macro takes the form:
F$BPS numeric
If there is no initialization macro, BPS

3-14

File Access Block (FAB):

BPS

= O.

macro
7~.

shown

'-'

3.7.4

Examples

INBUF:

.EVEN
.BLKB

4096.

MASTER: FAB$B

F$BPA
F$BPS

INBUF
4096

FAB$E

File Access Block (FAB):

BPS

3-15

*************

*
*
*

CTX

*
*
*

*************

3.8

CTX

The one-word User Context (CTX) field is not used by RMS-11,
but is
made available to you to contain any information you want associated
with the file during run time.

3.8.1

Use

Anything you want.
For example, you might use the CTX field
municate with a common completion routine.

3.8.2

com~,

Input Values

Anything you want, as long as it fits in 16 bits.
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.8.3

shown
~.

Initialization and Default

Macro takes the form:
F$CTX argument
where argument is any value you want.
If there is no initialization macro, CTX = O.

3-16

File Access Block (FAB):

CTX

*************
FILE ATTRIBUTE

3.9

*
*

*
*
*
*
*************
DEQ

DEQ

The one-word Default Extension Quantity
(DEQ)
field contains the
number of blocks RMS-11 requests whenever it automatically extends the
file (opposed to the explicit extend operation).
RMS-11 requests additional
blocks from the operating system* whenever a task attempts a
put or update operation and there is not enough room in the file represented by the FAB to complete the operation.
For Relative and Indexed files, RMS-11 rounds DEQ up to the nearest multiple of bucket
size before requesting the extension.

3.9.1

Use

Input to:
$:CREATE
You set the DEQ field equal to the number of blocks that
should be requested in each automatic extension of the file
to be created.
$:OPEN
You set the DEQ field equal to the number of ·blocks to be
used by RMS-11 as a temporary default extension quantity
is not
until the file
is closed;
the
file attribute
changed.
Output from:
$;OPEN
If the DEQ field is zero, RMS-11 sets it equal to the number
of blocks established as the default extension quantity when
the file was created.

3.9.2

Input Values

Default extension quantity should be a multiple of bucket size for Relative and Indexed files.
MINIMUM = O, meaning that whenever RMS-11 has to ex.tend the
file,
it
requests five blocks for Sequential files and four times
*Automatic extension can fail;

see "Comments."

File Access Block (FAB):

DEQ

3-17

bucket size for Relative and Indexed files.
MAXIMUM = 65,535 blocks
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.9.3

shown

Initialization and Default

Macro takes the form:
F$DEQ numeric
If there is no initialization macro, DEQ

3.9.4

= O.

Comments

•

If Allocation XABs are linked to the FAB, RMS-11 uses the FAB DEQ
value as a
file default extension quantity, substituting it whenever an area has to be extended automatically and the XAB DEQ
field for that area is zero.

•

Automatic extension can fail for at least
there might be others:

the

following

reasons;

Operating system is RSTS/E and file is:
contiguous; error code = ER$PRV
shared;
error code = ER$PRV
No more room is available on the storage device;
ER$FUL
•

•

error

code

On the RSTS/E operating system,
file allocation is done
in
clusters;
see the RMS-11 User's Guide for a discussion of the interaction between clusters and default extension quantity.
See the RMS-11 User's Guide for a discussion of
quantity and its optimization.

3-18

File Access Block (FAB):

DEQ

default

extension

,~1

*************
*
*

DEV

*
*************

3.10

DEV

The one-byte Device Characteristics (DEV) field contains a bit string
indicating
the generic characteristics of the device containing the
file represented by the FAB.

3.10.JL
~

Use

Output from:
~?CREATE/$0PEN

RMS-11 sets the field equal to the appropriate device indicator.
You can use field access macros (see Chapter 7) to
examine the field.

'-"'

3.10.2

Output Values

The DEV field contains one or more of the following symbolic values:
FB$CCL

Carriage control device, such as printer or terminal

FB$MDI

Multiple-directory-structured device, such as a disk with
a Master File Directory and at least one User File Directory

FB$REC

Unit record device, such as a terminal or line printer;
all
unit record devices are considered to be Sequential
in nature

FB$SDI

Single-directory device, such as a disk with a
Master
File Directory, but no User File Directories present

FB$SQD

Sequential, block-oriented device, that is, magnetic tape

FB$TRM

Terminal device with keyboard and hard- or soft-copy output

File Access Block (FAB):

DEV

3-19

*************

*
*
DNA
*
*
***************
3.11

DNA

The one-word Default Name String (DNA) field points to an ASCII string
containing the program-specific defaults for
file specifications.
During the file open process, if the file name string indicated by the
FNA field
is not a complete file specification, RMS-11 examines the
DNA field.
If it is not zero, RMS-11 uses the string
indicated to
supply the missing components.
If DNA is zero, or not all the defaults are supplied by the DNA string,
RMS-11 uses the system defaults.

3.11.1

Use

Input to:
$CREATE/$0PEN

3.11.2

•

If you want to specify a default name string for a
file
operation, store the string's address in the DNA field
before you initiate the operation; also store the size
of the string in the DNS field.

•

If you are not using a default name string, ensure that
the DNA field is zero; otherwise, RMS-11 interprets the
value in the field as an address and tries to use the
string indicated:
the results are unpredictable.

Input Values

The DNA field must contain either:
•

zero (0) = there is no default name string

•

address of the default nam~ string. This string may contain values
for one or more of the following file specification components:
device
account
file name
file type
f.ile extension
version number

protection code

3-20

File Access Block (FAB):

DNA

,.~,

The string must be written in ASCII notation,
.ASCII/.ASCIZ MACR0-11 directive.

that

is,

with

A value can be set in the field with the
initialization macro
below or with the $SET field access macro (see Chapter 7).

3.11.3

the
shown

Initialization and Default

Macro takes the form:
Ei'$DNA label
If there is no initialization macro, DNA

3.11.4

= O.

Examples

To set up a default device specification:

ANYFAB: FAB$B
F$DNA
F$DNS

DEF DEV
3

FAB$E
DEFDEV: .ASCII /SY:/

3 .11. ~>
'-"''

Comments

•

The d efa ult name string may include logical names.

•

RMS-11 checks the DNA string validity during each create and open
operation.
RMS-11
returns an error if it finds a bad component
even if the FNA string supplies a valid value for that component.

•

See also FNA discussion about file specifications, parsing sequence
on RSTS/E, and so on.

File Access Block (FAB):

DNA

3-21

*************

*
DNS

*************

3.12

DNS

The one-byte Default Name String Size (DNS) field contains the size,
in bytes, of the default name string indicated by the DNA field.

3.12.1

Use

Input to:
$CREATE/$0PEN
if
If the DNA field is zero, RMS-11 ignores the DNA field;
the DNA field is not zero, that is, you are providing a dethe
fault name string, you must set the DNS field equal
to
size of that string in bytes.

3.12.2

Input Values

The DNS field must contain either:
•

any value*, if the DNA field is zero

•

the size of the default name string, in bytes, with
255

maximum

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.12.3

Initialization and Default

Macro takes the form:
F$DNS numeric
If there is no initialization macro, DNS = O.

*Recommended value is the default, zero.
3-22

File Access Block (FAB):

DNS

shown
~

*************
*
*

*
*

FAC

*
*

*************

3.13

J~AC

The one-byte File Access (FAC) field contains a bit string
indicating
the types of record operations that may be performed on the file represented by the FAB.
This declaration enables RMS-11 to set up
transfer vectors to the appropriate RMS-11 routines.
RMS-11 rejects
any record operation that was not specified in the FAC field when the
file is opened (error code ER$FAC).

3.13.1

Use

·."-"
Input to:
$CREATE
You set the FAC field to indicate all operations your program performs on the file during the current access (open to
close).
NOTE
The FAC field must contain at least FB$PUT.

$OPEN
You set the FAC field to indicate all operations your program performs on the existing file during the current access
( open to c 1 o s e) •

3.13.2

Input Values

FAC may contain one or more of the following symbolic values:
FB$DEL

$DELETE operations

FB$GET

$GET and/or $FIND operations

FB$PUT

$PUT operations

FB$REA

$READ Block I/O operations (see Chapter 9)

FB$TRN

$TRUNCATE operations:

valid for Sequential files only

File Access Block (FAB):

FAC

3-23

FB$UPD

$UPDATE operations

FB$WRT

$WRITE Block I/O operations (see Chapter 9)

If you want to specify more than one operation, you
the values using an exclamation point (!).

must

concatenate

A value can be set in the field with the initialization macro
below or with the $SET field access macro (see Chapter 7).

3.13.3

shown

Initialization and Default

Macro takes the form:
F$FAC symbolic[!symbolic ••• ]
If there is no initialization macro, FAC = FB$GET.

3.13.4

Comments

•

If the file is an ANSI magtape file, RMS-11 automatically positions
the tape at the end of the file when it is opened, unless the FOP
field contains FB$NEF.

•

Since the FAC field is a bit string, values cannot be added to the
field with the $STORE field access macro.
You should use the $SET
field access macro (see Chapter 7). However, you use the $STORE
macro to (re)set all bits in the field.

•

If you specify FB$DEL, FB$TRN, and/or FB$UPD, but do not include
FB$GET, RMS-11 activates that capability anyway.
Delete, truncate,
and update operations must be preceded by a successful find or get
operation.

3-24

File Access Block (FAB):

FAC

*************

*
*
FNA
*
***************

3.14

FNA

The one-word File Name String Address (FNA) field points to the ASCII
string
that is the file specification of the file represented by the
FAB.
RMS-11 examines the string indicated, if FNA is not zero.
If
any file specification components are missing from the string, or FNA
is zero, RMS-11 checks the DNA field.
If DNA is not zero, RMS-11 uses
the string indicated to fill in the filespec;
if DNA is zero, or the
string indicated is not sufficient, RMS-11 inserts system default values into the file specification.
Then it passes the complete filespec to the operating system to either open or create,
then open, a
file by that name.

3.14.1

Use

Input to:
~iCREATE/$0PEN

3.14.2

•

If you want to specify a file specification for a
file
operation, store the specification's address in the FNA
field before you initiate the operation; also store the
size of the specification in the FNS field.

•

If you are not using a file specification*, ensure that
the FNA field is zero; otherwise, RMS-11 interprets the
value in the field as an address and tries to
use the
string indicated:
the results are unpredictable.

Input Values

FNA must contain either:
•

zero (0) = there is no file specification

•

address of file specification string for the file

The string must be written in ASCII
.ASCII/.ASCIZ MACR0-11 directive.

notation,

that

is,

with

the

*If you are using all defaults, program and/or system, to define the
file specification, or file ID to identify the file without a file
specification (see Chapter 8).
File Access Block (FAB):

FNA

3-25

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.14.3

shown

Initialization and Default

Macro takes the form:
F$FNA label
If there is no initialization macro, FNA

3.14.4

= O.

Comments

•

File specifications contained in the FNA-indicated buffer must conform to operating system standards.
See the RMS-11 User's Guide,
Appendix A, for RMS-11 restrictions on the operating systems and
operating system restrictions on RMS-11.

•

On RSTS/E, RMS-11 parses file specifications in the
quence.
RMS-11:

following

se-

fields

the

Places the string described by the DNA and DNS
FIR QB.

Issues a .FSS call on the string described by the FNA and FNS
fields.
In the process,
the monitor merges the FNA and DNA
strings in the FIRQB, overriding only those components already
existing
in the FNA string.
The monitor also translates logical names.

Checks if the FSS processing encountered an RMS-11 restriction
on RSTS/E file specifications, such as switches or an equal
sign (=).

Examines the resultant file specification for device and account components.
If these components are missing, RMS-11 obtains the system defaults for those fields and puts them into
the file specification.

Examines the resultant file specification.
If a component is
missing,
returns the appropriate error code;
if there are too
many components, returns the error code ER$XTR.

3-26

File Access Block (FAB):

FNA

*************

FNS
*
*
***************

3.15

FNS

The one-byte File Name String Size (FNS) field contains the size,
bytes, of the file specification indicated by the FNA field.

3.15.1

Use

Input to:
$CREATE/$0PEN
If the FNA field is zero, RMS-11 ignores the FNA field;
if
FNA is not zero, that is, you are providing a file specification, you should set the FNA field equal to the size of
that string in bytes.

3.15.2

Input Values

The FNA field must contain either:
•

any value* if FNA is zero

•

size of the file specification string, in bytes, with a maximum
255

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.15.3

shown

Initialization and Default

Macro takes the form:
1~$FNS

numeric:

If there is no initialization macro, FNS = O.

*Recommended value is the default, zero.

File Access Block (FAB):

FNS

3-27

*************

*
*
FOP
*
*
***************
3.16

FOP

The one-word File Processing Options (FOP) field contains a bit string
indicating the file processing options that you have selected for the
file represented by the FAS.

3.16.1

Use

Input to:
$CREATE
You set the FOP field to indicate the processing option(s)
you want applied to the new file until it is closed.
$OPEN
You set the FOP field to indicate the processing options you
want applied to the existing file until it is closed.
$EXTEND
You set the FOP field equal to FS$CTG if you want the file
extended contiguously, that is, the new blocks allocated in
such a manner that they are contiguous with the present extent of the file.
$CLOSE
You set the FOP field equal to FS$RWC if you want a magnetic
tape file rewound when the file is closed, but did not include the option when the file was opened.

Output from:
$OPEN
If the file is contiguous, RMS-11 sets the FOP field equal
to FS$CTG; otherwise, the field is zero.
You can test for
this value with field access macros (see Chapter 7).

3.16.2

Input Values

The FOP field may contain
values:
FS$CTG

3-28

one

the

following

symbolic

RMS-11 is to allocate contiguously the amount of space
specified
in the FAS ALQ field.
Used on $CREATE and
$EXTEND only.

File Access Block (FAB):

FOP

FB$DFW

directs RMS-11 to defer writing the I/O buffer out to a
file after a $DELETE, $UPDATE, or $PUT operation. Under
default conditions, RMS-11 causes a physical transfer of
data from your program to the file as part of any of the
above record operations--for Relative and Indexed files
only. However, if you specify FB$DFW in the RAB when you
initiate one of these operations, RMS-11 does not automatically write out the buffer.
Instead, it defers the
disk write until it requires the buffer for some other
purpose, such as reading a different bucket into memory
or the buffer is full.
Since this is similar to the default condition for Sequential files, specifying Deferred
Write does not affect record operations on Sequential
:Eiles.

FB$DLK

RMS-11 unlocks the file so that it is available for access if this program does not close it in a normal
manner.
Used on
$CREATE
and
$OPEN
only.
See
"Comments."

FB$FID

RMS-11 uses the value in the NAM FID field to open or
erase the file (see Chapter 8). Used on $OPEN and $ERASE
only~

FB$MKD

RMS-11 creates this file, then deletes it when
is closed. Used on $CREATE only.

FB$NEF

RMS-11 does not position the ANSI magnetic tape to the
end of the file even though the FAB FAC field contains
FB$PUT.
Used on $OPEN only.

FB$POS

RMS-11 positions the magtape to the point immediately
after the most recently closed file before it creates the
file specified by this FAB; all subsequent files on the
tape are logically deleted. ·If FB$POS is not specified,
RMS-11 positions the magtape at the end of the last file
on the volume. However, the FB$RWO option overrides the
FB$POS option. Used on $CREATE only.

FB$RWC

RMS-11 requests the operating system to rewind the magtape when the file is closed. If FB$RWC is set when the
file is opened ($CREATE or $OPEN), RMS-11 does not notice
its absence when the file is closed;
that is, you can't
undo this once specified. However, if FB$RWC was not
specified for the open, you can include it for the $CLOSE
and RMS-11 rewinds the tape.

FB$RWO

RMS-11 requests the operating system to rewind the magtape before the file represented by the FAB is created
and/or opened. Used on $CREATE and $OPEN only.

FB$SUP

RMS-11 supersedes an existing file if the file specification indicated by this FAB contains an explicit version
number.
Used on $CREATE only.

File Access Block (FAB):

the

FOP

file

3-29

FB$TMD

RMS-11 creates this file as a temporary file and deletes
it when the file is closed.
Used on $CREATE only.

FB$TMP

RMS-11 creates this file as a temporary file and does not
delete
it;
that is, RMS-11 retains the file, when it is
closed, even though it is not entered into the directory.
The FB$TMD option overrides the FB$TMP option.
Used on
$CREATE only.

If you want to specify more than one option, you must concatenate
values using an exclamation point (!).

the

A value can be set in the field with the
initialization macro
below or with the $SET field access macro (see Chapter 7).

shown

3.16.3

Initialization and Default

Macro takes the form:
F$FOP symbolic[!symbolic ••• ]
If there is no initialization macro, FOP

= O, meaning:

•

The file is created or extended noncontiguously.

•

If file is not closed normally, it remains locked (see "Comments").

•

Open operation accesses file via filespec.

•

RMS-11 positions magtape to end of the file when it opens the file.

•

RMS-11 positions magtape to end of the last file on
it creates the specified file.

•

RMS-11 does not request the operating system to rewind magtape when
the file is closed.

•

RMS-11 fails with error code ER$FEX if the filespec
explicit version number and the file already exists.

•

before

contains

RMS-11 creates a permanent file.

3.16.4
•

volume

Comments

The !AS and RSX-llM operating systems provide protection to any
file that is not closed properly* by a task that creates or opens
it:
the file is locked and not accessible by any user task until a
u t i 1 i t y (PIP ) un 1 o ck s i t •
This protection is particularly valuable for Sequential
files.
When RMS-11 opens a
Sequential file, it reads the file's attributes, including end-of-file location from
the file header
into
memory;
however, RMS-11 does not update the file header until the

3-30

File Access Block (FAB):

FOP

file is closed.
Until the file's attributes are revised on disk,
any extension of the file while it was opened (and any data added
to it) is not permanently recorded.
Therefore,
if a
Sequential
file
is not closed properly*,
all data added while it was open
could be lost if another task does access the file and make its own
revision of the file header.
These considerations do not apply to Relative and
Indexed
files.
Therefore,
they are the only files
for which the FB$DLK value
should be specified.
•

Since the FOP field is a bit string, values cannot be added to
the
field with the $STORE field access macro.
You should use the $SET
field access macro (see Chapter 7).
However, you use the $STORE
macro to (re)set all bits in the field.

*Caused by an improperly designed task, operating system collapse,
hardware malfunction.

File Access Block (FAB):

NAM 3-30.l

*************

*
*
FSZ
*
*
*
*
*************

FILE ATTRIBUTE

3.17

FSZ

The one-byte Fixed Control Area Size (FSZ) field contains the size, in
bytes, of thE~ fixed control area for Variable-with-Fixed-Control (VFC)
records in the file represented by the FAB.

3.17.1

Use

The F'SZ field is only used when a file contains (or will contain)
VFC
records.
It therefore applies only to Sequential and Relative files.
Input to:
$CREATE
You set the FSZ field equal to the number of bytes in the
fixed control area of the VFC records that will be written
into the file to be created.
Output from:
$OPEN
RMS-11 sets the FSZ field to the size of the
area established when the file was created.

3.17.2

Input Values

MINIMUM

= o, meaning that RMS-11 sets the control

area

fixed

control

size

two

bytes*

·~

= 1, the smallest fixed control area allowed
MAXIM.UM

= 255

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.17.3

shown

Initialization and Default

Macro takes the form:
F$FSZ numeric
*Compatible with FCS.
File Access Block (FAB):

FSZ

3-31

If there is no initialization macro, FSZ = O.

3.17.4

Comments

RMS-11 uses this number as the size of the buffer indicated by the RAB
RHB field.

·~

3-32

File Access Block (FAB):

FSZ

*************

*
*

!FI

*
*
*

*************

3.18

!FI

The $OPEN macro sets the one-word Internal File Identifier (IFI) field
to an address that links the FAB to the IFAB RMS-11 creates when a
file is opened. The $CLOSE macro clears the !FI field.
CAUTION
DO NOT CHANGE THE IF! FIELD.

3.18.1

Use

RMS-11 uses the address in the IF! field to
from the FAB to the IFAB.

transfer

pertinent

File Access Block (FAS):

!FI

data

3-33

*************

*
*

LCH

*
*
*

*************

3.19

LCH

The one-byte Logical Channel (LCH) field contains the number of the
logical channel through which all I/O operations between the file and
the task are performed.

3.19.1

Use

Input to:

$CREATE/$0PEN
You set the LCH field to the number of the channel the file
should be linked with until it is closed.
Each file opened
must have a unique LCH (error code ER$LBY).

3.19.2

Input Values

.~.\

MINIMUM is system-dependent
MAXIMUM is system-dependent
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.19.3

shown

Initialization and Default

Macro takes the form:
F$LCH numeric
If there is no initialization macro, LCH = O, meaning the field must
be set with the $STORE
field access macro before the file open is
attempted.

3-34

File Access Block (FAB):

LCH

3.19.4

Comments

•

Multiple Record Access Streams is a method
channel to carry multiple functions.

using

one

•

Once a logical channel is assigned to a device, no operation,
including $CLOSE, automatically deassigns the channel. The channel
remains assigned to the device until you reassign it.

File Access Block (FAB):

logical

LCH

3-35

*************

*
FILE ATTRIBUTE

*
MRN

*************

3.20

MRN

The two-word Maximum Record Number (MRN) field contains the maximum
number of records that can be written to the Relative file associated
with the FAB.
RMS-11 checks the relative record number used with each
put operation against this maximum and rejects (error code ER$MRN) any
operation with too high a number.

3.20.1

Use
~.

The MRN field is only meaningful for Relative files.
Input to:
$CREATE
You set the MRN field to the highest relative number of any
record that will (or should) be written into the file*.
If
you want no checks on relative record number, set MRN equal
to zero.

Output from:
$OPEN
RMS-11 sets the MRN field equal
when the file* was created.

3.20.2

Input Values

MINIMUM

MAXIMUM

the

value

established

meaning
that RMS-11 writes
the
MRN
v~lue
as
2,147,483,647** during
the create operation, returns
this number during an open operation, and makes no
checks on relative record numbers during put operations.

= number of records that will fit on the device

containing

the file
*Unless the FAB ORG field contains FB$REL,
RMS-11
ignores
field during $CREATE and sets it to zero during $OPEN.
**The largest possible positive value for the 32-bit field.

3-36

File Access Block (FAB):

MRN

the

MRN

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.20.3

shown

Initialization and Default

Macro takes the form:
F:$MRN numeric
If there is no initialization macro, MRN = O.

File Access Block (FAB):

MRN

3-37

*************

3.21

*
MRS
*
*
*
*************

FILE ATTRIBUTE

MRS

The one-word Maximum Record Size
(MRS)
field contains the maximum
size,
in bytes, of any record in the file associated with the FAB.
RMS-11 checks all records written to the file against this maximum and
rejects those that are too large (error code ER$RSZ).

3. 21.1

Use

Input to:
$CREATE
You set the MRS field equal to the number of bytes in:
•

all fixed-length records in the file

•

the largest variable-length or stream record that can
written to the file.

•

The variable area in the largest VFC record that can be
written to the file, that is, the number does not include
the fixed control area.

Output from:
$OPEN
RMS-11 sets the MRS field equal
when the file was created.

the

value

established

3.21.2

Input Values

MINIMUM

= O, meaning that RMS-11 makes no checks on the length of

records written to
the file via either $PUT or $UPDATE.
However, there are restrictions on the use of zero in the
MRS field;
see "Comments."

MAXIMUM -- 32767, the largest number that can be stored in the signed
two-byte field.
However, Maximum Record Size is
further limited by bucket size in Relative and
Indexed files and by task buffer space for all files.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

3-38

File Access Block (FAB):

MRS

shown

3.21.3

Initialization and Default

Macro takes the form:
F$MRS numeric
If there is no initialization macro, MRS = O.

3.21.4

Comments

A nonzero MRS field is required during the $CREATE
following situations:

operation

•

Fixed-length records (FAB RFM field = RB$FIX)

•

Relative file organization (FAB ORG field = FB$REL)

File Access Block (FAB):

the

MRS

3-39

*************

*
NAM
*
*
*
*************

3.22

NAM

The one-word Name Block Address (NAM) field points to a separately allocated Name Control Block (NAM) and thereby activates RMS-11 to use
the NAM Block when the file is opened.
See Chapter 6.

3.22.1

Use

Input to:
$CLOSE
If you have specified a valid NAM Block, RMS-11 clears the
first word of the FID field, making the field invalid for
any subsequent operations.
$CREATE
•

If you have allocated a NAM Block and want RMS-11 to set
the fields when it opens the file, you set the NAM field
equal to the address of the block.

•

If you have not allocated a NAM Block and/or you do not
want RMS-11 to fill it in during the file open procedure,
set the NAM field equal to zero; otherwise,
RMS-11
interprets the value in the field as an address and tries
to use the area indicated as a NAM Block:
if that area
is not a valid NAM Block, RMS-11 returns the error code
ER$NAM.

~
I

$ERASE

3-40

•

If you want RMS-11 to use the device and file IDs in NAM
DVI and FID fields to identify, then erase a file.
The
file ID must be valid and probably was supplied by RMS-11
during a create or open operation.
You must also set
FB$FID in the FAB FOP field.

•

If you have not allocated a NAM Block and/or you do not
want RMS-11 to use it in during the erase operation, set
the NAM field equal to zero;
otherwise,
RMS-11
interprets the value in the field as an address and tries to
use the area indicated as a NAM Block:
if that area
is
not a valid NAM Block,
RMS-11 returns the error code
ER$NAM.

File Access Block (FAB):

NAM

$OPEN

3.22.2

•

If you have allocated a NAM Block and want RMS-11 to fill
in the fields when it opens the file, you set the NAM
field equal to the address of the block.

•

If you want RMS-11 to
DVI and FID fields
file ID must be valid
during a create or
FB$FID in the FAB FOP

•

If you have not allocated a NAM Block and/or you do not
want RMS-11 to fill it in during the open operation, set
the NAM field equal to zero;
otherwise,
RMS-11
interprets the value in the field as an address and tries to
use the area indicated as a NAM Block:
if that area
is
not a valid NAM Block,
RMS-11 returns the error code
:ER$NAM.

use the device and file IDs in NAM
to identify, then open a file.
The
and probably was supplied by RMS-11
open operation.
You must also set
field.

Input Values

The NAM field must contain either:

•

zero (0) = there is no NAM Block associated with this FAB

•

address of a Name Control Block separately allocated in the program

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.22.3

shown

Initialization and Default

Macro takes the form:
l~$NAM

thE~re

label

is no initialization macro, NAM = O.

File Access Block (FAB):

NAM

3-41

*************
*
*
FILE ATTRIBUTE

ORG

*
*
*************

3.23

ORG

The one-byte File Organization (ORG) field contains an
the organization of the file associated with the FAB.

indicator

for

$CREATE
You set the ORG field to indicate the organization you
established for the file to be created.

want

3.23.1

Use

Input to:
·~

Output from:
$OPEN
RMS-11 stores in the ORG field the indicator for the organization of the existing file.
You can test this value with
field access macros (see Chapter 7).

3.23.2

Input Values

The ORG field may contain one of the following symbolic values:
FB$SEQ

Sequential file organization

FB$REL

Relative file organization

FB$IDX

Indexed file organization

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.23.3

Initialization and Default

Macro takes the form:
F$0RG symbolic
If there is no initialization macro, ORG = FB$SEQ.

3-42

File Access Block (FAB):

ORG

shown

*************

*
*
*
*
*************
*

FILE ATTRIBUTE

3.24

RAT

The one-byte Record Attributes (RAT) field contains a bit string describing
the attributes of the records in the file associated with the
FAB.

3.24.1

Use

Input to:
$CREATE
You set the RAT field to indicate the characteristics of the
records that will be stored in the file to be created.
Output from:
~;OPEN

RMS·-11 stores in the RAT field indicators of the record atYo u
tributes established for the file when it was created.
(see
can test for these values using
field access macros
Chapter 7).

3.24.2

Input Values

The RAT field may contain
values:

'-""'

one

the

following

symbolic

FB$BLK

records in the file do not cross block boundaries;
valid
only for Sequential files.
This attribute restricts record size to 512 bytes.

J?B$CR

when RMS-11 writes a record from this file to a unit record device,
that is, a terminal or printer opened as a
Sequential file, it precedes the record with a line feed
character and
follows
it with a carriage return character.
RMS-11 may or may not actually add the characters, depending on the operating system.

FB$FTN

the first byte of each record in the file contains a FORTRAN forms control character

If you want to specify more than one attribute, you
the values using an exclamation point(!).

must

File Access Block (FAB):

concatenate

RAT

3-43

A value can be set in the field with the
initialization macro
below or with the $SET field access macro (see Chapter 7).

3.24.3

shown

Initialization and Default

Macro takes the form:
F$RAT symbolic[!symbolic ••• ]
If there is no initialization macro, RAT
•

Records span block boundaries

•

No carriage or FORTRAN control

3.24.4

= O, meaning:

Comments

•

If the file associated with the FAB is a unit record device,
such
as a terminal or printer, you should put at least FB$CR in the RAT
field.

•

By default, records in all files are allowed to cross block boundaries~
Although this attribute can be restricted for Sequential
files, there seems to be little reason to do so.

•

Since the RAT field is a bit string, values cannot be added to
the
field with the $STORE field access macro.
You should use the $SET
field access macro (see Chapter 7).
However, you use
the $STORE
macro to (re)set all bits in the field.

3-44

File Access Block (FAB):

RAT

FILE ATTRIBUTE

3.25

*************
*
*
RFM

*
***************
*

RFM

The one-byte Record Format (RFM) field contains an indicator
format of the records in the file associated with the FAB.

3.25.1

for

the

Use

Input to:
~?CREATE

You set the RFM field to indicate the record format you want
established for the file to be created.
Output from:
!$OPEN

RMS-11 stores in the RFM field the indicator for the record
format of the existing file.
You can test this value with
field access macros (see Chapter 7).

3.25.2

Input Values

The RFM field may contain one of the following symbolic values:
FB$FIX

fixed-length records

FB$STM

ASCII stream record format;
valid only for disk Sequential
files.
The RMS-11 User's Guide explains how RMS-11
handles stream records.

FB$UDF

no record format is defined for the file;
valid only for
Sequential
files during create operations. When accessing a file with undefined
record
format,
your program
must use block I/O (see Chapter 9).

FB$VAR

variable-length records

FB$VFC

variable-with-fixed-control records;
Sequential and Relative files

valid only for disk

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

File Access Block (FAS):

RFM

shown

3-45

3.25.3

Initialization and Default

Macro takes the form:
F$RFM symbolic
If there is no initialization macro, RFM = FB$VAR.

"'
-;

3-46

File Access Block (FAB):

RFM

*************

*
*
RTV
*
*
***************
The meaning of the RTV field depends on your operating
section defines the field for:

system.

This

Il~S/RSX-1 lM

3.26

HTV

The one-byte Retrieval Window Size (RTV) field contains the number of
retrieval
pointers kept in memory* for the file represented by the
FAB.
Hetrieval pointers map virtual block numbers to logical block
numbers.
See Chapter 8 of the RMS-11 User's Guide for more information.

3.26.1

Use

Input to:
$CREATE/$0PEN
You set the RTV field equal to the size of window
maintained for the file until it is closed.

3.26.2

you

want

Input Values

The RTV field must contain one of the following:

'-"

•

-1 - as much of the file as possible is mapped with one window

•

a nonzero positive value, specifying the number
inters to be maintained in memory:

·- RMS-11 uses the current default value

MINIMUM
MAXIMUM

retrieval

po-

= 127

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

shown

*This set of pointers is called a "window."

File Access Block (FAB):

RTV

3-47

3.26.3

Initialization and Default

Macro takes the form:
F$RTV numeric
If there is no initialization macro, RTV

= O.

..~

""·

3-48

File Access Block (FAB):

RTV

*************

*
*
RTV
*
*
***************

FILE ATTRIBUTE

The meaning of the RTV field depends on your operating
section defines the field for:

system.

This

RSTS/E

3.27

RTV

The one-byte Clustersize (RTV) field contains the number of blocks
each cluster of the file represented by the FAB.

3.27.1

Use

Input to:
$CREATE
You set the RTV field to the clustersize
blished for the file to be created.

you

want

esta-

Output ,from:
$OPEN
RMS-11 sets the RTV field to the clustersize established for
the file when it was created.

3.27.2

Input Values

The value in the RTV field must be:
•

a positive integer

•

a power of two;

•

greater than or equal to volume* clustersize

else ER$CRE

MINIMUM = O, meaning that RMS-11 uses the volume* clustersize
MAXIMUM

= 255, meaning that RMS-11 sets clustersize to 256 blocks

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

shown

*"Volume" means the disk pack as opposed to the disk device, which has
its own characteristic clustersize.

File Access Block (FAB):

RTV

3-49

3.27.3

Initialization and Default

Macro takes the form:
F$RTV numeric
If there is no initialization macro, RTV

3-50

File Access Block (FAB):

RTV

= O.

*************

*
*

*
*
*
*************

3.28

SHR

The one-byte File Sharing (SHR) field contains a bit string indicating
the operations on the file represented by the FAB you are willing to
share with other tasks.
This sharing criterion is applied whether or
not this is the first task to access the file:
if one or more other
tasks have already opened the file to write and the SHR field
indicates no write sharing, the open operation fails;
however, if this
task is the first to open the file, specifying no write sharing, all
other tasks that indicate write operations* are denied access.
See also Chapter 2 of the RMS-11 User's Guide.

3.28.JL

Use

Input to:
~>CREATE/$0PEN

You set the SHR field to indicate the type of operations you
allow other tasks accessing the file •

.._,,.
.

3.28.2

Input Values

The SHR field may contain one of the following:
•

zero (0), meaning no write sharing;
however, other tasks may access the file for reading only (FB$GET only in the FAB ROP field)

•

FB$WRI, meaning that other tasks may access the file for write
era1tions

op-

NOTE
For Sequential files, FB$WRI can be used only when the FAC
field does NOT contain FB$PUT or FB$UPD.
If you want write
access, you cannGt allow others to have write access.

A value can be set in the field with the

initialization

macro

shown

*FB$DEL, FB$PUT, and/or FB$UPD in FAB ROP field.

File Access Block (FAB):

SHR

3-51

below or with the $SET field access macro (see Chapter 7).

3.28.3

Initialization and Default

Macro takes the form:
F$SHR FB$WRI
If there is no initialization macro, SHR = O.

3-52

File Access Block (FAB):

SHR

*************
*
*

STS
*
*
***************

'-''
3.29

STS

The one-word Completion Status Code (STS) field contains a code indicating the success or failure (and type of failure) of a file operation.
See Appendix A for symbolic and octal codes for both success
and failure of operations.

3.29.1

Use

Output from:
$CLOSE/$CREATE/$DISPLAY/$ERASE/$EXTEND/$0PEN
RMS-11 sets the STS field equal to a completion code.
You
should test this field ($COMPARE field access macro) for a
negative value after each file operation, or you can use an
error completion routine that checks the value (see Chapter
8) "

'-"'

3.29.2

Input Values

No input values;

see Appendix A for output values.

File Access Block (FAB):

STS

3-53

*************
*
*
STV
*
*
*
*
*************
3.30

!:::~

STV

The one-word Status Value (STV) field contains additional
about some error codes returned in the STS field.

3.30.1

information

Use

Output from:
$CLOSE/$CREATE/$DISPLAY/$ERASE/$EXTEND/$0PEN
RMS-11 sets the STV field whenever it has additional
information to communicate about an error. See Appendix A for
the specific errors on which the STV field
is used.
You
should check the STV field for a nonzero value whenever you
detect an error (negative value in STS field).

3.30.2

Input Values

No input values;

3-54

see Appendix A for output values.

File Access Block (FAB):

STV

*************

*
*

XAB

*
*
*

*************

3.31

XAB

The one-word Extended Attribute Block Address
(XAB)
field,
if not
zero, points to a separately allocated Extended Attribute Block (XAB)
and thereby indicates to RMS-11 that there is a chain of at least one
XAB that must be examined for input to and filled with output from a
file operation.
RMS-11 finds the other XABs in the chain,
if there
are any, via the NXT field in the XAB indicated by the FAB XAB field.

3. 31.1

Use

Input to:
$CREATE/$DISPLAY/$EXTEND/$0PEN

3.31.2

•

If you have allocated one or more XABs and want RMS-11 to
use the chain, you set the XAB field equal to the address
of the first XAB in the chain.

•

If you have not allocated an XAB and/or you do not want
RMS-11 to use it during the file open procedure, set the
XAB field equal to zero;
otherwise,
RMS-11
interprets
the val~e in the field as an address and tries to use the
area indicated as an XAB:
if that area is not a valid
XAB, RMS-11 returns error code ER$XAB.

Input Values

The XAB field must contain either:
•

zero (0) = there is no XAB associated with this FAB

•

address of an Extended Attribute Block separately allocated in
praig ram

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

3.31.3

the
shown

Initialization and Default

Macro takes the form:
E'$XAB label
File Access Block (FAB):

XAB

3-55

If there is no initialization macro, XAB

3.31.4

= O.

Comments

•

See Chapter

•

An Indexed file requires at least one XAB
Key.

3-56

for details on XABs.

File Access Block (FAB):

XAB

define

the

Primary

CHAPTER 4
RECORD ACCESS BLOCK

The initialization macros (this chapter) and the field
access macros
(Chapter 7) are provided so that you do not have to know the specific
position and to a large extent, the size of each field in a RAB.
You
can, therefore, treat the fields as logical entities.
It is also possible that the positions and sizes of the fields will change from
release to release of RMS-11.
However, you can determine the position of any field in a
RAB as an
offset from the RAB's starting address.
RMS-11 represents these offset values with symbols in one of the following forms:

•

O$fnm
where fnm is the three-letter name of a one-byte or one-word field;
fnm
is the name used to reference the field in the initialization
and field access macros.
Example

•

0$STS for the status code field

O$fnmx
where fnm is the name of a multiword field;
fnm is the name used
to
reference the
field in the initialization and field
access macros.
x is a number associated with an
individual word
field, from 0 through the end of the field.
Example

the

O$BKTO for less significant word and Q$BKT1 for the
significant word in the BKT field

The values of these symbols can be found in the symbol table of an assembly listing file for any module containing the RAB.

Table 4-1:

Record Access Block Fields

Field
Name

Field
Size

Default

BID
BKT
BLN
CTX
FAB
!SI
KBF
KRF
KSZ
MBC
MBF
RAC
RBF
RFA
RHB
ROP
RSZ
STS
STV
UBF
USZ

lB
2W
lB
lW
lW
lW
lW
lB
lB
lB
lB
lB
lW
3W
lW
lW
lW
lW
lW
lW
lW

N/A
None
N/A

4-2

N/A
0
0
0

0
0
0
0
0
0
0

N/A
N/A
0

Record Access Block (RAB):

Introduction

*************

*
*
*

.......,.,,

BID

*
*
*

*************

4.1

BID

The RAB$B macro sets the one-byte Block Identifier (BID) field to
the
Record Access Block identifier, with the symbolic value of RB$BID.
CAUTION
DO NOT CHANGE THE BID FIELD.

4.1.1

Use

Before RMS-11 uses a RAB during a record operation, it verifies that
the block is a valid RAB;
one of the checks examines the BID field.
If this field does not contain the proper code, RMS-11 terminates the
operation with a ER$RAB error code.

Record Access Block (RAB):

BID

4-3

*************

*
*
*

BKT

*
*
*

*************

4. 2

BKT

The one-byte Bucket (BKT) field contains:
•

the relative record number of the record accessed by the Record Access Stream during sequential access operations on a Relative file

•

the Virtual Block Number when the Record Access Stream is
ing Block I/O operations

4.2.1

perform-

Use

Input to Block I/O Operations:
$READ/$WRITE
You set the BKT field equal to the
block you want read or written.

number

the

virtual

Output from Relative File record operations:
$FIND/$GET/$PUT
If you have specified sequential access (RB$SEQ in the RAB
RAC field), RMS-11 sets the BKT field equal to the relative
record number of the record read or written by the operation.

4.2.2

Input Values (Block I/O only)

MINIMUM = 0
MAXIMUM = value of FAB ALQ field
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.2.3

shown

Initialization and Default

Logical for Block I/O operations only, the macro takes the form:
R$BKT numeric
If there is no initialization macro, BKT

__________________________
4-4

= O.

Record Access Block (RAB) :

BKT

*************

*
*
*

BLN

*
*
*

*************

4.3

BLN

The RAB$B macro sets the one-byte Block Length (BLN) field to the Record Access Block length, with one of the following symbolic values:
RB$BLN

= synchronous RAB

RB$BLL

= asynchronous RAB
CAUTION
DO NOT CHANGE THE BLN FIELD.

4.3.1

Use

Before RMS-11 uses a RAB during a record operation, it verifies that
the blocks is a valid RAB;
one of the checks examines the BLN field.
If this field does not contain the proper code, RMS-11 aborts the operation with a ER$BLN error code.

Record Access Block (RAB):

BKT

4-5

*************

*
*
*

CTX

*
*
*

*************
4.4

CTX

The one-word User Context (CTX) field is not used by RMS-11,
but is
made available to you to contain any information you want associated
with the Record Access Stream during run time.

4.4.1

Use

Anything you want.
For example, you might use the CTX field
municate with a common completion routine.

4.4.2

com-

Input Values

Anything you want, as long as it fits in 16 bits.
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

shown

4.4.3

Initialization and Default

Macro takes the form:
R$CTX argument
where argument is any value you want.
If there is no initialization macro, CTX

4-6

Record Access Block (RAB):

CTX

= O.

*************

*
*
*

FAB

*
*
*

*************

4.5

lPAB

The one-word File Access Block (FAB) field points to the File Access
Block connected to this RAB to form a Record Access Stream (RAS).
The
FAB must be associated with an open file at the time the $CONNECT
macro
is used.
If an
invalid address is stored in the FAB field,
RMS-11 returns error code ER$IFI.

4.5.1

Use

Input to:
:$CONNECT
You set the FAB field equal to the address of the FAB you
want associated with this RAB to make a Record Access Stream.

4.5.2

Input Values

Before the $CONNECT macro is executed, you must put a
dress in the FAB field.

valid

FAB

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.5.3

adshown

Initialization and Default

Macro takes the form:
H$FAB label
If there is no initialization macro, FAB

= O, meaning you must set the
field with the $STORE
field access macro before
initiating
$CONNECT.

Record Access Block (RAB):

FAB

4-7

4.5.4

Comments

If you are using the same FAB for more than one file, you should set
up all Record Access Streams associated with one file before you modify the FAB in preparation for another $OPEN or $CREATE.

4-8

Record Access Block (RAB):

FAB

*************

*
*
*

!SI

*
*
*

*************

'-""'
4.6

IS!

The $CONNECT macro sets the one-word Internal Stream Identifier
(ISI)
field to an address that links the RAB to the !RAB RMS-11 has created.
CAUTION
DO NOT CHANGE THE !SI FIELD.

4.6.1

Use

RMS-11 uses the address in the !SI field to
from the RAB to the !RAB.

transfer

pertinent

Record Access Block (RAB):

!SI

data

4-9

*************

*
*
*

KBF

*
*
*

*************

4.7

KBF

The one-word Key Buffer (KBF) field points to the key that RMS-11 uses
to locate a record during a random record operation:
•

For Relative files, RMS-11 uses the value as
number for $FIND, $GET, and $PUT operations.

•

For Indexed files, RMS-11 uses the buffer contents as the key value
during its index search for $FIND and $GET operations.
The RAB KRF
field determines the specific index searched and
the contents of
the RAB KSZ and ROP fields decide the match criteria used.

4.7.1

the

relative

record

"""

Use

Input to:
$FIND/$GET
You set
program
eration
KSZ and

the KBF field to the address of the buffer
in your
that contains the key for the next random record .op(RB$KEY in RAB RAC field).
You must also
set the
ROP fields appropriately.

$PUT
For Relative files, you set the KBF field
to
indicate the
relative record number of the cell where RMS-11 should write
the specified record.
~I

4.7.2

Input Values

The KBF field must contain a valid address before
operation macro is executed.

any

random

The address must indicate a buffer in the current
tains either:

program

record

that

con-

•

a relative record number as a two-word integer that is positive, at
least 1, and no greater than the Maxium Record Number (MRN) set for
the file when it was created.
The address must point to the least
significant byte of the record number.

•

a key value for an index search;
valid Indexed key types.

4-10

Record Access Block (RAB):

KBF

this value

can

any

the

The buffer does not have to be word-aligned.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.7.3

shown

Initialization and Default

Macro takes the form:
H$KBF label
If there is no initialization macro, KBF = O, meaning you must set the
field with the $STORE
field access macro before any random record
operation •

....,.

Record Access Block (RAB):

KBF

4-11

*************

*
*
*

KRF

*************

4.8

KRF

The one-byte Key of Reference (KRF) field indicates the
referenced in the current operation.

4.8.1

index

Use

The KRF field is only used for record operations on Indexed files.
Input to:
$FIND/$GET
You set the KRF field to indicate the index that should be
searched for
the value defined by the contents of the KBF
and KSZ fields;
match criterion is also specified by the
ROP field.
$CONNECT/$REWIND
You set the KRF field to indicate the index that is used
to
set the context of the Record Access Stream, that is, the
logical first record in the file.

4.8.2

Input Values

MINIMUM

= O, meaning the Primary Key

MAXIMUM -- 254
All values beginning with 1 indicate Alternate
and so on.

Keys,

first,

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.8.3

Initialization and Default

Macro takes the form:
R$KRF numeric
If there is no initialization macro, KRF

4-12

Record Access Block (RAB):

KRF

= O.

second,
shown

*************

*
*
*

KSZ

*************

4.9

KSZ

The one-byte Key Size (KSZ) field contains the size, in bytes, of the
key buffer indicated by the KBF field.
RMS-11 requires specific sizes
for a relative record number and all Indexed key types except string
(see
"Values").
However, for string keys, RMS-11 uses the number of
characters specified in KSZ as a length criterion in the index search
required
by the record operation.
Therefore, before a search can be
successful, RMS-11 must find a record with a key value that matches
the value
indicated
by KBF to the number of characters indicated by
KSZ.
If KSZ equals the length of the key (established when the
file
was created), the search requires an exact match, whereas when KSZ is
less than the key length, only an approximate match is needed.
The value of the ROP field also affects match criteria.

4.9.l

Use

Input to:
$FIND/$GET
For Relative files, you must set the KSZ field equal to 0 or
4.
For Indexed files, you set the KSZ field equal to:
•

specific number of bytes for all key types except string

•

the number of characters in a key field that must
the KBF value before the search is successful

match

$PUT
For Relative files, you must set the KSZ field equal to 0 or
4.

4.9.2

Input Values

The values of the KSZ field depend on the type of key indicated by the
KBF f i,eld:
e

Relative Record Number (FB$REL in FAB ORG field), KSZ
faults to 4)

Record Access Block (RAB):

de-

KSZ

4-13

• String Key Type (FB$IDX in FAB ORG field):
MINIMUM

MAXIMUM

= size of key indicated by the KRF field

• 15-bit Signed Integer Key Type, KSZ = 2 (0 defaults to 2)
• 31-bit Signed Integer Key Type, KSZ = 4 (0 defaults to 4)
• 16-bit Unsigned Binary Key Type, KSZ = 2 (0 defaults to 2)
• 32-bit Unsigned Binary Key Type, KSZ = 4 (0 clef a ul ts to 4)
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7) •

4.9.3

shown

Initialization and Default

Macro takes the form:
R$KSZ numeric
If there is no initialization macro, KSZ = O, meaning you must set the
field with the $STORE
field access macro before any Indexed random
record operation.

4.9.4

Comments

RMS-11 uses the KSZ field only for Indexed
with string keys.

4-14

Record Access Block (RAB):

KSZ

random

record

operations

..-..

*************

*
*
*

MBC

*************
4.10

MBC

The one-byte Multi-Block Count (MBC) field contains number of blocks
from a disk Sequential file that RMS-11 reads or writes as a single
I/O unit while the Record Access Stream is set up
(between $CONNECT
and $DISCONNECT).

4.10.1

Use

The MBC field should be set for disk Sequential files only;
take the
default of one for all other files.
See also the RMS-11 User's Guide.
Input to:
$CONNECT
You set the MBC field equal to the number of blocks you want
read
from or written to the file in each I/O access operation.

4.10.2

Input Values

MINIMUM

= O, meaning· one block is the I/O unit

MAXIMUM = 6 3.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.10.3

shown

Initialization and Default

Macro takes the form:
R$MBC numeric
If there is no initialization macro, MBC = O.

4.10.4
•
"-".

Comments

See the RMS-11 User's Guide for a discussion of the use of
optimization.

Record Access Block (RAB):

MBC

4-15

•

The value in the MBC field determines the size of the I/O buffer
used for the file represented by the FAB indicated by the RAB FAB
field. See Chapters 1 and 2.

4-16

Record Access Block (RAB):

MBC

*************

*
*
*

MBF

*************

4.11

MBF

The one-byte Multi-Buffer (MBF) field contains the number of buffers*
RMS-11 allocates for I/O operations when the Record Access Stream is
set up ($CONNECT).

4.11.1

Use

The MBF field should be set only for Indexed
files,
although RMS-11
uses it for Relative files as well:
take the default value of one for
Relative files.
Input to:
$:CONNECT
If you want to cache index Root buckets, set the MBF field
to a number greater than two to make buffers available (see
"Values") •

4.11.2

Input Values

MINIMUM

= O, meaning RMS-11 allocates the minimum

number of buffers
required by the file organization.
Sequential and Relative files require one buffer;
Indexed files require two
buffers.

MAXIMUM = 255
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.11.3

shown

Initialization and Default

Macro takes the form:
H$MBF numeric
If there is no initialization macro, MBF

= O.

*A buffer is one bucket long.

Record Access Block (RAB):

MBF

4-17

4.11.4
•

Comments

The value in the MBF field affects the size of the buffer pool
the file.
See Chapters 1 and 2.

for
'""·

•

Although RMS-11 does respond
to
the MBF field
for non-Indexed
files,
the use of a value greater than the m1n1mum (other than the
default) is a waste of address space and the use of a macro to
set
the value.

•

See the RMS-11 User's Guide for a discussion of the use of
optim i za ti on.

•

The value in the MBF field should incorporate the minimum
requirements for
the
Indexed
file:
add
the number of Roots you want
cached to the minimum requirements to get the value
for
the MBF
field.

•

If the value is:
less than
buffers

minimum,

RMS-11

allocates

the

more than two for Sequential files, RMS-11
buffers

MBF

minimum

number

allocates

only

two

more than is available, RMS-11 allocates as many buffers as possible

-•!\,

4-18

Record Access Block (RAB):

MBF

*************
*
*
RAC

*************

4.12

RAC

The one-byte Record Access (RAC) field contains an indicator
access method to be used in a record operation.

4.12.1

for

the

Use

Input to:
$FIND/$GET/$PUT
You set the RAC field to indicate the access method
should use to locate the next record position.

4.12.2

RMS-11

Input Values

The RAC field must contain one of the following symbolic values:
RM$KEY

RMS-11 performs a random record operation, using specifications from the KBF, KSZ, and if necessary KRF and ROP
fields.
Random access applies only to Relative and
Indexed fi 1 es.

RB$RFA

RMS-11 performs a record operation using
the Record's
File Address specified in the RFA field to locate the record position.
RFA access applies only to disk files.

RB$SEQ

RMS-11 performs a sequential record operation.

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.12.3

shown

Initialization and Default

Macro takes the form:
H$RAC symbolic
If there is no initialization macro, RAC = RB$SEQ.

Record Access Block (RAB):

RAC

4-19

*************

*
*

RBF

buffer

*
*
*

*
*************

4.13

RBF

The one-word Record Buffer (RBF) field points to
program that contains the
record moved by the record operation.

4.13.1

the

Use

Input to:
$PUT/$UPDATE
Regardless of the Record Transfer Mode, you must set the RBF
field
equal
to the address of the first byte of the record
you want written to the file.
You must also set the RSZ
field.
Output from:
~.

$GET
Regardless of Record Transfer Mode,
RMS-11 sets the RBF
field
equal
to the address of the first byte of the record
read from the file.
The RSZ field is also set.
$PUT
When your program is writing records to a Sequential file in
the Locate Record Transfer Mode, RMS-11 returns an address
in the RBF field after each $PUT operation.
This address is
the location where your program can build the next record.
If your program uses this location,
it must set the RSZ
field
to describe the record that begins at the location.
However, if your program does not use the address,
it must
reset both the RBF and RSZ fields.

4.13.2

"""

Input Values

The RBF field must contain a valid address.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4-20

Record Access Block (RAB):

shown

RBF

I Wiii

4.13.3

Initialization and Default

Macro takes the form:
H$RBF label
If there is no initialization macro, RBF

= O, meaning you must set the
field with $STORE before
a put or update operation is initiated.

4.13.4

Comments

During the simplest of processes, that is,
in Move Record Transfer
Mode and
the same records are being read and written/updated, the
RBF/RSZ and UBF/USZ fields describe the same buffer within your program:
•

RBF/RSZ describe the record that RMS-11 moves out of
to the file.

•

UBF/USZ describe the buffer where RMS-11 places
from the file.

each

your

program

record

read

In anticipation of this common usage, RMS-11 resets RBF after a
successful get operation so that you don't have to set it before initiating a $UPDATE macro: when RBF and UBF point to the same buffer,
RBF
is not changed.

Record Access Block (RAB):

RBF

4-21

*************
*
*

*
*

RFA

*
*

*************

4.14

RFA

The three-word Record's File Address (RFA) field contains the file address of the target record for or from a get or find operation or of
the record written by a put operation.

4.14.1

Use

Input to:
$FIND/$GET
If you have set the RAC field to RB$RFA,
you set the RFA
field
equal
to the Record's File Address of the record you
want found or read.
Output from:
$FIND/$GET
If the RAC field does not contain RB$RFA,
RMS-11 sets the
RFA field
equal to the Record's File Address of the record
found or read.
$PUT/$UPDATE
RMS-11 sets the RFA field equal to the Record's File Address
where it wrote the record specified.

4.14.2

Input Values

If the RAC field contains RB$RFA,
Record's File Address for the file;

the RFA must contain a valid
otherwise, error code ER$RFA.

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.14.3

Initialization and Default

Macro takes the form:
R$RFA. numeric
If there is no initialization macro, RFA

4-22

Record Access Block (RAB):

RFA

= o.

shown

*************

*
*
*

RHB

*************

4.15

RHB

The one-word Record Header Buffer (RHB) field points to the buffer
in
the
program
containing
the
fixed
control
area
of
Variable-with-Fixed~Control (VFC) records.
When RMS-11 gets a record,
it separates the fixed control area from the variable portion of the
record;
it places the fixed data in the buffer indicated by the RHB
field
and the variable data in the buffer indicated by the UBF field.
For put operations, RMS-11 prefixes the data from the RHB buffer to
the data in the RBF buffer before it moves the entire record from the
program to the I/O buffer and then to the file.
If no RHB buffer is indicated (the RHB field is zero),
but the
file
contains VFC records
(FB$VFC in the FAB RFM field), RMS-11 does the
following:
•

ignores the fixed control area of records read ($GET)

from the file

•

fills the fixed control area of records written ($PUT)
with zeros

to the

•

does not change the fixed control area of records during update operations

4.15.1

file

Use

Input to:
$GET/$PUT/$UPDATE
•
If you want the fixed control area of each record
read
and written properly, set the RHB field equal to the address of a buffer in the program.
•

4.15.2

If you do not want the fixed control area of each record
read or written,
ensure that the RHB field is zero;
otherwise, RMS-11 interprets the value in the field as an
address and tries to use the area indicated as a buffer:
the results are unpredictable.

Input Values

The RHB field must contain either:
•

zero (0)

= there is no buffer for the fixed control area
Record Access Block (RAB):

RHB

4-23

•

address of the fixed control area buffer. This buffer must
least as long as the value* in the FAB FSZ field indicates.

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.15.3

shown

Initialization and Default

Macro takes the form:
R$RHB label
If there is no initialization macro, RHB

4.15.4

= O.

Comments

During Locate Mode operations, the variable area data is accessed in
the I/O buffer, but the data in the fixed control area is moved to and
from the buffer described by the RAB RHB and FAB FSZ fields.

*This value is a file attribute established when the file was
and set in the FAB FSZ field by the file open process.

4-24

Record Access Block (RAB):

RHB

created

*************

*
*

ROP

*
*
*

*************

4.16

ROP

The one-word Record Processing Options
(ROP)
field contains a bit
string
indicating optional functions that you want RMS-11 to perform
while this Record Access Stream is set up
(between $CONNECT and
$DISCONNECT) •

4.16.1

Use

Input to:
$CONNECT/$DELETE/$FIND/$GET/$PUT
You set the ROP field to indicate the optional functions you
want RMS-11 to perform.

4.16.2
-~

Input Values

The ROP field may contain
values:

one

the

following

symbolic

RB$ASY

RMS-11 performs an asynchronou~ record operation, possibly returning control to your program before the operation is completed.
The RAB must have been defined as asynchronous type by the RAB$B macro (see "Allocation" at
the beginning of this chapter).

RB$EOF

RMS-11 sets the context of the stram at the end of the
file when the $CONNECT macro is finished;
valid for disk
Sequential files only.
This feature enables you to optimize buffer space:
when you are adding records to a
Sequential file, you can:

RB$FDL

•

disconnect the Record Access Stream when you are not
using
the file.
This operation releases buffer space
for use by other operations.

•

connect the Record Access Stream at end-of-file, ready
to put another record.

RMS-11 uses the Fast Delete procedure;
valid for Indexed
files only.
During $DELETE execution, RMS-11 flags the
user data record in the file as being deleted, but it updates Alternate indexes depending on whether duplicates
are allowed:
Record Access Block (RAB):

ROP

4-25

•

•
RB$KGE

•

RB$MAS

4-26

If duplicates are not allowed,
the
from the Alternate Level 0 bucket.

SIDR

J,.~b

removed

RMS-ll's search during a find or get operation depends on
file organization:
•

RB$KGT

If duplicates are allowed, the SIDR array entry for
the
deleted
record
is NOT flagged
as deleted.
Thereafter, a find or get operation using
that key
value
for that Alternate index will go to the Primary
Level O bucket before it detects that the
record has
been deleted.

In Relative files, RMS-11 checks the cell specified by
the
relative record number in the RAB KBF field;
if
the cell contains a valid
record,
the search ends.
However,
if the cell is empty or contains a deleted
record,
RMS-11
continues
searching
sequentially
through the cells until it finds a valid record, en~~~~;~~s end-of-file, or exceeds
the Maximum Record

.Allll~

In Indexed files, RMS-11 searches 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.

RMS-ll's search during a find or get operation depends on
file organization:
•

In Relative files, RMS-11 starts at the cell with a
relative record
number one higher than the number in
the RAB KBF field and
searches sequentially through
the cells until
it finds a valid record, encounters
end-of-file, or exceeds the Maximum Record Number.

•

In Indexed files, RMS-11 searches 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.

indicates to RMS-11 that you intend to insert a series of
records at the logical end of an Indexed file. These records must be sorted in ascending order by the Primary
Key value, and the lowest Primary Key value in the series, that of the first record, must be higher than any
Primary Key value already in the file. To implement Mass
Insert, RMS-11 keeps the data bucket locked after the
$PUT operation ends and maintains a pointer into the
index bucket above the data bucket in the index.
This
effort enables RMS-11 to rapidly insert records into the
file, splitting buckets economically if necessary.
The
presence of Alternate Keys degrades this performance.
Activating Deferred Write (FB$DFW) enhances it.

Record Access Block (RAB):

ROP

~·

RB$LOA

RMS-11 obeys bucket fill numbers when it is inserting records;
valid for Indexed files only.
See Allocation XAB
DFL and IFL fields and the RMS-11 User's Guide.

RB$LOC

RMS-11 uses the Locate Record Transfer Mode for get operations on all file organizations and for put operations
for Sequential files only.
See the RMS-11 User's Guide.

RB$UIF

If RMS-11 encounters a record in the target cell during a
put operation, it updates the record rather than returning error code ER$REX;
valid for Relative files only.

If you want to specify more than one option, you must concatenate
values using an exclamation point (!).

the

A value can be set in the field with the
initialization macro
below or with the $SET field access macro (see Chapter 7).

shown

4.16.3

Initialization and Default

Macro takes the form:
R$ROP symbolic[!symbolic ••• ]
If there is no initialization macro, ROP

'-""

= O, meaning:

•

Synchronous record operation

•

Context in a disk Sequential file after $CONNECT is the
cord in the file.

•

RMS-11 removes SIDR duplicate array entries from Alternate
during delete operations on Indexed files.

•

RMS-11 requires that a record's key value be equal
to
the value
specified by the KBF and KSZ fields before it returns the record to
the task.

•

RMS-11 completely fills Indexed file buckets.

•

Move Record Transfer Mode

•

If RMS-11 encounters a record in the target cell during a put operation on a Relative file, it returns error code ER$REX.

4.16.4

first

re-

indexes

Comments

Since the ROP field is a bit string, values cannot be added
to
the
field with the $STORE field access macro.
You should use the $SET
field access macro (see Chapter 7).
However, you use the $STORE macro
to (re) set all bits in the field.

Record Access Block (RAB):

ROP

4-27

*************

*
*
*

RSZ

*
*
*

*************

4.17

RSZ

The one-word Record Size (RSZ) field contains the size, in
the record indicated by the RBF field.

4.17.1

bytes,

Use

Input to:
$PUT/$UPDATE
You set the RSZ field equal to the size of the record in the
record buffer indicated by the RBF field.
RMS-11 moves only
the number of bytes specified.
Output from:
$GE'I'
record

~· ....

but maximum record size
is also affected
by file
structure, file organization, and task address space.
See the RMS-11 User's Guide.

""'

RMS-11 sets the RSZ field equal to the length of the
it placed in the buffer indicated by the UBF field.

4.17.2

Input Values

MINIMUM -· 1
MAXIMUM

= 65535,

A value of 0 is valid for only Sequential and Relative files with stream or variable-length records.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

4-28

Record Access Block (RAB):

RSZ

shown

4.17.3

Initialization and Default

Macro takes the form:
R$RSZ numeric
If there is no initialization macro, RSZ = O, meaning you must set the
field with the $STORE
field access macro before a $PUT operation*
is initiated.
NOTE
RSZ is also input to the $UPDATE macro; however, an update
operation must be preceded by a get (or find):
that operation sets the RSZ field so you don't have to set it before
an update operation unless the record size changes.

Record Access Block (RAB):

RSZ

4-29

*************
*
*
*
STS
*

*************

4.18

STS

The one-word Completion Status Code (STS) field contains a code indicating the success or failure (and type of failure) of the last record
operation. See Appendix A for symbolic and octal codes for both success and failure of operations.

4.18.1

Use

Output from:
$CONNECT/$DELETE/$DISCONNECT/$FIND/$GET/$PUT/$UPDATE/$REWIND/
$TRUNCATE/$FLUSH/$NXTVOL
RMS-11 sets the STS field equal to a completion status code.
You should test this field ($COMPARE field access macro) for
a negative value after each record operation, or you can use
an error routine that checks the value (see Chapter 8).
·~.

4.18.2

Input Values

No input values;

4-30

see Appendix A for output values.

Record Access Block (RAB):

STS

*************

STV

*
*

*************

4.19

STV

The one-word Status Value (STV) field contains additional
about some error codes returned in the STS field.

4.19.1

information

Use

Output from:
$CONNECT/$DELETE/$DISCONNECT/$FIND/$GET/$PUT/$UPDATE/$REWIND/
$TRUNCATE/$FLUSH/$NXTVOL
RMS--11 sets the STV field whenever it had additional
information to communicate about an error.
See Appendix A for
the specific errors on which the STV field
is used.
You
should check the STV field for a nonzero value whenever your
program detects an error (negative value in STS field).

4.19.2

Input Values

No input values;

see Appendix A for output values.

Record Access Block (RAB):

STV

4-31

*************

*
*

UBF

*
*
*

*************

4.20

UBF

The one-word User Buffer (UBF) field points to a buffer in your program where RMS-11 should place a record read from the file or that
RMS-11 can use during Locate Mode if necessary.

4.20.1

Use

Input to:
$CONNECT
RMS-11 transfers the address in the UBF field
to
the RBF
field
so that your program does not have to treat the first
put in Locate Mode on a Sequential file as a special case.
$GET
Regardless of Record Transfer Mode (RTM), you set the UBF
field
equal
to the address of the first byte of the record
buffer you have provided for RMS-11 to store the
record
it
reads from the file:
•

In Move RTM, RMS-11 automatically places
record in the buffer indicated by UBF.

the

retrieved

•

In Locate RTM, RMS-11 normally leaves the
retrieved
record
in the stream's I/O buffer and then sets the RBF
field to its address.
However, RMS-11 can determine that
it cannot perform the
record operation in Locate mod·e
(see UG):
it then moves the record into the buffer indicated by UBF.

In either circumstance, if the buffer described
by UBF is
too small
to contain the retrieved record, RMS-11 moves as
much of the record as possible into the buffer
(the number
of bytes in the USZ field), updates the context of the stream, and returns error code ER$RTB
$PUT
During Locate Mode operations on Sequential files only,
UBF
must continue to point to a valid record buffer within your
program.
Normally after a put operation,
RMS-11 sets the
RBF field
to the address of a location in the stream's I/O
buffer where your
program can build
the next record.
However,
if there is not enough room in the buffer to contain another record (based on the value
in the FAB MRS
field),
RMS-11
changes RBF to UBF, thereby pointing your
4-32

Record Access Block (RAB):

UBF

program to the user buffer to build the next record.
Then,
during the next put, RMS-11 fills out the current I/O buffer
from the UBF buffer, writes the I/O buffer to the file, and
then starts a new I/O buffer with the data left in the UBF
buffer, setting RBF back into the I/O buffer.

4.20.2

Input Values

The UBF field must contain the address of a buffer in your program.
The buffer should be large enough to contain the largest record in the
file.
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.20.3

shown

Initialization and Default

Macro takes the form:
R$UBF label
If there is no initialization macro, UBF

= O.

Record Access Block (RAB):

UBF

4-33

*************

*
*
*

usz

*
*
*

*************

usz

4.21

The one-word User Buffer Size (USZ) field contains the size, in bytes,
of the buffer indicated by the UBF field.

4. 21.1

Use

Input to:
$GET
You set the USZ field equal to the size of the buffer you
are providing to hold a record.
RMS-11 reads in only the
number of bytes specified.
During Locate Mode operations on Sequential files only.
discussion under "Use" for the UBF field.

4.21.2

See

Input Values

MINIMUM = 1
MAXIMUM = 65535, but maximum record size
is also affected by file
structure, file organization, and task address space.
See the RMS-11 User's Guide.
~.

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

4.21.3

shown

Initialization and Default

Macro takes the form:
R$USZ numeric
If there is no initialization macro, USZ

= O.

Allt\,

4-34

Record Access Block (RAB):

USZ

CHAPTER 5
EXTENDED ATTRIBUTE BLOCKS

The initialization macros (this chapter) and the field
access macros
(Chapter 7) are provided so that you do not have to know the specific
position and to a large extent, the size of each field in a XAB.
You
can, therefore, treat the fields as logical entities.
It is also possible that the positions and sizes of the fields will change from
release to release of RMS-11.
However, you can determine the position of any field in a
XAB as an
offset from the XAB's starting address.
RMS-11 represents these offset values with symbols in one of the following forms:

•

O$fnm
where fnm is the three-letter name of a one-byte or one-word field;
fnm
is the name used to reference the field in the initialization
and field access macros.
Example

•

O$STS

~or

the status code field

O$fnmx
whe:re fnm is the name of a multi.word field;
fnm is the name used
to
reference the
field in the initialization and field
access macros.
x is a number associated with an
individual word
field, from 0 through the end of the field.
Example

the

O$SIZO for the size of the first segment in a key as
most significant word

the

The values of these symbols can be found in the symbol table of an assembly listing file for any module containing the XAB.

5.1

Allocation Extended Attribute Block

Each Allocation XAB describes an area of a file.
An area is a portion
an RMS-11 file that is treated as a separate entity for purposes

~~:

F"""

Initial allocation
Extension
Placement
Bucket size
See also the RMS-11 User's Guide.
Sequential and Relative files are always composed of a single
(Area 0), while Indexed files should contain more than one area.

area

Allocation XABs enable you to control:
•

The physical placement of an RMS-11 file of any organization
disk volume:

You provide one (for any type of file) or more (for Indexed
files
only) Allocation XABs linked to the FAS you use to create the file.
Within each XAB are two fields:
Alignment Block Type (ALN)
Allocation Starting Point (LOC)
If the ALN field is not zero when the $CREATE macro
is executed,
RMS-11 uses the values in the two fields to direct the placement of
the first block of the area on the device specified;
the XAB ALQ
field controls the size of the initial allocation.
NOTE
On RSTS/E, the File Processor allows RMS-11 to place only
Area 0.
RMS-11 allocates all other areas as extents of
Area 0.
See also comments for the AOP field in this section.

•

The internal structure of an Indexed file:
Whether or not you use placement control, you can use Allocation
XABs to define multiple areas within an Indexed file, assign the
index and data levels of the various indexes to particular areas,
and vary the size of buckets for each area.

Allocation XABs are completely optional.
If you do not require either
placement control or an optimized Indexed file, do not include Allocation XABs in your XAB chain; RMS-11 uses the following defaults:
•

5-2

RMS-11 creates the file as a single area, using the value in the
FAB ALQ for the initial allocation quantity.
The default extension
quantity is derived from the FAB DEQ field.
The operating system
Allocation XAB:

Introduction

completely
vo1 ume.
•

controls the physical placement of the file on the disk

For Indexed files, RMs--11 sets up a single bucket size and
buckets of all
types
(index, SIDR, and user data record)
single area of the file.

stores
in the

If you do use Allocation XABs, they are used as:
Input to $CREATE and $EXTEND
Before the initiation of a
$CREATE macro,
all Allocation
XABs must be set up and included in the XAB chain linked in
dense ascending order by AID field:
the XAB for Area 0 must
be the first Allocation XAB in the chain;
the XAB for Area
1 must be next;
and so on.
The NXT field for Area O's XAB
must point to Area
l's XAB, Area l's XAB NXT field must
point to Area 2's XAB, and so on.
Output from $DISPLAY, $EXTEND, and $OPEN
If you want one or more area definitions, link a
sufficient
number of Allocation XABs.
RMS-11 sets the appropriate
fields to the values established when the file was created.
The Allocation XABs must be adjoining, linked in ascending
order,
but they do not have to be densely
ordered.
Therefore,
you can link Allocation XABs for Areas 1 and 3
only, for example, if descriptions of those areas are
the
only ones you want.
NOTE
Since RMS-11 creates a file with areas by allocating Area 0
first and then extending the file for each additional area,
you can't have a contiguous file with multiple areas on
RSTS/E.
However, after you create the file with areas, you
can use PIP to copy it into a contiguous space.
Table 5-1:
Field
Name

Field
Size

AID
ALN
ALQ
AOP
BKZ
BLN
COD
DEQ
LOC
NXT
VOL

lB
lB
2W
lB
lB
lB
lB
lW
2W
lW
lW

Allocation Extended Attribute Block Fields
Default
0
0
0
0

1 record
N/A
N/A
0
0
0
0

Description
Area id number
Alignment block type
Allocation quantity
Allocation options
Area bucket size
All XAB length
XAB type
Area extension quantity
Number of block specified by ALN
Next XAB
Not used

Allocation XAB:

Introduction

5-3

*************

*
*

AID

*************

5 .1. 1

AID

The one-byte Area Identification Number
area described by the XAB.

5.1.1.1

(AID)

field

identifies

the

Use

Input to:
$CRE.ATE/$EXTEND
You set the AID field to tell RMS-11 the area defined by the
XAB.

"""

$DISPLAY/$0PEN
You set the AID field to tell RMS-11 the area whose description it should set into the fields of the XAB.
Additionally, RMS-11 uses the AID field to check the sequencing of the
Allocation
XABs
in the chain before continuing with the
file
operation;
if the XABs are out of sequence, RMS-11 terminates the operation.

5.1.1.2

Input Values

MINIMUM

= O*

MAXIMUM

= 254

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.1.3

shown

Initialization and Default - Macro takes the form:'

X$AID numeric
If there is no initialization macro, AID

= o.

*Zero is the only value acceptable for Sequential and Relative files.

5-4

Allocation XAB:

AID

·""'

*************

*
*

ALN

*
*
*

*************

5 .1. 2

ALN

The one-byte Alignment Block Type
(ALN)
field determines whether
placement control is used in the allocation of blocks in this area by
the file operation.

5.1.2.1

Use

Input to:
$CREATE
•

If you want placement control over the initial allocation
of the area, you set the ALN field to indicate that the
number in the LOC field is one of the following:
Device Cluster Number
Logical Block Number
Virtual Block Number
Cylinder number on VAX
The AOP field also affects placement control.

•

If you do not want placement control,
field to zero.

you

set

the

ALN

$EXTEND
•

If you want placement control over the explicit extension
of ·the area, you set the ALN field to indicate that the
block number in the LOC field is either a
Logical Block
Number or a Virtual Block Number.
The AOP field also affects placement control.

•

If you do not want placement control,
field to zero.}

you

set

the

ALN

$DISPLAY/$0PEN
RMS-11 sets t·he ALN field equal to the value specified
the file was created.

when

Output from:

Allocation XAB:

ALN

5-5

5.1.2.2
ing:

Input Values - The ALN field must contain one of the

follow-

zero

no placement control

XB$LBN

RMS-11 requests the operating system to place the
first
block of the specified allocation on or near the logical
block I device cluster
indicated by the number
in the
LOC field.

XB$VBN

RMS-11 requests the operating system to place the
first
block of the specified allocation near the virtual block
of the file indicated by the LOC field;
not valid during
$CREATE when the AID field is zero, that is, for Area O.

XB$CYL

RMS-11 requests the operating system to place the
first
block of the specified allocation at the first block of a
cylinder as indicated by the LOC field.
VAX only

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.2.3

shown

Initialization and Default - Macro takes the form:

X$ALN symbolic
If there is no initialization macro, ALN

= O.

5.1.2.4 Comments - On RSTS/E, you can specify location information
for Area 0 only.
If RMS-11 detects nonzero values in the ALN and LOC
fields in other Allocation XABs, it returns the error code ER$ALQ.

5-6

Allocation XAB:

ALN

*************

*
*

ALQ

*
*
*************

5. 1. 3

ALQ

The two-word Allocation Quantity (ALQ) field contains the size of
area represented by the XAB, in blocks.

5.1.3.1

the

Use

Input to:
$CREATE
You set the ALQ field equal to the number of
allocated in the initial extent of the area.

blocks

~>EXTEND

You set the ALQ field equal to the number of
added to the area.
Output from:
~?DISPLAY/$0PEN

RMS-11 sets the ALQ field equal to the number of blocks unused
in the current extent of the area (see "Comments").
RMS-11 obtains this information from the file Prologue.

5.1.3~2

Input Values

$CREA~rE

MINIMUM = O, meaning that this area will only be as long as necessary;
that is, Area 0 will contain the file Prologue and all other areas will be allocated with no
blocks.
MAXIMUM = number of free blocks
file.

the

device

containing

the

$EXTEND
MINIMUM = 1, meaning that one block should be added to
the area
(although a zero extent is possible, it is not logical)
MAXIMUM = number of free blocks
area.

the

device

containing

Allocation XAB:

ALQ

the

5-7

RMS-11 rounds values up to a multiple of area bucket size.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.3.3

shown

Initialization and Default - Macro takes the form:

X$ALQ numeric
If there is no initialization macro, ALQ

5.1.3.4
•

•

= O.

Comments

When Allocation XAB(s) are linked to a FAB, create and extend operations ignore the FAB ALQ field, using the XAB ALQ field(s) for the
particular area(s).
If you include only one .Allocation XAB,
for
Area O, RMS-11 uses the ALQ field in the XAB instead of the FAB for
the size of Area O, which is essentially the whole file.

The current extent of an area is the number of blocks that were
last added to the area, via either automatic or explicit extension.
It is, therefore, not necessarily the total size of the area.

""'
5-8

Allocation XAB:

ALQ

*************

*
*

AOP

*
*

*************

5 .1. 4

AOP

The one-byte Allocation Options (AOP) field contains a bit string
indicating
the type of allocation RMS-11 makes during the file operation.

5.1.4.1

Use

Input to $CREATE/$EXTEND:
You set the AOP field to indicate how exact you require the actual alignment of the area's allocation with the value specified in
the LOC field ..
Output from $DISPLAY/$0PEN:
RMS-11 sets the AOP field equal to the value specified
file was created.

when

the

5.1.4.2 Input Values - The AOP field may contain one or both
following symbolic values:
XB$HRD

The operation fails unless the allocation starts exactly
at the
Device Cluster /Logical Block Number specified by
the LOC field;
valid only if the ALN field contains
XB$LBN.

XB$CTG

The operation fails unless the allocation
within itself.

contiguous

A value can be set in the field with the initialization macro
below or with the $SET field access macro (see Chapter 7).

5.1.4.3

shown

Initialization and Default - Macro takes the form:

X$AOP symbolic[!symbolic]
If there is no initialization macro, AOP

= O, meaning:

•

Allocation is made as close to the requested block as possible.

•

Allocation is not necessarily contiguous with the current extent of
the area.

Allocation XAB:

AOP

5-9

*************

*
*
*

BKZ

*************

5.1.5

BKZ

The one-byte Bucket Size (BKZ) field contains the size of a bucket, in
disk blocks, in the area represented by the XAB.

5.1.5.1
files.

Use - RMS-11 uses the BKZ

field

for

Relative

and

Indexed

Input to:
$CREATE
You set the BKZ field equal to the number of disk blocks
a bucket for the area to be created.

Output from:
$DISPLAY/$0PEN
RMS-11 sets the BKZ field equal to the bucket size established
for the area when the file was created.
RMS-11 obtains the information from the file Prologue.

5.1.5.2

Input Values -

MINIMUM - O, meaning that RMS-11 calculates a size so
contains at least one record.

that

bucket

MAXIMUM -· number of blocks allowed by the operating system (specifying
a larger value results in error code ER$BKZ):

IAS = 32 blocks
RSTS/E = 15 blocks
RSX-llM = 32 blocks
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.5.3

shown

Initialization and Default - Macro takes the form:

X$BKZ n um er ic
If there is no initialization macro, BKZ

= minimum number of blocks to
contain one record.

5-10

Allocation XAB:

BKZ

5.1.5~4

Comments -

•

When Allocation XABs are linked to a FAB, RMS-11
ignores the
BKZ field, using the XAB BKZ fields for the particular areas.

FAB

•

You gain no particular advantage from different
different areas •

bucket

sizes

for

Allocation XAB:

BKZ

5-11

.....,,.

*************

*
*
*

BLN

*
*
*

*************

5 .1. 6

BLN

The XAB$B macro sets the one-byte Block Length (BLN)
tended Attribute Block length.

field to the

Ex-

CAUTION
DO NOT CHANGE THE BLN FIELD.

5.1.6.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the BLN field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$BLN error code.

5-12

Allocation XAB:

BLN

*************

*
*
*

COD

*
*

*************

5. 1. 7

COD

The XA.B$B macro sets the one-byte Code (COD) field to the Extended Attribute Block type, with the symbolic value of XB$ALL.
CAUTION
DO NOT CHANGE THE COD FIELD.

5.1.7.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB;
one of the checks examines
the COD field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$COD error code.

Allocation XAB:

COD

5-13

*************

DEQ
*
*
***************

5.1.8

DEQ

The one-word Default Extension Quantity
(DEQ)
field
contains the
number of blocks RMS-11 requests whenever it automatically extends the
area {opposed to an explicit extend operation).
RMS-11 requests additional
blocks from
the operating system* whenever a task attempts a
put or update operation and there is not enough room in the area
represented by the XAB to complete the operation.

5.1.8.1

Use - RMS-11 uses the DEQ field for Indexed files only.

Input to:
$CREATE
You set the DEQ field equal to the number of blocks that
should be requested in each automatic extension of the area
to be created.
$OPEN
You set the DEQ field equal to the number of blocks to be
used
by RMS-11 as a temporary default extension quantity
until the area
is closed;
the area attribute
is not
changed.
Output from:
$OPEN
If the DEQ field is zero, RMS-11 sets it equal to the number
of blocks estab'l ished as the default extension quantity when
the area was created.

5.1.8.2 Input Values - Default extension quantity should be a multiple of bucket size;
RMS-11 rounds it up to the nearest multiple anyway before it sends the extension request to the operating system.
MINIMUM = O, meaning that whenever RMS-11 has to extend the area,
it
will request the minimum blocks necessary to complete the
current operation, that is, one bucket.
MAXIMUM

= 65,535 blocks

*Automatic extension can fail;see "Comments."

5-14

Allocation XAB:

DEQ

RMS-11 rounds value up to a multiple of area bucket size.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.8.3

shown

Initialization and Default - Macro takes the form:

X$DEQ numeric
If there is no initialization macro, DEQ

5.1.8.4

= O.

Comments

•

WhEm Al location XASs a re 1 inked to a FAS, RMS-11 uses the XAS DEQ
field whenever an area has to be extended automatically, unless
that field is zero;
in that case, RMS-11 uses the value in the FAS
DEC~ field.

•

Automatic extension can fail for at least
there might be others:

the

following

reasons;

Operating system is RSTS/E and file is:
contiguous;
error code = ER$PRV
shared;
error code = ER$PRV
No more room is available on the storage device;
ER$FUL

error

code

•

On the RSTS/E operating system, area allocation is done
in
clusters;
see the RMS-11 User's Guide for a discussion of the interaction between clusters and default extension quantity.

•

See the RMS-11 User's Guide for a discussion of
quantity and its optimization.

default

Allocation XAS:

extension

DEQ

5-15

*************

LOC

*************

5 .1. 9

LOC

The two-word Allocation Starting Point (LOC) field contains a number
interpreted by RMS-11 as the Device Cluster,
Logical Block, Virtual
Block, or cylinder number (depending on the value of the ALN field)
where the allocation specified by the operation should start. The ALQ
field specifies the allocation quantity and the AOP field indic~tes
how definite the placement is.

5.1.9.1

Use

Input to:
$CREATE/$EXTEND
If you specify a nonzero value for the ALN field, you must
set the LOC field equal to the appropriate number (depending
on the value in the ALN field) where you want the specified
allocation to begin.

5.1.9.2
ing:

Input Values - The LOC field must contain one of the

•

any value* if the ALN field is zero

•

numeric value within the range:

follow-

MINIMUM = O; if the ALN field contains XB$VBN, RMS-11 requests
placement near the current end of the file, unless AID
is zero.
MAXIMUM = number of free blocks I clusters on the device containing the file, if the ALN field contains XB$LBN

= number of cylinders on the device containing the file,

the ALN field contains XB$CYL
=

•

number of blocks currently in the file, if the ALN
contains XB$VBN

the numeric value -1 if the ALN tield contains XB$CYL;
quests placement at the first block of any cylinder

*Recommended value is the default, zero.

5-16

Allocation XAB:

LOC

RMS-11

field
re-

A v~lue can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.9.3

shown

Initialization and Default - Macro takes the form:

X$LOC numeric
If there is no initialization macro, LOC

= O.

Allocation XAB:

LOC

5-17

*************
*
*
NXT
*
*
*
*
*************

5. 1. 10

NXT

The one-word Next XAB (NXT) field, if not zero, points to another separately allocated XAB and thereby indicates to RMS-11 that there is at
least one more XAB in the chain connected to the FAB via the FAB XAB
field.
See "Linking and Ordering XABs"
at the beginning of this
chapter.

5.1.10.1

Use

Input to:
$CREATE/$DELETE/$EXTEND/$0PEN

5.1.10.2

•

If you have allocated another XAB and want RMS-11 to
use
it,
you set the NXT field equal to the address of that
XAB.

•

If you have not allocated an XAB and/or you want the XAB
chain to end here,
set the NXT field equal to zero;
otherwise, RMS-11 interprets the value in the field as an
address and
tries to use the area indicated as an XAB:
if that area is not a valid XAB, RMS-11 returns the error
code ER$XAB.

Input Values - The NXT field must contain either:

= there are no more XABs in this chain

•

zero (0)

•

address of an Extended Attribute Block separately allocated in
program

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.1.10.3

Initialization and Default - Macro takes the form:

X$NXT label
If there is no initialization macro, NXT

5-18

Allocation XAB:

NXT

= 0.

the
shown

*************

*
*
*
*************

*
*

5. 1. 11

VOL

The one-word Relative Volume Number (VOL)
by RMS-11.

field is currently not

5.1.11.1

Use - NONE

5.1.11.2

Input Values - NONE

5.1.11.3

Initialization and Default - NONE

5.1.11.4

Examples - NONE

5.1.11.5

Comments - NONE

Allocation XAB:

VOL

used

5-19

5.2

Date Extended Attribute Block

The Date XAB contains date and time information about the creation and
revision of the file, as well as an RMS-11 revision number.
The information is output only by RMS-11 during a $DISPLAY or $OPEN operation; RMS-11 obtains the data from the file attributes.
Table 5-2:

Date Extended Attribute Block Fields

Field
Name

Field
Size

Default

BLN
CDT
COD
NXT
RDT
RVN

lB
4W
lB
lW
4W
lW

N/A
N/A
N/A

5-20

N/A
N/A

Description
DAT XAB length
Creation date-time
XAB type
Next XAB
Revision date-time
RMS-11 revision number

Date XAB: Introduction

l .

*************

*
*
*

BLN

*
*

*************

5. 2. 1

BLN

The XAB$B macro sets the one-byte Block Length (BLN)
tended Attribute Block length.

field to the

Ex-

CAUTION
DO NOT CHANGE THE BLN FIELD.

5.2.1.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB;
one of the checks examines
the BLN field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$BLN error code.

Date XAB:

BLN

5-21

*************

*
*

CDT

*
*
*

*************

5. 2. 2

CDT

The four-word Creation Date (CDT) field contains the date and time the
file associated with the linked FAB was created.

5.2.2.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the CDT field equal
finds in the file attributes.

the

creation

date

5.2.2.2 Output Values - The value RMS-11 puts into the CDT field
is
an eight-byte binary number representing the number of hundreds of nanoseconds that elapsed between November 17, 1858*, and
the time the
file was created.
This method of storing dates is standard for DIGITAL operating
systems,
although it has not been implemented in IAS, RSTS/E, or RSX-llM
yet**·
RMS-11 translates the dates these operating systems do maintain
into
the 64-bit format before storing it in the Date XAB.
The
resultant date is only as accurate as the operating system date:
IAS
RSTS/E
RSX-llM

accurate to the second
accurate to the minute
accurate to the second

Appendix C contains a MACR0-11 routine for converting this 8-byte binary number
to ASCII characters;
this is the same routine used by
RMSDSP (see the RMS-11 User's Guide).

*The Smithsonian Astrophysical Base Date, celebrating
the day the
first
photographic plate was exposed at the Harvard Smithsonian Observatory.
k*It has been implemented in the VAX/VMS System.

5-22

Date XAB:

CDT

*************

*
*

COD

*
*
*

*************

5.2.3

COD

The XAB$B macro sets the one-byte Code (COD) field to the Extended Attribute Block type, with the symbolic value of XB$DAT.
CAUTION
DO NOT CHANGE THE COD FIELD.

5.2.3~1
Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the COD field.
If this field does not contain the proper code, RMS-11
terminates the operation with a ER$COD error code.

"-"'

Date XAB:

COD

5-23

*************

*
*
*

NXT

*
*
*

*************

5. 2. 4

NX~r

5.2.4.1

Use

Input to:
$CREATE/$DELETE/$EXTEND/$0PEN

5.2.4.2

•

If you have allocated another XAB and want RMS-11 to use
it, you set the NXT field equal to the address of that
XAB.

•

If you have not allocated an XAB and/or you want the XAB
chain to end here, set the NXT field equal to zero;
otherwise, RMS-11 interprets the value in the field as an
address and tries to use the area indicated as an XAB:
if that area is not a valid XAB, RMS-11 returns error
code ER$XAB.

Input Values - The NXT field must contain either:

= there are no more XABs in this chain

•

zero (0)

•

address of an Extended Attribute Block separately allocated in
program

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.2.4.3

Initialization and Default - Macro takes the form:

X$NX~r

label

If there is no initialization macro, NXT

5-24

Date XAB:

NXT

= O.

the
shown

*************

*
*
RDT
*
*
***************

5.2.5

RDT

The four-word Revision Date (RDT) field contains the date and time the
file associated with the linked FAB was last updated, that is, the
date and time the last write record operation* was executed against
the file.

5.2.5"1

Use

Output from:
~?DISPLAY/$0PEN

RMS-11 sets the RDT field equal
finds in the file header.

the

revision

date

5.2.5"2 Output Values - The value RMS-11 puts into the CDT field
is
an eight-byte binary number representing the number of hundreds of nanoseconds that elapsed between November 17, 1858**, and the time the
file was created.
This method of storing dates is standard for DIGITAL operating systems, although it has not been implemented in IAS, RSTS/E, or RSX-llM
yet***·
RMS-11 translates the dates these operating systems do maintain into the 64-bit format before storing it in the Date XAB.
The
resultant date is only as accurate as the operating system date:
!AS
RSTS/E
RSX-llM

accurate to the second
accurate to the day
accurate to the second

Appendix C contains a MACR0-11 routine for converting this 8-byte binary number to ASCII characters;
this is the same routine used by
RMSDSP (see the RMS-11 User's Guide).
*Includes RMS-11 delete, put, and update operations and any non-RMS-11
operc;1tions, such as FCS,
BASIC+, and utilities (PIP and so on).
Since higher-level language statements eventually break down to
RMS-11 macros,
the r~vision date is valid no matter the source
language of the program doing the file revision.
**The Smithsonian Astrophysical Base Date, celebrating the day the
first photographic plate was exposed at the Harvard Smithsonian Observatory ..
***It has been implemented in the VAX/VMS System.

Date XAB:

RDT

5-25

*************

*
*

RVN

*
*

*************

5.2.6

RVN

RMS-11 returns valid data to the RVN field only on !AS and RSX-llM operating
systems.
On RSTS/E systems, this field is always zero.
The
one-word Revision Number {RVN) field indicates the number of times the
Eile has been opened for write operations by RMS-11* and non-RMS-11
tasks since it was created {that open is therefore not counted).

5.2.6.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the RVN field equal to the
finds in the file header.

revision

number

5.2.6.2 Input Values - The value stored in the RVN field is a
simple
binary number, easily translated to octal or decimal {see subroutines
in the sample program in Appendix B).

*If the FAS FAC field contains FB$DEL, FB$PUT, FB$UPD, and/or FB$WRI,
the operating
system
increments the
revision number in the file
header during an open operation.

5-26

Date XAB:

RDT

5.3

Key Extended Attribute Block

A Key XAB describes one key of an Indexed file.
This includes specifications for
the
key field (type, position, length) as well as the
index structure supporting that key.
See the RMS-11 User's Guide.
Key XABs are used as:
Input to $CREATE
Before the initiation of a $CREATE macro,
if the
FAB ORG
field contains FB$IDX, you must link at least one Key XAB to
the FAB to define the Primary Key.
You must also
use one
Key XAB to define each additional key you want the file to
have.
If you specify more than one Key XAB, they must be:
•

linked in densely ascending order by REF field;
that is,
the Primary Key XAB is the first Key XAB to occur in the
chain, the First Alternate Key XAB next, and so on

•

adjoining in the XAB chain;
that is, the Primary Key XAB
NXT field
points to
the First Alternate Key XAB, the
First Alternate Key XAB points to
the Second Alternate
Key XAB, and so on

Output from $DISPLAY and $OPEN:
If you want one or more key definitions, link in a
sufficient number of key XABs.
RMS-11 sets the appropriate
fields to the values established when the file was created.
If there is more than one, the Key XABs must be:
•

linked in ascending order by REF field, but not necessarily densely;
for example, if you only want descriptions
of the Second and Fourth Alternate Keys,
you must link
only the XABs for those keys, in that order

•

adjoining in the XAB chain;
that is, the first
Key
in the chain must point to the second one, and so on

XAB

NOTE
Since Key XABs describe both keys
terms:

and

their

indexes,

the

"key described by the XAB"
"index described by the XAB"
are used in the following
field descriptions;
they both
refer
to
the same XAB.
The value in the REF field determines which key/index is described.

Key XAB:

Introduction

5-27

Table 5-3:

Key Extended Attribute Block Fields

Field
Name

Field
Size

Default

BLN
COD
DAN
DBS
DFL
DTP
DVB
FLG
IAN
IBS
IFL
KNM
LAN
LVL
MRL
NSG
NUL
NXT
POS
REF
RVB
SIZ
TKS

lB
lB
lB
lB
lW
lB
4W
lB
lB
lB
lW
lW
lB
lB
lB
lB
lB
lW
8W
lB
2W
8W
lB

N/A
N/A

5-28

Key XAB:

0
0
0
0
0
0
0

0
0
0
0

0
0
0
0
0
0
0
0
0

Introduction

Description
KEY XAB length
XAB type
Level 0 area number
Data bucket size
Level 0 fill number
Key data type
VBN of first data bucket
Key characteristics
Levels 2+ area number
Index bucket size
Levels 2+ fill number
Pointer to key name
Level 1 area number
Index level of root
Minimum length record size
Number of key segments
Null key value
Next XAB
Key position(s) in record
Key described by XAB
VBN of index root
Size(s) of key segments
Total key size

*************

*
*
*

BLN

*
*
*

*************

5. 3. 1

BLN

The XAB$B macro sets the one-byte Block Length (BLN) field to the
tended Attribute Block length.

Ex-

CAUTION
DO NOT CHANGE THE BLN FIELD.

'-"'
5.3.l~l
Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the BLN field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$BLN error code.

Key XAB:

BLN

5-29

*************

*
*

COD

*
*

*
*
*************
5.3.2

COD

The XAB$B macro sets the one-byte Code (COD) field to the Extended Attribute Block type, with the symbolic value of XB$KEY.
CAUTION
DO NOT CHANGE THE COD FIELD.

5.3.2.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the COD field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$COD error code.

5-30

Key XAB:

COD

*************

*
*
DAN
*
*
***************
5.3.3

DAN

The one-byte Data Area Number (DAN) field contains the number of the
file area in which Level O* of the index described by this XAB is (or
will be) stored.

5.3.3.,l

Use

Input to:
~?CREATE

•

If you are not creating a multi-area file**, that is, no
or one Allocation XAB, ensure that the DAN field is zero
(the default) •

•

If you are creating a multi-area file, that is, there are
multiple Allocation XABs also linked to the FAB, set the
DAN field to the number of the area in which you want the
data level of this index (set by REF field) stored.
This
number must be the same as the AID field of one of the
Allocation XABs.

Output from:
:$DISPLAY/$0PEN
RMS-11 sets the DAN field equal to the number of the area in
which Level O of the index indicated by the REF field is
stored.

5.3.3.2

Input Values

MINIMUM

= O, meaning Area O**

MAXIMUM

254,

meaning
the maximum possible area that may be
allocated;
however, the maximum within each program
is restricted to the highest number in an Allocation
XAB AID field

*The data level (Level 0) of the Primary index contains your data
records while Level O of Alternate indexes contain Secondary Index Data
Records that point into the Primary index Level O.
See the RMS-11
User's Guide.
**If there are no Allocation XABs, the entire file is in Area O.
Key XAB:

DAN

5-31

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.3.3

shown

Initialization and Default - Macro takes the form:

X$DAN numeric
If there is no initialization macro, DAN = O.

5-32

Key XAB:

DAN

u .e::u:z;n 11111111111

*************

*
*
*

DBS

*
*

*************

5.3.4

DBS

The one-byte Data Bucket Size
(DBS)
field contains the number of
blocks in a bucket in the file area that contains Level 0 of the index
described by this XAB.

5.3.4.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the DBS field equal to the bucket size of the
area established for Level 0 of this index when the file was
created.

5.3.4o2

Output Values

MINIMUM = 1
MAXIMUM = number of blocks allowed by the operating system

Key XAB:

DBS

5-33

*************

DFL

*************

5.3.5

DFL

The one-word Data Bucket Fill Number
(DFL)
contains the number of
bytes in each bucket of this index's Level 0 that should be used to
store data if the RAB ROP field contain RB$LOA when the Record Access
Stream is set up ($CONNECT);
if RB$LOA is not set, RMS-11 ignores the
fill number.
See the RMS-11 User's Guide for a discussion of fill
numbers.

5.3.5.1

Use

""'·

Input to:
$CREATE
You set the DFL field equal to the number of bytes you want
filled
in each Level 0 bucket when RMS-11 is honoring fill
numbers.
Output from:
$DISPLAY/$0PEN
RMS-11 sets the DFL field equal to fill
number established
for
Level 0 of the index designated by the REF field when
the file was created.

5.3.5.2

Input Values

MINIMUM

= 0, meaning the buckets should be completely

filled

regard-

less of value in RAB ROP field

= half of the bytes in the bucket;

this is a logical m1n1mum,
meaning you can specify less, but RMS-11 ignores it, supplying its own 50% figure

MAXIMUM = total number of bytes in a bucket less one record (including
overhead);
this is a logical maximum;
the physical maximum
(total number of bytes in a bucket) can be achieved by specifying zero
You can figure the number of bytes in a bucket as follows:
NRBKT = 512*BKS
where BKS is the bucket size, expressed in blocks.

5-34

Key XAB:

DFL

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.5.3

shown

Initialization and Default - Macro takes the form:

X$DFL numeric
If there is no initialization macro, DFL = O.

Key XAB:

DFL

5-35

*************

*
*
DTP
*
*
***************
5.3.6

DTP

The one-word Key Data Type (DTP) field contains a bit string
ing the data type of the key described by this XAB.

indicat-

CAUTION
If you are currently using RMS-llK Vl.5 and want to use the
DTP field,
you must reassemble your program using the
RMS-llK Vl.8 RMSLIB.MLB.

5.3.6.1

Use

Input to:
$CREATE
You set the DTP field to indicate the data type of
you have defined with the POS and SIZ field.

the

key
~.

Output from:
$DISPLAY/$0PEN
RMS-11 sets the DTP field to indicate the data type established for the key indicated by the REF field when the file
was created.

5.3.6.2 Input Values - The DTP field must contain one of the
ing symbolic values:
XB$BN2

Each 16-bit unsigned binary key requires two bytes.

XB$BN4

Each 32-bit unsigned binary key requires four bytes.

XB$IN2

Each 15-bit signed integer key requires two bytes.

XB$IN4

Each 31-bit signed integer key requires four bytes.

XB$PAC

A packed decimal key has two
each byte.

XB$STG

Each character of a string key
value.

A value can be set in the field with the
5-36

follow-

Key XAB:

DTP

dee imal
is

digits

stored

initialization

stored

binary

macro

shown

below or with the $SET field access macro (see Chapter 7).

5.3.6.3

Initialization and Default - Macro takes the form:

X$DTP symbolic
If there is no initialization macro, DTP = XB$STG.

'-"'

Key XAB:

DTP

5-37

*************

*
*
DVB
*
*
***************
5.3.7

DVB

The two-word Data Virtual Block Number
(DVB)
field specifies the
number of the file's virtual block that contains the first block of
the first* bucket in Level 0 of the index described by this XAB.

5.3.7.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the DVB field equal to the number of the virtual
block containing the first data from this index in the file.

5.3.7.2

Output Values

MINIMUM

= first data block in the file (after

the

Prologue)

index is Primary

MAXIMUM

= last block in the file

*Based on physical ordering from the beginning of the file.

5-38

Key XAB:

DVB

the

*************

*
*
*

FLG

*
*
*

*************
5. 3. 8

FLG

The one-word Flags (FLG) field contains a bit string indicating
acteristics of the key described by the XAB.

5.3.8.1

char-

Use

Input to:
$CREATE
You set the FLG field to indicate the characteristics you
want associated with the key described by the REF field.
Output from:
$DISPLAY/$0PEN
RMS-11 sets the FLG field to indicate the key
tics established when the file was created.

characteris-

5.3.8.2 Input Values - The FLG field may contain one or more
following symbolic values:

the

XB$CHG

the value in the key field described by this XAB may be
changed during an update operation; valid only for Alternate Keys (REF field greater than 0) and in conjunction with XB$DUP

XB$DUP

more than one record within the file may have
value in the key field described by this XAB

XB$NUL

if the string key described by this XAB is completely
filled with the character in the NULL field or the integer, binary, or packed decimal key is zero, RMS-11
makes no entry in the index for the record; valid for
Alternate Keys only

Key XAB:

the

FLG

same

5-39

RMS-11 restricts the combination of XB$CHG and XB$DUP as follows:
Combination
Default

XB$CHG

Default

Key Type

XB$DUP

Default

XB$DUP

Default

Primary

Error

Allowed

Alternate

Allowed

Error

Allowed

A value can be set in the field with the initialization macro
below or with the $SET field access macro (see Chapter 7).

5.3.8.3

shown

Initialization and Default - Macro takes the form:

X$FLG symbolic[!symbolic[!symbolic]]
If there is no initialization macro, FLG

= O, meaning:

•

For Primary Key, duplicate keys are not allowed.

•

For Alternate Keys
duplicate keys allowed
key values may change during update operation
no null key value

5.3.8.4
•

Comments

At all times, for Primary Keys:
key values cannot change during update operation
no null key values

•

Since the FLG field is a bit string, values cannot be added to
the
field with the $STORE field access macro.
You should use the $SET
field access macro (see Chapter 7).
However, you use the $STORE
macro to (re)set all bits in the field.

5-40

Key XAB:

FLG

*************

*
*
IAN
*
*
***************
5.3.9

IAN

The one-byte Index Area Number (IAN) field contains the number of the
file area in which Levels 2+ of the index described by this XAB are
(or w:ill be) stored.

5.3.9.1

Use

Input to:
:$CREATE
If you are not creating a multi-area file*, that is, no
• or
one Allocation XAB, ensure that the IAN field is zero
(the default) •
•

If you are creating a multi-area file, that is, there are
multiple Allocation XABs also linked to the FAB, set the
IAN field to the number of the area in which you want the
index levels two and up of this index (set by REF field)
stored. This number must be the same as the AID field of
one of the Allocation XABs.

Output from:
$DISPLAY/$0PEN
RMS-11 sets the IAN field equal to the area in which Levels
2+ of the index indicated by the REF field are stored.

5.3.9~2

MINIMUM
MAXIMUM

Input Values

= O, meaning Area O*
=

254, meaning the maximum possible area that may be
allocated; however, the maximum within each program is
restricted to the highest number in an Allocation XAB
AID field

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

shown

*If there are no Allocation XABs, the entire file is in Area O.
Key XAB:

IAN

5-41

5.3.9.3

Initialization and Default - Macro takes the form:

X$IAN numeric
If there is no initialization macro, IAN = O.

5-42

Key XAB:

IAN

*************
*
*

*
*

!BS

*
*

*************

5.3.10

!BS

The one-byte Index Bucket Size (!BS)
field contains the number of
blocks in a bucket in the one or two file areas that contain Levels l+
of the index described by this XAB.

5.3.10.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the IBS field equal to the bucket size of the
area(s)
established for Levels l+ of this index when the
file was created.

5.3.10.2

Output Values

MINIMUM = 1
MAXIMUM

= number of blocks allowed by the operating system

Key XAB:

IBS

5-43

*************

*
*
!FL
*
*
***************
5.3.11

!FL

The one-word Index Bucket Fill Number (IFL)
contains the number of
bytes in each bucket of this index's Levels l+ that should be used to
store index information if the RAB ROP field contains RB$LOA when the
Record Access Stream is set up ($CONNECT);
if RB$LOA is not set,
RMS-11 ignores the fill number.
See the RMS-11 User's Guide for a
discussion of fill numbers.

5.3.11.1

Use

Input to:
$CREATE
You set the !FL field-equal to the number of bytes you want
filled in each Levels l+ bucket when RMS-11 is honoring fill
numbers~

Output from:
$DISPLAY/$0PEN
RMS-11 sets the !FL field equal to fill
number established
for
Levels l+ of the index designated by the REF field when
the file was created.

5.3.11.2
MINIMUM

Input Values

= O, meaning the buckets should be completely

filled

regard-

less of the value in the RAB ROP field
= half of the bytes in the bucket;

this is a logical m1n1mum,
meaning you can specify less, but RMS-11 ignores it, supplying its own 50% figure

MAXIMUM

= total number of bytes in a bucket less one record (including

overhead);
this is a logical maximum;
the physical maximum
(total number of bytes in a bucket) can be achieved by specifying zero

You can figure the number of bytes in a bucket as follows:
NRBKT

= 512*BKS

where BKS is the bucket size, expressed in blocks.

5-44

Key XAB:

!FL

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.11.3

shown

Initialization and Default - Macro takes the form:

X$IFL numeric
If there is no initialization macro, !FL

= O.

""-"'
Key XAB:

!FL

5-45

*************
*
*

*
*

KNM

*
*

*************

5.3.12

KNM

The one-word Key Name Address (KNM) field points to an ASCII string
that is associated with the key described by this XAB.
RMS-11 does
not use this field for processing, but does store it in the file Prologue during a create operation and outputs it during $DISPLAY and
$OPEN.
The RMSDSP utility also prints out this string (see the RMS-11
User's Guide).

5.3.12.1

Use

Input to:
$CREATE
If you want to associate a name or other identification with
the key described by this XAB, set the KNM field equal to
the address of that name.
$DISPLAY/$0PEN
•

If you do not want to provide a 32-byte buffer to hold
the key name string, you set the KNM field to zero;
RMS-11 does not output the key name.

•

If you are providing a buffer for the key name string,
you set the KNM field equal to the buffer's address.
·~.

5.3.12.2

Input Values - The KNM field must contain either:

= no ASCII key name string

•

zero (0)

•

address of an ASCII string;
starting with this location:
during $CREATE, be sure
blanks) for that length

RMS-11
that

you

reads

and

writes

bytes

have

valid

data

(if

only

during $DISPLAY and $OPEN, be sure that the indicated buffer is
at least 32 bytes long or the key name will overlay other data
or instructions
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5-46

Key XAB:

KNM

shown
~

5.3.12.3

Initialization and Default - Macro takes the form:

X$KNM label
;~

If th E~ re i s no in i t i a 1 i z at ion mac r o , KN M = 0 •

Key XAB:

KNM

5-47

*************

*
*

LAN

*************

5.3.13

LAN

The one-byte Lowest Index Level Area Number (LAN) field contains the
number of the file area in which Level 1 of the index described by
this XAB is (or will be) stored.

5.3.13.1

Use

Input to:
$CREATE
If you are not creating a multi-area file*, that is, no
• or
one Allocation XAB, ensure that the LAN field is zero
(the default).
•

If you are creating a multi-area file, that is, there are
multiple Allocation XABs also linked to the FAB, set the
LAN field to the number of the area in which you want the
index level one of this index (set by REF field) stored.
This number must be the same as the AID field of one of
the allocation XABs.

Output from:
$DISPLAY/$0PEN
RMS-11 sets the LAN field equal to
Level 1 of the index indicated
stored.

5.3.13.2
MINIMUM

the area in which
by the REF field is

Input Values

= O, meaning the same area as the rest of

the

index

(Levels

2+), not necessarily Area 0

= 1, lowest area number that can be specifically identified
MAXIMUM

= 254, meaning the maximum possible areas that may be allocat-

ed;
however, the maximum within each program is restricted to the highest number in an Allocation XAB AID
field

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5-48

Key XAB:

LAN

shown

5.3.13.3

Initialization and Default - Macro takes the form:

X$LAN numeric
'~

If the re is no initialization macro, LAN = 0.

5.3.13.4 Comments - The bucket size for the area containing Level 1
of an index must be the same as the bucket size for the area containing the rest of the index (Levels 2+).

Key XAB:

LAN

5-49

*************

*
*
*

LVL

*
*

*************
5.3.14

LVL

The one-byte Root Level (LVL) field contains the level number of the
Root bucket of the index described by this XAB.
This number is one
less than the depth of the index.

5.3.14.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the LVL field equal to the number of the
index
level of the Root bucket for the index identified by the REF
field.

5.3.14.2

Input Values

MINIMUM = 1, meaning that the index is the shallowest possible,
one level of data and one level of index, the Root
MAXIMUM

with

= no logical limit

5-50

Key XAB:

LVL

*************

*
*
*

MRL

*
*
*

*************

5.3.15

MRL

The one-word Minimum Record Length (MRL) field contains the length, in
bytes, that a record must be to include the key described by the XAB.

5.3.15.1

Use

Output from:
~iDISPLAY/$0PEN

RMS-11 sets the MRL field to the number of bytes in the
shortest record
that can contain the key identified by the
REF field.

5.3.15.2 Output Values - The value in the MRL field is based on the
key's position (specified by the POS field) and the key's length (indicated by the SIZ field) •
In a single-segment key, the sum of the
two provides the minimum record length.
However, in a multi-segment
key, the pertinent segment is the one farthest from the beginning of
the record.
The starting position of that segment, plus its length,
determine the minimum length record.

5.3.15.3
•

•

Comments

If the index described by the XAB is the Primary index, then no record smaller than the MRL value can be written to the file;
RMS-11
returns error code ER$RSZ.
If the index described by the XAB is an Alternate
index,
then if
record
is shorter than the MRL, RMS-11 makes no entry in the
index for the record.

the~

Key XAB:

MRL

5-51

*************

*
*
*

NSG

*
*
*

*************

5.3.16

NSG

The one-byte Number of Key Segments (NSG) field contains the number of
segments specified
in the key described by the XAB when the file was
created.
The POS and SIZ fields contain this number of values.

5.3.16.1

Use

Output from:
$DISPLAY/$0PEN
RMS-11 sets the NSG field equal to the number of
and lengths it finds in the POS and SIZ fields.

5.3.16.2

Input Values

MINIMUM = 1
MAXIMUM

Only string keys will have NSG values greater than 1.

5-52

Key XAB:

NSG

positions

*************

*
*
NUL
*
*
***************

5.3.17

NUL

The one-byte Null Key Character (NUL) field contains the binary representation of the null key character for the key described by this XAB.
This field is valid for string Alternate Keys only (REF field greater
than 0).
See the RMS-11 User's Guide for a discussion of null key values.

5.3.17.1

Use

Input to:
$CREATE
You set the NUL field equal to the character or code you
want used as the null key character for this key; you
should also put the symbolic value XB$NUL in the FLG field.
Output from:
$DISPLAY/$0PEN
RMS-11 sets the NUL field equal to the null key value
blished when the file was created.

"-""

esta-

5.3.17.2 Inpµt Values - RMS-11 uses the NUL field only if the FLG
field contains XB$NUL and the key is a string data type;
if both are
true, the NUL field must contain* a binary number whose octal value
ranges from 000 to 377.
You may represent an ASCII character (via the
MACR0-11 single-quote (') convention) or a non-ASCII octal value.
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.17.3

shown

Initialization and Default - Macro takes the form:

X$NUL value
where value is a valid MACR0-11 representation of a one-byte value.
If there is no initialization macro, NUL

= O.

*If one of these conditions is false, the NUL may contain
the recommended value in that case is the default, zero.
Key XAB:

any
NUL

value;
5-53

5.3.17.4
•

Examples

The following code specifies a null key value of
key:
KEYDEF: XAB$B

XB$KEY

X$DTP

XB$STG

X$FLG
X$NUL

XB$NUL
I

for

string
~

XAB$E
•

The following code specifies the null key feature for a string key,
but the null key value is the ASCII character DEL:
KEYDEF: XAB$B

.
X$DTP
.

X$FLG
X$NUL

XB$KEY
·~

XB$STG
XB$NUL
"177

XAB$E
•

The following code specifies the null key feature for a packed
cimal key; however, no null key value is necessary:
KEYDEF: XAB$B

XB$KEY

X$DTP

XB$PAC

.
X$FLG

XB$NUL

......

XAB$E

5-54

Key XAB:

de-

NUL

*************

*
*
*

NXT

*
*
*

*************

5.3.18

NXT

5.3.18.1

Use

Input to:
$CREATE/$DELETE/$EXTEND/$0PEN

5.3.18.2
'-""

•

If you have allocated another XAB and want RMS-11 to
use
it, you set the NXT field equal to the address of that
XAB.

•

If you have not allocated an XAB and/or you want the XAB
chain to end here,
set the NXT field equal to zero;
otherwise, RMS-11 interprets the value in the field as an
address and tries to use the area indicated as an XAB:
if that area is not a valid XAB, RMS-11 returns the error
code ER$XAB.

Input Values - The NXT field must contain either:

•

zero (0) = there are no more XABs in this chain

•

address of an Extended Attribute Block separately allocated in
program

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.18.3

the
shown

Initialization and Default - Macro takes the form:

X$NXT label
If there is no initialization macro, NXT = O.

Key XAB:

NXT

5-55

*************

*
*
*

POS

*
*
*

*************

5.3.19

POS

The eight-word Key Position (POS) field contains the starting positions within the record for all segments of the key described by this
XAB.
Combined with the SIZ and DTP fields, the POS field
completely
defines the key.
An RMS-11 key string may contain from one to eight segments;
all
other key types require a single segment.
Each word in the POS field
specifies the starting position of a segment:
the
first word,
the
first
segment,
the second word, the second segment, and so on.
Each
segment must be contiguous, but the segments do not have to be contiguous with each other. When processing records, RMS-11 combines the
individual segments and treats them as a single, logically contiguous
string beginning with the first segment and ending with the last.
See
also the RMS-11 User's Guide discussion of segmented keys.

5.3.19.1

Use

Input to:
$CREATE
You set the POS field to include the starting position of
each segment in the key described by this XAB.
See "Comments" for $STORE syntax.
Output from:
$DISPLAY/$0PEN
RMS-11 sets the POS field to include starting
positions
the key segments established when the file was created.

5.3.19.2 Input Values - The POS field must contain at least one
eric value in the range:
MINIMUM = O, meaning the segment starts in the first byte of
cord
MAXIMUM

= 65535, meaning the segment starts in the last

byte

num-

the

re-

the

largest possible record
If a string key has multiple segments, you must specify a starting position for each segment, each within the above range, using the form:
<segO,segl [,seg2, ••• ,seg7]>
5-56

Key XAB:

POS

The values do not have to represent ascending byte
record.

positions

the

A value can be set in the field with the
initialization macro
shown
below or with the $STORE field access macro (see "Comments" below and
Chapter 7).

5.3.19.3

Initialization and Default - Macro takes the form:

X $Po S

[ <] n um e r i c [ , n um er i c , • • • >]

If there is no initialization macro, POS

5.3.19.4
•
'-"

= O.

Comments

You may store or fetch the position of an individual segment in the
POS field, by using the term
PO Sn
where n is an integer in the range 0 to 7, indicating
number whose position you want to affect.
Example

the

segment

You want to check the starting position of the third segment of a key string:
$FETCH RO,POS2,R4
You want to reset the starting position of the first segment of a key string:
$STORE RO,POSO,R4
In both cases, RO is used as a buffer
number.

for

the

Key XAB:

position

POS

5-57

*************

*
*
*

REF

*
*

*************

5.3.20

REF

The one-byte Key of Reference (REF)
described by this XAB.

5.3.20.1

field identifies the index and key

Use

Input to:
$CREATE/$EXTEND
You set the REF field to tell RMS-11 exactly
index you are describing in the XAB.

what

key

and

$DISPLAY/$0PEN
You set the REF field to tell RMS-11 exactly what
index you want RMS-11 to describe in the XAB.

key

and

second,

and

5.3.20.2
MINIMUM

Input Values

= O, meaning Primary Key

MAXIMUM - 254
All values from 1 to 254 indicate Alternate Keys, first,
so on.

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.20.3

Initialization and Default - Macro takes the form:

X$REF numeric
If there is no initialization macro, REF = O.

5-58

Key XAB:

REF

shown

*************

*
*

RVB

*
*
*

*************

5.3.21

RVB

The two-word Root Virtual
Block Number
(RVB)
field
specifies the
number of the file's virtual block that contains the Root of the index
represented by this XAB.

5. 3. 21.1

Use

Output from:

'"-I

~?DISPLAY/$0PEN

RMS-11 sets the RVB field equal to the number of the
first
virtual
block of the Root bucket for the index indicated by
the REF field.

5.3.21.2
MINIMUM

Output Values -

= first data block of the file, after the Prologue

MAXIMUM = last block of the file
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

Key XAB:

RVB

shown

5-59

*************

*
*
*

SIZ

*
*

*************

5.3.22

SIZ

The eight-byte Key Size (SIZ) field contains the lengths, in bytes, of
all
segments of the key described by this XAB.
Each byte in the SIZ
field specifies the size of a segment:
the first byte, the first segment, second byte,
the second segment, and so on.
There must be a
length specified for each segment given a starting position in the POS
field.

5.3.22.1

Use

Input to:
$CREATE
You set the SIZ field to include the length of each segment
in the key described by this XAB.
See "Comments" for $STORE
syntax.
Output from:
$DISPLAY/$0PEN
RMS-11 sets the.SIZ field to include lengths of the key segments established when the file was created.

5.3.22.2 Input Values - The SIZ field must contain at least one numeric value which depends on key data type (specified by the DTP field
in this XAB), as follows:

• 15-bit Signed Integer Key Type, SIZ = 0 or 2
• 31-bit Signed Integer Key Type, SIZ = 0 or 4
• 16-bit Unsigned Binary Key Type, SIZ = 0 or 2
• 32-bit Unsigned Binary Key Type, SIZ = 0 or 4
• String Key Type
MINIMUM

MAXIMUM

= 255

(null segment)

·""
5-60

Key XAB:

SIZ

If a string key has multiple segments, you must
for each segment, using the form:

specify

length

<len0,lenl[,len3, ••• ,len7]>
The sum of the multiple lengths cannot exceed 255.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.3.22.3

shown

Initialization and Default - Macro takes the form:

X$ S I Z [ < ] n um er i c [ , n um er i c , • • • > ]

If there is no initialization macro, SIZ = O.

5.3.2:2.4
•

Examples

The following code specifies a single-segment key eight bytes long:
KEYDEF: XAB$B

X$SIZ

XB$KEY
8•

XAB$E
•

The following code specifies a key
their sizes and positions:
KEYDEF: XAB$B
X$SIZ
X$POS

with

four

segments,

defining

XB$KEY
<8,2,5,32>
<19,0,13,28>

XAB$E

5.3.22.5 Comments - You may store or fetch the length of an individual segment in the SIZ field, by using the term
SI Zn
where n is an integer in the range 0 to 7,
indicating
number whose length you want to affect.

the

Key XAB:

segment

SIZ

5-61

Example

You want to check the length of the third segment of
string:

key

$FETCH RO,SIZ2,R4
You want to reset the length of the first segment of
string:
$STORE RO,SIZO,R4
In both cases, RO is used as a buffer for the length.

5-62

Key XAB:

SIZ

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .lmtll

*************

*
*
*

TKS

*
*

*************

5.3.23

TKS

The one-byte Total Key Size (TKS) field specifies the number of
contained in all segments of the key described by the XAB.

5.3.23.1

bytes

Use

Output. from:
~;DISPLAY/$0PEN

RMS-11 sets the TKS field equal to the sum of the segment
lengths established via the SIZ field for the key indicated
by the REF field.

5.3.23.2

Input Values

MINIMUM = 1
'-""'

MAXIMUM = 255

Key XAB:

TKS

5-63

5.4

Protection Extended Attribute Block

The Protection XAB describes the protection code of a file,
including
specifications for the owner's account number~
You use a Protection
XAB generally when you do not want the default protection value for
the operating system applied to the file.
Protection XABs are used as:
Input to $CREATE and $CLOSE
For an RMS-11 file of any organization, you may set its protection code when it is created and change that code when it
is closed.
Output from $DISPLAY and $OPEN
RMS-11 supplies the current protection value for the file.
Table 5-4:

Protection Extended Attribute Block Fields

Field
Name

Field
Size

Default

BLN
COD
NXT
PRG
PRJ
PRO

lB
lB
lW
lW
lW
lW

N/A
N/A

5-64

0
0
0
0

Protection XAB:

Description
PRO XAB length
XAB type
Next XAB
Programmer part of account number
Pro j ec t pa rt o f account number
File protection value

Introduction

*************

*
*
*
*
*************

5.4.1

BLN

The XA.B$B macro sets the one-byte Block Length (BLN) field to the
tended Attribute Block length.

Ex-·

CAUTION
DO NOT CHANGE THE BLN FIELD.

5. 4. 1.. 1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the BLN field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$BLN error code.

Protection XAB:

BLN

5-65

*************
*
COD
*
*
*
*************

*
*

5.4.2

COD

The XAB$B macro sets the one-byte Code (COD) field to the Extended Attribute Block type, with the symbolic value of XB$PRO.
CAUTION
DO NOT CHANGE THE COD FIELD.

5.4.2.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the COD field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$COD error code.

5-66

Protection XAB:

COD

*************

*
*
*

NXT

*
*
*

*************

5. 4. 3

NXT

5.4.3.1

Use

Input to:
$CREATE/$DELETE/$EXTEND/$0PEN

5.4.3.2
·~

•

If you have allocated another XAB and want RMS-11 to use
it, you set the NXT field equal to the address of that
XAB.

•

If you have not allocated an XAB and/or you want the XAB
chain to end here, set the NXT field equal to zero;
otherwise, RMS-11 interprets the value in the field as an
address and tries to use the area indicated as an XAB:
if that area is not a valid XAB, RMS-11 returns the error
code ER$XAB.

Input Values - The NXT field must contain either:

•

ze r o ( 0 ) == there are no more XAB s in this cha in

•

address of an Extended Attribute Block separately allocated in
program

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.4.3.3

the
shown

Initialization and Default - Macro takes the form:

X$NXT label
If there is no initialization macro, NXT = O.

Protection XAB:

NXT

5-67

*************

*
*
*

PRG

*************

5.4.4

PRG

The one-word Programmer Number (PRG) field contains the second
in the file owner's account number pair.

5.4.4.1

number

Use

Input to:
$CLOSE/$CREATE
You set the PRG field to the individually unique
the owner of the file.

number

Output from:
$DISPLAY/$0PEN
RMS-11 sets the PRG field to the individually unique
of the file owner it reads from the file directory.

number
~.

5.4.4.2

Input Values

MINIMUM

= 0, meaning the default programmer number, based on

the

ac-

count in which the program is currently running

= 1, the smallest programmer number you can identify
MAXIMUM = 255
The programmer number specified in the Protection XAB must agree with
the programmer number specified in the filespec indicated by the FAB
FNA field or in the default name string
indicated by the FAB DNA
field.
A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.4.4.3

Initialization and Default - Macro takes the form:

X$PRG numeric
If there is no initialization macro, PRG = O.

5-68

Protection XAB:

PRG

shown

*************

*
*
*

PRJ

*************

5.4.5

PRJ

The one-word Project Number (PRJ) field contains the first
the file owner's account number pair.

5.4.5.l

number

You set the PRJ field to the group or project number of
owner of the file.

the

Use

Input to:
~:c LOSE/$CREATE

Output from:
~;DISPLAY/$0PEN

RMS-11 sets the PRJ field to the group or project number
the file owner it reads from the file header.

5.4.5.2

Input Values

MINIMUM = 0, meaning the default project number, based on the
in which the' program is currently running

account

= 1, the smallest project number you can identify

MAXIMUM

= 255

The project number specified in the Protection XAB must agree with the
project number specified
in the filespec indicated by the FAB FNA
field or in the default name string indicated by the FAB DNA field.
A value can be set in the field ~ith the initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.4.5~3

shown

Initialization and Default - Macro takes the form:

X$PRJ numeric
If there is no initialization macro, PRJ =

·~·

Protection XAB:

PRJ

5-69

*************
*
*

*
*

PRO

*
*

*************

5.4.6

PRO

The one-word System File Protection Code (PRO) field contains the system-specific code that indicates the access relationship allowed for
the file represented by the FAB linked to this XAB.

5.4.6.1

Use

Input to:
$CREATE
You set the PRO field to the protection code
access to the file as you want it.

·~.
that

controls

Output from:
$DISPLAY/$0PEN
RMS-11 sets the PRO field equal to the protection code found
in the file directory.

5.4.6.2 Input Values - Specific protection values depend on operating
system standards:
•

IAS/RSX-llM
The file protection value identifies the file access privileges
four classes of users:
group

those accounts with the project
the PRJ field of this XAB

owner

that account with the project and
contained in this XAB

system

privileged accounts

world

all accounts not in the other categories

The PRO field assumes the following format:
1

I WORLD I GROUP I OWNER I SYSTEM I

5-70

Protection XAB:

PRO

number

contained

programmer

of
~

numbers

Each of the categories is allocated four bits, with
meanings with respect to file access:
bit

I DELETE

I EXTEND

I WRITE

the

following

READ

If a bit is not set (zero), the respective type of access to
the
file
is allowed;
if the bit is set (one), that type of access is
denied.
You should use a numeric value for that PRO field that sets the appropriate bits;
this number may be decimal, octal, or binary,
though using the MACR0-11 octal radix unary operator makes it easiE~r.

•

RS~rS/E

The file protection value identifies the file access privileges
three classes of users:
group

those accounts with the project
the PRJ field of this XAB

number

owner

that account with the project and
contained in this XAB

others

all accounts not in the owner or group categories

contained

programmer

numbers

The value of the PRO field is the numeric sum of one or more of the
following codes:
1

read protect against owner

write protect against owner

read protect against everyone in group except owner

write protect against everyone in group except owner

read protect against others

write protect against others

See also your operating system documentation about protection codes.
A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.4.6~3

shown

Initialization and Default - Macro takes the form:

X$PRO numeric
If there is no initialization macro, PRO

= O.
Protection XAB:

PRO

5-71

5.5

Summary Extended Attribute Block

The Summary XAB generally describes an Indexed file,
including the
number of keys and areas established for the file when it was created.
Summary XABs may also be used for Relative files if you want to determine their prologue version number.
Summary XABs are used as output only during $DISPLAY and $OPEN
tions.
Example

opera-

You want to open an Indexed file, but you don't know anything about its keys or areas, including their number.
You
therefore do not know how many Key or Allocation XABs to
link to the FAB before you issue the $OPEN macro.
You can,
however, link a Summary XAB to the FAB and initiate an open
operation.
You then examine the NOA and NOK fields of the
Summary XAB to determine how many of the other XABs you need
for a $DISPLAY macro.

Table 5-5:

Summary Extended Attribute Block Fields

Field
Name

Field
Size

Default

BLN
COD
NOA
NOK
NXT
PVN

lB
lB
lB
lB
lW
lW

N/A
N/A
0
0
0
0

Description
SUM XAB length
XAB type
Number of areas
Number of keys
Next XAB
RMS-11 Prologue version number

·""·

5-72

Summary XAB:

Introduction

*************
*
*
BLN

*
*
*************

*
*

5.5.1

BLN

The XAB$B macro sets the one-byte Block Length (BLN) field to the
t.ended Attribute Block length.

Ex-

CAUTION
DO NOT CHANGE THE BLN FIELD.

5.5.1.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB; one of the checks examines
the BLN field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$BLN error code.

Summary XAB:

BLN

5-73

*************

*
*
*

COD

*
*
*

*************

5.5.2

COD

The XAB$B macro sets the one-byte Code (COD) field to the Extended Attribute Block type, with the symbolic value of XB$SUM.
CAUTION
DO NOT CHANGE THE COD FIELD.

5.5.2.1 Use - Before RMS-11 uses an XAB during a file operation,
it
verifies that the block is a valid XAB;
one of the checks examines
the COD field.
If this field does not contain the proper code, RMS-11
aborts the operation with a ER$COD error code.

5-74

Summary XAB:

COD

*************

*
*
*

NOA

*
*

*************

5.5.3

NOA

The one-byte Number Of Areas (NOA) field contains the number of file
areas that were created in the file represented by the linked FAB.

5.5.3.1

Use - The NOA field is only applicable to Indexed files.

Output from:
$lDISPLAY/$0PEN
RMS-11 sets the NOA file equal to the number of areas in the
file associated with the XAB.

5.5.3.2

Output Values

MINIMUM = 1
MAXIMUM

= 254

Summary XAB:

NOA

5-75

*************

*
*

NOK

*
*
*

*************

5.5.4

NOK

The one-byte Number Of Keys (NOK) field contains the number
that were created in the file represented by the linked FAB.

5.5.4.1

keys

Use - The NOK field is only applicable to Indexed files.

Output from:
$DISPLAY/$0PEN
RMS-11 sets the NOK file equal to the number of keys in
file associated with the XAB.

5.5.4.2

Output Values

MINIMUM - O, meaning a Relative file
1, minimum number of keys for an Indexed file
MAXIMUM -- 255

5-76

Summary XAB:

NOK

the

*************

*
*
*

NXT

*
*

*
*************

5. 5. 5

NXT

5.5.5 .. 1

Use

Input to:
$CREATE/$DELETE/$EXTEND/$0PEN

5.5.5~2

•

If you have allocated another XAB and want RMS-11 to
use
it,
you set the NXT field equal to the address of that
XAB.

•

Input Values - The NXT field must contain either:

•

zero (0) = there are no more XABs in this chain

•

address of an Extended Attribute Block separately allocated in
program

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

5.5.5.3

the
shown

Initialization and Default - Macro takes the form:

X$NXT label
If there is no initialization macro, NXT

= 0.

Summary XAB:

NXT

5-77

*************

*
*
*

PVN

*
*
*

*************

5.5.6

PVN

The one-word Prologue Version Number (PVN)
Prologue version number.

field contains

5.5.6.1 Use - The PVN field is only applicable to
dexed f i 1 es.

the

Relative

RMS-11

and

In-

Output from:
$DISPLAY/$0PEN
RMS-11 sets the PVN field equal to
the version number
it
finds
in the
file Prologue,
if the Summary XAB is long
enough to contain this field (see "Comments").

5.5.6.2

Output Values -

MINIMUM

= 1, for Relative files and Indexed files with string keys

MAXIMUM = 2, for Indexed files with nonstring keys

5.5.6.3 Comments - RMS-11 fills in the PVN field if the Summary XAB
is long enough to contain it.
The XAB won't be long enough if you assembled your program using RMS-11 Vl.O RMSLIB.MAC and then task built
it using RMS-11 Vl. 5 RMSLIB.OLB.

5-78

Summary XAB:

PVN

CHAPTER 6
NAME BLOCK

The initialization macros (this chapter) and the field access macros
(Chapter 7) are provided so that you do not have to know the specific
position and to a large extent, the size of each field in a NAM Block.
You can, therefore, treat the fields as logical entities. It is also
possible that the positions and sizes of the fields will change from
release to ~elease of RMS-11.
However, you can determine the position of any field in a NAM as an
offset from the NAM's starting address. RMS-11 represents these offset values with symbols in following form:
O$fnm
where fnm is the three-letter name of a NAM Block field;
fnm is the
name used to reference the field in the initialization and field access macros.
Example

O$ESA for the expanded string address field

The v.alues of these symbols can be found in the symbol table of an assembly listing file for any module containing the FAB.
~

Table 6-1:

NAM Block Fields

Field
Name

Field
Size

Default

DVI
ESA
ESL
ESS
FID

lW
lW
lB
lB
lB

0
0
0
0
0

Description
Device ID
Expanded string address
Expanded string length
Expanded string size
File ID

*************

*
*
*

DVI

*
*
*

*************

6. 1

DVI

The three-word Device ID (DVI) field contains a
code that the
file
processor can use in conjunction with a file ID to locate a file without consulting device directories.

6. 1. 1

Use

Input to:

$ERASE/$0PEN
You set the NAM DVI field equal to a device ID value RMS-11
provided during a previous create or open by file specification operation.
You must also set the NAM FID field
equal
to the file ID returned during the same operation as well as
storing FB$FID in the FAB FOP field.
Output from:
$CREATE/$0PEN by file specification
RMS-11 sets the DVI field equal to the code the file processor provides during the open by file specification process.

6.1.2

Input Values

You should make no attempt to analyze or change the device ID provided
by RMS-11.
Store the contents of the NAM DVI field as a three-word
quantity and supply it as such when you execute an erase or open by
file ID operation.

6-2

NAM Block (NAM) :

DVI

*************

*
*

ESA

*
*
*

*************

6.2

E:SA

The Expanded String Address (ESA) field
contains the address of a
buffer
that you have allocated.
During an open, create, or erase operation, RMS-11 places in this buffer the
file
specification string
resulting from the application of default information (provided by the
default name string of the FAS and system defaults)
to
the primary
file name string of the FAS.
The ESA buffer must be present if the FAS NAM field is not zero.
NOTE
The NAM ESA field and the expanded string buffer are not required or used during an open or erase by file ID operation.

6.2.1

Use

Input to $CREATE/$ERASE/$0PEN:
You set the ESA field equal to the address of a buffer where
want RMS-11 to store the full file specification.

6.2.2

you

Input Values

ESA must contain either:

•

zero
(0)
=
there
is no
file specification buffer
o pE! rat ion ;
valid only for open and erase by file ID

•

address of the first byte of a buffer for the full file
tion;
the buffer does not have to be word-aligned

for

specifica-

A value can be set in the field with the
initialization macro
below or with the $STORE field access macro (see Chapter 7).

6.2.3

this

shown

Initialization and· Default

Macro takes the form:
N$ESA address
If there is no initialization macro, BKS

= O.
NAM Block (NAM) :

ESA

6-3

*************

*
*
*

ESL

*
*
*

*************

6. 3

ESL

The one-byte Expanded String Length (ESL) field
contains the actual
length of the full file specification RMS-11 stored beginning with the
address in the NAM ESA field.

6.3.1

Use

Output from:
$CREATE/$ERASE/$0PEN by file specification
RMS-11 sets the ESL field equal to the size in bytes of the
expanded file specification resulting from the operation.

6-4

NAM Block (NAM) :

ESA

*************

*
*

ESS

*
*
*
*************
6.4

ESS

The one-byte Expanded String Size (ESS) field contains the size of the
buffer whose address you stored in the NAM ESA field.

6.4.1

Use

Input to:
$CREATE/$ERASE/$0PEN
You set the ESS field equal to the size of the buffer
you want RMS-11 to store the full file specification.

'-'1

6.4.2

Input Values

MINIMUM

MAXIMUM

= 255

A value can be set in the field with the initialization macro
below or with the $STORE field access macro (see Chapter 7).

6.4.3
-~

where

shown

Initialization and Default

Macro takes the form:
N$ES S n um er i c
If there is no initialization macro, ESS = O.

NAM Block (NAM) :

ESS

6-5

*************

*
*
*

FID

*
*
*

*************

6.5

FID

The three-word File ID (FID) field contains a code that the file
processor can use in conjunction with a device ID to locate a file without consulting device directories.

6.5.1

Use

Input to:
$ERASE/$0PEN
You set the NAM FID field equal to a file
ID value RMS-11
provided during a previous create or ~pen by file specification operation.
You must also set the NAM D~I
field
equal
to
the device ID returned during the same operation as well
as storing FB$FID in the FAB FOP field.
Output from:

$CREATE/$0PEN by file specification
RMS-11 sets the FID field equal to the index the
file
processor provides during the open by file specification process.

6.5.2

Input Values

You should make no attempt to analyze or change the File ID provided
by RMS-11.
Store the contents of the NAM FID field as a three-word
quantity and supply it as such when you execute an erase or open by
file ID operation.

6-6

NAM Block (NAM) :

FID

l•W·_ _ _ _ _ _ _ _ _ _ _ _ _ _. , __ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ .

CHAPTER 7
FIELD ACCESS MACROS

RMS-11 field access macro retrieve, modify, and test the contents of
fields
in the RMS-11 control blocks, FABs, RABs, and XABs, at run
time.
These macros enable you to treat the control block fields as
logical entities, without regard for the placement of the fields within the control blocks and to a large degree,
for
the sizes of the
fields.
Table 7-1 contains a summary of the available macros.
also described in a separate section of this chapter.

Each

macro

RMS-11 assumes octal radix for all numeric values used as operands for
the field access macros.
In all two-word fields containing numeric values, the
cant bits appear in the word with the lower address.
Table 7-1:

least

signifi-

RMS-11 Field Access Macros

Macro Name

Field Size

Function

$COMPARE

1 byte or 1 word

Compares the contents of
with a value yo u spec i f y •

$FE'I'CH

Any size

Copies the contents of a field into
a location you specify.

$OFE'

1 byte or 1 word

Resets one or more
bit string field.

$SE'l~

1 byte or 1 word

Sets one or more bits within a
string field.

$STORE

Any size

Copies the contents of a
you specify into a field.

$TESTBITS

1 byte or 1 word

Tests one or more bits within a bit
string field.

bits

field

within

a
bit

location

*************

*
* $COMPARE
*

*
*
*

*************

7.1

$COMPARE

The $COMPARE macro compares a one-byte or one-word control block data
field with a value you specify and sets the PDP-11 condition codes.

7.1.1

General Form
$COMPARE

source, fnm, reg

where source represents a value you want compared with the contents of
a control block data field.
You can express this operand
using any valid addressing mode.
The operand must be
word-aligned for comparison with one-word data fields.

fnm is the three-letter name of a one-byte or one-word field.
The assembler generates an error message if the name is
invalid for the block referenced by reg or if the
field
specified by fnm is a multiword field.
reg is a general register (RO through RS) loaded with the address of the control block containing
the specified
field.

7.1.2

Effect

The $COMPARE macro makes the syntax checks as described under "General
Form." Then, if the source operand is #0, the macro generates a TST or
TSTB instruction, according to the size of the field.
If the source
operand
is not #0, the macro generates a CMP or CMPB instruction appropriately, comparing the source operand with the specified field
as
an offset from the contents of the specified register.

At run time, condition codes are set according to the instruction generated.

7. 1. 3
•

Exam pl es

$COMPARE

#SU$SUC,STS,Rl

The contents of the STS field in the control block pointed to by Rl
are compared with the symbolic completion value SU$SUC.

7-2

Field Access Macros:

$COMPARE

""'

•

$COMPARE

2(Rl),RSZ,R5

The contents of the Record Size field in the RAB indicated by RS is
compared with the operand specified by indexed addressing mode.
$COMPARE #0,STS,Rl
• BGT
14$
;
CONTINUE IF SUCCESSFUL
BLT
JMP

ERRTN
TRUBLE

;

HANDLE ERROR IF THERE IS ONE
SOFTWARE IS IN A JAM

General register Rl points to the block controlling
the operation
just completed
(FAB for
file operations, RAB for record operations).
The program then branches according to the contents of the
STS field.

··~

Field Access Macros:

$COMPARE

7-3

*************

*
*
* $FETCH *
*
*
*************
7.2

$FETCH

The $FETCH macro copies the contents of a
control block data
field
into a location you specify.
This macro can be used to access a field
of any size.

7.2.1

General Form
$FETCH

destination,fnm,reg

where destination is a location within your program where you want the
contents of a control block field copied.
The following restrictions apply to this operand:
•

You cannot use immediate mode or any form of deferred
addressing mode:
the assembler generates
an error.

If fnm is POS or SIZ,
you cannot
• mode
addressing:
the assembler

use
register
generates an

error.
•

•

For multiword fields other than POS or SIZ,
use
register mode addressing carefully:
the $FETCH
macro uses successive registers as destination
operands for successive words of the data field;
it uses the register containing the control block
address
if the data field is long enough.
The
results are unpredictable.

For single- and multiword fields, the destination
location must be word-aligned.

fnm is the three-letter name of any field
within the
control block.
The assembler generates an error if
the name is invalid for the block referenced by reg.
To reference Key XAB SIZ and POS fields, you:

7-4

•

specify SIZ or POS to fetch all
eight words of
the
field.
The macro copies the words into successive locations beginning with the destination
yo u spec i f y •

•

specify SIZ or POS plus a numbher f:omdO throu?.h 7
to
fetch a single word from t e fiel • See Examples."

Field Access Macros:

$FETCH

·""

reg is a general register (RO through RS)
loaded with
the address of the control block containing the
source data field.

7.2.2

Effect

The $FETCH macro makes the syntax checks as described
under "General
Form.
Then,
the macro generates a MOVB or one or more MOV instructions, according to size of the field.
11

7. 2. 3
•

Examples

$FETCH

R2,RBF,R4

General register R4 contains the address of a RAB.
The macro copies the contents of that RAB's RBF field into general register R2.
•

$FETCH

8. (R3),MRN,Rl

General register Rl contains the address of a FAB.
The macro copies both words of that FAB's MRN field into successive words beginning with the specified location.
•

$FETCH

LSEG3,SIZ2,R5

General register RS contains the address of a Key XAB.
The macro
copies the length of the third key segment into the location labeled LSEG3.

Field Access Macros:

$FETCH

7-5

*************

*
*
* $OFF
*
***************
7.3

$OFF

The $OFF macro resets one or more bits within a one-byte
bit string data field.

7.3.1

one-word

General Form
$OFF

value, fnm, reg

where value is an expression or location specifying
the data field you want reset,

the

bits

within

fnm is the three-letter name of a one-byte or one-word
field.
The assembler generates an error message if the name is
invalid for the block referenced by reg or
if the
field
specified by fnm is a multiword field.
reg is a general register (RO through RS) loaded with the address of the control block containing the specified field.

7.3.2

Effect

The $OFF macro makes the syntax checks as described
under "General
Form." Then, the macro generates one or more BIC or BICB instructions,
according to size of the field.

7.3.3
•

Examples

$OFF

RB$KGE,ROP,R2

General register R2 contains the address of a RAB.
The macro operates on that RAB's ROP field, resetting the bit that specifies greater than or equal key match during a random record operation.

7.3.4

Comments

The $OFF macro resets individual bits.
You should
use the $STORE
macro instead if you want to clear an entire bit string field or reset
a value in a field not a bit string.

7-6

Field Access Macros:

$OFF

*************

*
*
*

$SET

*
*

*************

7.4

$SET

The $SET macro sets one or more bits within a one-byte or one-word bit
string data field~

7.4.1

General Form
$SET

"-""

value, fnm, reg

where value is an expression or location specifying
the data field you want set,

the

bits

within

fnm is the three-letter name of a one-byte or one-word
field.
The assembler generates an error message if the name is
invalid for the block referenced by reg or
if the
field
specified by fnm is a multiword field.
reg is a general register (RO through RS) loaded with the address of the control block containing the specified data
field.

7.4.2

Effect

The $OFF macro makes the syntax checks as described
under "General
Form." Then, the macro generates one or more BIS or BISB instructions,
according to size of the field.

7.4.3
e

$SET

Examples
FB$GET!FB$UPD,FAC,R4

General register R4 contains the address of a FAB.
The macro sets
bits within that FAB's FAC field indicating get and update operations will be performed on the associated file.
The $SET macro
is
executed before a $CREATE or $OPEN operation is initiated.
•

$SET

HB$EOF,ROP,Rl

General register Rl contains the address of a RAB.
The macro sets
the bit within that RAB's ROP field that specifies positioning to
end-of-file during the following $CONNECT record operation.

Field Access Macros:

$SET

7-7

7.4.4

Comments

The $SET macro sets individual bits.
instead if you want to:

$STORE

macro

•

set only the specified values in a bit string field, ensuring
no other bits remain set

that

•

set a value in a field not a bit string $STORE macro.

7-8

Field Access Macros:

$SET

You

should

the

*************
*
*

*
*

$STORE

*
*

*************

7.5

$STORE

The $STORE macro copies values from a location you specify into a control block data field.
This macro can be used to access a field of
any size.

7.5.1

General Form
$STORE

source, fnm, reg

where source represents a value or series of values you want stored in
a control block data field.
The following restrictions
apply to this operand:
e

You cannot use any form of deferred
the assembler generates an error.

addressing

mode:

Immediate mode addressing can be used only with
one-byte and one-word fields:
the assembler generates
an error.
If fnm is POS or SIZ, you cannot use register mode addressing:
the assembler generates an error.
•

For multiword fields other than POS or SIZ, use register mode addressing carefully:
the $STORE macro uses
successive registers as source operands for successive
words of the data field;
it uses the register containing the control block address if the data field is
long enough.
The results are unpredictable.

•

For single- and multiword fields, the source
must be word-aligned.

location

fnm is the three-letter name of any field within the control
block.
The macro changes all bytes in this field.
The
assembler generates an error if the name is invalid
for
the block referenced by reg.
To reference Key XAB SIZ and POS fields, you:
•

specify SIZ or POS to change all eight words of the
field.
The macro copies eight words from successive
locations beginning with the source location you specify.

Field Access Macros:

$STORE

7-9

•

specify SIZ or POS plus a number from 0 through 7
to
store a single word into the field.
See "Examples."

reg is a general register (RO through RS) loaded with the address of the control
block containing the source data
field.

7.5.2

il~

Effect

The $STORE macro makes the syntax checks as described
under "General
Form."
Then,
the macro generates a MOVB or one or more MOV instructions, according to size of the
field.
For multiword
fields,
the
macro generates a MOV instruction for each word in the field, beginning with the specified source location and
using
successive words
after that.

7.5.3
•

Examples

$STORE

O,ALQ,R3

General register R3 contains the address
clears that FAB's two-word ALQ field.
•

•

FAB.

The

macro

General register Rl contains the address of a
RAB.
stores the address of a FAB in that RAB's FAB field.

The

macro

$STORE

INPUT,FAB,Rl

23. ,SIZ2,Rl

General register Rl points to a Key XAB.
The macro changes
size of the third segment of the key defined by the XAB.

7-10

Field Access Macros:

$STORE

the

*************

*
*
* $TESTS ITS *

*************

7. 6

:$TES TB ITS

The $TESTBITS macro compares one or more bits within a one-byte or
one-word control
block data field with a value you specify and sets
the PDP-11 condition codes.

7.6.1

General Form
$TESTBITS

value,fnm,reg

where value is an expression or location specifying
the data field you want tested,

the

bits

within

fnm is the three-letter name of a one-byte or one-word
field
within a control block.
The assembler generates an error
message if the name is invalid for the block referenced by
reg or if the field specified by fnm is a multiword field.
reg is a general register (RO through RS) loaded with the address of the control block containing the specified data
fieldo

7.6.2

Effect

The $OFF macro makes the syntax checks as described
under "General
Form." Then, the macro generates one or more BIT or BITS instructions,
according to size of the field.

7. 6. 3

Exam pl es

$TJESTBITS

FB$UPD!FB$PUT,FAC,R3

General register R3 contains the address of a
FAB.
The macro
checks that FAB's FAC field to determine if the current program can
issue update or put operations.
If either or both bits are set,
condition code Z is not set;
if neither is set, code Z is set.

Field Access Macros:

$TESTBITS

7-11

CHAPTER 8
FILE AND RECORD OPERATION MACROS

8.1

FILE OPERATION MACROS

A file operation macro causes RMS-11 to perform an action related
to
an entire file.
The macro name indicates the type of operation performed.
The fields of the FAB associated with the macro in the calling sequence identifies the file and qualifies the operation.
Table 8-1 summarizes the RMS-11 file operation macros •
.,._.,,

Table 8-1:
Macro Name

RMS-11 File Operation Macros
Description

$CLOSE

Closes an open RMS-11 file so that your program
longer access its contents.

can

$CRJE:ATE

RMS-11 creates and opens an RMS-11 file as described
the associated FAB and XABs, if any.

$DISPLAY

Stores attributes of an existing RMS-11 file in FAB
XAB fields.

and

$ER1~SE

Deletes an existing RMS-11 file and removes its entry(s)
from a directory.

$EX'rEND

Increases the number of blocks allocated
file.

$0PlE:N

Opens an existing RMS-11 file, making its contents
ilable for processing.

RMS-11
ava-

***************
*
*

*
*

$CLOSE

*
*

***************

8. 1.1

$CLOSE

The $CLOSE macro closes an open RMS-11 file, making its contents unavailable to your program. The operation effectively disconnects all
the file's Record Access Streams;
if a stream has an outstanding I/O
request,
the close fails with the ER$ACT error code.
However, you
should shut down all streams with $DISCONNECT macros before initiating
a close operation.

8.1.1.1
space.

Buffer Requirements - One BDB and 512

bytes

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8.1.1.2

Input Fields -

FAB FOP (can contain FB$RWC to rewind a magtape file)
!FI
PRO XAB All fields

8.1.1.3

Output Fields -

FAB IFI (set to zero)
BPA (address of buffer area returned for your use)
BPS (size of buffer area returned for your use)
STS
STV

8-2

File Operation Macros:

$CLOSE

~
~

8.1.1.4

General Form -

$CLOSE

fab [,error]

where fab is the address of a File Access Block representing
RMS-11 file.

open

error is the address of a completion routine to be called
$CLOSE operation fails.

the

8.1.1.5

Comments -

•

Even if RMS-11 returns the ER$WER error code in the FAB STS
the file is closed and deaccessed.

field,

•

If you issue a record operation on
RMS-11 returns error code ER$ISI.

closed,

•

If your program operates as follows, be sure to detach the NAM
Block before initiating the $CLOSE macro:
RMS-11 destroys the NAM
FID field during close.

file

after

Program links NAM Block to FAB, then opens file by file specification.

Program closes file.

Program opens or erases file by file ID.

File Operation Macros:

$CLOSE

8-3

***************

*
*
*

$CREATE

***************

8. 1. 2

$CREATE

The $CREATE macro creates an RMS-11 file with the attributes you specify in a FAB and any XABs linked to that FAB, then makes the new files
available for processing by your program.
Key and Allocation XABs must be grouped
in densely ascending order
(see Section 5.0.3);
otherwise, RMS-11 returns the error code ER$0RD.
An illogical XAB type in the chain causes the ER$COD error code.
Example

Summary XAB.

Example

Key XAB for a Sequential file.

If no Allocation XABs are linked to the FAB, the create operation creates the file as a single area (Area 0), using data from the FAB
fields to control its processing.
However, if one or more Allocation XABs are linked to the FAB,
the
create operation ignores the FAB ALQ and BKS fields, creating the file
according to the values in the ALL XAB(s), establishing areas as specified.
If a NAM Block is linked to the FAB, RMS-11 provides the expanded file
specification of the new file.
The new file must be closed before your program terminates.

8.1.2.1
space.

Buffer Requirements - One BDB and 512

bytes

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8-4

File Operation Macros:

$CREATE

8.1.2.2
F,~B

'-""

Input
ALQ
BKS
BLS
BPA
BPS
DEQ
DNA
DNS
FAC
FNA
FNS
FOP
FSZ
LCH
MRN
MRS
NAM
ORG
RAT
RFM
RTV
SHR
XAB

FiE~lds

(ignored if Allocation XABs linked)
(ignored if Allocation XABs linked)
(magnE~tic tape files only)
(used when no ALL XABs or ALL XAB DEQ field is zero)
(must contain at least FB$PUT)

(VFC records only)
(Relative files only)

ALL XAB All fields
KEY XAB All fields
~

PRO XAB All fields

8.1.2.3

Output Fields -

FAB DEV
!FI
STS
STV
NAM DVI
ESA
ESL
FID

8.1.2.4

General Form -

$CREATE

~··

rab [,error]

where, rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$CREATE operation fails.

the

$CREATE

8-5

File Operation Macros:

***************

*
*

$DISPLAY

*
*

***************

8. 1. 3

$DISPLAY

The $DISPLAY macro causes RMS-11 to store attribute
an open file in XAB fields.

information

from

Key and Allocation XABs must be grouped in ascending order (error code
ER$0RD),
but they do not have to be densely ordered.
RMS-11 ignores
excess and illogical XABs.

8.1.3.1
space.

Buffer Requirements - One BDB and 512

bytes

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8.1.3.2

'~·

Input Fields -

FAB IF!
XAB
ALL XAB AID
NXT

DAT XAB NXT
KEY XAB NXT
PRO XAB NXT
SUM XAB NXT

8-6

File Operation Macros:

$CREATE

8.1.3.3

Output Fields -

FA.B STS
STV
~

ALL XA.B ALN
ALQ (number of blocks unused in current extent)
AOP (can contain XB$CTG)
BKZ
DEQ
LOC
DAT XAB All fields
KEY XA.B All fields
PRO XAB All fields
SUM XAB All fields
NA.M All fields

8.1.3.4

General Form -

$DISPLAY

fab [,error]

where fab is the address of a File Access Block representing an existing RMS-11 file.
error is the address of a completion routine to be called
$DISPLAY operation fails.

8.1.3.5

the

Examples -

•

A program that opens a file with unknown attributes cannot link in
the proper Key and Allocation XABs.
That program can link a Summary XAB to the FAB, then open the file.
From the SUM XAB, the program determines whether XABs are appropriate, then how many of each
are necessary.
The program links in the proper XABs and executes a
$DISPLAY macro to obtain the attribute information.

•

A program has room for only one XAB.
It can accumulate the
information it needs on areas and keys by executing a series of $DISPLAY
macros, changing the XAB fields appropriately between operations.

'-"1

File Operation Macros:

$DISPLAY

8-7

***************
*
*

$ERASE

*
*
***************

8. 1. 4

$EHASE

The $ERASE macro deletes an RMS-11 file and
removes its directory
entry(s).
The blocks occupied by the file are made available for
reuse in other files.
You can erase a file by file specification or by file ID.
You indicate the file specification in a FAB.
To specify a file by file ID,
you must:
•

link a NAM Block to the FAB

•

indicate the correct ID with the NAM FID field

•

set the value FB$FID in the FAB FOP field

•

set appropriate values
Fields")

the

other

input

fields

(see

"Input

If the file is open, your program cannot erase it on the logical channel it was opened on.
Example

A file is opened with the FAB LCH field set to 3.
Channel 3
cannot be used for any other file operation, including
erase, until that file is closed.

You cannot erase magnetic tape files or files on unit record devices.

8.1.4.1
space.

Buffer Requirements - One BDB and 512

bytes

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8-8

File Operation Macros:

$ERASE

8.1.4.2

Input Fields -

FAB BPA
BPS
DNA
DNS

FNA
FNS

LCH (must be different from open LCH)
NAM
NAM DVI

ESS
FID

8.1.4.3

Output Fields -

FA.B STS
STV

8.1.4.4

General Form -

$ERASE

fab [,error]

where fab is the address of a File Access Block representing an existing RMS-11 file.
error is the address of a completion routine to be called
$ERASE operation fails.

the

8.1.4.5 Comments - If your or another program has a
file open and
your program erases the file (on a different logical channel), the
file processor does not delete the file from the directory and release
its allocated blocks until all accessors close the file.

File Operation Macros:

$ERASE

8-9

***************

$EXTEND

**
*

***************

8.1.5

$EXTEND

The $EXTEND macro requests the file
file's allocation~

processor

add

blocks

If no Allocation XABs are linked to the FAB, RMS-11 extends Area O*,
using data from the FAB fields to control its processing.
If the FAB
FOP field contains FB$CTG, RMS-11 requests the file processor to allocate the requested blocks contiguously with those blocks already allocated to the file;
if no contiguous blocks are available, RMS-11 returns an error.
However, if one or more Allocation XABs are linked to the FAB,
RMS-11
extends the areas indicated by the ALL XAB AID fields by the amounts
specified in the ALL XAB ALQ fields.
If the XAB AOP field contains
XB$CTG,
RMS-11
requests the file processor to allocate the requested
blocks contig uo usl y with those blocks al ready al located to
the area;
if no contiguous blocks are available, RMS-11 returns an error.}

8 .1. 5.1
space.

Buffer Requirements - One BDB and 512

bytes

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8.1.5.2

Input Fields -

FAB ALQ (ignored if Allocation XABs linked)
FOP (can contain FB$CTG;
ignored if Allocation XABs linked)
!FI
XAB
ALL XAB AID
ALQ
AOP (can contain XB$CTG)
*For Sequential and Relative files, Area 0 is the file.

8-10

File Operation Macros:

$EXTEND

8.1.5~3

Output Fields -

FAB ALQ (number of blocks actually added to the file)
STS
STV
ALL XJ\B ALQ (number of blocks actually added to the file)

8.l.5u4

General Form -

~~EXTEND

rab [,error]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$EXTEND operation fails.

the

8.1.SuS Comments - RMS-11 applies the following restrictions
erase operation:

the

•

The file must be open.

•

All Record Access Streams connected to the file must
otherwise, RMS-11 returns error code ER$ACT.

inactive;

•

The file must have been opened with at least one of
specified in the FAB FAC field:

the

follo~ing

FB$DEL
FB$PUT
FB$UPD
•

The file does not reside on magnetic tape;
turns error code ER$IOP.

otherwise,

File Operation Macros:

RMS-11

re-

$EXTEND

8-11

***************

*
*
*

$OPEN

*
*
*

***************

8 .1. 6

$OPEN

The $OPEN macro makes an existing RMS-11 file available for processing
by your program.
RMS-11 also returns the basic attributes of the file
in the FAB associated with the macro;
if XABs are linked to the FAB,
RMS-11 files
in attribute information appropriately; and if a NAM
Block is linked, RMS-11 provides the expanded file specification of
the open file.
Key and Allocation XABs must be grouped in ascending order (error code
ER$0RD), but they do not have to be densely ordered.
RMS-11 ignores
excess and illogical XABs.
You can open a file by file specification or by file ID.
You indicate
the file specification in a FAB.
To specify a file by file ID, you
must:
•

link a NAM Block to the FAB

•

indicate the correct ID with the NAM FID field

•

set the value FB$FID in the FAB FOP field

•

set appropriate values
Fields")

8.1.6.1
space.

the

other

input

Buffer Requirements - One BDB and 512

fields

bytes

(see

"Input

I/O

buffer

NOTE
Since any record operation requires at least one BDB and an
I/O buffer a block long, the buffer requirements for this
operation are typically met without specific attention on
your part.

8-12

File Operation Macros:

$OPEN

8.1.6.2

Input Fields -

FAB BPA
BPS
DEQ (used as temporary run-time value)
DNA
DNS
FAC
FNA
FNS
FOP
LCH
NAM
RTV
SHR
XAB

ALL

X~1B

AID
DEQ
NXT

DAT

XA~B

NXT

PRO

XJl~B

NXT

SUM

XJl~B

NXT

NJl~M

DVI
ESS
FID

8.1.6 .. 3
FJ~B

'-"".

Output Fields ALQ
BKS
DEQ
BLS
DEV
FOP
FSZ
!FI
MRN
MRS
ORG
RAT
RFM
RTV
STS
STV

(if input value = O, set to value set at create time)
(magnetic tape files only)
(contains FB$CTG if the file is contiguous)
(VFC records only)
(Relative files only)

ALL Xl\B ALN
ALQ (number of blocks unused in current extent)
AOP
(can contain XB$CTG)

File Operation Macros:

$OPEN

8-13

BKZ
DEQ
LOC

DAT XAB All fields
PRO XAB All fields
SUM XAB All fields
NAM All fields

8.1.6.4

General Form -

$OPEN

fab [,error]

where fab is the address of a File Access Block representing an existing file.
error is the address of a completion routine to be called
$OPEN operation fails.

the

8.1.6.5 Comments - If you intend to extend the file while it is open,
ensure that the FAB FAC field contains FB$DEL, FB$PUT, and/or FB$UPD
before your program initiates the open operation.

8-14

File Operation Macros:

$OPEN

8.2

RECORD OPERATION MACROS

After it has created or opened an RMS-11 file, your program can perform
record operations on it.
These operations involve the following
concepts that are explained in the RMS-11 User's Guide and Chapter 1
of this manual.
Record Access Streams
F'i le sha:r ing
Context, Current Record, and Next Record
Synchronous and asynchronous record operations
Table 8-2:

RMS-11 Record Operation Macros

Macro Name

Description

$CONNECT

Establishes a Record Access Stream.

$DELETE

Deletes a record from an RMS-11
fi 1 e.

$DISCONNECT

Terminates a Record Access Stream.

$FIND

Locates a record in an RMS-11 file.

$FLUSH

Moves all data in unwritten I/O buffers to disk.

$FREE

Unlocks a bucket locked by a Record Access Stream.

$GE~r

Moves a record from an RMS-11 file into your program's
user buffer.

$NX~rVOL

Continues processing with the next volume of
tape multivolume set.

magnetic

Moves a record from your program's user buffer
RMS-11 file.

Relative

Indexed

$REWIND

Resets a Record Access Stream's context to the logical
beginning of an RMS-11 file.

$TRUNCATE

Deletes record at the
fi 1 e.

$UPDATE

Replaces a record in an RMS-11 file with a record from
your program's user buffer.

$WAIT

Suspends processing until an RMS-11
cord operation completes.

end

RMS-11

Sequential

asynchronous

re-

Record Operation Macros

8-15

***************
*
*

$CONNECT

*
*
***************

8. 2. 1

$CONNECT

The $CONNECT macro establishes a Record Access Stream by associating a
RAB with a
FAB.
RMS-11 also allocates buffer space or uses the GSA
routine you provided to allocate buffer space, for:
•

internal control structures from the central buffer pool

•

I/O buffers from the central or private pool as you indicate in the
FAB, according to file organization and the values specified in RAB
MBC and MBF fields

8.2.1.1
BID
BLN
FAB
KRF
MBC
MBF
ROP
UBF

8.2.1.2

Input RAB Fields -

(Indexed files only)
(disk Sequential files only)
(Relative and Indexed files only)
(see RBF under "Output RAB Fields")

Output RAB Fields -

!SI
RBF {= UBF value for Locate Mode on Sequential files)
STS
STV

8.2.1.3

General Form -

$CONNECT

rab[,error[,success]]

where rab is the address of a Record Access Block you
to a FAB.

want

connected

error is the address of a completion routine to be called
$CONNECT operation fails.

the

success is the address of a completion routine to be called
$CONNECT operation succeeds.

the

8-16

Record Operation Macros:

$CONNECT

***************

*
*
*

$DELETE

*
*
*

***************

8.2.2

$DELETE

The $DELETE macro deletes an existing record from a Relative or Indexed file.
If your program initiates a delete operation on a Sequential file, RMS-11 returns error code ER$IOP.
The $DELETE operation always applies to
the
Current
Record.
Therefore, your program must successfully execute a $FIND or $GET
macro before initiating a $DELETE macro;
otherwise,
RMS-11
returns
error code ER$CUR.

8.2.2ol

Input RAB Fields -

BID
BLN
!SI
ROP

8.2.2~2

Output RAB Fields -

S'rS
S'rV

8.2.2.3
~·

General Form -

:$DELETE

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$DELETE ope ration fails.

the

success is the address of a completion routine to be called
$DELETE operation succeeds.

the

$DELETE

8-17

Record Operation Macros:

***************

*
*
* $DISCONNECT *
*
*

***************
8.2.3

$DISCONNECT

The $DISCONNECT macro terminates a Record Access Stream, ending
the
association between a FAB and a RAB.
RMS-11 releases all buffer space
for reuse.

8.2.3.1

Input RAB Fields -

BID
BLN
IS I

8.2.3.2

Output RAB Fields -

ISI (set to zero)
STS
STV

8.2.3.3

General Form -

$DISCONNECT rab[,error[,success]]
where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$DISCONNECT operation fails.

the

success is the address of a completion routine to be called
$DISCONNECT operation succeeds.

the

8.2.3.4 Comments - The $DISCONNECT macro does not rewind magnetic
tape
files.
If you want the file positioned to beginning-of-file for
a subsequent connect operation, use the $REWIND macro before initiating the disconnect operation.

8-18

Record Operation Macros:

$DISCONNECT

***************

*
*
*

$FIND

*
*
*

***************

"'-"'
$FIND

8. 2. 4

The $E~IND macro locates a specified record in a file and
returns its
Record's File Address in the RAB RFA field.
During the operation,
RMS-11 sets the Current Record pointer and for Sequential Access Mode
only, the Next Record pointer.

8.2.4ol

''--'

Input RAB Fields -

BID
BLN
IS I

KBF (Random Access Mode only)
KRF (Random Access Mode on Indexed files only)
KSZ (Random Access Mode only)
Ri!\C

RFA (if RAC contains RB$RFA)
ROP

8.2.4.2

Output RAB Fields -

BKT (Sequential Access Mode on Relative files only)
RFA (if RAC does not contain RB$RFA)
STS
STV

8.2.4.3

General Form -

$FIND

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$FIND operation fails.

the

success is the address of a completion routine to be called
$FIND operation succeeds.

the

$FIND

8-19

Record Operation Macros:

8.2.4.4

Comments -

•

RMS-11 allows Access by RFA during find operations
only.

•

Normally, you would not use Access by RFA for find operations on
Relative and Indexed files, since the output of the operation is
the RFA used as input. However, a find by RFA returns error code
ER$DEL if the specified record once existed in the file, but was
subsequently deleted: a random find operation returns error code
ER$RNF whether the record never existed or was deleted.

•

In Sequential Access Mode, a find operation on an Indexed file uses
the index of reference set by the most recent successful get, sequential find, or connect operation.
If you want to use a different index for sequential processing, you should execute a rewind or
a random get operation specifying the key of reference (RAB KRF
field) you want.

•

If the file allows duplicates in the key of reference, RMS-11 does
not indicate if the record located is one of a series containing
duplicates in that field.

8-20

Record Operation Macros:

$FIND

disk

files

***************

*
*

$FLUSH

*
*
*

*
***************

8.2.5

$FLUSH

The $FLUSH macro writes all modified I/O buffers associated with a Record Access Stream to disk, if they haven't been written. With this
operation, you can ensure that all record activity up to a
po int in
time
is reflected
in the file.
For Relative and Indexed files, any
bucket locked by the stream remains locked.

8.2.5.1

Input RAB Fields -

BID
BLN

IS I

8.2.5~2

Output RAB Fields -

s~rs

srrv

8.2.5~3

General Form -

!?FLUSH

'-"

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream •

Re-

error is the address of a completion routine to be called
$FLUSH operation fails.

the

success is the address of a completion routine to be cal 1 ed
$FLUSH operation succeeds.

the

$FLUSH

8-21

Record Operation Macros:

***************

*
*
*

$FREE

*
*
*

***************

8.2.6

$FREE

The $FREE macro unlocks a bucket that RMS-11 locked on behalf of a Record Access Stream.
If no bucket is locked, RMS-11 returns error code
ER$RNL.
See Chapter 2 of the RMS-11 User's Guide for more information on
sharing.

8.2.6.1

file

Input RAB Fields -

BID
BLN
!SI

8.2.6.2

Output RAB Fields -

"~.

STS
STV

8.2.6.3

General Form -

$FREE

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be cal led
$FREE operation fa i 1 s.

the

success is the address of a completion routine to be called
$FREE operation succeeds.

the

8.2.6.4 Comments - If you are using multiple Record Access Streams to
access a
file,
you must not merely reissue a record operation that
fails with error code ER$RLK.
Since one of your program's streams can
have the target bucket locked, you could place the program into an infinite loop if you continue to issue the same operation.
Therefore,
y~u
should execute a $FRE~ ~a:ro for all ~ther streams to the s~me
file.
Then you can safely reinitiate the original
record operation
until RMS-11 indicates successful completion.
8-22

Record Operation Macros:

$FREE

***************

*
*

$GET

***************

8.2.7

$GET

The $GET macro retrieves a record from an RMS-11 file, moving the record
from the I/O buffer to your program's user buffer* and returning
the record's RFA in the RAB RFA field.
After a successful operation,
the HAB RBF and RSZ fields describe the retrieved record with the address of its first byte and its length, respectively.

8.2.7~1

Input RAB Fields -

BID
BLN
!SI
KBF (Random Access Mode only)
KRF (Random Access Mode on Indexed files only)
KSZ (Random Access Mode only)
Rl~C

RFA (if RAC contains RB$RFA)
RHB (VFC records only)
ROP
UBF (regardless of Record Transfer Mode)

usz

8.2.7~2

Output RAB Fields -

BKT (Sequential Access Mode on Relative files only)
RBF
RFA (if RAC does not contain RB$RFA)
RSZ
s~rs
s~rv

8.2.7~3

$GET

General Form rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

"-"'

Re-

*Unless you specify Locate Record Transfer Mode (RB$LOC in the RAB ROP
field).

Record Operation Macros:

$FREE

8-23

error is the address of a completion routine to be called
$GET operation fails.

the

success is the address of a completion routine to be cal led
$GET ope ration succeeds.

the

8.2.7.4
•

Comments -

After a successful get operation from a unit record device, such as
a terminal, the less significant byte of the RAB STV field contains
a code representing the character that terminated the input record,
as follows:
Code
(in octal)

15
33
32
0

Character
Represented
Carriage Return
Escape
CTRL/Z
other

Except when the code is O, the terminating character
the record described by the RAB RBF and RSZ fields.
Example

$GET
CMPB
CORD

#0, O$STS (RS)

never

;RETRIEVE A RECORD
;CHECK IF TERMINATOR STILL IN RE-

•

RMS-11 allows Access by RFA during get
only.

disk

files

•

Normally, you would not use Access by RFA for get operations
lative and Indexed files, since the output of the operation
RFA used as input.
However, a get by RFA returns error code
if the specified
record once existed in the file, but was
quently deleted:
a random get operation returns error code
whether the record never existed or was deleted.

on Reis the
ER$DEL
subseER$RNF

•

In Sequential Access Mode, a get operation not preceded by a
successful
find
uses the
index of reference set by the most recent
successful get, find, or connect operation.
If you want to
use a
different index
for
sequential
processing, you should execute a
rewind or a random get or find
operation specifying
the
key of
reference (RAB KRF field) you want.

•

If the file allows duplicates in the key of reference, RMS-11 does
not indicate if the record retrieved is one of a series containing
duplicates in that field.

8-24

Record Operation Macros:

$GET

operations

The $NXTVOL macro is not supported by RSTS/E.

8.2.8

***************
*
*
$NXTVOL
*
*
*
*
***************

$NXTVOL

The $NXTVOL macro can be used only when the Record Access Stream is
accessing a multivolume file on magnetic tape.
You execute this macro
when you want to continue processing the current file on the next volume before the end of the current volume is reached.
See also the
magnetic tape handling appendix of the RMS-11 User's Guide.
Next-volume processing depends on whether your program is
writing data on the tape:

reading

Input File Processing
lo

RMS-11 skips all records in I/O buffers for the
file section.

RMS-11 requests the next tape volume from the file
cessor:

current
pro-

•

If there is no next volume, RMS-11 returns error code
ER$EOF.

•

If there is another volume,
the file processor
rewindg the current volume, requests the system operator to mount the next volume, and reads the header
label
(HDRl)
of the first file section on the next
tape.
If the tape is not the proper volume, the processor requests the operator to mount the correct
tape and repeats this step.

The operation terminates.

Output File Processing
1.

RMS-11 writes I/O buffers to the current file section in
an implicit flush operation.

RMS-11 requests the next tape volume from the file
cessor:

pro-

The processor closes the current file section, writing EOVl and EOV2 labels and rewinding the volume.

The processor requests the system operator to
the next volume.

The processor creates a file with che same name and
the next higher section number and opens the file
Record Operation Macros:

$NXTVOL

mount

8-25

for write operations.
The file set identifier
is
identical with the volume identifier of the first
volume in the volume set.
3.

8.2.8.1

The operation terminates.

Input RAB Fields -

BID
BLN
IS!

8.2.8.2

Output RAB Fields -

STS
STV

8.2.8.3

General Form -

$NXTVOL

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$NXTVOL operation fails.

the

success is the address of a completion routine to be called
$NXTVOL operation succeeds.

the

8-26

Record Operation Macros:

$NXTVOL

***************

*
*
*

$PUT

*
*

***************

8.2.9

$PUT

The $PUT macro writes a new record into an RMS-11 file.
The RAB RBF
and RSZ fields describe the record to be written.
You cannot use Access by RFA.
Put operations in Random Access Mode do not change the
Next Record pointer.

8.2.9.1
BID
BLN
!SI
KBF
KSZ
RAC
RBF
RHB
ROP
RSZ
UBF
USZ

Input RAB Fields -

(Random Access Mode on Relative files only)
(Random Access Mode on Relative files only)
(VFC records only)
(Locate Mode for Sequential files only)
(Locate Mode for Sequential files only)

8.2.9.2

Output RAB Fields -

BKT (Sequential Access Mode on Relative files only)
RBF (Locate Mode for Sequential files)
RFA
STS
STV

8.2.9.3
$PUT

General Form rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$PUT operation fa i 1 s.

the

success is the address of a completion routine to be called
$PUT operation succeeds.

the

$PUT

8-27

Record Operation Macros:

8.2.9.4
•

•

Comments -

Since RMS-11 supports put operations in Sequential Access Mode only
for
Sequential files, you must set the value RB$SEQ in the RAB RAC
field before initiating a $PUT operation on a Sequential file.

"""

RMS-11 supports put operations only at the end of Sequential files.
Your program can reach end-of-file by one of the following methods:
the connect
Set RB$EOF in the RAB ROP field before initiating
operation.
RMS-11
sets
the
Current Record po inter to
encl-of-file.
Execute $FIND (or $GET) macros until RMS-11 returns
ER$EOF.

•

error

code

RMS-11 restricts put operations on Relative files as follows:
No record can be written that is longer than the Maximum
Size specified when the file was created.

Record

The cell specified by the contents of the RAB KBF field cannot
contain a valid record--unless you set the value RB$UIF in the
RAB ROP field.
The relative record number in the RAB KBF field cannot be greater than the Maximum Record Number specified when the file was
created.
•

RMS-11 restricts put operations on Indexed files as follows:
No record can be written that is longer than the Maximum
Size specified when the file was created.

Record

No record can be written that is too short to contain the complete Primary Key field.
The record does not have to contain
all defined Alternate Key fields.
•

If a put operation on an Indexed file specifies a record that contains a key value already existing in the file, RMS-11 response depends on whether you allowed duplicate key values when you created
the file:
If duplicates are not allowed, RMS-11 returns error code ER$DUP.
If duplicates are allowed, RMS-11 inserts the record after all
records with the same key value and before a record with a
higher key value.
Then RMS-11 returns success code SU$DUP.

8-28

Record Operation Macros:

$PUT

#"'

***************

*
*
*

$REWIND

*
*
*

***********"***

8.2.10

$REWIND

The $REWIND macro sets the context of a Record Access Stream to
the
logical beginning of the associated file.
Following the operation,
there is no Current Record, and the Next Record is the first record in
the file;
for Indexed files, the value of the RAB KRF sets the index
that defines the first record logically.

8.2.10.1

Input RAB Fields -

BID
BLN
!SI
KRF (Indexed files only)

8.2.10.2

Output RAB Fields -

S'l~S

S'l~V

8.2.10.3

General Form -

~?REWIND

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$REWIND operation fa i 1 s.

the

success is the address of a completion routine to be called
$REWIND operation succeeds.

the

macro

for

$REWIND

8-29

8.2.10.4 Comments RSTS/E does not support the
magnetic tape files only.

$REWIND

Record Operation Macros:

***************
*
*

*
*

$TRUNCATE

*
*

***************

8.2.11

$TRUNCATE

The $TRUNCATE macro truncates a Sequential file.
If you initiate a
truncate operation on a Relative or Indexed file, RMS-11 returns error
code ER$IOP.
A truncate operation deletes the Current Record and all
records following that record and sets Next Record to point to the end-of-file.
Therefore, your program must successfully execute a $FIND or $GET
macro before initiating a $UPDATE macro; otherwise, RMS-11 returns
error code ER$CUR.

8.2.11.1

Input RAB Fields -

BID
BLN
!SI

8.2.11.2

Output RAB Fields -

STS
STV

8.2.11.3

General Form · ..

$TRUNCATE

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$TRUNCATE operation fails.

the

success is the address of a completion routine to be called
$TRUNCATE operation succeeds.

the

8.2.11.4 Comments - Your program can follow a truncate operation
mediately with one or more sequential put operations.

im-

8-30

Record Operation Macros:

JJUIMllUIZIUIUP ¥4

rab[,error[,success]]

$TRUNCATE

;

mil'

***************
*
*

*
*

$UPDATE

*
*

***************

·~·

8. 2. 12

$UPDA'.rE

The $UPDATE macro replaces an existing record
cribed by the RAB RBF and RSZ fields.

with

the

record

des-

The $UPDATE operation always applies to
the
Current
Record.
Therefore,
your
program must successfully execute a $FIND or $GET
macro before initiating a $UPDATE macro;
otherwise,
RMS-11
returns
error code ER$CUR.
RMS-11 error codes indicating an illegal input value in a RAB field do
not affect the record being updated.
Example

ER$RSZ

However, other errors can mean that the target record is lost.
Example

ER$WER

8.2.12.1

Input RAB Fields -

BID
BLN
IS I
RBF
RHB (VFC records only)
RSZ

8.2.12.2

Output RAB Fields -

RFA

s·rs
s·rv

8.2.12.3

General Form -

:$UPDATE

rab[,error[,success]]

where rab is the address of a Record Access Block representing
cord Access Stream.

Re-

error is the address of a completion routine to be called
$UPDATE operation fails.

the

$UPDATE

8-31

Record Operation Macros:

success is the address of a completion routine to be called
$UPDATE operation succeeds.

8.2.12.4
•

the

Comments -

RMS-11 restricts update operations on Sequential files as follows:
No updates on magnetic tape files or unit record devices.
No updates on disk Sequential files with stream format records.
No updates that change the length of the target record:
your
program must not change the RAB RSZ field between the get or
find operation and the update operation.

•

For Relative files, the replacement record cannot be longer
the Maximum Record Size specified when the file was created.

•

For an update operation on an Indexed file that allows duplicate
Primary Keys,
the replacement record length must equal the target
record length;
that is, your program must not change the RAB RSZ
field between the get or find operation and the update operation.

•

For an update operation on an Indexed file that does not allow duplicate Primary Keys,
the record length can change, but the replacement record cannot be longer than the
file's Maximum Record
Size or too short to contain the complete Primary Key field.

8-32

Record Operation Macros:

$UPDATE

than

***************
*
*

*
*

$WAIT

*
*

***************

8.2.13

$WAIT

The $WAIT macro suspends your program's operation until an outstanding
asynchronous record operation completes.

8.2.13.1

Input RAB Fields -

BID
BLN

IS!

8.2.13.2

Output RAB Fields -

ST1S
1

S'I V

plus fields of asynchronous record operation your program is waiting for

8.2.13.3
$WAIT

General Form rab[,error[,success]]

where rab is the address of an asynchronous Record Access Block representing a Record Access Stream with an asynchronous record
operation in progress.
~·

error is the address of a completion routine to be called
$WAIT operation fails.

the

success is the address of a completion routine to be called
$WAIT operation succeeds.

the

$WAIT

8-33

Record Operation Macros:

CHAPTER 9
PERFORMING BLOCK I/O

Block I/O allows you to bypass the record processing capabilities of
RMS-11.
Through macros described in this chapter, you can read and
write the virtual blocks of a file.
CAUTION
Many elements of the internal structure of RMS-11 files are
not visible during
record processing.
With Block I/O,
however, you can examine these elements.
Exercise extreme caution when altering the virtual blocks of
RMS-11-structured Sequential, Relative, or Indexed files.
To use Block I/O, your program must do the following:
1.

Allocate one BDB for each stream* connected for Block I/O.
You
specify BDBs with the P$BDB macro between the POOL$B and POOL$E
macros (see Chapter 2).

Allocate an I/O buffer with at least 512 bytes
(to support file
operations).
Use one of the techniques described in Chapters 1
and 2.
If your program reads or writes more than one block at a
time, allocate a buffer large enough to support all operations.

Set one or both of the following values in the FAS FAC
fore initiating any file operation macros:

field

FB$REA

if you want to read blocks from an RMS-11 file

FB$WRI

if you want to write blocks to an RMS-11 file

be-

Initiate one of the following file operaton macros:
$CREATE
You create a file that can be processed only with Block
I/O operations.
RMS-11 restricts such files as follows:
•

disk or magnetic tape medium

*RMS-11 permits a single Block I/O stream for Sequential
multiple streams for Relative and Indexed files.

files

and

• Sequential organization (FB$SEQ in the FAS ORG field)
• Undefined record format (FB$UDF in the FAS RFM field)
$OPEN
file organization;
You access a file with any RMS-11
however, you can use only Block I/O operations to access
data in the file.
5.

Set up a Record Access Block
(see Chapter 4)
$CONNECT macro
for
each Record Access Stream.
connected to the file for record processing.

and
initiate a
No stream can be

Use the macros described in this chapter to processing data in the
file.

Disconnect each stream.

Close the file.

Table 9-1 summarizes the RMS-11 Block I/O macros.
Table 9-1:

RMS-11 Block I/O Macros

Macro Name

Description

$READ

Retrieve a specified number of bytes from a virtual block.

$WRITE

Write a specified number of bytes to a virtual block.

$SPACE

Move a magnetic tape a specified number of blocks.

9-2

Performing Block I/O:

Introduction

***************

*
*

$READ

*
***************

9.1

$READ

The $READ macro retrieves a specified number of bytes from a file beginning on a
specified virtual
block boundary.
You must supply a
word-aligned buffer for the data.

9.1.1

Input RAB Fields

BKT
IS: I
UBF
USZ

9.1.2

(VBN where read starts)
(address for input buffer)
(size of input buffer as a multiple of two bytes)

Output RAB Fields

RBF (location of data read from file)
RSZ (number of bytes read)
S'l$
S'l~V

9.1.3

General Form
~iREAD

rab[,error[,success]]

where rab is the address of a Record Access Block containing the specification for the read operation.
error is the address of a completion routine to be called
$READ operation fails.

the

success is the address of a completion routine to be called
$READ operation succeeds.

the

9. 1. 4
•

Comm en ts

You can read multiple blocks by specifying an appropriate
of 512 bytes in the RAB USZ field.

Block I/O Operations:

multiple

$READ

9-3

•

The value RMS-11 returns in the RAB RSZ field does not count the
terminator character received from a unit record or terminal device.
The RAB STV field reports on that character;
see the $GET
record operation in Chapter 8.

If the RAB STS field contains ER$EOF, the RAB
the number of bytes transferred.

RSZ

still

contains

""""·
9-4

Block I/O Operations:

$READ

***************

*
*
*

$WRITE

*
*
*

***************

9.2

$WRITE

The $WRITE macro writes a specified number of bytes into a file beginning on a specified virtual block boundary.

9.2.1

Input RAB Fields

BKT (VBN where write starts)
ISI
RBF (address o:E first byte of one or more blocks to be written)
RSZ (size of data to be written as a multiple of two bytes)

9.2.2

Output RAB Fields

STS
STV (actual number of bytes transferred)

9.2.3

General Form
$WRITE

rab[,error[,success]]

where rab is the address of a Record Access Block containing the specification for the write operation.
error is the address of a completion routine to be called
$WRITE operation fails.

the

success is the address of a completion routine to be called
$WRITE operation succeeds.

the

9.2.4

Comments

•

You can write multiple blocks by specifying an appropriate multiple
of 512 bytes in the RAB RSZ field~

•

If the RAB RSZ does not contain an even multiple of 512 bytes,
the
number of bytes specified are written, but the disk contents of the
unwritten portion of the last block affected are undefined.
Block I/O Operations:

$WRITE

9-5

***************
The $SPACE macro is not supported on RSTS/E

*
*

$SPACE

***************

9. 3

$SPACE

The $SPACE macro causes a magnetic tape file to move forward or backward.
The file must have been opened for Block I/O and reside of magnetic tape;
otherwise, RMS-11 returns error code ER$IOP.

9.3.1

Input RAB Fields

BKT (number of blocks to be spaced;
sign indicates direction)
ISI
ROP (can contain RB$ASY;
see Chapter 4)

9.3.2

Output RAB Fields

STS
STV (number of blocks spaced)

9.3.3

General Form
$SPACE

rab[,error[,success]]

where rab is the address of a Record Access Block containing the specification for the spacing operation.
error is the address of a completion routine to be called
$SPACE ope ration fails.

the

success is the address of a completion routine to be cal led
$SPACE operation succeeds.

the

RMS-11 examines only the lower addressed byte of the one-word
field.
RMS-11 interprets this byte as a signed 15-bit integer:

BKT

•

9.3.4

9-6

Comments

A positive integer represents the number of blocks the file
be spaced forward

Block I/O Operations:

$WRITE

"""

•

A negative number represents the number of blocks the file is to be
backspaced.

Block I/O Operations:

$SPACE

9-7

APPENDIX A
RMS-11 COMPLETION CODES

All RMS-11 file and record operations return a completion code into
the STS field of the associated control block (FAB or RAB).
A symbolic name is defined for each code, with one of the following forms:
'~

Successful completion codes:
SU!$cod
Error completion codes:
ER!$cod
where cod represents the success qualifier or the reason the operation
failed.

"-"''

For certain error conditions, RMS-11 uses the STV field to communicate
additional
information to your program.
The tables in this appendix
list all instances where an STS code indicates the presence of further
information in the STV field.
A limited number of severe error conditions cause RMS-11 to use a
fatal error crash routine.
Section A.3 describes these conditions and
the crash routine.

A.l

SUCCESSFUL COMPLETION CODES

Table A-1 describes successful completion codes returned by RMS-11 operations.

Table A-1:

RMS-11 Successful Completion Codes

Symbolic
Value

Numeric
Value

SU$SUC

1/1

Operation
successful
qualification.

SU$DUP

2/2

Conditional success:
A record
inserted into an Indexed file by
a put or update operation contains at least one key value
present in another record.

SU$IOX

3/3

SU$RRV

4/4

A-2

STV Field
Value

RMS-11 code

Successful Completion Codes

Description

without

A put or update operation on an
Indexed file ended successfully,
but RMS-11 could not optimize
the index structure during the
operation.
Therefore,
RMS-11
will require extra I/O operations to retrieve the record.
With this success code, RMS-11
can include an RMS-11 error code
in the STV field of the control
block to indicate why the index
structure was not updated.
No longer a valid completion
code. See ER$RVU in Table A-2.

A.2

ERROR COMPLETION CODES

Table A-2 shows:
•

the RMS-11 error completion codes in alphabetical order by symbolic
value

•

the numeric values of the codes in both octal and decimal radix

•

a brief explanation of the cause of the error

When '!'able A-2 indicates that the STV field contains a file processor
code
(with the term fipcode), refer to the description of such codes
in one of the following manuals:
•

Error code appendix of the IAS/RSX-11 I/O Operations Reference Manual

•

User recoverable error messages in an appendix of the RSTS/E Programming Manual.
Note that the value returned in STV is the negative of the decimal value shown in the Programming Manual.
That
is, if STV contains "-20.," look up "20."

When 'l~able A-2 indicates that the Status Value field contains an FSS
directive error code (with the term fsscode), you should refer to the
error code appendix of the RSTS/E System Directives Manual for a description of the codes.

Table A-2:

RMS-11 Error Completion Codes

Symbolic
Value

Numeric
Value

ER$ABO

177760/-16.

ER$ACC

177740/-·32.

ER$ACT

177720/-·48.

STV Field
Value

Description

Stack save
ER$STK/ER$MAP Operation aborted:
area exhausted or memory resident control structures corrupted.
fipcode

File proFile processor error:
cessor
could not access. the
file.

File activity precludes operation.
Example

You attempted to close
a file before an asynchronous record operation finished.
(Continued on next page)

Error Completion Codes

A-3

Table A-2

(continued)

Symbolic
Value

Numeric
Value

STV Field
Value

Description

ER$AID

177700/-64.

XAB address

The area indicated by the
does not exist in the file.

XAB

ER$ALN

177660/-37.

XAB address

Illegal
alignment
Placement Control.

for

ER$ALQ

177640/-96.

XAB address

Illegal allocation
quantity:
The quantity exceeds 65K blocks
during file
creation
on
a
non-Large Files RSTS/E system
or equals zero during an explicit file extension operation.

ER$ANI

177620/-112.

ER$AOP

177600/-128.

ER$AST

177560/-144.

ER$ATR

177540/-160.

value

Records
in
a
file
on
ANSI-labeled magnetic tape are
not
in
variable-length, but
ANSI-D format.
XAB address

Invalid type of allocation.
Invalid operation at AST level:
You attempted
to
issue a synchronous operation from an asynchronous record operation completion routine.

f i pc ode

177530/-168

File processor error:
Read failure on file attributes.
Invalid File ID.

See ER$FID.

ER$ATW

177520/-176.

ER$BKS

177500/-192.

ER$BKZ

177460/-208.

ER$BLN

177440/-224.

Control block (FAB, RAB, or XAB)
length is invalid.

ER$BOF

177430/-232.

Beginning of file detected during magnetic tape spacing operation.

f i pc ode

File processor error: Write failure on file attributes.
File bucket size exceeds maximum
for operating system.

XAB address

Area bucket size exceeds maximum
for operating system.

(Continued on next page)

·A-4

Error Completion Codes

""'·

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$BPA

177420/-240.

Invalid I/O buffer:
Private
buffer pool not on word bound ary.

ER$BPS

177400/-256.

Invalid I/O buffer:
Private
buffer pool size not a multiple
of two bytes.

ER$BUG

177360/-272.

RMS-11 aborts your task because
it detected an internal error.
Contact a DIGITAL Software Specialist.

ER$CCR

177340/-288.

You attempted to connect more
than one record access stream to
a Sequential file.

ER$CHG

177320/-304.

During an update operation, you
attempted
to change a key field
that does not allow changes.

ER$CHK

177300/-·320.

Indexed file bucket corrupted.
Do as many of the following
steps as necessary:
1. Move the disk pack containing
the file to another device
and try the process again.
If it works,
the error was
caused by a hardware read fai 1 ur e.
2. Recreate the file using
the
RMSIFL or RMSCNV utility.
If
this works,
the
corrupted
bucket was in an index bucket
not used during sequential
access by Primary Key.
3. Restore the file from your
last backup copy.

ER$CLS

177260/-336

f ipcode

ER$COD

177240/-352.

XAB address

ER$CRE

177220/--368.

fipcode

STV Field
Value

'-''

Description

File processor error:
During
RMS-11 file close operation.
XAB type is invalid for the
ganization or operation.

or-

File processor error: File processor could not create file.
(Continued on next page)
Error Completion Codes

A-5

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$CUR

177200/-384.

ER$DAC

177160/-370.

fipcode

File processor error: File processor deaccess failure during
RMS-11 file close operation.

ER$DAN

177140/-416.

XAB address

Invalid area number specified in
Key XAB DAN field.

ER$DEL

177120/-432.

Record accessed by RFA
mode has been deleted.

ER$DEV

177100/-448.

•
•
•

STV Field
Value

No Current
Record:
Delete,
truncate, or update operation
was not immediately preceded by
a successful get or find.

177070/-456.

fipcode

access

Syntax error in device name
No such device
Inappropriate device for operation
Example

ER$DFW

-....

Description

You attempted
to
create an Indexed
file on
magnetic
tape.

File processor error:
File processor could not write bucket;
RMS-11 deferred the I/O operation until
it needed
the I/O
buffer for another bucket because the user program specified
Deferred Write.

ER$DIR

177060/-464.

Syntax error in filespec
tory name.

direc-

ER$DME

177040/-480.

Dynamic memory exhausted:
An
RMS-11
buffer pool has insufficient free space.

ER$DNF

177020/-496.

Directory not found.

ER$DNR

177000/-512.

Device not ready.

ER$DPE

176770/-520.

f i pc ode

ER$DTP

176760/-528.

XAB address

Device positioning error.
Invalid key data type.
(Continued on next page)

A-6

Error Completion Codes

-""·

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$DUP

176740/-544.

ER$ENT

176720/-560.

ER$ENV

176700/-576.

You attempted an operation when
the RMS-11 routines were not in
the task:
In MACR0-11, the operation or file organization was
not specified in ORG$ macro;
in
BASIC-PLUS-2, you didn't specify
correct switches with BUILD command.

ER$EOF

176660/-592.

•

STV Field
Value

Description

Invalid record operation:
You
attempted
to
insert a
record
that would cause duplicate values in a key field where duplicates are not allowed.
f i pc ode

File processor error:
File processor could not enter filespec
in directory.

•

For record processing:
End
of file.
For Block I/O:
Invalid VBN.

ER$ESS

176640/-608.

Expanded file-name string
in NAM Block is too short.

area

ER$EXP

176630/-616.

File expiration
ached.

re-

ER$EXT

176620/-·624.

fipcode

date

not

File processor error:
During
RMS-11 file extension operation.

176600/-640.

FAB BID field does
FB$BID.

ER$Fi~C

176560/-656.

Invalid
record
operation:
Operation does not match access
declaration made when file was
created or opened.

ER$FEX

176540/--672.

You tried to create a file
exists.

ER$FID

177530/-168.

Invalid file ID.

not

contain

that

(Continued on next page)

Error Completion Codes

A-7

Table A-2

(continued)

Symbolic
Value

Numeric
Value

STV Field
Value

Description

ER$FLG

176520/-688.

XAB address

Invalid combination of key characteristics.
Example

No duplicate key values, but key values
can change during update operations.

File locked by another user:
You cannot access the file because your sharing specifications cannot be met.

ER$FLK

176500/-704.

ER$FND

176460/-720.

ER$FNF

176440/-736.

File not found during file
operation ..

ER$FNM

176420/-752.

Syntax error in file-name.

ER$FOP

176400/-768.

Invalid file access option specified in FAB FOP field.

ER$FSS

176370/-776.

ER$FUL

176360/-784.

ER$IAN

176340/-370.

ER$IDX

176320/-816.

Specified index was not created.
This code can only occur in the
STV field when STS
contains
ER$RNF.

ER$IFI

176300/-832.

FAB IFI field
value.

f i pc ode

f sscode

File processor error: File processor could not find filespec
in specified directory.
open

RSTS/E monitor
error:
the
File-name String routine is unable to parse the
file-name
string supplied by RMS-11.
Device full:
RMS-11 cannot create or extend file.

XAB address

Invalid area number specified in
Key XAB IAN field.

contains

invalid

(Continued on next page)

A-8

Error Completion Codes

,.........,. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .lllllllim. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.Hl

Table A-2

(continued)

Symbolic
Value

Numeric
Value

STV Field
Value

De script ion

ER$IMX

176260/-848.

XAB address

More than 254 keys and/or areas
defined
or multiple Summary,
Protection, or Date/Time XABs
present during operation.

ER$INI

1 76240/-864.

$INIT or $INITIF
never issued.

ER$IOP

176220/-880.

Illegal operation.

macro

call

Example

You attempted to truncate a nonSequential
fi 1 e •

Example

You attempted
to delete or extend a magnet i c tape f i 1 e •

Example

You issued a Block I/O
operation to a stream
not
connected
for
block operations.

Example

You issued a record
operation to a stream
connected
for
Block
I/O ope rations.

'-".
.

ER$IRC

176200/-896.

in
Illegal
record encountered
Record-length
Sequential
file:
field is invalid.

ER$ISI

176160/-912.

RAB ISI field is invalid.
You
may have altered it or failed to
connect the stream.

ER$KBF

176140/-928.

random
No key specified during
RAB KBF field
record operation:
equals O.

ER$KEY

176120/-944.

Negative Relative Record Number
during
random operation or bad
format
in packed decimal
key
value.
(Continued on next page)

Error Completion Codes

A-9

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$KRF

176100/-960.

Invalid key of reference:
•
During random get or find operation.
•
During connect or rewind operation:
Error code is returned for the first sequential get or find operation
following
the
connect
or
rewind.

ER$KSZ

176060/-976.

Invalid key size.

ER$LAN

176040/-992.

ER$LBL

176020/-1008.

Invalid medium:
Magnetic tape
is not labeled
in accordance
with ANSI standards.

ER$LBY

176000/-1024.

Logical channel busy:
You attempted to create or open a file
using a logical channel in use;
th a t
i s , yo u a 1 re ad y o pen ed a
file on that channel.

ER$LCH

175760/-1040.

Invalid logical channel or
number.

ER$LEX

175750/-1048. XAB address

You attempted to extend an area
containing an unused extent.

ER$LOC

175740/-1056. XAB address

Invalid location
ment Control.

ER$MAP

175720/-1072.

Memory-resident data structures,
such as I/O buffers, corrupted.
This code can occur in the STV
field when Status Code contains
ER$ABO.

ER$MKD

175700/-1088.

STV Field
Value

XAB address

f i pc ode

Description

Invalid area number specified in
Key XAB LAN field.

during

unit

Place-

File processor error: File processor could not mark file for
deletion.
(Continued on next page)

A-10

Error Completion Codes

i'i•'. . . . ,_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _. . . , ._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _. . . , ._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _........,

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$MR.N

175660/-1104.

STV Field
Value

Description

•

Maximum Record Number
field
contains
a negative value
during creation of Relative
file.
Relative Record Number
for
random operation to Relative
file exceeds Maximum Record
Number specified when file
was created.

ER$MRS

175640/-1120.

Maximum Record Size is zero during file creation and one of the
following is true:
•
Record format is fixed
•
File organization is Relative.

ER$N1~M

175620/-1136.

Odd address in FAB NAM field on
file open, creation, or erase
operation.

ER$NgF

175600/-1152.

You attempted a put operation to
a Sequential file when stream is
not positioned to end-of-file.

ER$NID

175560/-1168.

Dynamic memory
enough buffer
Indexed file.

ER$NPK

175540/-·1184.

You attempted to create an Indexed
file without defining a
Primary Key.

ER$0PN

175520/-1200.

ER$0HD

175500/-1216. XAB address

XABs not ordered properly.

ER$0HG

175460/-1232.

Invalid file organization.

'-'.
fipcode

exhausted:
Not
area to open an

File processor error:
During
RMS-11 file open operation.

(Continued on next page)

Error Completion Codes

A-11

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$PLG

175440/-1248.

STV Field
Value

Description

A Prologue block may be corruptDo as many of the following
ed.
steps as necessary:
1. Move the disk pack containing
the file to another device
and try the process again.
the error was
If it works,
caused by a hardware read fai l ur e.
2. Recreate the file using
the
RMSIFL or RMSCNV utility.
3. Restore the file from your
last backup copy.

ER$POS

175420/-1264. XAB address

You specified a key po si ti on
beyond the end of the record.

ER$PRM

175400/-1280. XAB address

File directory entry contains
date and time information not
semantically correct.
The file
may
be
corrupted.
Recreate
field
using RMSIFL or RMSCNV
utility.

ER$PRV

175360/-1296.

Privilege violation: access to
the file denied by the operating
system.

ER$RAB

175340/-1312.

RAB BID field does
RB$BID.

ER$RAC

175320/-1328.

Invalid or illogical record access option specified in RAB RAC
field.

ER$RAT

175300/-1344.

You specified both Carriage Return control and FORTRAN forms
control.

ER$RBF

175260/-1360.

RAB RBF field contains an odd
address (Block I/O access only).

ER$RER

175240/-1376.

f i pc ode

not

contain

File processor error:
•
In record processing:
Read
failure on file block.
•
In Block I/O,
VBN = O,
an
illegal value.
(Continued on next page)

A-12

Error Completion Codes

Table A-2

(continued)

Symbolic
Value

Numeric
Value·

ER$REX

175220/-1392.

Record exists:
During a put operation in random mode to a Relative file, you tried to insert
a
record into a cell containing
a record.

ER$RF'A

175200/-·1408.

Invalid RFA during RFA access.

ER$RF'M

175160/-1424.

Invalid record format.

ER$RLK

175140/-1440.

Target bucket locked by another
task or another stream in the
same program.

ER$RMV

175120/-1456.

f i pc ode

File processor error:
File processor could not remove filespec
from directory.

ER$RNF

175100/-1472.

ER$IDX

Record specified during
random
get or find operation does not
exist in Relative or Indexed
file.
For Indexed files only,
STV may contain ER$IDX.

ER$RNL

175060/-·1488.

You initiated a free operation,
but no bucket was locked.

ER$ROP

175040/--1504.

Invalid record processing option
or illogical combination of values specified in RAB ROP field.

ER$RPL

175020/--1520.

ER$RHV

175000/-1536.

Invalid RRV record encountered
in Indexed
file.
File may be
corrupted.
Recreate field using
RMSIFL or RMSCNV utility.

ER$RSA

174760/-1552.

Record stream active:
In asynchronous environment, you attempted a record operation on a
stream that is performing an operation.

ER$R:SZ

174740/-1568.

•

STV Field
Value

fipcode

Description

File processor error:
Read failure on file Prologue.

Record size
Block I/O.

zero

during

(Continued on next page)
Error Completion Codes

A-13

Table A-2

(continued)

Symbolic
Value

Numeric
Value

STV Field
Value

Description

•

•
•

•

Record size exceeds one of
the following:
-- MRS for variable-length or
VFC records.
-- magnetic tape block size.
-- data bucket size of Indexed file.
-- 510(10)
bytes and
block
spanning not allowed.
-- end of I/O buffer during
Locate Mode put operation
on Sequential file.
Record is too short to contain
Primary Key of Indexed
fi 1 e.
Record size is not equal
to
size of Current Record for
update operation on a disk
Sequential
file or on an Indexed file where Primary Key
duplicate are allowed.
Record size does not equal
MRS for fixed-length records.

ER$RTB

174720/-1584. Bytes moved

Record too big for user buffer:
RMS-11 could not move entire record retrieved by get operation
to user buffer.
This error does
not destroy the context of the
stream.
Rather,
the stream's
context is updated as if the operation were completely successful and as much of the record as
possible is moved
to the user
buffer.

ER$RVU

174710/-1592.

During a put or update operation, RMS-11 moved the specified
record to the file successfully,
but could not update one or more
Record Reference Vector
(RRV).
The file
is corrupted, but you
can retrieve every record via
the Primary index.
Therefore,
you should create a new Indexed
file and
populate
it from the
bad file using either the RMSIFL
or the RMSCNV utility.
(Continued on next page)

A-14

Error Completion Codes

--..,

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$SEQ

174700/-·1600.

Invalid
record
operation:
During a sequential put operation to an Indexed file, Primary
Key of record to be written is
not equal to or greater than key
of previous record.

ER$SHR

174660/-1616.

You specified allow write declaration for Sequential file.

ER$SIZ

174640/-1632. XAB address

Invalid key size.

STV Field
Value

Description

Example

Key is bigger
than
Maximum Record Size.

ER$S~rK

174620/-1648.

During asynchronous record operation,
RMS-11 found
the stack
too big to saved.
This code can
only occur in the STV field when
Status Code contains ER$ABO.

ER$SYS

174600/-1664. Directive or
QIO status
error code

The interface between RMS-11 and
the
operating
system
has
changed.
Report this error on
an SPR to DIGITAL.

ER$THE

174560/-1680.

Index in Indexed file is corrupted.
Recreate file using
RMSIFL or RMSCNV utility.

ER$TYP

174540/-·1696.

Syntax error in extension, such
as more than three characters
specified.

ER$UBF

174520/-·l 712.

User
buffer
improperly
specified:
address is either
zero
or
buffer
is
not
word-aligned
(for Block I/O access only) •

ER$USZ

174500/-·l 728.

User buffer length equals zero.

ER$VErn

174460/-1744

Syntax error
number.

ER$VOL

174440/-1760. XAB address

Nonzero relative volume number.

file

version

(Continued on next page)

Error Completion Codes

A-15

Table A-2

(continued)

Symbolic
Value

Numeric
Value

ER$WCD

174430/-1768.

ER$WER

174420/-1776.

ER$WLK

174410/-1784.

ER$WPL

174400/-1792.

ER$XAB
ER$XTR

A-16

STV Field
Value

Description

Explicit or default file specification field contains wild card
character.
File processor error:
ilure on file block.

Write fa-

File processor error:
write locked.

Device is

File processor error:
while writing Prologue.

Error

174360/-1808. XAB address

FAB XAB field or XAB NXT
contains an odd address.

field

174340/-1824.

Explicit or default file specification
contains
extraneous
field.

f i pc ode

Error Completion Codes

A.3

"-"'

FATAL ERROR CRASH ROUTINE

RMS-11 issues a BPT instruction whenever it encounters an inconsistent
internal conditions.
This action is taken only when RMS-11 cannot
continue processing because it might damage your files or task image.
Exampl1e

When RMS-11 encounters an invalid FAB or RAB, it cannot perform a normal error routine because it has no recognizable
control block to set a status code in.

The BP~r instruction generated is in the RORMSA module of RMS-11.
The
general
registers contain the following values at the time this instruction is executed:
RO
Rl
R2
R3

= RMS-11 error code
= Entry Stack Pointer value
= Entry return Program Counter
= Address of system impure area

General registers Rl and R2 are always valid if the crash routine is
caused by a fatal user call error (described in Section A.3.1). When
the crash routine is used because of inconsistent.internal conditions
(described
in Section A.3.2), the contents of Rl and R2 can be meaningless if RMS-11 was executing an asynchronous record operation.

A.3.1

Fatal User Call Errors

If general
register RO contains 176600(8)
(ER$FAB)
or 175340(8)
(ER$RAB), your program initiated an RMS-11 operation using an invalid
control block:
FAB for file operations and RAB for record operations.
This condition can occur for any one of the following reasons:

'-"'

•

The address of the control block is O.

•

The address of the control block is odd.

•

The control block's BID field does not contain the proper
identifier code:
FB$BID for FABs and RB$BID for RABs.
Example

block

On RSX-llM, a fatal user call error resulted in:
TASK "TTnn " TERMINATED
T BIT TRAP OR BPT EXECUTION
PC =021144
PS=l70004
R0=175340
Rl=001162
R2=003646
R3=045276
R4=000000
R5=001164
SP=001126

RMS-11 Fatal Error Crash Routine

A-17

A.3.2

RMS-11 Inconsistent Internal Conditions Errors

If general
register RO contains 177360(8)
(ER$BUG)
or 175720(8)
(ER$MAP),
RMS-11 encountered a fatal internal problem.
Such conditions can be caused by your program (destroying some internal RMS-11
data base, for example), but RMS-11 can also be responsible.
If one of your tasks crashes with one of these error codes, send a
Software Performance Report (SPR) to DIGITAL with the following information:
•

The contents of the general registers

•

The first ten words, at a minimum, or all words on the system stack

•

The operation your task was performing (open, get, put, and so on)

•

The organization of the file being processed

•

A load map of the task (produced by the Task Builder utility)
•

A-18

A post-mortem dump

RMS-11 Fatal Error Crash Routine

),..,~

APPENDIX B
SAMPLE CODE SEGMENTS

The programs and
is,
they run,
error.
They are
construe them to

B.l

code segments included in this appendix work;
that
performing
the
indicate RMS-11 operations, without
samples of programs that do run, but you should
not
be examples of approved programming techniques.

COPYING SEQUENTIAL FILES

The sample code segments in this section demonstrate the copying of
records from an existing Sequential file to a new Sequential file.

; DEMO.RMS
PROGRAM TO COPY RECORDS FROM A SEQUENTIAL FILE NAMED
FILEl.DAT TO A NEW SEQUENTIAL FILE NAMED FILE2.DAT
STEP 1:
. MCALI.
.MCALL
;STEP 2:

ACCESS THE NECESSARY RMS MACROS
$ INIT, ORG$, FAB$B, RAB$B, POOL$B, $CREATE, $OPEN, $CLOSE
$CONNECT,$GET,$PUT,$FETCH,$STORE,$COMPARE
DEFINE CONTROL BLOCKS AND FILE NAME STRINGS

;

;THE FAB FOR THE INPUT FILE, WHICH ALREADY EXISTS, WILL BE
; FILLE:D WITH MOST OF THE ESSENTIAL INFORMATION CONCERNING
;FILEl..DAT WHEN THE FILE IS OPENED. THE PROGRAM NEED ONLY
;SPECIFY ENOUGH INFORMATION TO OPEN THE FILE.
;

FABl:

;FAB FOR FILEl.DAT
F$FNA
NAMEl
;ADDRESS OF NAME STRING
F$FNS
9
;STRING IS 9 CHARACTERS LONG
F$LCH
1
;ACCESS ON CHANNEL 1
FAB$E
;END OF FABl
NAMEl: .ASCII /FILEl.DAT/
;NAME STRING FOR FABl
;HERE, AND WITH FILE2, WE ASSUME THAT THE FILE EXISTS
;ON THE SYSTEM DISK UNDER THE ACCOUNT ON WHICH WE ARE
;LOGGED IN .
. EVEN
; (CONTROL BLOCKS MUST BE WORD ALIGNED)

'-"''

FAB$B

;THE FAB FOR THE OUTPUT FILE, WHICH DOES NOT YET EXIST, MUST
;BE FILLED WITH THE INFORMATION NECESSARY TO CREATE IT (AS IN
;THE PREVIOUS CASE, SOME FIELDS SIMPLY CONTAIN DEFAULT VALUES
;AND ARE NOT EXPRESSED EXPLICITLY). SOME OF THIS INFORMATION

FAB2:

NAME2:
RAB!:

RAB2:

;WILL DEPEND ON THE CHARACTERISTICS OF FILEl.DAT, AND MUST BE
;FILLED IN AT RUN-TIME AFTER FILEl.DAT HAS BEEN OPENED.
FAB$B
;FAB FOR FILE2.DAT
F$FNA
NAME2
;ADDRESS OF NAME STRING
F$FNS
9
;STRING IS 9 CHARACTERS LONG
F$LCH
2
;ACCESS ON CHANNEL 2
F$FAC
FB$PUT
;WRITE ACCESS REQUIRED
FAB$E
;END OF FAB2
.ASCII /FILE2.DAT/
;NAME STRING FOR FAB2
.EVEN
RAB$B
;RAB FOR FILEl.DAT
R$FAB
FABl
;ADDRESS OF OWNER (FAB)
R$RAC
RB$SEQ ;SPECIFY SEQUENTIAL ACCESS
R$UBF
RECBUF
;ADDRESS OF RECORD BUFFER FOR $GETS
R$USZ
500
;SIZE OF THIS BUFFER (500. BYTES)
R$RHB
HEDBUF
;ADDRESS OF RECORD HEADER BUFFER
; (NECESSARY FOR VFC RECORDS ONLY)
RAB$E
;END OF RABI
RAB$B
;RAB FOR FILE2.DAT
R$FAB
FAB2
;ADDRESS OF OWNER
R$RAC
RB$SEQ ;SPECIFY SEQUENTIAL ACCESS
R$RBF
RECBUF
;ADDRESS OF RECORD BUFFER FOR $PUTS
R$RSZ
500
;SIZE OF THIS BUFFER (500. BYTES)
R$RHB
HEDBUF
;ADDRESS OF RECORD HEADER BUFFER
; (NECESSARY FOR VFC RECORDS ONLY)
RAB$E
;END OF RAB2

;STEP 3:
RECBUF: • BLKW
HEDB UF: • BLKW

ALLOCATE THE BUFFERS SPECIFIED ABOVE
250.
128.

;STEP 4:

GENERATE RMS INTERNAL SPACE POOL
;BEGIN POOL SPECIFICATION
2
;A FAB FOR EACH FILE
2
;A RAB FOR EACH FAB
2
;AN I/O BUFFER FOR EACH RAB
1024
;MINIMUM BUFFER SIZE IS 512. BYTES
;END OF POOL SPECIFICATION

POOL$B
P$FAB
P$RAB
P$BDB
P$BUF
POOL$E
;STEP 5:
ORG$
;STEP 6:

ERROR:

DEFINE THE RMS FUNCTIONALITY REQUIRED
SEQ,<CRE,GET,PUT>
;SEQUENTIAL FILES ONLY, $FIND,
;$UPDATE, $DELETE NOT REQUIRED

PROVIDE A GENERAL ERROR ROUTINE TO HANDLE UNEXPECTED
ERRORS WHICH MIGHT OCCUR (WHAT IF FILEl.DAT DID NOT
EXIST, OR CONTAINED A RECORD LARGER THAN 500 BYTES?).
THIS IS AN ALTERNATIVE TO THE 'COMPLETION ROUTINE'
;
FUNCTION PROVIDED BY RMS.
; (CODE WHICH WILL HANDLE THE ERROR, PROMPT AT THE TERMINAL FOR
;FURTHER INSTRUCTIONS, ETC.)

;STEP 7:

WRITE THE PROGRAM
;

START:

B-2

$!NIT
$OPEN
MOV

#FABl
#FABl,RO

Sample RMS-11 Programs

; INITIAL! Z E RMS.
; OPEN FILE 1. DAT,
;SET UP FOR $COMPARE:

1$:

$COMPARE #0,STS,RO
SGT
1$
JSR
PC,ERROR
MOV
#FAB2,Rl
$FETCH R2,RAT,RO
$STORE R2,RAT,Rl
$FETCH R2,RFM,RO
$STORE R2,RFM,Rl
$FETCH R2,FSZ,RO
$STORE R2,FSZ,Rl
$FETCH R2,MRN,RO
$STORE R2,MRN,Rl
$FETCH R2,MRS,RO
$STORE R2,MRS,Rl

;NEG STS VALUE MEANS OPEN FAILURE
;BRANCH IF SUCCESSFUL
;OTHERWISE EXECUTE ERROR ROUTINE.
;COMPLETE INITIALIZATION OF FAB2:
;GET RAT FIELD FROM FABl
;AND MOVE IT INTO FAB2;
;DO THE SAME WITH THE RFM FIELD;
;FSZ IS PERTINENT ONLY IF FILEl.DAT
;MAY CONTAIN VFC RECORDS.
;YOU MAY OR MAY NOT WISH TO TRANSFER
;MRN, MRS, AND FOP. IF MRN IS COPIED,
;REMEMBER THAT IT IS A 2-WORD FIELD,
;AND WILL DESTROY THE CONTENTS OF R3.

;

2$:

3$:

4$:

5$:

6$:
DONE:

1$:

;INITIALIZATION OF FAB2 SHOULD NOW BE COMPLETE EXCEPT FOR ANY
;SPECIAL CASES (FOR EXAMPLE, IF FILE2.DAT IS ON MAGNETIC TAPE,
;YOU MAY WISH TO SET THE BLS FIELD).
$FETCH R2,ALQ,RO
$STORE R2,ALQ,Rl
;NOW CREATE FILE2.DAT (Rl=FAB2):
$CREATE Rl
;CHECK FOR FAILURE
$COMPARE #0,STS,Rl
SGT
2$
;BRANCH IF SUCCESSFUL
;OTHERWISE EXECUTE ERROR ROUTINE.
JSR
PC,ERROR
MOV
#RABl,RO
;CONNECT THE RABS.
MOV
#RAB2,Rl
$CONNECT
RO
$COMPARE #0,STS,RO
SGT
3$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
$CONNECT Rl
$COMPARE #0,STS,Rl
SGT
4$
JSR
PC,ERROR
$GET
RO
;GET A RECORD FROM FILEl.DAT.
$COMPARE #ER$EOF,STS,RO ;WERE WE AT END-OF-FILE?
;IF SO, CLEAN UP AND EXIT.
SEQ
DONE
$COMPARE #0,STS,RO
;SOME OTHER ERROR?
SGT
5$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
;IF SO, HANDLE IT.
$FETCH R2,RSZ,RO
;COPY RECORD LENGTH FROM
$STORE R2,RSZ,Rl
;RABI TO RAB2.
;OUTPUT THE RECORD TO FILE2.DAT.
$PUT
Rl
$COMPARE #0,STS,Rl
SGT
6$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
BR
4$
;LOOP UNTIL DONE.
MOV
#FABl,RO
;BACK TO THE FASS FOR $CLOSE.
MOV
#:e'AB 2, Rl
$CLOSE RO
$COMPARE #0,STS,RO
SGT
1$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
$CLOSE Rl
$COMPARE #0,STS,Rl
SGT
2~?
JSR
PC,ERROR
Sample RMS-11 Programs

B-3

2$:

;RMS IS NOW DONE:
FILE2.DAT NOW CONTAINS ALL THE DATA RECORDS
;OF FILEl.DAT, PLUS OTHER INFORMATION (MRS, MRN, ETC.)
; YOU CHOSE TO DUPLICATE. INSERT YOUR OWN EXIT CODE AND EXIT.
. END
START

·.~

B-4

Sample RMS-11 Programs

B.2

COUNTING WORDS IN A SEQUENTIAL FILE

This sample program reads through a sequential
file named RNO.DOC,
noting pages and counting words.
The program uses RMS-11 for terminal
I/O.
.TITLE WORDS.MAC
• SB TTL READ A DOCUMENTATION FILE AND COUNT THE WORDS
; SO CAN USE RO, Rl, ETC •
• ENABL REG
• NLIS'I' ME
.NLIST BIN
PROGRAM TO READ A DOC FILE PRODUCED BY RUNOFF OR RNO AND
; COUNT THE WORDS,
STORING ENTRIES IN AN RMS ISAM FILE
;

.MCALL
.MCALL
.MCALL
.MCALL
$GNCAL
$FBCAL
$RBCAL

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

;

; THE FAB FOR THE INPUT DOC FILE, NAMED RNO.DOC, MUST
; COMPLETELY DESCRIBE THE FILE AT ASSY TIME TO SAVE RUN TIME.
;

• SB TTL RMS-11 DATA BLOCKS
• PAGE
.EVEN
DOCFAB: FAB$B
F$BPA
0
F$BPS
0
F$DNA
0
F$DNS
0
F$FAC
FB$GET
F$FNA
DOC NAM
F$FNS
DOCNML
F$FOP
0
F$LCH
1
F$NAM
0
F$0RG
FB$SEQ
F$RFM
FB$STM
F$RTV
0
F$SHR
0
F$XAB
0
FAB$E
DOCNAM: .ASCII /RNO.DOC/
DOCNML = .-DOCNAM

BEGIN MINIMUM INITIALIZATION
NO PRIVATE BUFFER POOL
DITTO
USE SYSTEM DEFAULTS
DITTO
ONLY GET RECORD OPERATIONS
FILE NAME ADDRESS
FILE NAME LENGTH
NOT CONTIGUOUS
LOGICAL CHANNEL FOR FILE 1
NO NAM BLOCK
; FILE ORGANIZATION
DOC FILES ARE STREAM
VOLUME CLUSTERSIZE
NOBODY ELSE
NO XABs
END INITIALIZATION BLOCK
ASSUME SYSTEM DEFAULTS

; NEED CRT TO OUTPUT MESSAGES TO TERMINAL RUNNING JOB
;

.EVEN
CRTFAB: FAB$B
F$FAC

FB$PUT

BEGIN MINIMUM INITIALIZATION
; OUTPUT ONLY
Sample RMS-11 Programs

B-5

F$FNA
CRTNAM
F$FNS
CRTNML
F$LCH
3
F$0RG
FB$SEQ
F$RFM
FB$VAR
FAB$E
CRTNAM: .ASCII /TI:/
CRTNML = .-CRTNAM

FILE NAME ADDRESS
FILE NAME LENGTH
LOGICAL CHANNEL FOR FILE
FILE ORGANIZATION
CRTS ARE VARIABLE
END INITIALIZATION BLOCK
ASSUME SYSTEM DEFAULTS

;

; INPUT RECORD IS SINGLE CHARACTER STRING, VARIABLE IN LENGTH
; THOUGH MOST WILL BE 70 CHARACTERS LONG (MARGINS 0 70).
;

.EVEN
DOCRAB: RAB$B
R$FAB
R$MBC
R$MBF
R$RAC
R$UBF
R$USZ
RAB$E

DOCFAB
1
1

RB$SEQ
DOCRCD
DOCRCL

BEGIN INITIALIZATION BLOCK
ADDRESS OF ASSOCIATED FAB
ONE AT A TIME
MULTI-BUFFER COUNT
RECORD ACCESS MODE(S)
USER RECORD BUFFER ADDRESS
USER-SET RECORD SIZE
END INITIALIZATION BLOCK

CRTRAB: RAB$B
R$FAB
CRTFAB
R$RAC
RB$SEQ
R$ROP
RB$EOF
RAB$E
• SBTTL BUFFERS AND MESSAGES
• PAGE
; BUFFERS

BEGIN INITIALIZATION BLOCK
ADDRESS OF ASSOCIATED FAB
RECORD ACCESS MODE

DOCRCD:

INPUT RECORD BUFFER
FILL WITH SPACES

.REPT
80.
.BYTE
040
• ENDR
DOCRCL = .-DOCRCD
.EVEN
WDCNT: • WORD
0
C HRCNT: • WORD
0
RECLEN: .WORD
0
XLTB UF:
PAGENO:
LIN ENO:

.WORD
• WORD
• WORD
• WORD

END INITIALIZATION BLOCK

COUNT WORDS IN FILE
COUNT CHAR IN RCDS AS DONE
; STORE RCD LENGTH AFTER RMS
RETURNS IT
0
; STOPPER FOR SCAN
1,10.,100.,1000.,10000.,0; POWERS OF 10
0
; PAGE COUNTER
0
; LINE COUNTER

;

; ARGUMENTS LISTS FOR RMS I/O OPERATIONS
;

DOC LST:

• WORD
.WORD
CRTLST: • WORD
.WORD

CRTRAB

LENGTH OF ARGUMENT LIST
RAB FOR RECORD BEING MOVED
LENGTH OF ARGUMENT LIST
RAB FOR RECORD BEING MOVED

014
040
055

FORM FEED
SPACE
HYPHEN

DOC RAB
1

;

VECTOR TABLES
;

CHC ODE:

B-6

• WORD
.WORD
.WORD

Sample RMS-11 Programs

CHCEND

= .-CHCODE

;

CHPRCS:

• WORD
.WORD
.WORD
.WORD

.NLIST

BIN

FFEED
SPACE
HYFEN
NOTS PA

;

; MESSAGES
;

ERRMSG: .ASCII /
ERROR /
ERRNBR: .ASCII /000000/
; FILL IN ERROR CODES
ERRMSL = .-ERRMSG
BGNMSG: .ASCIZ /START WORDS PROGRAM /
BGNMSL = .-BGNMSG
ENDMSG: .ASCIZ /END WORDS PROGRAM /
ENDMSL = .-ENDMSG
OPNMSG: .ASCII /RNO.DOC OPENED/
OPNMSL = .-OPNMSG
FFMSG:
.ASCII /PAGE
I
FFMSL = .-FFMSG
WDMSG:
.ASCIZ /
WORDS IN THIS LINE.
TOTAL WORDS =
WDMSL = • -WDMSG
LINMSG: .ASCII /LINE
IS TOO LONG./
.ASCIZ /
CONTINUING WITH NEXT LINE./
LINMSL = .-LINMSG
BLKS3:
.ASCIZ I
I

;

FILID:
• ASCIZ
DOC ID:
.ASCIZ
STVID:
.ASCIZ
• SBT'rL MACROS
• PAGE:
• LIS'r
BIN

/FILE/
/DOC I
/STV I

;

; MACROS
;

.MACHO

MOVWD
MOV

A,B,?C
A,R2

MOV
CLR
MOVB
INC
CMPB
BNE

; MOVE STRING A TO THE AREA
DESIGNATED BY B, COUNTING THE
B,R3
; CHARACTERS AS YOU GO
; INITIALIZE COUNTER
Rl
MOVE ONE CHARACTER
(R2)+, (R3)+
; COUNT IT
Rl
CHECK NEXT SOURCE WORD CHAR
O, (R2)
; GO BACK FOR MORE IF NOT ZERO
c

XLT28
MOV
MOV
MOV
MOV
ADD
JSR
MOV

A,B
RO,-(SP)
5,RO
A,Rl
B,R2
6,R2
PC, XLT8
(SP)+,RO

.ENDM
.MACRO

; 16-BIT NBR TO OCTAL ASCII
STORE RO AWAY
5 IS NBR OF CHARS IN BFR
PUT IN NBR
MOVE IN RCV BFR
MOVE TO END OF RCV BFR
DO IT
; BRING RO BACK FROM THE STACK
Sample RMS-11 Programs

B-7

.ENDM
I

.MACRO

XLT210
MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
JSR
MOV
MOV
MOV
MOV
MOV
MOV

A,B
RO,-(SP)
Rl,-(SP)
R2, - (SP)
R3,-(SP)
R4,-(SP)
RS,-(SP)
A,RO
B,RS
PC, XLTlO
(SP)+,RS
(SP}+,R4
(SP)+,R3
(SP)+,R2
(SP)+,Rl
(SP)+,RO

16-BIT NBR TO DECIMAL ASCII
SAVE REGISTER ON STACK
SAVE REGISTER ON STACK
SAVE REGISTER ON STACK
SAVE REGISTER ON STACK
; SAVE REGISTER ON STACK
; SAVE REGISTER ON STACK
PUT IN NUMBER
LOCATION OF lST BYTE RCV BFR
TRANSLATE IT
GET REGISTER BACK FROM STACK
GET REGISTER BACK FROM STACK
GET REGISTER BACK FROM STACK
GET REGISTER BACK FROM STACK
; GET REGISTER BACK FROM STACK
GET REGISTER BACK FROM STACK

WRTOUT
MOV
MOV
MOV
$STORE
$STORE
MOV
$PUT
MOV
MOV

A,B
R4,-(SP)
RS,-(SP)
CRTR.a. B, R4
A,RBF,R4
B,RSZ,R4
CRTLST,RS

OUTPUT MSG AND LENGTH
PUT RAB REFERENCE ON STACK
OUT ARG LIST REF ON STACK
PUT CRT RAB REFERENCE IN R4
MSG NAME IN RAB FLD
PUT MSG LENGTH IN RAB FLD
PUT CRT ARG LIST IN RS
WRITE MESSAGE TO CRT
POP OFF ORIGINAL ARG LIST
POP OFF ORIGINAL RAB REF

POOL$B
P$BDB

; BEGIN INITIALIZATION
2
; NBR =
; MAXBUF(l/SEQ)+MAXREL(0)+(2*MAXIDX(O))
1024.
; NBR =
DOC-STREAM-SIZE + CRT-STREAMS-SIZE
; DOC-STREAM-SIZE =
BKS ( 1) * ( S 12 *MBC ( 1) ) * MBF ( 1) = 512
CRT-STREAM-SIZE =
BKS (1) * (Sl2*MBC (1)) * MBF (1) = 512
2
FAB FOR EACH FILE
2
; TWO SEQUENTIAL FILES
END INITIALIZATION AREA

• ENDM
;

.MACRO

(SP)+, RS

(SP}+,R4
.ENDM
.SBTTL MAIN PROGRAM
.PAGE
; INTERNAL SPACE POOL
;

.EVEN

P$BUF

P$FAB
P$RAB
POOL$E

RMS FUNCTIONS NEEDED
ORG$

SEQ,<GET,PUT,FIN> ; SEQ FILE GETS, PUT,

FINDS

;

!!!!!!!!!!!!!!!

• EVEN
START:
B-8

$!NIT

Sample RMS-11 Programs

RUN - TIME

!!!!!!!!!!!!!!!!!!!!!!

INITIALIZE RMS

$OPEN
CRTFAB
MOV
CRTFAB,R4
$COMPARE O,STS,R4
BGT
2$
JMP
FILERR

OPEN CRT
; SET BLOCK TO LOOK AT
CHECK OUT STATUS FIELD
GO AROUND IF NO ERROR
ERROR CODE(S) AND QUIT

2$: $CONNECT CRTRAB
MOV
CRTRAB,R4
$COMPARE O,STS,R4
BG'r
4$
JMP
FILERR

HOOK UP CRT
; SET BLOCK TO LOOK AT
CHECK OUT STATUS FIELD
GO AROUND IF NO ERROR
ERROR CODE(S) AND QUIT

4$: WRTOUT

BGNMSG,BGNMSL

OUTPUT IT

$OPEN
DOCFAB
MOV
DOCFAB,R4
$COMPARE O,STS,R4
SGT
8$
JMP
FILERR

OPEN INPUT FILE
SET BLOCK TO LOOK AT
CHECK OUT STATUS FIELD
GO AROUND IF NO ERROR
ERROR CODE(S) AND QUIT

8$: WRTOUT OPNMSG,OPNMSL
$CONNECT DOCRAB
MOV
DOCRAB,R4
$COMPARE O,STS,R4
SGT
GETLIN
JMP
FILERR

HOOK UP INPUT FILE
SET BLOCK TO LOOK AT
CHECK OUT STATUS FIELD
GO AROUND IF NO ERROR
ERROR CODE(S) AND QUIT

;

GETLIN: MOV
MOV
JSR
RO
; Rl
R2
R3
R4
; RS

DOCRAB,R4
DOCLST, RS
PC, INPUT

; DOCERR GETS RIGHT CODE
DOC FILE ARG LIST
GET RECORD FROM DOC FILE

- POINTER TO INPUT LINE
- CHARACTERS/WORD COUNTER (TO HANDLE MULTIPLE SPACES)
- WORDS/LINE COUNTER
- VECTOR OFFSET INTO TABLE
·- DOCRAB
·- DOCLST

;

CLR
DOWORD: CLR
INC
CMP
SGT

Rl
R3
CHRCNT

INITIALIZE CHAR/WORD COUNTER
; INITIALIZE VECTOR OFFSET
CNT CHAR BEFORE LOOK AT IT

CHRCNT,RECLEN
12$

PAST END OF INPUT RCD YET?
IF SO, GO FINISH UP

4$: CMPB
SEQ
TST
CMP
BLT

CHCODE (R3), (RO)
8$
(R3) +
R3, CHCEND
4$

CHECK ON NEXT CHAR IN LINE
PROCESSING IF EQUAL
INCREMENT VECTOR
NOT IN TABLE?
CHECK NEXT ONE

8$: JSR
INCB

PC ,@CHPRCS (R3)
(RO)+

DO RIGHT THING
MOVE TO NEXT CHARACTER

;

Sample RMS-11 Programs

B-9

DOW ORD

;

;
;
;

12$: CMP
BEQ
INC
16$: CMP
BEQ
ADD
XLT210
XLT210
WRTOUT
MOVWD
18$: JMP

O,Rl
16$
R2
O,R2
18$
R2, WDCNT
R2, WDMSG
WDCNT, WDMSG+3 8.
WDMSG,WDMSL
B LKS 3, WDMSG
GETLIN

ANY CHARACTERS MOVED?
NOT A REAL LAST WORD
COUNT LAST WORD
ANY WORDS IN THIS LINE?
IF NOT, DON'T DO ANYTHING
ADD THIS LINE TO TOTAL
PUT CURRENT LINE IN MSG
PUT TOTAL CURRENT IN MSG
OUTPUT IT
COVER UP LAST WORD COUNT
GO BACK FOR NEXT LINE

;

.SBTTL SUBROUTINES
• PAGE

; ===========
; ===========

; SUBROUTINES

INPUT: $GET
$COMPARE O,STS,R4
BGT
2$
JMP
DOC ERR

GET RECORD FROM INPUT FILE
CHECK OUT STATUS FIELD
GO AROUND IF NO ERROR
ERROR CODE(S) AND QUIT

2$: $COMPARE O,RSZ,R4
BEQ
INPUT
MOV
RECLEN,R3
$FETCH
(R3) ,RSZ,R4
BR
8$

RECORD LENGTH = O?
IF SO, GO GET ANOTHER ONE
ADDRESS IN REGISTER
XFR RCD LEN TO BBFR
BYPASS WRITE OUT

; SPECIAL CASE OF WRTOUT HERE BECAUSE OF RECLEN
;

6$: MOV
MOV
MOV
$STORE
$STORE
MOV
$PUT
MOV
MOV

R4,-(SP)
RS,-(SP)
CRTRAB,R4
DOCRCD,RBF,R4
RECLEN,RSZ,R4
CRTLST,RS

8$: MOV
CLR
CLR
INC
RTS

DOCRCD,RO
R2
CHRCNT
LINENO
PC

(SP)+,RS
(SP)+,R4

.FFEED: INC
PAGE NO
CLR
LIN ENO
XLT210 PAGENO,FFMSG+S.
WRTOUT FFMSG,FFMSL
5. , R3
MOV
2$: $FIND
$COMPARE O,STS,R4
B-10

PUT RAB REFERENCE ON STACK
OUT ARG LIST REF ON STACK
PUT CRT RAB REFERENCE IN R4
PUT MSG NAME IN RAB FLD
PUT MSG LENGTH IN RAB FLD
PUT CRT ARG LIST IN RS
; WRITE MESSAGE TO CRT
POP OFF ORIGINAL ARG LIST
POP OFF ORIGINAL RAB REF
ADDR OF lST CHAR TO RO
INITIALIZE WORD COUNTER
INITIALIZE CHAR COUNTER
COUNT LINE/RECORD

ADD ONE TO PAGE NUMBER
; RESET LINE NUMBER
TURN IT INTO DECIMAL
ANNOUNCE FORM FEED
FIND CTR TO TOP OF TEXT
; MOVE PAST A LINE
CHECK OUT STATUS FIELD

Sample RMS-11 Programs

_ . . . ,_ _ _ _ _ _ _ _ _ _ _. . , ._ _ _ _ _ _ _ _ _ _ _ _ _ _, . . ._ _. __ _ _ _ _ _ _ _ _. _ . _...l_I'

RTS

GO AROUND IF NO ERROR
PULL R~N ADDR OFF STACK
ERROR CODE(S) AND QUIT
SUB ONE AND BRNCH IF <> 0
; READ NEXT RECORD
FOR COMMON INCREMENT
GET RID OF ANY RESIDUAL THAT
CAN COUNT WORD
; PROCESS IT

NOTSPA: INC
RTS

Rl
PC

COUNT IT
; LOOK AT NEXT CHARACTER

HYFEN: CMP
BNE
MOV
JSR

CHRCNT,RECLEN
LAST CHARACTER IN LINE?
TREAT IT LIKE ANY OTHER
NOTS PA
CIRCUMVENT INPUT
R2, - (SP)
; BRING IT CONTINUATION LINE
PC, INPUT
(DON'T WORRY ABOUT DOUBLE-SPACING
SINCE INPUT THROWS AWAY BLANK LINE)
BRING WORD COUNT BACK
(SP)+,R2
ANTICIPATE AUTO INCREMENT
RO
GET RID OF ANY RESIDUAL THAT
Rl
CAN COUNT WORD
PROCESS IT
PC

BGT
MOV
JMP
4$: SOB
JSR
DECB
CLR

4$
(SP)+,RO
DOC ERR
R3,2$
PC, INPUT
RO
Rl

;
;

MOV
DECB
CLR
RTS
SPACE: CMP
BEQ
CLR
INC
4$: RTS

O,Rl
4$
Rl
R2
PC

ANY CHARACTERS MOVED?
NONE WERE
CLEAR CHAR/WORD COUNTER
; ONE MORE WORD
; DO NEXT ONE

XLT8: MOV
BIC
ADD
MOVB
ASR
ASR
ASR
SOB

Rl,-(SP)
; USE STACK AS SCRATCH PAD
BlllllllllllllOOO,@SP ; CLR ALL BUT LAST 3
'O,@SP
; CHANGE DIGIT TO ASCII
(SP)+,-(R2)
MOVE CHARACTER INTO BUFFER
Rl
; 3 PLACES TO THE RIGHT
Rl
Rl
RO,XLT8
; LOOP IF MORE DIGITS

;

NOW CONVERT LEFTMOST BIT IN OCTAL NUMBER
BIC
ADD
MOVB
RTS
XLTlO: MOV
2$: TST
BEQ
CMP
BHIS

BllllllllllllllO,Rl ; GET BIT 15
'O,Rl
; CONVERT TO ASCII
Rl,-(R2)
MOVE TO BUFFER
PC
GO BACK
XLTBUF,R4
(R4)
4$
RO, (R4)+
2$

POINT TO POWERS OF 10
END OF TABLE?
YES
; START YET?
NO
Sample RMS-11 Programs

B-11

TST
4$: TST
BNE
MOVB
BR
6$: MOV
8$: CLR
DIV
ADD
MOVB
TST
BNE

- (R4)
- (R4)
6$
'O, (RS)+
10$
RO,R3
R2
(R4) ,R2
'0,R2
R2, (RS)+
- (R4)
8$

BACK UP TABLE
DITTO
NON-ZERO NUMBER TO PRINT
PRINT A ZERO
ALL DONE
MOVE NBR IN PREP FOR DIVIDE
MORE PREP FOR DIVIDE
DIVIDE BY POWER OF 10
MAKE QUOTIENT A CHARACTER
INSERT IN RCV BUFFER
GET ANOTHER POWER OF 10
NO THRU YET

10$: RTS

GO HOME WHEN DONE

;

.SBTTL ERROR ROUTINES
• PAGE

===========

ERROR ROUTINES

===========
;

ERROR ROUTINE FOR FILE OPERATIONS AND DOC FILE AND CRT
;

FILERR: MOVWD
FILID,ERRMSG
FILER!: $FETCH R2,STS,R4
XLT28
R2,ERRNBR
WRTOUT ERRMSG,ERRMSL
$COMPARE O,STV,R4
BEQ
DUN
MOVWD
STVID,ERRMSG
$FETCH R2,STV,R4
MOV
R2, - (SP)
XLT28
R2,ERRNBR
WRTOUT ERRMSG,ERRMSL
MOV
(SP)+,R2
MOV
6.,RO
4$: CLR
(RO)+
SOB
R0,4$
• LIST ME
XLT210 R2,ERRNBR
.NLIST ME
WRTOUT ERRMSG,ERRMSL
DUN: EXIT$S

MOVE ERROR CODE IN
FIGURE NBR; PUT IT IN BFR
PUT IT OUT
ANYTHING IN STV?
GO AROUND IF THERE'S NOT
MOVE COMPLETION VALUE IN
SO NO NEED FETCH IT AGN
; FIGURE NBR; PUT IT IN BFR
BRING BACK STV VALUE
NBR OF CHAR IN ERRNBR
ZERO THAT BYTE
TILL ALL ARE DONE
; MAKE IT A DECIMAL NUMBER
DISPLAY IT
QUIT THIS THING

ERROR ROUTINE FOR RECORD OPERATION ON INPUT FILE
;

DOCERR: $COMPARE ER$EOF,STS,R4
RUN OUT OF RECORDS?
BEQ
2$
GO AROUND IF THAT'S IT
$COMPARE ER$RTB,STS,R4
LINE TOO LONG?
BEQ
4$
GO AROUND IF THAT'S IT
MOVWD
DOCID,ERRMSG
IDENTIFY ERROR
JMP
FILER!
HANDLE LIKE OTHER ERRORS
2$: XLT210 WDCNT,WDMSG+38. ; PUT TOTAL CURRENT IN MSG
WRTOUT WDMSG+24. , 18.
; OUTPUT IT
WRTOUT ENDMSG,ENDMSL
PUT IT ON SCREEN
BR
32$
GO TO END
B-12

Sample RMS-11 Programs

4$: XLT210
WRTOUT
JMP
32$: EXIT$S

LINENO,LINMSG+S.; PUT IN LINE NUMBER
LINMSG,LINMSL
DISPLAY MSG
INPUT
GET NEXT RECORD (PC IS GOOD
'CAUSE NOT LEFT SUBRTN)
QUIT IT

;

.END START

Sample RMS-11 Programs

B-13

B.3

TESTING RELATIVE FILE CAPABILITIES

This sample program creates a Relative file, sets up a Record Access
Stream, and runs five tests:
1.

Test if can put a record with a relative record number greater
than the Maximum Record Number set for the file.

Test if can get records past the Maximum Record Number set for the
file.

Test if sequential get operations retrieve only valid records.

Test if sequential get operations retrieves deleted records.

Test if approximate match tests (KGE and KG'r) work during random
get operations.
.MCALL
.MCALL

$INIT,FAB$B,NAM$B,XAB$B,RAB$B,ORG$,POOL$B
$GNCAL,$FBCAL,$RBCAL,$STGDPLY,$GETSTG,EXIT$S

$GNCAL
$FBCAL
$RBCAL
;
;

POOL SPACE

POOLAR:
POOL$B
P$BDB
P$FAB
P$RAB
P$BUF
POOL$E

6
2

4608.

FAB AREA
.EVEN
FABAR:
FAB$B
F$BKS
F$FAC
F$FOP
F$LCH
F$MRS
F$0RG
F$RFM
FAB$E

;ALLOCATE FAB
2
;BUCKET SIZE
FB$GET!FB$PUT!FB$DEL ;DOING GETS AND PUTS
FB$TMD
;THIS FILE TO BE DELETED
1
;USE LOGICAL CHANNEL 1
80.
;MAX RECORD SIZE OF 80
FB$REL
;RELATIVE FILE
FB$VAR
;VARIABLE LENGTH RECORDS

RAB AREA
.EVEN
RABAR:
RAB$B
R$FAB
R$KBF
R$KSZ
R$RAC
B-14

FABAR
KEYNO
4

RB$SEQ

Sample RMS-11 Programs

;ALLOCATE RAB
;POINTS TO FAB AREA
;WHERE TO PUT RELATIVE KEY NUMBER
; KEY IS 4 BYTES
;WRITE RECORDS SEQUENTIALLY

R$RBF
R$UBF
R$USZ
RAB$E

RECBUF
RECBUF
150.

;ADDR OF RCD PUT OR GOT
;SAME AS RBF

FB$PUT
TFNAM
TFNAMS
FB$CTG!FB$TMD
768.
FB$SEQ
FB$CR
FB$FIX

;PUT TO THE FILE
;TERMINAL FILE NAME
;TERMINAL FILE NAME SIZE
;CONTIGUOUS SPACE, TEMP FILE
;LOGICAL CHANNEL 2
;MAX REC SIZE = 768. BYTES
;SEQUENTIAL FILE
;RECS DELIMITED BY CR AND LF
;FIXED FORMAT RECS

FABTI
RB$SEQ
BUFTI
80.

;FILE CTRL BLOCK ADDR
;SEQUENTIAL ACCESS
;USER BUFFER ADDR
;MAX SIZE = 80. BYTES

;

.EVEN
FABTI:
FAB$B
F$FAC
F$FNA
F$FNS
F$FOP
F$LCH
F$MRS
F$0RG
F$RAT
F$RFM
FAB$E

;

RABTI:
RAB$B
R$FAB
R$RAC
R$UB.F
R$USZ
RAB$E
;

LOCAL
·~·

SYMBOLS
CR = 15
LF = 12

;ASCII CARRIAGE RETURN
;ASCII LINE FEED

;

PRAMTR: .BLKW 1

;PARAMETER TO SEND INFO TO PRINT

;

HOLDIT: .BLKB
2
KEYNO:
• BLKB
4
KEYT ST: • BLKB
2
WITH HECORD PUT
DE LTST: • BLKB
2
TSTFOR: .BLKB
1
ERR:
• BLKB
1
RNFSET: .BLKB
1

;HOLD NUMBER FOR ASCII CONVERT
; RELATIVE KEY
;KEYTST TO COMPARE RECORD RETRIEVED
;TEST FOR DELETED RECORDS
;TO TEST FOR FOURTH TEST
;TEST FOR TEST 4 ERRORS
;TEST FOR RNF ERROR

;

.EVEN
;

BUFTI:

.BLKB

80 ()

;TERMINAL FILE BUFFER

;

RECBUF:
REC KEY:
REC LEN

.BLKW
• ASCII
=

2
/MISC • DATA/ <CR><LF>
RECBUF

;

TFNAM:
TFNAMS

.ASCII /TI:RELTST.ERR/
- TFNAM

;TERMINAL FILE NAME

Sample RMS-11 Programs

B-15

MSGTBL:
;

ERRl:
ERRlLN

.ASCII /ERROR CREATING TTY FILE/ <CR><LF>

= . - ERRl

;

ERR2:
ERR2LN

.ASCII /ERROR CONNECTING TTY FILE/ <CR><LF>

= . - ERR2

;

ERR3:
.ASCII /ERROR CREATING RELATIVE FILE/ <CR><LF>
ERR3LN = • - ERR3
;

ERR4:
.ASCII /ERROR CONNECTING RELATIVE FILE/ <CR><LF>
ERR4LN = • - ERR4
;

MSGS:
.ASCII /TEST I
TESTNO: .BLKB
2
sues:
.ASCII I SUCCESSFUL!/ <CR><LF>
MSGSLN = • - MSGS
;

ERR6:
ERR6LN

.ASCII /ERROR PUTTING RECORD TO FILE/ <CR><LF>

= . - ERR6

;

ERR7:
.ASCII /ERROR DELETING RECORD NUMBER
DELNUM: .BLKB
4
.ASCII <CR><LF>
ERR7LN = • - ERR7

;

ERR8:
.ASCII /ERROR GETTING RECORD FROM FILE/ <CR><LF>
ERR8LN = • - ERR8
;

ERR9:
ERR9LN

.ASCII /ERROR CLOSING FILE/ <CR><LF>

= . - ERR9

;

ERRlO:
.ASCII /ERROR REWINDING FILE/ <CR><LF>
ERlOLN = • - ERRlO
;

ERRll:
ERllLN

.ASCII /ERROR DISCONNECTING FILE/ <CR><LF>

= . - ERRll

;

ERR12:
.ASCII /RETRIEVED WRONG RECORD IN FILE/ <CR><LF>
ER12LN = • - ERR12
;

ERR13:
.ASCII /ERROR FINDING RECORD NUMBER /
FINDNO: .BLKB
4
CRLF13: .ASCII <CR><LF>
ER13LN = . - ERR13
;

ERR14:
.ASCII /ERROR - OVER 40. RECORDS WRITTEN ON TESTl/ <CR><LF>
ER14LN = • - ERR14
;

ERRlS:
.ASCII /DID NOT GET RECORD NUMBER
TSTSNO: .WORD
1
CRLF15: .ASCII
<CR><LF>
ERlSLN = • - ERR15

;

ERR16:
B-16

.ASCII /ERROR DISCONNECTING FILE/ <CR><LF>
Sample RMS-11 Programs

ER16LN =
ERRTBL:

'-"

"-""'

. - ERR16
• EVEN
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
ORG$
ORG$

ERRl
ERRlLN
ERR2
ERR2LN
ERR3
ERR3LN
ERR4
ERR4LN
MSGS
MSGSLN
ERR6
ERR6LN
ERR7
ERR7LN
ERR8
ERR8LN
ERR9
ERR9LN
ERRlO
ERlOLN
ERRll
ERllLN
ERR12
ER12LN
ERR13
ER13LN
ERR14
ER14LN
ER.Rl5
ER.15LN
ER.Rl6
ER.16LN
REL,<CRE,FIN,GET,PUT,DEL>
SEQ,<CRE,PUT>

;

START:
$!NIT

JSR

PC,CRETTY

;CREATE, CONNECT TTY FILE

JSR

PC,CREATE

;CREATE, CONNECT RELATIVE FILE

JSR

PC,TESTl

;TEST 1 BEGINS

JSR

PC,TEST2

;TEST 2 BEGINS

JSR

PC,CLOSE

;DISCONNECT AND CLOSE FILE

JSR

PC, TEST3

;TEST 3 BEGINS

JSR

PC, TEST4

;TEST 4 BEGINS

JSR

PC,TESTS

;TEST 5 BEGINS

;

Sample RMS-11 Programs

B-17

JSR

PC,CLOSE

;DISCONNECT AND CLOSE FILE

;

EXIT$S
;

;CREATE AND CONNECT THE TTY FILE
CRETTY:
MOV
O,PRAMTR
$CREATE FABTI, ENDIT
MOV
4,PRAMTR
$CONNECT RABTI, ENDIT
HTS
PC

;SET UP TTY CREATE ERRMSG
;CREATE TTY FILE
;SET UP TTY CONNECT ERR
;CONNECT TTY FILE

;

;CREATE THE RELATIVE FILE
;

CREATE:
MOV
$STORE
CLR
MOV
MOV
$STORE
MOV
$CREATE
RTS

RABAR,R4
RECLEN,RSZ,R4
Rl
40. ,RO
FABAR,RS
RO,MRN,RS
10,PRAMTR
RS, ENDIT
PC

;INITIALIZE RAB POINTER
;SET UP RECORD SilE
;RO Rl SET UP 2 WORD MRN
;SET UP RO FOR MRN
;SET UP FAB POINTER
;INITIALIZE 40. AS MRN
;SET UP CREATE REL FILE ERR
;CREATE THE FILE

""'·

CONECT:
MOV
14,PRAMTR
MOV
RABAR,RS
$CONNECT RS, ENDIT
RTS
PC

;SET UP CONNECT REL FILE ERR
;SET UP RAB POINTER
;CONNECT REL FILE

;

;REWIND THE FILE
;

REWIND:
MOV
44,PRAMTR
$REWIND RABAR, ENDIT
RTS
PC

;SET UP FOR REWIND ERROR
;GO TO B-0-F FOR NEXT TEST

;

;DISCONNECT AND CLOSE THE FILE
CLOSE:

MOV
74,PRAMTR
;SET UP FOR DISCONNECT ERROR
$DISCONNECT RABAR, ENDIT ;DISCONNECT FILE
MOV
40,PRAMTR
;SET UP FOR CLOSE ERROR
$CLOSE
FABAR, ENDIT
;CLOSE FILE
RTS
PC

;PRINT THE MESSAGES
;

PRINT:
MOV
MOV
ADD
MOV
$STORE
$STORE
B-18

O,R2
PRAMTR,R2
ERRTBL,R2
RABTI,R3
( R 2) , RB F , R3
2 ( R 2) , RS Z , R3

;CLEAR R2
;SET UP INDEX WITHIN TABLE
;POINTER TO ERROR MESSAGE
;POINTER TO ERROR TABLE
;STORE ADDRESS OF MESSAGE
;STORE SIZE OF MESSAGE

Sample RMS-11 Programs

j,,,_...____________..,._____________,___- __________._

$PUT
RTS

R3, BOMB
PC

;TTY MSG - BOMB ON ERROR

JSR

PC, PRINT

;PRINT ERROR MESSAGE

;

ENDIT:

'-''
BOMB:

BPT

;BOMB

;----------------------------------------------

;TEST 1
;
THIS IS A TEST OF MRN.
MRN SET TO 40.
WILL ATTEMPT TO WRITE 50. RECORDS.
SHOULD ENCOUNTER ER$MRN ERROR.

;----------------------------------------------

;

TES Tl:
CLR
JSR
~

"-"'

Rl
PC, CONEcrr

;INITIALIZE Rl
;CONNECT THE FILE

PUT IT::
INC
Rl
$PUT
R4
$COMPARE S U$S UC, STS, R4
BNE
Tl ERR
CMP
50. , Rl
BHI
PUT IT
MOV
64,PRAMTR
JSR
PC, ENDIT

;NEXT RECORD
;WRITE THE RECORD
;PUT ERROR?
;IF YES, GO TO TlERR
;WRITTEN 50 RECORDS YET?
;NO, GO WRITE SOME MORE
;SET UP FOR TEST 1 ERROR
;PRINT ERROR MESSAGE, BOMB

MOV
24,PRAMTR
$COMPARE ER$MRN,STS,R4
BNE
ENDIT
20,PRAMTR
MOV
61,TESTNO
MOV
JSR
PC, PRINT
JSR
PC, REWIND
RTS
PC

;SET UP FOR PUT ERROR
;MRN ERROR?
;NOT MRN ERROR--BOMB
;SET UP FOR SUCCESS MSG
;SET UP FOR PRINTING TEST 1
;PRINT SUCCESS MESSAGE
;RETURN TO B-0-F
;GO ON TO TEST 2

Tl ERR::

;----·---------------------------------------------------------IF TEST 1 IS SUCCESSFUL, RECORDS HAVE BEEN WRITTEN
UP TO MRN.
THAT IS, 40 RECORDS HAVE BEEN WRITTEN.
THE FILE HAS BEEN REWOUND, READY FOR TEST 2.

;-------------------------------------------------------------;-----------------~---------------------------------

;TEST 2
;
;
;

THIS TEST ATTEMPTS TO RETRIEVE RECORDS
SEQUENTIALLY BEYOND MRN.
SHOULD ENCOUNTER AN ER$EOF ERROR.
IT ATTEMPTS TO RETRIEVE 50 •. RECORDS.
AFTER THE 40.TH RECORD, AN ER$EOF ERROR
SHOULD RESULT.

;--------------------------------------------------

;

TEST2:
Sample RMS-11 Programs

B-19

MOV
CLR
MOV
MOV

RABAR,R4
Rl
34,PRAMTR
62,TESTNO

;SET UP RAB POINTER
;INITIALIZE RECORD COUNTER
;SET UP FOR GET ERROR
;SET UP FOR PRINTING TEST 2

T2INC:
INC
Rl
$GET
RABAR
$COMPARE SU$SUC,STS,R4
BNE
GETERR
CMP
50.,Rl
BNE
T2INC
RTS
PC

;INCREMENT RECORD COUNTER
;GET ANOTHER RECORD
; SUCCESSFUL GET?
;IF NOT, GO TO GETERR
;GOTTEN 50 RECORDS YET?
;IF NOT, CONTINUE
;YES, RETURN

GE TERR:
$COMPARE ER$&OF,STS,R4 ;EOF ERROR?
BNE
ENDIT
;NOT AN EOF ERROR - BOMB
MOV
20,PRAMTR
;SET UP FOR TEST SUCCESS MESSAGE
JSR
PC,PRINT
;PRINT SUCCESS MESSAGE
JSR
PC,REWIND
;GO TO BEGINNING OF FILE
RTS
PC
;GO ON TO NEXT TEST
;

;------------------------------------------------------------

;TEST 3

CREATE A NEW FILE.
PUT EVERY OTHER RECORD RANDOMLY UP TO AN MRN OF 40.
REWIND, AND GET SEQUENTIALLY.
SHOULD GET ONLY THOSE RECORDS JUST PUT.

;------------------------------------------------------------

;

TEST3:
JSR
$STORE
JSR
MOV
CLR
CLR

PC,CREATE
RB$KEY,RAC,R4
PC, CONECT
1, KEYNO
KEYN0+2
RECKEY+2

;CREATE NEW RELATIVE FILE
;RELATIVE ACCESS MODE
;CONECT THE FILE
;INITIALIZE THE RELATIVE KEY
;CLEAR 2ND WORD OF KEY
;CLEAR 2ND WD OF KEY IN FILE

;

;SET UP FILE - WRITE EVERY OTHER RECORD
;

SETUP:
MOV
MOV
$PUT
ADD
CMP
BHI
MOV
MOV

24,PRAMTR
KEYNO, REC KEY
RABAR, ENDIT
2,KEYNO
40., KEYNO
SETUP
20,PRAMTR
63,TESTNO

;SET UP FOR PUT ERROR
;PUT KEY NUMBER IN RECORD
;PUT RCD; ERROR = MSG, END.
; SKIP A RECORD
;FILE FULL?
;IF NOT, WRITE SOME MORE
;SET UP FOR TEST 3 SUCCESS
;SET UP FOR PRINTING TEST 3

;

;******** COMMON ROUTINE FOR TESTS 3 AND 4 **********
;
;

;REWIND AND REINITIALIZE
;

SEQGET:
CALL
MOV
$STORE
B-20

REWIND
-1,KEYTST
RB$SEQ,RAC,R4

Sample RMS-11 Programs

;RETURN TO BEGINNING OF FILE
;SET UP TO TEST FOR CORRECT RCD
;GET SEQUENTIALLY

;

;GET THE RECORDS SEQUENTIALLY
;

GETIT:
$GET
R4
;GET RECORD
$COMPARE SU$SUC,STS,R4 ;SUCCESSFUL GET?
BNE
GETERR
;IF NOT, TEST FOR E-0-F
;GETERR IN TEST 2
RECTS~r:

ADD
CMP
SEQ

2,KEYTST
KEYTST,RECKEY
GETIT

;EVERY OTHER RECORD
;RIGHT RECORD?
;IF SO, LET'S GET ANOTHER

CMPB
BNE
ADD
CMP
SEQ

1,TSTFOR
BADCON
6,DELTST
DELTST,KEYTST
RECTST

;IS IT TEST 4?
;IF NOT, WRONG RCD
;HOLD KEY OF NXT DELETED RCD
;IS IT A DELETED RECORD?
;YES, ADD 2 TEST AGAIN

MOV
JMP

~)4, PRAM TR
END IT

;WRONG RECORD = MSG
;PRINT OUT MESSAGE, BOMB

BADREC:

BADCON:

;----·--------------------------------------------------------

;TEST 4

TEST 4 USES THE FILE CREATED IN TEST 3.
SOME RECORDS ARE DELETED.
GET SEQUENTIALLY AND SEE IF DELETED RECORDS
ARE FOUND.

;----·--------------------------------------------------------

TEST4:

MOV
$STORE
MOV
MOV
MOV

RABAR,R4
RB$KEY,RAC,R4
-5,KEYNO
l, TSTFOR
-5,DELTST

;SET UP RAB POINTER
;DELETE USING RANDOM
;!NIT REL KEY FOR DELETES
;SET UP FOR FOURTH TEST
;!NIT FOR DELETED RCD KEY

ADD
JSR
CMP

6, KEYNO
PC, FINDIT
37. , KEYNO

SHI
CMPB
SEQ
JMP

NXTDEL
O,ERR
GET4
BOMB

;DELETE EVERY 4TH RECORD
;GO DELETE IT
;LAST RECORD
;TO BE DELETED BEFORE EOF?
;IF NOT, DELETE SOME MORE
;ANY ERRORS ENCOUNTERED?
;NO ERRORS, GET SEQUENTIALLY
;ERRORS FOUND - BOMB

MOV
MOV
JSR
RTS

20,PRAMTR
64,TESTNO
PC, SEQGET
PC

;SET UP FOR TEST 4 SUCC MSG
;SET UP FOR PRINTING TEST 4
;READY TO GET SEQUENTIALLY
;GO ON TO NEXT FILE

NXTDEL:

'-''
GET4:

FINDIT:
$FIND
HABAR
$COMPARE SU$SUC,STS,R4 ;FIND SUCCESSFUL?
SEQ
DELETE
;IF IT WAS, DELETE RECORD
MOV
60,PRAMTR
;SET UP FOR FIND ERROR
MOV
KEYNO,RO
;SET UP FOR KEY NO.
;CONVERSION TO ASCII
JSR
PC,CONVER
;CONVERT RCD NBR TO ASCII
Sample RMS-11 Programs

B-21

MOV
JSR
RTS

HOLDIT,FINDNO
PC, PRINT
PC

;PUT RCD NBR IN ERRMSG
;PRINT ERROR MESSAGE
;GO ON TO NEXT RECORD

DELETE:
$DELETE RABAR
$COMPARE SU$SUC,STS,R4
BEQ
RETURN
MOV
30,PRAMTR
MOV
KEYNO,RO
CALL
CONVER
MOV
HOLDIT,DELNUM
JSR
PC,PRINT

;DELETE RECORD
;SUCCESSFUL DELETE?
;IF SUCCESSFUL, CONTINUE
;SET UP FOR DELETE ERRMSG
;SET UP FOR ASCII CONVERT
;CNV KEY NBR TO ASCII FOR ERRMSG
;PUT RCD NBR IN ERRMSG
;PRINT ERROR MESSAGE

;

RETURN:
RTS

;GO ON TO NEXT RECORD

;

;CONVERSION TO ASCII TO PRINT OUT RCD NBR IN ERRMSG
CONVER:
MOVB
MOV
$STORE
MOV
MOV

l,ERR
;NOTE THAT ERROR OCCURRED
;SET UP RAB PNTR AFTER ERR
RABAR,R4
;RESET TO GOOD STATUS
l,STS,R4
l,R3
; SET UP R3 FOR INDEXING
;SET UP R2 TO LOOP 2 TIMES:
2,R2
;ONCE FOR EACH BYTE

MOV
BIC
ADD
MOVB
MOV
ASR
ASR
ASR
DEC
SOB
RTS

RO,-(SP)
-10,RO
60,RO
RO,HOLDIT(R3)
(SP)+,RO
RO
RO
RO
R3
R2,LOOP
PC

LOOP:
;SAVE REMAINDER FOR CNV
;CLEAR ALL BUT LOW ORDER 3 BITS
;CONVERT TO ASCII
;STORE IT IN RECORD
;GET COUNTER
;SHIFT RIGHT 3 BITS
;TO WORK ON EACH DIGIT
;MOVE TO NXT BYTE OF RECKEY
;DIGIT IN EACH BYTE??

;-------------------------------------------------------

;TEST 5

;
;
;
;
;

THIS TEST WILL TEST THE ROP FIELDS OF
KGT AND KGE.
AFTER SUCCESSFUL COMPLETION OF TEST 4,
THE FILE WILL NOW HAVE OCTAL RECORDS:
3,5,11,13,17,21,25,27,33,35,41,43,47.
USING THIS INFORMATION, WE WILL TEST
'KEY GREATER THAN' AND 'KEY GREATER THAN
OR EQUAL TO'.

;-------------------------------------------------------

;

TESTS:
MOV
$STORE
$STORE
JSR
$STORE
B-22

RABAR,R4
RB$KEY,RAC,R4
RB$KGT,ROP,R4
PC, KGT
RB$KGE,ROP,R4

Sample RMS-11 Programs

;SET UP RAB POINTER
;USING RANDOM
;SET UP KEY GREATER THAN
;DO KEY GREATER THAN TEST
;SET UP KEY GTR'N OR =TO

""'·

JSR
JSR
CMPB
BEQ
RTS

PC, REWIND
PC, KGE
O,ERR
GOODS
PC

;GO TO BEGINNING OF FILE
;DO KEY GTR'N OR = TEST
;ANY ERRORS DETECTED?
;NO ERRORS = SUCCESS MSG

MOV
MOV
CALL
RTS

6S,TESTNO
20,PRAMTR
PRINT
PC

;MOV S INTO SUCCESS MESSAGE
;SET UP FOR TEST S SUCC MSG
;PRINT MESSAGE
;DONE WITH TEST S

MOV
MOV
JSR
MOV
MOV
CALL
MOV
MOV
JSR
MOV
MOVB
JSR
RTS

5,KEYNO
11,RO
PC ,GETS
20, KEYNO
21,RO
GETS
27,KEYNO
33,RO
PC,GETS
47,KEYNO
l,RNFSET
PC, GETS
PC

;WE WANT THE NEXT REC GT S
;IT SHOULD BE RECORD 11
;GET THE RECORD
;TRY NEXT REC GTR'N 20
;WE SHOULD GET RECORD 21
;GET THE RECORD
;WANT THE NEXT REC GTR'N 27
;WE SHOULD GET RECORD 33
;GET THE RECORD
;GET REC GT 47
;SET UP TO TEST FOR RNF
;SHOULD GET RNF ERROR
;GO ON TO KGE TEST

MOV
MOV
JSR
MOV
MOV
CALL
MOV
MOV
CALL
MOV
MOV
JSR
RTS

5,KEYNO
5,RO
PC, GETS
20,KEYNO
21,RO
GETS
27,KEYNO
27,RO
GETS
47,KEYNO
47,RO
PC, GETS
PC

;WE WANT THE REC. GE S
;SHOULD GET RECORD S
;GET THE RECORD
;WE WANT THE REC. GE 20
;WE SHOULD GET RECORD 21
;GET THE RECORD
;WE WANT THE REC. GE 27
;SHOULD GET RECORD 27
;GET THE RECORD
;WE WANT THE REC. GE 47
;SHOULD GET RECORD 47
;GET THE RECORD
;DONE WITH TEST S

GOODS::

KGT:

KGE:

GETS:
$GET
R4
$COMPARE SU$SUC,STS,R4
BEQ
COM PAR
CMPB
l,RNFSET
BNE
GT SERR
MOVB
O,RNFSET
$COMPARE ER$RNF,STS,R4
BNE
GT SERR
RTS
PC

;GET THE RECORD
;SUCCESSFUL GET?
;YES = TEST FOR CORRECT RCD
;TESTING FOR RNF ERROR?
;NO = CONT ERR PROCESSING
;RESET FOR NO RNF ERROR
;DID WE GET AN RNF ERROR?
;NO, THERE'S REALLY AN ERROR
;RNF ERR = GOOD, CONTINUE

MOV
$STORE
MOVB
JSR
RTS

34,PRAMTR
l,STS,R4
l,ERR
PC, PRINT
PC

;SET INDEX FOR GET ERR
;RESET TO GOOD STATUS
;SET ERR BYTE
;PRINT GET ERROR MESSAGE

CMP
BNE

RO, REC KEY
ERRORS

;CORRECT RECORD?
;IF NOT GO TO ERROR ROUTINE

GT SERR:

COMPAR:

Sample RMS-11 Programs

B-23

RTS

;WE DID, CONTINUE

MOV
JSR
MOV
CALL
RTS

70,PRAMTR
PC, CONVER
HOLDIT,TST5NO
PRINT
PC

;SET INDEX IN TABLE FOR ERROR MSG
;CNV RCD NBR TO ASCII FOR PRINT
;PUT RCD NBR IN MSG
;PRINT THE MESSAGE

.END

START

ERRORS:

"""·

B-24

Sample RMS-11 Programs

APPENDIX C
DATE CONVERSION ROUTINE

;

$CDTTA - CONVERT DATE AND TIME TO ASCII

.!DENT

"XOOOl"

COPYRIGHT (C) 1977 BY DIGITAL EQUIPMENT CORPORATION,
COPYRIGHT (C) 1976 BY DIGITAL EQUIPMENT CORPORATION,
MAYNARD, MASSACHUSETTS
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE, OR
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS.
TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DIGITAL.

;

.TITLE

THE INFORMATION IN THIS SOFTWARE 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
THE usg OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS
NOT SUPPLIED BY DIGITAL.
ANDREW C.

GOLDSTEIN 20 JUN 76 14:12

SMACIT
.MACRO
JSR
.ENDM

$SAVRG
R5,$SAVRG
$SAVRG

.MACRO .QUAD
$$$Bl=O
$$$B2=0
$$$B3=0
$$$B4=0
$$$B5=0
$$$B6=0
$$$B7=0
$$$B8=0

WORD

• IRPC
D, WORD
$$$Bl=$$$Bl*l0.+D'.
$$$C=$$$Bl/256.
$$$Bl=$$$Bl0377
$$$B2=$$$B2*10.+$$$C
$$$C=$$$B2/256.
$$$B2=$$$B20377
$$$B3=$$$B3*10.+$$$C
$$$C=$$$B3/256.
$$$B3=$$$B30377
$$$B4=$$$B4*10.+$$$C
$$$C=$$$B4/256.
$$$B4=$$$B40377
$$$B5=$$$B5*10.+$$$C
$$$C=$$$B5/256.
$$$B5=$$$B50377
$$$B6=$$$B6*10.+$$$C
$$$C=$$$B7/256.
$$$B6=$$$B60377
$$$B7=$$$B7*10.+$$$C
$$$C=$$$B7/256.
$$$B7=$$$B70377
$$$B8=$$$B8*10.+$$$C
$$$C=$$$B8/256.
$$$B8=$$$B80377
• ENDM
$$$Wl=$$$B2*256.+$$$Bl
$$$W2=$$$B4*256.+$$$B3
$$$W3=$$$B6*256.+$$$B5
$$$W4=$$$B8*256.+$$$B7
• LIST
MEB
.WORD
$$$Wl,$$$W2
.WORD
$$$W3,$$$W4
• NL I ST MEB
.ENDM
.QUAD
SOME CONSTANTS

QNS:
QND:

.RADIX

• QUAD
.WORD
.WORD
• QUAD
.WORD
.WORD

10000000
$$$Wl,$$$W2
$$$W3,$$$W4
864000000000
$$$Wl,$$$W2
$$$W3,$$$W4

FDAYS = 365*4+1
CDAYS
QDAYL
QDAYH
DS15L
DS15H

C-2

= FDAYS*25-l
= 15025
= 2
= 65176
= 1

Date Conversion Routine

TENTHS OF MICROSECONDS IN A SECOND
TENTHS OF MICROSECONDS IN A DAY

NUMBER OF DAYS IN 4 YEARS
AND NUMBER OF QUARTER DAYS IN A YEAR
NUMBER OF DAYS IN A CENTURY
NUMBER OF DAYS IN QUADRICENTURY, LOW
NUMBER OF DAYS IN QUADRICENTURY, HI
NUMBER OF DAYS BETWEEN l-JAN-1501
AND 17-NOV-1858, LOW AND HIGH

.RADIX
;+

1
"

$COTTA CONVERT DATE/TIME TO ASCII

;

THIS ROUTINE CONVERTS THE STANDARD DATE/TIME REPRESENTATION INTO
AN ASCII STRING.
THE FORMATTING OF THE STRING IS CONTROLLED BY
OPTION BITS ON INPUT.
;

INPUTS:
;

RO
Rl
R2

= ADDRESS TO STORE ASCII STRING
= ADDRESS OF 64 BIT DATE/TIME
= OPTION FLAGS:
BIT 0 = 1 IF DATE NOT WANTED
BIT 1 = 1 IF TIME NOT WANTED
BIT 2 = 1 IF TIME WANTED IN AM/PM
BIT 3 = 1 IF SECONDS NOT WANTED

OU'rPUTS:
RO UPDATED TO END OF GENERATED STRING
OTHER REGISTERS PRESERVED
THE DATE ALGORITHM BELOW ACCOUNTS FOR THE COMMON LEAP YEAR CYCLES EVERY FOURTH YEAR IS, EXCEPT EVERY lOOTH ISN'T, EXCEPT EVERY 400TH
IS.
YEAR 2000 IS A LEAP YEAR.
THE CODE IS BASED ON ALGORITHMS
WRITTEN BY P.CONKLIN, J.BARNABY, D.ROSENBERG, AND M.SPEIR.
;-

$COTT.A: :
$SAVRG
MOV
MOV
MOV
SUB
MOV
ADD
MOV
MOV
JSR

SAVE ALL REGISTERS
Rl,-(SP)
R2,-(SP)
RO,R5
#16.,SP
SP,R3
#8.,R3
#QND,RO
SP,R2
PC, $DIVQ

ALLOCATE TWO QUAD SLOTS
SPLIT DATE/TIME INTO DAY AND TIME

TOP OF STACK CONTAINS DAYS SINCE 17-NOV-1858.
RE.AL DATE.
BIT
BNE
MOV
MOV

#1, 16. (SP)
LO
(SP) ,R3
2(SP),R2

ADD
ADC
ADD

#DS15L,R3
R2
#DS15H,R2

CONVERT THIS TO A

DO OF DATE REQUESTED
DAY SINCE 17-NOV-1858 IS
LESS THAN 32 BITS
ADD THE OFFSET SO WE HAVE THE NUMBER
OF· DAYS SINCE l-JAN-1501, ALIGNING
CYCLES SO THAT THE LATER
TRUNCATIONS AND ROUND-OFFS WORK.

Date Conversion Routine

C-3

DIVIDE BY THE NUMBER OF DAYS IN
A QUADRICENTURY
MOV
MOV
JSR

#QDAYH,RO
#QDAYL,Rl
PC, $DIVD

ASL
ASL
MOV
ASL
ROL
ASL
ROL
MOV
MOV

R3
R3
R3,-(SP)
Rl
RO
Rl
RO
Rl,R3
RO,R2

RO,Rl = DAYS INTO THIS QUADRICENTURY
R3 = QUADRICENTURIES SINCE 1501
CONVERT TO CENTURIES
;
;

AND SAVE
CONVERT NUMBER OF DAYS INTO
NUMBER OF QUARTER DAYS
BY MULTIPLYING BY 4

DIVIDE BY THE AVERAGE NUMBER OF
QUARTER DAYS IN A CENTURY
MOV
MOV
JSR

#QDAYH,RO
#QDAYL,Rl
PC, $DIVD

ADD

R3, (SP)

RO,Rl = QUARTER DAYS INTO CENTURY
R3 = CENTURIES IN THIS QUAD CENTURY
ADD TO ACCUMULATED TIME

;

BY BASING THE TIME AT 1501, THE CENTURY HAS AN EXTRA LEAP DAY
INTO THE FIRST CENTURY OF THE QUADRICENTURY.
NOW DISCARD ANY
FRACTION OF A DAY LEFT FROM THE PREVIOUS DIVISION AND ADD IN 3/4
OF A DAY TO FORCE THE LEAP YEAR INTO THE LAST YEAR OF EACH 4 YEAR
CYCLE.
BIS
MOV
MOV
MOV
MOV
JSR
MOV
ASR
ASR
INC
MOV
MOV
JSR
ADD
ADD
MOV
;

NOW DIVIDE BY THE AVERAGE NUMBER OF
QUARTER DAYS IN A YEAR

NUMBER OF DAY IN YEAR

COMPUTE # YEARS IN CENTURIES
COMPUTE TRUE CALENDAR YEAR
SAVE FOR FINAL OUTPUT

FIND OUT WHETHER THIS YEAR IS A LEAP YEAR.
IF NOT, BIAS THE DAY IF
IT IS PAST FEBRUARY:
THE MONTH TABLE IS WRITTEN FOR A LEAP YEAR.
MOV
MOV
MOV
JSR
TST
BNE

C-4

#3,Rl
Rl,R3
RO,R2
#0, RO
#FDAYS, Rl
PC, $DIVD
Rl,R2
R2
R2
R2
#100.,RO
(SP)+,Rl
PC, $MULUS
R3,Rl
#1501., Rl
Rl,-(SP)

#1, R4
(SP) ,RO
#400.,Rl
PC, $DIV
Rl
Ll

Date Conversion Routine

!NIT LEAP YEAR FLAG TO NO
EVERY 400TH IS A LEAP YEAR
FROM SYSLIB

"'
l

CLR
BR

R4
L2

MOV
MOV
JSR
TST
BEQ
MOV
MOV
JSR
TST
BNE
CLR

(SP) ,RO
#100.,Rl
PC, $DIV
Rl
L3
(SP) ,RO
#4,Rl
PC, $DIV
Rl
L4
R4

L 1:

EVERY lOOTH IS NOT
FROM SYSLIB
AND EVERY 4TH IS
FROM SYSLIB

L4:
L3:
L2:
IF THIS IS NOT A LEAP YEAR,
BIAS THE DAY UP ONE IF IT IS
PAST FEBRUARY.
CMP
BLOS
ADD

R2, #31. +28.
L5
R4,R2

L 5:

SCAN THE MONTH TABLE AND FIND OUT WHAT MONTH THIS IS.
CLR

MOVB
CMP
BLOS
SUB
INC
CMP
BLT

$DAYTB(Rl),RO
R2,RO
EO
RO,R2
Rl
Rl, #11.
BO

B 0:

GET NUMBER OF DAYS IN MONTH

E 0:

R2 = DAY, Rl = MONTH
START TO CRANK OUT THE ASCII DATE
MOV
MOV
MOV
MOV
JSR
MOVB

Rl,-(SP)
RS,RO
R2, Rl
#0,R2
PC, $CBDMG
#'-,(RO)+

MOV
(SP) ,Rl
ASL
Rl
ADD (SP)+,Rl
ADD
#$MONTS, Rl
MOVB
(Rl)+
MOVB
(Rl)+, (RO)+
MOVB
(Rl)+, (RO)+
MOVB
#'-,(RO)+
MOV
(SP)+,Rl

DAY NUMBER

DASH
INDEX INTO THE MONTH NAME TABLE

FILL IN MONTH NAME
DASH
ADD YEAR
Date Conversion Routine

C-5

MOV
JSR
MOVB
MOV

#0,R2
PC, $CBDMG
#40,(RO)+
RO,RS

AND A SPACE
SAVE THE POINTER WHILE WE MESS
WITH THE TIME OF DAY

LO:
NOW CONVERT THE TIME OF DAY TO ASCII
BIT
BNE
MOV
ADD
MOV
SUB
MOV
MOV

~JSR

#2, 16. (SP)
L6
SP,Rl
#8. , Rl
SP,R3
#8. ,SP
#QNS,RO
SP,R2
PC, $DIVQ
(SP)+,R3
(SP)+,R2
(SP)+, (SP)+
#0,RO
#60.,Rl
PC, $DIVD
Rl,-(SP)
#60. ,Rl
PC, $DIVD
Rl,-(SP)
#24. ,Rl
PC, $DIVD

MOV
JSR
MOVB
MOV
JSR
MOV
BIT
BNE
MOVB
JSR

Rl,RO
PC, C2D
#':,(RS)+
(SP)+,RO
PC, C2D
(SP)+,RO
#10, 16. (SP)
L7
#':,(RS)+
PC,C2D

MOV

RS,RO

RETURN FINAL STRING POINTER

ADD
MOV
MOV
RTS

#16. ,SP
(SP)+,R2
(SP)+,Rl
PC

FINAL STACK CLEANUP

~JSR

MOV
MOV
CMP
MOV
MOV
JSR
MOV
MOV
JSR
MOV
MOV

DO IF TIME REQUESTED
POINT TO TIME ON STACK
ALLOCATE ONE MORE QUAD
REDUCE TO TIME IN SECONDS
WHICH IS EXPRESSIBLE IN 32 BITS
CLEAN GARBAGE FROM STACK
DIVIDE OUT SECONDS
AND SAVE THEM
DIVIDE OUT MINUTES
AND SAVE
AND DIVIDE OUT HOURS
OUTPUT ASCII TIME OF DAY

GET SECONDS
IF SECONDS WANTED

L7:
L6:

*** - C2D

CONVERT BINARY TO 2 DECIMAL DIGITS

THIS ROUTINE IS USED TO OUTPUT THE COMPONENTS OF THE TIME
INPUTS:
;

RO
C-6

= BINARY VALUE

Date Conversion Routine

OU'I'PUTS:
TWO DIGITS STORED AT RS
RS BUMPED BY 2
RO,Rl CLOBBERED

;
;

;C2D:
MOV
JSR
ADD
ADD
MOVB
MOVB
RTS

#10.,Rl
PC,$DIV
#'O,RO
#'O,Rl
RO, (RS)+
Rl, (RS)+
PC

SPLIT THE DIGITS
FROM SYSLIB
CONVERT TO ASCII

- $DIVD

DOUBLE PRECISION DIVIDE

AND STORE

;

;+
**~~

;

THIS ROUTINE PERFORMS AN UNSIGNED DIVIDE WITH 32 BIT DIVISOR,
DIVIDEND, QUOTIENT, AND REMAINDER.
DIVIDE BY ZERO IS NOT CHECKED.
ANDREW Co

GOLDSTEIN 4 MAR 76 11:41

BASED ON THE ALGORITHM IN RT-ll'S LIBRARY ROUTINE JDIV
INPUTS:
;

RO = HIGH ORDER DIVISOR
Rl = LOW ORDER DIVISOR
R2 = HIGH ORDER DIVIDEND
R3 = LOW ORDER DIVIDEND

;

OU'l'PUTS:

;

RO - HIGH ORDER REMAINDER
Rl = LOW ORDER REMAINDER
R2 = HIGH ORDER QUOTIENT
R3 = LOW ORDER QUOTIENT
R4,RS PRESERVED

;

$DIVD: :

10$:

MOV
MOV
MOV
CLR
CLR
ROL
ROL
CMP
BHI
BNE
CMP

R4,-(SP)
RS,-(SP)
#33.,-(SP)
R4
RS
RS
R4
RO,R4
30$
20$
Rl,RS

SAVE R4
;

SET UP ITERATION COUNT
QUOTIENT ENDS UP IN R2:R3
REMAINDER ENDS UP IN R4:RS
EXPOSE NEW BIT OF NUMERATOR
DOES DENOM FIT?
BRANCH IF NOT, C=O
BRANCH IF YES
HIGH PARTS SAME, CHECK LOW
Date Conversion Routine

C-7

BHI
SUB
SBC
SUB
SEC
ROL
ROL
DECB
BGT

20$:

30$:

~rST

MOV
MOV
MOV
MOV
RTS

*** - $DIVQ

30$
Rl,RS
R4
RO,R4

BRANCH IF NOT, C=O
SUBTRACT DENOM FROM REMAINDER
INDICATE NEW QUOTIENT BIT
SHIFT IN NEW BIT OF QUOTIENT

R3
R2
(SP)
10$
(SP)+
R4,RO
RS,Rl
(SP)+,RS
(SP)+,R4
PC

CHECK LOOP COUNT
BRANCH TO LOOP
CLEAN THE STACK
MOVE REMAINDER TO RO
RESTORE R4

QUAD DIVIDE ROUTINE

THIS ROUTINE DOES A 64 BIT UNSIGNED DIVIDE OPERATION.
DIVIDE
BY ZERO IS NOT CHECKED.
ALL NUMBERS ARE STORED WITH INCREASING
SIGNIFICANCE IN INCREASING ADDRESSED BYTES.
;
;

ANDREW

GOLDSTEIN 17-NOV-76 10:47

;+
INPUTS:
HO
Rl
H.2
H3
;

= ADDRESS
= ADDRESS
= ADDRESS
= ADDRESS

OF
OF
OF
OF

DIVISOR
DIVIDEND
QUOTIENT
REMAINDER

OUTPUTS:
QUOTIENT AND REM~INDER RETURNED IN SPECIFIED ADDRESSES

$DIVQ: :

10$:

C-8

CALL
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CLR
CLR
CLR
CLR
MOV
ROL
ROL
ROL
HOL
MOV
ADD
MOV

$SA VAL
#6S.,-(SP)
R2,RS
(Rl)+, (RS)+
(R 1) +, (RS)+
(Rl)+, (RS)+
(Rl)+, (RS)+
R3,R4
(R4 )+
(R4) +
(R4) +
(R4) +
R3,R4
(R4) +
(R4) +
(R4) +
(R4) +
RO,Rl
#8. , Rl
R4,R5

Date Conversion Routine

SET UP LOOP COUNT
POINT TO QUOTIENT AREA
COPY DIVIDEND INTO QUOTIENT AREA

COPY REMAINDER POINTER
CLEAR OUT REMAINDER AREA
R4 POINTS TO END OF REMAINDER
SHIFT IN NEXT BIT OF DIVIDEND

POINT TO HIGH ORDER OF DIVISOR
AND OF REMAINDER AREA

20$:

30 $:

"-"''

CMP
BNE
CMP
BNE
CMP
BNE
CMP
SHI
MOV
MOV
SUB
SBC
SBC
SBC
CMP
SUB
SBC
SBC
SUB
SBC
SUB
SEC
MOV
ROL
ROL
ROL
ROL
DEC
BNE
TST
RTS

$MULUS::
10 $:

._.,,

MOV
CLR
ROR
ROR

sec
20$:

ADD
DEC
BGT
CMP
RETURN
• END

- (R 1) , - (RS)
20$
-(Rl);-(RS)
20$
- (R 1) , - (RS)
20$
- (R 1) , - (RS)
30$
RO,Rl
R3, R4
(Rl)+, (R4)+
(R4)+
(R4) +
(R4)
-(R4),-(R4)
(Rl)+, (R4)+
(R4)
2(R4)
(Rl)+, (R4)+
(R4)
(Rl)+, (R4)+
R2,RS
(RS)+
(RS)+
(RS)+
(RS)+
(SP)
10 $
(SP)+
PC
MOV
#21,-(SP)
RO
RO
Rl
20$
2(SP),RO
@SP
10$
(SP)+, (SP)+

SEE IF DIVISOR IS GREATER THAN
CURRENT REMAINDER VALUE

BRANCH, NO SUBTRACT, C IS CLEAR
YES:
POINT TO START OF DIVISOR
AND START OF REMAINDER
SUBTRACT DIVISOR FROM REMAINDER

SET BIT TO SHIFT INTO QUOTIENT
POINT TO QUOTIENT
SHIFT NEW BIT IN FROM RIGHT
C = NEXT BIT OF DIVIDEND
COUNT ITERATIONS
AND LOOP
CLEAN THE STACK
RO,-(SP)

Date Conversion Routine

C-9

INDEX

16-bit signed integer key type, 5-36
16-bit unsigned binary key type, 5-36
32-bit signed integer key type, 5-36
32-bit unsigned binary key type, 5-36
64-bit date, 5-23
Abnormal close, unlock file if, 3-29
Access by RFA, 4-19
Access fields in user control blocks, 1-2
Access mode during record operation, 4-19
Access mode, random, 4-19
Access mode, sequential, 4-19
Add blocks to an RMS-11 file, 8-10
Address, lower, 7-1
Address, Record's File, 4-19, 4-22, 8-19, 8-23
and disk files, 8-20, 8-24
Advantage of different bucket sizes, 5-12
Allocate user control blocks, 1-2
Allocation information, 1-13
Allocation options, 5-10
Allocation quantity, 5-8
maximum, 3-4
minimum, 3-4
(See also Allocation XAB ALQ field)
(See also FAB ALQ field)
Allocation XAB
AID, 5-3t, 5-4
ALN, 5-3t, 5-6
ALQ, 5-3t, 5-8
ALQ field and current extent, 5-9
AOP, 5-3t, 5-10
BKZ, 5-3t, 5-11
BLN, 5-3t, 5-13
COD, 5-3t, 5-14
completely optional, 5-2
DEQ, 5-3t, 5-15
DEQ is zero, 3-18
internal structure of Indexed file, 5-2
LOC, 5-3t, 5-1 7
NXT, 5-3t, 5-19
placement control, 5-2
sequencing of, 5-4
VOL, 5-3t, 5-20
Allocation, contiguous, 3-28, 5-10
Index-1

Allocation, hard, 5-10
ALQ.
(See File Access Block)
ANSI magnetic tape, 3-24
Approximate match, 4-13
Area, 1-13, 5-2, 5-4.
(See also Allocation XAB)
containing index Level O, 5-31
containing index Level 1, 5-48
containing index Levels 2+, 5-41
maximum number, 5-4
maximum number in an Indexed file, 5-74
minimum number, 5-4
number in an Indexed file, 5-74
summary of keys and, in an Indexed file, 5-71
Area number
data, 5-31
index, 5-41
lowest index level, 5-48
maximum, 5-31, 5-41, 5-48
Area, fixed control, 3-32
max i mum , 3- 3 2
minim um , 3- 3 2
Argument list
address of, 1-21
contents, 1-21
RMS-11 generates, 1-21
your program supplies, 1-20
ASCII, conversion of eight-byte date to, 5-23
Assemble, 1-2
command string, 1-22
Astrophysical base date, Smithsonian, 5-23, 5-26
Asynchronous record operation, 1-22, 4-25
outstanding, 8-33
wait for, 8-33
Attribute information, 1-2
Attributes in XAB fields, store file, 8-6
Attributes of an RMS-11 file, retrieve, 8-12
Attributes, record, 3-44
Automatic file extension, 5-15
failure of, 3-18
(See also File Access Block DEQ field)
(See also Allocation XAB DEQ field)
Available for processing, existing file, 8-12
Backward, move magnetic tape file forward or, 9-6
Base date, Smithsonian astrophysical, 5-23, 5-26
BAS IC+ I 5--2 6
Beginning of a file, logical, 8-29
BID.
(See File Access Block)
Binary key type
16-bit unsigned, 5-36
32-bit unsigned, 5-36
Bit string data field
reset bits within a, 7-6
set bits within a, 7-7
Bits within a bit string data field
reset, 7-6
set, 7-7
Bits within a field with your value, compares, 7-11
Bits, least significant, 7-1
BKS.
(See File Access Block)

Index-2

B.KT.
(See Record Access Block)
BLN.
(See Record Access Block)
Block boundaries, cross, 3-45
Block fields, retrieve modify and test, 7-1
Block header formats, RMS-11 pool, 2-10
Block I/O, 9-1
cautions, 9-1
$READ, 3-23, 9-2t, 9-3
$READ and ER$EOF error code, 9-4
$READ and multiple blocks, 9-3
$READ and unit record terminators, 9-4
required procedure, 9-1
$SPACE, 9-2t, 9-6
virtual block number, 4-4
$WRITE, 3-24, 9-2t, 9-5
$WRITE and multiple blocks, 9-5
$WRITE and partial blocks, 9-5
Block number
logical, 3-48, 5-7
maximum virtual, 4-4
Root virtual, 5-59
virtual, 3-48, 5-7, 5-38
Block size, magnetic tape.
(See File Access Block BLS field)
maximum magnetic tape, 3-10
minimum magnetic tape, 3-10
recommended sizes, 3-9
Block spanning, 3-44
Block, characters in magnetic tape.
(See File Access Block)
Block, Release Core.
(See GSA routine)
Block, Request Core.
(See GSA routine)
Block, retrieve a specified virtual, 9-3
Block, user control.
(See user control block)
Block, write a specified virtual, 9-5
Blocks to an RMS-11 file, add, 8-10
BLS.
(See File Access Block)
Bqundaries, cross block, 3-45
BPA.
(See File Access Block)
BPT instruction, A-18
Bucket fill number
data, 5-34
index, 5-44
Bucket size, 4-17, 5-9, 5-11, 5-16, 5-49
advantage of different, 5-12
and default extension quantity, 3-17, 5-15
and initial allocation quantity, 3-4, 5-8
data, 5-33
index, 5-43
maximum, 3-6, 5-11
min i mum , 3- 6 , 5-11
valid for Relative and Indexed files only, 3-6
(See also FAB BKS field)
(See also Allocation XAB BKZ field)
Bucket, calculating number of bytes in a, 5-34, 5-44
Bucket, first data, 5-38

Index-3

Buffer
allocation, 8-16
I/O buffer size, 1-6
record processing use, 1-6
requirements, 1-7
RMS-11 control of, 1-6
user control of, 1-6
Buffer Descriptor Blocks, 2-lt
calculating requirements, 2-2
Buff e r po o 1 •
(See cent r a 1 buff e r po o 1 )
Buffer pool, private
address, 3-11
address on word boundary, 3-11
and central buffer pool, 3-12
calculating size of, 3-13
your program's use of, 3-12
Buffer size, key, 4-13
Buffer size, user, 4-34
and Locate Mode, 4-32
maximum, 4-34
Buffer space.
(See central buffer pool)
optimize, 4-25
release, 8-18
Buffer
I/O, 1-6
private I/O, 1-6.
(See also private buffer pool)
record header, 4-23
user, 8-23
Buffers, writes all modified I/O, 8-21
Bypass RMS-11 record processing, 9-1
Bytes in a bucket, calculating number of, 5-34, 5-44
Calculating number of bytes in a bucket, 5-34, 5-44
Call error, fatal user, A-18
Calling sequence, 1-20
Carriage return control, 3-44
Central buffer pool
allocated at assembly time, 2-1
multiple allocation in modules, 2-1
requirements, 1-2
Task Builder, 2-1
Chain of XABs, 5-19, 5-25, 5-55, 5-67, 5-76
Changability, 5-39
Change during update, key, 5-39
Channel, logical, 3-35
and Record Access Streams, 3-36
maximum logical, 3-35
minimum logical, 3-35
once assigned, 3-36
Character, null key, 5-53
Characteristics, key, 5-39
and Primary Keys, 5-40
null key, 5-39
valid combination of, 5-40
Characters in magnetic tape block.
(See File Access Block)
$CLOSE.
(See macro)
Close
an open RMS-11 file, 8-2
rewind magnetic tape file on, 3-29
unlock file if abnormal, 3-29

Index-4

Cluster number, device, 5-7
Clustersize, 3-50
file extension and, 3-18, 5-16
maximum, 3-50
minim um , 3- 5 0
Code, protection, 5-64
programmer number, 5-68
project number, 5-69
Code, status, 3-54
Codes, error completion, A-1
Codes, success completion, A-1
$COMPARE.
(See macro)
Compare field with your value, 7-2
Compares bits within a field with your value, 7-11
Completion codes, error, A-1
Completion codes, success, A-1
Completion routines, 1-19
register usage during, 1-20
return control from, 1-20
RMS-11 operations within, 1-20
Conditions, inconsistent internal, A-18
Conditions, severe error, A-2
$CONNECT.
(See macro)
Contents of a field to your location, copy the, 7-4
Contents of your location to a field, copy the, 7-9
Context, 1-22
Context field, user.
(See File Access Block CTX field)
Context, set, 8-29
at end-of-file during connect operation, 4-25
Contiguous allocation, 3-28, 5-10
Continue processing on the next tape volume, 8-25
Control block, user.
(See user control block)
Control structures, internal, 1-6
Control, carriage return, 3-44
Control, FORTRAN forms, 3-44
Control, placement, 5-6
RSTS/E restriction, 5-7
Conversion of eight-byte date to ASCII, 5-23, 5-26
Copy the contents of a field to your location, 7-4
Copy the contents of your location to a field, 7-9
Core Block, Release.
(See GSA routine)
Core Block, Request.
(See GSA routine)
Crash routine, fatal error, A-2
and general registers, A-18
ER$BUG error code, A-19
ER$FAB error code, A-18
ER$MAP error code, A-19
ER$RAB error code, A-18
$CREATE.
(See macro)
Create
an RMS-11 file, 8-4
an RMS-11 task, 1-22
Creation date and time information, file, 5-21
Creation date, file, 5-23
accuracy of, 5-23
Criterion, match, 4-13
Cross block boundaries, 3-45
CTX.
(See File Access Block)
Current extent and Allocation XAB ALQ field, 5-9

Index-5

Current record, 1-22
Cylinder number, 5-7
Data area number, 5-31
Data bucket fill number, 5-34
Data bucket size, 5-33
Data bucket, first, 5-38
Data field, reset bits within a bit string, 7-6
Data field, set bits within a bit string, 7-7
Data type, key, 5-36
and prologue version number, 5-77
reassembly requirement, 5-36
Date and time information
file creation, 5-21
file revision, 5-21
Date-time information, 1-13
Date to ASCII, conversion of eight-byte, 5-23, 5-26
Date XAB
BLN, 5-2lt, 5-22
CDT , 5- 2 1 t , 5- 2 3
COD, 5-2lt, 5-24
NXT, 5-2lt, 5-25
R DT , 5- 21 t , 5- 2 6
RVN, 5-2lt, 5-27
Date, 64-bit, 5-23, 5-26
Date, file creation, 5-23
accuracy of, 5-23
Date, file revision, 5-26
accuracy of, 5-26
Date, Smithsonian astrophysical base, 5-23, 5-26
Decimal radix, 1-2, 1-10
Declare RMS-11 facilities, 1-2
Default extension quantity, 3-17, 5-15
for file, 3-18
maximum, 3-18, 5-15
minimum, 3-17, 5-15
when Allocation XAB DEQ fields are zero, 3-18
(See File Access Block DEQ field)
(See Allocation XAB DEQ field)
Default name string, 3-20
and logical names, 3-21
contents, 3-20
maximum, 3-22
no ta t i on , 3- 2 1
size, 3--22
Defaults, system, 1-16
Deferred Write, 3-29
$DELETE.
(See macro)
Delete
an existing record, 8-17
an RMS-11 file, 8-8
(See also $ERASE)
fast, 4--25
file marked for, 3-29
records from a Sequential file, 8-30
temporary file marked for, 3-29
DEQ.
(See Fi 1 e Access Block)
DEV.
(See File Access Block)
Device characteristics.
(See File Access Block DEV field)
Device cluster number, 5-7

Index-6

~A.

DE!V ice ID, 1-16
do not manipulate, 6-2
used with file ID, 6-2
Device, unit record, 3-45
Different bucket sizes, advantage of, 5-12
Directives, .MCALL, 1-2
Directory entry(s), remove RMS-11 file's, 8-8
$DISCONNECT.
(See macro)
Disconnect all Record Access Streams, 8-2
Disk file size~
(See Allocation XAB ALQ field)
Disk Sequential files and multiblock count, 4-15
$DIS PLAY.
(See macro)
DNA.
(See File Access Block)
Duplicatability, 5-39
Duplicate key values, 5-39
Eight-byte date, 5-23, 5-26
conversion to ASCII, 5-23, 5-26
End of magnetic tape file, position to, 3-29
Environment, processing, 1-2
EH$cod, A·-1
EH$ISI error code after close operation, 8-3
ER$WER error code on close operation, 8-3
$ERASE.
(See macro)
Error completion codes, A-1
Error conditions, severe, A-2
Error crash routine, fatal, A-2
and general registers, A-18
ER$BUG error code, A-19
ER$FAB error code, A-18
ER$MAP error code, A-19
ER$RAB error code, A-18
Error on relative files, record-exists, 4-26
Error, fatal user call, A-18
Establish a Record Access Stream, 8-16
• EVEN , 1-8 , 1-11 , 1-1 3 , 1-1 7
Exact match, 4-13
Existing file
available for processing, 8-12
s u pe rs e de , 3- 2 9
Existing record in an RMS-11 file, replace an, 8-31
Existing record, delete an, 8-17
Expanded file name string
address, 6-3
length from RMS-11, 6-4
size from your program, 6-5
Explanation of locked file, 3-30
$EXTEND.
(See macro)
Extended Attribute Block, 1-1, 1-13, 5-1
allocation macros, 1-3
Allocation XAB, 1-13, 5-2
and Indexed files, 3-57
and the FAB, 3-56
ca u t i on s , 1--1 4
chain of, 3-56
Date XAB, 1-13, 5-21
extension of FAB, 1-13
field offset macros, 1-3, 5-1
initialization, 1-14
initialization macros, 1-3, 5-1

Index-7

Extended Attribute Block (continued}
Key XAB, 1-13, 5-28
linking and ordering, 1-14
ordering by type of XAB, 1-14
ordering withing XAB type, 1-16
Protection XAB, 1-13, 5-64
required during creation, 1-13
required during display, 1-13
Summary XAB, 1-13, 5-71
XB $ALL, 1-13
XB $DAT, 1-13
XB$KEY, 1-13
XB$PRO, 1-13
XB$SUM, 1-13
Extension and clustersize on RSTS/E, file, 3-18, 5-16
Extension quantity, default.
(See default extension quantity}
Extension, automatic file, 5-15
failure of, 3-18
Extent and Allocation XAB ALQ field, current, 5-9
F $ f nm •
( Se e mac r o }
FAB.
(See Record Access Block}
FAC.
(See File Access Block}
Facilities, declare RMS-11, 1-2
Failure of automatic file extension, 3-18
Fast delete, 4-25
Fatal error crash routine, A-2, A-18
and general registers, A-18
ER$BUG error code, A-19
ER$FAB error code, A-18
ER$MAP error code, A-19
ER$RAB error code, A-18
Fatal user call error, A-18, A-18
FCS, 5-26
$FETCH.
(See macro}
Field Access Macros
#0 and $COMPARE, 7-2
$COMPARE, 7-lt, 7-2
$FETCH, 7-lt, 7-4
$FETCH and KEY XAB SIZ/POS field, 7-4
$OFF, 7-lt, 7-6
$SET, 7-lt, 7-7
$STORE, 7-lt, 7-9
$STORE and KEY XAB SIZ/POS field, 7-9
$TESTBITS, 7-lt, 7-11
Field
com pa re with your value, 7-2
compares bits within to your value, 7-11
copy the contents of your location to a, 7-9
copy the contents to your location, 7-4
key, 5-28
set bits within a bit string data, 7-7
reset bits within a bit string data, 7-6
user context.
(See File Access Block CTX field}
Fields
access at run time, 1-18
access macros, 1-18.
(See also Field Access Macros}
in use( control blocks, access, 1-2
modify contents, 1-18, 7-6, 7-7, 7-9
proper values before operation, 1-8, 1-11, 1-13

Index-8

''-'

Fields (continued)
retrieve contents, 1-18, 7-4
retrieve, modify, and test block, 7-1
RMS-11 changes default during operations, 1-19
store file attributes in XAB, 8-6
test contents, 1-18, 7-11
user control block.
(See user control block)
File Access Block, 1-1, 1-8, 3-1
allocation, 1-8
allocation macros, 1-3
ALQ, l-9t, 3-2t, 3-3
associated with a RAB, 8-16
BID, 1-9t, 3-5
BKS, 1-9t, 3-2t, 3-6
BKS vs. XAB BKZ, 5-9
BLN, 1-9t, 3-2t, 3-8
BLS, 1-9t, 3-2t, 3-9
BPA, 1-9t, 3-2t, 3-11
BPS, 3-2t, 3-13
cautions, 1-10
CTX, l-9t, 3-2t, 3-16
DEQ, l-9t, 3-2t, 3-17
DEQ vs. XAB DEQ, 3-18, 5-16
DEV, 1-9t, 3-2t, 3-19
DNA, 1-9t, 1-16, 3-2t, 3-20
DNS, 1-16, 3-2t, 3-22
FAC, 1-9t, 3-2t, 3-23
field offset macros, 1-3, 3-1
FNA, 1-9t, 1-16, 3-2t, 3-25
FNS, l-9t, 1-16, 3-2t, 3-27
FOP, l-9t, 3-2t, 3-28
FSZ, 1-9t, 3-2t, 3-32
IF!, 1-9t, 3-2t, 3-34
initialization, 1-9
initialization macros, 1-3, 3-1
KSZ, 3-2t
LCH, 1-9t, 3-2t, 3-35
MRN, 1-9t, 3-2t, 3-37
MRS, 1-9t, 3-2t, 3-39
NAM, l-9t, 3-2t, 3-41
ORG, 1-9t, 3-2t, 3-43
RAT, l-9t, 3-2t, 3-44
representing more than one file, 1-8, 4-8
RFM, l-9t, 3-2t, 3-46
RTV, l-9t, 3-2t, 3-48, 3-50
SHR, l-9t, 3-2t, 3-52
STS, l-9t, 3-2t, 3-54
STV, l-9t, 3-2t, 3-55
XAB, l-9t, 3-2t, 3-56
File Address, Record's, 4-19, 4-22, 8-19, 8-23
and disk files, 8-20, 8-24
File attributes in XAB fields, store, 8-6
File available for processing, existing, 8-12
File contents unavailable, 8-2
File creation date, 5-23

Index-9

accuracy of, 5-23
File creation date and time information, 5-21
File default extension quantity, 3-18
File extension
and clustersize on RSTS/E, 3-18, 5-16
automatic, 5-15
failure of automatic, 3-18
File forward or backward, move magnetic tape, 9-6
File ID, 1-16, 3-29
do not manipulate, 6-6
used with device ID, 6-6
File marked for delete, 3-29
File marked for delete, temporary, 3-29
File name string
address,, 3-25
conform to system standards, 3-26
notation, 3-25
parsing under RSTS/E, 3-26
size, 3-2 7
use in file specification, 3-25
File name string size, maximum, 3-27
File name string, expanded
address, 6-3
length from RMS-11, 6-4
size from your program, 6-5
File on close, rewind magnetic tape, 3-29
File on open, rewind magnetic tape, 3-29
File opened for write operations by RMS-11, 5-27
File operation, 1-2, 1-19
calling sequence, 1-20
FAB associated with the macro, 8-1
RMS-11 verifies FAB before, 3-5, 3-8
RMS-11 verifies XAB before, 5-13, 5-14, 5-22, 5-24, 5-29, 5-30,
5-65, 5-66, 5-72, 5-73
valid, 3-23
File Operation Macros, 1-21, 8-1
$CLOSE, l-22t, 8-lt, 8-2
$CLOSE and ER$ISI error code, B-3
$CLOSE and ER$WER error code, 8-3
$CLOSE and I/O request, 8-2
$CLOSE and NAM Block, 8-3
$CLOSE buffer requirements, 8-2·
$CREATE, l-22t, 8-lt, 8-4
$CREATE and Allocation XABs, 8-4
$CREATE and NAM Block, 8-4
$CREATE buffer requirements, 8-4
$DISPLAY, l-22t, 8-lt, 8-6
$DISPLAY buffer requirements, 8-6
$ERASE, l-22t, 8-lt, 8-8
$ERASE buffer requirements, 8-8
$ERASE by file ID, 8-8
$ERASE while file is open, 8-9
$EXTEND, l-22t, 8-lt, 8-10
$EXTEND and Allocation XABs, 8-10
$EXTEND buffer requirements, 8-10
$EXTEND restrictions, 8-11
$OPEN, l-22t, 8-lt, 8-12
$OPEN and Allocation XABs, 8-12
$OPEN before $EXTEND, 8-14
$OPEN buffer requirements, 8-12
$OPEN by file ID, 8-12
Index-10

File organization, 3-43
File processing options, 3-28
File revision date, 5-26
accuracy of, 5-26
File revision date and time information, 5-21
File revision number, 5-27
File sharing, 1-22, 3-52
allowing readers, 3-52
allowing writers, 3-52
and Sequential files, 3-52
File size, disk.
(See File Access Block ALQ field)
File specification, 3-25
full, 1--16, 6-3, 6-4
maximum full, 6-5
File,
add blocks to an RMS-11, 8-10
close an open RMS-11, 8-2
create an RMS-11, 8-4
delete an RMS-11, 8-8.
(See also $ERASE)
delete records from a Sequential, 8-30
explanation of locked, 3-30
locate a specified record in a, 8-19
logical beginning of a, 8-29
operation related to an entire, 8-1
position to end of magnetic tape, 3-29
replace an existing record in an RMS-11, 8-31
retrieve attributes of an RMS-11, 8-12
supersede existing, 3-29
temporary, 3-2 9
write a new record into an RMS-11, 8-27
Files and multiblock count, disk sequential, 4-15
Files, multivolume magnetic tape, 8-25
Files, record-exists error on relative, 4-26
Fill number
data bucket, 5-34
honor, 4-26
index bucket, 5-44
maximum, 5-34, 5-44
minimum, 5-34, 5-44
$1~ IND.
(See macro)
First data bucket, 5-38
Fixed control area, 3-32
maximum, 3-32
minim um , 3- 3 2
Fixed-length record format, 3-46
$PLUSH.
(See macro)
FNA.
(See File Access Block)
FNS.
(See File Access Block)
FOP.
(See File Access Block)
Format
fixed-length record, 3-46
re co rd, 3-4 6
stream record, 3-46
undefined record, 3-46
variable-length record, 3-46
VFC record, 3-46
Formats, RMS-11 pool block header, 2-10
Forms control, FORTRAN, 3-44
FORTRAN forms control, 3-44

Index-11

Forward or backward, move magnetic tape file, 9-6
Fragmentation in central buffer pool, 1-6
FSZ.
(See File Access Block)
Full file specification, 1-16, 6-3, 6-4
maximum, 6-5
Generic device characteristics.
(See File Access Block DEV field)
$GET.
(See macro)
Get Space Address (GSA), 1-7
Get Space Routine, 2-8.
(See also GSA routine)
$GETGSA.
(See macro)
Global
labels, 1-10
symbols, 1-10
$GNCAL.
(See macro)
Greater-than match, 4-26
Greater-than-or-equal match, 4-26
GSA, 1-7.
(See also Get Space Address)
GSA routine
and general registers, 2-10
controls all buffer space, 2-8
expected outputs, 2-8
failure, 2-12
interface to, 2-9
Release Core Block, 2-12
Request Core Block, 2-12
retrieving address at run time, 2-9
$RLCB, 2-12
RMS-11 inputs to, 2-9
RMS-11 Pool Block Header Formats, 2-10
RMS-11 release of space, 2-10
RMS-11 request for space, 2-10
RMS-11 trusts, 2-8
RMS-11 use, 2-8
$RQCB, 2-12
serves all files, 2-8
specifying address at assembly time, 2-8
specifying address at run time, 2-9
symmetrical processing, 2-12
word boundary, 2-8
GSA$.
(See macro)
Hard allocation, 5-10
Header buffer, record, 4-23
Header formats, RMS-11 pool block, 2-10
Honor fill numbers, 4-26
Hundreds of nanoseconds since Nov 17, 1858, 5-23, 5-26
I/O buffer, 1-6
calculating requirements, 2-7
private, 1-6.
(See also private buffer pool)
writes all modified, 8-21
ID, device
do not manipulate,_ 6-2
used with file ID, 6-2
ID, file
do not manipulate, 6-6
used with device ID, 6-6
IFAB.
(See Internal File Access Block)

Index-12

,-~,

,.....,

!FI.
(See File Access Block)
Inconsistent internal conditions, A-18, A-19
Index
area number, 5-41
bucket fill number, 5-44
bucket size, 5-43
level area number, lowest, 5-48
Index of reference, 4-12
Indexed file
maximum number of areas in, 5-74
maximum number of_ keys in, 5-75
number of areas in, 5-74
number of keys in, 5-75
$INIT.
(See macro)
Initialize user control blocks, 1-2
$INITIF.
(See macro)
Integer key type
16-bit signed, 5-36
32-bit signed, 5-36
Internal conditions, inconsistent, A-18
Internal control structures, 1-6
Internal File Access Block, 1-8, 2-3, 3-34
Internal Record Access Block, 1-11, 2-4, 2-5, 4-9
!RAB.
(See Internal Record Access Block)
I SI.
( SeE~ Re co rd Access Block)
KBF.
{See Record Access Block)
KE~Y

and areas in an Indexed file, summary of, 5-71
maximum number in an Indexed file, 5-75
number in an Indexed file, 5-75
Key buffer size, 4-13
Key change during update, 5-39
Key character, null, 5-53
Key characteristics, 5-39
_and Primary Keys, 5-40
null, 5--39
valid combination of, 5-40
Key data type, 5-36
and prologue version number, 5-77
reassembly requirement, 5-36
Key Descriptors, 2-6
KE~Y field., 5-28
Key information, 1-13
KE~Y length, 5-28
KE~Y name, 5-46
Ieng th, 5-46
Key of reference, 4-12, 5-58
maximum" 4-12
minimum" 4-12
Key position, 5-28
KE~Y segments
maximum number of, 5-52
minimum number of, 5-52
multiple, 5-56, 5-61
n um be r o f , 5- 5 2
position of, 5-56
KE~Y sizE~, 5-60
maximum, 5-60
nonstring, 4-14
total, 5-63
Index-13

Key type , 5- 2 8
16-bit signed integer, 5-36
16-bit unsigned binary, 5-36
32-bit signed integer, 5-36
32-bit unsigned binary, 5-36
string, 5-36
Key value during random operations, 4-10
Key value, null, 5-39, 5-53
Key XAB
BLN, 5-28t, 5-29
COD, 5-28t, 5-30
DAN, 5-28t, 5-31
DBS, 5-28t, 5-33
DFL, 5-28t, 5-34
DTP, 5-28t, 5-36
DVB , 5- 2 8 t , 5- 3 8
FLG, 5-28t, 5-39
FLG field contains XB$NUL, 5-53
IAN, 5-28t, 5-41
IBS, 5-28t, 5-43
IFL, 5-28t, 5-44
KNM, 5-28t, 5-46
LAN, 5-28t, 5-48
LVL, 5-28t, 5-50
MRL, 5-28t, 5-51
NSG, 5-28t, 5-52
NUL, 5-28t, 5-53
NXT, 5-28t, 5-55
POS, 5-28t, 5-56
REF, 5-28t, 5-58
required for Indexed file, 5-28
RVB, 5-28t, 5-59
SIZ, 5-28t, 5-60
TKS, 5-28t, 5-63
Keys
key characteristic and Primary, 5-40
maximum number of, 5-58
random record operations with string, 4-14
segmented, 5-52, 5-56
segmented and ascending byte positions, 5-57
size of segmented, 5-60
KRF.
(See Record Access Block)
KSZ.
(See Record Access Block)
Label, 1-8, 1-10, 1-11, 1-13, 1-1 7, 2-8
global, 1-10
LCH.
(See File Access Block)
Least significant bits, 7-1
Length, key, 5-28
Length, minimum record, 5-51
and Alternate Keys, 5-51
and the Primary Key, 5-51
Level number, root, 5-50
Locate a specified record in a file, 8-19
Locked file, explanation of, 3-30
Logical beginning of a file, 8-29
Logical block number, 3-48, 5-7

Index-14

"'-"'

Logical channel, 3-35
and Record Access Streams, 3-36
maximumjT 3-35
minimum,, 3-35
once assigned, 3-36
Logical names, 3-21
Logical unit.
(See logical channel)
Lowest index level area number, 5-48
Macro
as arguments in .MCALL directive, 1-3
buffer pool declaration, 1-3
$CLOSE, 1-8 t, 8-2
$COMPARE, 1-18, 7-2
$CONNECT, 1-lOt, 8-16
$CREATE, l-8t, 8-4
$DELETE, 1-lOt, 8-17
$DISCONNECT, 1-lOt, 8-18
$DISPLAY, l-8t, 8-6
$ERASE, l-8t, 8-8
$EXTEND, l-8t, 8-10
F$ALQ,, 3-4
F$BKS, 3-7
F$BLS, 3-10
F$BPS, 3-14
F$CTX, 3-16
F$DEQ, 3-18
F$DNA, 3-21
F$DNS, 3-22
F$FAC, 3-24
F$FNA, 3-26
F$fnm, 1-1 O
F$FNS, 3-27
F$FOP, 3-~0
F$FSZ, 3-32
F$LCH, 3-35
F$MRN, 3-38
F$MRS, 3-40
F$NAM, 3-42
F$0RG, 3-43
F$RAT, 3-45
F$RFM, 3-47
F$RTV, 3-49, 3-51
F$SHR, 3-53
F$XAB, 3-56
FAB$B, 1-3, 1-8
FAB$E, 1-8
FB$BLK, 3-44
FB$CCL, 3-19
FB$CR, 3-44
FB$CTG, 3-28
FB$DEL, 3-23
FB$DFW, 3-29
FB$DLK, 3-29
FB$FID, 3-29
FB$FIX, 3-46
FB$FTN, 3-44
FB$GET, 3-23
FB$IDX, 3-43
FB$MDI, 3-19

Index-15

Macro (continued)
FB$MKD, 3-29
F B $NE F , 3-2 9
FB$POS, 3-29
FB$PUT, 3-23
FB$REA, 3-23, 9-1
FB$REC, 3-19
FB$REL, 3-43
FB$RWC, 3-29
FB$RWO, 3-29
FB$SDI, 3-19
FB$SEQ, 3-43
FB$SQD, 3-19
FB$STM, 3-46
FB$SUP, 3-29
FB$TMD, 3-29
FB$TMP, 3-30
FB$TRM, 3-19
FB$TRN, 3-23
FB$UDF, 3-46
FB$UPD, 3-24
FB$VAR, 3-46
FB$VFC, 3-46
FB$WRI, 3-52, 9-1
FB$WRT, 3-24
$FETCH, 1-18, 7-4
field access, 1-3, 3-1, 4-1, 5-1, 6-1
file operation, 1-21
$FIND, 1-lOt, 8-19
$FLUSH, 1-lOt, 8-21
$FREE, 8-22
$GET, 1-lOt, 8-23
$GETGSA, 2-9
$GNCAL, 1-3
GSA$, 2-8
$INIT, 1-2, 1-3
$INITIF, 1-2, 1-3
N$ESA, 6-3
N$ESS, 6-5
N$fnm, 1-1 7
NAM$B, 1-3, 1-1 7
NAM$E, 1-17
$NXTVOL, 1-1 Ot, 8-25
$OFF, 1-18, 7-6
$OPEN, l-8t, 8-12
ORG$, 1-3
P$BDB, l-7t, 2-lt, 2-2
P$BUF, l-7t, 2-lt, 2-7
P$FAB, l-7t, 2-lt, 2-3
P$IDX, l-7t, 2-lt, 2-6
P$RAB, l-7t, 2-lt, 2-4
P$RABX, l-7t, 2-lt, 2-5
POOL$B, 1-3, l-7t, 2-lt
POOL$E, 1-7t, 2-lt
processing, 1-1
$PUT, 1-lOt, 8-27
R$BKT, 4-4
R$CTX, 4-6
R$FAB, 4-7

Index-16

Macro (continu~d)
R$KBF, 4-11
R$KRF, 4-12
R$KSZ, 4-14
R$MBC, 4-15
R$MBF, 4-17
R$RAC, 4-19
R$RBF, 4-21
R$RFA, 4-22
R$RHB, 4-24
R$RSZ, 4-29
R$UBF, 4-B3
R$USZ, 4-34
RAB$B, 1-3, 1-11
RAB$E, 1-11
RB$ASY, 4-25
RB$EOF, 4-25
RB$FDL, 4-25
RB$KEY, 4-19
RB$KGE, 4-26
RB$KGT, 4-26
RB$LOA, 4-26
RB$MAS, 4-26
RB$RFA, 4-19
RB$SEQ, 4-19
RB$UIF, 4-26
record operation, 1-22
$REWIND, 1-lOt, 8-29
$SET, 1-18, 7-7
$SETGSA, 2-9
$STORE, 1-18, 7-9
$TESTBITS, 1-18, 7-11
$TRUNCATE, 1-lOt, 8-30
$UPDATE, 1-lOt, 8-31
$WAIT, 8-33
X$AID, 5-4
X$ALN, 5-7
X$ALQ, 5-9
X$AOP, 5-10
X$BKZ, 5-11
X$DAN, 5-312
X$DEQ, 5-16
X$DFL, 5-35
X$DTP, 5-37
X$FLG, 5-40
X$fnm, 1-14
X$IAN, 5-42
X$IFL, 5-45
X$KNM, 5-47
X$LAN, 5-49
X$LOC, 5-18
X$NUL, 5-53
X$NXT, 5-19u 5-25, 5-55, 5-67, 5-76
X$POS, 5-57
X$PRG, 5-68
X$PRJ, 5-69
X$PRO, 5-71
X$REF, 5-58
X$SIZ, 5-61

Index-17

Macro (continued)
XAB$B, 1-3, 1-13
XAB$E, 1-13
XB$ALL, 1-13
XB$BN2, 5-36
XB$BN4, 5-36
XB $CHG, 5-3 9
XB $CTG, 5-10
XB$CYL, 5-7
XB$DAT, 1-13
XB$DUP, 5-39
XB$HRD, 5-10
XB$IN2, 5-36
XB$IN4, 5-36
XB$KEY, 1-13
XB$LBN, 5-7
XB $NUL, 5-3 9
XB$PRO, 1-13
XB$STG, 5-36
XB$SUM, 1-13
XB$VBN, 5-7
Macros
file operation, 1-21
record operation, 1-22
Magnetic tape block size.
(See File Access Block BLS field)
maximum, 3-10
minimum, 3-10
Magnetic tape block, characters in.
(See File Access Block BLS field)
Magnetic tape file
move forward or backward, 9-6
multivolume, 8-25
position to end of, 3-29
rewind on close, 3-29
rewind on open, 3-29
Magnetic tape, ANSI, 3-24
Marked for delete
permanent file, 3-29
temporary file, 3-29
Mass Insert, 4-26
Match criterion, 4-13
approximate, 4-13
exact, 4-13
greater-than, 4-26
greater-than-or-equal, 4-26
Maximum
allocation quantity, 3-4
area number, 5-31, 5-41, 5-48
bucket size, 3-6, 5-11
clustersize, 3-50
default extension quantity, 3-18, 5-15
default name string, 3-22
file name string size, 3-27
fill number, 5-34, 5-44
fixed control area, 3-32
full file specification, 6-5
key of reference, 4-12
key size, 5-60
logical channel, 3-35
magnetic tape block size, 3-10

Index-18

,191

;

Maximum (continued)
multiblock count, 4-15
multibuffer value, 4-17
number of areas, 5-4
number of areas in an Indexed file, 5-74
number of key segments, 5-52
number of keys, 5-58
number of keys in an Indexed file, 5-75
programmer number, 5-68
project number, 5-69
Record Number
Record Number, minimum, 3-37
Record Size, 3-39, 4-28
Record Size and fixed-length records, 3-40
Record Size and Relative files, 3-40
user buffer size, 4-34
virtual block number, 4-4
window size, 3-48
MBC.
(See Record Access Block)
MBF.
(See Re co rd Access Block)
.MCALL directives, 1-2
general form ir 1-3
minimizing number of directives, 1-3
minimum set of arguments, l-3t
omitting macro names, 1-4
use across modules, 1-4
Minimum
allocation quantity, 3-4
bucket size, 3-6, 5-11
clustersize, 3-50
default extension quantity, 3-17, 5-15
fill number, 5-34, 5-44
fixed control area, 3-32
key of reference, 4-12
logical channel, 3-35
magnetic tape block size, 3-10
Maximum Record Number, 3-37
number of areas, 5-4
number of key segments, 5-52
record length, 5-51
record length and Alternate Keys, 5-51
record length and the Primary Key, 5-51
record size, 3-39
window size, 3-48
Mode during record operation, access, 4-19
Mode
Random Access, 4-19
Record Transfer, 4-20
Sequential Access, 4-19
Modified I/O buffers, writes all, 8-21
Module, Root, 1-5
Move magnetic tape file forward or backward, 9-6
Moved by record operation, record, 4-20
MRN.
(See File Access Block)
MRS.
(See File Access Block)
Multiblock count, 4-15
and I/O buffer size, 4-16
disk sequential files and, 4-15
maximum, 4-15

Index-19

Multibuffer, 4-17
and I/O buffer size, 4-18
and Indexed files, 4-17
and minimum buffer requirements, 4-18
and Relative files, 4-17
maximum value, 4-17
waste of address space, 4-18
Multiple key segments, 5-56, 5-61
Multivolume magnetic tape files, 8-25
N$fnm.
(See macro)
NAM.
(See File Access Block)
NAM Block, 1-1, 1-16, 6-1
allocation, 1-17
allocation macros, 1-3
and the FAB, 3-41
cautions, 1-1 7
DVI, 1-18, 6-lt, 6-2
ESA, 1-18, 6-lt, 6-3
ESA and open/erase by file ID, 6-3
ESL, 1-18, 6-lt, 6-4
ESS, 1-18, 6-lt, 6-5
FID, 1-18, 6-lt, 6-6
field offset macros, 1-3, 6-1
indicate existence of, 1-16
initialization, 1-17
initialization macros, 1-3, 6-1
Name Block.
(See NAM Block)
Name string, default, 3-20
and logical names, 3-21
contents, 3-20
maximum size, 3-22
notation, 3-21
size, 3-2 2
Name string, expanded file
address, 6-3
length from RMS-11, 6-4
size from your program, 6-5
Name string, file
address,, 3-25
conform to system standards, 3-26
maximum size, 3-27
notation, 3-25
parsing under RSTS/E, 3-26
size, 3-27
use in file specification, 3-25
Name, key, 5-46
length, 5-46
Names, logical, 3-21
Nanoseconds since Nov 17, 1858, hundreds of, 5-23, 5-26
New record into an RMS-11 file, write a, 8-27
Next record, 1-22
Next tape volume, continue processing on the, 8-25
Nonstring key size, 4-14
Nov 17, 1858, hundreds of nanoseconds since, 5-23, 5-26
Null key character, 5-53
Null key characteristic, 5-39
Null key value, 5-39, 5-53

Index-20

Number of
areas in an Indexed file, 5-74
bytes in a bucket, calculating, 5-34, 5-44
key segments, 5-52
key segments, maximum, 5-52
key segments, minimum, 5-52
keys in an Indexed file, 5-75
keys, maximum, 5-58
Number
cylinder, 5-7
data bucket fill, 5-34
device cluster, 5-7
file revision, 5-27
honor fill, 4-26
index bucket fill, 5-44
Logical Block, 3-48, 5-7
maximum fill, 5-34, 5-44
maximum programmer, 5-68
maximum project, 5-69
Maximum Record
maximum virtual block, 4-4
minimum fill, 5-34, 5-44
minimum Maximum Record, 3-37
programmer, 5-68
project, 5-69
prologue version, 5-77
prologue version, and key data types, 5-77
relative record, 4-4, 4-10, 4-13
relative volume, 5-20
root level, 5-50
Root Virtual Block, 5-59
Virtual Block, 3-48, 5-7, 5-38
Numeric value, 1-10
$NXTVOL.
(See macro)
Octal radix, 1-18, 7-1
$OFF.
(See macro)
$OPEN.
(See macro)
Open, rewind magnetic tape file on, 3-29
Opened for write operations by RMS-11, file, 5-27
Operating systems, PDP-11, 1-1
Operation macros
file, 1-21
record, 1-22
Operation
access mode during record, 4-19
asynchronous record, 1-22, 4-25
calling sequence, 1-20
file, 1-2, 1-19
key value during random, 4-10
optional functions during record, 4-25
random record, with string keys, 4-14
record, 1-2,, 1-19
record moved by record, 4-20
related to an entire file, 8-1
set proper field values before, 1-19
suspend program, 8-33
synchronous record, 1-22
valid file, 3-23

Index-21

Optimize buffer space, 4-25
Optional functions during record operations, 4-25
Options
allocation, 5-10
file processing, 3-28
ORG.
{See File Access Block)
ORG$, 1-3, 1-5.
{See also macro)
CRE, 1-5
DEL, 1-5
FIN, 1-5
for each file organization, 1-5
general form, 1-5
GET, 1-5
IDX, 1-5
PUT, 1-5
REL, 1-5
SEQ, 1-5
UPD, 1-5
use, 1-5
Organization, file, 3-43
Outstanding asynchronous record operation, 8-33
Overlays, 1-22
PDP-11 operating systems, 1-1
Performance Report, Software, A-19
Placement control, 5-6
location, 5-17
RSTS/E restriction, 5-7
Pointers, retrieval, 3-48
Pool block header formats, RMS-11, 2-10
Pool, central buffer.
{See central buffer pool)
Pool, private buffer {See private buffer pool)
Position of key segments, 5-56 ·
Position to end of magnetic tape file, 3-29
Position, key, 5-28
Primary Keys, key characteristic and, 5-40
Printer, 3-45
Private buffer pool
address, 3-11
address on word boundary, 3-11
and central buffer pool, 3-12
calculating size of, 3-13
your program's use of, 3-12
Private I/O buffer, 1-6.
{See also private buffer pool)
Processing
bypass RMS-11 record, 9-1
continue on the next tape volume, 8-25
environment, 1-2
existing file available for, 8-12
options, file, 3-28
Program operation, suspend, 8-33
Programmer number, 5-68
maximum, 5-68
Project number, 5-69
maximum, 5-69
Prologue version number, 5-77
and key data types, 5-77
Protection code, 5-64
programmer number, 5-68
project number, 5-69
values, 5-70
Protection information, 1-13
Index-22

..•.

Protection XAB
BLN, 5-64t, 5-65
COD, 5-64t, 5-66
NXT, 5-64t, 5-67
PRG, 5-64t, 5-68
PRJ, 5-64t, 5-69
PRO, 5-64t, 5-70
$PUT.
(See macro)
Put operation, automatic file extension during, 3-17
Quantity
allocation.
(See allocation quantity)
default extension.
(See default extension quantity)
file default extension, 3-18
maximum allocation, 3-4
maximum default extension, 3-18, 5-15
minimum allocation, 3-4
minimum default extension, 3-17, 5-15
R$fnm.
(See macro)
RAB.
(See Record Access Block)
RAC.
(See Record Access Block)
Radix
decimal, 1-2, 1-10
octal, 1-18, 7-1
Random Access Mode, 4-19
Random record operations
key value during, 4-10
with string keys, 4-14
RAT.
(See File Access Block)
RBF.
(See Record Access Block)
Read-sharing, 3-52
Record Access Block, 1-1, 1-10, 4-1
allocation, 1-11
allocation macros, 1-3
and a FAB, 4-7
associated with a FAB, 8-16
ASYN, 1-11
asynchronous, 4-25
BID, l-12t, 4-2t, 4-3
BKT, l-12t, 4-2t, 4-4
B LN , 1-1 2 t , 4- 2 t , 4- 5
cautions, 1-12
CTX, l-12t, 4-2t, 4-6
FAB, l-12t, 4-2t, 4-7
field offset macros, 1-3, 4-1
initialization, 1-11
initialization macros, 1-3, 4-1
ISI, l-12t, 4-2t, 4-9
KBF, l-12t, 4-2t, 4-10
KRF, l-12t, 4-2t, 4-12
KSZ, l-12t, 4-2t, 4-13
MBC, l-12t, 4-2t, 4-15
MBF, l-12t, 4-2t, 4-17
RAC, 1-12t, 4-2t, 4-19
RB$LOA, 5-34, 5-44
RBF, l-12t, 4-2t, 4-20
representing more than one Record, 1-11
RFA, 1-12t, 4-2t, 4-22
RHB, 1-12t, 4-2t, 4-23

Index-23

Record Access Block (continued)
ROP, l-12t, 4-2t, 4-25
RSZ, l-.12t, 4-2t, 4-28
STS, l-12t, 4-2t, 4-30
STV, l-l 2t, 4-2t, 4-31
SYN, 1-11
type, 1-11
UBF, l-12t, 4-2t, 4-32
use of RBF/RSZ during processing, 4-21
usz, l-12t, 4-2t, 4-34
Record Access Stream, 1-22
disconnect all, 8-2
establish a, 8-16
terminate a, 8-18
unlocks a bucket for, 8-22
Record attributes, 3-44
Record-exists error on Relative files, 4-26
Record format, 3-46
fixed-length, 3-46
stream, 3-46
undefined, 3-46
variable-length, 3-46
VFC, 3-46
Record header buffer, 4-23
Record length, minimum, 5-51
and Alternate Keys, 5-51
and the Primary Key, 5-51
Record Management Service, 1-1
Record Number, Maximum (Relative files only), 3-37
minimum, 3-3 7
Record number, relative, 4-4, 4-10, 4-13
Record operation, 1-2, 1-19
calling sequence, l_.20
connect, 4-7
$DELETE, 3-23
$GET, 3--2 3
greater-than match, 4-26
greater-than-or-equal match, 4-26
input key, 4-10
$PUT, 3-2 3
relative record number input, 4-4
RMS-11 verifies RAB before, 4-3, 4-5
$TRUNCATE, 3-2 3
$UPDATE, 3-24
Record Operation Macros, 1-22, 8-15
$CONNECT, 1-23t, 8-15t, 8-16
$DELETE, l-23t, 8-15t, 8-17
$DELETE and Current Record, 8-17
$DELETE and Sequential file, 8-17
$DISCONNECT, l-23t, 8-15t, 8-18
$DISCONNECT and magnetic tape file, 8-18
$FIND, 1-23t, 8-15t, 8-19
$FIND and duplicate keys, 8-20
$FIND and ER$RNF error code, 8-20
$FIND and index of reference, 8-20
$FLUSH, 1-23t, 8-15t, 8-21
$FREE, l-23t, 8-15t, 8-22
$FREE and multiple streams, 8-22
$GET, l-23t, 8-15t, 8-23
$GET and duµlicate keys, 8-24
Index-24

Record Operation Macros (continued}
$GET and ER$RNF error code, 8-24
$GET and RAB RBF/RSZ fields, 8-23
$GET and unit record terminator, 8-24
$NXTVOL, l-23t, 8-15t, 8-25
$NXTVOL and input file processing, 8-25
$NXTVOL and output file processing, 8-25
$PUT, l-23t, 8-15t, 8-27
$PUT and Indexed files, 8-28
$PUT and Next Record, 8-27
$PUT and Relative files, 8-28
$PUT and Sequential files, 8-28
$REWIND, l-23t, 8-15t, 8-29
$REWIND and RSTS/E magnetic tape, 8-29
$TRUNCATE, l-23t, 8-15t, 8-30
$TRUNCATE and Current Record, 8-30
$TRUNCATE and Next Record, 8-30
$UPDATE, l-23t, 8-15t, 8-31
$UPDATE and Current Record, 8-31
$UPDATE and RAB RBF/RSZ fie, 8-31
$UPDATE restrictions on Indexed files, 8-32
$UPDATE restrictions on Relative files, 8-32
$UPDATE restrictions on Sequential files, 8-32
$WAIT, l-23t, 8-15t, 8-33
Re~co rd operation
access mode during, 4-19
asynchronous, 1-22, 4-25
optional functions during, 4-25
random with string keys, 4-14
record moved by, 4-20
synchronous, 1-22
Record processing, bypass RMS-11, 9-1
Record size, 4-28
input to put operation, 4-29
input to update operation, 4-29
Record size, maximum, 3-39, 4-28
and fixed-length records, 3-40
and Relative files, 3-40
Record size, minimum, 3-39
Record Transfer Mode, 4-20
Locate, 4-26
Record's File Address, 4-19, 4-22, S-19, 8-23
and disk files, 8-20, 8-24
RE~co rd
Current, 1-2.2
delete an existing, 8-17
Next, 1·-22
retrieve a specified, 8-23
delete from a Sequential file, 8-30
Reference, key of, 5-58
maximum, 4-12
minimum, 4-12
Relative files, record-exists error on, 4-26
Relative record number, 4-4, 4-10, 4-13
Relative volume number, 5-20
Release buffer space, 8-18
R elease Core Block.
(See GSA routine}
Release of space, RMS-11, 2-10
Replace an existing record in an RMS-11 file, 8-31
1

Index-25

Report, Software Performance, A-19
Request Core Block.
(See GSA routine)
Request for service, 1-2
Request for space, RMS-11, 2-10
Reset bits within a bit string data field, 7-6
Retrieval pointers, 3-48
Retrieval window size, 3-48
Retrieve
a specified record, 8-23
a specified virtual block, 9-3
attributes of an RMS-11 file, 8-12
Revision date and time information, file, 5-21
Revision date, file, 5-26
accuracy of, 5-26
Revision number, file, 5-27
$REWIND.
(See macro)
Rewind magnetic tape file
on close, 3-29
on open, 3-2 9
RFA.
(See Record Access Block)
RFA, access by, 4-19
RFM.
(See File Access Block)
RHB.
(See Record Access Block)
$RLCB.
(See GSA routine)
RMS-11, 1--1
facilities, declare, 1-2
Pool Block Header Formats, 2-10
release of space, 2-10
request for space, 2-10
Root level number, 5-50
Root module, 1-5
Root Virtual Block Number, 5-59
ROP.
(See Record Access Block)
Routine, fatal error crash, A-2
and general registers, A-18
ER$BUG error code, A-19
ER$FAB error code, A-18
ER$MAP error code, A-19
ER$RAB error code, A-18
Routines, completion, 1-19
$ RQC B •
(See GS A r o u t in e)
RSTS/E, file extension and clustersize on, 3-18, 5-16
RSZ.
(See Record Access Block)
RTV.
(See File Access Block)
Segmented keys, 5-52, 5-56
and ascending byte positions, 5-57
size of, 5-60
maximum number of segments, 5-52
minimum number of segments, 5-52
Segments
multiple key, 5-56, 5-61
number of key, 5-52
position of key, 5-56
Sequencing of Allocation XABs, 5-4
Sequential Access Mode, 4-19
Sequential file
delete records from a, 8-30
and multiblock count, 4-15
Service, request for, 1-2

Index-26

~.
I

"-"'

$SET.
(See macro)
Set bits within a bit string data field, 7-7
Set context, 8-29
at end-of-file during connect, 4-25
$SETGSA.
(See macro)
Severe error conditions, A-2
Sharing, file, 1-22, 3-52
allowing readers, 3-52
allowing writers, 3-52
and Sequential files, 3-52
SHR.
(See File Access Block)
Signed integer key type
16-bi t I 5-36
32-bit, 5-36
Significant bits, least, 7-1
Size of segmented keys, 5-60
Size, bucket, 4-17, 5-9, 5-11, 5-16, 5-49
and default extension quantity, 3-17, 5-15
and initial allocation quantity, 3-4, 5-8
valid for Relative and Indexed files only, 3-6
(See also File Access Block BKS field)
(See also Allocation XAB BKZ field)
Size
advantage of different bucket, 5-12
data bucket, 5-33
disk file.
(See Allocation XAB ALQ field)
index bucket, 5-43
key, 5-60
key buffer, 4-13
magnetic tape block.
(See File Access Block BLS field)
maximum bucket, 3-6, 5-11
maximum file name string, 3-27
maximum key, 5-60
maximum magnetic tape block, 3-10
Maximum Record, 3-39, 4-28
Maximum Record, and fixed-length records, 3-40
Maximum Record, and Relative files, 3-40
maximum user buffer, 4-34
maximum window, 3-48
minimum bucket, 3-6, 5-11
minimum magnetic tape block, 3-10
minimum record, 3-39
m1n1mum window, 3-48
nonstring key, 4-14
recommended for magnetic tape blocks, 3-9
re co rd, 4-2 8
record, input to put operation, 4-29
record, input to update operation, 4-29
retrieval window, 3-48
total key, 5-63
user buffer, 4-32, 4-34
Smithsonian Astrophysical Base Date, 5-23, 5-26
Software Performance Report, A-19
Space, buffer.
(See also central buffer pool)
optimize, 4-25
release, 8-18
RMS-11 release of, 2-10
RMS-11 request for, 2-fo
Spanning, block, 3-44

Index-27

Specification, full file, 1-16, 6-3, 6-4
Specification, maximum full file, 6-5
Status code, 3-54, 4-30
Status value, 3-55, 4-31, A-2
description of system error codes, A-4
$STORE.
(See macro)
Store file attributes in XAB fields, 8-6
Stream.
(See Record Access Stream)
Stream record format, 3-46
String key type, 5-36
String keys, ~andom record operations with, 4-14
String size, maximum file name, 3-27
Structures, internal control, 1-6
STS.
(See Record Access Block)
STV.
(See Record Access Block)
STV field, A-2
SU$cod, A-1
Success completion codes, A-1
Summary information, 1-13
Summary of keys and areas in an Indexed file, 5-71
Summary XAB
BLN I 5-71 t I 5-72
COD, 5-7lt, 5-73
NOA I 5-71 t I 5-7 4
NOK, 5-7lt, 5-75
NXT, 5-7lt, 5-76
PVN, 5-7lt, 5-77
Supersede existing file, 3-29
Suspend program operation, 8-33
Symbolic value, 1-10
Symbols, global, 1-10
Synchronous record operation, 1-22
System defaults, 1-16, 3-25
Systems, PDP-11 operating, 1-1
Tape block size, magnetic.
(See File Access Block BLS field)
recommended, 3-9
maximum, 3-10
minimum, 3-10
Tape block, characters in magnetic.
(See File Access Block)
Tape file forward or backward, move magnetic, 9-6
Tape files, multivolume magnetic, 8-25
Tape volume, continue processing on the next, 8-25
Task build, 1-2
Task Builder, 1-5, 1-22
PSECTS in alphabetical order, 1-23
/SQ switch, 1-23
Temporary file, 3-29
Temporary file marked for delete, 3-2 9
Terminal, 3-45
Terminate a Record Access Stream, 8-18
$TES TB ITS.
(See macro)
Time information
file creation date and, 5-21
file revision date and, 5-21
Total key size, 5-63
Transfer mode, record, 4-20
$TRUNCATE.
(See macro)

Index-28

Type, key, 5-28
16-bit signed integer key, 5-36
16-bit unsigned binary key, 5-36
32-bit signed integer key, 5-36
32-bit unsigned binary key, 5-36
and prologue version number, 5-77
key data,' 5-36
reassembly requirement, 5-36
string key, 5-36
UBF.
(See Record Access Block)
Undefined record format, 3-46
Unit record device, 3-45
Unit, logical.
(See logical channel)
Unlock file if abnormal close, 3-29
Unlocks a bucket for a Record Access Stream, 8-22
Unsigned binary key type
16-bit, 5-36
32-bit, 5-36
$UPDATE.
(See macro)
Update operation
automatic file extension during, 3-17
key change during, 5-39
User buffer, 8-23
User buffer size, 4-34
and Locate Mode, 4-32
· maximum., 4-3 4
User call error, fatal, A-18
User context field.
(See Record Access Block CTX field)
User control block
access fields in, 1-2
allocatE~, 1-2
allocation at assembly time, 1-8
assembly-time field initialization, 1-8
data fields in, 1-8
initialize, 1-2
other than default value in field, 1-10
run-time field access, 1-8
(See also File Access Block)
(See also Record Access Block)
(See also Extended Attribute-Block)
(See also NAM Block)
usz. (See Record Access Block)
Variable-length record format, 3-46
Variable-with-fixed-control.
(See VFC)
V•Hsion number, prologue, 5-77
and key data types, 5-77
VJ~C

and no record header buffer, 4-23
and scatter-read, gather-write, 4-23
during Locate Mode, 4-24
record format, 3-46
records, 3-32, 4-23
Virtual block number, 3-48, 5-7, 5-38
maximum, 4-4
Root, 5·-59
Virtual block
retrieve a specified, 9-3
write a specified, 9-5

Index-29

Volume number, relative, 5-20
Volume, continue processing on the next tape, 8-25
Wait for asynchronous record operation, 8-33
Window size
maximum, 3-4 8
minimum, 3-48
retrieval, 3-48
Write
a new record into an RMS-11 file, 8-27
a specified virtual block, 9-5
operations by RMS-11, file opened for, 5-27
Write-sharing, 3-52
Writes all modified I/O buffers, 8-21
X$fnm.
(See macro)
XAB.
(See File Access Block)

·~.

Index-30

RMS-11 MACR0-11
Reference Manual°
READER'S COMMENTS

Order No. AA-H683A-TC

NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.
D
D
D
D
D
D

Assembly language programmer
Higher··level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Name
Organization _ _ _· - - - · - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Street
City

State - - - - - - Zip C o d e - - - - - - - - or
Country

I
- - -

-Do Not Tear - ~'old Here and Tape -

- -

- - -

~nmnomn

- ---1

No Postage
Necessary
if Mailed in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

ATTN: Commercial Engineering Publications MK1-2/2H3
DIGITAL EQUIPMENT CORPORATION
CONTINENTAL BOULEVARD
MERRIMACK N.H. 03054

I
I

-- -

Do Not Tear - Fold Here and Tape -

-- -