Digital PDFs

AA-H683A-TC

March 1979

371 pages

Original

11MB

Document:	RMS-11 MACRO-11 Reference Manual Version 1.8
Order Number:	AA-H683A-TC
Revision:	000
Pages:	371
Original Filename:

OCR Text

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

March 1979

This manual describes the use of RMS-11 facilities 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

digital 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-lo
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
CHAPTER 1
DECLARING RMS-11 FACILITIES
1.1
Listing Names of Required Macro Definitions
1.1.1
Declaring the Processing Environment
1.1. 2
1.1. 3
Declaring Buffer Pool Requirements
USER CONTROL BLOCKS
1. 2
1. 2. 1
File Access Block (FAB)
1.2.1.1
Allocation
1.2.1.2
Initialization
1. 2. 2
Record Access Block (RAB)
1.2.2.1
Allocation
1.2.2.2
Initialization
1. 2. 3
Extended Attribute Block (XAB)
1.2.3.1
Allocation
1.2.3.2
Initialization
1.2.3.3
Linking and Ordering XABs
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
1. 3
CONTROL BLOCK FIELD ACCESS AT RUN TIME
1. 4
FILE .AND RECORD OPERATIONS
1. 4 .1
Completion Routines
Calling Sequence
1. 4. 2
1.4.2.1
Your Program Supplies the Argument List
1.4.2.2
RMS-11 Generates the Argument List
1. 4. 3
File Operation Macros
1. 4. 4
Record Operation Macros
1. 5
CREATING THE TASK

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

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

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-17
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.1
3.22.2
3.22.3
3.23
3.23.1
3.23.2
3.23.3
3.24
3.24.1
3.24.2
3.24.3
3.24.4
3.25
3.25.1
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 Default
Comments
FNS
Use
Input Values
Initialization and Default
FOP
Use
Input Values
Initialization and Default
Comments
FSZ
Use
Input Values
Initialization and Default
Comments
IF!
Use
LCH
Use
Input Values
Initialization and Default
Comments
MRN
Use
Input Values
Initialization and Default
MRS
Use
Input Values
Initialization and Default
Comments
NAM
Use
Input Values
Initialization and Default
ORG
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
-,:7

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

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
!SI
Use
KBF
Use
Input Va 1 ues
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

3-49
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
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

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.1
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.1
4.18.2
4.19
4.19.1
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

CHAPTER 5
5.1
5 .1. 1
5.1.1.1
5.1.1.2
5.1.1.3
5.1. 2
5.1.2.1
5.1.2.2
5.1.2.3
5.1.2.4

Use
Input Values
Initialization and
Comments
RAC
Use
Input Values
Initialization and
RBF
Use
Input Values
Initialization and
Comments
RFA
Use
Input Va 1 ues
Initialization and
RHB
Use
Input Values
Initialization and
Comments
ROP
Use
Input. Values
Initialization and
Comments
RSZ
Use
Input Va 1 ues
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
5 .1. 8
5.1.8.1
5.1.8.2
5.1.8.3
5.1.8.4
5 .1. 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
5.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
,;) .. 2. 6
~) .. 2.6.1
S .. 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 and
DBS
Use
Output Values
DFL
Use
Input Values
Initialization and
DTP
Use
Input Values
Initialization and
DVB
Use
Output Values
FLG
Use
Input Values
Initialization and
Comments
IAN
Use
Input Values
Initialization and
!BS
Use
Output Values
!FL
Use
Input Values
Initialization and
KNM
Use
Input Values
Initialization and
LAN
Use
Input Values
Initialization and
Comments
LVL
Use
Input Values
MRL
Use
Output Values
Comments
NSG
Use
Input Values
NUL

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

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

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

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

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

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

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
$TESTBITS
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
v;

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

7-11
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-I

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

?REFACE

Management Services for the PDP-11 (RMS-11) provides powerful
jata 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.
~ecord

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 1

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 5

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.

xvi

See the

Documenta-

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 or another
are printed in color as follows:
•

RSTS/E-specific information is printed in red.

•

IAS-, 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

REQUIRED

You must include
acters as shown.

uppercase

char-

user-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 G~ide 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 program 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 a rg [ , a rg] •• ]
where arg is a symbolic name of a macro required in the ,assembly of
your program. The macro names can be listed in any 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.

$!NIT 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).

$RBCAL

Record operation macros (described in Chapter 9).
llc::i nn

'QM~-11

;:i

MA.r.Rn-11 Proa ram

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 executi-0n 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 mBcros, 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

Usina RMS-11 in a MACR0-11 Proaram

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

IDX = Indexed file organization
REL = Relative file organization
SEQ = Sequential file organization
recop 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.
IJqinn

RM~-11

in~

MArRn-11

Prnnr~m

1-t;

1.1.3

Declaring Buffer Pool Requirements

RMS-11 requires a collection of I/O buffers and internal contro1
structures· to support file processing at run time. The area in your
program occupied by these buffers and control structures is known 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 is 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

Usina RMS-11 in a MACR0-11 Proaram

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
simultaneously

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

Usina 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 $INIT or $INITIF macro.
General form:
$INIT

$INITIF

The code generated by the $INIT macro unconditionally 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 initialization was successful. Therefore, normally after $INIT, 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.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:
$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 IF!
field contains the value returned by RMS-11 when the file was c'reated
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

ti~e.

.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.
The FAB$B macro allocates space for
1-8

CJ~i na

RM~-11

M1'r~n-11

the

Prnnr~m

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
XAB

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

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
Re co rd format
Window size
Cl ustersi ze
File sharing
Completion code
More error information
Pointer to first XAB

*File attribute

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

Usina RMS-11 in a MACR0-11 Proaram

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.

•

numeric value, such as maximum record size, specifying
the number of bytes, characters, blocks, and 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

Usina RMS-11 in a MACR0-11 Proaram

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 IRAB. 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 RAB$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:

initialization

macros

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

Description

1----+-----+------- - - - - - - - - - - - - - - - - - - - - · - - - - - ____________,__

usz

1-12

0
0

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

N/A
N/A
0
0

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

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 label 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:
XB$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 file

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) to be
tered in the indicated field; arg can be a:

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

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

X$NXT

SUMXAB

XAB$E
SUMXAB: XAB$B

XB$SUM

PROXAB

;

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
#PROXAB, 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
An index that the file processor can use to locate a file
without 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 "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 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 tetm 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:
•

•

The default radix for numeric values in
decimal.

initialization

macros

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

field

ac-

Usinq RMS-11 in a MACR0-11 Program

1-17

Table 1-5:

Field
Name

Fi eld
Si ze
·~

1.3

Default

Description

..............

1w
1w
1B
1B
1B

DVI
ESA
ESL
ESS
FID

NAM Block Fields

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

0
0
0
0
0

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:
Macro Name

Each

macro

RMS-11 Field Access Macros
Function

Field Size
"'"-··

$COMPARE

1 byte or 1 word

Compares the con tents of
with a value you specify.

field

$FETCH

Any size

Copies the conte nts of a field into
a location you s pecify.

$OFF

1 byte or 1 word

Resets one or mo re
bit string field.

$SET

1 byte or 1 word

Sets one or more bits within a
string field.

$STORE

Any size

Copies the conte nts of a
you specify into a field.

$TESTBITS

1 byte or 1 word

Tests one or mor e bits within a bit
string field.

,,,

-····'

bits

within

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

bit

location

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 ex tension 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.
"~.;l"\N

DMC:-1 l

MarRn-11

Proaram

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 R5 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(R5) 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 requires 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

Usinq RMS-11 in a MACR0-11

Proar~m

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

following

form,

Argument

Size

RMS-11 Interpretation

Undefined
Argument 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 list 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 of the associated control block.

Example

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

LIST:

Example

.WORD
.WORD
.WORD
.WORD

uses

#LIST,R5

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

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

INRAB
ERRl
SUCCl

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

.WORD
.WORD
.WORD
.WORD

INRAB
;NO ERROR ROUTINE

-1

SUCCl

Usina 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
MOV
#LIST,RS
$GET
$COMPARE #0,STS,2(R5)
BGT
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

INRAB
ERRl
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

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

$ERASE

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

$EXTEND

Increases the number of blocks allocated
file.

$OPEN

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
File 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
file.

$UPDATE

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

$WAIT

1-24

Suspends processing until an RMS-11
cord operation completes •
.........._

_______ _______

.___

end

Relative

~-~---

File Operation Macros

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$BUF

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 f i 1 e
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

*
*
*

P$FAB

*
*

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

2.1.2

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.
keysiz 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 iosiz
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.
•

For Relative files:

STRMSZ

RAB

associated

= 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
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 properly.

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

2-8

GSARTN:
RTS

GSA$

GSARTN

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:
R6 MUST BE RO - R5;

.ERROR
Example

GSARTN:
RTS

$SETGSA #GSARTN
Example

$SETGSA R5

Example

$SETGSA 10 (SP)

Example

$SETGSA 10 (R 3)

2.2.1.3

Retrieving a Get Space Address at Run Time -

General form:
$GETGSA
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

<> O)

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 Soace 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 i~s 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 <> 0, value points
header

the

first

the

pool

des-

available

pool

block

RMS-11 Pool Block Header:
----------- 0

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

size
----------- 4

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

if value
pool

= 0, this is the last available block in

this

•

if value <> O, value points to the next available
block

pool

size is the size in bytes of
four-byte header

including

the

•

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

The

•

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

2.2.3

this

pool

block

Comments

Get Space Routine

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 = 0
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 buff~r, 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

CHAPTER 3
FILE 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 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 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$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:

File Access Block Fields

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
XAB

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

Default
0

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

N/A
0
0

FB$GET
0
0
0
0

lW
lB
lW
lB
2W
lW
lW
lB
lB

N/A
0
0
0
0

FB$SEQ
0

FB$VAR

0
0
0

18
18

lW
lW
lW

____.____

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
Si ze o f f i 1 es pe c
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

~----'-"·-~~---.-...a....---------~,---------------1

*File attribute

3-2

File Access Block (FAB):

Introduction

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

*
*

ALQ

*
*

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

3.1

ALQ

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

$CREATE
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 initialization 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

Comments

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

ALO

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

*
*

BID

*
*
*

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

3.2

BID

The FAB$B macro sets the one-byte Block Identifier (BID) field to
File Access 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

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

*
*

FILE ATTRIBUTE

BKS

*
*

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

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

that

bucket

= 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

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

*
*

BLS

*
*

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

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 (FAB):

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

device

driver software
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

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

*
*
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 = O.

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
two
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 macro
below or with the $STORE field access macro (see Chapter 7~.

3.7.3

Initialization and Default

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

3-14

File Access Block (FAB):

BPS

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.

com-

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

shown

3.8.2

Input Values

Anything you want, as long as it fits in 16 bits.

3.8.3

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
until the file is closed;
the file attribute
is not
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 extend 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 = O.

3.9.4

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

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

*
*

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

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

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

*
*
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 name string.
This string may contain values
for one or more of the following file specification components:
device
account
file name
file type
file 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:
F$DNA label
If there is no initialization macro, DNA = O.

3.11.4

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

Comments

•

The default 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 the DNA field is zero, RMS-11 ignores the DNA field;
if
the DNA field is not zero, that is, you are providing a default name string, you must set the DNS field equal
to
the
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

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

File Access Block (FAB):

DNS

= O.

shown

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

*
*
FAC
*
*
***************
3.13

FAC

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:
$CREATE/$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-

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

fields

the

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:
F$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 FAB.

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 FB$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 FB$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 FB$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:
FB$CTG

3-28

one

the

following

symbolic

RMS-11 is to allocate contiguously the amount of space
specified in the FAB 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
files.

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.

~ilo

~~~~~~

Rlo~k

lFAB):

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.

•

RMS-11 creates a permanent file.

3.16.4
•

volume

before

contains

Comments

The IAS 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
utility (PIP) unlocks it.
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.

~;10

n~~~~~

Rln~k

(FAB):

NAM 3-30.1

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

*
*

FILE ATTRIBUTE

FSZ

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

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

fixed

control

size

Input Values

MINIMUM = O, meaning that RMS-11 sets the control
bytes*

area

two

= 1, the smallest fixed control area allowed
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.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

3.17.4

= 0.

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 FAS to the !FAS 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 !FI field to
from the FAS to the !FAS.

transfer

pertinent

data

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

*
*
*

*
*
*
*************
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.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 maximui
number of records that can be written to the Relative file associate1
with the FAB. RMS-11 checks the relative record number used with eac:
put operation against this maximum and rejects (error code ER$MRN) an
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 an~
record that will (or should) be written into the file*. If
you want no checks on relative record number, set MRN equaJ
to zero.
Output from:
$OPEN
RMS-11 sets the MRN field equal
when the file* was created.

3.20.2

the

value

established

Input Values

MINIMUM

MAXIMUM

meaning that RMS-11 writes
the
MRN
value
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

************~

*
*
*

FILE ATTRIBUTE

MRS

~
************~

3.21

MRS

The one-word Maximum Record Size (MRS) field contains the maximurr
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. l

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.

3.21.2

the

value

established

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

3.21.4

= O.

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.

$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 use the device and file IDs in NAM
DVI and FID fields to identify, then open 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 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.

Input Values

The NAM field must contain either:

= there is no NAM Block associated with this FAB

•

zero (0)

•

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:
F$NAM label
If there is no initialization macro, NAM

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

3-42

File Access Block (FAB):

ORG

= FB$SEQ.

shown

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

*
*
*

FILE ATTRIBUTE

RAT

*
*
*

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

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 attributes established for the file when it was created. You
can test for these values using field access macros (see
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.

FB$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

*
*

RFM

*
*

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

3.25

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 (FAB):

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

IAS/RSX-llM

3.26

RTV

The one-byte Retrieval Window Size (RTV) field contains the number of
retrieval pointers kept in memory* for the file represented by the
FAB.
Retrieval 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-

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

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:

This

system.

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

MINIMUM

else ER$CRE

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

FilP

~~~P~~

Rlock

lFAB):

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.

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

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

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
erations

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

3-52

File Access Block (FAB):

SHR

= O.

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

*
*
*

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 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 XAB field must contain either:
•

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

•

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

3.31.3

the
shown

Initialization and Default

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

XAB

3-55

If there is no initialization macro, XAB = O.

3.31.4

Comments

•

See Chapter 5 for details on XABs.

•

An Indexed file requires at least one XAB
Key.

3-56

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

•

O$STS for the status code field

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

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

4-2

N/A
0
0

0
0
0

0
0
0
0
0
0

N/A
N/A
0
0

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

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

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

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

Record Access Block (RAB) :

BKT

= O.

shown

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

*
*
*

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.

com-

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

Input Values

Anything you want, as long as it fits in 16 bits.

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

FAB

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:
R$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

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

*
*

ISI

*
*
*

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

4.6

ISI

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

4.6.1

Use

RMS-11 uses the address in the ISI field to
from the RAB to the IRAS.

transfer

pertinent

Record Access Block {RAB):

IS!

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.

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

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 field:
e

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

Record Access Block (RAB):

KSZ

de-

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

63.

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

4.10.4
•

= O.

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
11
Va 1 ue s 11 ) •

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:
R$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.

•

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

•

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

MBF

for

the

minimum

number

more than two for Sequential files, RMS-11
buffers

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

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:
R$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) :

RBF

shown

4.13.3

Initialization and Default

Macro takes the form:
R$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.

your

•

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

record

each

program
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) to the
with zeros

•

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

•

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-?4

Recorn Access Block lRAB):

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 asynchronous 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:
D,....,..." ~ ~

7\,...,... ,..._,...,...

D, - - 1..

In 1\ n \

1"'"\

"T"'\

'"' I:"

RB$KGE

RB$KGT

RB$MAS

•

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 0 bucket before it detects that the record has
been deleted.

•

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

SIDR

removed

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

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

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

Rlo~k

fRAR' !

RnP

~-?7

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

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:
$GET
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

record

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 of O 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 CRAB):

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 mode
(see UG):
it then moves the record into the buffer ind icated 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

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.
$RUT
During Locate Mode operations on Sequential files only.
discussion under "Use" for the UBF field.

4.21.2

Input Values

MINIMUM

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

Initialization and Default

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

4-34

See

Record Access Block (RAB) :

USZ

= O.

shown

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

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
of an RMS-11 file that is treated as a separate entity for purposes
0 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 FAB 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 O.
RMS-11 allocates all other areas as extents of
Area O. 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
volume.
•

controls the physical placement of the file on the disk

For Indexed files, RMS-11 sets up a single bucket size and stores
buckets of all types (index, SIDR, and user data record) in the
single area of the file.

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 O
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:

Allocation Extended Attribute Block Fields

Field
Name

Field
Size

Default

AID
ALN
ALQ
AOP
BKZ
BLN
COD
DEQ
LOC

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

0
0
0
0

VOL

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:
$CREATE/$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

Initialization and Default - Macro takes the

shown

form~

X$AID n um er ic
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 the 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 / 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.

blocks

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

$CREATE
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

the

device

containing

the

file.
$EXTEND
MINIMUM

= 1, meaning that one block should be added to

MAXIMUM

= number of free blocks

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

the

device

containing

the

area.

Allocation XAB:

ALQ

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 = O.

5.1.3.4

Comments

•

When Allocation XAS(s) are linked to a FAB, create and extend operations ignore the FAS ALQ field, using the XAS ALQ field(s) for the
particular area(s). If you include only one Allocation XAS, for
Area O, RMS-11 uses the ALQ field in the XAS instead of the FAS 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 XAS:

ALO

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

*
*
*

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

that

bucket

contains at least one record.
MAXIMUM

= number of blocks allowed by the operating system {specifying
a larger value results in error code ER$BKZ):
IAS
RSTS/E
RSX-llM

= 32 blocks
= 15 blocks
= 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 XASs are linked to a FAS, RMS-11 ignores the
SKZ field, using the XAS SKZ fields for the particular areas.

FAS

•

You gain no particular advantage from different
different areas.

bucket

sizes

for

Allocation XAS:

SKZ

5-11

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

*
*
*

BLN

*
*
*

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

5.1.6

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

5-12

Allocation XAB:

BLN

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

*
*
*

COD

*
*
*

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

5.1.7

COD

The XAB$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 estabiished 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

MAXIMUM

= 65,535 blocks

area,
it
will request the minimum blocks necessary to complete the
current operation, that is, one bucket.

*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 = O.

5.1.8.4

Comments

•

When Allocation XABs are linked to a FAB, RMS-11 uses the XAB 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 FAB
DEQ 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 XAB:

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 indicates
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:
MINIMUM

follow-

= 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, if
the ALN field contains XB$CYL

= number of blocks currently in the file,

if the ALN

field

contains XB$VBN
•

the numeric value -1 if the ALN ~ield 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

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

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

= O.

the
shown

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

*
*

VOL

*
*

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

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:
Field
Name

Field
Size

Date Extended Attribute Block Fields
Default

Description
,_,

BLN
CDT
COD
NXT
RDT
RVN

lB
4W
lB
lW
4W
lW

N/A
N/A
N/A
0

N/A
N/A

DAT XAB length
Creation date-time
XAB type
Next XAB
Revision date-time
RMS-11 revision number
""-

5-20

Date XAB: Introduction

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

*
*
*

BLN

*
*
*

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

5. 2. 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.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 !AS, 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 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.
**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

NXT

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.

•

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$NXT 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:
IAS
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
operations, such as FCS,
BASIC+,
and
utilities (PIP and so on).
Since higher-level
language statements eventually break down to
RMS-11 macros,
the r~v1s1on 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 IAS 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
file 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 FAB 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
.,,,,=..- " _ " _ "

5-28

Key XAB:

Introduction

...........

,,__,........,. ___

0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

KEY XAB length
XAB t ype
Level 0 area number
Data bucket size
Level 0 fill number
Key d ata type
VBN o f first data bucket
Key c haracteristics
Level s 2+ area number
Index bucket size
Level s 2+ fill number
Point er to key name
Level 1 area number
Index level of root
Minim um length record size
Numbe r of key segments
Null key value
Next XAB
Key p osition(s) in record
Key d escribed by XAB
VBN o f index root
Size ( s) of key segments
Total key size
.

N/A
N/A

lB
lB
lB
lB
lW
lB
4W
lB
lB
lB
lW
lW
lB
lB
lB
lB
lB
lW
8W
lB
2W
8W
lB

BLN
COD
DAN
DBS
DFL
DTP
DVB
FLG
IAN
IBS
IFL
KNM
LAN
LVL
MRL
NSG
NUL
NXT
POS
REF
RVB
SIZ
TKS

-----~--------------

Descr iption

Default

Field
Size

Field
Name

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

*
*
*

BLN

*
*
*

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

5. 3. l

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

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

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

Initialization and Default - Macro takes the form:

X$DAN numeric
If there is no initialization macro, DAN = O.

5-32

Key XAB:

DAN

shown

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

*
*
*

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

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

= O, 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 minimum,
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.

dee imal

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

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
index is Primary
MAXIMUM

the

Prologue)

= 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

Key Type

XB$CHG
+
XB$DUP

XB$CHG
+
Default

Default
+
XB$DUP

Default
+
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 will 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

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

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

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

*
*
*

IBS

*
*
*

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

5.3.10

IBS

The one-byte Index Bucket Size (IBS)
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

IFL

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 IFL 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 IFL 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
=

MAXIMUM

half of the bytes in the bucket; this is a logical minimum,
meaning you can specify less, but RMS-11 ignores it, supplying its own 50% figure

= 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

5.3.12.2

•

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.

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 there is no initialization macro, KNM

= O.

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 de fault) •

•

If you are creating a multi-area file, that is, ther~ 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 allocati~n 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 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).

5-48

Key XAB:

LAN

shown

5.3.13.3

Initialization and Default - Macro takes the form:

X$LAN numeric
If there is no initialization macro, LAN = O.

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

MAXIMUM

= no logical limit

5-50

possible,
one level of data and one level of index, the Root

Key XAB:

LVL

with

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

*
*
*

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:
$DISPLAY/$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 m1n1mum 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
the record is shorter than the MRL, RMS-11 makes no entry in the
index for the record.

KP-v XAR !

MRT.

C:.-C:.1

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

*
*

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.

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

XB$KEY

.
X$DTP
.

XB$STG

X$FLG
X$NUL

XB$NUL
"l 77

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:

NUL

de-

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

*
*
*

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

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.

•

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:

num-

MINIMUM = O, meaning the segment starts in the first byte of
cord

the

re-

the

MAXIMUM

= 65535, meaning the segment starts in the last

byte

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:
<seg0,segl[,seg2, ••• ,seg7]>
5-56

Kev 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$POS [<]numeric[,numeric, ••• >]
If there is no initialization macro, POS = O.

5.3.19.4
•

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) field identifies the index and key
described by this XAB.

5.3.20.l

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

Input Values

MINIMUM

= 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

5-58

Key XAB:

REF

= O.

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:
$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

Output Values -

MINIMUM

= 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

5-60

Key XAB:

(null segment)

SIZ

If a string key has multiple segments, you must
for each segment, using the form:

specify

length

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

shown

<len0,lenl[,len3, ••• ,len7]>
The sum of the multiple lengths cannot exceed 255.

5.3.22.3

Initialization and Default - Macro takes the form:

X$SIZ [<]numeric[,numeric, ••• >]
If there is no initialization macro, SIZ = 0.

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

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

*
*
*

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

Description
-· !---··-·---··-·-'"·

0
0
0
0

PRO XAB length
XAB type
Next XAB
Programmer part of account number
Project part of account number
File protection value

---

--~~~1-----·----~~----~--

5-64

Protection XAB:

Introduction

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

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

*
*
*

BLN

*
*
*

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

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

•

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

5.4.4.2

Input Values

MINIMUM

= O, meaning the default programmer number, based on

number

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

5-68

Protection XAB:

PRG

= O.

shown

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

*
*
*

PRJ

The one-word Project Number (PRJ) field contains the first
the file owner's account number pair.

number

$CLOS E/$CREATE
You set the PRJ field to the group or project number of
owner of the file.

the

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

5.4.5

PRJ

5.4.5.1

Use

Input to:

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
MINIMUM

Input Values
=

O, 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 with 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

= O.

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
5

I WORLD I GROUP I OWNER I SYSTEM I

5-70

Protection XAB:

PRO

number

contained

programmer

of
in

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

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

owner

that account with the project and
contained in this XAB

others

all accounts not in the owner or group categories

number

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 n um er ic
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

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

5-72

opera-

Summary XAB:

0
0
0
0

Descr iption
SUM XAB length
XAB t ype
Numbe r of areas
Numbe r of keys
Next XAB
RMS-1 1 Prologue version number

Introduction

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

*
*

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

5.5.1

BLN

The XAB$B macro sets the one-byte Block Length (BLN)
~ended Attribute Block length.

field to the

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:
$DISPLAY/$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

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

*
*

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

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.

•

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

the
shown

Initialization and Default - Macro takes the form:

X$NXT label
If there is no initialization macro, NXT = O.

Summary XAB:

NXT

5-77

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

*
*
*

PVN

*
*
*

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

5.5.6

PVN

The one-word Prologue Version Number (PVN) field contains
Prologue version number.

5.5.6.1 Use - The PVN field is only applicable to
dexed files.

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 release 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.
O$ESA for the expanded string address field

Example

The values 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

ESA

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 FAB and system defaults)
to the primary
file name string of the FAB.
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)
operation;

•

address of the first byte of a buffer for the full file
tion; the buffer does not have to be word-aligned

there is no file specification buffer
valid only for open and erase by file ID

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.

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$ESS numeric
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 open 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

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 you specify.

$FETCH

Any size

Copies the contents of a field into
a location yo u spec i f y •

$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

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
•

Examples

$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

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

use register
generates an

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
you specify.

•

specify SIZ or POS plus a number from 0 through 7
to fetch a single word from the field. 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.

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

$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,RS

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

************~

*
*
*

$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

bits

within

General Form
$OFF

value,fnm,reg

where value is an expression or location specifying
the data field you want reset,

the

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

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

RB$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:
•

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

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

General register R3 contains the address
clears that FAB's two-word ALQ field.
•

•

$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

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

*
*
* $TESTBITS *
*
*
*************

7.6

$TESTBITS

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

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 BITB instructions,
according to size of the field.

7.6.3

Examples

$TESTBITS

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

$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

$ERASE

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

$EXTEND

Increases the number of blocks allocated
file.

$OPEN

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 !FI (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

Input Fields -

FAS ALQ
BKS
BLS
SPA
BPS
DEQ
DNA
DNS
FAC
FNA
FNS
FOP
FSZ
LCH
MRN
MRS
NAM
ORG
RAT
RFM
RTV
SHR
XAB

(ignored if Allocation XABs linked)
(ignored if Allocation XABs linked)
(magnetic 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 -

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

FAB STS
STV
ALL XAB ALN
ALQ (number of blocks unused in current extent)
AOP (can contain XB$CTG)
BKZ
DEQ
LOC
DAT XAB All fields
KEY XAB All fields
PRO

XAB All fields

SUM XAB All fields
NAM 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.

File Operation Macros:

$DISPLAY

8-7

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

*
*
*

$ERASE

*
*
*

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

8.1.4

$ERASE

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 FAS

•

indicate the correct ID with the NAM FID field

•

set the value FB$FID in the FAS 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 -

FAB 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 contiguously with those blocks already allocated 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 FBSCTG; ignored if Allocation XABs linked)
IFI
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 XAB ALQ (number of blocks actually added to the file)

8.1.5.4

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.5.5 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 f i 1 e •
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:
e

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 XAB AID
DEQ
NXT
DAT XAB NXT
PRO XAB NXT
SUM XAB NXT
NAM DVI
ESS
FID

8.1.6.3

Output Fields -

FAB ALQ
BKS
DEQ
BLS
DEV
FOP
FSZ
IFI
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 XAB 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 f i 1 e.
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
File sharing
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
file.

$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
file.

$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

Relative

RMS-11

Indexed

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

Input RAB Fields -

BID
B~

FAB
KRF
MBC
MBF
ROP
UBF

8.2.1.2

(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.2.1

Input RAB Fields -

BID
BLN
ISI
ROP

8.2.2.2

Output RAB Fields -

STS
STV

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 operation fails.

the

success is the address of a completion routine to be called
$DELETE operation succeeds.

the

$DELETE

8-17

Record Oneration 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
!SI

8.2.3.2

Output RAB Fields -

!SI (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

*
*

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

8.2.4

$FIND

The $FIND 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.4.1
BID
BLN
ISI
KBF
KRF
KSZ
RAC
RFA
ROP

8.2.4.2

Input RAB Fields -

(Random Access Mode only)
(Random Access Mode on Indexed files only)
(Random Access Mode only)
(if RAC contains RB$RFA)

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 -

STS
STV

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 fa i 1 s.

the

success is the address of a completion routine to be called
$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.l

file

Input RAB Fields -

BID
BLN
ISI

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 called
$FREE operation fails.

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,
you should execute a $FREE macro for all other streams to the same
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 RAB RBF and RSZ fields describe the retrieved record with the address of its first byte and its length, respectively.

8.2.7.1
BID
BLN
!SI
KBF
KRF
KSZ
RAC
RFA
RHB
ROP
UBF

usz

Input RAB Fields -

(Random Access Mode only)
(Random Access Mode on Indexed files only)
(Random Access Mode only)
(if RAC contains RB$RFA)
(VFC records only)
(regardless of Record Transfer Mode)

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
STS
STV

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 called
$GET operation 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 0, the terminating character
the record described by the RAB RBF and RSZ fields.
Example

$GET
CMPB
CORD

#0,0$STS(R5)

never

;RETRIEVE A RECORD
;CHECK IF TERMINATOR STILL IN RE-

•

RMS-11 allows Access by RFA during get
only.

•

Normally, you would not use Access by RFA for get operations on Relative and Indexed files, since the output of the operation is the
RFA used as input. However, a get by RFA returns error code ER$DEL
if the specified record once existed in the file, but was subsequently deleted: a random get operation returns error code ER$RNF
whether the record never existed or was deleted.

•

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

disk

files

***************
The $NXTVOL macro is not supported by RSTS/E.

*
*
*

$NXTVOL

*
*
*

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

8.2.8

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

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
rewinds 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 the 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 I

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 ope ration 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
IS I
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 fails.

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:
Set RB$EOF in the RAB ROP field before initiating the connect
operation.
RMS-11
sets
the
Current Record pointer to
end-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
ISI
KRF (Indexed files only)

8.2.10.2

Output RAB Fields -

STS
STV

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

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

!SI

8.2.11.2

Output RAB Fields -

STS
STV

8.2.11.3

General Form -

$TRUNCATE

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
$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:

$TRUNCATE

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

*
*
*

$UPDATE

*
*
*

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

8.2.12

$UPDATE

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

!SI
RBF
RHB (VFC records only)
RSZ

8.2.12.2

Output RAB Fields -

RFA
STS
STV

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

!SI

8.2.13.2

Output RAB Fields -

STS
STV
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 FAB 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 FAB ORG field)

•

Undefined record format {FB$UDF in the FAS RFM field)

$OPEN
You access a file with any RMS-11 file organization;
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.

Use the macros described in this chapter to processing data in the

and initiate a
No stream can be

f i 1 e.

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 (VBN where read starts)
ISI
UBF (address for input buffer)
USZ (size of input buffer as a multiple of two bytes)

9.1.2

Output RAB Fields

RBF (location of data read from file)
RSZ (number of bytes read)
STS
STV

9.1.3

General Form
$READ

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
•

Comments

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.

9-4

Block I/O Operations:

$READ

RSZ

still

contains

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

*
*

$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 of 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 com pl et ion routine to be cal 1 ed
$SPACE operation 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.I

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

ER$STK/ER$MAP Operation aborted:
Stack save
area exhausted or memory resident control structures corrupted.
f ipcode

File processor error: File processor
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

·--··----,··--!-----·-··-··· - - -

i------~1--------·---+-·····-··-·

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
variable-length, but
not
in
ANSI-D format
XAB address

Invalid type of allocation.
Invalid operation at AST level:
You attempted
to
issue a syn-,
chronous operation from an asyn-'
chronous 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.

f i pc ode

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

Description

No Current
Record:
Delete,
truncate, or update operation
was not immediately preceded by
a successful get or find.

Syntax error in device name
No such device
Inappropriate device for operation
Example

f i pc ode

access

You at tempted
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$DFW

177070/-456.

ER$DIR

177060/-464.

Syntax error in filespec
tory name.

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.

fipcode

ER$DTP

176760/-528.

XAB address

______...___________,__________

direc-

Device positioning error.
Invalid key data type.
-i------------"----····---~~~

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

ER$FAB

176600/-640.

FAB BID field does
FB$BID.

ER$FAC

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.

f i pc ode

date

not

File processor error:
During
RMS-11 file extension operation.
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.

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.

File locked by another user:
You cannot access the file because your sharing specifications cannot be met.
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

'-------.JI----~·-~--~~~--~-~---~~~~-~------------·---------='

(Continued on next page)

A-8

Error Completion Codes

Table A-2 (continued)
Symbolic
Value

Numeric
Value

STV Field
Value

Description

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

176240/-864.

$!NIT 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 operations.

ER$IRC

176200/-896.

Illegal record encountered in
Sequential file: Record-length
field is invalid.

ER$ISI

176160/-912.

RAB IS! field is invalid.
You
may have altered it or failed to
connect the stream.

ER$KBF

176140/-928.

No key specified during random
record operation: RAB KBF field
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;
that is, you al ready opened 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

Description

Invalid area number specified in
Key XAB LAN field.

XAB address

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

fipcode

Place-

File processor error: File processor could not mark file for
deletion.

___________ ________
...__

during

unit

---------~

(Continued on next page)

A-10

Error Completion Codes

Table A-2 (continued)
Symbolic
Value

Numeric
Value

ER$MRN

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$NAM

175620/-1136.

Odd address in FAS NAM field on
file open, creation, or erase
operation.

ER$NEF

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$0RD

175500/-1216. XAB address

XABs not ordered properly.

ER$0RG

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)
- - - - - - - - - - - - - - - - - - - -.. ···-r---··--··"""""'""""-'""'"·"""'"""-"" __,,_,_ _ _ -----·~------

Symbolic
Value

Numeric
Value

ER$PLG

175440/-1248.

A Prologue block may be 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 failure.
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 position
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.

STV Field
Value

f i pc ode

De script ion

not

contain

File processor error:
•
In record processing:
Read
failure on file block.
•
In Block I/O, VBN = O, an
i 11 eg a 1 v a 1 ue •
(Continued on next page)

A-12

Error Completion Codes

Table A-2 (continued)
STV Field
Value

Description

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$RFA

175200/-1408.

Invalid RFA during RFA access.

ER$RFM

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$RRV

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$RSZ

174740/-1568.

•

fipcode

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
file.
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$STK

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$TRE

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

User
buffer
improperly
specified:
address is either
zero
or
buffer
is
not
word-aligned
(for Block I/O access only) •

ER$USZ

174500/-1728.

User buffer length equals zero.

ER$VER

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

174360/-1808. XAB address

ER$XTR

174340/-1824.

____ ____
_....

A-16

~--~~--~"-~

STV Field
Value

Description

Explicit or default file specification field contains wild card
character.
fipcode

f i pc ode

File processor error:
ilure on file block.

Write fa-

File processor error:
write locked.

Device is

File processor error:
while writing Prologue.

Error

FAB XAB field or XAB NXT
contains an odd address.

field

Explicit or default file specification
contains
extraneous
field.
_.___

_ _______ ___________________
__.__

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

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 BPT 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
RO=l75340
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:
.MCALL
.MCALL
;STEP 2:

ACCESS THE NECESSARY RMS MACROS
$INIT,ORG$,FAB$B,RAB$B,POOL$B,$CREATE,$0PEN,$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
;FILLED 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$B

;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)
;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:
RABI:

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

;INITIALIZE RMS.
;OPEN FILEl.DAT,
;SET UP FOR $COMPARE:

1$:

$COMPARE #0,STS,RO
BGT
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
$CREATE Rl
;NOW CREATE FILE2.DAT (Rl=FAB2):
$COMPARE #0,STS,Rl
;CHECK FOR FAILURE
BGT
2$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
;OTHERWISE EXECUTE ERROR ROUTINE.
MOV
#RABl,RO
;CONNECT THE RABS.
MOV
#RAB2,Rl
$CONNECT
RO
$COMPARE #0,STS,RO
BGT
3$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
$CONNECT Rl
$COMPARE #0,STS,Rl
BGT
4$
JSR
PC,ERROR
$GET
RO
;GET A RECORD FROM FILEl.DAT.
$COMPARE #ER$EOF,STS,RO ;WERE WE AT END-OF-FILE?
BEQ
DONE
;IF SO, CLEAN UP AND EXIT.
$COMPARE #0,STS,RO
;SOME OTHER ERROR?
BGT
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.
$PUT
Rl
;OUTPUT THE RECORD TO FILE2.DAT.
$COMPARE #0,STS,Rl
BGT
6$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
BR
4$
;LOOP UNTIL DONE.
MOV
#FABl,RO
;BACK TO THE FABS FOR $CLOSE.
MOV
#FAB2,Rl
$CLOSE RO
$COMPARE #0,STS,RO
BGT
1$
;BRANCH IF SUCCESSFUL
JSR
PC,ERROR
$CLOSE Rl
$COMPARE #0,STS,Rl
BGT
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
.SBTTL READ A DOCUMENTATION FILE AND COUNT THE WORDS
SO CAN USE RO, Rl, ETC •
• ENABL REG
.NLIST 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.
;

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

CRTRAB: RAB$B
R$FAB
CRTFAB
R$RAC
RB$SEQ
R$ROP
RB$EOF
RAB$E
. SBTTL BUFFERS AND MESSAGES
.PAGE
; BUFFERS
80.
• REPT
040
.BYTE
.ENDR
DOCRCL = . -DOCRCD
• EVEN
0
WDCNT: .WORD
0
CHRCNT: .WORD
REC LEN: .WORD
0

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
BEGIN INITIALIZATION BLOCK
; ADDRESS OF ASSOCIATED FAB
RECORD ACCESS MODE
END INITIALIZATION BLOCK

INPUT RECORD BUFFER
FILL WITH SPACES

DOCRCD:

XLTBUF:
PAGENO:
LINENO:

.WORD
.WORD
.WORD
.WORD

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. ,o ; POWERS OF 10
0
; PAGE COUNTER
0
; LINE COUNTER
;
;

;

; ARGUMENTS LISTS FOR RMS I/O OPERATIONS
;

DOCLST:
CRTLST:

DOC RAB
1
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

VECTOR TABLES

CHCODE:

B-6

.WORD
.WORD
• WORD
.WORD

. WORD
.WORD
.WORD

Sample RMS-11 Programs

CHCEND

= .-CHCODE

;

CHPRCS: . WORD
.WORD
.WORD
.WORD
.NLIST

FFEED
SPACE
HYFEN
NOTS PA

BIN

; 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
/
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
.SBTTL MACROS
.PAGE
BIN
. LIST
;
;
;

/FILE/
/DOC I
/STV I

MACROS

.MACRO

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)+
Rl
COUNT IT
O, (R2)
CHECK NEXT SOURCE WORD CHAR
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
;

.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)
R5,-(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)
CRTRAB,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

• ENDM
;

.MACRO

(SP)+,RS
(SP)+,R4

.ENDM
• SB TTL MAIN PROGRAM
• PAGE
; INTERNAL SPACE POOL

.EVEN
POOL$B
P$BDB
P$BUF

P$FAB
P$RAB
POOL$E

; 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) * ( 512 *MBC {1) ) * MBF ( 1) = 512
CRT-STREAM-SIZE =
BK S ( 1 ) * ( 5 1 2 *MB C ( 1 ) ) * MB F ( 1 ) = 5 1 2
2
FAB FOR EACH FILE
2
; TWO SEQUENTIAL FILES
END INITIALIZATION AREA

RMS FUNCTIONS NEEDED
;

ORG$

SEQ,<GET,PUT,FIN>

SEQ FILE GETS, PUT,

FINDS

;

!!!!!!!!!!!!!!!

RUN - TIME

!!!!!!!!!!!!!!!!!!!!!!

;

• EVEN
START:
B-8

$!NIT

Sample RMS-11 Programs

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

DOCRAB,R4
DOCLST,R5
PC, INPUT

DOCERR GETS RIGHT CODE
DOC FILE ARG LIST
; GET RECORD FROM DOC FILE

; RO = POINTER TO INPUT LINE
Rl = CHARACTERS/WORD COUNTER (TO HANDLE MULTIPLE SPACES)
R2 = WORDS/LINE COUNTER
R3 = VECTOR OFFSET INTO TABLE
R4 = DOCRAB
R5 = DOCLST
CLR
DOWORD: CLR
INC
CMP
BGT

Rl
R3
CHRCNT
CHRCNT,RECLEN
12$

INITIALIZE CHAR/WORD COUNTER
INITIALIZE VECTOR OFFSET
CNT CHAR BEFORE LOOK AT IT
; PAST END OF INPUT RCD YET?
IF SO, GO FINISH UP

4$: CMPB
BEQ
TST
CMP
BLT

CHCODE (R3), (RO)
8$
(R3) +
R3, CHCEND
4$
;

8$: JSR
INCB

PC ,@CHPRCS (R3)
(RO)+

CHECK ON NEXT CHAR IN LINE
PROCESSING IF EQUAL
INCREMENT VECTOR
NOT IN TABLE?
CHECK NEXT ONE

; DO RIGHT THING
MOVE TO NEXT CHARACTER
Sample RMS-11 Programs

B-9

;
;
;

12$: CMP
BEQ
INC
16$: CMP
BEQ
ADD
XLT210
XLT210
WRTOUT
MOVWD
18$: JMP

DOW ORD
O,Rl
; ANY CHARACTERS MOVED?
16$
NOT A REAL LAST WORD
R2
COUNT LAST WORD
O,R2
; ANY WORDS IN THIS LINE?
18$
IF NOT, DON'T DO ANYTHING
R2, WDCNT
; ADD THIS LINE TO TOTAL
R2,WDMSG
; PUT CURRENT LINE IN MSG
WDCNT, WDMSG+3 8.
PUT TOTAL CURRENT IN MSG
WDMSG,WDMSL
; OUTPUT IT
B LKS 3, WDMSG
; COVER UP LAST WORD COUNT
GETLIN
; 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
LIN ENO
PC

(SP)+,RS
(SP)+,R4

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

;

FFEED:

INC
PAGE NO
ADD ONE TO PAGE NUMBER
LIN ENO
RESET LINE NUMBER
CLR
TURN IT INTO DECIMAL
XLT210 PAGENO,FFMSG+S.
; ANNOUNCE FORM FEED
WRTOUT FFMSG,FFMSL
5.,R3
; FIND CTR TO TOP OF TEXT
MOV
; MOVE PAST A LINE
2$: $FIND
O,STS,R4
CHECK OUT STATUS FIELD
$COMPARE

B-10

Sample RMS-11 Programs

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

NOTS PA: INC
RTS

Rl
PC

; COUNT IT
; LOOK AT NEXT CHARACTER

HYFEN: CMP
BNE
MOV
JSR

CHRCNT,RECLEN
LAST CHARACTER IN LINE?
NOTS PA
TREAT IT LIKE ANY OTHER
R2, - (SP)
CIRCUMVENT INPUT
PC, INPUT
; BRING IT CONTINUATION LINE
(DON'T WORRY ABOUT DOUBLE-SPACING
; SINCE INPUT THROWS AWAY BLANK LINE)
(SP)+,R2
BRING WORD COUNT BACK
RO
ANTICIPATE AUTO INCREMENT
Rl
GET RID OF ANY RESIDUAL THAT
CAN COUNT WORD
PC
; PROCESS IT

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

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

; ANY CHARACTERS MOVED?
NONE WERE
CLEAR CHAR/WORD COUNTER
ONE MORE WORD
DO NEXT ONE

;

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
'O,R2
R2, (RS)+
- (R4)
8$

10$: RTS

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
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
BEQ
2$
$COMPARE ER$RTB,STS,R4
BEQ
4$
MOVWD
DOCID,ERRMSG
JMP
FILER I
2$: XLT210 WDCNT,WDMSG+38.
WRTOUT WDMSG+24.,18.
WRTOUT ENDMSG,ENDMSL
BR
32$
B-12

Sample RMS-11 Programs

RUN OUT OF RECORDS?
GO AROUND IF THAT'S IT
LINE TOO LONG?
GO AROUND IF THAT'S IT
IDENTIFY ERROR
HANDLE LIKE OTHER ERRORS
PUT TOTAL CURRENT IN MSG
OUTPUT IT
PUT IT ON SCREEN
GO TO END

4$: XLT210
WRTOUT
JMP
32$: EXIT$S

LINENO,LINMSG+5.; 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 KGT) 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
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

RECBUF
RECBUF
150.

;ADDR OF RCD PUT OR GOT
;SAME AS RBF

FAB$B
F$FAC
F$FNA
F$FNS
F$FOP
F$LCH
F$MRS
F$0RG
F$RAT
F$RFM
FAB$E

FB$PUT
TFNAM
TFNAMS
FB$CTG!FB$TMD
2
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

RAB$B
R$FAB
R$RAC
R$UBF
R$USZ
RAB$E

FABTI
RB$SEQ
BUFTI
80.

;FILE CTRL BLOCK ADDR
;SEQUENTIAL ACCESS
;USER BUFFER ADDR
;MAX SIZE = 80. BYTES

R$RBF
R$UBF
R$USZ
RAB$E
.EVEN
FABTI:

;

RABTI:

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
KEYTST: .BLKB
2
WITH RECORD PUT
DELTST: .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.

.BLKW
• ASCII

2
/MISC • DATA/ <CR><LF>
RECBUF

;TERMINAL FILE BUFFER

;

RECBUF:
REC KEY:
REC LEN

;

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

= . - ERR2

.ASCII /ERROR CONNECTING TTY FILE/ <CR><LF>

'
ERR3:
ERR3LN

= . - ERR3

.ASCII /ERROR CREATING RELATIVE FILE/ <CR><LF>

'
ERR4:
.ASCII /ERROR CONNECTING RELATIVE FILE/ <CR><LF>
ERR4LN = • - ERR4
;

MSGS:
TESTNO:

.ASCII /TEST /
.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:
ER14LN

.ASCII /ERROR - OVER 40. RECORDS WRITTEN ON TESTl/ <CR><LF>

= • - ERR14

;

ERR15:
.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
MSG5
MSG5LN
ERR6
ERR6LN
ERR7
ERR7LN
ERRS
ERR8LN
ERR9
ERR9LN
ERRlO
ERlOLN
ERRll
ERllLN
ERR12
ER12LN
ERR13
ER13LN
ERR14
ER14LN
ERR15
ER15LN
ERR16
ER16LN
REL,<CRE,FIN,GET,PUT,DEL>
SEQ, <CRE, PUT>

;

S'rART:
$!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
RTS
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 SieE
;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
;SET UP FOR CLOSE ERROR
MOV
40,PRAMTR
$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
(R2), RBF, R3
2(R2),RSZ,R3

Sample RMS-11 Programs

;CLEAR R2
;SET UP INDEX WITHIN TABLE
;POINTER TO ERROR MESSAGE
;POINTER TO ERROR TABLE
;STORE ADDRESS OF MESSAGE
;STORE SIZE OF MESSAGE

$PUT
RTS

R3,BOMB
PC

;TTY MSG - BOMB ON ERROR

JSR

PC, PRINT

;PRINT ERROR MESSAGE

;

ENDIT:
BOMB:
;BOMB

BPT
;

;----------------------------------------------

;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, CONECT

;INITIALIZE Rl
;CONNECT THE FILE

PUT IT:
INC
Rl
$PUT
R4
$COMPARE SU$SUC,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
MOV
20,PRAMTR
MOV
61,TESTNO
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

TlERR:

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

T 2INC:
INC
Rl
$GET
RABAR
$COMPARE S U$S UC, 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$EOF,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
RECTST:
ADD
CMP
BEQ

2,KEYTST
KEYTST,RECKEY
GETIT

;EVERY OTHER RECORD
;RIGHT RECORD?
;IF SO, LET'S GET ANOTHER

CMPB
BNE
ADD
CMP
BEQ

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

54,PRAMTR
ENDIT

;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

BHI
CMPB
BEQ
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
RABAR
$COMPARE SU$SUC,STS,R4 ;FIND SUCCESSFUL?
BEQ
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

RTS

;GO ON TO NEXT RECORD

;

RETURN:
PC

;

;CONVERSION TO ASCII TO PRINT OUT RCD NBR IN ERRMSG
;

CONVER:
MOVB
MOV
$STORE
MOV
MOV

l,ERR
;NOTE THAT ERROR OCCURRED
RABAR,R4
;SET UP RAB PNTR AFTER ERR
;RESET TO GOOD STATUS
l,STS,R4
;SET UP R3 FOR INDEXING
l,R3
;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 I •

;-------------------------------------------------------

;

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

S, 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

S,KEYNO
S,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:

COM PAR:

Sample RMS-11 Programs

B-23

RTS

;WE DID, CONTINUE

MOV
JSR
MOV
CALL
RTS

70,PRAMTR
PC, CONVER
HOLDIT,TSTSNO
PRINT
PC

;SET IND&X 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

.TITLE

$CDTTA - CONVERT DATE AND TIME TO ASCII

.IDENT

"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.
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 USE 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
RS, $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
.NLIST 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-1
= 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
;+

*** - $CDTTA 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 = ADDRESS TO STORE ASCII STRING
Rl = ADDRESS OF 64 BIT DATE/TIME
R2 = 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
OUTPUTS:
RO UPDATEb 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.

;$CDTTA: :
$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.
REAL DATE.

CONVERT THIS TO A

;

BIT
BNE
MOV
MOV

#1,16. (SP)
LO
(SP) ,R3
2(SP),R2

ADD
ADC
ADD

#DS15L,R3
R2
#DS15H,R2

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)

#l,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

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:
;
CMP
BLOS
ADD

IF THIS IS NOT A LEAP YEAR,
BIAS THE DAY UP ONE IF IT IS
PAST FEBRUARY.

R2,#31.+28.
LS
R4,R2

LS:
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
#$MONTB,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-S

MOV
JSR
MOVB
MOV

#0,R2
PC, $CBDMG
#4 0, (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
MOV
MOV
CMP
MOV
MOV
JSR
MOV
MOV
JSR
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

ADD
MOV
MOV
RTS

#16.,SP
(SP)+,R2
(SP)+,Rl
PC

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:
RETURN FINAL STRING POINTER

L6:
;

FINAL STACK CLEANUP

*** - C2D

CONVERT BINARY TO 2 DECIMAL DIGITS

THIS ROUTINE IS USED TO OUTPUT THE COMPONENTS OF THE TIME
;

INPUTS:
;

;

RO = BINARY VALUE

C-6

Date Conversion Routine

OUTPUTS:
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
AND STORE

;

*** - $DIVD

DOUBLE PRECISION DIVIDE

THIS ROUTINE PERFORMS AN UNSIGNED DIVIDE WITH 32 BIT DIVISOR,
DIVIDEND, QUOTIENT, AND REMAINDER.
DIVIDE BY ZERO IS NOT CHECKED.
ANDREW C.

GOLDSTEIN 4 MAR 76 11:41

BASED ON THE ALGORITHM IN RT-ll'S LIBRARY ROUTINE JDIV
INPUTS:
RO
Rl
R2
R3

= HIGH ORDER DIVISOR
= LOW ORDER DIVISOR
= HIGH ORDER DIVIDEND
= LOW ORDER DIVIDEND

OUTPUTS:
RO
Rl
R2
R3

= HIGH ORDER REMAINDER
= LOW ORDER REMAINDER
= HIGH ORDER QUOTIENT
= LOW ORDER QUOTIENT

;

R4,RS PRESERVED
;-

$DIVD: :

10$:

MOV
MOV
MOV
CLR
CLR
ROL
ROL
CMP
BHI
BNE
CMP

R4,-(SP)
RS,-(SP)
# 3 3. , - (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
TST
MOV
MOV
MOV
MOV
RTS

20$:

30$:

*** - $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 C.

GOLDSTEIN 17-NOV-76 10:47

;+
INPUTS:
RO
Rl
R2
R3

;

= ADDRESS
= ADDRESS
= ADDRESS
= ADDRESS

OF
OF
OF
OF

DIVISOR
DIVIDEND
QUOTIENT
REMAINDER

OUTPUTS:
QUOTIENT AND REMAINDER RETURNED IN SPECIFIED ADDRESSES

;$DIVQ: :

10 $:

C-8

CALL
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CLR
CLR
CLR
CLR
MOV
ROL
ROL
ROL
ROL
MOV
ADD
MOV

$SA VAL
#6S.,-(SP)
R2,RS
(R 1) +, (RS)+
(R 1) +, (RS)+
(R 1) +, (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
BHI
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$:

20$:

MOV
CLR
ROR
ROR
BCC
ADD
DEC
BGT
CMP
RETURN
.END

- (R 1) , - (R 5)
20$
-(Rl)1-(R5)
20$
- (R 1) , - (R 5)
20$
- (R 1) , - (R 5)
30$
RO,Rl
R3, R4
(Rl)+, (R4)+
(R4) +
(R4) +
(R4)
-(R4),-(R4)
(Rl)+, (R4)+
(R4)
2(R4)
(Rl)+, (R4)+
(R4)
(Rl)+, (R4)+
R2,R5
(R5) +
(R5) +
(R5) +
(RS)+

(s p)

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

YES:
BRANCH, NO SUBTRACT, C IS CLEAR
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 FAS 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
maximum, 3-32
minimum, 3-32
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
BASIC+, 5-26
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

BKT.
(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-4 8, 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)
Boundaries, cross block, 3-45
BPA.
(See Fi 1 e 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
minimum, 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
Buffer pool.
(See central buffer pool)
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
Buff e r space •
( See cent r a 1 buff e r po o 1 )
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
minimum, 3-50
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-2 2
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
CT X.
( See Fi 1 e Access B1 o ck}
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- 21 t , 5- 2 3
COD, 5-2lt, 5-24
NXT, 5-2lt, 5-25
RDT, 5-2lt, 5-26
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-2 2
notation, 3-21
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
DE Q.
(See Fi 1 e Access B1 o ck)
DEV.
(See File Access Block)
Device characteristics.
(See File Access Block DEV field)
Device cluster number, 5-7

Index-6

Device 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
Di rec to r y entry ( s) , remove RM S-11 f il e ' 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
$DISPLAY.
(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
ER$cod, A-1
ER$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-13, 1-17
Exact match, 4-13
Existing file
available for processing, 8-12
supersede, 3-29
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
cautions, 1-14
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-1 3
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 •
( See 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
iO 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-1 t, 7-6
$SET, 7-1 t, 7-7
$STORE, 7-lt, 7-9
$STORE and KEY XAB SIZ/POS field, 7-9
$TESTBITS, 7-lt, 7-11
Field
compare 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 user 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
BIDv l-9t, 3-5
BKS, l-9t, 3-2t, 3-6
BKS vs. XAB BKZ, 5-9
BLN, l-9t, 3-2t, 3-8
BLS, l-9t, 3-2t, 3-9
BPA, l-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, l-9t, 3-2t, 3-19
DNA, l-9t, 1-16, 3-2t, 3-20
DNS, 1-16, 3-2t, 3-22
FAC, l-9t, 3-2t, 3-23
field offset macros, 1-3, 3-1
FNA, l-9t, 1-16, 3-2t, 3-25
FNS, l-9t, 1-16, 3-2t, 3-27
FOP, l-9t, 3-2t, 3-28
FSZ, l-9t, 3-2t, 3-32
!FI, l-9t, 3-2t, 3-34
initialization, 1-9
initialization macros, 1-3, 3-1
KSZ, 3-2t
LCH, l-9t, 3-2t, 3-35
MRN, l-9t, 3-2t, 3-37
MRS, l-9t, 3-2t, 3-39
NAM, l-9t, 3-2t, 3-41
ORG, l-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-2 5
conform to system standards, 3-26
notation, 3-25
parsing under RSTS/E, 3-26
size, 3-27
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, 8-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-29
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
$FIND.
(See macro)
First data bucket, 5-38
Fixed control area, 3-32
maximum, 3-32
minimum, 3-32
Fixed-length record format, 3-46
$FLUSH.
(See macro)
FNA.
(See File Access Block)
FNS.
(See File Access Block)
FOP.
(See File Access Block)
Format
fixed-length record, 3-46
record, 3-46
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
s ym bo 1 s , 1-1 0
$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 Fi le Access Block)

Index-12

IFI.
(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
IRAB.
(See Internal Record Access Block)
ISI.
(See Record Access Block)
KBF.
(See Record Access Block)
Key
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
Key field, 5-28
Key information, 1-13
Key length, 5-28
Key name, 5-46
length, 5-46
Key of reference, 4-12, 5-58
maximum, 4-12
minimum, 4-12
Key position, 5-28
Key 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
Key size, 5-60
maximum, 5-60
nonstring, 4-14
total, 5-63
Index-13

Key type, 5-28
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
B LN , 5- 2 8 t , 5- 2 9
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-28t, 5-38
F LG , 5- 2 8 t , 5- 3 9
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-17, 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
maximum, 3-3 5
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, l-8t, 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-10
F$FNS, 3-27
F$FOP, 3-30
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-2 8
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$S UP, 3-2 9
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
$!NIT, 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-1 7
$NXTVOL, 1-lOt, 8-25
$OFF, 1-18, 7-6
$OPEN, l-8t, 8-12
ORG$, 1-3
P$BDB, 1-7t, 2-lt, 2-2
P$BUF, l-7t, 2-1 t, 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, l-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-3 2
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-19, 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
1

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

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 Rel~tive 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, 1-3
minimizing number of directives, 1-3
minimum set of arguments, 1-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 q~antity, 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$ f nm •
(See mac r o)
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-17
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-22
Name string, expanded f1le
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-2 7
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
m1n1mum 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 al so private buffer. pool)
Processing
bypass RMS-11 record, 9-1
continue on the next tape volume, 8-25
environment, 1-2
~xisting 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
Frotection code, 5-64
programmer number, 5-68
project number, 5-69
values, 5-70
Protection information, 1-13
Index-22

Protection XAB
B LN , 5- 6 4 t , 5- 6 5
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, 1-18, 5-15
minimum allocation, 3-4
m1n1mum default extension, 3-17, 5-15
R $ f nm •
( Se e mac r o )
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 Fi 1 e 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, l-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, l-12t, 4-2t, 4-22
RHB, l-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-12t, 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
minim um , 3- 3 7
Record number, relative, 4-4, 4-10, 4-13
Record operation, 1-2, 1-19
calling sequence, 1-·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-23
relative record number input, 4-4
RMS-11 verifies RAB before, 4-3, 4-5
$TRUNCATE, 3-23
$UPDATE, 3-24
Record Operation Macros, 1-22, 8-15
$CONNECT, l-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, l-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, l-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 duplicate 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 terminatori 8-24
$N XT VOL , 1-2 3 t , 8-1 5 t , 8- 2 5
$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
Record 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, 8-19, 8-23
and disk files, 8-20, 8-24
Record
Current, 1-22
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
minim um , 4-1 2
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
Release Core Block.
(See GSA routine)
Release of space, RMS-11, 2-10
Replace an existing record in an RMS-11 file, 8-31

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 Re co rd Access Block)
Routine, fatal erior 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
$R QC 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

$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-bit, 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
record, 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, 5-7lt, 5-72
COD, 5-71 t, 5-73
NOA, 5-7lt, 5-74
NOK, 5-7lt, 5-75
NXT, 5-71 t, 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-29
Terminal, 3-45
Terminate a Record Access Stream, 8-18
$TESTBITS.
(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 ~inary 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 Re co rd 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-14
and Locate Mode, 4-32
maximum, 4-34
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
Var iabl e-wi th-fixed-control.
(See VFC)
Version number, prologue, 5-77
and key data types, 5-77
VFC
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

READER'S COMMENTS

RMS-11 MACR0-11
Reference Manual
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

Name

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify)------~--------------------

Date---------------------~~------

Organization __________________________________________
Street __________________________________________________________

C i t Y - - - - - - - - - - - - - - - - - - - - - - - - - State - - - - - - - Zip C o d e - - - - - - - or
Country

-- -

-Do Not Tear - J.'old Here and Tape -

- - - - -

-- -

~nmnomn

No Postage
Necessary
if Mailed in ti
United State

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

- -

Do Not Tear - Fold Here and Tape -